|
|
# 项目知识库
|
|
|
|
|
|
**生成时间:** 2026-04-25
|
|
|
**项目:** CNC机床数据采集系统
|
|
|
|
|
|
---
|
|
|
|
|
|
## ⚠️ 铁律（每次会话必须遵守）
|
|
|
|
|
|
> 以下规则优先级最高，无论执行什么任务都必须遵守。
|
|
|
|
|
|
### 1. 全程中文
|
|
|
|
|
|
- **思考过程使用中文**：所有AI助手的推理、分析、思考过程必须使用中文输出
|
|
|
- **控制台输出中文**：所有控制台输出、日志、提示信息使用中文，不得出现乱码
|
|
|
- **所有文档使用中文**：项目内所有文档、注释、界面文案使用中文
|
|
|
- **代码注释中文**：所有代码注释使用中文
|
|
|
|
|
|
### 2. Git提交（每次代码改动必须执行）
|
|
|
|
|
|
- **每次代码改动，编译/验证成功后，必须提交到Git并Push到远程仓库**
|
|
|
- 远程仓库: `https://git.cjy.net.cn/jcl/haoliang-net.git`（分支: `main`）
|
|
|
- 账号: `821644@qq.com`
|
|
|
- 提交信息必须使用中文，清楚描述改动内容
|
|
|
- 提交流程：
|
|
|
```bash
|
|
|
git add <变更文件>
|
|
|
git commit -m "改动内容描述"
|
|
|
git push
|
|
|
```
|
|
|
- **禁止跳过此流程**：任何代码变更（修复、新增、重构）完成后，都必须执行 commit + push
|
|
|
|
|
|
### 3. 文件写入编码规范
|
|
|
|
|
|
- 禁止使用PowerShell `Out-File -Encoding utf8` 写入文件（PS5.1会产生UTF-8 with BOM + CRLF）
|
|
|
- 使用Write/Edit工具直接写入（无BOM、LF换行）
|
|
|
- 如必须用PowerShell写入，需用 `[System.IO.File]::WriteAllText($path, $content, [System.Text.UTF8Encoding]::new($false))` 避免BOM
|
|
|
- 已有BOM文件修复：`node -e "const fs=require('fs');let b=fs.readFileSync('文件路径');if(b[0]===0xEF&&b[1]===0xBB&&b[2]===0xBF)b=b.slice(3);let t=b.toString('utf8').replace(/\r\n/g,'\n');fs.writeFileSync('文件路径',t,'utf8')"`
|
|
|
|
|
|
### 4. 修改请求预处理协议
|
|
|
|
|
|
### 5. 测试与验证（每次代码改动必须执行）
|
|
|
|
|
|
- 详见 `docs/06-测试规范.md`
|
|
|
- **每次代码改动后，必须执行完整验证流程，禁止跳过**：
|
|
|
1. **L1编译**：`dotnet build` 0错误 + `npm run build` 0错误
|
|
|
2. **L2 API验证**：用PowerShell调用改动过的API端点，确认返回值字段和内容正确
|
|
|
3. **L3 浏览器验证**：用Playwright打开页面，实际操作交互控件（展开下拉框→选择→点查询→检查数据）
|
|
|
4. **L4 发布**：回收AppPool后重新验证
|
|
|
- **验证铁律**：
|
|
|
- 编译通过 ≠ 功能正确，必须验证数据内容
|
|
|
- 断言必须检查数据值，禁止只检查"元素存在"
|
|
|
- 下拉框必须展开确认有选项、表格必须检查数据列有值、卡片必须检查数值非空
|
|
|
- 改完即验证，不累积到"全部改完"
|
|
|
- **自动化测试**：`cd frontend && npx playwright test --project=chromium`（运行E2E验证套件）
|
|
|
|
|
|
详见 `docs/05-修改请求预处理协议.md`（影响面分类 → 规范路由 → 输出修改计划摘要 → 等待确认）
|
|
|
|
|
|
---
|
|
|
|
|
|
## 项目上下文
|
|
|
|
|
|
### 概述
|
|
|
|
|
|
多品牌CNC机床统一化数据采集系统。技术栈：Vue3前端 + ASP.NET Web API 2后端 + Windows Service采集服务 + MariaDB数据库。本地IIS部署，局域网场景。
|
|
|
|
|
|
### 项目结构
|
|
|
|
|
|
```
|
|
|
.
|
|
|
├── CncDataSystem.sln ← VS2017 解决方案（4层+3测试项目+前端文件夹）
|
|
|
├── src/ ← 后端源码
|
|
|
│ ├── CncModels/ ← 数据模型层（Entity + Dto + Enum + Constants）
|
|
|
│ ├── CncRepository/ ← 数据访问层（Dapper + MariaDB双库）
|
|
|
│ ├── CncService/ ← 业务逻辑层（接口 + 实现）
|
|
|
│ └── CncWebApi/ ← Web API 主项目（Controllers + Filters + Infrastructure）
|
|
|
├── tests/ ← 测试项目（xUnit + Moq，100%方法覆盖 ≥95%分支覆盖）
|
|
|
│ ├── CncModels.Tests/
|
|
|
│ ├── CncRepository.Tests/
|
|
|
│ ├── CncService.Tests/
|
|
|
│ └── CncWebApi.Tests/
|
|
|
├── database/ ← 数据库脚本（幂等DDL+预置数据）
|
|
|
├── docs/ ← 全部设计文档
|
|
|
│ ├── 00-需求与设计文档.md # 核心需求、架构决策、技术选型
|
|
|
│ ├── 01-数据库设计.md # 双库设计(业务库+日志库)，20张表DDL（已定稿）
|
|
|
│ ├── 02-功能清单/ # 按模块拆分的功能清单
|
|
|
│ │ ├── 02-文件夹创建规范.md # ⚠️ 文档结构规范，新增模块必读
|
|
|
│ │ ├── 02-前端全局规范.md # 前端全局规范+CRUD必填项+模块进度+工程开发规范
|
|
|
│ │ ├── 03-界面变更执行规范.md # ⚠️ AI助手执行界面变更时必读
|
|
|
│ │ ├── 大屏/ # 大屏看板模块
|
|
|
│ │ └── 管理后台/ # 12个子模块（登录/仪表盘/设备/品牌/采集地址/员工/产量/告警/系统/车间/操作日志/大屏配置）
|
|
|
│ ├── 03-API接口设计.md # 13模块83端点（URL+Method两列对照）
|
|
|
│ └── 04-后端开发规范.md # ⚠️ 后端必读：技术栈/项目结构/命名/注释/测试/分层/依赖注入规范
|
|
|
├── frontend/ ← 前端工程（Vue3+Vite+TypeScript+Element Plus）
|
|
|
│ ├── mock/ # Mock数据定义（按模块拆分）
|
|
|
│ ├── src/ # 源码（路由/组件/样式/类型）
|
|
|
│ └── vite.config.ts # Vite配置（mock插件+proxy）
|
|
|
└── 发那科系统采集示例.txt # FANUC品牌采集JSON样例数据
|
|
|
```
|
|
|
|
|
|
### 查找指南
|
|
|
|
|
|
| 需求 | 位置 | 备注 |
|
|
|
|------|------|------|
|
|
|
| 了解项目背景/架构决策 | `docs/00-需求与设计文档.md` | 核心文档，所有已确认决策在此 |
|
|
|
| 查看数据库表结构 | `docs/01-数据库设计.md` | 668行，含完整DDL+字段说明 |
|
|
|
| 前端页面交互设计 | `docs/02-前端全局规范.md` | 全局组件规范+CRUD必填项+模块进度+工程开发规范 |
|
|
|
| 前端工程开发规范 | `docs/02-前端全局规范.md` → 前端工程开发规范章节 | 技术栈/Mock方案/目录结构/CSS规范 |
|
|
|
| 新增功能模块文档 | `docs/02-功能清单/02-文件夹创建规范.md` | 目录结构/命名/内容模板规范 |
|
|
|
| AI助手执行界面变更 | `docs/02-功能清单/03-界面变更执行规范.md` | ⚠️ 必读：最小必读文件+变更清单+联动同步规则 |
|
|
|
| 后端开发规范 | `docs/04-后端开发规范.md` | ⚠️ 后端必读：技术栈/项目结构/命名/注释/测试/分层/依赖注入 |
|
|
|
| 修改请求预处理协议 | `docs/05-修改请求预处理协议.md` | AI助手收到修改请求时的分析流程和示例 |
|
|
|
| API接口设计 | `docs/03-API接口设计.md` | 13模块83端点（URL+Method两列对照，不含数据结构） |
|
|
|
| 品牌采集数据格式 | `发那科系统采集示例.txt` | FANUC品牌JSON结构示例 |
|
|
|
| 管理后台某模块设计 | `docs/02-功能清单/管理后台/{编号}-{模块名}/` | 每模块含索引+规范+页面文件 |
|
|
|
| 大屏看板设计 | `docs/02-功能清单/大屏/` | 索引+规范+页面 |
|
|
|
|
|
|
### 文档规范
|
|
|
|
|
|
**文件命名规则（必须遵循）：**
|
|
|
|
|
|
- 索引文件：`00-{名称}-索引.md`
|
|
|
- 规范文件：`01-{名称}-规范.md`
|
|
|
- 页面文件：`{模块号}-{页面号}-{页面名}.md`（如 `03-01-设备列表页面.md`）
|
|
|
- 模块编号：两位数 01-99
|
|
|
|
|
|
**三种文件分工：**
|
|
|
|
|
|
| 文件类型 | 内容重点 |
|
|
|
|---------|---------|
|
|
|
| 索引文件 | 功能逻辑、交互关系、路由跳转、状态机 |
|
|
|
| 规范文件 | 技术规范（组件、校验、布局、安全） |
|
|
|
| 页面文件 | 技术实现（界面布局、字段定义、Mock数据） |
|
|
|
|
|
|
**页面文件20项模板：** 结构定义(1-6) → 交互行为(7-12,14-15) → 技术实现(13,16-20)，详见 `docs/02-功能清单/02-文件夹创建规范.md` 第五节
|
|
|
|
|
|
### 核心业务规则
|
|
|
|
|
|
- **采集模式**：HTTP拉取JSON，非直连机床；地址间并行、地址内串行
|
|
|
- **零件计数**：NC程序名切换时结账上一段，新程序从0开始；同程序名多次出现分段记录
|
|
|
- **双库分离**：业务库 `cnc_business` + 日志库 `cnc_log`；原始JSON存日志库，解析后存业务库
|
|
|
- **时间标准**：以服务器时间为准
|
|
|
- **品牌映射**：管理后台可视化配置，修改不回溯历史数据
|
|
|
|
|
|
### 前端全局规范摘要
|
|
|
|
|
|
- 组件库：Element Plus
|
|
|
- API响应格式：`{ code: 0, message: "success", data: ... }`
|
|
|
- 分页默认：page-sizes=[20,50,100]
|
|
|
- 写操作防重复：loading+disabled+requestLock+axios 500ms去重
|
|
|
- API超时：30秒
|
|
|
- 删除确认：`确定删除【{name}】？此操作不可恢复。`
|
|
|
- Layout：顶部栏(系统名+管理员下拉) + 侧边栏(200px可折叠+10个菜单项) + 内容区
|
|
|
- 路由守卫：有Token访问/login重定向/dashboard，无Token访问管理后台重定向/login
|
|
|
|
|
|
### 项目状态
|
|
|
|
|
|
**已完成：**
|
|
|
|
|
|
- ✅ 前端管理后台设计（见 `02-前端全局规范.md` + `02-功能清单/管理后台/`）
|
|
|
- ✅ 大屏看板设计（见 `02-功能清单/大屏/`）
|
|
|
- ✅ 数据库设计定稿（见 `01-数据库设计.md`，20张表已落地MariaDB）
|
|
|
- ✅ API接口设计（见 `03-API接口设计.md`，13模块83端点）
|
|
|
- ✅ 后端开发规范（见 `04-后端开发规范.md`）
|
|
|
- ✅ 前端界面设计全部完成(2026-04-26)，13个模块16个页面均已设计
|
|
|
|
|
|
**待设计：**
|
|
|
|
|
|
- 采集服务核心逻辑设计（后置，后端API完成后启动）
|
|
|
|
|
|
**备注：**
|
|
|
|
|
|
- 品牌预置：FANUC已预置，其他品牌手动添加
|