diff --git a/healthlink-his-server/AGENTS.md b/healthlink-his-server/AGENTS.md index 4a13dc4ae..d320b4a8a 100644 --- a/healthlink-his-server/AGENTS.md +++ b/healthlink-his-server/AGENTS.md @@ -1,29 +1,438 @@ -# HealthLink-HIS 后端开发规范 +# HealthLink-HIS — AI 开发规范 -> 🤖 本文件供 AI 工具自动读取。完整规范见 **[../../RULES.md](../../RULES.md)** +> 🤖 本文件供所有 AI 编码工具自动读取。进入本项目后必须遵守以下规范。 +> +> **模型决定上限,Harness 决定底线。** -## 铁律速查 +--- -1. **修改完必须测试** — `mvn clean compile -DskipTests` -2. **Flyway 迁移** — 新建表/字段必须走 Flyway -3. **测试通过才提交** — 编译+测试全通过才能 commit -4. **API路径对齐** — `/healthlink-his/api/v1/` -5. **先分解再行动** — 非平凡任务先出计划 -6. **文档在 MD 目录** — 大写下划线命名 -7. **铁律18: 禁止破坏原有功能** — 完善功能时不能破坏已有功能 +## 一、项目概览 -## 快速命令 +| 属性 | 值 | +|------|------| +| 项目名 | HealthLink-HIS(医院信息系统) | +| 后端路径 | `healthlink-his-server/` | +| 前端路径 | `healthlink-his-ui/` | +| 文档路径 | `MD/` | +| JDK | 25 (OpenJDK) | +| Spring Boot | 4.0.6 | +| MyBatis-Plus | 3.5.16 | +| Vue | 3.x + Vite + Element Plus | +| 数据库 | PostgreSQL 15+ | +| 包名 | `com.healthlink.his` | +| 后端端口 | 18082 | +| 前端端口 | 81 | + +--- + +## 二、铁律(必须遵守,违反即失败) + +### 🔴 P0 铁律 — 不可违反 + +**铁律1: 修改完必须测试** +``` +后端: mvn clean compile -DskipTests → mvn install -DskipTests → mvn test +前端: npm run build:dev → npm run lint +``` +- 白盒:编译通过,无 ERROR +- 黑盒:关键接口返回 `{code:200, data:...}`,验证业务逻辑 +- 冒烟:应用正常启动,核心流程通畅 + +**铁律2: Flyway 数据库迁移** +- 凡是新建表、新增字段,必须创建 Flyway 迁移脚本 +- 路径:`healthlink-his-domain/src/main/resources/db/migration/` +- 命名:`V{版本号}__{描述}.sql`(双下划线) + +**铁律3: 测试通过后才提交** +- 编译 + 测试全部通过后才能 git commit +- 不提交未完成的功能、调试代码、临时文件 + +**铁律4: 前后端API路径对齐** +- 后端前缀:`/healthlink-his/api/v1/` +- 前端 `request.js` 的 baseURL 必须与后端匹配 + +**铁律5: 状态值一致性(Bug #574 教训)** +- 修改任何状态值前,必须先列出完整的状态流转链路 +- 检查项:枚举定义 → Service 设置 → 查询映射 → 前端 STATUS_CLASS_MAP → 前端 v-if → 统计SQL +- 禁止:只改一端不检查其他端 + +**铁律6: 禁止删除源文件(Bug #574 教训)** +- 绝对禁止删除项目中已有的 Java/Vue/SQL 源文件 +- 编译错误 → 修复错误;重复文件 → 重构合并 +- AI 幻觉文件 → 检查 `git ls-tree baseline -- ` 确认后再删除 +- 唯一例外:明确由人类确认删除的文件 + +**铁律7: 禁止修改已有公开方法签名** +- 不能删除/重命名已有的 public 方法,不能修改参数列表 +- 需要新功能 → 添加重载方法;需要改行为 → 修改内部实现 + +**铁律8: 验证后才宣称完成(Verification Before Completion)** +- **没有跑过验证命令,就不能说"完成了""通过了""没问题"** +- 禁止使用"应该可以""大概没问题""看起来正确" +- 必须:运行命令 → 读取输出 → 确认结果 → 才能宣称 +- 这是诚实原则,不是效率问题 + +**铁律9: 开发前必须审核原有代码(P0 — 铁律)** +- **任何新功能开发前,必须先搜索项目中是否已有相关代码** +- 搜索路径:Controller / AppService / Service / Mapper / Entity / 前端页面 / API接口 +- 如果已有部分功能 → 在原有代码基础上**升级优化完善**,禁止另起炉灶 +- 如果已有接口但前端缺失 → 只补前端,不重复建后端 +- 如果已有前端但后端缺失 → 只补后端,不重写前端 +- 搜索命令:`rg -l "关键词" healthlink-his-server/ healthlink-his-ui/src/` +- 禁止:不看代码就新建模块、重复实现已有功能、废弃原有代码另写一套 + +**铁律10: 状态变更影响面分析(Bug #574→575 教训)** +- 改任何状态枚举值前,**必须**执行影响面分析 +- `rg "原状态枚举名" --type java` 列出所有引用文件 +- 逐个检查:设置值?查询过滤?显示映射?统计聚合? +- 检查逆向流程:退号、取消、停诊是否兼容新状态 +- 检查 XML mapper 中所有查询过滤条件 +- 检查前端所有 v-if/v-for/disabled 条件 +- **禁止**:只改正向流程不验逆向流程 + +**铁律11: 逆向流程验证(Bug #575 教训)** +- 涉及状态流转的 Bug,验证时**必须**覆盖: + - 正向:预约→签到→就诊→完成 + - 逆向:退号、取消预约、停诊、退费 + - 边界:并发操作、重复操作、异常中断 +- **禁止**:只测正向流程就标记"修复完成" + +**铁律12: 全链路 6 环分析** +- 涉及数据库字段的 Bug/需求 必须走完整链路 +``` +前端/页面 → Controller → Service → Mapper → DB/SQL → 关联模块 + ①录入 ②验证 ③业务 ④持久化 ⑤存储 ⑥联动 +``` +- ①录入:前端有无输入入口(弹窗、表格行编辑、表单) +- ②验证:Controller 参数校验、@Valid、权限控制 +- ③业务:Service 业务逻辑、事务边界、多个 Service 实现类入口 +- ④持久化:Mapper XML、DTO 字段映射、类型转换 +- ⑤存储:数据库表结构、索引、NOT NULL 约束 +- ⑥联动:上游(医嘱→护士站)、下游(打印、计费、报表)是否同步 + +**铁律13: 全链路验证(状态流转 Bug 必做)** +- 修复后按以下顺序验证,**编译通过不等于修复完成** +``` +① 数据库:SELECT status FROM table WHERE id = ? → 确认写入正确 +② 后端接口:检查所有 if/switch 分支 → 确认映射正确 +③ 前端显示:检查 STATUS_CLASS_MAP → 确认文本正确 +④ 前端交互:检查 v-if/v-for/disabled → 确认按钮状态正确 +⑤ 统计数据:检查聚合 SQL → 确认统计包含新状态 +``` + +**铁律14: 池/统计表同步(Bug #574 教训)** +- **任何状态变更必须同步更新关联统计表** +- 检查清单: + 1. 状态变更后,哪些统计字段需要更新? + 2. 是原子递增/递减,还是全量重算? + 3. 并发安全:用 `SET field = field + 1` 还是先查后改? + 4. 逆向操作(退号/取消)是否正确回滚统计? +- **禁止**:只改状态不改统计,或只改统计不改状态 + +**铁律15: 统计变更必须验证实际值(Bug #575 教训)** +- 修改统计逻辑后,**必须查数据库验证实际值** +- 对比操作前后的值,确认统计正确 +- **禁止**:改了统计逻辑不查数据库验证 + +**铁律16: 搜索所有相关代码路径** +- 修复前必须用 `rg` 搜索所有引用 +``` +rg "状态枚举名|相关方法名|相关字段名" --type java --type vue +``` +- 确保不遗漏任何引用路径 + +**铁律17: 数据库铁律** +- **修前必须查询真实数据库** — 确认表结构、字段约束、索引 +- **禁止凭猜测写 SQL** — 先查看表结构 +- **修改 SQL 后必须验证** — `EXPLAIN` 或实际查询验证语法 +- **NOT NULL 约束必须检查** — INSERT/UPDATE 前先查 `is_nullable` +- **关联表必须查完整** — 涉及 JOIN 查所有关联表结构和外键 + +**铁律18: 禁止破坏原有功能(P0绝对铁律)** +- **完善增加功能和流程时,绝对不能破坏或者让原有功能不能用** +- 修改已有实体前必须对比原始文件(`git show HEAD~N:./file.java`),保留所有原有字段和方法 +- 新增字段只能追加,不能删除或重命名已有字段 +- SQL迁移只允许 `ALTER TABLE ADD COLUMN`,不允许 `DROP COLUMN` 或 `RENAME COLUMN` +- Controller新端点不能修改已有端点的路径或参数 +- 前端新页面不能修改已有页面的组件结构 +- 每次修改后必须 `mvn clean compile -DskipTests` 验证 + +**铁律19: 编译错误不区分来源(Bug #698 教训)** +- `mvn compile`、`vite build`、`vue-tsc` 等构建命令报错 = 不过关,**不管是自己引入的还是历史遗留的** +- 禁止说"这是预存问题""不是我改的""原有bug"——构建通不过就不能宣称完成 +- 正确做法:定位错误 → 修复 → 重新构建确认通过 → 然后才能继续 + +**铁律20: 数据来源必须验证(Bug #698 教训)** +- 涉及数据查询/提取时,必须先确认数据实际存储位置,不能假设 +- 修复前必须:打印/检查原始数据结构 → 确认字段存在 → 再写提取逻辑 +- 禁止:凭代码推断数据位置、假设"应该在这里" + +**铁律21: 外部配置值必须实测验证(Bug #698 教训)** +- 使用外部服务(API、模型、数据库)的配置值,必须实际调用验证 +- 配置变更后必须:发起一次真实请求 → 确认返回 200 → 再宣称配置正确 +- 禁止:改完配置不测试、假设"应该能用" + +**铁律22: 端到端验证必须有实际输出证据(Bug #698 教训)** +- 声称功能生效前,必须有实际的端到端输出证据 +- 验证方式:运行命令 → 检查输出中包含预期关键词 +- 禁止:只检查代码路径可达就算"验证通过" + +**铁律23: 文件读写强制 UTF-8 编码(必遵守)** +- **禁止**使用 PowerShell Get-Content -Raw(不带 -Encoding UTF8)读取源文件 +- **禁止**使用 Out-File -Encoding utf8(会写 BOM) +- **正确写法**: + - 读取:`[System.IO.File]::ReadAllText($path, [System.Text.Encoding]::UTF8)` + - 写入:`[System.IO.File]::WriteAllText($path, $content, [System.Text.UTF8Encoding]::new(False))` +- **原因**:Windows PowerShell 5.1 默认用系统 locale(GBK/CP936)读写,会把 UTF-8 中文变成乱码 + +**铁律24: 禁止硬编码业务默认值(Bug #617 教训)** +- **禁止**在提交参数中硬编码业务默认值(如 `contractNo: '0000'`) +- 必须使用用户在表单中选择的值,硬编码值仅作为 fallback +- 检查清单: + 1. 表单字段是否有 `v-model` 绑定? + 2. 构建提交参数时是否使用了绑定值? + 3. 提交后是否覆盖了用户选择? + +--- + +### 🟡 P1 铁律 — 强烈建议 + +**铁律25: 先分解再行动** +- 修改超过3个文件、涉及多模块、数据库变更,必须先制定计划 + +**铁律26: 验证后信** +- 每次修改后必须验证编译通过,不信记忆 + +**铁律27: 文档统一管理** +- 所有文档存储在 `MD/` 目录 +- 文件名:大写英文+下划线(如 `BACKEND_CHECKLIST.md`) +- 文档头部必须包含元数据块(文档类型、版本、日期) + +**铁律28: 设计文档必须包含UI设计和调用流程** +- 所有新模块/页面的设计文档必须包含:UI布局描述、交互效果清单、前后端调用流程 +- 没有明确UI设计的模块,禁止直接编码 +- 设计文档必须写清楚:系统调用关系、方法函数调用关系、完整业务流程 +- 设计文档中每个用户操作必须对应:前端事件 → API调用 → 后端处理链路 → 返回数据 → UI渲染 + +**铁律29: 设计文档确认后自主开发(铁律)** +- 设计文档一旦确认,后续开发**必须按文档自主执行** +- **禁止反复询问"是否继续""下一步做什么""是否开始"**——直接按计划推进 +- 每完成一个 Sprint,自动提交推送,然后立即开始下一个 Sprint +- 只在遇到**无法解决的阻塞**时才暂停询问 + +**铁律30: 前端验证铁律** +- **提交前必须编译前端** — `npm run build:dev` 或 `npx vite build` 通过才算完成 +- **禁止只改 .vue 文件不验证编译** — 改完必须跑一次编译确认无报错 +- **SCSS 括号闭合必须检查** — `