his/AGENTS.md

HealthLink-HIS — AI 开发规范

🤖 本文件由 Codex CLI、Claude Code 等工具自动读取。 工具进入项目目录时会自动加载此文件作为开发规范上下文。

---

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

🤖 本文件供所有 AI 编码工具自动读取。无论使用 Claude Code、Cursor、Codex CLI、Copilot、Qwen、Cline 还是其他工具，进入本项目后必须遵守以下规范。

模型决定上限，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（双下划线）
• 禁止直接在数据库执行 SQL 不走 Flyway

铁律3: 测试通过后才提交

• 编译 + 测试全部通过后才能 git commit
• 不提交未完成的功能、调试代码、临时文件

铁律4: 前后端API路径对齐

• 后端前缀：/healthlink-his/api/v1/
• 前端 request.js 的 baseURL 必须与后端匹配
• 接口变更必须同步更新前后端代码

铁律5: 状态值一致性（来自 Bug #574 教训）

• 修改任何状态值前，必须先列出完整的状态流转链路
• 检查项：
  1. 枚举定义的值是否正确
  2. Service 层设置的状态值是否与枚举一致
  3. 查询/列表接口的状态映射是否覆盖所有枚举值
  4. 前端 STATUS_CLASS_MAP 是否包含新状态
  5. 前端过滤条件（如 v-if）是否兼容新状态
  6. 池/统计表的聚合 SQL 是否包含新状态值
• 禁止：只改一端不检查其他端

铁律6: 禁止删除源文件（来自 Bug #574 教训）

• 绝对禁止删除项目中已有的 Java/Vue/SQL 源文件
• 文件有编译错误 → 修复错误，不删除文件
• 文件是重复的 → 重构合并，不删除文件
• 文件是 AI 幻觉创建的 → 检查 git baseline 确认后再删除
• 唯一例外：明确由人类确认删除的文件

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

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

🟡 P1 铁律 — 强烈建议

铁律8: 先分解再行动

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

铁律9: 验证后信

• 每次修改后必须验证编译通过，不信记忆
• 重新编译命令：mvn clean compile -DskipTests

铁律10: 文档统一管理

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

---

三、全链路 6 环分析

⚠️ 涉及数据库字段的 Bug / 需求，必须走完整链路，不得"就事论事"。

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

每一环必须确认

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

全链路验证顺序

修复涉及状态流转的问题后，必须按以下顺序验证：

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

常见陷阱

• ❌ 只修了「主入口」的保存逻辑，忘了「批量保存」「签发保存」等其他入口
• ❌ 前端加了输入框，后端 Service 没传字段
• ❌ Mapper XML 是 UNION ALL 查询，只改了其中一个子查询
• ❌ DTO 层级继承关系没检查
• ❌ 只测了新增，没测编辑已有数据的回显和修改再保存

---

四、Harness Engineering 方法论

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

4.1 四层约束金字塔

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

约束优先级：安全 > 架构 > 质量 > 业务

4.2 三层反馈系统

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

反馈设计铁律：

• 反馈必须可行动（指出：文件 + 行号 + 错误类型 + 修复方向）
• 反馈越及时越好（L1 即时 → L2 分钟 → L3 小时）
• 失败后先回滚到最近检查点，再重试

4.3 控制平面（Agent 协调）

┌─────────────────────────────────────────────┐
│  战略层（人类主导）                          │
│  ├── 设定目标、审批关键决策                   │
│  └── 异常升级处理                            │
├─────────────────────────────────────────────┤
│  战术层（Control Plane）                     │
│  ├── 任务分解 + update_plan                  │
│  ├── 依赖协调 + 资源分配                     │
│  └── 检查点保存 + 恢复                       │
├─────────────────────────────────────────────┤
│  执行层（Agent 自主）                        │
│  ├── 代码生成、测试执行                      │
│  └── 错误恢复 + 幂等重试                     │
└─────────────────────────────────────────────┘

4.4 持久执行

• 每个关键步骤保存检查点（update_plan 进度）
• 失败后从最新检查点恢复，不从头开始
• 幂等设计：同一操作重复执行结果一致

---

五、质量门禁（5 级）

级别	门禁	通过标准
L1	编译通过	mvn clean compile + npm run build:dev 无 ERROR
L2	测试通过	单元测试 + 接口测试全部通过
L3	DB 审查	Flyway 脚本规范、SQL 安全、索引合理
L4	验收通过	核心功能流程完整验证、全链路检查
L5	归档完成	Git commit + 文档更新 + 代码推送

提交铁律

• L1-L2 必须通过才能 commit
• L3（如有DB变更）必须通过才能 push
• L4-L5 发布前必须完成

---

六、后端开发规范

分层架构

Controller → AppService → Service → Mapper → Entity
  接收请求    编排业务      单表CRUD   数据访问   实体定义

命名规范

类型	规则	示例
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

统一返回格式

AjaxResult.success(data)       // 成功
AjaxResult.error("错误信息")    // 失败
getDataTable(list)             // 列表

关键约束

• 所有查询使用 LambdaQueryWrapper，禁止字符串拼接 SQL
• @Transactional(rollbackFor = Exception.class) 管理事务
• 所有接口标注 @PreAuthorize 权限控制
• 患者敏感信息（身份证、手机号）在日志中脱敏
• 扩展功能不修改原有函数签名，新建 Service/AppService
• 涉及多表写操作的方法标注 @Transactional
• 事务方法未被同一类内方法直接调用（避免自调用失效）

---

七、前端开发规范

技术栈

• Vue 3 + Vite + Element Plus + Pinia + Axios
• 基于 RuoYi-Vue3 框架

目录结构

src/api/{module}/        # API接口（kebab-case路径）
src/views/{module}/      # 页面组件
src/store/modules/       # Pinia状态管理
src/components/          # 公共组件

API 路径规范

// 统一前缀 /healthlink-his/api/v1/
export function listXxx(query) {
  return request({ url: '/healthlink-his/api/v1/xxx/list', method: 'get', params: query })
}

组件规范

• 页面组件使用 <script setup> 语法
• 弹窗组件使用 defineExpose({ open }) 暴露打开方法
• 列表必须支持分页（pagination 组件）
• 按钮权限使用 v-hasPermi 指令

关键约束

• 路由懒加载：() => import('@/views/xxx/index.vue')
• 不使用 v-html（除非做 XSS 转义）
• 不在前端硬编码密码、密钥
• onMounted 中注册的事件在 onUnmounted 中移除

---

八、Agent 体系（智能体协作）

角色定义

代号	名称	角色	职责
liubei	刘备	项目经理	总协调、任务分配、异常升级
zhugeliang	诸葛亮	架构师	需求分析、方案设计、技术决策
guanyu	关羽	后端开发	Java 后端修复、API 开发
zhaoyun	赵云	前端开发	Vue 前端修复、页面开发
xunyu	荀彧	DBA	数据库审查、SQL 优化、Flyway 脚本
zhangfei	张飞	测试	Playwright 测试、接口测试、回归测试
huatuo	华佗	验收	功能验收、质量确认、发布检查
chenlin	陈琳	文档	归档记录、文档更新、Git 提交

协作流水线

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

Bug 状态管理铁律

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

修复流程铁律

• 一次只修一个 Bug，不扩大范围
• 修复前必须读 AGENTS.md
• 修复后必须验证编译
• 涉及 SQL 必须先查真实数据库

测试流程铁律

• Playwright 必须 --workers=1 单线程
• 超时 120 秒
• 最多重试 3 次
• 测试结果写入禅道备注

归档流程铁律

• 三重归档：Git + SQLite + Redis
• SQLite 必须使用完整字段
• 禅道备注格式：[📝 陈琳归档] Bug #xxx

---

九、开发流程

收到任务
  ├→ ① 分析需求 → 读相关文档(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): description"  # 提交
git push origin develop                 # 推送

---

十一、详细规范文档索引

文档	路径	用途
执行铁律	MD/specs/IRON_RULES.md	铁律完整版
后端规范	MD/specs/BACKEND_DEVELOPMENT_STANDARD.md	后端编码标准
前端规范	MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md	前端编码标准
文档规范	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	数据库迁移指南
E2E测试	MD/specs/PLAYWRIGHT_TESTING_PLAN.md	Playwright测试方案

---

十二、过往教训（必须铭记）

教训	来源	教训内容
状态链路断裂	Bug #574	checkInTicket() 设 BOOKED(1) 而非 CHECKED_IN(3)，前端映射缺失，池统计漏计 → 必须走完整状态链路验证
盲删源文件	Bug #574	AI 看到编译错误直接删文件，没检查是否在 baseline → 必须先确认文件来源再操作
修复方向偏差	Bug #574	多次 fallback 改的是 OrderServiceImpl，完全没触及 TicketServiceImpl → 必须用 rg 搜索所有相关代码路径
bug_reports 表缺少列	经验	INSERT 会静默失败，必须检查表结构
禅道 comment API	经验	API 不存在，必须用 resolve+activate workaround
SQLite WAL 并发	经验	多进程并发写需要 checkpoint
UTF-8 切片	经验	多字节字符不能用 byte index 切片
禅道图片附件	经验	必须 OCR 读取，不能直接解析

---

⚠️ 警告: 本文件是项目 AI 开发规范的唯一信源。各工具配置文件（AGENTS.md、.cursorrules 等）均通过 bash scripts/sync-ai-rules.sh 从本文件同步。修改规范请只修改本文件。

---

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