You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
haoliang-net/AGENTS.md

377 lines
18 KiB
Markdown

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# 项目知识库
**生成时间:** 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. 修改请求预处理协议
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 + Moq100%方法覆盖 ≥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跳过预处理直接开始修改。