jcl
/
haoliang-net
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

refactor: 重组AGENTS.md结构——铁律置顶、项目上下文居中、示例下沉为附录

Browse Source
main
haoliang 1 week ago
parent d2b44d2c64
commit a0cef659c5
1 changed files with 118 additions and 105 deletions
Show Stats Download Patch File Download Diff File

223
AGENTS.md
Unescape Escape View File

@ -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已预置，其他品牌手动添加

Write Preview
Loading…
Cancel
Save