his/.github/copilot-instructions.md

HealthLink-HIS — AI 开发规范 (GitHub Copilot)

🤖 GitHub Copilot 打开本项目时自动加载此文件。

---

HealthLink-HIS — AI 开发规范（自动加载）

🤖 本文件供所有 AI 编码工具自动读取。进入本项目后必须遵守以下规范。

模型决定上限，Harness 决定底线。

---

一、项目概览

属性	值
项目名	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 源文件
• 编译错误 → 修复错误；重复文件 → 重构合并
• 唯一例外：明确由人类确认删除的文件

铁律7: 禁止修改已有公开方法签名

• 不能删除/重命名已有的 public 方法，不能修改参数列表
• 需要新功能 → 添加重载方法；需要改行为 → 修改内部实现

铁律8: 验证后才宣称完成（Verification Before Completion）

• 没有跑过验证命令，就不能说"完成了""通过了""没问题"
• 禁止使用"应该可以""大概没问题""看起来正确"
• 必须：运行命令 → 读取输出 → 确认结果 → 才能宣称
• 这是诚实原则，不是效率问题

铁律9: 开发前必须审核原有代码（P0 — 铁律）

• 任何新功能开发前，必须先搜索项目中是否已有相关代码
• 搜索路径：Controller / AppService / Service / Mapper / Entity / 前端页面 / API接口
• 如果已有部分功能 → 在原有代码基础上升级优化完善，禁止另起炉灶
• 如果已有接口但前端缺失 → 只补前端，不重复建后端
• 如果已有前端但后端缺失 → 只补后端，不重写前端
• 搜索命令：rg -l "关键词" healthlink-his-server/ healthlink-his-ui/src/
• 禁止：不看代码就新建模块、重复实现已有功能、废弃原有代码另写一套

铁律12: 设计文档确认后自主开发（铁律）

• 设计文档（如 MD/architecture/GRADE3A_GAP_ANALYSIS_AND_DESIGN.md）一旦确认，后续开发必须按文档自主执行
• 禁止反复询问"是否继续""下一步做什么""是否开始"——直接按计划推进
• 每完成一个 Sprint，自动提交推送，然后立即开始下一个 Sprint
• 只在遇到无法解决的阻塞（如技术选型冲突、需求不明确、第三方依赖不可用）时才暂停询问
• 设计文档是"已签合同"，不是"参考意见"。铁律执行优先级：设计文档 > 人类临时指令 > AI 自行判断

🟡 P1 铁律 — 强烈建议

铁律9: 先分解再行动

• 修改超过3个文件、涉及多模块、数据库变更，必须先制定计划

铁律10: 验证后信

• 每次修改后必须验证编译通过，不信记忆

铁律13: 文档统一管理

• 所有文档存储在 MD/ 目录
• 文件名：大写英文+下划线（如 BACKEND_CHECKLIST.md）
• 文档头部必须包含元数据块（文档类型、版本、日期）

---

铁律14: 设计文档必须包含UI设计和调用流程

• 所有新模块/页面的设计文档必须包含：UI布局描述、交互效果清单、前后端调用流程
• 没有明确UI设计的模块，禁止直接编码
• 详见
• 设计文档必须写清楚：系统调用关系、方法函数调用关系、完整业务流程
• 设计文档中每个用户操作必须对应：前端事件 → API调用 → 后端处理链路 → 返回数据 → UI渲染

---

三、Karpathy 编码准则

减少 LLM 常见编码错误。偏向谨慎而非速度。

3.1 先想再写

• 明确陈述假设，不确定就问
• 多种解读时都列出来，不要默默选一种
• 有更简单的方案就说出来，该推回就推回
• 不清楚的地方停下来，说清楚哪里不清楚

3.2 简洁优先

• 不做没要求的功能，不做一次性代码的抽象
• 不加没要求的"灵活性"和"可配置性"
• 200 行能 50 行搞定就重写
• 自问："高级工程师会不会觉得这过度设计？"

3.3 精准修改

• 只改必须改的，不"顺手改进"相邻代码
• 匹配现有代码风格，即使你有不同的偏好
• 每行改动都能追溯到用户的请求
• 只清理你自己改动产生的无用代码

3.4 目标驱动

• 把任务转化为可验证目标
• 多步任务声明计划：[步骤] → 验证: [检查]
• 强验收标准让 Agent 能独立循环，弱标准需要持续澄清

---

四、全链路 6 环分析

⚠️ 涉及数据库字段的 Bug / 需求，必须走完整链路。

前端/页面 → Controller → Service → Mapper → DB/SQL → 关联模块
 ①录入      ②验证      ③业务     ④持久化    ⑤存储     ⑥联动

环	检查内容
① 录入	前端有无输入入口（弹窗、表格行编辑、表单）
② 验证	Controller 参数校验、@Valid、权限控制
③ 业务	Service 业务逻辑、事务边界、多个 Service 实现类入口
④ 持久化	Mapper XML、DTO 字段映射、类型转换
⑤ 存储	数据库表结构、索引、NOT NULL 约束
⑥ 联动	上游（医嘱→护士站）、下游（打印、计费、报表）是否同步

修复后的验证顺序：

1. 数据库：确认状态值已正确写入
2. 后端接口：确认返回的状态映射正确
3. 前端显示：确认页面显示正确状态文本
4. 前端交互：确认按钮/操作基于正确状态启用/禁用
5. 统计数据：确认池/报表统计包含新状态

---

五、Harness Engineering 方法论

Harness = 约束 + 反馈 + 控制平面 + 持久执行

5.1 四层约束金字塔

层级	内容	落地方式
L1 架构约束	接口合约、包结构、命名规范、禁止模式	本文件铁律
L2 代码质量	圈复杂度、代码风格、类型提示	编译门禁 + ESLint
L3 安全约束	敏感信息检测、权限检查、输入验证	配置不可硬编码
L4 业务规则	领域逻辑、数据一致性、事务边界	全链路 6 环验证

约束设计原则：

• 可验证：每条约束必须能被自动化检查（"覆盖率>90%"✅ "质量要高"❌）
• 无歧义："每函数不超过50行"✅ "函数不要太长"❌
• 优先级：安全(1) > 架构(2) > 业务(3) > 质量(4) > 性能(5)
• 渐进增强：L1编译通过 → L2+命名规范 → L3+测试覆盖 → L4+安全扫描

5.2 三层反馈系统

层级	速度	覆盖范围	失败处理
L1 编译检查	<30秒	语法、类型、签名	立即阻断，自行修复
L2 数据流验证	<5分钟	全链路字段、Mapper XML、DTO	修复后上报
L3 人工审查	10-30分钟	架构、设计、业务正确性	驳回/指导/批准

反馈铁律：

• 反馈必须可行动（文件 + 行号 + 错误类型 + 修复方向）
• 失败后先回滚到最近检查点，再重试
• 持续失败3次 → 上报人类

5.3 控制平面

战略层（人类） → 设定目标、审批决策、异常升级
战术层（Agent） → 任务分解、update_plan、依赖协调、检查点保存
执行层（Agent） → 代码生成、测试执行、错误恢复、幂等重试

5.4 持久执行

• 每个关键步骤保存检查点（update_plan 进度）
• 失败后从最新检查点恢复，不从头开始
• 幂等设计：同一操作重复执行结果一致
• 三层状态管理：系统层(工作流ID/超时/重试) → 执行层(当前活动/进度) → 业务层(已完成工作/中间产物)

---

六、五层质量门禁

门禁	时间	范围	失败处理
L1 编译检查	<30秒	语法、类型、导入	Agent 自行修复
L2 静态分析	<2分钟	代码风格、复杂度、安全	Agent 修复
L3 单元测试	<5分钟	功能正确性、边界条件	自动修复或上报
L4 集成测试	<15分钟	模块间交互、数据流	上报人工
L5 生产验证	持续	监控、告警、性能	自动回滚

提交铁律：L1-L2 必须通过才能 commit，L3（如有DB变更）必须通过才能 push

---

七、系统化调试（Systematic Debugging）

铁律：没有根因调查，不能提出修复方案。

四阶段流程

阶段1：根因调查（修复前必须完成）

1. 仔细阅读错误信息（堆栈、行号、错误码）
2. 稳定复现（能否可靠触发？步骤？每次？）
3. 检查最近变更（git diff、新依赖、配置变更）
4. 多组件系统：在每个组件边界加诊断日志，定位哪一层断裂
5. 追踪数据流：坏值从哪里来？谁调用的？一直追溯到源头

阶段2：模式分析

• 找到同代码库中类似的正常工作代码
• 逐项对比差异
• 理解依赖关系

阶段3：假设与测试

• 形成单一假设："我认为X是根因，因为Y"
• 做最小改动测试
• 有效 → 阶段4；无效 → 新假设

阶段4：实施

• 创建失败测试用例
• 修复根因（不是症状）
• 验证修复

---

八、后端开发规范

分层架构

Controller → AppService → Service → Mapper → Entity

命名规范

类型	规则	示例
Controller	XxxController	RegistrationController
AppService	IXxxAppService / XxxAppServiceImpl	IRegistrationAppService
Service	IXxxService / XxxServiceImpl	IRegistrationService
Mapper	XxxMapper	RegistrationMapper
Entity	Xxx	Registration
DTO	XxxDto / XxxQueryDto	RegistrationDto

包结构

com.healthlink.his.web.{module}.controller
com.healthlink.his.web.{module}.appservice
com.healthlink.his.web.{module}.service
com.healthlink.his.web.{module}.mapper
com.healthlink.his.web.{module}.dto
com.healthlink.his.domain.{module}
com.healthlink.his.common.enums

关键约束

• 所有查询使用 LambdaQueryWrapper，禁止字符串拼接 SQL
• @Transactional(rollbackFor = Exception.class) 管理事务
• 所有接口标注 @PreAuthorize 权限控制
• 患者敏感信息在日志中脱敏
• 扩展功能不修改原有函数签名

---

九、前端开发规范

技术栈

• Vue 3 + Vite + Element Plus + Pinia + Axios（基于 RuoYi-Vue3）

目录结构

src/api/{module}/        # API接口
src/views/{module}/      # 页面组件
src/store/modules/       # Pinia状态管理
src/components/          # 公共组件

关键约束

• API前缀：/healthlink-his/api/v1/
• 路由懒加载：() => import('@/views/xxx/index.vue')
• 页面使用 <script setup> 语法
• 按钮权限使用 v-hasPermi 指令
• onMounted 中注册的事件在 onUnmounted 中移除

---

十、Agent 体系

角色与路由

代号	名称	角色	路由关键词
liubei	刘备	项目经理	协调、分派、异常升级
zhugeliang	诸葛亮	架构师	分析、路由、设计
guanyu	关羽	后端开发	java, api, spring, service, controller
zhaoyun	赵云	前端开发	vue, 界面, 显示, 弹窗, 按钮
xunyu	荀彧	DBA	数据库, sql, 迁移, mapper xml
zhangfei	张飞	测试	测试, QA, 回归
huatuo	华佗	验收	需求验收、质量确认
chenlin	陈琳	文档	文档、归档、Git提交

协作流水线

刘备(协调) → 诸葛亮(分析路由) → {关羽|赵云}(修复) → 荀彧(DB审查) → 张飞(测试) → 华佗(验收) → 陈琳(归档)

Bug 修复完整管线（BDT 方法论）

获取Bug → 设计测试用例 → 基线测试(应失败) → 全链路修复 → 回归测试(应通过) → 扩展测试(无回归) → 提交

Bug 状态管理铁律

• 人类提的 Bug：只加备注，不改状态，不改分配
• 智能体提的 Bug：可以改分配和加备注
• 已关闭/已解决的 Bug 不再处理

---

十一、审查与审计

三层审查体系

层级	内容	时机
L1 自审	Agent 对照约束逐条检查	每次提交前
L2 配对审查	Agent 生成变更摘要，人类终审	PR/提交时
L3 合规审查	审计追踪，记录所有 AI 操作	持续

L1 自审清单

self_review:
  - "所有修改能通过编译？"
  - "遵守命名规范？"
  - "测试覆盖达标？"
  - "没有遗漏的 TODO / DEBUG？"
  - "变更范围没超出任务边界？"

评审评分维度

维度	问题
正确性	行为是否符合目标功能？
验证	检查是否真的跑过并留下证据？
范围纪律	是否保持在选定功能范围内？
可靠性	结果能否在重启后继续工作？
可维护性	代码和文档是否清楚到可交接？

---

十二、标准工作循环

开始会话
  ├→ 1. Init — 读 AGENTS.md + PROGRESS.md + git log
  ├→ 2. Select — 只选一个未完成功能
  ├→ 3. Implement — 一次只做一个，不扩大范围
  ├→ 4. Verify — 运行验证命令，有证据才标记完成
  └→ 5. Cleanup — 更新进度 + clean-state-checklist + git commit

会话结束前必须运行 Clean State Checklist

□ 标准启动路径仍然可用
□ 标准验证路径仍然可运行
□ 当前进度已记录到进度日志
□ 无半成品步骤处于未记录状态
□ 下一轮会话无需人工修复即可继续

---

十三、开发流程

收到任务
  ├→ ① 分析需求 → 读相关文档(MD/)、读全链路6环
  ├→ ② 制定计划 → update_plan (3-6个阶段)
  ├→ ③ 后端开发 → Controller → AppService → Service → Mapper → Entity → Flyway
  ├→ ④ 后端测试 → mvn test → 接口测试(业务逻辑验证)
  ├→ ⑤ 前端开发 → API接口 → 页面组件 → 路由配置
  ├→ ⑥ 前端测试 → npm run build:dev → 功能验证
  ├→ ⑦ 质量门禁 → L1编译 → L2测试 → L3DB审查 → L4验收 → L5归档
  └→ ⑧ 提交代码 → git commit(规范格式) → git push → 文档更新

Git Commit 格式

<type>(<scope>): <subject>

type: feat|fix|docs|refactor|test|chore
scope: 模块名(如 registration, billing, pharmacy)

---

十四、快速参考命令

# === 后端 ===
export JAVA_HOME=/opt/jdk-25
mvn clean compile -DskipTests          # 编译
mvn install -DskipTests                # 构建
mvn test -pl healthlink-his-application -Dtest="XxxTest" -Dsurefire.failIfNoSpecifiedTests=false

# === 前端 ===
cd healthlink-his-ui
npm run dev && npm run build:dev && npm run lint && npm run test:run

# === Git ===
git status && git add -A && git commit -m "feat(module): desc" && git push origin develop

---

十五、详细规范文档索引

文档	路径	用途
执行铁律	MD/specs/IRON_RULES.md	铁律完整版
后端规范	MD/specs/BACKEND_DEVELOPMENT_STANDARD.md	后端编码标准
前端规范	MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md	前端编码标准
Harness方法论	MD/specs/HARNESS_ENGINEERING.md	完整Harness+Agent方法论
文档规范	MD/DOCUMENTATION_STANDARD.md	文档管理标准
后端清单	MD/specs/BACKEND_CHECKLIST.md	发布前检查
前端清单	MD/specs/FRONTEND_CHECKLIST.md	发布前检查
三甲标准	MD/standards/GRADE3A_HIS_STANDARD.md	三甲医院达标标准
Flyway指南	MD/guides/FLYWAY_USAGE_GUIDE.md	数据库迁移指南

---

十六、过往教训

教训	内容
状态链路断裂	Bug#574: 签到设 BOOKED(1) 而非 CHECKED_IN(3)，前端映射缺失 → 必须走完整状态链路
盲删源文件	AI 看到编译错误直接删文件，没检查 baseline → 必须先确认文件来源
修复方向偏差	多次 fallback 改的是错误的 Service → 必须用 rg 搜索所有相关代码路径
bug_reports 缺列	INSERT 静默失败 → 必须检查表结构
禅道 comment API	API 不存在，用 resolve+activate workaround
SQLite WAL 并发	多进程并发写需要 checkpoint
UTF-8 切片	多字节字符不能用 byte index 切片
上下文焦虑	Agent 感觉上下文快满时会匆忙结束，跳过验证 → 注意 context 40% 阈值
过早宣告胜利	自评≠验证，分开"干活"和"检查"
覆盖率幻觉	覆盖率达标但逻辑没测 → 引入变异测试

---

⚠️ 本文件是 AI 开发规范的唯一信源。各工具配置文件由 bash scripts/sync-ai-rules.sh 同步。

---

📅 最后同步: 2026-06-06 14:02 | 源文件: RULES.md | 重新同步: bash scripts/sync-ai-rules.sh