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.

10 KiB

Raw Blame History Unescape Escape

项目知识库

生成时间: 2026-04-25 项目: CNC机床数据采集系统

⚠️ 铁律（每次会话必须遵守）

以下规则优先级最高，无论执行什么任务都必须遵守。

1. 全程中文

思考过程使用中文：所有AI助手的推理、分析、思考过程必须使用中文输出
控制台输出中文：所有控制台输出、日志、提示信息使用中文，不得出现乱码
所有文档使用中文：项目内所有文档、注释、界面文案使用中文
代码注释中文：所有代码注释使用中文

2. Git提交（每次代码改动必须执行）

每次代码改动，编译/验证成功后，必须提交到Git并Push到远程仓库
远程仓库: https://git.cjy.net.cn/jcl/haoliang-net.git（分支: main）
账号: 821644@qq.com
提交信息必须使用中文，清楚描述改动内容

提交流程：

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验证套件）

6. 子代理委托铁律（每次委托必须遵守）

子代理（Sisyphus-Junior）会虚报完成——声称"已写入文件"但实际文件为空或不存在。

委托写文件任务时，必须在prompt中明确指定使用 Write 或 Edit 工具，禁止子代理自行选择 apply_patch 等不可用工具
收集子代理结果后，必须用 Read 工具验证文件实际内容，不能信任子代理的文字报告
子代理说自己 commit 了，必须用 git log 验证，不能信任其口头声明
验证清单（每个委托写文件的任务完成后必查）：
1. 文件是否存在（Read工具打开确认）
2. 文件内容是否完整（不是1行空文件）
3. 文件内容是否正确（不是占位符或模板）
发现子代理虚报完成时，必须立即自己重写，不能再次委托给同一个session

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

10 KiB Raw Blame History Unescape Escape