# 项目知识库

**生成时间:** 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中文编码修复（每次会话必须执行）**：PowerShell 5.1默认OutputEncoding为GB2312，中文路径/文件名输出会乱码。在执行任何涉及中文路径的PowerShell命令前，必须先设置编码：
  ```powershell
  [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
  [Console]::InputEncoding = [System.Text.Encoding]::UTF8
  $OutputEncoding = [System.Text.Encoding]::UTF8
  ```
- **文件写入编码规范**：
  - 禁止使用PowerShell `Out-File -Encoding utf8` 写入文件（会产生UTF-8 with BOM + CRLF）
  - 使用Node.js `fs.writeFileSync(path, content, 'utf8')` 写入文件（无BOM、LF换行）
  - 或使用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. 修改请求预处理协议

AI助手收到任何修改/新增/删除请求时，除非用户明确指示"直接执行"（或等效表述），必须先完成影响面分析并向用户报告，等待确认后再开始实施。

#### 第一步：影响面分类

识别本次修改涉及的领域（可多选）：

| 标记 | 领域 | 说明 |
|------|------|------|
| F | 前端 | 涉及Vue组件、样式、路由、Mock数据、页面交互 |
| B | 后端 | 涉及Controller/Service/Repository/Model、C#代码 |
| D | 数据库 | 涉及表结构变更、新增表、字段增删改 |
| A | API接口 | 涉及端点新增/修改、请求响应格式变更 |
| R | 需求文档 | 涉及需求变更、架构决策调整 |

#### 第二步：规范路由

根据分类结果，列出本次修改必须遵循的规范文件：

| 涉及领域 | 必读规范 | 关键检查项 |
|---------|---------|-----------|
| F 前端 | `03-界面变更执行规范.md` + `02-前端全局规范.md` | 联动同步规则、CRUD必填项、Mock/API切换Checklist、组件规范 |
| B 后端 | `04-后端开发规范.md` | 分层职责、命名后缀、测试覆盖(100%方法/95%分支)、Mock数据结构对齐、端点对照表、DTO断言完整性 |
| D 数据库 | `01-数据库设计.md` | 双库归属判断、DDL幂等、是否需要数据迁移脚本 |
| A API接口 | `03-API接口设计.md` | 双列URL同步（Mock列+正式列）、页面§9数据结构同步 |
| R 需求文档 | `00-需求与设计文档.md` | 检查是否与已确认架构决策冲突 |

#### 第三步：输出修改计划摘要

向用户展示以下信息，等待确认：

```
修改分类：[标记组合]
必读规范：[列出具体文件名]
涉及文件：[逐文件列出变更内容]
联动影响：[需同步更新的文件清单，按03-界面变更执行规范.md联动规则逐条检查]
预估步骤：[1-N步]
```

#### 豁免条件

以下情况可跳过预处理直接执行：

1. 用户明确说"直接执行"/"不用分析"/"直接改"等等效表述
2. 修复代码中的typo/注释修改等纯文本变更（不涉及逻辑）
3. 用户已经在上文给出了完整的修改方案（等同于已确认）

---

## 项目上下文

### 概述

多品牌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` | ⚠️ 后端必读：技术栈/项目结构/命名/注释/测试/分层/依赖注入 |
| 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已预置，其他品牌手动添加

---

## 附录：修改预处理协议示例

### 示例1：纯前端修改

> 用户："告警列表页的告警等级用不同颜色标签展示，紧急红色、重要橙色、一般黄色、提示蓝色"

AI回复：

> 修改分类：F（前端）
>
> 必读规范：
> - `03-界面变更执行规范.md` → 第二节B"修改页面"
> - `02-前端全局规范.md` → 组件规范（el-tag size=small, 按状态配color）
>
> 涉及文件：
> - `docs/02-功能清单/管理后台/08-告警中心/08-01-告警中心页面.md` → 列表字段区，告警等级列增加颜色定义
> - `frontend/src/views/alert/AlertPage.vue` → 实际组件代码
> - `frontend/mock/alert.ts` → Mock数据中告警等级字段确保覆盖4种等级
>
> 联动影响（按`03-界面变更执行规范.md`第三节）：
> - 规则1：不涉及路由/跳转变更 → 无需更新索引文件
> - 规则2：不涉及新增数据字段 → 无需更新数据需求章节
> - 规则3：不涉及新增/删除页面 → 无需更新进度表
> - 无后端/API/数据库变更
>
> 预估步骤：
> 1. 读取 `08-01-告警中心页面.md` 确认当前告警等级列定义
> 2. 更新页面文件中告警等级列的展示方式（增加颜色映射表）
> 3. 更新 `AlertPage.vue` 中 el-tag 的 type/color 绑定
> 4. 验证 Mock 数据覆盖4种等级
>
> 是否按此方案执行？

### 示例2：前端+API+后端联动

> 用户："设备列表加一个按品牌筛选的条件"

AI回复：

> 修改分类：F + A + B
>
> | 标记 | 领域 | 变更内容 |
> |------|------|---------|
> | F | 前端 | 设备列表页查询条件区新增「品牌」下拉（filterable, clearable） |
> | A | API | GET `/api/admin/machine` 增加 `brandId` 可选查询参数 |
> | B | 后端 | MachineQuery DTO 增加 BrandId 字段；Repository SQL 增加 WHERE 条件 |
>
> 必读规范：
> - `03-界面变更执行规范.md` → B"修改页面" + 规则6"接口变更同步"
> - `02-前端全局规范.md` → 组件规范（el-select: filterable=true, clearable=true）
> - `04-后端开发规范.md` → §5.2.1 Mock数据结构对齐、§3.4 控制器路由规范
> - `03-API接口设计.md` → §3.3 设备管理模块，双列URL同步
>
> 涉及文件（共8处）：
>
> | 文件 | 变更 |
> |------|------|
> | `docs/02-功能清单/管理后台/03-设备管理/03-01-设备列表页面.md` | §3 查询条件表增加品牌行 |
> | `docs/03-API接口设计.md` | §3.3 设备列表端点，参数列增加 brandId |
> | `frontend/mock/machine.ts` | Mock 列表接口支持 brandId 过滤 |
> | `frontend/src/views/machine/MachineListPage.vue` | 查询区增加品牌下拉 |
> | `src/CncModels/Dto/MachineQuery.cs` | 新增 `public int? BrandId { get; set; }` |
> | `src/CncRepository/Impl/MachineRepository.cs` | GetList SQL 增加 `AND brand_id = @BrandId` 条件 |
> | `src/CncService/Impl/MachineService.cs` | 无变更（透传参数） |
> | `tests/CncService.Tests/MachineServiceTests.cs` | 新增 `GetList_FilterByBrandId` 测试用例 |
>
> 联动影响（按规则6接口变更同步）：
> - ✅ 端点清单（`03-API接口设计.md`）：Mock列 + 正式列 同时更新参数说明
> - ✅ 页面§9（`03-01-设备列表页面.md`）：接口请求参数增加 brandId
> - ✅ Mock文件（`frontend/mock/machine.ts`）：支持按 brandId 过滤返回数据
> - 无数据库变更（`cnc_machine` 表已有 `brand_id` 字段）
> - 无需求文档变更
>
> 预估步骤：
> 1. 读取 `03-01-设备列表页面.md` 确认当前查询条件和§9接口定义
> 2. 更新页面文件 §3 查询条件 + §9 接口参数
> 3. 更新 `03-API接口设计.md` 端点参数
> 4. 更新 Mock 文件支持过滤
> 5. 后端：DTO + Repository SQL + 测试用例
> 6. 前端组件增加品牌下拉
>
> 是否按此方案执行？

### 示例3：全栈变更（数据库+后端+API+前端）

> 用户："设备表增加一个「最后采集时间」字段，前端详情页和列表页都要显示"

AI回复：

> 修改分类：D + B + A + F
>
> | 标记 | 领域 | 变更内容 |
> |------|------|---------|
> | D | 数据库 | `cnc_machine` 表新增 `last_collect_time DATETIME` 字段 |
> | B | 后端 | Entity 增加属性、Repository SELECT 增加字段、详情/列表 DTO 增加字段 |
> | A | API | 设备列表、设备详情接口响应增加 `lastCollectTime` 字段 |
> | F | 前端 | 列表页增加列、详情页增加展示行 |
>
> 必读规范：
> - `01-数据库设计.md` → §2.4 cnc_machine 表结构，确认字段命名规范
> - `04-后端开发规范.md` → §3.3 Entity映射、§5.2.1 Mock对齐、§6 测试规范（新增字段需同步测试断言）
> - `03-界面变更执行规范.md` → B"修改页面" + 规则6 接口变更同步
> - `02-前端全局规范.md` → 列表字段规范
>
> 涉及文件（共12+处）：
>
> | 层 | 文件 | 变更 |
> |----|------|------|
> | D | `database/` 下新建增量迁移脚本 | ALTER TABLE ADD COLUMN，幂等 |
> | D | `docs/01-数据库设计.md` | §2.4 表DDL增加字段说明 |
> | B | `src/CncModels/Entity/Machine.cs` | 新增 `public DateTime? LastCollectTime { get; set; }` |
> | B | `src/CncModels/Dto/MachineListItem.cs` | 新增 `public DateTime? LastCollectTime { get; set; }` |
> | B | `src/CncModels/Dto/MachineDetail.cs` | 新增 `public DateTime? LastCollectTime { get; set; }` |
> | B | `src/CncRepository/Impl/MachineRepository.cs` | SELECT 列增加 `last_collect_time` |
> | B | `tests/CncRepository.Tests/MachineRepositoryTests.cs` | 断言增加 LastCollectTime 字段 |
> | B | `tests/CncService.Tests/MachineServiceTests.cs` | DTO 断言完整性（§6.12，每个字段必须断言） |
> | A | `docs/03-API接口设计.md` | 设备列表/详情端点响应字段更新 |
> | F | `docs/02-功能清单/管理后台/03-设备管理/03-01-设备列表页面.md` | §4 列表字段增加「最后采集时间」列 |
> | F | `docs/02-功能清单/管理后台/03-设备管理/03-02-设备详情页面.md` | §3 数据区块增加展示行 |
> | F | `frontend/mock/machine.ts` | Mock 数据增加 lastCollectTime |
> | F | `frontend/src/views/machine/MachineListPage.vue` | el-table 增加列 |
> | F | `frontend/src/views/machine/MachineDetailPage.vue` | 详情展示增加 |
>
> 联动影响：
> - 规则2：页面新增展示字段 → 更新§9数据需求章节
> - 规则6：接口响应变更 → 端点清单 + 页面§9 + Mock 三处同步
> - `04-后端开发规范.md` §6.12 DTO断言完整性：列表DTO和详情DTO新增字段，对应测试必须增加断言
> - 数据库变更需幂等脚本（`database/` 目录规范）
>
> 预估步骤：
> 1. 数据库迁移脚本 + 更新设计文档
> 2. 后端 Entity/DTO/Repository/Service + 测试
> 3. API文档更新 + Mock更新
> 4. 前端页面文件更新 + 组件更新
>
> 是否按此方案执行？

### 示例4：纯后端Bug修复

> 用户："MachineService.GetList 分页 page=0 时报错，应该自动修正为1"

AI回复：

> 修改分类：B（后端）
>
> 必读规范：
> - `04-后端开发规范.md` → §5 编码规范、§6 测试规范
>
> 涉及文件：
> - `src/CncService/Impl/MachineService.cs` → GetList 方法增加 page 参数修正逻辑
> - `tests/CncService.Tests/MachineServiceTests.cs` → 新增/补充分页边界测试
>
> 关键约束（从§6必测场景清单提取）：
> - §G 分页参数场景：`page=0或负数 → 自动修正为page=1`（已定义为必须覆盖的场景）
> - 需要补充测试：`GetList_PageIsZero_CorrectsToPage1`、`GetList_PageIsNegative_CorrectsToPage1`
>
> Bugfix原则（最小修复）：
> - 只修分页参数修正逻辑，不重构 GetList 方法
> - 不涉及前端、数据库、API文档变更
>
> 预估步骤：
> 1. 先写失败测试 `GetList_PageIsZero_CorrectsToPage1`
> 2. 修改 Service 逻辑
> 3. 确认测试通过
>
> 是否按此方案执行？

### 示例5：豁免直达

> 用户："设备列表的分页 pageSize 上限从100改成200，直接执行"

AI跳过预处理，直接开始修改。