From a0cef659c53848a173e6d662be2036175c68cf0c Mon Sep 17 00:00:00 2001 From: haoliang <821644@qq.com> Date: Wed, 29 Apr 2026 17:21:10 +0800 Subject: [PATCH] =?UTF-8?q?refactor:=20=E9=87=8D=E7=BB=84AGENTS.md?= =?UTF-8?q?=E7=BB=93=E6=9E=84=E2=80=94=E2=80=94=E9=93=81=E5=BE=8B=E7=BD=AE?= =?UTF-8?q?=E9=A1=B6=E3=80=81=E9=A1=B9=E7=9B=AE=E4=B8=8A=E4=B8=8B=E6=96=87?= =?UTF-8?q?=E5=B1=85=E4=B8=AD=E3=80=81=E7=A4=BA=E4=BE=8B=E4=B8=8B=E6=B2=89?= =?UTF-8?q?=E4=B8=BA=E9=99=84=E5=BD=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 223 +++++++++++++++++++++++++++++------------------------- 1 file changed, 118 insertions(+), 105 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 2313dcd..338ea80 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,11 +3,105 @@ **生成时间:** 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部署，局域网场景。 -## 项目结构 +### 项目结构 ``` . @@ -34,14 +128,14 @@ │ │ └── 管理后台/ # 12个子模块（登录/仪表盘/设备/品牌/采集地址/员工/产量/告警/系统/车间/操作日志/大屏配置） │ ├── 03-API接口设计.md # 13模块83端点（URL+Method两列对照） │ └── 04-后端开发规范.md # ⚠️ 后端必读：技术栈/项目结构/命名/注释/测试/分层/依赖注入规范 -├── frontend/ # 前端工程（Vue3+Vite+TypeScript+Element Plus） +├── frontend/ ← 前端工程（Vue3+Vite+TypeScript+Element Plus） │ ├── mock/ # Mock数据定义（按模块拆分） │ ├── src/ # 源码（路由/组件/样式/类型） │ └── vite.config.ts # Vite配置（mock插件+proxy） └── 发那科系统采集示例.txt # FANUC品牌采集JSON样例数据 ``` -## 查找指南 +### 查找指南 | 需求 | 位置 | 备注 | |------|------|------| @@ -57,16 +151,16 @@ | 管理后台某模块设计 | `docs/02-功能清单/管理后台/{编号}-{模块名}/` | 每模块含索引+规范+页面文件 | | 大屏看板设计 | `docs/02-功能清单/大屏/` | 索引+规范+页面 | -## 文档规范 +### 文档规范 -### 文件命名规则（必须遵循） +**文件命名规则（必须遵循）：** - 索引文件：`00-{名称}-索引.md` - 规范文件：`01-{名称}-规范.md` - 页面文件：`{模块号}-{页面号}-{页面名}.md`（如 `03-01-设备列表页面.md`） - 模块编号：两位数 01-99 -### 三种文件分工 +**三种文件分工：** | 文件类型 | 内容重点 | |---------|---------| @@ -74,12 +168,9 @@ | 规范文件 | 技术规范（组件、校验、布局、安全） | | 页面文件 | 技术实现（界面布局、字段定义、Mock数据） | -### 页面文件20项模板 - -结构定义(1-6) → 交互行为(7-12,14-15) → 技术实现(13,16-20) -详见 `docs/02-功能清单/02-文件夹创建规范.md` 第五节 +**页面文件20项模板：** 结构定义(1-6) → 交互行为(7-12,14-15) → 技术实现(13,16-20)，详见 `docs/02-功能清单/02-文件夹创建规范.md` 第五节 -## 核心业务规则 +### 核心业务规则 - **采集模式**：HTTP拉取JSON，非直连机床；地址间并行、地址内串行 - **零件计数**：NC程序名切换时结账上一段，新程序从0开始；同程序名多次出现分段记录 @@ -87,7 +178,7 @@ - **时间标准**：以服务器时间为准 - **品牌映射**：管理后台可视化配置，修改不回溯历史数据 -## 前端全局规范摘要 +### 前端全局规范摘要 - 组件库：Element Plus - API响应格式：`{ code: 0, message: "success", data: ... }` @@ -98,87 +189,30 @@ - Layout：顶部栏(系统名+管理员下拉) + 侧边栏(200px可折叠+10个菜单项) + 内容区 - 路由守卫：有Token访问/login重定向/dashboard，无Token访问管理后台重定向/login -## 待设计模块 - -- 采集服务核心逻辑设计（后置，后端API完成后启动） +### 项目状态 -## 已完成模块 +**已完成：** - ✅ 前端管理后台设计（见 `02-前端全局规范.md` + `02-功能清单/管理后台/`） - ✅ 大屏看板设计（见 `02-功能清单/大屏/`） - ✅ 数据库设计定稿（见 `01-数据库设计.md`，20张表已落地MariaDB） - ✅ API接口设计（见 `03-API接口设计.md`，13模块83端点） - ✅ 后端开发规范（见 `04-后端开发规范.md`） +- ✅ 前端界面设计全部完成(2026-04-26)，13个模块16个页面均已设计 -## 强制要求（必须遵守） - -- **思考过程使用中文**：所有AI助手的推理、分析、思考过程必须使用中文输出 -- **控制台输出中文**：所有控制台输出、日志、提示信息使用中文，不得出现乱码 -- **所有文档使用中文**：项目内所有文档、注释、界面文案使用中文 -- **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')"` - -## 修改请求预处理协议（强制执行） - -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` | 检查是否与已确认架构决策冲突 | +**待设计：** -### 第三步：输出修改计划摘要 +- 采集服务核心逻辑设计（后置，后端API完成后启动） -向用户展示以下信息，等待确认： +**备注：** -``` -修改分类：[标记组合] -必读规范：[列出具体文件名] -涉及文件：[逐文件列出变更内容] -联动影响：[需同步更新的文件清单，按03-界面变更执行规范.md联动规则逐条检查] -预估步骤：[1-N步] -``` +- 品牌预置：FANUC已预置，其他品牌手动添加 -### 豁免条件 +--- -以下情况可跳过预处理直接执行： +## 附录：修改预处理协议示例 -1. 用户明确说"直接执行"/"不用分析"/"直接改"等等效表述 -2. 修复代码中的typo/注释修改等纯文本变更（不涉及逻辑） -3. 用户已经在上文给出了完整的修改方案（等同于已确认） - -### 示例 - -**示例1：纯前端修改** +### 示例1：纯前端修改 > 用户："告警列表页的告警等级用不同颜色标签展示，紧急红色、重要橙色、一般黄色、提示蓝色" @@ -209,7 +243,7 @@ AI回复： > > 是否按此方案执行？ -**示例2：前端+API+后端联动** +### 示例2：前端+API+后端联动 > 用户："设备列表加一个按品牌筛选的条件" @@ -259,7 +293,7 @@ AI回复： > > 是否按此方案执行？ -**示例3：全栈变更（数据库+后端+API+前端）** +### 示例3：全栈变更（数据库+后端+API+前端） > 用户："设备表增加一个「最后采集时间」字段，前端详情页和列表页都要显示" @@ -313,7 +347,7 @@ AI回复： > > 是否按此方案执行？ -**示例4：纯后端Bug修复** +### 示例4：纯后端Bug修复 > 用户："MachineService.GetList 分页 page=0 时报错，应该自动修正为1" @@ -343,29 +377,8 @@ AI回复： > > 是否按此方案执行？ -**示例5：豁免直达** +### 示例5：豁免直达 > 用户："设备列表的分页 pageSize 上限从100改成200，直接执行" AI跳过预处理，直接开始修改。 - -## 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 - -## 注意事项 - -- 部分索引/规范文件内容为空（尚未填写）→ 已全部填写 -- 数据库设计已定稿(状态：定稿)，20张表已落地MariaDB -- 前端界面设计全部完成(2026-04-26)，13个模块16个页面均已设计 -- 品牌预置：FANUC已预置，其他品牌手动添加