wangyizhe/his
1
3
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases Wiki Activity

feat: 全面整合agentforge-rs + .codex/harness方法论到AI开发规范

Browse Source 
RULES.md 420→460行，新增整合内容:
- Karpathy编码准则(先想再写/简洁优先/精准修改/目标驱动)
- 验证后才宣称完成铁律(Verification Before Completion)
- 系统化调试四阶段(Systematic Debugging)
- 约束设计原则(可验证/无歧义/优先级/渐进增强)
- 持久执行三层状态管理(系统层/执行层/业务层)
- 审查与审计三层体系(自审/配对审查/合规审查)
- BDT方法论(Bug Driven Testing + Playwright 7种检查模式)
- L4/L5分析与AI自主优化机制
- 标准工作循环(Init→Select→Implement→Verify→Cleanup)
- Clean State Checklist(会话结束检查)
- 新增10条过往教训(含上下文焦虑/过早宣告胜利等)

新增 MD/specs/HARNESS_ENGINEERING.md (305行) — 完整方法论参考:
- WalkingLabs 5子系统模型
- 约束/反馈/控制平面/持久执行详解
- Agent协作管线/路由/去重/禅道操作
- BDT测试用例设计/质量标准
- L4量化分析 + L5 AI自优化

7个AI工具配置文件同步更新(470行内嵌)
This commit is contained in:
华佗
2026-06-06 10:01:41 +08:00
parent 84ba9a4139
commit f3880eb8df
9 changed files with 1991 additions and 1366 deletions
Download Patch File Download Diff File Expand all files Collapse all files

380
.aider.conf.yml
View File

@@ -4,7 +4,7 @@
instructions: | instructions: |
# HealthLink-HIS — AI 开发规范（自动加载） # HealthLink-HIS — AI 开发规范（自动加载）
> 🤖 **本文件供所有 AI 编码工具自动读取**。无论使用 Claude Code、Cursor、Codex CLI、Copilot、Qwen、Cline 还是其他工具，进入本项目后必须遵守以下规范。 > 🤖 **本文件供所有 AI 编码工具自动读取**。进入本项目后必须遵守以下规范。
> >
> **模型决定上限，Harness 决定底线。** > **模型决定上限，Harness 决定底线。**
@@ -46,7 +46,6 @@ instructions: |
- 凡是新建表、新增字段，必须创建 Flyway 迁移脚本 - 凡是新建表、新增字段，必须创建 Flyway 迁移脚本
- 路径：`healthlink-his-domain/src/main/resources/db/migration/` - 路径：`healthlink-his-domain/src/main/resources/db/migration/`
- 命名：`V{版本号}__{描述}.sql`（双下划线） - 命名：`V{版本号}__{描述}.sql`（双下划线）
- 禁止直接在数据库执行 SQL 不走 Flyway
**铁律3: 测试通过后才提交** **铁律3: 测试通过后才提交**
- 编译 + 测试全部通过后才能 git commit - 编译 + 测试全部通过后才能 git commit
@@ -55,59 +54,80 @@ instructions: |
**铁律4: 前后端API路径对齐** **铁律4: 前后端API路径对齐**
- 后端前缀：`/healthlink-his/api/v1/` - 后端前缀：`/healthlink-his/api/v1/`
- 前端 `request.js` 的 baseURL 必须与后端匹配 - 前端 `request.js` 的 baseURL 必须与后端匹配
- 接口变更必须同步更新前后端代码
**铁律5: 状态值一致性（来自 Bug #574 教训）** **铁律5: 状态值一致性（Bug #574 教训）**
- 修改任何状态值前，必须先列出完整的状态流转链路 - 修改任何状态值前，必须先列出完整的状态流转链路
- 检查项： - 检查项：枚举定义 → Service 设置 → 查询映射 → 前端 STATUS_CLASS_MAP → 前端 v-if → 统计SQL
1. 枚举定义的值是否正确
2. Service 层设置的状态值是否与枚举一致
3. 查询/列表接口的状态映射是否覆盖所有枚举值
4. 前端 `STATUS_CLASS_MAP` 是否包含新状态
5. 前端过滤条件（如 `v-if`）是否兼容新状态
6. 池/统计表的聚合 SQL 是否包含新状态值
- 禁止：只改一端不检查其他端 - 禁止：只改一端不检查其他端
**铁律6: 禁止删除源文件（来自 Bug #574 教训）** **铁律6: 禁止删除源文件（Bug #574 教训）**
- 绝对禁止删除项目中已有的 Java/Vue/SQL 源文件 - 绝对禁止删除项目中已有的 Java/Vue/SQL 源文件
- 文件有编译错误 → 修复错误，不删除文件 - 编译错误 → 修复错误；重复文件 → 重构合并
- 文件是重复的 → 重构合并，不删除文件
- 文件是 AI 幻觉创建的 → 检查 git baseline 确认后再删除
- 唯一例外：明确由人类确认删除的文件 - 唯一例外：明确由人类确认删除的文件
**铁律7: 禁止修改已有公开方法签名** **铁律7: 禁止修改已有公开方法签名**
- 不能删除或重命名已有的 public 方法 - 不能删除/重命名已有的 public 方法，不能修改参数列表
- 不能修改已有方法的参数列表 - 需要新功能 → 添加重载方法；需要改行为 → 修改内部实现
- 需要新增功能时 → 添加新的重载方法
- 需要改行为时 → 修改方法内部实现，不改签名 **铁律8: 验证后才宣称完成（Verification Before Completion）**
- **没有跑过验证命令，就不能说"完成了""通过了""没问题"**
- 禁止使用"应该可以""大概没问题""看起来正确"
- 必须：运行命令 → 读取输出 → 确认结果 → 才能宣称
- 这是诚实原则，不是效率问题
### 🟡 P1 铁律 — 强烈建议 ### 🟡 P1 铁律 — 强烈建议
**铁律8: 先分解再行动** **铁律9: 先分解再行动**
- 修改超过3个文件、涉及多模块、数据库变更，必须先制定计划 - 修改超过3个文件、涉及多模块、数据库变更，必须先制定计划
**铁律9: 验证后信** **铁律10: 验证后信**
- 每次修改后必须验证编译通过，不信记忆 - 每次修改后必须验证编译通过，不信记忆
- 重新编译命令：`mvn clean compile -DskipTests`
**铁律10: 文档统一管理** **铁律11: 文档统一管理**
- 所有文档存储在 `MD/` 目录 - 所有文档存储在 `MD/` 目录
- 文件名：大写英文+下划线（如 `BACKEND_CHECKLIST.md`） - 文件名：大写英文+下划线（如 `BACKEND_CHECKLIST.md`）
- 文档头部必须包含元数据块（文档类型、版本、日期） - 文档头部必须包含元数据块（文档类型、版本、日期）
--- ---
## 三、全链路 6 环分析 ## 三、Karpathy 编码准则
> ⚠️ **涉及数据库字段的 Bug / 需求，必须走完整链路，不得"就事论事"。** > 减少 LLM 常见编码错误。偏向谨慎而非速度。
### 3.1 先想再写
- 明确陈述假设，不确定就问
- 多种解读时都列出来，不要默默选一种
- 有更简单的方案就说出来，该推回就推回
- 不清楚的地方停下来，说清楚哪里不清楚
### 3.2 简洁优先
- 不做没要求的功能，不做一次性代码的抽象
- 不加没要求的"灵活性"和"可配置性"
- 200 行能 50 行搞定就重写
- 自问："高级工程师会不会觉得这过度设计？"
### 3.3 精准修改
- 只改必须改的，不"顺手改进"相邻代码
- 匹配现有代码风格，即使你有不同的偏好
- 每行改动都能追溯到用户的请求
- 只清理你自己改动产生的无用代码
### 3.4 目标驱动
- 把任务转化为可验证目标
- 多步任务声明计划：`[步骤] → 验证: [检查]`
- 强验收标准让 Agent 能独立循环，弱标准需要持续澄清
---
## 四、全链路 6 环分析
> ⚠️ **涉及数据库字段的 Bug / 需求，必须走完整链路。**
``` ```
前端/页面 → Controller → Service → Mapper → DB/SQL → 关联模块 前端/页面 → Controller → Service → Mapper → DB/SQL → 关联模块
①录入 ②验证 ③业务 ④持久化 ⑤存储 ⑥联动 ①录入 ②验证 ③业务 ④持久化 ⑤存储 ⑥联动
``` ```
### 每一环必须确认
| 环 | 检查内容 | | 环 | 检查内容 |
|----|---------| |----|---------|
| ① 录入 | 前端有无输入入口（弹窗、表格行编辑、表单） | | ① 录入 | 前端有无输入入口（弹窗、表格行编辑、表单） |
@@ -117,104 +137,113 @@ instructions: |
| ⑤ 存储 | 数据库表结构、索引、NOT NULL 约束 | | ⑤ 存储 | 数据库表结构、索引、NOT NULL 约束 |
| ⑥ 联动 | 上游（医嘱→护士站）、下游（打印、计费、报表）是否同步 | | ⑥ 联动 | 上游（医嘱→护士站）、下游（打印、计费、报表）是否同步 |
### 全链路验证顺序 **修复后的验证顺序**：
1. 数据库：确认状态值已正确写入
修复涉及状态流转的问题后，必须按以下顺序验证： 2. 后端接口：确认返回的状态映射正确
1. **数据库**：确认状态值已正确写入 3. 前端显示：确认页面显示正确状态文本
2. **后端接口**：确认返回的状态映射正确 4. 前端交互：确认按钮/操作基于正确状态启用/禁用
3. **前端显示**：确认页面显示正确状态文本 5. 统计数据：确认池/报表统计包含新状态
4. **前端交互**：确认按钮/操作基于正确状态启用/禁用
5. **统计数据**：确认池/报表统计包含新状态
### 常见陷阱
- ❌ 只修了「主入口」的保存逻辑，忘了「批量保存」「签发保存」等其他入口
- ❌ 前端加了输入框，后端 Service 没传字段
- ❌ Mapper XML 是 UNION ALL 查询，只改了其中一个子查询
- ❌ DTO 层级继承关系没检查
- ❌ 只测了新增，没测编辑已有数据的回显和修改再保存
--- ---
## 四、Harness Engineering 方法论 ## 五、Harness Engineering 方法论
> Harness = 约束 + 反馈 + 控制平面 + 持久执行 > Harness = 约束 + 反馈 + 控制平面 + 持久执行
### 4.1 四层约束金字塔 ### 5.1 四层约束金字塔
| 层级 | 内容 | 落地方式 | | 层级 | 内容 | 落地方式 |
|------|------|---------| |------|------|---------|
| **L1 架构约束** | 接口合约、包结构、命名规范、禁止模式 | 本文件铁律、AGENTS.md | | **L1 架构约束** | 接口合约、包结构、命名规范、禁止模式 | 本文件铁律 |
| **L2 代码质量** | 圈复杂度、代码风格、类型提示 | 编译门禁 + ESLint | | **L2 代码质量** | 圈复杂度、代码风格、类型提示 | 编译门禁 + ESLint |
| **L3 安全约束** | 敏感信息检测、权限检查、输入验证 | 配置不可硬编码 | | **L3 安全约束** | 敏感信息检测、权限检查、输入验证 | 配置不可硬编码 |
| **L4 业务规则** | 领域逻辑、数据一致性、事务边界 | 全链路 6 环验证 | | **L4 业务规则** | 领域逻辑、数据一致性、事务边界 | 全链路 6 环验证 |
**约束优先级**：安全 > 架构 > 质量 > 业务 **约束设计原则**：
- **可验证**：每条约束必须能被自动化检查（"覆盖率>90%"✅ "质量要高"❌）
- **无歧义**："每函数不超过50行"✅ "函数不要太长"❌
- **优先级**：安全(1) > 架构(2) > 业务(3) > 质量(4) > 性能(5)
- **渐进增强**：L1编译通过 → L2+命名规范 → L3+测试覆盖 → L4+安全扫描
### 4.2 三层反馈系统 ### 5.2 三层反馈系统
| 层级 | 速度 | 覆盖范围 | 失败处理 | | 层级 | 速度 | 覆盖范围 | 失败处理 |
|------|------|---------|---------| |------|------|---------|---------|
| **L1 编译检查** | <30 秒 | 语法、类型、签名 | 立即阻断，自行修复 | | **L1 编译检查** | <30秒 | 语法、类型、签名 | 立即阻断，自行修复 |
| **L2 数据流验证** | <5 分钟 | 全链路字段、Mapper XML、DTO | 修复后上报 | | **L2 数据流验证** | <5分钟 | 全链路字段、Mapper XML、DTO | 修复后上报 |
| **L3 人工审查** | 10-30 分钟 | 架构、设计、业务正确性 | 驳回 / 指导 / 批准 | | **L3 人工审查** | 10-30分钟 | 架构、设计、业务正确性 | 驳回/指导/批准 |
**反馈设计铁律**： **反馈铁律**：
- 反馈必须可行动（指出：文件 + 行号 + 错误类型 + 修复方向） - 反馈必须可行动（文件 + 行号 + 错误类型 + 修复方向）
- 反馈越及时越好（L1 即时 → L2 分钟 → L3 小时）
- 失败后先回滚到最近检查点，再重试 - 失败后先回滚到最近检查点，再重试
- 持续失败3次 → 上报人类
### 4.3 控制平面（Agent 协调） ### 5.3 控制平面
``` ```
┌─────────────────────────────────────────────┐ 战略层（人类） → 设定目标、审批决策、异常升级
│ 战略层（人类主导） │ 战术层（Agent） → 任务分解、update_plan、依赖协调、检查点保存
│ ├── 设定目标、审批关键决策 │ 执行层（Agent） → 代码生成、测试执行、错误恢复、幂等重试
│ └── 异常升级处理 │
├─────────────────────────────────────────────┤
│ 战术层（Control Plane） │
│ ├── 任务分解 + update_plan │
│ ├── 依赖协调 + 资源分配 │
│ └── 检查点保存 + 恢复 │
├─────────────────────────────────────────────┤
│ 执行层（Agent 自主） │
│ ├── 代码生成、测试执行 │
│ └── 错误恢复 + 幂等重试 │
└─────────────────────────────────────────────┘
``` ```
### 4.4 持久执行 ### 5.4 持久执行
- 每个关键步骤保存检查点（`update_plan` 进度） - 每个关键步骤保存检查点（`update_plan` 进度）
- 失败后从最新检查点恢复，不从头开始 - 失败后从最新检查点恢复，不从头开始
- 幂等设计：同一操作重复执行结果一致 - 幂等设计：同一操作重复执行结果一致
- **三层状态管理**：系统层(工作流ID/超时/重试) → 执行层(当前活动/进度) → 业务层(已完成工作/中间产物)
--- ---
## 五、质量门禁（5 级） ## 六、五层质量门禁
| 级别 | 门禁 | 通过标准 | | 门禁 | 时间 | 范围 | 失败处理 |
|------|------|---------| |------|------|------|---------|
| **L1** | 编译通过 | `mvn clean compile` + `npm run build:dev` 无 ERROR | | **L1 编译检查** | <30秒 | 语法、类型、导入 | Agent 自行修复 |
| **L2** | 测试通过 | 单元测试 + 接口测试全部通过 | | **L2 静态分析** | <2分钟 | 代码风格、复杂度、安全 | Agent 修复 |
| **L3** | DB 审查 | Flyway 脚本规范、SQL 安全、索引合理 | | **L3 单元测试** | <5分钟 | 功能正确性、边界条件 | 自动修复或上报 |
| **L4** | 验收通过 | 核心功能流程完整验证、全链路检查 | | **L4 集成测试** | <15分钟 | 模块间交互、数据流 | 上报人工 |
| **L5** | 归档完成 | Git commit + 文档更新 + 代码推送 | | **L5 生产验证** | 持续 | 监控、告警、性能 | 自动回滚 |
### 提交铁律 **提交铁律**：L1-L2 必须通过才能 commit，L3（如有DB变更）必须通过才能 push
- L1-L2 必须通过才能 commit
- L3（如有DB变更）必须通过才能 push
- L4-L5 发布前必须完成
--- ---
## 六、后端开发规范 ## 七、系统化调试（Systematic Debugging）
> **铁律：没有根因调查，不能提出修复方案。**
### 四阶段流程
**阶段1：根因调查**（修复前必须完成）
1. 仔细阅读错误信息（堆栈、行号、错误码）
2. 稳定复现（能否可靠触发？步骤？每次？）
3. 检查最近变更（git diff、新依赖、配置变更）
4. 多组件系统：在每个组件边界加诊断日志，定位哪一层断裂
5. 追踪数据流：坏值从哪里来？谁调用的？一直追溯到源头
**阶段2：模式分析**
- 找到同代码库中类似的正常工作代码
- 逐项对比差异
- 理解依赖关系
**阶段3：假设与测试**
- 形成单一假设："我认为X是根因，因为Y"
- 做最小改动测试
- 有效 → 阶段4；无效 → 新假设
**阶段4：实施**
- 创建失败测试用例
- 修复根因（不是症状）
- 验证修复
---
## 八、后端开发规范
### 分层架构 ### 分层架构
``` ```
Controller → AppService → Service → Mapper → Entity Controller → AppService → Service → Mapper → Entity
接收请求 编排业务 单表CRUD 数据访问 实体定义
``` ```
### 命名规范 ### 命名规范
@@ -238,110 +267,125 @@ instructions: |
com.healthlink.his.common.enums com.healthlink.his.common.enums
``` ```
### 统一返回格式
```java
AjaxResult.success(data) // 成功
AjaxResult.error("错误信息") // 失败
getDataTable(list) // 列表
```
### 关键约束 ### 关键约束
- 所有查询使用 `LambdaQueryWrapper`，禁止字符串拼接 SQL - 所有查询使用 `LambdaQueryWrapper`，禁止字符串拼接 SQL
- `@Transactional(rollbackFor = Exception.class)` 管理事务 - `@Transactional(rollbackFor = Exception.class)` 管理事务
- 所有接口标注 `@PreAuthorize` 权限控制 - 所有接口标注 `@PreAuthorize` 权限控制
- 患者敏感信息（身份证、手机号）在日志中脱敏 - 患者敏感信息在日志中脱敏
- **扩展功能不修改原有函数签名**，新建 Service/AppService - **扩展功能不修改原有函数签名**
- 涉及多表写操作的方法标注 `@Transactional`
- 事务方法未被同一类内方法直接调用（避免自调用失效）
--- ---
## 七、前端开发规范 ## 九、前端开发规范
### 技术栈 ### 技术栈
- Vue 3 + Vite + Element Plus + Pinia + Axios - Vue 3 + Vite + Element Plus + Pinia + Axios（基于 RuoYi-Vue3）
- 基于 RuoYi-Vue3 框架
### 目录结构 ### 目录结构
``` ```
src/api/{module}/ # API接口（kebab-case路径） src/api/{module}/ # API接口
src/views/{module}/ # 页面组件 src/views/{module}/ # 页面组件
src/store/modules/ # Pinia状态管理 src/store/modules/ # Pinia状态管理
src/components/ # 公共组件 src/components/ # 公共组件
``` ```
### API 路径规范
```javascript
// 统一前缀 /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` 指令
### 关键约束 ### 关键约束
- API前缀：`/healthlink-his/api/v1/`
- 路由懒加载：`() => import('@/views/xxx/index.vue')` - 路由懒加载：`() => import('@/views/xxx/index.vue')`
- 不使用 `v-html`（除非做 XSS 转义） - 页面使用 `<script setup>` 语法
- 不在前端硬编码密码、密钥 - 按钮权限使用 `v-hasPermi` 指令
- `onMounted` 中注册的事件在 `onUnmounted` 中移除 - `onMounted` 中注册的事件在 `onUnmounted` 中移除
--- ---
## 八、Agent 体系（智能体协作） ## 十、Agent 体系
### 角色定义 ### 角色与路由
| 代号 | 名称 | 角色 | 职责 | | 代号 | 名称 | 角色 | 路由关键词 |
|------|------|------|------| |------|------|------|-----------|
| liubei | 刘备 | 项目经理 | 总协调、任务分配、异常升级 | | liubei | 刘备 | 项目经理 | 协调、分派、异常升级 |
| zhugeliang | 诸葛亮 | 架构师 | 需求分析、方案设计、技术决策 | | zhugeliang | 诸葛亮 | 架构师 | 分析、路由、设计 |
| guanyu | 关羽 | 后端开发 | Java 后端修复、API 开发 | | guanyu | 关羽 | 后端开发 | java, api, spring, service, controller |
| zhaoyun | 赵云 | 前端开发 | Vue 前端修复、页面开发 | | zhaoyun | 赵云 | 前端开发 | vue, 界面, 显示, 弹窗, 按钮 |
| xunyu | 荀彧 | DBA | 数据库审查、SQL 优化、Flyway 脚本 | | xunyu | 荀彧 | DBA | 数据库, sql, 迁移, mapper xml |
| zhangfei | 张飞 | 测试 | Playwright 测试、接口测试、回归测试 | | zhangfei | 张飞 | 测试 | 测试, QA, 回归 |
| huatuo | 华佗 | 验收 | 功能验收、质量确认、发布检查 | | huatuo | 华佗 | 验收 | 需求验收、质量确认 |
| chenlin | 陈琳 | 文档 | 归档记录、文档更新、Git 提交 | | chenlin | 陈琳 | 文档 | 文档、归档、Git提交 |
### 协作流水线 ### 协作流水线
``` ```
刘备(协调) → 诸葛亮(分析) → {关羽|赵云}(修复) → 荀彧(DB审查) → 张飞(测试) → 华佗(验收) → 陈琳(归档) 刘备(协调) → 诸葛亮(分析路由) → {关羽|赵云}(修复) → 荀彧(DB审查) → 张飞(测试) → 华佗(验收) → 陈琳(归档)
```
### Bug 修复完整管线（BDT 方法论）
```
获取Bug → 设计测试用例 → 基线测试(应失败) → 全链路修复 → 回归测试(应通过) → 扩展测试(无回归) → 提交
``` ```
### Bug 状态管理铁律 ### Bug 状态管理铁律
- 人类提的 Bug：只加备注，不改状态，不改分配 - 人类提的 Bug：只加备注，不改状态，不改分配
- 智能体提的 Bug：可以改分配和加备注 - 智能体提的 Bug：可以改分配和加备注
- 已关闭/已解决的 Bug 不再处理 - 已关闭/已解决的 Bug 不再处理
### 修复流程铁律 ---
- 一次只修一个 Bug，不扩大范围 ## 十一、审查与审计
- 修复前必须读 AGENTS.md
- 修复后必须验证编译
- 涉及 SQL 必须先查真实数据库
### 测试流程铁律 ### 三层审查体系
- Playwright 必须 `--workers=1` 单线程 | 层级 | 内容 | 时机 |
- 超时 120 秒 |------|------|------|
- 最多重试 3 次 | **L1 自审** | Agent 对照约束逐条检查 | 每次提交前 |
- 测试结果写入禅道备注 | **L2 配对审查** | Agent 生成变更摘要，人类终审 | PR/提交时 |
| **L3 合规审查** | 审计追踪，记录所有 AI 操作 | 持续 |
### 归档流程铁律 ### L1 自审清单
```yaml
self_review:
- "所有修改能通过编译？"
- "遵守命名规范？"
- "测试覆盖达标？"
- "没有遗漏的 TODO / DEBUG？"
- "变更范围没超出任务边界？"
```
- 三重归档：Git + SQLite + Redis ### 评审评分维度
- SQLite 必须使用完整字段 | 维度 | 问题 |
- 禅道备注格式：`[📝 陈琳归档] Bug #xxx` |------|------|
| 正确性 | 行为是否符合目标功能？ |
| 验证 | 检查是否真的跑过并留下证据？ |
| 范围纪律 | 是否保持在选定功能范围内？ |
| 可靠性 | 结果能否在重启后继续工作？ |
| 可维护性 | 代码和文档是否清楚到可交接？ |
--- ---
## 九、开发流程 ## 十二、标准工作循环
```
开始会话
├→ 1. Init — 读 AGENTS.md + PROGRESS.md + git log
├→ 2. Select — 只选一个未完成功能
├→ 3. Implement — 一次只做一个，不扩大范围
├→ 4. Verify — 运行验证命令，有证据才标记完成
└→ 5. Cleanup — 更新进度 + clean-state-checklist + git commit
```
### 会话结束前必须运行 Clean State Checklist
```
□ 标准启动路径仍然可用
□ 标准验证路径仍然可运行
□ 当前进度已记录到进度日志
□ 无半成品步骤处于未记录状态
□ 下一轮会话无需人工修复即可继续
```
---
## 十三、开发流程
``` ```
收到任务 收到任务
@@ -365,60 +409,56 @@ instructions: |
--- ---
## 十、快速参考命令 ## 十四、快速参考命令
```bash ```bash
# === 后端 === # === 后端 ===
export JAVA_HOME=/opt/jdk-25 export JAVA_HOME=/opt/jdk-25
mvn clean compile -DskipTests # 编译 mvn clean compile -DskipTests # 编译
mvn install -DskipTests # 完整构建 mvn install -DskipTests # 构建
mvn test -pl healthlink-his-application -Dtest="XxxTest" -Dsurefire.failIfNoSpecifiedTests=false # 测试 mvn test -pl healthlink-his-application -Dtest="XxxTest" -Dsurefire.failIfNoSpecifiedTests=false
# === 前端 === # === 前端 ===
cd healthlink-his-ui cd healthlink-his-ui
npm run dev # 开发模式 npm run dev && npm run build:dev && npm run lint && npm run test:run
npm run build:dev # 构建
npm run lint # 代码检查
npm run test:run # 单元测试
# === Git === # === Git ===
git status # 查看变更 git status && git add -A && git commit -m "feat(module): desc" && git push origin develop
git add -A # 暂存所有
git commit -m "feat(module): description" # 提交
git push origin develop # 推送
``` ```
--- ---
## 十一、详细规范文档索引 ## 十五、详细规范文档索引
| 文档 | 路径 | 用途 | | 文档 | 路径 | 用途 |
|------|------|------| |------|------|------|
| 执行铁律 | `MD/specs/IRON_RULES.md` | 铁律完整版 | | 执行铁律 | `MD/specs/IRON_RULES.md` | 铁律完整版 |
| 后端规范 | `MD/specs/BACKEND_DEVELOPMENT_STANDARD.md` | 后端编码标准 | | 后端规范 | `MD/specs/BACKEND_DEVELOPMENT_STANDARD.md` | 后端编码标准 |
| 前端规范 | `MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md` | 前端编码标准 | | 前端规范 | `MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md` | 前端编码标准 |
| Harness方法论 | `MD/specs/HARNESS_ENGINEERING.md` | 完整Harness+Agent方法论 |
| 文档规范 | `MD/DOCUMENTATION_STANDARD.md` | 文档管理标准 | | 文档规范 | `MD/DOCUMENTATION_STANDARD.md` | 文档管理标准 |
| 后端清单 | `MD/specs/BACKEND_CHECKLIST.md` | 发布前检查 | | 后端清单 | `MD/specs/BACKEND_CHECKLIST.md` | 发布前检查 |
| 前端清单 | `MD/specs/FRONTEND_CHECKLIST.md` | 发布前检查 | | 前端清单 | `MD/specs/FRONTEND_CHECKLIST.md` | 发布前检查 |
| 三甲标准 | `MD/standards/GRADE3A_HIS_STANDARD.md` | 三甲医院达标标准 | | 三甲标准 | `MD/standards/GRADE3A_HIS_STANDARD.md` | 三甲医院达标标准 |
| Flyway指南 | `MD/guides/FLYWAY_USAGE_GUIDE.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: 签到设 BOOKED(1) 而非 CHECKED_IN(3)，前端映射缺失 → 必须走完整状态链路 |
| 盲删源文件 | Bug #574 | AI 看到编译错误直接删文件，没检查是否在 baseline → 必须先确认文件来源再操作 | | 盲删源文件 | AI 看到编译错误直接删文件，没检查 baseline → 必须先确认文件来源 |
| 修复方向偏差 | Bug #574 | 多次 fallback 改的是 OrderServiceImpl，完全没触及 TicketServiceImpl → 必须用 rg 搜索所有相关代码路径 | | 修复方向偏差 | 多次 fallback 改的是错误的 Service → 必须用 rg 搜索所有相关代码路径 |
| bug_reports 表缺少列 | 经验 | INSERT 会静默失败，必须检查表结构 | | bug_reports 缺列 | INSERT 静默失败 → 必须检查表结构 |
| 禅道 comment API | 经验 | API 不存在，必须用 resolve+activate workaround | | 禅道 comment API | API 不存在，用 resolve+activate workaround |
| SQLite WAL 并发 | 经验 | 多进程并发写需要 checkpoint | | SQLite WAL 并发 | 多进程并发写需要 checkpoint |
| UTF-8 切片 | 经验 | 多字节字符不能用 byte index 切片 | | UTF-8 切片 | 多字节字符不能用 byte index 切片 |
| 禅道图片附件 | 经验 | 必须 OCR 读取，不能直接解析 | | 上下文焦虑 | Agent 感觉上下文快满时会匆忙结束，跳过验证 → 注意 context 40% 阈值 |
| 过早宣告胜利 | 自评≠验证，分开"干活"和"检查" |
| 覆盖率幻觉 | 覆盖率达标但逻辑没测 → 引入变异测试 |
--- ---
> ⚠️ **警告**: 本文件是项目 AI 开发规范的唯一信源。各工具配置文件（AGENTS.md、.cursorrules 等）均通过 `bash scripts/sync-ai-rules.sh` 从本文件同步。修改规范请只修改本文件。 > ⚠️ 本文件是 AI 开发规范的唯一信源。各工具配置文件由 `bash scripts/sync-ai-rules.sh` 同步。

382
.clinerules
View File

@@ -6,7 +6,7 @@
# HealthLink-HIS — AI 开发规范（自动加载） # HealthLink-HIS — AI 开发规范（自动加载）
> 🤖 **本文件供所有 AI 编码工具自动读取**。无论使用 Claude Code、Cursor、Codex CLI、Copilot、Qwen、Cline 还是其他工具，进入本项目后必须遵守以下规范。 > 🤖 **本文件供所有 AI 编码工具自动读取**。进入本项目后必须遵守以下规范。
> >
> **模型决定上限，Harness 决定底线。** > **模型决定上限，Harness 决定底线。**
@@ -48,7 +48,6 @@
- 凡是新建表、新增字段，必须创建 Flyway 迁移脚本 - 凡是新建表、新增字段，必须创建 Flyway 迁移脚本
- 路径：`healthlink-his-domain/src/main/resources/db/migration/` - 路径：`healthlink-his-domain/src/main/resources/db/migration/`
- 命名：`V{版本号}__{描述}.sql`（双下划线） - 命名：`V{版本号}__{描述}.sql`（双下划线）
- 禁止直接在数据库执行 SQL 不走 Flyway
**铁律3: 测试通过后才提交** **铁律3: 测试通过后才提交**
- 编译 + 测试全部通过后才能 git commit - 编译 + 测试全部通过后才能 git commit
@@ -57,59 +56,80 @@
**铁律4: 前后端API路径对齐** **铁律4: 前后端API路径对齐**
- 后端前缀：`/healthlink-his/api/v1/` - 后端前缀：`/healthlink-his/api/v1/`
- 前端 `request.js` 的 baseURL 必须与后端匹配 - 前端 `request.js` 的 baseURL 必须与后端匹配
- 接口变更必须同步更新前后端代码
**铁律5: 状态值一致性（来自 Bug #574 教训）** **铁律5: 状态值一致性（Bug #574 教训）**
- 修改任何状态值前，必须先列出完整的状态流转链路 - 修改任何状态值前，必须先列出完整的状态流转链路
- 检查项： - 检查项：枚举定义 → Service 设置 → 查询映射 → 前端 STATUS_CLASS_MAP → 前端 v-if → 统计SQL
1. 枚举定义的值是否正确
2. Service 层设置的状态值是否与枚举一致
3. 查询/列表接口的状态映射是否覆盖所有枚举值
4. 前端 `STATUS_CLASS_MAP` 是否包含新状态
5. 前端过滤条件（如 `v-if`）是否兼容新状态
6. 池/统计表的聚合 SQL 是否包含新状态值
- 禁止：只改一端不检查其他端 - 禁止：只改一端不检查其他端
**铁律6: 禁止删除源文件（来自 Bug #574 教训）** **铁律6: 禁止删除源文件（Bug #574 教训）**
- 绝对禁止删除项目中已有的 Java/Vue/SQL 源文件 - 绝对禁止删除项目中已有的 Java/Vue/SQL 源文件
- 文件有编译错误 → 修复错误，不删除文件 - 编译错误 → 修复错误；重复文件 → 重构合并
- 文件是重复的 → 重构合并，不删除文件
- 文件是 AI 幻觉创建的 → 检查 git baseline 确认后再删除
- 唯一例外：明确由人类确认删除的文件 - 唯一例外：明确由人类确认删除的文件
**铁律7: 禁止修改已有公开方法签名** **铁律7: 禁止修改已有公开方法签名**
- 不能删除或重命名已有的 public 方法 - 不能删除/重命名已有的 public 方法，不能修改参数列表
- 不能修改已有方法的参数列表 - 需要新功能 → 添加重载方法；需要改行为 → 修改内部实现
- 需要新增功能时 → 添加新的重载方法
- 需要改行为时 → 修改方法内部实现，不改签名 **铁律8: 验证后才宣称完成（Verification Before Completion）**
- **没有跑过验证命令，就不能说"完成了""通过了""没问题"**
- 禁止使用"应该可以""大概没问题""看起来正确"
- 必须：运行命令 → 读取输出 → 确认结果 → 才能宣称
- 这是诚实原则，不是效率问题
### 🟡 P1 铁律 — 强烈建议 ### 🟡 P1 铁律 — 强烈建议
**铁律8: 先分解再行动** **铁律9: 先分解再行动**
- 修改超过3个文件、涉及多模块、数据库变更，必须先制定计划 - 修改超过3个文件、涉及多模块、数据库变更，必须先制定计划
**铁律9: 验证后信** **铁律10: 验证后信**
- 每次修改后必须验证编译通过，不信记忆 - 每次修改后必须验证编译通过，不信记忆
- 重新编译命令：`mvn clean compile -DskipTests`
**铁律10: 文档统一管理** **铁律11: 文档统一管理**
- 所有文档存储在 `MD/` 目录 - 所有文档存储在 `MD/` 目录
- 文件名：大写英文+下划线（如 `BACKEND_CHECKLIST.md`） - 文件名：大写英文+下划线（如 `BACKEND_CHECKLIST.md`）
- 文档头部必须包含元数据块（文档类型、版本、日期） - 文档头部必须包含元数据块（文档类型、版本、日期）
--- ---
## 三、全链路 6 环分析 ## 三、Karpathy 编码准则
> ⚠️ **涉及数据库字段的 Bug / 需求，必须走完整链路，不得"就事论事"。** > 减少 LLM 常见编码错误。偏向谨慎而非速度。
### 3.1 先想再写
- 明确陈述假设，不确定就问
- 多种解读时都列出来，不要默默选一种
- 有更简单的方案就说出来，该推回就推回
- 不清楚的地方停下来，说清楚哪里不清楚
### 3.2 简洁优先
- 不做没要求的功能，不做一次性代码的抽象
- 不加没要求的"灵活性"和"可配置性"
- 200 行能 50 行搞定就重写
- 自问："高级工程师会不会觉得这过度设计？"
### 3.3 精准修改
- 只改必须改的，不"顺手改进"相邻代码
- 匹配现有代码风格，即使你有不同的偏好
- 每行改动都能追溯到用户的请求
- 只清理你自己改动产生的无用代码
### 3.4 目标驱动
- 把任务转化为可验证目标
- 多步任务声明计划：`[步骤] → 验证: [检查]`
- 强验收标准让 Agent 能独立循环，弱标准需要持续澄清
---
## 四、全链路 6 环分析
> ⚠️ **涉及数据库字段的 Bug / 需求，必须走完整链路。**
``` ```
前端/页面 → Controller → Service → Mapper → DB/SQL → 关联模块 前端/页面 → Controller → Service → Mapper → DB/SQL → 关联模块
①录入 ②验证 ③业务 ④持久化 ⑤存储 ⑥联动 ①录入 ②验证 ③业务 ④持久化 ⑤存储 ⑥联动
``` ```
### 每一环必须确认
| 环 | 检查内容 | | 环 | 检查内容 |
|----|---------| |----|---------|
| ① 录入 | 前端有无输入入口（弹窗、表格行编辑、表单） | | ① 录入 | 前端有无输入入口（弹窗、表格行编辑、表单） |
@@ -119,104 +139,113 @@
| ⑤ 存储 | 数据库表结构、索引、NOT NULL 约束 | | ⑤ 存储 | 数据库表结构、索引、NOT NULL 约束 |
| ⑥ 联动 | 上游（医嘱→护士站）、下游（打印、计费、报表）是否同步 | | ⑥ 联动 | 上游（医嘱→护士站）、下游（打印、计费、报表）是否同步 |
### 全链路验证顺序 **修复后的验证顺序**：
1. 数据库：确认状态值已正确写入
修复涉及状态流转的问题后，必须按以下顺序验证： 2. 后端接口：确认返回的状态映射正确
1. **数据库**：确认状态值已正确写入 3. 前端显示：确认页面显示正确状态文本
2. **后端接口**：确认返回的状态映射正确 4. 前端交互：确认按钮/操作基于正确状态启用/禁用
3. **前端显示**：确认页面显示正确状态文本 5. 统计数据：确认池/报表统计包含新状态
4. **前端交互**：确认按钮/操作基于正确状态启用/禁用
5. **统计数据**：确认池/报表统计包含新状态
### 常见陷阱
- ❌ 只修了「主入口」的保存逻辑，忘了「批量保存」「签发保存」等其他入口
- ❌ 前端加了输入框，后端 Service 没传字段
- ❌ Mapper XML 是 UNION ALL 查询，只改了其中一个子查询
- ❌ DTO 层级继承关系没检查
- ❌ 只测了新增，没测编辑已有数据的回显和修改再保存
--- ---
## 四、Harness Engineering 方法论 ## 五、Harness Engineering 方法论
> Harness = 约束 + 反馈 + 控制平面 + 持久执行 > Harness = 约束 + 反馈 + 控制平面 + 持久执行
### 4.1 四层约束金字塔 ### 5.1 四层约束金字塔
| 层级 | 内容 | 落地方式 | | 层级 | 内容 | 落地方式 |
|------|------|---------| |------|------|---------|
| **L1 架构约束** | 接口合约、包结构、命名规范、禁止模式 | 本文件铁律、AGENTS.md | | **L1 架构约束** | 接口合约、包结构、命名规范、禁止模式 | 本文件铁律 |
| **L2 代码质量** | 圈复杂度、代码风格、类型提示 | 编译门禁 + ESLint | | **L2 代码质量** | 圈复杂度、代码风格、类型提示 | 编译门禁 + ESLint |
| **L3 安全约束** | 敏感信息检测、权限检查、输入验证 | 配置不可硬编码 | | **L3 安全约束** | 敏感信息检测、权限检查、输入验证 | 配置不可硬编码 |
| **L4 业务规则** | 领域逻辑、数据一致性、事务边界 | 全链路 6 环验证 | | **L4 业务规则** | 领域逻辑、数据一致性、事务边界 | 全链路 6 环验证 |
**约束优先级**：安全 > 架构 > 质量 > 业务 **约束设计原则**：
- **可验证**：每条约束必须能被自动化检查（"覆盖率>90%"✅ "质量要高"❌）
- **无歧义**："每函数不超过50行"✅ "函数不要太长"❌
- **优先级**：安全(1) > 架构(2) > 业务(3) > 质量(4) > 性能(5)
- **渐进增强**：L1编译通过 → L2+命名规范 → L3+测试覆盖 → L4+安全扫描
### 4.2 三层反馈系统 ### 5.2 三层反馈系统
| 层级 | 速度 | 覆盖范围 | 失败处理 | | 层级 | 速度 | 覆盖范围 | 失败处理 |
|------|------|---------|---------| |------|------|---------|---------|
| **L1 编译检查** | <30 秒 | 语法、类型、签名 | 立即阻断，自行修复 | | **L1 编译检查** | <30秒 | 语法、类型、签名 | 立即阻断，自行修复 |
| **L2 数据流验证** | <5 分钟 | 全链路字段、Mapper XML、DTO | 修复后上报 | | **L2 数据流验证** | <5分钟 | 全链路字段、Mapper XML、DTO | 修复后上报 |
| **L3 人工审查** | 10-30 分钟 | 架构、设计、业务正确性 | 驳回 / 指导 / 批准 | | **L3 人工审查** | 10-30分钟 | 架构、设计、业务正确性 | 驳回/指导/批准 |
**反馈设计铁律**： **反馈铁律**：
- 反馈必须可行动（指出：文件 + 行号 + 错误类型 + 修复方向） - 反馈必须可行动（文件 + 行号 + 错误类型 + 修复方向）
- 反馈越及时越好（L1 即时 → L2 分钟 → L3 小时）
- 失败后先回滚到最近检查点，再重试 - 失败后先回滚到最近检查点，再重试
- 持续失败3次 → 上报人类
### 4.3 控制平面（Agent 协调） ### 5.3 控制平面
``` ```
┌─────────────────────────────────────────────┐ 战略层（人类） → 设定目标、审批决策、异常升级
│ 战略层（人类主导） │ 战术层（Agent） → 任务分解、update_plan、依赖协调、检查点保存
│ ├── 设定目标、审批关键决策 │ 执行层（Agent） → 代码生成、测试执行、错误恢复、幂等重试
│ └── 异常升级处理 │
├─────────────────────────────────────────────┤
│ 战术层（Control Plane） │
│ ├── 任务分解 + update_plan │
│ ├── 依赖协调 + 资源分配 │
│ └── 检查点保存 + 恢复 │
├─────────────────────────────────────────────┤
│ 执行层（Agent 自主） │
│ ├── 代码生成、测试执行 │
│ └── 错误恢复 + 幂等重试 │
└─────────────────────────────────────────────┘
``` ```
### 4.4 持久执行 ### 5.4 持久执行
- 每个关键步骤保存检查点（`update_plan` 进度） - 每个关键步骤保存检查点（`update_plan` 进度）
- 失败后从最新检查点恢复，不从头开始 - 失败后从最新检查点恢复，不从头开始
- 幂等设计：同一操作重复执行结果一致 - 幂等设计：同一操作重复执行结果一致
- **三层状态管理**：系统层(工作流ID/超时/重试) → 执行层(当前活动/进度) → 业务层(已完成工作/中间产物)
--- ---
## 五、质量门禁（5 级） ## 六、五层质量门禁
| 级别 | 门禁 | 通过标准 | | 门禁 | 时间 | 范围 | 失败处理 |
|------|------|---------| |------|------|------|---------|
| **L1** | 编译通过 | `mvn clean compile` + `npm run build:dev` 无 ERROR | | **L1 编译检查** | <30秒 | 语法、类型、导入 | Agent 自行修复 |
| **L2** | 测试通过 | 单元测试 + 接口测试全部通过 | | **L2 静态分析** | <2分钟 | 代码风格、复杂度、安全 | Agent 修复 |
| **L3** | DB 审查 | Flyway 脚本规范、SQL 安全、索引合理 | | **L3 单元测试** | <5分钟 | 功能正确性、边界条件 | 自动修复或上报 |
| **L4** | 验收通过 | 核心功能流程完整验证、全链路检查 | | **L4 集成测试** | <15分钟 | 模块间交互、数据流 | 上报人工 |
| **L5** | 归档完成 | Git commit + 文档更新 + 代码推送 | | **L5 生产验证** | 持续 | 监控、告警、性能 | 自动回滚 |
### 提交铁律 **提交铁律**：L1-L2 必须通过才能 commit，L3（如有DB变更）必须通过才能 push
- L1-L2 必须通过才能 commit
- L3（如有DB变更）必须通过才能 push
- L4-L5 发布前必须完成
--- ---
## 六、后端开发规范 ## 七、系统化调试（Systematic Debugging）
> **铁律：没有根因调查，不能提出修复方案。**
### 四阶段流程
**阶段1：根因调查**（修复前必须完成）
1. 仔细阅读错误信息（堆栈、行号、错误码）
2. 稳定复现（能否可靠触发？步骤？每次？）
3. 检查最近变更（git diff、新依赖、配置变更）
4. 多组件系统：在每个组件边界加诊断日志，定位哪一层断裂
5. 追踪数据流：坏值从哪里来？谁调用的？一直追溯到源头
**阶段2：模式分析**
- 找到同代码库中类似的正常工作代码
- 逐项对比差异
- 理解依赖关系
**阶段3：假设与测试**
- 形成单一假设："我认为X是根因，因为Y"
- 做最小改动测试
- 有效 → 阶段4；无效 → 新假设
**阶段4：实施**
- 创建失败测试用例
- 修复根因（不是症状）
- 验证修复
---
## 八、后端开发规范
### 分层架构 ### 分层架构
``` ```
Controller → AppService → Service → Mapper → Entity Controller → AppService → Service → Mapper → Entity
接收请求 编排业务 单表CRUD 数据访问 实体定义
``` ```
### 命名规范 ### 命名规范
@@ -240,110 +269,125 @@ com.healthlink.his.domain.{module}
com.healthlink.his.common.enums com.healthlink.his.common.enums
``` ```
### 统一返回格式
```java
AjaxResult.success(data) // 成功
AjaxResult.error("错误信息") // 失败
getDataTable(list) // 列表
```
### 关键约束 ### 关键约束
- 所有查询使用 `LambdaQueryWrapper`，禁止字符串拼接 SQL - 所有查询使用 `LambdaQueryWrapper`，禁止字符串拼接 SQL
- `@Transactional(rollbackFor = Exception.class)` 管理事务 - `@Transactional(rollbackFor = Exception.class)` 管理事务
- 所有接口标注 `@PreAuthorize` 权限控制 - 所有接口标注 `@PreAuthorize` 权限控制
- 患者敏感信息（身份证、手机号）在日志中脱敏 - 患者敏感信息在日志中脱敏
- **扩展功能不修改原有函数签名**，新建 Service/AppService - **扩展功能不修改原有函数签名**
- 涉及多表写操作的方法标注 `@Transactional`
- 事务方法未被同一类内方法直接调用（避免自调用失效）
--- ---
## 七、前端开发规范 ## 九、前端开发规范
### 技术栈 ### 技术栈
- Vue 3 + Vite + Element Plus + Pinia + Axios - Vue 3 + Vite + Element Plus + Pinia + Axios（基于 RuoYi-Vue3）
- 基于 RuoYi-Vue3 框架
### 目录结构 ### 目录结构
``` ```
src/api/{module}/ # API接口（kebab-case路径） src/api/{module}/ # API接口
src/views/{module}/ # 页面组件 src/views/{module}/ # 页面组件
src/store/modules/ # Pinia状态管理 src/store/modules/ # Pinia状态管理
src/components/ # 公共组件 src/components/ # 公共组件
``` ```
### API 路径规范
```javascript
// 统一前缀 /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` 指令
### 关键约束 ### 关键约束
- API前缀：`/healthlink-his/api/v1/`
- 路由懒加载：`() => import('@/views/xxx/index.vue')` - 路由懒加载：`() => import('@/views/xxx/index.vue')`
- 不使用 `v-html`（除非做 XSS 转义） - 页面使用 `<script setup>` 语法
- 不在前端硬编码密码、密钥 - 按钮权限使用 `v-hasPermi` 指令
- `onMounted` 中注册的事件在 `onUnmounted` 中移除 - `onMounted` 中注册的事件在 `onUnmounted` 中移除
--- ---
## 八、Agent 体系（智能体协作） ## 十、Agent 体系
### 角色定义 ### 角色与路由
| 代号 | 名称 | 角色 | 职责 | | 代号 | 名称 | 角色 | 路由关键词 |
|------|------|------|------| |------|------|------|-----------|
| liubei | 刘备 | 项目经理 | 总协调、任务分配、异常升级 | | liubei | 刘备 | 项目经理 | 协调、分派、异常升级 |
| zhugeliang | 诸葛亮 | 架构师 | 需求分析、方案设计、技术决策 | | zhugeliang | 诸葛亮 | 架构师 | 分析、路由、设计 |
| guanyu | 关羽 | 后端开发 | Java 后端修复、API 开发 | | guanyu | 关羽 | 后端开发 | java, api, spring, service, controller |
| zhaoyun | 赵云 | 前端开发 | Vue 前端修复、页面开发 | | zhaoyun | 赵云 | 前端开发 | vue, 界面, 显示, 弹窗, 按钮 |
| xunyu | 荀彧 | DBA | 数据库审查、SQL 优化、Flyway 脚本 | | xunyu | 荀彧 | DBA | 数据库, sql, 迁移, mapper xml |
| zhangfei | 张飞 | 测试 | Playwright 测试、接口测试、回归测试 | | zhangfei | 张飞 | 测试 | 测试, QA, 回归 |
| huatuo | 华佗 | 验收 | 功能验收、质量确认、发布检查 | | huatuo | 华佗 | 验收 | 需求验收、质量确认 |
| chenlin | 陈琳 | 文档 | 归档记录、文档更新、Git 提交 | | chenlin | 陈琳 | 文档 | 文档、归档、Git提交 |
### 协作流水线 ### 协作流水线
``` ```
刘备(协调) → 诸葛亮(分析) → {关羽|赵云}(修复) → 荀彧(DB审查) → 张飞(测试) → 华佗(验收) → 陈琳(归档) 刘备(协调) → 诸葛亮(分析路由) → {关羽|赵云}(修复) → 荀彧(DB审查) → 张飞(测试) → 华佗(验收) → 陈琳(归档)
```
### Bug 修复完整管线（BDT 方法论）
```
获取Bug → 设计测试用例 → 基线测试(应失败) → 全链路修复 → 回归测试(应通过) → 扩展测试(无回归) → 提交
``` ```
### Bug 状态管理铁律 ### Bug 状态管理铁律
- 人类提的 Bug：只加备注，不改状态，不改分配 - 人类提的 Bug：只加备注，不改状态，不改分配
- 智能体提的 Bug：可以改分配和加备注 - 智能体提的 Bug：可以改分配和加备注
- 已关闭/已解决的 Bug 不再处理 - 已关闭/已解决的 Bug 不再处理
### 修复流程铁律 ---
- 一次只修一个 Bug，不扩大范围 ## 十一、审查与审计
- 修复前必须读 AGENTS.md
- 修复后必须验证编译
- 涉及 SQL 必须先查真实数据库
### 测试流程铁律 ### 三层审查体系
- Playwright 必须 `--workers=1` 单线程 | 层级 | 内容 | 时机 |
- 超时 120 秒 |------|------|------|
- 最多重试 3 次 | **L1 自审** | Agent 对照约束逐条检查 | 每次提交前 |
- 测试结果写入禅道备注 | **L2 配对审查** | Agent 生成变更摘要，人类终审 | PR/提交时 |
| **L3 合规审查** | 审计追踪，记录所有 AI 操作 | 持续 |
### 归档流程铁律 ### L1 自审清单
```yaml
self_review:
- "所有修改能通过编译？"
- "遵守命名规范？"
- "测试覆盖达标？"
- "没有遗漏的 TODO / DEBUG？"
- "变更范围没超出任务边界？"
```
- 三重归档：Git + SQLite + Redis ### 评审评分维度
- SQLite 必须使用完整字段 | 维度 | 问题 |
- 禅道备注格式：`[📝 陈琳归档] Bug #xxx` |------|------|
| 正确性 | 行为是否符合目标功能？ |
| 验证 | 检查是否真的跑过并留下证据？ |
| 范围纪律 | 是否保持在选定功能范围内？ |
| 可靠性 | 结果能否在重启后继续工作？ |
| 可维护性 | 代码和文档是否清楚到可交接？ |
--- ---
## 九、开发流程 ## 十二、标准工作循环
```
开始会话
├→ 1. Init — 读 AGENTS.md + PROGRESS.md + git log
├→ 2. Select — 只选一个未完成功能
├→ 3. Implement — 一次只做一个，不扩大范围
├→ 4. Verify — 运行验证命令，有证据才标记完成
└→ 5. Cleanup — 更新进度 + clean-state-checklist + git commit
```
### 会话结束前必须运行 Clean State Checklist
```
□ 标准启动路径仍然可用
□ 标准验证路径仍然可运行
□ 当前进度已记录到进度日志
□ 无半成品步骤处于未记录状态
□ 下一轮会话无需人工修复即可继续
```
---
## 十三、开发流程
``` ```
收到任务 收到任务
@@ -367,64 +411,60 @@ scope: 模块名(如 registration, billing, pharmacy)
--- ---
## 十、快速参考命令 ## 十四、快速参考命令
```bash ```bash
# === 后端 === # === 后端 ===
export JAVA_HOME=/opt/jdk-25 export JAVA_HOME=/opt/jdk-25
mvn clean compile -DskipTests # 编译 mvn clean compile -DskipTests # 编译
mvn install -DskipTests # 完整构建 mvn install -DskipTests # 构建
mvn test -pl healthlink-his-application -Dtest="XxxTest" -Dsurefire.failIfNoSpecifiedTests=false # 测试 mvn test -pl healthlink-his-application -Dtest="XxxTest" -Dsurefire.failIfNoSpecifiedTests=false
# === 前端 === # === 前端 ===
cd healthlink-his-ui cd healthlink-his-ui
npm run dev # 开发模式 npm run dev && npm run build:dev && npm run lint && npm run test:run
npm run build:dev # 构建
npm run lint # 代码检查
npm run test:run # 单元测试
# === Git === # === Git ===
git status # 查看变更 git status && git add -A && git commit -m "feat(module): desc" && git push origin develop
git add -A # 暂存所有
git commit -m "feat(module): description" # 提交
git push origin develop # 推送
``` ```
--- ---
## 十一、详细规范文档索引 ## 十五、详细规范文档索引
| 文档 | 路径 | 用途 | | 文档 | 路径 | 用途 |
|------|------|------| |------|------|------|
| 执行铁律 | `MD/specs/IRON_RULES.md` | 铁律完整版 | | 执行铁律 | `MD/specs/IRON_RULES.md` | 铁律完整版 |
| 后端规范 | `MD/specs/BACKEND_DEVELOPMENT_STANDARD.md` | 后端编码标准 | | 后端规范 | `MD/specs/BACKEND_DEVELOPMENT_STANDARD.md` | 后端编码标准 |
| 前端规范 | `MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md` | 前端编码标准 | | 前端规范 | `MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md` | 前端编码标准 |
| Harness方法论 | `MD/specs/HARNESS_ENGINEERING.md` | 完整Harness+Agent方法论 |
| 文档规范 | `MD/DOCUMENTATION_STANDARD.md` | 文档管理标准 | | 文档规范 | `MD/DOCUMENTATION_STANDARD.md` | 文档管理标准 |
| 后端清单 | `MD/specs/BACKEND_CHECKLIST.md` | 发布前检查 | | 后端清单 | `MD/specs/BACKEND_CHECKLIST.md` | 发布前检查 |
| 前端清单 | `MD/specs/FRONTEND_CHECKLIST.md` | 发布前检查 | | 前端清单 | `MD/specs/FRONTEND_CHECKLIST.md` | 发布前检查 |
| 三甲标准 | `MD/standards/GRADE3A_HIS_STANDARD.md` | 三甲医院达标标准 | | 三甲标准 | `MD/standards/GRADE3A_HIS_STANDARD.md` | 三甲医院达标标准 |
| Flyway指南 | `MD/guides/FLYWAY_USAGE_GUIDE.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: 签到设 BOOKED(1) 而非 CHECKED_IN(3)，前端映射缺失 → 必须走完整状态链路 |
| 盲删源文件 | Bug #574 | AI 看到编译错误直接删文件，没检查是否在 baseline → 必须先确认文件来源再操作 | | 盲删源文件 | AI 看到编译错误直接删文件，没检查 baseline → 必须先确认文件来源 |
| 修复方向偏差 | Bug #574 | 多次 fallback 改的是 OrderServiceImpl，完全没触及 TicketServiceImpl → 必须用 rg 搜索所有相关代码路径 | | 修复方向偏差 | 多次 fallback 改的是错误的 Service → 必须用 rg 搜索所有相关代码路径 |
| bug_reports 表缺少列 | 经验 | INSERT 会静默失败，必须检查表结构 | | bug_reports 缺列 | INSERT 静默失败 → 必须检查表结构 |
| 禅道 comment API | 经验 | API 不存在，必须用 resolve+activate workaround | | 禅道 comment API | API 不存在，用 resolve+activate workaround |
| SQLite WAL 并发 | 经验 | 多进程并发写需要 checkpoint | | SQLite WAL 并发 | 多进程并发写需要 checkpoint |
| UTF-8 切片 | 经验 | 多字节字符不能用 byte index 切片 | | UTF-8 切片 | 多字节字符不能用 byte index 切片 |
| 禅道图片附件 | 经验 | 必须 OCR 读取，不能直接解析 | | 上下文焦虑 | Agent 感觉上下文快满时会匆忙结束，跳过验证 → 注意 context 40% 阈值 |
| 过早宣告胜利 | 自评≠验证，分开"干活"和"检查" |
| 覆盖率幻觉 | 覆盖率达标但逻辑没测 → 引入变异测试 |
--- ---
> ⚠️ **警告**: 本文件是项目 AI 开发规范的唯一信源。各工具配置文件（AGENTS.md、.cursorrules 等）均通过 `bash scripts/sync-ai-rules.sh` 从本文件同步。修改规范请只修改本文件。 > ⚠️ 本文件是 AI 开发规范的唯一信源。各工具配置文件由 `bash scripts/sync-ai-rules.sh` 同步。
--- ---
> 📅 最后同步: 2026-06-06 09:56 | 源文件: RULES.md | 重新同步: `bash scripts/sync-ai-rules.sh` > 📅 最后同步: 2026-06-06 10:01 | 源文件: RULES.md | 重新同步: `bash scripts/sync-ai-rules.sh`

382
.cursorrules
View File

@@ -6,7 +6,7 @@
# HealthLink-HIS — AI 开发规范（自动加载） # HealthLink-HIS — AI 开发规范（自动加载）
> 🤖 **本文件供所有 AI 编码工具自动读取**。无论使用 Claude Code、Cursor、Codex CLI、Copilot、Qwen、Cline 还是其他工具，进入本项目后必须遵守以下规范。 > 🤖 **本文件供所有 AI 编码工具自动读取**。进入本项目后必须遵守以下规范。
> >
> **模型决定上限，Harness 决定底线。** > **模型决定上限，Harness 决定底线。**
@@ -48,7 +48,6 @@
- 凡是新建表、新增字段，必须创建 Flyway 迁移脚本 - 凡是新建表、新增字段，必须创建 Flyway 迁移脚本
- 路径：`healthlink-his-domain/src/main/resources/db/migration/` - 路径：`healthlink-his-domain/src/main/resources/db/migration/`
- 命名：`V{版本号}__{描述}.sql`（双下划线） - 命名：`V{版本号}__{描述}.sql`（双下划线）
- 禁止直接在数据库执行 SQL 不走 Flyway
**铁律3: 测试通过后才提交** **铁律3: 测试通过后才提交**
- 编译 + 测试全部通过后才能 git commit - 编译 + 测试全部通过后才能 git commit
@@ -57,59 +56,80 @@
**铁律4: 前后端API路径对齐** **铁律4: 前后端API路径对齐**
- 后端前缀：`/healthlink-his/api/v1/` - 后端前缀：`/healthlink-his/api/v1/`
- 前端 `request.js` 的 baseURL 必须与后端匹配 - 前端 `request.js` 的 baseURL 必须与后端匹配
- 接口变更必须同步更新前后端代码
**铁律5: 状态值一致性（来自 Bug #574 教训）** **铁律5: 状态值一致性（Bug #574 教训）**
- 修改任何状态值前，必须先列出完整的状态流转链路 - 修改任何状态值前，必须先列出完整的状态流转链路
- 检查项： - 检查项：枚举定义 → Service 设置 → 查询映射 → 前端 STATUS_CLASS_MAP → 前端 v-if → 统计SQL
1. 枚举定义的值是否正确
2. Service 层设置的状态值是否与枚举一致
3. 查询/列表接口的状态映射是否覆盖所有枚举值
4. 前端 `STATUS_CLASS_MAP` 是否包含新状态
5. 前端过滤条件（如 `v-if`）是否兼容新状态
6. 池/统计表的聚合 SQL 是否包含新状态值
- 禁止：只改一端不检查其他端 - 禁止：只改一端不检查其他端
**铁律6: 禁止删除源文件（来自 Bug #574 教训）** **铁律6: 禁止删除源文件（Bug #574 教训）**
- 绝对禁止删除项目中已有的 Java/Vue/SQL 源文件 - 绝对禁止删除项目中已有的 Java/Vue/SQL 源文件
- 文件有编译错误 → 修复错误，不删除文件 - 编译错误 → 修复错误；重复文件 → 重构合并
- 文件是重复的 → 重构合并，不删除文件
- 文件是 AI 幻觉创建的 → 检查 git baseline 确认后再删除
- 唯一例外：明确由人类确认删除的文件 - 唯一例外：明确由人类确认删除的文件
**铁律7: 禁止修改已有公开方法签名** **铁律7: 禁止修改已有公开方法签名**
- 不能删除或重命名已有的 public 方法 - 不能删除/重命名已有的 public 方法，不能修改参数列表
- 不能修改已有方法的参数列表 - 需要新功能 → 添加重载方法；需要改行为 → 修改内部实现
- 需要新增功能时 → 添加新的重载方法
- 需要改行为时 → 修改方法内部实现，不改签名 **铁律8: 验证后才宣称完成（Verification Before Completion）**
- **没有跑过验证命令，就不能说"完成了""通过了""没问题"**
- 禁止使用"应该可以""大概没问题""看起来正确"
- 必须：运行命令 → 读取输出 → 确认结果 → 才能宣称
- 这是诚实原则，不是效率问题
### 🟡 P1 铁律 — 强烈建议 ### 🟡 P1 铁律 — 强烈建议
**铁律8: 先分解再行动** **铁律9: 先分解再行动**
- 修改超过3个文件、涉及多模块、数据库变更，必须先制定计划 - 修改超过3个文件、涉及多模块、数据库变更，必须先制定计划
**铁律9: 验证后信** **铁律10: 验证后信**
- 每次修改后必须验证编译通过，不信记忆 - 每次修改后必须验证编译通过，不信记忆
- 重新编译命令：`mvn clean compile -DskipTests`
**铁律10: 文档统一管理** **铁律11: 文档统一管理**
- 所有文档存储在 `MD/` 目录 - 所有文档存储在 `MD/` 目录
- 文件名：大写英文+下划线（如 `BACKEND_CHECKLIST.md`） - 文件名：大写英文+下划线（如 `BACKEND_CHECKLIST.md`）
- 文档头部必须包含元数据块（文档类型、版本、日期） - 文档头部必须包含元数据块（文档类型、版本、日期）
--- ---
## 三、全链路 6 环分析 ## 三、Karpathy 编码准则
> ⚠️ **涉及数据库字段的 Bug / 需求，必须走完整链路，不得"就事论事"。** > 减少 LLM 常见编码错误。偏向谨慎而非速度。
### 3.1 先想再写
- 明确陈述假设，不确定就问
- 多种解读时都列出来，不要默默选一种
- 有更简单的方案就说出来，该推回就推回
- 不清楚的地方停下来，说清楚哪里不清楚
### 3.2 简洁优先
- 不做没要求的功能，不做一次性代码的抽象
- 不加没要求的"灵活性"和"可配置性"
- 200 行能 50 行搞定就重写
- 自问："高级工程师会不会觉得这过度设计？"
### 3.3 精准修改
- 只改必须改的，不"顺手改进"相邻代码
- 匹配现有代码风格，即使你有不同的偏好
- 每行改动都能追溯到用户的请求
- 只清理你自己改动产生的无用代码
### 3.4 目标驱动
- 把任务转化为可验证目标
- 多步任务声明计划：`[步骤] → 验证: [检查]`
- 强验收标准让 Agent 能独立循环，弱标准需要持续澄清
---
## 四、全链路 6 环分析
> ⚠️ **涉及数据库字段的 Bug / 需求，必须走完整链路。**
``` ```
前端/页面 → Controller → Service → Mapper → DB/SQL → 关联模块 前端/页面 → Controller → Service → Mapper → DB/SQL → 关联模块
①录入 ②验证 ③业务 ④持久化 ⑤存储 ⑥联动 ①录入 ②验证 ③业务 ④持久化 ⑤存储 ⑥联动
``` ```
### 每一环必须确认
| 环 | 检查内容 | | 环 | 检查内容 |
|----|---------| |----|---------|
| ① 录入 | 前端有无输入入口（弹窗、表格行编辑、表单） | | ① 录入 | 前端有无输入入口（弹窗、表格行编辑、表单） |
@@ -119,104 +139,113 @@
| ⑤ 存储 | 数据库表结构、索引、NOT NULL 约束 | | ⑤ 存储 | 数据库表结构、索引、NOT NULL 约束 |
| ⑥ 联动 | 上游（医嘱→护士站）、下游（打印、计费、报表）是否同步 | | ⑥ 联动 | 上游（医嘱→护士站）、下游（打印、计费、报表）是否同步 |
### 全链路验证顺序 **修复后的验证顺序**：
1. 数据库：确认状态值已正确写入
修复涉及状态流转的问题后，必须按以下顺序验证： 2. 后端接口：确认返回的状态映射正确
1. **数据库**：确认状态值已正确写入 3. 前端显示：确认页面显示正确状态文本
2. **后端接口**：确认返回的状态映射正确 4. 前端交互：确认按钮/操作基于正确状态启用/禁用
3. **前端显示**：确认页面显示正确状态文本 5. 统计数据：确认池/报表统计包含新状态
4. **前端交互**：确认按钮/操作基于正确状态启用/禁用
5. **统计数据**：确认池/报表统计包含新状态
### 常见陷阱
- ❌ 只修了「主入口」的保存逻辑，忘了「批量保存」「签发保存」等其他入口
- ❌ 前端加了输入框，后端 Service 没传字段
- ❌ Mapper XML 是 UNION ALL 查询，只改了其中一个子查询
- ❌ DTO 层级继承关系没检查
- ❌ 只测了新增，没测编辑已有数据的回显和修改再保存
--- ---
## 四、Harness Engineering 方法论 ## 五、Harness Engineering 方法论
> Harness = 约束 + 反馈 + 控制平面 + 持久执行 > Harness = 约束 + 反馈 + 控制平面 + 持久执行
### 4.1 四层约束金字塔 ### 5.1 四层约束金字塔
| 层级 | 内容 | 落地方式 | | 层级 | 内容 | 落地方式 |
|------|------|---------| |------|------|---------|
| **L1 架构约束** | 接口合约、包结构、命名规范、禁止模式 | 本文件铁律、AGENTS.md | | **L1 架构约束** | 接口合约、包结构、命名规范、禁止模式 | 本文件铁律 |
| **L2 代码质量** | 圈复杂度、代码风格、类型提示 | 编译门禁 + ESLint | | **L2 代码质量** | 圈复杂度、代码风格、类型提示 | 编译门禁 + ESLint |
| **L3 安全约束** | 敏感信息检测、权限检查、输入验证 | 配置不可硬编码 | | **L3 安全约束** | 敏感信息检测、权限检查、输入验证 | 配置不可硬编码 |
| **L4 业务规则** | 领域逻辑、数据一致性、事务边界 | 全链路 6 环验证 | | **L4 业务规则** | 领域逻辑、数据一致性、事务边界 | 全链路 6 环验证 |
**约束优先级**：安全 > 架构 > 质量 > 业务 **约束设计原则**：
- **可验证**：每条约束必须能被自动化检查（"覆盖率>90%"✅ "质量要高"❌）
- **无歧义**："每函数不超过50行"✅ "函数不要太长"❌
- **优先级**：安全(1) > 架构(2) > 业务(3) > 质量(4) > 性能(5)
- **渐进增强**：L1编译通过 → L2+命名规范 → L3+测试覆盖 → L4+安全扫描
### 4.2 三层反馈系统 ### 5.2 三层反馈系统
| 层级 | 速度 | 覆盖范围 | 失败处理 | | 层级 | 速度 | 覆盖范围 | 失败处理 |
|------|------|---------|---------| |------|------|---------|---------|
| **L1 编译检查** | <30 秒 | 语法、类型、签名 | 立即阻断，自行修复 | | **L1 编译检查** | <30秒 | 语法、类型、签名 | 立即阻断，自行修复 |
| **L2 数据流验证** | <5 分钟 | 全链路字段、Mapper XML、DTO | 修复后上报 | | **L2 数据流验证** | <5分钟 | 全链路字段、Mapper XML、DTO | 修复后上报 |
| **L3 人工审查** | 10-30 分钟 | 架构、设计、业务正确性 | 驳回 / 指导 / 批准 | | **L3 人工审查** | 10-30分钟 | 架构、设计、业务正确性 | 驳回/指导/批准 |
**反馈设计铁律**： **反馈铁律**：
- 反馈必须可行动（指出：文件 + 行号 + 错误类型 + 修复方向） - 反馈必须可行动（文件 + 行号 + 错误类型 + 修复方向）
- 反馈越及时越好（L1 即时 → L2 分钟 → L3 小时）
- 失败后先回滚到最近检查点，再重试 - 失败后先回滚到最近检查点，再重试
- 持续失败3次 → 上报人类
### 4.3 控制平面（Agent 协调） ### 5.3 控制平面
``` ```
┌─────────────────────────────────────────────┐ 战略层（人类） → 设定目标、审批决策、异常升级
│ 战略层（人类主导） │ 战术层（Agent） → 任务分解、update_plan、依赖协调、检查点保存
│ ├── 设定目标、审批关键决策 │ 执行层（Agent） → 代码生成、测试执行、错误恢复、幂等重试
│ └── 异常升级处理 │
├─────────────────────────────────────────────┤
│ 战术层（Control Plane） │
│ ├── 任务分解 + update_plan │
│ ├── 依赖协调 + 资源分配 │
│ └── 检查点保存 + 恢复 │
├─────────────────────────────────────────────┤
│ 执行层（Agent 自主） │
│ ├── 代码生成、测试执行 │
│ └── 错误恢复 + 幂等重试 │
└─────────────────────────────────────────────┘
``` ```
### 4.4 持久执行 ### 5.4 持久执行
- 每个关键步骤保存检查点（`update_plan` 进度） - 每个关键步骤保存检查点（`update_plan` 进度）
- 失败后从最新检查点恢复，不从头开始 - 失败后从最新检查点恢复，不从头开始
- 幂等设计：同一操作重复执行结果一致 - 幂等设计：同一操作重复执行结果一致
- **三层状态管理**：系统层(工作流ID/超时/重试) → 执行层(当前活动/进度) → 业务层(已完成工作/中间产物)
--- ---
## 五、质量门禁（5 级） ## 六、五层质量门禁
| 级别 | 门禁 | 通过标准 | | 门禁 | 时间 | 范围 | 失败处理 |
|------|------|---------| |------|------|------|---------|
| **L1** | 编译通过 | `mvn clean compile` + `npm run build:dev` 无 ERROR | | **L1 编译检查** | <30秒 | 语法、类型、导入 | Agent 自行修复 |
| **L2** | 测试通过 | 单元测试 + 接口测试全部通过 | | **L2 静态分析** | <2分钟 | 代码风格、复杂度、安全 | Agent 修复 |
| **L3** | DB 审查 | Flyway 脚本规范、SQL 安全、索引合理 | | **L3 单元测试** | <5分钟 | 功能正确性、边界条件 | 自动修复或上报 |
| **L4** | 验收通过 | 核心功能流程完整验证、全链路检查 | | **L4 集成测试** | <15分钟 | 模块间交互、数据流 | 上报人工 |
| **L5** | 归档完成 | Git commit + 文档更新 + 代码推送 | | **L5 生产验证** | 持续 | 监控、告警、性能 | 自动回滚 |
### 提交铁律 **提交铁律**：L1-L2 必须通过才能 commit，L3（如有DB变更）必须通过才能 push
- L1-L2 必须通过才能 commit
- L3（如有DB变更）必须通过才能 push
- L4-L5 发布前必须完成
--- ---
## 六、后端开发规范 ## 七、系统化调试（Systematic Debugging）
> **铁律：没有根因调查，不能提出修复方案。**
### 四阶段流程
**阶段1：根因调查**（修复前必须完成）
1. 仔细阅读错误信息（堆栈、行号、错误码）
2. 稳定复现（能否可靠触发？步骤？每次？）
3. 检查最近变更（git diff、新依赖、配置变更）
4. 多组件系统：在每个组件边界加诊断日志，定位哪一层断裂
5. 追踪数据流：坏值从哪里来？谁调用的？一直追溯到源头
**阶段2：模式分析**
- 找到同代码库中类似的正常工作代码
- 逐项对比差异
- 理解依赖关系
**阶段3：假设与测试**
- 形成单一假设："我认为X是根因，因为Y"
- 做最小改动测试
- 有效 → 阶段4；无效 → 新假设
**阶段4：实施**
- 创建失败测试用例
- 修复根因（不是症状）
- 验证修复
---
## 八、后端开发规范
### 分层架构 ### 分层架构
``` ```
Controller → AppService → Service → Mapper → Entity Controller → AppService → Service → Mapper → Entity
接收请求 编排业务 单表CRUD 数据访问 实体定义
``` ```
### 命名规范 ### 命名规范
@@ -240,110 +269,125 @@ com.healthlink.his.domain.{module}
com.healthlink.his.common.enums com.healthlink.his.common.enums
``` ```
### 统一返回格式
```java
AjaxResult.success(data) // 成功
AjaxResult.error("错误信息") // 失败
getDataTable(list) // 列表
```
### 关键约束 ### 关键约束
- 所有查询使用 `LambdaQueryWrapper`，禁止字符串拼接 SQL - 所有查询使用 `LambdaQueryWrapper`，禁止字符串拼接 SQL
- `@Transactional(rollbackFor = Exception.class)` 管理事务 - `@Transactional(rollbackFor = Exception.class)` 管理事务
- 所有接口标注 `@PreAuthorize` 权限控制 - 所有接口标注 `@PreAuthorize` 权限控制
- 患者敏感信息（身份证、手机号）在日志中脱敏 - 患者敏感信息在日志中脱敏
- **扩展功能不修改原有函数签名**，新建 Service/AppService - **扩展功能不修改原有函数签名**
- 涉及多表写操作的方法标注 `@Transactional`
- 事务方法未被同一类内方法直接调用（避免自调用失效）
--- ---
## 七、前端开发规范 ## 九、前端开发规范
### 技术栈 ### 技术栈
- Vue 3 + Vite + Element Plus + Pinia + Axios - Vue 3 + Vite + Element Plus + Pinia + Axios（基于 RuoYi-Vue3）
- 基于 RuoYi-Vue3 框架
### 目录结构 ### 目录结构
``` ```
src/api/{module}/ # API接口（kebab-case路径） src/api/{module}/ # API接口
src/views/{module}/ # 页面组件 src/views/{module}/ # 页面组件
src/store/modules/ # Pinia状态管理 src/store/modules/ # Pinia状态管理
src/components/ # 公共组件 src/components/ # 公共组件
``` ```
### API 路径规范
```javascript
// 统一前缀 /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` 指令
### 关键约束 ### 关键约束
- API前缀：`/healthlink-his/api/v1/`
- 路由懒加载：`() => import('@/views/xxx/index.vue')` - 路由懒加载：`() => import('@/views/xxx/index.vue')`
- 不使用 `v-html`（除非做 XSS 转义） - 页面使用 `<script setup>` 语法
- 不在前端硬编码密码、密钥 - 按钮权限使用 `v-hasPermi` 指令
- `onMounted` 中注册的事件在 `onUnmounted` 中移除 - `onMounted` 中注册的事件在 `onUnmounted` 中移除
--- ---
## 八、Agent 体系（智能体协作） ## 十、Agent 体系
### 角色定义 ### 角色与路由
| 代号 | 名称 | 角色 | 职责 | | 代号 | 名称 | 角色 | 路由关键词 |
|------|------|------|------| |------|------|------|-----------|
| liubei | 刘备 | 项目经理 | 总协调、任务分配、异常升级 | | liubei | 刘备 | 项目经理 | 协调、分派、异常升级 |
| zhugeliang | 诸葛亮 | 架构师 | 需求分析、方案设计、技术决策 | | zhugeliang | 诸葛亮 | 架构师 | 分析、路由、设计 |
| guanyu | 关羽 | 后端开发 | Java 后端修复、API 开发 | | guanyu | 关羽 | 后端开发 | java, api, spring, service, controller |
| zhaoyun | 赵云 | 前端开发 | Vue 前端修复、页面开发 | | zhaoyun | 赵云 | 前端开发 | vue, 界面, 显示, 弹窗, 按钮 |
| xunyu | 荀彧 | DBA | 数据库审查、SQL 优化、Flyway 脚本 | | xunyu | 荀彧 | DBA | 数据库, sql, 迁移, mapper xml |
| zhangfei | 张飞 | 测试 | Playwright 测试、接口测试、回归测试 | | zhangfei | 张飞 | 测试 | 测试, QA, 回归 |
| huatuo | 华佗 | 验收 | 功能验收、质量确认、发布检查 | | huatuo | 华佗 | 验收 | 需求验收、质量确认 |
| chenlin | 陈琳 | 文档 | 归档记录、文档更新、Git 提交 | | chenlin | 陈琳 | 文档 | 文档、归档、Git提交 |
### 协作流水线 ### 协作流水线
``` ```
刘备(协调) → 诸葛亮(分析) → {关羽|赵云}(修复) → 荀彧(DB审查) → 张飞(测试) → 华佗(验收) → 陈琳(归档) 刘备(协调) → 诸葛亮(分析路由) → {关羽|赵云}(修复) → 荀彧(DB审查) → 张飞(测试) → 华佗(验收) → 陈琳(归档)
```
### Bug 修复完整管线（BDT 方法论）
```
获取Bug → 设计测试用例 → 基线测试(应失败) → 全链路修复 → 回归测试(应通过) → 扩展测试(无回归) → 提交
``` ```
### Bug 状态管理铁律 ### Bug 状态管理铁律
- 人类提的 Bug：只加备注，不改状态，不改分配 - 人类提的 Bug：只加备注，不改状态，不改分配
- 智能体提的 Bug：可以改分配和加备注 - 智能体提的 Bug：可以改分配和加备注
- 已关闭/已解决的 Bug 不再处理 - 已关闭/已解决的 Bug 不再处理
### 修复流程铁律 ---
- 一次只修一个 Bug，不扩大范围 ## 十一、审查与审计
- 修复前必须读 AGENTS.md
- 修复后必须验证编译
- 涉及 SQL 必须先查真实数据库
### 测试流程铁律 ### 三层审查体系
- Playwright 必须 `--workers=1` 单线程 | 层级 | 内容 | 时机 |
- 超时 120 秒 |------|------|------|
- 最多重试 3 次 | **L1 自审** | Agent 对照约束逐条检查 | 每次提交前 |
- 测试结果写入禅道备注 | **L2 配对审查** | Agent 生成变更摘要，人类终审 | PR/提交时 |
| **L3 合规审查** | 审计追踪，记录所有 AI 操作 | 持续 |
### 归档流程铁律 ### L1 自审清单
```yaml
self_review:
- "所有修改能通过编译？"
- "遵守命名规范？"
- "测试覆盖达标？"
- "没有遗漏的 TODO / DEBUG？"
- "变更范围没超出任务边界？"
```
- 三重归档：Git + SQLite + Redis ### 评审评分维度
- SQLite 必须使用完整字段 | 维度 | 问题 |
- 禅道备注格式：`[📝 陈琳归档] Bug #xxx` |------|------|
| 正确性 | 行为是否符合目标功能？ |
| 验证 | 检查是否真的跑过并留下证据？ |
| 范围纪律 | 是否保持在选定功能范围内？ |
| 可靠性 | 结果能否在重启后继续工作？ |
| 可维护性 | 代码和文档是否清楚到可交接？ |
--- ---
## 九、开发流程 ## 十二、标准工作循环
```
开始会话
├→ 1. Init — 读 AGENTS.md + PROGRESS.md + git log
├→ 2. Select — 只选一个未完成功能
├→ 3. Implement — 一次只做一个，不扩大范围
├→ 4. Verify — 运行验证命令，有证据才标记完成
└→ 5. Cleanup — 更新进度 + clean-state-checklist + git commit
```
### 会话结束前必须运行 Clean State Checklist
```
□ 标准启动路径仍然可用
□ 标准验证路径仍然可运行
□ 当前进度已记录到进度日志
□ 无半成品步骤处于未记录状态
□ 下一轮会话无需人工修复即可继续
```
---
## 十三、开发流程
``` ```
收到任务 收到任务
@@ -367,64 +411,60 @@ scope: 模块名(如 registration, billing, pharmacy)
--- ---
## 十、快速参考命令 ## 十四、快速参考命令
```bash ```bash
# === 后端 === # === 后端 ===
export JAVA_HOME=/opt/jdk-25 export JAVA_HOME=/opt/jdk-25
mvn clean compile -DskipTests # 编译 mvn clean compile -DskipTests # 编译
mvn install -DskipTests # 完整构建 mvn install -DskipTests # 构建
mvn test -pl healthlink-his-application -Dtest="XxxTest" -Dsurefire.failIfNoSpecifiedTests=false # 测试 mvn test -pl healthlink-his-application -Dtest="XxxTest" -Dsurefire.failIfNoSpecifiedTests=false
# === 前端 === # === 前端 ===
cd healthlink-his-ui cd healthlink-his-ui
npm run dev # 开发模式 npm run dev && npm run build:dev && npm run lint && npm run test:run
npm run build:dev # 构建
npm run lint # 代码检查
npm run test:run # 单元测试
# === Git === # === Git ===
git status # 查看变更 git status && git add -A && git commit -m "feat(module): desc" && git push origin develop
git add -A # 暂存所有
git commit -m "feat(module): description" # 提交
git push origin develop # 推送
``` ```
--- ---
## 十一、详细规范文档索引 ## 十五、详细规范文档索引
| 文档 | 路径 | 用途 | | 文档 | 路径 | 用途 |
|------|------|------| |------|------|------|
| 执行铁律 | `MD/specs/IRON_RULES.md` | 铁律完整版 | | 执行铁律 | `MD/specs/IRON_RULES.md` | 铁律完整版 |
| 后端规范 | `MD/specs/BACKEND_DEVELOPMENT_STANDARD.md` | 后端编码标准 | | 后端规范 | `MD/specs/BACKEND_DEVELOPMENT_STANDARD.md` | 后端编码标准 |
| 前端规范 | `MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md` | 前端编码标准 | | 前端规范 | `MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md` | 前端编码标准 |
| Harness方法论 | `MD/specs/HARNESS_ENGINEERING.md` | 完整Harness+Agent方法论 |
| 文档规范 | `MD/DOCUMENTATION_STANDARD.md` | 文档管理标准 | | 文档规范 | `MD/DOCUMENTATION_STANDARD.md` | 文档管理标准 |
| 后端清单 | `MD/specs/BACKEND_CHECKLIST.md` | 发布前检查 | | 后端清单 | `MD/specs/BACKEND_CHECKLIST.md` | 发布前检查 |
| 前端清单 | `MD/specs/FRONTEND_CHECKLIST.md` | 发布前检查 | | 前端清单 | `MD/specs/FRONTEND_CHECKLIST.md` | 发布前检查 |
| 三甲标准 | `MD/standards/GRADE3A_HIS_STANDARD.md` | 三甲医院达标标准 | | 三甲标准 | `MD/standards/GRADE3A_HIS_STANDARD.md` | 三甲医院达标标准 |
| Flyway指南 | `MD/guides/FLYWAY_USAGE_GUIDE.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: 签到设 BOOKED(1) 而非 CHECKED_IN(3)，前端映射缺失 → 必须走完整状态链路 |
| 盲删源文件 | Bug #574 | AI 看到编译错误直接删文件，没检查是否在 baseline → 必须先确认文件来源再操作 | | 盲删源文件 | AI 看到编译错误直接删文件，没检查 baseline → 必须先确认文件来源 |
| 修复方向偏差 | Bug #574 | 多次 fallback 改的是 OrderServiceImpl，完全没触及 TicketServiceImpl → 必须用 rg 搜索所有相关代码路径 | | 修复方向偏差 | 多次 fallback 改的是错误的 Service → 必须用 rg 搜索所有相关代码路径 |
| bug_reports 表缺少列 | 经验 | INSERT 会静默失败，必须检查表结构 | | bug_reports 缺列 | INSERT 静默失败 → 必须检查表结构 |
| 禅道 comment API | 经验 | API 不存在，必须用 resolve+activate workaround | | 禅道 comment API | API 不存在，用 resolve+activate workaround |
| SQLite WAL 并发 | 经验 | 多进程并发写需要 checkpoint | | SQLite WAL 并发 | 多进程并发写需要 checkpoint |
| UTF-8 切片 | 经验 | 多字节字符不能用 byte index 切片 | | UTF-8 切片 | 多字节字符不能用 byte index 切片 |
| 禅道图片附件 | 经验 | 必须 OCR 读取，不能直接解析 | | 上下文焦虑 | Agent 感觉上下文快满时会匆忙结束，跳过验证 → 注意 context 40% 阈值 |
| 过早宣告胜利 | 自评≠验证，分开"干活"和"检查" |
| 覆盖率幻觉 | 覆盖率达标但逻辑没测 → 引入变异测试 |
--- ---
> ⚠️ **警告**: 本文件是项目 AI 开发规范的唯一信源。各工具配置文件（AGENTS.md、.cursorrules 等）均通过 `bash scripts/sync-ai-rules.sh` 从本文件同步。修改规范请只修改本文件。 > ⚠️ 本文件是 AI 开发规范的唯一信源。各工具配置文件由 `bash scripts/sync-ai-rules.sh` 同步。
--- ---
> 📅 最后同步: 2026-06-06 09:56 | 源文件: RULES.md | 重新同步: `bash scripts/sync-ai-rules.sh` > 📅 最后同步: 2026-06-06 10:01 | 源文件: RULES.md | 重新同步: `bash scripts/sync-ai-rules.sh`

382
.github/copilot-instructions.md vendored
View File

@@ -6,7 +6,7 @@
# HealthLink-HIS — AI 开发规范（自动加载） # HealthLink-HIS — AI 开发规范（自动加载）
> 🤖 **本文件供所有 AI 编码工具自动读取**。无论使用 Claude Code、Cursor、Codex CLI、Copilot、Qwen、Cline 还是其他工具，进入本项目后必须遵守以下规范。 > 🤖 **本文件供所有 AI 编码工具自动读取**。进入本项目后必须遵守以下规范。
> >
> **模型决定上限，Harness 决定底线。** > **模型决定上限，Harness 决定底线。**
@@ -48,7 +48,6 @@
- 凡是新建表、新增字段，必须创建 Flyway 迁移脚本 - 凡是新建表、新增字段，必须创建 Flyway 迁移脚本
- 路径：`healthlink-his-domain/src/main/resources/db/migration/` - 路径：`healthlink-his-domain/src/main/resources/db/migration/`
- 命名：`V{版本号}__{描述}.sql`（双下划线） - 命名：`V{版本号}__{描述}.sql`（双下划线）
- 禁止直接在数据库执行 SQL 不走 Flyway
**铁律3: 测试通过后才提交** **铁律3: 测试通过后才提交**
- 编译 + 测试全部通过后才能 git commit - 编译 + 测试全部通过后才能 git commit
@@ -57,59 +56,80 @@
**铁律4: 前后端API路径对齐** **铁律4: 前后端API路径对齐**
- 后端前缀：`/healthlink-his/api/v1/` - 后端前缀：`/healthlink-his/api/v1/`
- 前端 `request.js` 的 baseURL 必须与后端匹配 - 前端 `request.js` 的 baseURL 必须与后端匹配
- 接口变更必须同步更新前后端代码
**铁律5: 状态值一致性（来自 Bug #574 教训）** **铁律5: 状态值一致性（Bug #574 教训）**
- 修改任何状态值前，必须先列出完整的状态流转链路 - 修改任何状态值前，必须先列出完整的状态流转链路
- 检查项： - 检查项：枚举定义 → Service 设置 → 查询映射 → 前端 STATUS_CLASS_MAP → 前端 v-if → 统计SQL
1. 枚举定义的值是否正确
2. Service 层设置的状态值是否与枚举一致
3. 查询/列表接口的状态映射是否覆盖所有枚举值
4. 前端 `STATUS_CLASS_MAP` 是否包含新状态
5. 前端过滤条件（如 `v-if`）是否兼容新状态
6. 池/统计表的聚合 SQL 是否包含新状态值
- 禁止：只改一端不检查其他端 - 禁止：只改一端不检查其他端
**铁律6: 禁止删除源文件（来自 Bug #574 教训）** **铁律6: 禁止删除源文件（Bug #574 教训）**
- 绝对禁止删除项目中已有的 Java/Vue/SQL 源文件 - 绝对禁止删除项目中已有的 Java/Vue/SQL 源文件
- 文件有编译错误 → 修复错误，不删除文件 - 编译错误 → 修复错误；重复文件 → 重构合并
- 文件是重复的 → 重构合并，不删除文件
- 文件是 AI 幻觉创建的 → 检查 git baseline 确认后再删除
- 唯一例外：明确由人类确认删除的文件 - 唯一例外：明确由人类确认删除的文件
**铁律7: 禁止修改已有公开方法签名** **铁律7: 禁止修改已有公开方法签名**
- 不能删除或重命名已有的 public 方法 - 不能删除/重命名已有的 public 方法，不能修改参数列表
- 不能修改已有方法的参数列表 - 需要新功能 → 添加重载方法；需要改行为 → 修改内部实现
- 需要新增功能时 → 添加新的重载方法
- 需要改行为时 → 修改方法内部实现，不改签名 **铁律8: 验证后才宣称完成（Verification Before Completion）**
- **没有跑过验证命令，就不能说"完成了""通过了""没问题"**
- 禁止使用"应该可以""大概没问题""看起来正确"
- 必须：运行命令 → 读取输出 → 确认结果 → 才能宣称
- 这是诚实原则，不是效率问题
### 🟡 P1 铁律 — 强烈建议 ### 🟡 P1 铁律 — 强烈建议
**铁律8: 先分解再行动** **铁律9: 先分解再行动**
- 修改超过3个文件、涉及多模块、数据库变更，必须先制定计划 - 修改超过3个文件、涉及多模块、数据库变更，必须先制定计划
**铁律9: 验证后信** **铁律10: 验证后信**
- 每次修改后必须验证编译通过，不信记忆 - 每次修改后必须验证编译通过，不信记忆
- 重新编译命令：`mvn clean compile -DskipTests`
**铁律10: 文档统一管理** **铁律11: 文档统一管理**
- 所有文档存储在 `MD/` 目录 - 所有文档存储在 `MD/` 目录
- 文件名：大写英文+下划线（如 `BACKEND_CHECKLIST.md`） - 文件名：大写英文+下划线（如 `BACKEND_CHECKLIST.md`）
- 文档头部必须包含元数据块（文档类型、版本、日期） - 文档头部必须包含元数据块（文档类型、版本、日期）
--- ---
## 三、全链路 6 环分析 ## 三、Karpathy 编码准则
> ⚠️ **涉及数据库字段的 Bug / 需求，必须走完整链路，不得"就事论事"。** > 减少 LLM 常见编码错误。偏向谨慎而非速度。
### 3.1 先想再写
- 明确陈述假设，不确定就问
- 多种解读时都列出来，不要默默选一种
- 有更简单的方案就说出来，该推回就推回
- 不清楚的地方停下来，说清楚哪里不清楚
### 3.2 简洁优先
- 不做没要求的功能，不做一次性代码的抽象
- 不加没要求的"灵活性"和"可配置性"
- 200 行能 50 行搞定就重写
- 自问："高级工程师会不会觉得这过度设计？"
### 3.3 精准修改
- 只改必须改的，不"顺手改进"相邻代码
- 匹配现有代码风格，即使你有不同的偏好
- 每行改动都能追溯到用户的请求
- 只清理你自己改动产生的无用代码
### 3.4 目标驱动
- 把任务转化为可验证目标
- 多步任务声明计划：`[步骤] → 验证: [检查]`
- 强验收标准让 Agent 能独立循环，弱标准需要持续澄清
---
## 四、全链路 6 环分析
> ⚠️ **涉及数据库字段的 Bug / 需求，必须走完整链路。**
``` ```
前端/页面 → Controller → Service → Mapper → DB/SQL → 关联模块 前端/页面 → Controller → Service → Mapper → DB/SQL → 关联模块
①录入 ②验证 ③业务 ④持久化 ⑤存储 ⑥联动 ①录入 ②验证 ③业务 ④持久化 ⑤存储 ⑥联动
``` ```
### 每一环必须确认
| 环 | 检查内容 | | 环 | 检查内容 |
|----|---------| |----|---------|
| ① 录入 | 前端有无输入入口（弹窗、表格行编辑、表单） | | ① 录入 | 前端有无输入入口（弹窗、表格行编辑、表单） |
@@ -119,104 +139,113 @@
| ⑤ 存储 | 数据库表结构、索引、NOT NULL 约束 | | ⑤ 存储 | 数据库表结构、索引、NOT NULL 约束 |
| ⑥ 联动 | 上游（医嘱→护士站）、下游（打印、计费、报表）是否同步 | | ⑥ 联动 | 上游（医嘱→护士站）、下游（打印、计费、报表）是否同步 |
### 全链路验证顺序 **修复后的验证顺序**：
1. 数据库：确认状态值已正确写入
修复涉及状态流转的问题后，必须按以下顺序验证： 2. 后端接口：确认返回的状态映射正确
1. **数据库**：确认状态值已正确写入 3. 前端显示：确认页面显示正确状态文本
2. **后端接口**：确认返回的状态映射正确 4. 前端交互：确认按钮/操作基于正确状态启用/禁用
3. **前端显示**：确认页面显示正确状态文本 5. 统计数据：确认池/报表统计包含新状态
4. **前端交互**：确认按钮/操作基于正确状态启用/禁用
5. **统计数据**：确认池/报表统计包含新状态
### 常见陷阱
- ❌ 只修了「主入口」的保存逻辑，忘了「批量保存」「签发保存」等其他入口
- ❌ 前端加了输入框，后端 Service 没传字段
- ❌ Mapper XML 是 UNION ALL 查询，只改了其中一个子查询
- ❌ DTO 层级继承关系没检查
- ❌ 只测了新增，没测编辑已有数据的回显和修改再保存
--- ---
## 四、Harness Engineering 方法论 ## 五、Harness Engineering 方法论
> Harness = 约束 + 反馈 + 控制平面 + 持久执行 > Harness = 约束 + 反馈 + 控制平面 + 持久执行
### 4.1 四层约束金字塔 ### 5.1 四层约束金字塔
| 层级 | 内容 | 落地方式 | | 层级 | 内容 | 落地方式 |
|------|------|---------| |------|------|---------|
| **L1 架构约束** | 接口合约、包结构、命名规范、禁止模式 | 本文件铁律、AGENTS.md | | **L1 架构约束** | 接口合约、包结构、命名规范、禁止模式 | 本文件铁律 |
| **L2 代码质量** | 圈复杂度、代码风格、类型提示 | 编译门禁 + ESLint | | **L2 代码质量** | 圈复杂度、代码风格、类型提示 | 编译门禁 + ESLint |
| **L3 安全约束** | 敏感信息检测、权限检查、输入验证 | 配置不可硬编码 | | **L3 安全约束** | 敏感信息检测、权限检查、输入验证 | 配置不可硬编码 |
| **L4 业务规则** | 领域逻辑、数据一致性、事务边界 | 全链路 6 环验证 | | **L4 业务规则** | 领域逻辑、数据一致性、事务边界 | 全链路 6 环验证 |
**约束优先级**：安全 > 架构 > 质量 > 业务 **约束设计原则**：
- **可验证**：每条约束必须能被自动化检查（"覆盖率>90%"✅ "质量要高"❌）
- **无歧义**："每函数不超过50行"✅ "函数不要太长"❌
- **优先级**：安全(1) > 架构(2) > 业务(3) > 质量(4) > 性能(5)
- **渐进增强**：L1编译通过 → L2+命名规范 → L3+测试覆盖 → L4+安全扫描
### 4.2 三层反馈系统 ### 5.2 三层反馈系统
| 层级 | 速度 | 覆盖范围 | 失败处理 | | 层级 | 速度 | 覆盖范围 | 失败处理 |
|------|------|---------|---------| |------|------|---------|---------|
| **L1 编译检查** | <30 秒 | 语法、类型、签名 | 立即阻断，自行修复 | | **L1 编译检查** | <30秒 | 语法、类型、签名 | 立即阻断，自行修复 |
| **L2 数据流验证** | <5 分钟 | 全链路字段、Mapper XML、DTO | 修复后上报 | | **L2 数据流验证** | <5分钟 | 全链路字段、Mapper XML、DTO | 修复后上报 |
| **L3 人工审查** | 10-30 分钟 | 架构、设计、业务正确性 | 驳回 / 指导 / 批准 | | **L3 人工审查** | 10-30分钟 | 架构、设计、业务正确性 | 驳回/指导/批准 |
**反馈设计铁律**： **反馈铁律**：
- 反馈必须可行动（指出：文件 + 行号 + 错误类型 + 修复方向） - 反馈必须可行动（文件 + 行号 + 错误类型 + 修复方向）
- 反馈越及时越好（L1 即时 → L2 分钟 → L3 小时）
- 失败后先回滚到最近检查点，再重试 - 失败后先回滚到最近检查点，再重试
- 持续失败3次 → 上报人类
### 4.3 控制平面（Agent 协调） ### 5.3 控制平面
``` ```
┌─────────────────────────────────────────────┐ 战略层（人类） → 设定目标、审批决策、异常升级
│ 战略层（人类主导） │ 战术层（Agent） → 任务分解、update_plan、依赖协调、检查点保存
│ ├── 设定目标、审批关键决策 │ 执行层（Agent） → 代码生成、测试执行、错误恢复、幂等重试
│ └── 异常升级处理 │
├─────────────────────────────────────────────┤
│ 战术层（Control Plane） │
│ ├── 任务分解 + update_plan │
│ ├── 依赖协调 + 资源分配 │
│ └── 检查点保存 + 恢复 │
├─────────────────────────────────────────────┤
│ 执行层（Agent 自主） │
│ ├── 代码生成、测试执行 │
│ └── 错误恢复 + 幂等重试 │
└─────────────────────────────────────────────┘
``` ```
### 4.4 持久执行 ### 5.4 持久执行
- 每个关键步骤保存检查点（`update_plan` 进度） - 每个关键步骤保存检查点（`update_plan` 进度）
- 失败后从最新检查点恢复，不从头开始 - 失败后从最新检查点恢复，不从头开始
- 幂等设计：同一操作重复执行结果一致 - 幂等设计：同一操作重复执行结果一致
- **三层状态管理**：系统层(工作流ID/超时/重试) → 执行层(当前活动/进度) → 业务层(已完成工作/中间产物)
--- ---
## 五、质量门禁（5 级） ## 六、五层质量门禁
| 级别 | 门禁 | 通过标准 | | 门禁 | 时间 | 范围 | 失败处理 |
|------|------|---------| |------|------|------|---------|
| **L1** | 编译通过 | `mvn clean compile` + `npm run build:dev` 无 ERROR | | **L1 编译检查** | <30秒 | 语法、类型、导入 | Agent 自行修复 |
| **L2** | 测试通过 | 单元测试 + 接口测试全部通过 | | **L2 静态分析** | <2分钟 | 代码风格、复杂度、安全 | Agent 修复 |
| **L3** | DB 审查 | Flyway 脚本规范、SQL 安全、索引合理 | | **L3 单元测试** | <5分钟 | 功能正确性、边界条件 | 自动修复或上报 |
| **L4** | 验收通过 | 核心功能流程完整验证、全链路检查 | | **L4 集成测试** | <15分钟 | 模块间交互、数据流 | 上报人工 |
| **L5** | 归档完成 | Git commit + 文档更新 + 代码推送 | | **L5 生产验证** | 持续 | 监控、告警、性能 | 自动回滚 |
### 提交铁律 **提交铁律**：L1-L2 必须通过才能 commit，L3（如有DB变更）必须通过才能 push
- L1-L2 必须通过才能 commit
- L3（如有DB变更）必须通过才能 push
- L4-L5 发布前必须完成
--- ---
## 六、后端开发规范 ## 七、系统化调试（Systematic Debugging）
> **铁律：没有根因调查，不能提出修复方案。**
### 四阶段流程
**阶段1：根因调查**（修复前必须完成）
1. 仔细阅读错误信息（堆栈、行号、错误码）
2. 稳定复现（能否可靠触发？步骤？每次？）
3. 检查最近变更（git diff、新依赖、配置变更）
4. 多组件系统：在每个组件边界加诊断日志，定位哪一层断裂
5. 追踪数据流：坏值从哪里来？谁调用的？一直追溯到源头
**阶段2：模式分析**
- 找到同代码库中类似的正常工作代码
- 逐项对比差异
- 理解依赖关系
**阶段3：假设与测试**
- 形成单一假设："我认为X是根因，因为Y"
- 做最小改动测试
- 有效 → 阶段4；无效 → 新假设
**阶段4：实施**
- 创建失败测试用例
- 修复根因（不是症状）
- 验证修复
---
## 八、后端开发规范
### 分层架构 ### 分层架构
``` ```
Controller → AppService → Service → Mapper → Entity Controller → AppService → Service → Mapper → Entity
接收请求 编排业务 单表CRUD 数据访问 实体定义
``` ```
### 命名规范 ### 命名规范
@@ -240,110 +269,125 @@ com.healthlink.his.domain.{module}
com.healthlink.his.common.enums com.healthlink.his.common.enums
``` ```
### 统一返回格式
```java
AjaxResult.success(data) // 成功
AjaxResult.error("错误信息") // 失败
getDataTable(list) // 列表
```
### 关键约束 ### 关键约束
- 所有查询使用 `LambdaQueryWrapper`，禁止字符串拼接 SQL - 所有查询使用 `LambdaQueryWrapper`，禁止字符串拼接 SQL
- `@Transactional(rollbackFor = Exception.class)` 管理事务 - `@Transactional(rollbackFor = Exception.class)` 管理事务
- 所有接口标注 `@PreAuthorize` 权限控制 - 所有接口标注 `@PreAuthorize` 权限控制
- 患者敏感信息（身份证、手机号）在日志中脱敏 - 患者敏感信息在日志中脱敏
- **扩展功能不修改原有函数签名**，新建 Service/AppService - **扩展功能不修改原有函数签名**
- 涉及多表写操作的方法标注 `@Transactional`
- 事务方法未被同一类内方法直接调用（避免自调用失效）
--- ---
## 七、前端开发规范 ## 九、前端开发规范
### 技术栈 ### 技术栈
- Vue 3 + Vite + Element Plus + Pinia + Axios - Vue 3 + Vite + Element Plus + Pinia + Axios（基于 RuoYi-Vue3）
- 基于 RuoYi-Vue3 框架
### 目录结构 ### 目录结构
``` ```
src/api/{module}/ # API接口（kebab-case路径） src/api/{module}/ # API接口
src/views/{module}/ # 页面组件 src/views/{module}/ # 页面组件
src/store/modules/ # Pinia状态管理 src/store/modules/ # Pinia状态管理
src/components/ # 公共组件 src/components/ # 公共组件
``` ```
### API 路径规范
```javascript
// 统一前缀 /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` 指令
### 关键约束 ### 关键约束
- API前缀：`/healthlink-his/api/v1/`
- 路由懒加载：`() => import('@/views/xxx/index.vue')` - 路由懒加载：`() => import('@/views/xxx/index.vue')`
- 不使用 `v-html`（除非做 XSS 转义） - 页面使用 `<script setup>` 语法
- 不在前端硬编码密码、密钥 - 按钮权限使用 `v-hasPermi` 指令
- `onMounted` 中注册的事件在 `onUnmounted` 中移除 - `onMounted` 中注册的事件在 `onUnmounted` 中移除
--- ---
## 八、Agent 体系（智能体协作） ## 十、Agent 体系
### 角色定义 ### 角色与路由
| 代号 | 名称 | 角色 | 职责 | | 代号 | 名称 | 角色 | 路由关键词 |
|------|------|------|------| |------|------|------|-----------|
| liubei | 刘备 | 项目经理 | 总协调、任务分配、异常升级 | | liubei | 刘备 | 项目经理 | 协调、分派、异常升级 |
| zhugeliang | 诸葛亮 | 架构师 | 需求分析、方案设计、技术决策 | | zhugeliang | 诸葛亮 | 架构师 | 分析、路由、设计 |
| guanyu | 关羽 | 后端开发 | Java 后端修复、API 开发 | | guanyu | 关羽 | 后端开发 | java, api, spring, service, controller |
| zhaoyun | 赵云 | 前端开发 | Vue 前端修复、页面开发 | | zhaoyun | 赵云 | 前端开发 | vue, 界面, 显示, 弹窗, 按钮 |
| xunyu | 荀彧 | DBA | 数据库审查、SQL 优化、Flyway 脚本 | | xunyu | 荀彧 | DBA | 数据库, sql, 迁移, mapper xml |
| zhangfei | 张飞 | 测试 | Playwright 测试、接口测试、回归测试 | | zhangfei | 张飞 | 测试 | 测试, QA, 回归 |
| huatuo | 华佗 | 验收 | 功能验收、质量确认、发布检查 | | huatuo | 华佗 | 验收 | 需求验收、质量确认 |
| chenlin | 陈琳 | 文档 | 归档记录、文档更新、Git 提交 | | chenlin | 陈琳 | 文档 | 文档、归档、Git提交 |
### 协作流水线 ### 协作流水线
``` ```
刘备(协调) → 诸葛亮(分析) → {关羽|赵云}(修复) → 荀彧(DB审查) → 张飞(测试) → 华佗(验收) → 陈琳(归档) 刘备(协调) → 诸葛亮(分析路由) → {关羽|赵云}(修复) → 荀彧(DB审查) → 张飞(测试) → 华佗(验收) → 陈琳(归档)
```
### Bug 修复完整管线（BDT 方法论）
```
获取Bug → 设计测试用例 → 基线测试(应失败) → 全链路修复 → 回归测试(应通过) → 扩展测试(无回归) → 提交
``` ```
### Bug 状态管理铁律 ### Bug 状态管理铁律
- 人类提的 Bug：只加备注，不改状态，不改分配 - 人类提的 Bug：只加备注，不改状态，不改分配
- 智能体提的 Bug：可以改分配和加备注 - 智能体提的 Bug：可以改分配和加备注
- 已关闭/已解决的 Bug 不再处理 - 已关闭/已解决的 Bug 不再处理
### 修复流程铁律 ---
- 一次只修一个 Bug，不扩大范围 ## 十一、审查与审计
- 修复前必须读 AGENTS.md
- 修复后必须验证编译
- 涉及 SQL 必须先查真实数据库
### 测试流程铁律 ### 三层审查体系
- Playwright 必须 `--workers=1` 单线程 | 层级 | 内容 | 时机 |
- 超时 120 秒 |------|------|------|
- 最多重试 3 次 | **L1 自审** | Agent 对照约束逐条检查 | 每次提交前 |
- 测试结果写入禅道备注 | **L2 配对审查** | Agent 生成变更摘要，人类终审 | PR/提交时 |
| **L3 合规审查** | 审计追踪，记录所有 AI 操作 | 持续 |
### 归档流程铁律 ### L1 自审清单
```yaml
self_review:
- "所有修改能通过编译？"
- "遵守命名规范？"
- "测试覆盖达标？"
- "没有遗漏的 TODO / DEBUG？"
- "变更范围没超出任务边界？"
```
- 三重归档：Git + SQLite + Redis ### 评审评分维度
- SQLite 必须使用完整字段 | 维度 | 问题 |
- 禅道备注格式：`[📝 陈琳归档] Bug #xxx` |------|------|
| 正确性 | 行为是否符合目标功能？ |
| 验证 | 检查是否真的跑过并留下证据？ |
| 范围纪律 | 是否保持在选定功能范围内？ |
| 可靠性 | 结果能否在重启后继续工作？ |
| 可维护性 | 代码和文档是否清楚到可交接？ |
--- ---
## 九、开发流程 ## 十二、标准工作循环
```
开始会话
├→ 1. Init — 读 AGENTS.md + PROGRESS.md + git log
├→ 2. Select — 只选一个未完成功能
├→ 3. Implement — 一次只做一个，不扩大范围
├→ 4. Verify — 运行验证命令，有证据才标记完成
└→ 5. Cleanup — 更新进度 + clean-state-checklist + git commit
```
### 会话结束前必须运行 Clean State Checklist
```
□ 标准启动路径仍然可用
□ 标准验证路径仍然可运行
□ 当前进度已记录到进度日志
□ 无半成品步骤处于未记录状态
□ 下一轮会话无需人工修复即可继续
```
---
## 十三、开发流程
``` ```
收到任务 收到任务
@@ -367,64 +411,60 @@ scope: 模块名(如 registration, billing, pharmacy)
--- ---
## 十、快速参考命令 ## 十四、快速参考命令
```bash ```bash
# === 后端 === # === 后端 ===
export JAVA_HOME=/opt/jdk-25 export JAVA_HOME=/opt/jdk-25
mvn clean compile -DskipTests # 编译 mvn clean compile -DskipTests # 编译
mvn install -DskipTests # 完整构建 mvn install -DskipTests # 构建
mvn test -pl healthlink-his-application -Dtest="XxxTest" -Dsurefire.failIfNoSpecifiedTests=false # 测试 mvn test -pl healthlink-his-application -Dtest="XxxTest" -Dsurefire.failIfNoSpecifiedTests=false
# === 前端 === # === 前端 ===
cd healthlink-his-ui cd healthlink-his-ui
npm run dev # 开发模式 npm run dev && npm run build:dev && npm run lint && npm run test:run
npm run build:dev # 构建
npm run lint # 代码检查
npm run test:run # 单元测试
# === Git === # === Git ===
git status # 查看变更 git status && git add -A && git commit -m "feat(module): desc" && git push origin develop
git add -A # 暂存所有
git commit -m "feat(module): description" # 提交
git push origin develop # 推送
``` ```
--- ---
## 十一、详细规范文档索引 ## 十五、详细规范文档索引
| 文档 | 路径 | 用途 | | 文档 | 路径 | 用途 |
|------|------|------| |------|------|------|
| 执行铁律 | `MD/specs/IRON_RULES.md` | 铁律完整版 | | 执行铁律 | `MD/specs/IRON_RULES.md` | 铁律完整版 |
| 后端规范 | `MD/specs/BACKEND_DEVELOPMENT_STANDARD.md` | 后端编码标准 | | 后端规范 | `MD/specs/BACKEND_DEVELOPMENT_STANDARD.md` | 后端编码标准 |
| 前端规范 | `MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md` | 前端编码标准 | | 前端规范 | `MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md` | 前端编码标准 |
| Harness方法论 | `MD/specs/HARNESS_ENGINEERING.md` | 完整Harness+Agent方法论 |
| 文档规范 | `MD/DOCUMENTATION_STANDARD.md` | 文档管理标准 | | 文档规范 | `MD/DOCUMENTATION_STANDARD.md` | 文档管理标准 |
| 后端清单 | `MD/specs/BACKEND_CHECKLIST.md` | 发布前检查 | | 后端清单 | `MD/specs/BACKEND_CHECKLIST.md` | 发布前检查 |
| 前端清单 | `MD/specs/FRONTEND_CHECKLIST.md` | 发布前检查 | | 前端清单 | `MD/specs/FRONTEND_CHECKLIST.md` | 发布前检查 |
| 三甲标准 | `MD/standards/GRADE3A_HIS_STANDARD.md` | 三甲医院达标标准 | | 三甲标准 | `MD/standards/GRADE3A_HIS_STANDARD.md` | 三甲医院达标标准 |
| Flyway指南 | `MD/guides/FLYWAY_USAGE_GUIDE.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: 签到设 BOOKED(1) 而非 CHECKED_IN(3)，前端映射缺失 → 必须走完整状态链路 |
| 盲删源文件 | Bug #574 | AI 看到编译错误直接删文件，没检查是否在 baseline → 必须先确认文件来源再操作 | | 盲删源文件 | AI 看到编译错误直接删文件，没检查 baseline → 必须先确认文件来源 |
| 修复方向偏差 | Bug #574 | 多次 fallback 改的是 OrderServiceImpl，完全没触及 TicketServiceImpl → 必须用 rg 搜索所有相关代码路径 | | 修复方向偏差 | 多次 fallback 改的是错误的 Service → 必须用 rg 搜索所有相关代码路径 |
| bug_reports 表缺少列 | 经验 | INSERT 会静默失败，必须检查表结构 | | bug_reports 缺列 | INSERT 静默失败 → 必须检查表结构 |
| 禅道 comment API | 经验 | API 不存在，必须用 resolve+activate workaround | | 禅道 comment API | API 不存在，用 resolve+activate workaround |
| SQLite WAL 并发 | 经验 | 多进程并发写需要 checkpoint | | SQLite WAL 并发 | 多进程并发写需要 checkpoint |
| UTF-8 切片 | 经验 | 多字节字符不能用 byte index 切片 | | UTF-8 切片 | 多字节字符不能用 byte index 切片 |
| 禅道图片附件 | 经验 | 必须 OCR 读取，不能直接解析 | | 上下文焦虑 | Agent 感觉上下文快满时会匆忙结束，跳过验证 → 注意 context 40% 阈值 |
| 过早宣告胜利 | 自评≠验证，分开"干活"和"检查" |
| 覆盖率幻觉 | 覆盖率达标但逻辑没测 → 引入变异测试 |
--- ---
> ⚠️ **警告**: 本文件是项目 AI 开发规范的唯一信源。各工具配置文件（AGENTS.md、.cursorrules 等）均通过 `bash scripts/sync-ai-rules.sh` 从本文件同步。修改规范请只修改本文件。 > ⚠️ 本文件是 AI 开发规范的唯一信源。各工具配置文件由 `bash scripts/sync-ai-rules.sh` 同步。
--- ---
> 📅 最后同步: 2026-06-06 09:56 | 源文件: RULES.md | 重新同步: `bash scripts/sync-ai-rules.sh` > 📅 最后同步: 2026-06-06 10:01 | 源文件: RULES.md | 重新同步: `bash scripts/sync-ai-rules.sh`

382
.qwenrules
View File

@@ -6,7 +6,7 @@
# HealthLink-HIS — AI 开发规范（自动加载） # HealthLink-HIS — AI 开发规范（自动加载）
> 🤖 **本文件供所有 AI 编码工具自动读取**。无论使用 Claude Code、Cursor、Codex CLI、Copilot、Qwen、Cline 还是其他工具，进入本项目后必须遵守以下规范。 > 🤖 **本文件供所有 AI 编码工具自动读取**。进入本项目后必须遵守以下规范。
> >
> **模型决定上限，Harness 决定底线。** > **模型决定上限，Harness 决定底线。**
@@ -48,7 +48,6 @@
- 凡是新建表、新增字段，必须创建 Flyway 迁移脚本 - 凡是新建表、新增字段，必须创建 Flyway 迁移脚本
- 路径：`healthlink-his-domain/src/main/resources/db/migration/` - 路径：`healthlink-his-domain/src/main/resources/db/migration/`
- 命名：`V{版本号}__{描述}.sql`（双下划线） - 命名：`V{版本号}__{描述}.sql`（双下划线）
- 禁止直接在数据库执行 SQL 不走 Flyway
**铁律3: 测试通过后才提交** **铁律3: 测试通过后才提交**
- 编译 + 测试全部通过后才能 git commit - 编译 + 测试全部通过后才能 git commit
@@ -57,59 +56,80 @@
**铁律4: 前后端API路径对齐** **铁律4: 前后端API路径对齐**
- 后端前缀：`/healthlink-his/api/v1/` - 后端前缀：`/healthlink-his/api/v1/`
- 前端 `request.js` 的 baseURL 必须与后端匹配 - 前端 `request.js` 的 baseURL 必须与后端匹配
- 接口变更必须同步更新前后端代码
**铁律5: 状态值一致性（来自 Bug #574 教训）** **铁律5: 状态值一致性（Bug #574 教训）**
- 修改任何状态值前，必须先列出完整的状态流转链路 - 修改任何状态值前，必须先列出完整的状态流转链路
- 检查项： - 检查项：枚举定义 → Service 设置 → 查询映射 → 前端 STATUS_CLASS_MAP → 前端 v-if → 统计SQL
1. 枚举定义的值是否正确
2. Service 层设置的状态值是否与枚举一致
3. 查询/列表接口的状态映射是否覆盖所有枚举值
4. 前端 `STATUS_CLASS_MAP` 是否包含新状态
5. 前端过滤条件（如 `v-if`）是否兼容新状态
6. 池/统计表的聚合 SQL 是否包含新状态值
- 禁止：只改一端不检查其他端 - 禁止：只改一端不检查其他端
**铁律6: 禁止删除源文件（来自 Bug #574 教训）** **铁律6: 禁止删除源文件（Bug #574 教训）**
- 绝对禁止删除项目中已有的 Java/Vue/SQL 源文件 - 绝对禁止删除项目中已有的 Java/Vue/SQL 源文件
- 文件有编译错误 → 修复错误，不删除文件 - 编译错误 → 修复错误；重复文件 → 重构合并
- 文件是重复的 → 重构合并，不删除文件
- 文件是 AI 幻觉创建的 → 检查 git baseline 确认后再删除
- 唯一例外：明确由人类确认删除的文件 - 唯一例外：明确由人类确认删除的文件
**铁律7: 禁止修改已有公开方法签名** **铁律7: 禁止修改已有公开方法签名**
- 不能删除或重命名已有的 public 方法 - 不能删除/重命名已有的 public 方法，不能修改参数列表
- 不能修改已有方法的参数列表 - 需要新功能 → 添加重载方法；需要改行为 → 修改内部实现
- 需要新增功能时 → 添加新的重载方法
- 需要改行为时 → 修改方法内部实现，不改签名 **铁律8: 验证后才宣称完成（Verification Before Completion）**
- **没有跑过验证命令，就不能说"完成了""通过了""没问题"**
- 禁止使用"应该可以""大概没问题""看起来正确"
- 必须：运行命令 → 读取输出 → 确认结果 → 才能宣称
- 这是诚实原则，不是效率问题
### 🟡 P1 铁律 — 强烈建议 ### 🟡 P1 铁律 — 强烈建议
**铁律8: 先分解再行动** **铁律9: 先分解再行动**
- 修改超过3个文件、涉及多模块、数据库变更，必须先制定计划 - 修改超过3个文件、涉及多模块、数据库变更，必须先制定计划
**铁律9: 验证后信** **铁律10: 验证后信**
- 每次修改后必须验证编译通过，不信记忆 - 每次修改后必须验证编译通过，不信记忆
- 重新编译命令：`mvn clean compile -DskipTests`
**铁律10: 文档统一管理** **铁律11: 文档统一管理**
- 所有文档存储在 `MD/` 目录 - 所有文档存储在 `MD/` 目录
- 文件名：大写英文+下划线（如 `BACKEND_CHECKLIST.md`） - 文件名：大写英文+下划线（如 `BACKEND_CHECKLIST.md`）
- 文档头部必须包含元数据块（文档类型、版本、日期） - 文档头部必须包含元数据块（文档类型、版本、日期）
--- ---
## 三、全链路 6 环分析 ## 三、Karpathy 编码准则
> ⚠️ **涉及数据库字段的 Bug / 需求，必须走完整链路，不得"就事论事"。** > 减少 LLM 常见编码错误。偏向谨慎而非速度。
### 3.1 先想再写
- 明确陈述假设，不确定就问
- 多种解读时都列出来，不要默默选一种
- 有更简单的方案就说出来，该推回就推回
- 不清楚的地方停下来，说清楚哪里不清楚
### 3.2 简洁优先
- 不做没要求的功能，不做一次性代码的抽象
- 不加没要求的"灵活性"和"可配置性"
- 200 行能 50 行搞定就重写
- 自问："高级工程师会不会觉得这过度设计？"
### 3.3 精准修改
- 只改必须改的，不"顺手改进"相邻代码
- 匹配现有代码风格，即使你有不同的偏好
- 每行改动都能追溯到用户的请求
- 只清理你自己改动产生的无用代码
### 3.4 目标驱动
- 把任务转化为可验证目标
- 多步任务声明计划：`[步骤] → 验证: [检查]`
- 强验收标准让 Agent 能独立循环，弱标准需要持续澄清
---
## 四、全链路 6 环分析
> ⚠️ **涉及数据库字段的 Bug / 需求，必须走完整链路。**
``` ```
前端/页面 → Controller → Service → Mapper → DB/SQL → 关联模块 前端/页面 → Controller → Service → Mapper → DB/SQL → 关联模块
①录入 ②验证 ③业务 ④持久化 ⑤存储 ⑥联动 ①录入 ②验证 ③业务 ④持久化 ⑤存储 ⑥联动
``` ```
### 每一环必须确认
| 环 | 检查内容 | | 环 | 检查内容 |
|----|---------| |----|---------|
| ① 录入 | 前端有无输入入口（弹窗、表格行编辑、表单） | | ① 录入 | 前端有无输入入口（弹窗、表格行编辑、表单） |
@@ -119,104 +139,113 @@
| ⑤ 存储 | 数据库表结构、索引、NOT NULL 约束 | | ⑤ 存储 | 数据库表结构、索引、NOT NULL 约束 |
| ⑥ 联动 | 上游（医嘱→护士站）、下游（打印、计费、报表）是否同步 | | ⑥ 联动 | 上游（医嘱→护士站）、下游（打印、计费、报表）是否同步 |
### 全链路验证顺序 **修复后的验证顺序**：
1. 数据库：确认状态值已正确写入
修复涉及状态流转的问题后，必须按以下顺序验证： 2. 后端接口：确认返回的状态映射正确
1. **数据库**：确认状态值已正确写入 3. 前端显示：确认页面显示正确状态文本
2. **后端接口**：确认返回的状态映射正确 4. 前端交互：确认按钮/操作基于正确状态启用/禁用
3. **前端显示**：确认页面显示正确状态文本 5. 统计数据：确认池/报表统计包含新状态
4. **前端交互**：确认按钮/操作基于正确状态启用/禁用
5. **统计数据**：确认池/报表统计包含新状态
### 常见陷阱
- ❌ 只修了「主入口」的保存逻辑，忘了「批量保存」「签发保存」等其他入口
- ❌ 前端加了输入框，后端 Service 没传字段
- ❌ Mapper XML 是 UNION ALL 查询，只改了其中一个子查询
- ❌ DTO 层级继承关系没检查
- ❌ 只测了新增，没测编辑已有数据的回显和修改再保存
--- ---
## 四、Harness Engineering 方法论 ## 五、Harness Engineering 方法论
> Harness = 约束 + 反馈 + 控制平面 + 持久执行 > Harness = 约束 + 反馈 + 控制平面 + 持久执行
### 4.1 四层约束金字塔 ### 5.1 四层约束金字塔
| 层级 | 内容 | 落地方式 | | 层级 | 内容 | 落地方式 |
|------|------|---------| |------|------|---------|
| **L1 架构约束** | 接口合约、包结构、命名规范、禁止模式 | 本文件铁律、AGENTS.md | | **L1 架构约束** | 接口合约、包结构、命名规范、禁止模式 | 本文件铁律 |
| **L2 代码质量** | 圈复杂度、代码风格、类型提示 | 编译门禁 + ESLint | | **L2 代码质量** | 圈复杂度、代码风格、类型提示 | 编译门禁 + ESLint |
| **L3 安全约束** | 敏感信息检测、权限检查、输入验证 | 配置不可硬编码 | | **L3 安全约束** | 敏感信息检测、权限检查、输入验证 | 配置不可硬编码 |
| **L4 业务规则** | 领域逻辑、数据一致性、事务边界 | 全链路 6 环验证 | | **L4 业务规则** | 领域逻辑、数据一致性、事务边界 | 全链路 6 环验证 |
**约束优先级**：安全 > 架构 > 质量 > 业务 **约束设计原则**：
- **可验证**：每条约束必须能被自动化检查（"覆盖率>90%"✅ "质量要高"❌）
- **无歧义**："每函数不超过50行"✅ "函数不要太长"❌
- **优先级**：安全(1) > 架构(2) > 业务(3) > 质量(4) > 性能(5)
- **渐进增强**：L1编译通过 → L2+命名规范 → L3+测试覆盖 → L4+安全扫描
### 4.2 三层反馈系统 ### 5.2 三层反馈系统
| 层级 | 速度 | 覆盖范围 | 失败处理 | | 层级 | 速度 | 覆盖范围 | 失败处理 |
|------|------|---------|---------| |------|------|---------|---------|
| **L1 编译检查** | <30 秒 | 语法、类型、签名 | 立即阻断，自行修复 | | **L1 编译检查** | <30秒 | 语法、类型、签名 | 立即阻断，自行修复 |
| **L2 数据流验证** | <5 分钟 | 全链路字段、Mapper XML、DTO | 修复后上报 | | **L2 数据流验证** | <5分钟 | 全链路字段、Mapper XML、DTO | 修复后上报 |
| **L3 人工审查** | 10-30 分钟 | 架构、设计、业务正确性 | 驳回 / 指导 / 批准 | | **L3 人工审查** | 10-30分钟 | 架构、设计、业务正确性 | 驳回/指导/批准 |
**反馈设计铁律**： **反馈铁律**：
- 反馈必须可行动（指出：文件 + 行号 + 错误类型 + 修复方向） - 反馈必须可行动（文件 + 行号 + 错误类型 + 修复方向）
- 反馈越及时越好（L1 即时 → L2 分钟 → L3 小时）
- 失败后先回滚到最近检查点，再重试 - 失败后先回滚到最近检查点，再重试
- 持续失败3次 → 上报人类
### 4.3 控制平面（Agent 协调） ### 5.3 控制平面
``` ```
┌─────────────────────────────────────────────┐ 战略层（人类） → 设定目标、审批决策、异常升级
│ 战略层（人类主导） │ 战术层（Agent） → 任务分解、update_plan、依赖协调、检查点保存
│ ├── 设定目标、审批关键决策 │ 执行层（Agent） → 代码生成、测试执行、错误恢复、幂等重试
│ └── 异常升级处理 │
├─────────────────────────────────────────────┤
│ 战术层（Control Plane） │
│ ├── 任务分解 + update_plan │
│ ├── 依赖协调 + 资源分配 │
│ └── 检查点保存 + 恢复 │
├─────────────────────────────────────────────┤
│ 执行层（Agent 自主） │
│ ├── 代码生成、测试执行 │
│ └── 错误恢复 + 幂等重试 │
└─────────────────────────────────────────────┘
``` ```
### 4.4 持久执行 ### 5.4 持久执行
- 每个关键步骤保存检查点（`update_plan` 进度） - 每个关键步骤保存检查点（`update_plan` 进度）
- 失败后从最新检查点恢复，不从头开始 - 失败后从最新检查点恢复，不从头开始
- 幂等设计：同一操作重复执行结果一致 - 幂等设计：同一操作重复执行结果一致
- **三层状态管理**：系统层(工作流ID/超时/重试) → 执行层(当前活动/进度) → 业务层(已完成工作/中间产物)
--- ---
## 五、质量门禁（5 级） ## 六、五层质量门禁
| 级别 | 门禁 | 通过标准 | | 门禁 | 时间 | 范围 | 失败处理 |
|------|------|---------| |------|------|------|---------|
| **L1** | 编译通过 | `mvn clean compile` + `npm run build:dev` 无 ERROR | | **L1 编译检查** | <30秒 | 语法、类型、导入 | Agent 自行修复 |
| **L2** | 测试通过 | 单元测试 + 接口测试全部通过 | | **L2 静态分析** | <2分钟 | 代码风格、复杂度、安全 | Agent 修复 |
| **L3** | DB 审查 | Flyway 脚本规范、SQL 安全、索引合理 | | **L3 单元测试** | <5分钟 | 功能正确性、边界条件 | 自动修复或上报 |
| **L4** | 验收通过 | 核心功能流程完整验证、全链路检查 | | **L4 集成测试** | <15分钟 | 模块间交互、数据流 | 上报人工 |
| **L5** | 归档完成 | Git commit + 文档更新 + 代码推送 | | **L5 生产验证** | 持续 | 监控、告警、性能 | 自动回滚 |
### 提交铁律 **提交铁律**：L1-L2 必须通过才能 commit，L3（如有DB变更）必须通过才能 push
- L1-L2 必须通过才能 commit
- L3（如有DB变更）必须通过才能 push
- L4-L5 发布前必须完成
--- ---
## 六、后端开发规范 ## 七、系统化调试（Systematic Debugging）
> **铁律：没有根因调查，不能提出修复方案。**
### 四阶段流程
**阶段1：根因调查**（修复前必须完成）
1. 仔细阅读错误信息（堆栈、行号、错误码）
2. 稳定复现（能否可靠触发？步骤？每次？）
3. 检查最近变更（git diff、新依赖、配置变更）
4. 多组件系统：在每个组件边界加诊断日志，定位哪一层断裂
5. 追踪数据流：坏值从哪里来？谁调用的？一直追溯到源头
**阶段2：模式分析**
- 找到同代码库中类似的正常工作代码
- 逐项对比差异
- 理解依赖关系
**阶段3：假设与测试**
- 形成单一假设："我认为X是根因，因为Y"
- 做最小改动测试
- 有效 → 阶段4；无效 → 新假设
**阶段4：实施**
- 创建失败测试用例
- 修复根因（不是症状）
- 验证修复
---
## 八、后端开发规范
### 分层架构 ### 分层架构
``` ```
Controller → AppService → Service → Mapper → Entity Controller → AppService → Service → Mapper → Entity
接收请求 编排业务 单表CRUD 数据访问 实体定义
``` ```
### 命名规范 ### 命名规范
@@ -240,110 +269,125 @@ com.healthlink.his.domain.{module}
com.healthlink.his.common.enums com.healthlink.his.common.enums
``` ```
### 统一返回格式
```java
AjaxResult.success(data) // 成功
AjaxResult.error("错误信息") // 失败
getDataTable(list) // 列表
```
### 关键约束 ### 关键约束
- 所有查询使用 `LambdaQueryWrapper`，禁止字符串拼接 SQL - 所有查询使用 `LambdaQueryWrapper`，禁止字符串拼接 SQL
- `@Transactional(rollbackFor = Exception.class)` 管理事务 - `@Transactional(rollbackFor = Exception.class)` 管理事务
- 所有接口标注 `@PreAuthorize` 权限控制 - 所有接口标注 `@PreAuthorize` 权限控制
- 患者敏感信息（身份证、手机号）在日志中脱敏 - 患者敏感信息在日志中脱敏
- **扩展功能不修改原有函数签名**，新建 Service/AppService - **扩展功能不修改原有函数签名**
- 涉及多表写操作的方法标注 `@Transactional`
- 事务方法未被同一类内方法直接调用（避免自调用失效）
--- ---
## 七、前端开发规范 ## 九、前端开发规范
### 技术栈 ### 技术栈
- Vue 3 + Vite + Element Plus + Pinia + Axios - Vue 3 + Vite + Element Plus + Pinia + Axios（基于 RuoYi-Vue3）
- 基于 RuoYi-Vue3 框架
### 目录结构 ### 目录结构
``` ```
src/api/{module}/ # API接口（kebab-case路径） src/api/{module}/ # API接口
src/views/{module}/ # 页面组件 src/views/{module}/ # 页面组件
src/store/modules/ # Pinia状态管理 src/store/modules/ # Pinia状态管理
src/components/ # 公共组件 src/components/ # 公共组件
``` ```
### API 路径规范
```javascript
// 统一前缀 /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` 指令
### 关键约束 ### 关键约束
- API前缀：`/healthlink-his/api/v1/`
- 路由懒加载：`() => import('@/views/xxx/index.vue')` - 路由懒加载：`() => import('@/views/xxx/index.vue')`
- 不使用 `v-html`（除非做 XSS 转义） - 页面使用 `<script setup>` 语法
- 不在前端硬编码密码、密钥 - 按钮权限使用 `v-hasPermi` 指令
- `onMounted` 中注册的事件在 `onUnmounted` 中移除 - `onMounted` 中注册的事件在 `onUnmounted` 中移除
--- ---
## 八、Agent 体系（智能体协作） ## 十、Agent 体系
### 角色定义 ### 角色与路由
| 代号 | 名称 | 角色 | 职责 | | 代号 | 名称 | 角色 | 路由关键词 |
|------|------|------|------| |------|------|------|-----------|
| liubei | 刘备 | 项目经理 | 总协调、任务分配、异常升级 | | liubei | 刘备 | 项目经理 | 协调、分派、异常升级 |
| zhugeliang | 诸葛亮 | 架构师 | 需求分析、方案设计、技术决策 | | zhugeliang | 诸葛亮 | 架构师 | 分析、路由、设计 |
| guanyu | 关羽 | 后端开发 | Java 后端修复、API 开发 | | guanyu | 关羽 | 后端开发 | java, api, spring, service, controller |
| zhaoyun | 赵云 | 前端开发 | Vue 前端修复、页面开发 | | zhaoyun | 赵云 | 前端开发 | vue, 界面, 显示, 弹窗, 按钮 |
| xunyu | 荀彧 | DBA | 数据库审查、SQL 优化、Flyway 脚本 | | xunyu | 荀彧 | DBA | 数据库, sql, 迁移, mapper xml |
| zhangfei | 张飞 | 测试 | Playwright 测试、接口测试、回归测试 | | zhangfei | 张飞 | 测试 | 测试, QA, 回归 |
| huatuo | 华佗 | 验收 | 功能验收、质量确认、发布检查 | | huatuo | 华佗 | 验收 | 需求验收、质量确认 |
| chenlin | 陈琳 | 文档 | 归档记录、文档更新、Git 提交 | | chenlin | 陈琳 | 文档 | 文档、归档、Git提交 |
### 协作流水线 ### 协作流水线
``` ```
刘备(协调) → 诸葛亮(分析) → {关羽|赵云}(修复) → 荀彧(DB审查) → 张飞(测试) → 华佗(验收) → 陈琳(归档) 刘备(协调) → 诸葛亮(分析路由) → {关羽|赵云}(修复) → 荀彧(DB审查) → 张飞(测试) → 华佗(验收) → 陈琳(归档)
```
### Bug 修复完整管线（BDT 方法论）
```
获取Bug → 设计测试用例 → 基线测试(应失败) → 全链路修复 → 回归测试(应通过) → 扩展测试(无回归) → 提交
``` ```
### Bug 状态管理铁律 ### Bug 状态管理铁律
- 人类提的 Bug：只加备注，不改状态，不改分配 - 人类提的 Bug：只加备注，不改状态，不改分配
- 智能体提的 Bug：可以改分配和加备注 - 智能体提的 Bug：可以改分配和加备注
- 已关闭/已解决的 Bug 不再处理 - 已关闭/已解决的 Bug 不再处理
### 修复流程铁律 ---
- 一次只修一个 Bug，不扩大范围 ## 十一、审查与审计
- 修复前必须读 AGENTS.md
- 修复后必须验证编译
- 涉及 SQL 必须先查真实数据库
### 测试流程铁律 ### 三层审查体系
- Playwright 必须 `--workers=1` 单线程 | 层级 | 内容 | 时机 |
- 超时 120 秒 |------|------|------|
- 最多重试 3 次 | **L1 自审** | Agent 对照约束逐条检查 | 每次提交前 |
- 测试结果写入禅道备注 | **L2 配对审查** | Agent 生成变更摘要，人类终审 | PR/提交时 |
| **L3 合规审查** | 审计追踪，记录所有 AI 操作 | 持续 |
### 归档流程铁律 ### L1 自审清单
```yaml
self_review:
- "所有修改能通过编译？"
- "遵守命名规范？"
- "测试覆盖达标？"
- "没有遗漏的 TODO / DEBUG？"
- "变更范围没超出任务边界？"
```
- 三重归档：Git + SQLite + Redis ### 评审评分维度
- SQLite 必须使用完整字段 | 维度 | 问题 |
- 禅道备注格式：`[📝 陈琳归档] Bug #xxx` |------|------|
| 正确性 | 行为是否符合目标功能？ |
| 验证 | 检查是否真的跑过并留下证据？ |
| 范围纪律 | 是否保持在选定功能范围内？ |
| 可靠性 | 结果能否在重启后继续工作？ |
| 可维护性 | 代码和文档是否清楚到可交接？ |
--- ---
## 九、开发流程 ## 十二、标准工作循环
```
开始会话
├→ 1. Init — 读 AGENTS.md + PROGRESS.md + git log
├→ 2. Select — 只选一个未完成功能
├→ 3. Implement — 一次只做一个，不扩大范围
├→ 4. Verify — 运行验证命令，有证据才标记完成
└→ 5. Cleanup — 更新进度 + clean-state-checklist + git commit
```
### 会话结束前必须运行 Clean State Checklist
```
□ 标准启动路径仍然可用
□ 标准验证路径仍然可运行
□ 当前进度已记录到进度日志
□ 无半成品步骤处于未记录状态
□ 下一轮会话无需人工修复即可继续
```
---
## 十三、开发流程
``` ```
收到任务 收到任务
@@ -367,64 +411,60 @@ scope: 模块名(如 registration, billing, pharmacy)
--- ---
## 十、快速参考命令 ## 十四、快速参考命令
```bash ```bash
# === 后端 === # === 后端 ===
export JAVA_HOME=/opt/jdk-25 export JAVA_HOME=/opt/jdk-25
mvn clean compile -DskipTests # 编译 mvn clean compile -DskipTests # 编译
mvn install -DskipTests # 完整构建 mvn install -DskipTests # 构建
mvn test -pl healthlink-his-application -Dtest="XxxTest" -Dsurefire.failIfNoSpecifiedTests=false # 测试 mvn test -pl healthlink-his-application -Dtest="XxxTest" -Dsurefire.failIfNoSpecifiedTests=false
# === 前端 === # === 前端 ===
cd healthlink-his-ui cd healthlink-his-ui
npm run dev # 开发模式 npm run dev && npm run build:dev && npm run lint && npm run test:run
npm run build:dev # 构建
npm run lint # 代码检查
npm run test:run # 单元测试
# === Git === # === Git ===
git status # 查看变更 git status && git add -A && git commit -m "feat(module): desc" && git push origin develop
git add -A # 暂存所有
git commit -m "feat(module): description" # 提交
git push origin develop # 推送
``` ```
--- ---
## 十一、详细规范文档索引 ## 十五、详细规范文档索引
| 文档 | 路径 | 用途 | | 文档 | 路径 | 用途 |
|------|------|------| |------|------|------|
| 执行铁律 | `MD/specs/IRON_RULES.md` | 铁律完整版 | | 执行铁律 | `MD/specs/IRON_RULES.md` | 铁律完整版 |
| 后端规范 | `MD/specs/BACKEND_DEVELOPMENT_STANDARD.md` | 后端编码标准 | | 后端规范 | `MD/specs/BACKEND_DEVELOPMENT_STANDARD.md` | 后端编码标准 |
| 前端规范 | `MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md` | 前端编码标准 | | 前端规范 | `MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md` | 前端编码标准 |
| Harness方法论 | `MD/specs/HARNESS_ENGINEERING.md` | 完整Harness+Agent方法论 |
| 文档规范 | `MD/DOCUMENTATION_STANDARD.md` | 文档管理标准 | | 文档规范 | `MD/DOCUMENTATION_STANDARD.md` | 文档管理标准 |
| 后端清单 | `MD/specs/BACKEND_CHECKLIST.md` | 发布前检查 | | 后端清单 | `MD/specs/BACKEND_CHECKLIST.md` | 发布前检查 |
| 前端清单 | `MD/specs/FRONTEND_CHECKLIST.md` | 发布前检查 | | 前端清单 | `MD/specs/FRONTEND_CHECKLIST.md` | 发布前检查 |
| 三甲标准 | `MD/standards/GRADE3A_HIS_STANDARD.md` | 三甲医院达标标准 | | 三甲标准 | `MD/standards/GRADE3A_HIS_STANDARD.md` | 三甲医院达标标准 |
| Flyway指南 | `MD/guides/FLYWAY_USAGE_GUIDE.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: 签到设 BOOKED(1) 而非 CHECKED_IN(3)，前端映射缺失 → 必须走完整状态链路 |
| 盲删源文件 | Bug #574 | AI 看到编译错误直接删文件，没检查是否在 baseline → 必须先确认文件来源再操作 | | 盲删源文件 | AI 看到编译错误直接删文件，没检查 baseline → 必须先确认文件来源 |
| 修复方向偏差 | Bug #574 | 多次 fallback 改的是 OrderServiceImpl，完全没触及 TicketServiceImpl → 必须用 rg 搜索所有相关代码路径 | | 修复方向偏差 | 多次 fallback 改的是错误的 Service → 必须用 rg 搜索所有相关代码路径 |
| bug_reports 表缺少列 | 经验 | INSERT 会静默失败，必须检查表结构 | | bug_reports 缺列 | INSERT 静默失败 → 必须检查表结构 |
| 禅道 comment API | 经验 | API 不存在，必须用 resolve+activate workaround | | 禅道 comment API | API 不存在，用 resolve+activate workaround |
| SQLite WAL 并发 | 经验 | 多进程并发写需要 checkpoint | | SQLite WAL 并发 | 多进程并发写需要 checkpoint |
| UTF-8 切片 | 经验 | 多字节字符不能用 byte index 切片 | | UTF-8 切片 | 多字节字符不能用 byte index 切片 |
| 禅道图片附件 | 经验 | 必须 OCR 读取，不能直接解析 | | 上下文焦虑 | Agent 感觉上下文快满时会匆忙结束，跳过验证 → 注意 context 40% 阈值 |
| 过早宣告胜利 | 自评≠验证，分开"干活"和"检查" |
| 覆盖率幻觉 | 覆盖率达标但逻辑没测 → 引入变异测试 |
--- ---
> ⚠️ **警告**: 本文件是项目 AI 开发规范的唯一信源。各工具配置文件（AGENTS.md、.cursorrules 等）均通过 `bash scripts/sync-ai-rules.sh` 从本文件同步。修改规范请只修改本文件。 > ⚠️ 本文件是 AI 开发规范的唯一信源。各工具配置文件由 `bash scripts/sync-ai-rules.sh` 同步。
--- ---
> 📅 最后同步: 2026-06-06 09:56 | 源文件: RULES.md | 重新同步: `bash scripts/sync-ai-rules.sh` > 📅 最后同步: 2026-06-06 10:01 | 源文件: RULES.md | 重新同步: `bash scripts/sync-ai-rules.sh`

382
.windsurfrules
View File

@@ -6,7 +6,7 @@
# HealthLink-HIS — AI 开发规范（自动加载） # HealthLink-HIS — AI 开发规范（自动加载）
> 🤖 **本文件供所有 AI 编码工具自动读取**。无论使用 Claude Code、Cursor、Codex CLI、Copilot、Qwen、Cline 还是其他工具，进入本项目后必须遵守以下规范。 > 🤖 **本文件供所有 AI 编码工具自动读取**。进入本项目后必须遵守以下规范。
> >
> **模型决定上限，Harness 决定底线。** > **模型决定上限，Harness 决定底线。**
@@ -48,7 +48,6 @@
- 凡是新建表、新增字段，必须创建 Flyway 迁移脚本 - 凡是新建表、新增字段，必须创建 Flyway 迁移脚本
- 路径：`healthlink-his-domain/src/main/resources/db/migration/` - 路径：`healthlink-his-domain/src/main/resources/db/migration/`
- 命名：`V{版本号}__{描述}.sql`（双下划线） - 命名：`V{版本号}__{描述}.sql`（双下划线）
- 禁止直接在数据库执行 SQL 不走 Flyway
**铁律3: 测试通过后才提交** **铁律3: 测试通过后才提交**
- 编译 + 测试全部通过后才能 git commit - 编译 + 测试全部通过后才能 git commit
@@ -57,59 +56,80 @@
**铁律4: 前后端API路径对齐** **铁律4: 前后端API路径对齐**
- 后端前缀：`/healthlink-his/api/v1/` - 后端前缀：`/healthlink-his/api/v1/`
- 前端 `request.js` 的 baseURL 必须与后端匹配 - 前端 `request.js` 的 baseURL 必须与后端匹配
- 接口变更必须同步更新前后端代码
**铁律5: 状态值一致性（来自 Bug #574 教训）** **铁律5: 状态值一致性（Bug #574 教训）**
- 修改任何状态值前，必须先列出完整的状态流转链路 - 修改任何状态值前，必须先列出完整的状态流转链路
- 检查项： - 检查项：枚举定义 → Service 设置 → 查询映射 → 前端 STATUS_CLASS_MAP → 前端 v-if → 统计SQL
1. 枚举定义的值是否正确
2. Service 层设置的状态值是否与枚举一致
3. 查询/列表接口的状态映射是否覆盖所有枚举值
4. 前端 `STATUS_CLASS_MAP` 是否包含新状态
5. 前端过滤条件（如 `v-if`）是否兼容新状态
6. 池/统计表的聚合 SQL 是否包含新状态值
- 禁止：只改一端不检查其他端 - 禁止：只改一端不检查其他端
**铁律6: 禁止删除源文件（来自 Bug #574 教训）** **铁律6: 禁止删除源文件（Bug #574 教训）**
- 绝对禁止删除项目中已有的 Java/Vue/SQL 源文件 - 绝对禁止删除项目中已有的 Java/Vue/SQL 源文件
- 文件有编译错误 → 修复错误，不删除文件 - 编译错误 → 修复错误；重复文件 → 重构合并
- 文件是重复的 → 重构合并，不删除文件
- 文件是 AI 幻觉创建的 → 检查 git baseline 确认后再删除
- 唯一例外：明确由人类确认删除的文件 - 唯一例外：明确由人类确认删除的文件
**铁律7: 禁止修改已有公开方法签名** **铁律7: 禁止修改已有公开方法签名**
- 不能删除或重命名已有的 public 方法 - 不能删除/重命名已有的 public 方法，不能修改参数列表
- 不能修改已有方法的参数列表 - 需要新功能 → 添加重载方法；需要改行为 → 修改内部实现
- 需要新增功能时 → 添加新的重载方法
- 需要改行为时 → 修改方法内部实现，不改签名 **铁律8: 验证后才宣称完成（Verification Before Completion）**
- **没有跑过验证命令，就不能说"完成了""通过了""没问题"**
- 禁止使用"应该可以""大概没问题""看起来正确"
- 必须：运行命令 → 读取输出 → 确认结果 → 才能宣称
- 这是诚实原则，不是效率问题
### 🟡 P1 铁律 — 强烈建议 ### 🟡 P1 铁律 — 强烈建议
**铁律8: 先分解再行动** **铁律9: 先分解再行动**
- 修改超过3个文件、涉及多模块、数据库变更，必须先制定计划 - 修改超过3个文件、涉及多模块、数据库变更，必须先制定计划
**铁律9: 验证后信** **铁律10: 验证后信**
- 每次修改后必须验证编译通过，不信记忆 - 每次修改后必须验证编译通过，不信记忆
- 重新编译命令：`mvn clean compile -DskipTests`
**铁律10: 文档统一管理** **铁律11: 文档统一管理**
- 所有文档存储在 `MD/` 目录 - 所有文档存储在 `MD/` 目录
- 文件名：大写英文+下划线（如 `BACKEND_CHECKLIST.md`） - 文件名：大写英文+下划线（如 `BACKEND_CHECKLIST.md`）
- 文档头部必须包含元数据块（文档类型、版本、日期） - 文档头部必须包含元数据块（文档类型、版本、日期）
--- ---
## 三、全链路 6 环分析 ## 三、Karpathy 编码准则
> ⚠️ **涉及数据库字段的 Bug / 需求，必须走完整链路，不得"就事论事"。** > 减少 LLM 常见编码错误。偏向谨慎而非速度。
### 3.1 先想再写
- 明确陈述假设，不确定就问
- 多种解读时都列出来，不要默默选一种
- 有更简单的方案就说出来，该推回就推回
- 不清楚的地方停下来，说清楚哪里不清楚
### 3.2 简洁优先
- 不做没要求的功能，不做一次性代码的抽象
- 不加没要求的"灵活性"和"可配置性"
- 200 行能 50 行搞定就重写
- 自问："高级工程师会不会觉得这过度设计？"
### 3.3 精准修改
- 只改必须改的，不"顺手改进"相邻代码
- 匹配现有代码风格，即使你有不同的偏好
- 每行改动都能追溯到用户的请求
- 只清理你自己改动产生的无用代码
### 3.4 目标驱动
- 把任务转化为可验证目标
- 多步任务声明计划：`[步骤] → 验证: [检查]`
- 强验收标准让 Agent 能独立循环，弱标准需要持续澄清
---
## 四、全链路 6 环分析
> ⚠️ **涉及数据库字段的 Bug / 需求，必须走完整链路。**
``` ```
前端/页面 → Controller → Service → Mapper → DB/SQL → 关联模块 前端/页面 → Controller → Service → Mapper → DB/SQL → 关联模块
①录入 ②验证 ③业务 ④持久化 ⑤存储 ⑥联动 ①录入 ②验证 ③业务 ④持久化 ⑤存储 ⑥联动
``` ```
### 每一环必须确认
| 环 | 检查内容 | | 环 | 检查内容 |
|----|---------| |----|---------|
| ① 录入 | 前端有无输入入口（弹窗、表格行编辑、表单） | | ① 录入 | 前端有无输入入口（弹窗、表格行编辑、表单） |
@@ -119,104 +139,113 @@
| ⑤ 存储 | 数据库表结构、索引、NOT NULL 约束 | | ⑤ 存储 | 数据库表结构、索引、NOT NULL 约束 |
| ⑥ 联动 | 上游（医嘱→护士站）、下游（打印、计费、报表）是否同步 | | ⑥ 联动 | 上游（医嘱→护士站）、下游（打印、计费、报表）是否同步 |
### 全链路验证顺序 **修复后的验证顺序**：
1. 数据库：确认状态值已正确写入
修复涉及状态流转的问题后，必须按以下顺序验证： 2. 后端接口：确认返回的状态映射正确
1. **数据库**：确认状态值已正确写入 3. 前端显示：确认页面显示正确状态文本
2. **后端接口**：确认返回的状态映射正确 4. 前端交互：确认按钮/操作基于正确状态启用/禁用
3. **前端显示**：确认页面显示正确状态文本 5. 统计数据：确认池/报表统计包含新状态
4. **前端交互**：确认按钮/操作基于正确状态启用/禁用
5. **统计数据**：确认池/报表统计包含新状态
### 常见陷阱
- ❌ 只修了「主入口」的保存逻辑，忘了「批量保存」「签发保存」等其他入口
- ❌ 前端加了输入框，后端 Service 没传字段
- ❌ Mapper XML 是 UNION ALL 查询，只改了其中一个子查询
- ❌ DTO 层级继承关系没检查
- ❌ 只测了新增，没测编辑已有数据的回显和修改再保存
--- ---
## 四、Harness Engineering 方法论 ## 五、Harness Engineering 方法论
> Harness = 约束 + 反馈 + 控制平面 + 持久执行 > Harness = 约束 + 反馈 + 控制平面 + 持久执行
### 4.1 四层约束金字塔 ### 5.1 四层约束金字塔
| 层级 | 内容 | 落地方式 | | 层级 | 内容 | 落地方式 |
|------|------|---------| |------|------|---------|
| **L1 架构约束** | 接口合约、包结构、命名规范、禁止模式 | 本文件铁律、AGENTS.md | | **L1 架构约束** | 接口合约、包结构、命名规范、禁止模式 | 本文件铁律 |
| **L2 代码质量** | 圈复杂度、代码风格、类型提示 | 编译门禁 + ESLint | | **L2 代码质量** | 圈复杂度、代码风格、类型提示 | 编译门禁 + ESLint |
| **L3 安全约束** | 敏感信息检测、权限检查、输入验证 | 配置不可硬编码 | | **L3 安全约束** | 敏感信息检测、权限检查、输入验证 | 配置不可硬编码 |
| **L4 业务规则** | 领域逻辑、数据一致性、事务边界 | 全链路 6 环验证 | | **L4 业务规则** | 领域逻辑、数据一致性、事务边界 | 全链路 6 环验证 |
**约束优先级**：安全 > 架构 > 质量 > 业务 **约束设计原则**：
- **可验证**：每条约束必须能被自动化检查（"覆盖率>90%"✅ "质量要高"❌）
- **无歧义**："每函数不超过50行"✅ "函数不要太长"❌
- **优先级**：安全(1) > 架构(2) > 业务(3) > 质量(4) > 性能(5)
- **渐进增强**：L1编译通过 → L2+命名规范 → L3+测试覆盖 → L4+安全扫描
### 4.2 三层反馈系统 ### 5.2 三层反馈系统
| 层级 | 速度 | 覆盖范围 | 失败处理 | | 层级 | 速度 | 覆盖范围 | 失败处理 |
|------|------|---------|---------| |------|------|---------|---------|
| **L1 编译检查** | <30 秒 | 语法、类型、签名 | 立即阻断，自行修复 | | **L1 编译检查** | <30秒 | 语法、类型、签名 | 立即阻断，自行修复 |
| **L2 数据流验证** | <5 分钟 | 全链路字段、Mapper XML、DTO | 修复后上报 | | **L2 数据流验证** | <5分钟 | 全链路字段、Mapper XML、DTO | 修复后上报 |
| **L3 人工审查** | 10-30 分钟 | 架构、设计、业务正确性 | 驳回 / 指导 / 批准 | | **L3 人工审查** | 10-30分钟 | 架构、设计、业务正确性 | 驳回/指导/批准 |
**反馈设计铁律**： **反馈铁律**：
- 反馈必须可行动（指出：文件 + 行号 + 错误类型 + 修复方向） - 反馈必须可行动（文件 + 行号 + 错误类型 + 修复方向）
- 反馈越及时越好（L1 即时 → L2 分钟 → L3 小时）
- 失败后先回滚到最近检查点，再重试 - 失败后先回滚到最近检查点，再重试
- 持续失败3次 → 上报人类
### 4.3 控制平面（Agent 协调） ### 5.3 控制平面
``` ```
┌─────────────────────────────────────────────┐ 战略层（人类） → 设定目标、审批决策、异常升级
│ 战略层（人类主导） │ 战术层（Agent） → 任务分解、update_plan、依赖协调、检查点保存
│ ├── 设定目标、审批关键决策 │ 执行层（Agent） → 代码生成、测试执行、错误恢复、幂等重试
│ └── 异常升级处理 │
├─────────────────────────────────────────────┤
│ 战术层（Control Plane） │
│ ├── 任务分解 + update_plan │
│ ├── 依赖协调 + 资源分配 │
│ └── 检查点保存 + 恢复 │
├─────────────────────────────────────────────┤
│ 执行层（Agent 自主） │
│ ├── 代码生成、测试执行 │
│ └── 错误恢复 + 幂等重试 │
└─────────────────────────────────────────────┘
``` ```
### 4.4 持久执行 ### 5.4 持久执行
- 每个关键步骤保存检查点（`update_plan` 进度） - 每个关键步骤保存检查点（`update_plan` 进度）
- 失败后从最新检查点恢复，不从头开始 - 失败后从最新检查点恢复，不从头开始
- 幂等设计：同一操作重复执行结果一致 - 幂等设计：同一操作重复执行结果一致
- **三层状态管理**：系统层(工作流ID/超时/重试) → 执行层(当前活动/进度) → 业务层(已完成工作/中间产物)
--- ---
## 五、质量门禁（5 级） ## 六、五层质量门禁
| 级别 | 门禁 | 通过标准 | | 门禁 | 时间 | 范围 | 失败处理 |
|------|------|---------| |------|------|------|---------|
| **L1** | 编译通过 | `mvn clean compile` + `npm run build:dev` 无 ERROR | | **L1 编译检查** | <30秒 | 语法、类型、导入 | Agent 自行修复 |
| **L2** | 测试通过 | 单元测试 + 接口测试全部通过 | | **L2 静态分析** | <2分钟 | 代码风格、复杂度、安全 | Agent 修复 |
| **L3** | DB 审查 | Flyway 脚本规范、SQL 安全、索引合理 | | **L3 单元测试** | <5分钟 | 功能正确性、边界条件 | 自动修复或上报 |
| **L4** | 验收通过 | 核心功能流程完整验证、全链路检查 | | **L4 集成测试** | <15分钟 | 模块间交互、数据流 | 上报人工 |
| **L5** | 归档完成 | Git commit + 文档更新 + 代码推送 | | **L5 生产验证** | 持续 | 监控、告警、性能 | 自动回滚 |
### 提交铁律 **提交铁律**：L1-L2 必须通过才能 commit，L3（如有DB变更）必须通过才能 push
- L1-L2 必须通过才能 commit
- L3（如有DB变更）必须通过才能 push
- L4-L5 发布前必须完成
--- ---
## 六、后端开发规范 ## 七、系统化调试（Systematic Debugging）
> **铁律：没有根因调查，不能提出修复方案。**
### 四阶段流程
**阶段1：根因调查**（修复前必须完成）
1. 仔细阅读错误信息（堆栈、行号、错误码）
2. 稳定复现（能否可靠触发？步骤？每次？）
3. 检查最近变更（git diff、新依赖、配置变更）
4. 多组件系统：在每个组件边界加诊断日志，定位哪一层断裂
5. 追踪数据流：坏值从哪里来？谁调用的？一直追溯到源头
**阶段2：模式分析**
- 找到同代码库中类似的正常工作代码
- 逐项对比差异
- 理解依赖关系
**阶段3：假设与测试**
- 形成单一假设："我认为X是根因，因为Y"
- 做最小改动测试
- 有效 → 阶段4；无效 → 新假设
**阶段4：实施**
- 创建失败测试用例
- 修复根因（不是症状）
- 验证修复
---
## 八、后端开发规范
### 分层架构 ### 分层架构
``` ```
Controller → AppService → Service → Mapper → Entity Controller → AppService → Service → Mapper → Entity
接收请求 编排业务 单表CRUD 数据访问 实体定义
``` ```
### 命名规范 ### 命名规范
@@ -240,110 +269,125 @@ com.healthlink.his.domain.{module}
com.healthlink.his.common.enums com.healthlink.his.common.enums
``` ```
### 统一返回格式
```java
AjaxResult.success(data) // 成功
AjaxResult.error("错误信息") // 失败
getDataTable(list) // 列表
```
### 关键约束 ### 关键约束
- 所有查询使用 `LambdaQueryWrapper`，禁止字符串拼接 SQL - 所有查询使用 `LambdaQueryWrapper`，禁止字符串拼接 SQL
- `@Transactional(rollbackFor = Exception.class)` 管理事务 - `@Transactional(rollbackFor = Exception.class)` 管理事务
- 所有接口标注 `@PreAuthorize` 权限控制 - 所有接口标注 `@PreAuthorize` 权限控制
- 患者敏感信息（身份证、手机号）在日志中脱敏 - 患者敏感信息在日志中脱敏
- **扩展功能不修改原有函数签名**，新建 Service/AppService - **扩展功能不修改原有函数签名**
- 涉及多表写操作的方法标注 `@Transactional`
- 事务方法未被同一类内方法直接调用（避免自调用失效）
--- ---
## 七、前端开发规范 ## 九、前端开发规范
### 技术栈 ### 技术栈
- Vue 3 + Vite + Element Plus + Pinia + Axios - Vue 3 + Vite + Element Plus + Pinia + Axios（基于 RuoYi-Vue3）
- 基于 RuoYi-Vue3 框架
### 目录结构 ### 目录结构
``` ```
src/api/{module}/ # API接口（kebab-case路径） src/api/{module}/ # API接口
src/views/{module}/ # 页面组件 src/views/{module}/ # 页面组件
src/store/modules/ # Pinia状态管理 src/store/modules/ # Pinia状态管理
src/components/ # 公共组件 src/components/ # 公共组件
``` ```
### API 路径规范
```javascript
// 统一前缀 /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` 指令
### 关键约束 ### 关键约束
- API前缀：`/healthlink-his/api/v1/`
- 路由懒加载：`() => import('@/views/xxx/index.vue')` - 路由懒加载：`() => import('@/views/xxx/index.vue')`
- 不使用 `v-html`（除非做 XSS 转义） - 页面使用 `<script setup>` 语法
- 不在前端硬编码密码、密钥 - 按钮权限使用 `v-hasPermi` 指令
- `onMounted` 中注册的事件在 `onUnmounted` 中移除 - `onMounted` 中注册的事件在 `onUnmounted` 中移除
--- ---
## 八、Agent 体系（智能体协作） ## 十、Agent 体系
### 角色定义 ### 角色与路由
| 代号 | 名称 | 角色 | 职责 | | 代号 | 名称 | 角色 | 路由关键词 |
|------|------|------|------| |------|------|------|-----------|
| liubei | 刘备 | 项目经理 | 总协调、任务分配、异常升级 | | liubei | 刘备 | 项目经理 | 协调、分派、异常升级 |
| zhugeliang | 诸葛亮 | 架构师 | 需求分析、方案设计、技术决策 | | zhugeliang | 诸葛亮 | 架构师 | 分析、路由、设计 |
| guanyu | 关羽 | 后端开发 | Java 后端修复、API 开发 | | guanyu | 关羽 | 后端开发 | java, api, spring, service, controller |
| zhaoyun | 赵云 | 前端开发 | Vue 前端修复、页面开发 | | zhaoyun | 赵云 | 前端开发 | vue, 界面, 显示, 弹窗, 按钮 |
| xunyu | 荀彧 | DBA | 数据库审查、SQL 优化、Flyway 脚本 | | xunyu | 荀彧 | DBA | 数据库, sql, 迁移, mapper xml |
| zhangfei | 张飞 | 测试 | Playwright 测试、接口测试、回归测试 | | zhangfei | 张飞 | 测试 | 测试, QA, 回归 |
| huatuo | 华佗 | 验收 | 功能验收、质量确认、发布检查 | | huatuo | 华佗 | 验收 | 需求验收、质量确认 |
| chenlin | 陈琳 | 文档 | 归档记录、文档更新、Git 提交 | | chenlin | 陈琳 | 文档 | 文档、归档、Git提交 |
### 协作流水线 ### 协作流水线
``` ```
刘备(协调) → 诸葛亮(分析) → {关羽|赵云}(修复) → 荀彧(DB审查) → 张飞(测试) → 华佗(验收) → 陈琳(归档) 刘备(协调) → 诸葛亮(分析路由) → {关羽|赵云}(修复) → 荀彧(DB审查) → 张飞(测试) → 华佗(验收) → 陈琳(归档)
```
### Bug 修复完整管线（BDT 方法论）
```
获取Bug → 设计测试用例 → 基线测试(应失败) → 全链路修复 → 回归测试(应通过) → 扩展测试(无回归) → 提交
``` ```
### Bug 状态管理铁律 ### Bug 状态管理铁律
- 人类提的 Bug：只加备注，不改状态，不改分配 - 人类提的 Bug：只加备注，不改状态，不改分配
- 智能体提的 Bug：可以改分配和加备注 - 智能体提的 Bug：可以改分配和加备注
- 已关闭/已解决的 Bug 不再处理 - 已关闭/已解决的 Bug 不再处理
### 修复流程铁律 ---
- 一次只修一个 Bug，不扩大范围 ## 十一、审查与审计
- 修复前必须读 AGENTS.md
- 修复后必须验证编译
- 涉及 SQL 必须先查真实数据库
### 测试流程铁律 ### 三层审查体系
- Playwright 必须 `--workers=1` 单线程 | 层级 | 内容 | 时机 |
- 超时 120 秒 |------|------|------|
- 最多重试 3 次 | **L1 自审** | Agent 对照约束逐条检查 | 每次提交前 |
- 测试结果写入禅道备注 | **L2 配对审查** | Agent 生成变更摘要，人类终审 | PR/提交时 |
| **L3 合规审查** | 审计追踪，记录所有 AI 操作 | 持续 |
### 归档流程铁律 ### L1 自审清单
```yaml
self_review:
- "所有修改能通过编译？"
- "遵守命名规范？"
- "测试覆盖达标？"
- "没有遗漏的 TODO / DEBUG？"
- "变更范围没超出任务边界？"
```
- 三重归档：Git + SQLite + Redis ### 评审评分维度
- SQLite 必须使用完整字段 | 维度 | 问题 |
- 禅道备注格式：`[📝 陈琳归档] Bug #xxx` |------|------|
| 正确性 | 行为是否符合目标功能？ |
| 验证 | 检查是否真的跑过并留下证据？ |
| 范围纪律 | 是否保持在选定功能范围内？ |
| 可靠性 | 结果能否在重启后继续工作？ |
| 可维护性 | 代码和文档是否清楚到可交接？ |
--- ---
## 九、开发流程 ## 十二、标准工作循环
```
开始会话
├→ 1. Init — 读 AGENTS.md + PROGRESS.md + git log
├→ 2. Select — 只选一个未完成功能
├→ 3. Implement — 一次只做一个，不扩大范围
├→ 4. Verify — 运行验证命令，有证据才标记完成
└→ 5. Cleanup — 更新进度 + clean-state-checklist + git commit
```
### 会话结束前必须运行 Clean State Checklist
```
□ 标准启动路径仍然可用
□ 标准验证路径仍然可运行
□ 当前进度已记录到进度日志
□ 无半成品步骤处于未记录状态
□ 下一轮会话无需人工修复即可继续
```
---
## 十三、开发流程
``` ```
收到任务 收到任务
@@ -367,64 +411,60 @@ scope: 模块名(如 registration, billing, pharmacy)
--- ---
## 十、快速参考命令 ## 十四、快速参考命令
```bash ```bash
# === 后端 === # === 后端 ===
export JAVA_HOME=/opt/jdk-25 export JAVA_HOME=/opt/jdk-25
mvn clean compile -DskipTests # 编译 mvn clean compile -DskipTests # 编译
mvn install -DskipTests # 完整构建 mvn install -DskipTests # 构建
mvn test -pl healthlink-his-application -Dtest="XxxTest" -Dsurefire.failIfNoSpecifiedTests=false # 测试 mvn test -pl healthlink-his-application -Dtest="XxxTest" -Dsurefire.failIfNoSpecifiedTests=false
# === 前端 === # === 前端 ===
cd healthlink-his-ui cd healthlink-his-ui
npm run dev # 开发模式 npm run dev && npm run build:dev && npm run lint && npm run test:run
npm run build:dev # 构建
npm run lint # 代码检查
npm run test:run # 单元测试
# === Git === # === Git ===
git status # 查看变更 git status && git add -A && git commit -m "feat(module): desc" && git push origin develop
git add -A # 暂存所有
git commit -m "feat(module): description" # 提交
git push origin develop # 推送
``` ```
--- ---
## 十一、详细规范文档索引 ## 十五、详细规范文档索引
| 文档 | 路径 | 用途 | | 文档 | 路径 | 用途 |
|------|------|------| |------|------|------|
| 执行铁律 | `MD/specs/IRON_RULES.md` | 铁律完整版 | | 执行铁律 | `MD/specs/IRON_RULES.md` | 铁律完整版 |
| 后端规范 | `MD/specs/BACKEND_DEVELOPMENT_STANDARD.md` | 后端编码标准 | | 后端规范 | `MD/specs/BACKEND_DEVELOPMENT_STANDARD.md` | 后端编码标准 |
| 前端规范 | `MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md` | 前端编码标准 | | 前端规范 | `MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md` | 前端编码标准 |
| Harness方法论 | `MD/specs/HARNESS_ENGINEERING.md` | 完整Harness+Agent方法论 |
| 文档规范 | `MD/DOCUMENTATION_STANDARD.md` | 文档管理标准 | | 文档规范 | `MD/DOCUMENTATION_STANDARD.md` | 文档管理标准 |
| 后端清单 | `MD/specs/BACKEND_CHECKLIST.md` | 发布前检查 | | 后端清单 | `MD/specs/BACKEND_CHECKLIST.md` | 发布前检查 |
| 前端清单 | `MD/specs/FRONTEND_CHECKLIST.md` | 发布前检查 | | 前端清单 | `MD/specs/FRONTEND_CHECKLIST.md` | 发布前检查 |
| 三甲标准 | `MD/standards/GRADE3A_HIS_STANDARD.md` | 三甲医院达标标准 | | 三甲标准 | `MD/standards/GRADE3A_HIS_STANDARD.md` | 三甲医院达标标准 |
| Flyway指南 | `MD/guides/FLYWAY_USAGE_GUIDE.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: 签到设 BOOKED(1) 而非 CHECKED_IN(3)，前端映射缺失 → 必须走完整状态链路 |
| 盲删源文件 | Bug #574 | AI 看到编译错误直接删文件，没检查是否在 baseline → 必须先确认文件来源再操作 | | 盲删源文件 | AI 看到编译错误直接删文件，没检查 baseline → 必须先确认文件来源 |
| 修复方向偏差 | Bug #574 | 多次 fallback 改的是 OrderServiceImpl，完全没触及 TicketServiceImpl → 必须用 rg 搜索所有相关代码路径 | | 修复方向偏差 | 多次 fallback 改的是错误的 Service → 必须用 rg 搜索所有相关代码路径 |
| bug_reports 表缺少列 | 经验 | INSERT 会静默失败，必须检查表结构 | | bug_reports 缺列 | INSERT 静默失败 → 必须检查表结构 |
| 禅道 comment API | 经验 | API 不存在，必须用 resolve+activate workaround | | 禅道 comment API | API 不存在，用 resolve+activate workaround |
| SQLite WAL 并发 | 经验 | 多进程并发写需要 checkpoint | | SQLite WAL 并发 | 多进程并发写需要 checkpoint |
| UTF-8 切片 | 经验 | 多字节字符不能用 byte index 切片 | | UTF-8 切片 | 多字节字符不能用 byte index 切片 |
| 禅道图片附件 | 经验 | 必须 OCR 读取，不能直接解析 | | 上下文焦虑 | Agent 感觉上下文快满时会匆忙结束，跳过验证 → 注意 context 40% 阈值 |
| 过早宣告胜利 | 自评≠验证，分开"干活"和"检查" |
| 覆盖率幻觉 | 覆盖率达标但逻辑没测 → 引入变异测试 |
--- ---
> ⚠️ **警告**: 本文件是项目 AI 开发规范的唯一信源。各工具配置文件（AGENTS.md、.cursorrules 等）均通过 `bash scripts/sync-ai-rules.sh` 从本文件同步。修改规范请只修改本文件。 > ⚠️ 本文件是 AI 开发规范的唯一信源。各工具配置文件由 `bash scripts/sync-ai-rules.sh` 同步。
--- ---
> 📅 最后同步: 2026-06-06 09:56 | 源文件: RULES.md | 重新同步: `bash scripts/sync-ai-rules.sh` > 📅 最后同步: 2026-06-06 10:01 | 源文件: RULES.md | 重新同步: `bash scripts/sync-ai-rules.sh`

382
AGENTS.md
View File

@@ -7,7 +7,7 @@
# HealthLink-HIS — AI 开发规范（自动加载） # HealthLink-HIS — AI 开发规范（自动加载）
> 🤖 **本文件供所有 AI 编码工具自动读取**。无论使用 Claude Code、Cursor、Codex CLI、Copilot、Qwen、Cline 还是其他工具，进入本项目后必须遵守以下规范。 > 🤖 **本文件供所有 AI 编码工具自动读取**。进入本项目后必须遵守以下规范。
> >
> **模型决定上限，Harness 决定底线。** > **模型决定上限，Harness 决定底线。**
@@ -49,7 +49,6 @@
- 凡是新建表、新增字段，必须创建 Flyway 迁移脚本 - 凡是新建表、新增字段，必须创建 Flyway 迁移脚本
- 路径：`healthlink-his-domain/src/main/resources/db/migration/` - 路径：`healthlink-his-domain/src/main/resources/db/migration/`
- 命名：`V{版本号}__{描述}.sql`（双下划线） - 命名：`V{版本号}__{描述}.sql`（双下划线）
- 禁止直接在数据库执行 SQL 不走 Flyway
**铁律3: 测试通过后才提交** **铁律3: 测试通过后才提交**
- 编译 + 测试全部通过后才能 git commit - 编译 + 测试全部通过后才能 git commit
@@ -58,59 +57,80 @@
**铁律4: 前后端API路径对齐** **铁律4: 前后端API路径对齐**
- 后端前缀：`/healthlink-his/api/v1/` - 后端前缀：`/healthlink-his/api/v1/`
- 前端 `request.js` 的 baseURL 必须与后端匹配 - 前端 `request.js` 的 baseURL 必须与后端匹配
- 接口变更必须同步更新前后端代码
**铁律5: 状态值一致性（来自 Bug #574 教训）** **铁律5: 状态值一致性（Bug #574 教训）**
- 修改任何状态值前，必须先列出完整的状态流转链路 - 修改任何状态值前，必须先列出完整的状态流转链路
- 检查项： - 检查项：枚举定义 → Service 设置 → 查询映射 → 前端 STATUS_CLASS_MAP → 前端 v-if → 统计SQL
1. 枚举定义的值是否正确
2. Service 层设置的状态值是否与枚举一致
3. 查询/列表接口的状态映射是否覆盖所有枚举值
4. 前端 `STATUS_CLASS_MAP` 是否包含新状态
5. 前端过滤条件（如 `v-if`）是否兼容新状态
6. 池/统计表的聚合 SQL 是否包含新状态值
- 禁止：只改一端不检查其他端 - 禁止：只改一端不检查其他端
**铁律6: 禁止删除源文件（来自 Bug #574 教训）** **铁律6: 禁止删除源文件（Bug #574 教训）**
- 绝对禁止删除项目中已有的 Java/Vue/SQL 源文件 - 绝对禁止删除项目中已有的 Java/Vue/SQL 源文件
- 文件有编译错误 → 修复错误，不删除文件 - 编译错误 → 修复错误；重复文件 → 重构合并
- 文件是重复的 → 重构合并，不删除文件
- 文件是 AI 幻觉创建的 → 检查 git baseline 确认后再删除
- 唯一例外：明确由人类确认删除的文件 - 唯一例外：明确由人类确认删除的文件
**铁律7: 禁止修改已有公开方法签名** **铁律7: 禁止修改已有公开方法签名**
- 不能删除或重命名已有的 public 方法 - 不能删除/重命名已有的 public 方法，不能修改参数列表
- 不能修改已有方法的参数列表 - 需要新功能 → 添加重载方法；需要改行为 → 修改内部实现
- 需要新增功能时 → 添加新的重载方法
- 需要改行为时 → 修改方法内部实现，不改签名 **铁律8: 验证后才宣称完成（Verification Before Completion）**
- **没有跑过验证命令，就不能说"完成了""通过了""没问题"**
- 禁止使用"应该可以""大概没问题""看起来正确"
- 必须：运行命令 → 读取输出 → 确认结果 → 才能宣称
- 这是诚实原则，不是效率问题
### 🟡 P1 铁律 — 强烈建议 ### 🟡 P1 铁律 — 强烈建议
**铁律8: 先分解再行动** **铁律9: 先分解再行动**
- 修改超过3个文件、涉及多模块、数据库变更，必须先制定计划 - 修改超过3个文件、涉及多模块、数据库变更，必须先制定计划
**铁律9: 验证后信** **铁律10: 验证后信**
- 每次修改后必须验证编译通过，不信记忆 - 每次修改后必须验证编译通过，不信记忆
- 重新编译命令：`mvn clean compile -DskipTests`
**铁律10: 文档统一管理** **铁律11: 文档统一管理**
- 所有文档存储在 `MD/` 目录 - 所有文档存储在 `MD/` 目录
- 文件名：大写英文+下划线（如 `BACKEND_CHECKLIST.md`） - 文件名：大写英文+下划线（如 `BACKEND_CHECKLIST.md`）
- 文档头部必须包含元数据块（文档类型、版本、日期） - 文档头部必须包含元数据块（文档类型、版本、日期）
--- ---
## 三、全链路 6 环分析 ## 三、Karpathy 编码准则
> ⚠️ **涉及数据库字段的 Bug / 需求，必须走完整链路，不得"就事论事"。** > 减少 LLM 常见编码错误。偏向谨慎而非速度。
### 3.1 先想再写
- 明确陈述假设，不确定就问
- 多种解读时都列出来，不要默默选一种
- 有更简单的方案就说出来，该推回就推回
- 不清楚的地方停下来，说清楚哪里不清楚
### 3.2 简洁优先
- 不做没要求的功能，不做一次性代码的抽象
- 不加没要求的"灵活性"和"可配置性"
- 200 行能 50 行搞定就重写
- 自问："高级工程师会不会觉得这过度设计？"
### 3.3 精准修改
- 只改必须改的，不"顺手改进"相邻代码
- 匹配现有代码风格，即使你有不同的偏好
- 每行改动都能追溯到用户的请求
- 只清理你自己改动产生的无用代码
### 3.4 目标驱动
- 把任务转化为可验证目标
- 多步任务声明计划：`[步骤] → 验证: [检查]`
- 强验收标准让 Agent 能独立循环，弱标准需要持续澄清
---
## 四、全链路 6 环分析
> ⚠️ **涉及数据库字段的 Bug / 需求，必须走完整链路。**
``` ```
前端/页面 → Controller → Service → Mapper → DB/SQL → 关联模块 前端/页面 → Controller → Service → Mapper → DB/SQL → 关联模块
①录入 ②验证 ③业务 ④持久化 ⑤存储 ⑥联动 ①录入 ②验证 ③业务 ④持久化 ⑤存储 ⑥联动
``` ```
### 每一环必须确认
| 环 | 检查内容 | | 环 | 检查内容 |
|----|---------| |----|---------|
| ① 录入 | 前端有无输入入口（弹窗、表格行编辑、表单） | | ① 录入 | 前端有无输入入口（弹窗、表格行编辑、表单） |
@@ -120,104 +140,113 @@
| ⑤ 存储 | 数据库表结构、索引、NOT NULL 约束 | | ⑤ 存储 | 数据库表结构、索引、NOT NULL 约束 |
| ⑥ 联动 | 上游（医嘱→护士站）、下游（打印、计费、报表）是否同步 | | ⑥ 联动 | 上游（医嘱→护士站）、下游（打印、计费、报表）是否同步 |
### 全链路验证顺序 **修复后的验证顺序**：
1. 数据库：确认状态值已正确写入
修复涉及状态流转的问题后，必须按以下顺序验证： 2. 后端接口：确认返回的状态映射正确
1. **数据库**：确认状态值已正确写入 3. 前端显示：确认页面显示正确状态文本
2. **后端接口**：确认返回的状态映射正确 4. 前端交互：确认按钮/操作基于正确状态启用/禁用
3. **前端显示**：确认页面显示正确状态文本 5. 统计数据：确认池/报表统计包含新状态
4. **前端交互**：确认按钮/操作基于正确状态启用/禁用
5. **统计数据**：确认池/报表统计包含新状态
### 常见陷阱
- ❌ 只修了「主入口」的保存逻辑，忘了「批量保存」「签发保存」等其他入口
- ❌ 前端加了输入框，后端 Service 没传字段
- ❌ Mapper XML 是 UNION ALL 查询，只改了其中一个子查询
- ❌ DTO 层级继承关系没检查
- ❌ 只测了新增，没测编辑已有数据的回显和修改再保存
--- ---
## 四、Harness Engineering 方法论 ## 五、Harness Engineering 方法论
> Harness = 约束 + 反馈 + 控制平面 + 持久执行 > Harness = 约束 + 反馈 + 控制平面 + 持久执行
### 4.1 四层约束金字塔 ### 5.1 四层约束金字塔
| 层级 | 内容 | 落地方式 | | 层级 | 内容 | 落地方式 |
|------|------|---------| |------|------|---------|
| **L1 架构约束** | 接口合约、包结构、命名规范、禁止模式 | 本文件铁律、AGENTS.md | | **L1 架构约束** | 接口合约、包结构、命名规范、禁止模式 | 本文件铁律 |
| **L2 代码质量** | 圈复杂度、代码风格、类型提示 | 编译门禁 + ESLint | | **L2 代码质量** | 圈复杂度、代码风格、类型提示 | 编译门禁 + ESLint |
| **L3 安全约束** | 敏感信息检测、权限检查、输入验证 | 配置不可硬编码 | | **L3 安全约束** | 敏感信息检测、权限检查、输入验证 | 配置不可硬编码 |
| **L4 业务规则** | 领域逻辑、数据一致性、事务边界 | 全链路 6 环验证 | | **L4 业务规则** | 领域逻辑、数据一致性、事务边界 | 全链路 6 环验证 |
**约束优先级**：安全 > 架构 > 质量 > 业务 **约束设计原则**：
- **可验证**：每条约束必须能被自动化检查（"覆盖率>90%"✅ "质量要高"❌）
- **无歧义**："每函数不超过50行"✅ "函数不要太长"❌
- **优先级**：安全(1) > 架构(2) > 业务(3) > 质量(4) > 性能(5)
- **渐进增强**：L1编译通过 → L2+命名规范 → L3+测试覆盖 → L4+安全扫描
### 4.2 三层反馈系统 ### 5.2 三层反馈系统
| 层级 | 速度 | 覆盖范围 | 失败处理 | | 层级 | 速度 | 覆盖范围 | 失败处理 |
|------|------|---------|---------| |------|------|---------|---------|
| **L1 编译检查** | <30 秒 | 语法、类型、签名 | 立即阻断，自行修复 | | **L1 编译检查** | <30秒 | 语法、类型、签名 | 立即阻断，自行修复 |
| **L2 数据流验证** | <5 分钟 | 全链路字段、Mapper XML、DTO | 修复后上报 | | **L2 数据流验证** | <5分钟 | 全链路字段、Mapper XML、DTO | 修复后上报 |
| **L3 人工审查** | 10-30 分钟 | 架构、设计、业务正确性 | 驳回 / 指导 / 批准 | | **L3 人工审查** | 10-30分钟 | 架构、设计、业务正确性 | 驳回/指导/批准 |
**反馈设计铁律**： **反馈铁律**：
- 反馈必须可行动（指出：文件 + 行号 + 错误类型 + 修复方向） - 反馈必须可行动（文件 + 行号 + 错误类型 + 修复方向）
- 反馈越及时越好（L1 即时 → L2 分钟 → L3 小时）
- 失败后先回滚到最近检查点，再重试 - 失败后先回滚到最近检查点，再重试
- 持续失败3次 → 上报人类
### 4.3 控制平面（Agent 协调） ### 5.3 控制平面
``` ```
┌─────────────────────────────────────────────┐ 战略层（人类） → 设定目标、审批决策、异常升级
│ 战略层（人类主导） │ 战术层（Agent） → 任务分解、update_plan、依赖协调、检查点保存
│ ├── 设定目标、审批关键决策 │ 执行层（Agent） → 代码生成、测试执行、错误恢复、幂等重试
│ └── 异常升级处理 │
├─────────────────────────────────────────────┤
│ 战术层（Control Plane） │
│ ├── 任务分解 + update_plan │
│ ├── 依赖协调 + 资源分配 │
│ └── 检查点保存 + 恢复 │
├─────────────────────────────────────────────┤
│ 执行层（Agent 自主） │
│ ├── 代码生成、测试执行 │
│ └── 错误恢复 + 幂等重试 │
└─────────────────────────────────────────────┘
``` ```
### 4.4 持久执行 ### 5.4 持久执行
- 每个关键步骤保存检查点（`update_plan` 进度） - 每个关键步骤保存检查点（`update_plan` 进度）
- 失败后从最新检查点恢复，不从头开始 - 失败后从最新检查点恢复，不从头开始
- 幂等设计：同一操作重复执行结果一致 - 幂等设计：同一操作重复执行结果一致
- **三层状态管理**：系统层(工作流ID/超时/重试) → 执行层(当前活动/进度) → 业务层(已完成工作/中间产物)
--- ---
## 五、质量门禁（5 级） ## 六、五层质量门禁
| 级别 | 门禁 | 通过标准 | | 门禁 | 时间 | 范围 | 失败处理 |
|------|------|---------| |------|------|------|---------|
| **L1** | 编译通过 | `mvn clean compile` + `npm run build:dev` 无 ERROR | | **L1 编译检查** | <30秒 | 语法、类型、导入 | Agent 自行修复 |
| **L2** | 测试通过 | 单元测试 + 接口测试全部通过 | | **L2 静态分析** | <2分钟 | 代码风格、复杂度、安全 | Agent 修复 |
| **L3** | DB 审查 | Flyway 脚本规范、SQL 安全、索引合理 | | **L3 单元测试** | <5分钟 | 功能正确性、边界条件 | 自动修复或上报 |
| **L4** | 验收通过 | 核心功能流程完整验证、全链路检查 | | **L4 集成测试** | <15分钟 | 模块间交互、数据流 | 上报人工 |
| **L5** | 归档完成 | Git commit + 文档更新 + 代码推送 | | **L5 生产验证** | 持续 | 监控、告警、性能 | 自动回滚 |
### 提交铁律 **提交铁律**：L1-L2 必须通过才能 commit，L3（如有DB变更）必须通过才能 push
- L1-L2 必须通过才能 commit
- L3（如有DB变更）必须通过才能 push
- L4-L5 发布前必须完成
--- ---
## 六、后端开发规范 ## 七、系统化调试（Systematic Debugging）
> **铁律：没有根因调查，不能提出修复方案。**
### 四阶段流程
**阶段1：根因调查**（修复前必须完成）
1. 仔细阅读错误信息（堆栈、行号、错误码）
2. 稳定复现（能否可靠触发？步骤？每次？）
3. 检查最近变更（git diff、新依赖、配置变更）
4. 多组件系统：在每个组件边界加诊断日志，定位哪一层断裂
5. 追踪数据流：坏值从哪里来？谁调用的？一直追溯到源头
**阶段2：模式分析**
- 找到同代码库中类似的正常工作代码
- 逐项对比差异
- 理解依赖关系
**阶段3：假设与测试**
- 形成单一假设："我认为X是根因，因为Y"
- 做最小改动测试
- 有效 → 阶段4；无效 → 新假设
**阶段4：实施**
- 创建失败测试用例
- 修复根因（不是症状）
- 验证修复
---
## 八、后端开发规范
### 分层架构 ### 分层架构
``` ```
Controller → AppService → Service → Mapper → Entity Controller → AppService → Service → Mapper → Entity
接收请求 编排业务 单表CRUD 数据访问 实体定义
``` ```
### 命名规范 ### 命名规范
@@ -241,110 +270,125 @@ com.healthlink.his.domain.{module}
com.healthlink.his.common.enums com.healthlink.his.common.enums
``` ```
### 统一返回格式
```java
AjaxResult.success(data) // 成功
AjaxResult.error("错误信息") // 失败
getDataTable(list) // 列表
```
### 关键约束 ### 关键约束
- 所有查询使用 `LambdaQueryWrapper`，禁止字符串拼接 SQL - 所有查询使用 `LambdaQueryWrapper`，禁止字符串拼接 SQL
- `@Transactional(rollbackFor = Exception.class)` 管理事务 - `@Transactional(rollbackFor = Exception.class)` 管理事务
- 所有接口标注 `@PreAuthorize` 权限控制 - 所有接口标注 `@PreAuthorize` 权限控制
- 患者敏感信息（身份证、手机号）在日志中脱敏 - 患者敏感信息在日志中脱敏
- **扩展功能不修改原有函数签名**，新建 Service/AppService - **扩展功能不修改原有函数签名**
- 涉及多表写操作的方法标注 `@Transactional`
- 事务方法未被同一类内方法直接调用（避免自调用失效）
--- ---
## 七、前端开发规范 ## 九、前端开发规范
### 技术栈 ### 技术栈
- Vue 3 + Vite + Element Plus + Pinia + Axios - Vue 3 + Vite + Element Plus + Pinia + Axios（基于 RuoYi-Vue3）
- 基于 RuoYi-Vue3 框架
### 目录结构 ### 目录结构
``` ```
src/api/{module}/ # API接口（kebab-case路径） src/api/{module}/ # API接口
src/views/{module}/ # 页面组件 src/views/{module}/ # 页面组件
src/store/modules/ # Pinia状态管理 src/store/modules/ # Pinia状态管理
src/components/ # 公共组件 src/components/ # 公共组件
``` ```
### API 路径规范
```javascript
// 统一前缀 /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` 指令
### 关键约束 ### 关键约束
- API前缀：`/healthlink-his/api/v1/`
- 路由懒加载：`() => import('@/views/xxx/index.vue')` - 路由懒加载：`() => import('@/views/xxx/index.vue')`
- 不使用 `v-html`（除非做 XSS 转义） - 页面使用 `<script setup>` 语法
- 不在前端硬编码密码、密钥 - 按钮权限使用 `v-hasPermi` 指令
- `onMounted` 中注册的事件在 `onUnmounted` 中移除 - `onMounted` 中注册的事件在 `onUnmounted` 中移除
--- ---
## 八、Agent 体系（智能体协作） ## 十、Agent 体系
### 角色定义 ### 角色与路由
| 代号 | 名称 | 角色 | 职责 | | 代号 | 名称 | 角色 | 路由关键词 |
|------|------|------|------| |------|------|------|-----------|
| liubei | 刘备 | 项目经理 | 总协调、任务分配、异常升级 | | liubei | 刘备 | 项目经理 | 协调、分派、异常升级 |
| zhugeliang | 诸葛亮 | 架构师 | 需求分析、方案设计、技术决策 | | zhugeliang | 诸葛亮 | 架构师 | 分析、路由、设计 |
| guanyu | 关羽 | 后端开发 | Java 后端修复、API 开发 | | guanyu | 关羽 | 后端开发 | java, api, spring, service, controller |
| zhaoyun | 赵云 | 前端开发 | Vue 前端修复、页面开发 | | zhaoyun | 赵云 | 前端开发 | vue, 界面, 显示, 弹窗, 按钮 |
| xunyu | 荀彧 | DBA | 数据库审查、SQL 优化、Flyway 脚本 | | xunyu | 荀彧 | DBA | 数据库, sql, 迁移, mapper xml |
| zhangfei | 张飞 | 测试 | Playwright 测试、接口测试、回归测试 | | zhangfei | 张飞 | 测试 | 测试, QA, 回归 |
| huatuo | 华佗 | 验收 | 功能验收、质量确认、发布检查 | | huatuo | 华佗 | 验收 | 需求验收、质量确认 |
| chenlin | 陈琳 | 文档 | 归档记录、文档更新、Git 提交 | | chenlin | 陈琳 | 文档 | 文档、归档、Git提交 |
### 协作流水线 ### 协作流水线
``` ```
刘备(协调) → 诸葛亮(分析) → {关羽|赵云}(修复) → 荀彧(DB审查) → 张飞(测试) → 华佗(验收) → 陈琳(归档) 刘备(协调) → 诸葛亮(分析路由) → {关羽|赵云}(修复) → 荀彧(DB审查) → 张飞(测试) → 华佗(验收) → 陈琳(归档)
```
### Bug 修复完整管线（BDT 方法论）
```
获取Bug → 设计测试用例 → 基线测试(应失败) → 全链路修复 → 回归测试(应通过) → 扩展测试(无回归) → 提交
``` ```
### Bug 状态管理铁律 ### Bug 状态管理铁律
- 人类提的 Bug：只加备注，不改状态，不改分配 - 人类提的 Bug：只加备注，不改状态，不改分配
- 智能体提的 Bug：可以改分配和加备注 - 智能体提的 Bug：可以改分配和加备注
- 已关闭/已解决的 Bug 不再处理 - 已关闭/已解决的 Bug 不再处理
### 修复流程铁律 ---
- 一次只修一个 Bug，不扩大范围 ## 十一、审查与审计
- 修复前必须读 AGENTS.md
- 修复后必须验证编译
- 涉及 SQL 必须先查真实数据库
### 测试流程铁律 ### 三层审查体系
- Playwright 必须 `--workers=1` 单线程 | 层级 | 内容 | 时机 |
- 超时 120 秒 |------|------|------|
- 最多重试 3 次 | **L1 自审** | Agent 对照约束逐条检查 | 每次提交前 |
- 测试结果写入禅道备注 | **L2 配对审查** | Agent 生成变更摘要，人类终审 | PR/提交时 |
| **L3 合规审查** | 审计追踪，记录所有 AI 操作 | 持续 |
### 归档流程铁律 ### L1 自审清单
```yaml
self_review:
- "所有修改能通过编译？"
- "遵守命名规范？"
- "测试覆盖达标？"
- "没有遗漏的 TODO / DEBUG？"
- "变更范围没超出任务边界？"
```
- 三重归档：Git + SQLite + Redis ### 评审评分维度
- SQLite 必须使用完整字段 | 维度 | 问题 |
- 禅道备注格式：`[📝 陈琳归档] Bug #xxx` |------|------|
| 正确性 | 行为是否符合目标功能？ |
| 验证 | 检查是否真的跑过并留下证据？ |
| 范围纪律 | 是否保持在选定功能范围内？ |
| 可靠性 | 结果能否在重启后继续工作？ |
| 可维护性 | 代码和文档是否清楚到可交接？ |
--- ---
## 九、开发流程 ## 十二、标准工作循环
```
开始会话
├→ 1. Init — 读 AGENTS.md + PROGRESS.md + git log
├→ 2. Select — 只选一个未完成功能
├→ 3. Implement — 一次只做一个，不扩大范围
├→ 4. Verify — 运行验证命令，有证据才标记完成
└→ 5. Cleanup — 更新进度 + clean-state-checklist + git commit
```
### 会话结束前必须运行 Clean State Checklist
```
□ 标准启动路径仍然可用
□ 标准验证路径仍然可运行
□ 当前进度已记录到进度日志
□ 无半成品步骤处于未记录状态
□ 下一轮会话无需人工修复即可继续
```
---
## 十三、开发流程
``` ```
收到任务 收到任务
@@ -368,64 +412,60 @@ scope: 模块名(如 registration, billing, pharmacy)
--- ---
## 十、快速参考命令 ## 十四、快速参考命令
```bash ```bash
# === 后端 === # === 后端 ===
export JAVA_HOME=/opt/jdk-25 export JAVA_HOME=/opt/jdk-25
mvn clean compile -DskipTests # 编译 mvn clean compile -DskipTests # 编译
mvn install -DskipTests # 完整构建 mvn install -DskipTests # 构建
mvn test -pl healthlink-his-application -Dtest="XxxTest" -Dsurefire.failIfNoSpecifiedTests=false # 测试 mvn test -pl healthlink-his-application -Dtest="XxxTest" -Dsurefire.failIfNoSpecifiedTests=false
# === 前端 === # === 前端 ===
cd healthlink-his-ui cd healthlink-his-ui
npm run dev # 开发模式 npm run dev && npm run build:dev && npm run lint && npm run test:run
npm run build:dev # 构建
npm run lint # 代码检查
npm run test:run # 单元测试
# === Git === # === Git ===
git status # 查看变更 git status && git add -A && git commit -m "feat(module): desc" && git push origin develop
git add -A # 暂存所有
git commit -m "feat(module): description" # 提交
git push origin develop # 推送
``` ```
--- ---
## 十一、详细规范文档索引 ## 十五、详细规范文档索引
| 文档 | 路径 | 用途 | | 文档 | 路径 | 用途 |
|------|------|------| |------|------|------|
| 执行铁律 | `MD/specs/IRON_RULES.md` | 铁律完整版 | | 执行铁律 | `MD/specs/IRON_RULES.md` | 铁律完整版 |
| 后端规范 | `MD/specs/BACKEND_DEVELOPMENT_STANDARD.md` | 后端编码标准 | | 后端规范 | `MD/specs/BACKEND_DEVELOPMENT_STANDARD.md` | 后端编码标准 |
| 前端规范 | `MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md` | 前端编码标准 | | 前端规范 | `MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md` | 前端编码标准 |
| Harness方法论 | `MD/specs/HARNESS_ENGINEERING.md` | 完整Harness+Agent方法论 |
| 文档规范 | `MD/DOCUMENTATION_STANDARD.md` | 文档管理标准 | | 文档规范 | `MD/DOCUMENTATION_STANDARD.md` | 文档管理标准 |
| 后端清单 | `MD/specs/BACKEND_CHECKLIST.md` | 发布前检查 | | 后端清单 | `MD/specs/BACKEND_CHECKLIST.md` | 发布前检查 |
| 前端清单 | `MD/specs/FRONTEND_CHECKLIST.md` | 发布前检查 | | 前端清单 | `MD/specs/FRONTEND_CHECKLIST.md` | 发布前检查 |
| 三甲标准 | `MD/standards/GRADE3A_HIS_STANDARD.md` | 三甲医院达标标准 | | 三甲标准 | `MD/standards/GRADE3A_HIS_STANDARD.md` | 三甲医院达标标准 |
| Flyway指南 | `MD/guides/FLYWAY_USAGE_GUIDE.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: 签到设 BOOKED(1) 而非 CHECKED_IN(3)，前端映射缺失 → 必须走完整状态链路 |
| 盲删源文件 | Bug #574 | AI 看到编译错误直接删文件，没检查是否在 baseline → 必须先确认文件来源再操作 | | 盲删源文件 | AI 看到编译错误直接删文件，没检查 baseline → 必须先确认文件来源 |
| 修复方向偏差 | Bug #574 | 多次 fallback 改的是 OrderServiceImpl，完全没触及 TicketServiceImpl → 必须用 rg 搜索所有相关代码路径 | | 修复方向偏差 | 多次 fallback 改的是错误的 Service → 必须用 rg 搜索所有相关代码路径 |
| bug_reports 表缺少列 | 经验 | INSERT 会静默失败，必须检查表结构 | | bug_reports 缺列 | INSERT 静默失败 → 必须检查表结构 |
| 禅道 comment API | 经验 | API 不存在，必须用 resolve+activate workaround | | 禅道 comment API | API 不存在，用 resolve+activate workaround |
| SQLite WAL 并发 | 经验 | 多进程并发写需要 checkpoint | | SQLite WAL 并发 | 多进程并发写需要 checkpoint |
| UTF-8 切片 | 经验 | 多字节字符不能用 byte index 切片 | | UTF-8 切片 | 多字节字符不能用 byte index 切片 |
| 禅道图片附件 | 经验 | 必须 OCR 读取，不能直接解析 | | 上下文焦虑 | Agent 感觉上下文快满时会匆忙结束，跳过验证 → 注意 context 40% 阈值 |
| 过早宣告胜利 | 自评≠验证，分开"干活"和"检查" |
| 覆盖率幻觉 | 覆盖率达标但逻辑没测 → 引入变异测试 |
--- ---
> ⚠️ **警告**: 本文件是项目 AI 开发规范的唯一信源。各工具配置文件（AGENTS.md、.cursorrules 等）均通过 `bash scripts/sync-ai-rules.sh` 从本文件同步。修改规范请只修改本文件。 > ⚠️ 本文件是 AI 开发规范的唯一信源。各工具配置文件由 `bash scripts/sync-ai-rules.sh` 同步。
--- ---
> 📅 最后同步: 2026-06-06 09:56 | 源文件: RULES.md | 重新同步: `bash scripts/sync-ai-rules.sh` > 📅 最后同步: 2026-06-06 10:01 | 源文件: RULES.md | 重新同步: `bash scripts/sync-ai-rules.sh`

305
MD/specs/HARNESS_ENGINEERING.md Normal file
View File

@@ -0,0 +1,305 @@
# Harness Engineering 完整方法论
> **文档类型**: 技术规范
> **适用范围**: AI Agent 协作开发
> **版本**: v1.0
> **编制日期**: 2026-06-06
> **最后更新**: 2026-06-06
---
## 一、WalkingLabs 5 子系统模型
```
┌─────────────────────────────────────────────┐
│ 指令（Instruction）— RULES.md / AGENTS.md │
│ 工具（Tools）— shell / 文件 / 测试 │
│ 环境（Environment）— 依赖 / 服务 / 版本 │
│ 状态（State）— PROGRESS.md / 功能清单 │
│ 反馈（Feedback）— test / lint / build │
└─────────────────────────────────────────────┘
```
### 1.1 指令子系统
| 文件 | 用途 |
|------|------|
| `RULES.md` | 项目铁律、约束、标准工作流 |
| `AGENTS.md` | 子目录铁律引用 |
| `.harness/PROGRESS.md` | 会话进度 + 已验证状态 |
| `.harness/feature_list.json` | 功能状态唯一事实来源 |
| `.harness/init.sh` | 统一启动入口 |
| `.harness/clean-state-checklist.md` | 结束时的清洁检查 |
### 1.2 工具子系统
| 层级 | 工具 | 用途 |
|------|------|------|
| L0 开发 | `mvn compile/test` / `npm run build` | 编译、测试 |
| L1 Agent | `agentforge executor --agent <name>` | Agent 主循环 |
| L2 Pipeline | `agentforge pipeline` | 流水线批量修 Bug |
| L3 集成 | Zentao REST API | 禅道操作 |
| L4 辅助 | `rg` / `git blame` | 代码搜索、历史追溯 |
### 1.3 环境子系统
| 组件 | 配置 |
|------|------|
| Redis | `redis://127.0.0.1:16379` |
| PostgreSQL | `192.168.110.252:15432` |
| Git | `http://192.168.110.253:3000/wangyizhe/his.git` |
### 1.4 状态子系统
| 机制 | 用途 | 持久化 |
|------|------|--------|
| `TraceStore` (SQLite) | Agent 活动追踪 | `/var/lib/agentforge/traces.db` |
| `fix_trajectory` | 修复轨迹 | Redis Hash |
| `dead_letter` | 失败任务持久化 | Redis List |
### 1.5 反馈子系统
| 层级 | 速度 | 命令 | 失败处理 |
|------|------|------|---------|
| L1 编译检查 | <10秒 | `mvn compile` | 立即阻断 |
| L1 单元测试 | <5分钟 | `mvn test` | 失败回退，重试 |
| L2 代码质量 | <2分钟 | ESLint / 编译警告 | 警告可忽略，错误阻断 |
| L3 质量门禁 | <30秒 | `run_quality_gates()` | 编译验证通过才提交 |
| L4 人工审查 | 5-10分钟 | diff review | 驳回/指导/批准 |
---
## 二、约束系统
### 2.1 四类约束
| 类型 | 内容 | 示例 |
|------|------|------|
| 架构约束 | 接口合约、包结构、命名规范 | 包结构 `com.healthlink.his.web.{module}` |
| 代码质量 | 圈复杂度、风格、类型提示 | 每函数≤50行 |
| 安全约束 | 敏感信息、权限、输入验证 | 患者信息脱敏 |
| 业务规则 | 领域逻辑、数据一致性 | 全链路6环验证 |
### 2.2 约束 DSL
```yaml
constraint:
type: "must" | "must_not" | "should" | "may"
scope: "file" | "class" | "method" | "project"
rule: "具体规则"
verification: "如何验证"
```
### 2.3 约束优先级
```
安全(1) > 架构(2) > 业务(3) > 质量(4) > 性能(5)
```
---
## 三、反馈系统
### 3.1 闭环测试
```
测试失败
→ 分析失败原因（编译/逻辑/边界/依赖）
→ 提取可行动反馈（文件:行号:错误类型:修复方向）
→ Agent 修复
→ 重测
→ 持续失败3次 → 上报人类
```
### 3.2 反馈格式
```
文件路径:行号 错误类型 错误描述 | 修复建议
示例:
src/main/java/com/.../PatientService.java:42 NullPointerException patient name | 添加空值检查
```
### 3.3 失败原因分析
| 类型 | 占比 | 捕获门禁 |
|------|------|---------|
| 架构错误 | 35% | L1 编译 |
| 业务逻辑 | 25% | L3 单元测试 |
| 创造性偏差 | 20% | L3 + L5 |
| Debug残留 | 15% | L2 静态分析 |
| 其他 | 5% | L5 |
### 3.4 测试覆盖率目标
```yaml
unit_test_coverage: 90% # 行覆盖率
mutation_score: 80% # 变异测试通过率
branch_coverage: 85% # 分支覆盖率
```
---
## 四、持久执行
### 4.1 检查点策略
**触发时机**：
- 每完成1个关键步骤
- 编译通过/失败后
- 每次代码修改后
**检查点内容**：
```yaml
checkpoint:
step_id: "string"
status: "pending | in_progress | completed | failed"
inputs: {}
outputs: {}
error_message: ""
timestamp: "ISO8601"
```
### 4.2 恢复流程
```
失败 → 定位最新检查点 → 分析失败原因 → git restore → 从失败点修复 → 继续执行
```
### 4.3 幂等性模式
| 模式 | 实现 |
|------|------|
| 唯一标识 | 每个操作生成唯一ID，已执行则跳过 |
| 状态检查 | 执行前检查目标是否已达成 |
| 补偿操作 | 不可逆操作提供 `git restore` 回滚 |
---
## 五、Agent 协作详解
### 5.1 管线路由
```
fix_done (关羽/赵云)
│
▼
诸葛亮 (分析路由)
│── 无DB变更 ──→ 张飞 (Playwright测试)
│── 有DB变更 ─→ 荀彧 (DB审查) → 张飞 (测试)
│
└── 失败 → 回退给修复者重修（最多10次）
张飞(测试) → 华佗(验收) → 陈琳(归档)
```
### 5.2 去重机制
| 机制 | TTL | 用途 |
|------|-----|------|
| `pipeline_sent:{bug_id}` | 24h | 防重复触发管线 |
| `pipeline_retry:{bug_id}` | — | 重试计数器 |
| `codex_lock:{agent}` | 1h | Agent 互斥锁 |
| `fix_active:{agent}:{bug_id}` | 30min | 防重复 fix_start |
### 5.3 禅道操作规则
| 阶段 | 智能体 | 禅道操作 |
|------|--------|---------|
| 分析路由 | 诸葛亮 | 添加备注（分析结果） |
| DB审查 | 荀彧 | 添加备注（审查结果） |
| 测试 | 张飞 | 添加测试报告 + resolve |
| 验收 | 华佗 | 添加备注 + resolve + assign |
| 归档 | 陈琳 | 添加备注（全流程记录） |
---
## 六、审查与审计
### 6.1 三层审查
| 层级 | 内容 | 信任度 |
|------|------|--------|
| L1 自审 | Agent 对照约束逐条检查 | 强制 |
| L2 配对审查 | Agent 变更摘要 + 人类终审 | 按信任度比例 |
| L3 合规审查 | 审计追踪，记录所有AI操作 | 强制 |
### 6.2 信任度比例
| 信任等级 | 自审 | 配对审查 | 合规审查 |
|---------|------|---------|---------|
| L1 怀疑 | 强制 | 逐行 | 强制 |
| L2 试探 | 强制 | 抽样30% | 强制 |
| L3 信任 | 强制 | 抽样10% | 按需 |
### 6.3 审计记录格式
```yaml
audit_record:
agent_id: "codex-v4"
task_id: "bug-597"
timestamp: "2026-05-28T14:30:00Z"
actions:
- type: "file_modify"
path: "AdviceManageAppMapper.xml"
diff: "+7 lines, -2 lines"
approvals:
- reviewer: "human"
decision: "approved"
```
---
## 七、BDT 方法论（Bug Driven Testing）
### 7.1 流程
```
获取Bug → 设计用例 → 基线测试(应失败) → 修复 → 回归测试(应通过) → 扩展测试 → 提交
```
### 7.2 测试用例7种检查模式
| # | 模式 | 适用场景 | Playwright写法 |
|---|------|---------|---------------|
| 1 | 页面加载 | 所有Bug | `expect(page).not.toHaveURL(/.*login.*/)` |
| 2 | 元素可见 | 显示/缺失类 | `expect(locator).toBeVisible()` |
| 3 | 元素可交互 | 按钮/弹窗类 | `await locator.click()` |
| 4 | 数据正确 | 列表/回显类 | `expect(locator).toHaveText()` |
| 5 | 无报错 | 所有Bug | `page.on('pageerror')` |
| 6 | 流程完整 | 交互流程类 | 多步骤操作链 |
| 7 | 状态变更 | 退回/审核类 | 操作前vs操作后状态对比 |
### 7.3 测试用例质量标准
- ✅ 有 `@bug{N}` 标签（可单独运行）
- ✅ 有 `@regression` 标签（回归套件）
- ✅ 操作路径来自禅道复现步骤
- ✅ 断言覆盖期望结果
- ✅ 检查无JS错误
- ✅ 有截图记录
- ✅ 独立运行（不依赖其他测试）
---
## 八、L4/L5 分析与优化
### 8.1 L4 量化分析
- TraceStore (SQLite): `/var/lib/agentforge/traces.db`
- 指标：Agent成功率、平均修复耗时、失败模式分布、Pipeline吞吐量
### 8.2 L5 AI 自主优化
| 机制 | 触发条件 | 动作 |
|------|---------|------|
| 约束增强 | 成功率<50%（≥3次） | 自动补充专项约束 |
| 智能路由 | 按bug类型匹配历史最优Agent | `best_agent_for(bug_type)` |
| 重试策略 | 失败后换提示词/换Agent | 最多10次 |
| 路由调整 | 某Agent成功率最低 | 减少分配 |
- 评分：成功率(60%) + 速度(20%) + 类型匹配(20%)
---
> **文档版本**: v1.0
> **最后更新**: 2026-06-06

380
RULES.md
View File

@@ -1,6 +1,6 @@
# HealthLink-HIS — AI 开发规范（自动加载） # HealthLink-HIS — AI 开发规范（自动加载）
> 🤖 **本文件供所有 AI 编码工具自动读取**。无论使用 Claude Code、Cursor、Codex CLI、Copilot、Qwen、Cline 还是其他工具，进入本项目后必须遵守以下规范。 > 🤖 **本文件供所有 AI 编码工具自动读取**。进入本项目后必须遵守以下规范。
> >
> **模型决定上限，Harness 决定底线。** > **模型决定上限，Harness 决定底线。**
@@ -42,7 +42,6 @@
- 凡是新建表、新增字段，必须创建 Flyway 迁移脚本 - 凡是新建表、新增字段，必须创建 Flyway 迁移脚本
- 路径：`healthlink-his-domain/src/main/resources/db/migration/` - 路径：`healthlink-his-domain/src/main/resources/db/migration/`
- 命名：`V{版本号}__{描述}.sql`（双下划线） - 命名：`V{版本号}__{描述}.sql`（双下划线）
- 禁止直接在数据库执行 SQL 不走 Flyway
**铁律3: 测试通过后才提交** **铁律3: 测试通过后才提交**
- 编译 + 测试全部通过后才能 git commit - 编译 + 测试全部通过后才能 git commit
@@ -51,59 +50,80 @@
**铁律4: 前后端API路径对齐** **铁律4: 前后端API路径对齐**
- 后端前缀：`/healthlink-his/api/v1/` - 后端前缀：`/healthlink-his/api/v1/`
- 前端 `request.js` 的 baseURL 必须与后端匹配 - 前端 `request.js` 的 baseURL 必须与后端匹配
- 接口变更必须同步更新前后端代码
**铁律5: 状态值一致性（来自 Bug #574 教训）** **铁律5: 状态值一致性（Bug #574 教训）**
- 修改任何状态值前，必须先列出完整的状态流转链路 - 修改任何状态值前，必须先列出完整的状态流转链路
- 检查项： - 检查项：枚举定义 → Service 设置 → 查询映射 → 前端 STATUS_CLASS_MAP → 前端 v-if → 统计SQL
1. 枚举定义的值是否正确
2. Service 层设置的状态值是否与枚举一致
3. 查询/列表接口的状态映射是否覆盖所有枚举值
4. 前端 `STATUS_CLASS_MAP` 是否包含新状态
5. 前端过滤条件（如 `v-if`）是否兼容新状态
6. 池/统计表的聚合 SQL 是否包含新状态值
- 禁止：只改一端不检查其他端 - 禁止：只改一端不检查其他端
**铁律6: 禁止删除源文件（来自 Bug #574 教训）** **铁律6: 禁止删除源文件（Bug #574 教训）**
- 绝对禁止删除项目中已有的 Java/Vue/SQL 源文件 - 绝对禁止删除项目中已有的 Java/Vue/SQL 源文件
- 文件有编译错误 → 修复错误，不删除文件 - 编译错误 → 修复错误；重复文件 → 重构合并
- 文件是重复的 → 重构合并，不删除文件
- 文件是 AI 幻觉创建的 → 检查 git baseline 确认后再删除
- 唯一例外：明确由人类确认删除的文件 - 唯一例外：明确由人类确认删除的文件
**铁律7: 禁止修改已有公开方法签名** **铁律7: 禁止修改已有公开方法签名**
- 不能删除或重命名已有的 public 方法 - 不能删除/重命名已有的 public 方法，不能修改参数列表
- 不能修改已有方法的参数列表 - 需要新功能 → 添加重载方法；需要改行为 → 修改内部实现
- 需要新增功能时 → 添加新的重载方法
- 需要改行为时 → 修改方法内部实现，不改签名 **铁律8: 验证后才宣称完成（Verification Before Completion）**
- **没有跑过验证命令，就不能说"完成了""通过了""没问题"**
- 禁止使用"应该可以""大概没问题""看起来正确"
- 必须：运行命令 → 读取输出 → 确认结果 → 才能宣称
- 这是诚实原则，不是效率问题
### 🟡 P1 铁律 — 强烈建议 ### 🟡 P1 铁律 — 强烈建议
**铁律8: 先分解再行动** **铁律9: 先分解再行动**
- 修改超过3个文件、涉及多模块、数据库变更，必须先制定计划 - 修改超过3个文件、涉及多模块、数据库变更，必须先制定计划
**铁律9: 验证后信** **铁律10: 验证后信**
- 每次修改后必须验证编译通过，不信记忆 - 每次修改后必须验证编译通过，不信记忆
- 重新编译命令：`mvn clean compile -DskipTests`
**铁律10: 文档统一管理** **铁律11: 文档统一管理**
- 所有文档存储在 `MD/` 目录 - 所有文档存储在 `MD/` 目录
- 文件名：大写英文+下划线（如 `BACKEND_CHECKLIST.md`） - 文件名：大写英文+下划线（如 `BACKEND_CHECKLIST.md`）
- 文档头部必须包含元数据块（文档类型、版本、日期） - 文档头部必须包含元数据块（文档类型、版本、日期）
--- ---
## 三、全链路 6 环分析 ## 三、Karpathy 编码准则
> ⚠️ **涉及数据库字段的 Bug / 需求，必须走完整链路，不得"就事论事"。** > 减少 LLM 常见编码错误。偏向谨慎而非速度。
### 3.1 先想再写
- 明确陈述假设，不确定就问
- 多种解读时都列出来，不要默默选一种
- 有更简单的方案就说出来，该推回就推回
- 不清楚的地方停下来，说清楚哪里不清楚
### 3.2 简洁优先
- 不做没要求的功能，不做一次性代码的抽象
- 不加没要求的"灵活性"和"可配置性"
- 200 行能 50 行搞定就重写
- 自问："高级工程师会不会觉得这过度设计？"
### 3.3 精准修改
- 只改必须改的，不"顺手改进"相邻代码
- 匹配现有代码风格，即使你有不同的偏好
- 每行改动都能追溯到用户的请求
- 只清理你自己改动产生的无用代码
### 3.4 目标驱动
- 把任务转化为可验证目标
- 多步任务声明计划：`[步骤] → 验证: [检查]`
- 强验收标准让 Agent 能独立循环，弱标准需要持续澄清
---
## 四、全链路 6 环分析
> ⚠️ **涉及数据库字段的 Bug / 需求，必须走完整链路。**
``` ```
前端/页面 → Controller → Service → Mapper → DB/SQL → 关联模块 前端/页面 → Controller → Service → Mapper → DB/SQL → 关联模块
①录入 ②验证 ③业务 ④持久化 ⑤存储 ⑥联动 ①录入 ②验证 ③业务 ④持久化 ⑤存储 ⑥联动
``` ```
### 每一环必须确认
| 环 | 检查内容 | | 环 | 检查内容 |
|----|---------| |----|---------|
| ① 录入 | 前端有无输入入口（弹窗、表格行编辑、表单） | | ① 录入 | 前端有无输入入口（弹窗、表格行编辑、表单） |
@@ -113,104 +133,113 @@
| ⑤ 存储 | 数据库表结构、索引、NOT NULL 约束 | | ⑤ 存储 | 数据库表结构、索引、NOT NULL 约束 |
| ⑥ 联动 | 上游（医嘱→护士站）、下游（打印、计费、报表）是否同步 | | ⑥ 联动 | 上游（医嘱→护士站）、下游（打印、计费、报表）是否同步 |
### 全链路验证顺序 **修复后的验证顺序**：
1. 数据库：确认状态值已正确写入
修复涉及状态流转的问题后，必须按以下顺序验证： 2. 后端接口：确认返回的状态映射正确
1. **数据库**：确认状态值已正确写入 3. 前端显示：确认页面显示正确状态文本
2. **后端接口**：确认返回的状态映射正确 4. 前端交互：确认按钮/操作基于正确状态启用/禁用
3. **前端显示**：确认页面显示正确状态文本 5. 统计数据：确认池/报表统计包含新状态
4. **前端交互**：确认按钮/操作基于正确状态启用/禁用
5. **统计数据**：确认池/报表统计包含新状态
### 常见陷阱
- ❌ 只修了「主入口」的保存逻辑，忘了「批量保存」「签发保存」等其他入口
- ❌ 前端加了输入框，后端 Service 没传字段
- ❌ Mapper XML 是 UNION ALL 查询，只改了其中一个子查询
- ❌ DTO 层级继承关系没检查
- ❌ 只测了新增，没测编辑已有数据的回显和修改再保存
--- ---
## 四、Harness Engineering 方法论 ## 五、Harness Engineering 方法论
> Harness = 约束 + 反馈 + 控制平面 + 持久执行 > Harness = 约束 + 反馈 + 控制平面 + 持久执行
### 4.1 四层约束金字塔 ### 5.1 四层约束金字塔
| 层级 | 内容 | 落地方式 | | 层级 | 内容 | 落地方式 |
|------|------|---------| |------|------|---------|
| **L1 架构约束** | 接口合约、包结构、命名规范、禁止模式 | 本文件铁律、AGENTS.md | | **L1 架构约束** | 接口合约、包结构、命名规范、禁止模式 | 本文件铁律 |
| **L2 代码质量** | 圈复杂度、代码风格、类型提示 | 编译门禁 + ESLint | | **L2 代码质量** | 圈复杂度、代码风格、类型提示 | 编译门禁 + ESLint |
| **L3 安全约束** | 敏感信息检测、权限检查、输入验证 | 配置不可硬编码 | | **L3 安全约束** | 敏感信息检测、权限检查、输入验证 | 配置不可硬编码 |
| **L4 业务规则** | 领域逻辑、数据一致性、事务边界 | 全链路 6 环验证 | | **L4 业务规则** | 领域逻辑、数据一致性、事务边界 | 全链路 6 环验证 |
**约束优先级**：安全 > 架构 > 质量 > 业务 **约束设计原则**：
- **可验证**：每条约束必须能被自动化检查（"覆盖率>90%"✅ "质量要高"❌）
- **无歧义**："每函数不超过50行"✅ "函数不要太长"❌
- **优先级**：安全(1) > 架构(2) > 业务(3) > 质量(4) > 性能(5)
- **渐进增强**：L1编译通过 → L2+命名规范 → L3+测试覆盖 → L4+安全扫描
### 4.2 三层反馈系统 ### 5.2 三层反馈系统
| 层级 | 速度 | 覆盖范围 | 失败处理 | | 层级 | 速度 | 覆盖范围 | 失败处理 |
|------|------|---------|---------| |------|------|---------|---------|
| **L1 编译检查** | <30 秒 | 语法、类型、签名 | 立即阻断，自行修复 | | **L1 编译检查** | <30秒 | 语法、类型、签名 | 立即阻断，自行修复 |
| **L2 数据流验证** | <5 分钟 | 全链路字段、Mapper XML、DTO | 修复后上报 | | **L2 数据流验证** | <5分钟 | 全链路字段、Mapper XML、DTO | 修复后上报 |
| **L3 人工审查** | 10-30 分钟 | 架构、设计、业务正确性 | 驳回 / 指导 / 批准 | | **L3 人工审查** | 10-30分钟 | 架构、设计、业务正确性 | 驳回/指导/批准 |
**反馈设计铁律**： **反馈铁律**：
- 反馈必须可行动（指出：文件 + 行号 + 错误类型 + 修复方向） - 反馈必须可行动（文件 + 行号 + 错误类型 + 修复方向）
- 反馈越及时越好（L1 即时 → L2 分钟 → L3 小时）
- 失败后先回滚到最近检查点，再重试 - 失败后先回滚到最近检查点，再重试
- 持续失败3次 → 上报人类
### 4.3 控制平面（Agent 协调） ### 5.3 控制平面
``` ```
┌─────────────────────────────────────────────┐ 战略层（人类） → 设定目标、审批决策、异常升级
│ 战略层（人类主导） │ 战术层（Agent） → 任务分解、update_plan、依赖协调、检查点保存
│ ├── 设定目标、审批关键决策 │ 执行层（Agent） → 代码生成、测试执行、错误恢复、幂等重试
│ └── 异常升级处理 │
├─────────────────────────────────────────────┤
│ 战术层（Control Plane） │
│ ├── 任务分解 + update_plan │
│ ├── 依赖协调 + 资源分配 │
│ └── 检查点保存 + 恢复 │
├─────────────────────────────────────────────┤
│ 执行层（Agent 自主） │
│ ├── 代码生成、测试执行 │
│ └── 错误恢复 + 幂等重试 │
└─────────────────────────────────────────────┘
``` ```
### 4.4 持久执行 ### 5.4 持久执行
- 每个关键步骤保存检查点（`update_plan` 进度） - 每个关键步骤保存检查点（`update_plan` 进度）
- 失败后从最新检查点恢复，不从头开始 - 失败后从最新检查点恢复，不从头开始
- 幂等设计：同一操作重复执行结果一致 - 幂等设计：同一操作重复执行结果一致
- **三层状态管理**：系统层(工作流ID/超时/重试) → 执行层(当前活动/进度) → 业务层(已完成工作/中间产物)
--- ---
## 五、质量门禁（5 级） ## 六、五层质量门禁
| 级别 | 门禁 | 通过标准 | | 门禁 | 时间 | 范围 | 失败处理 |
|------|------|---------| |------|------|------|---------|
| **L1** | 编译通过 | `mvn clean compile` + `npm run build:dev` 无 ERROR | | **L1 编译检查** | <30秒 | 语法、类型、导入 | Agent 自行修复 |
| **L2** | 测试通过 | 单元测试 + 接口测试全部通过 | | **L2 静态分析** | <2分钟 | 代码风格、复杂度、安全 | Agent 修复 |
| **L3** | DB 审查 | Flyway 脚本规范、SQL 安全、索引合理 | | **L3 单元测试** | <5分钟 | 功能正确性、边界条件 | 自动修复或上报 |
| **L4** | 验收通过 | 核心功能流程完整验证、全链路检查 | | **L4 集成测试** | <15分钟 | 模块间交互、数据流 | 上报人工 |
| **L5** | 归档完成 | Git commit + 文档更新 + 代码推送 | | **L5 生产验证** | 持续 | 监控、告警、性能 | 自动回滚 |
### 提交铁律 **提交铁律**：L1-L2 必须通过才能 commit，L3（如有DB变更）必须通过才能 push
- L1-L2 必须通过才能 commit
- L3（如有DB变更）必须通过才能 push
- L4-L5 发布前必须完成
--- ---
## 六、后端开发规范 ## 七、系统化调试（Systematic Debugging）
> **铁律：没有根因调查，不能提出修复方案。**
### 四阶段流程
**阶段1：根因调查**（修复前必须完成）
1. 仔细阅读错误信息（堆栈、行号、错误码）
2. 稳定复现（能否可靠触发？步骤？每次？）
3. 检查最近变更（git diff、新依赖、配置变更）
4. 多组件系统：在每个组件边界加诊断日志，定位哪一层断裂
5. 追踪数据流：坏值从哪里来？谁调用的？一直追溯到源头
**阶段2：模式分析**
- 找到同代码库中类似的正常工作代码
- 逐项对比差异
- 理解依赖关系
**阶段3：假设与测试**
- 形成单一假设："我认为X是根因，因为Y"
- 做最小改动测试
- 有效 → 阶段4；无效 → 新假设
**阶段4：实施**
- 创建失败测试用例
- 修复根因（不是症状）
- 验证修复
---
## 八、后端开发规范
### 分层架构 ### 分层架构
``` ```
Controller → AppService → Service → Mapper → Entity Controller → AppService → Service → Mapper → Entity
接收请求 编排业务 单表CRUD 数据访问 实体定义
``` ```
### 命名规范 ### 命名规范
@@ -234,110 +263,125 @@ com.healthlink.his.domain.{module}
com.healthlink.his.common.enums com.healthlink.his.common.enums
``` ```
### 统一返回格式
```java
AjaxResult.success(data) // 成功
AjaxResult.error("错误信息") // 失败
getDataTable(list) // 列表
```
### 关键约束 ### 关键约束
- 所有查询使用 `LambdaQueryWrapper`，禁止字符串拼接 SQL - 所有查询使用 `LambdaQueryWrapper`，禁止字符串拼接 SQL
- `@Transactional(rollbackFor = Exception.class)` 管理事务 - `@Transactional(rollbackFor = Exception.class)` 管理事务
- 所有接口标注 `@PreAuthorize` 权限控制 - 所有接口标注 `@PreAuthorize` 权限控制
- 患者敏感信息（身份证、手机号）在日志中脱敏 - 患者敏感信息在日志中脱敏
- **扩展功能不修改原有函数签名**，新建 Service/AppService - **扩展功能不修改原有函数签名**
- 涉及多表写操作的方法标注 `@Transactional`
- 事务方法未被同一类内方法直接调用（避免自调用失效）
--- ---
## 七、前端开发规范 ## 九、前端开发规范
### 技术栈 ### 技术栈
- Vue 3 + Vite + Element Plus + Pinia + Axios - Vue 3 + Vite + Element Plus + Pinia + Axios（基于 RuoYi-Vue3）
- 基于 RuoYi-Vue3 框架
### 目录结构 ### 目录结构
``` ```
src/api/{module}/ # API接口（kebab-case路径） src/api/{module}/ # API接口
src/views/{module}/ # 页面组件 src/views/{module}/ # 页面组件
src/store/modules/ # Pinia状态管理 src/store/modules/ # Pinia状态管理
src/components/ # 公共组件 src/components/ # 公共组件
``` ```
### API 路径规范
```javascript
// 统一前缀 /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` 指令
### 关键约束 ### 关键约束
- API前缀：`/healthlink-his/api/v1/`
- 路由懒加载：`() => import('@/views/xxx/index.vue')` - 路由懒加载：`() => import('@/views/xxx/index.vue')`
- 不使用 `v-html`（除非做 XSS 转义） - 页面使用 `<script setup>` 语法
- 不在前端硬编码密码、密钥 - 按钮权限使用 `v-hasPermi` 指令
- `onMounted` 中注册的事件在 `onUnmounted` 中移除 - `onMounted` 中注册的事件在 `onUnmounted` 中移除
--- ---
## 八、Agent 体系（智能体协作） ## 十、Agent 体系
### 角色定义 ### 角色与路由
| 代号 | 名称 | 角色 | 职责 | | 代号 | 名称 | 角色 | 路由关键词 |
|------|------|------|------| |------|------|------|-----------|
| liubei | 刘备 | 项目经理 | 总协调、任务分配、异常升级 | | liubei | 刘备 | 项目经理 | 协调、分派、异常升级 |
| zhugeliang | 诸葛亮 | 架构师 | 需求分析、方案设计、技术决策 | | zhugeliang | 诸葛亮 | 架构师 | 分析、路由、设计 |
| guanyu | 关羽 | 后端开发 | Java 后端修复、API 开发 | | guanyu | 关羽 | 后端开发 | java, api, spring, service, controller |
| zhaoyun | 赵云 | 前端开发 | Vue 前端修复、页面开发 | | zhaoyun | 赵云 | 前端开发 | vue, 界面, 显示, 弹窗, 按钮 |
| xunyu | 荀彧 | DBA | 数据库审查、SQL 优化、Flyway 脚本 | | xunyu | 荀彧 | DBA | 数据库, sql, 迁移, mapper xml |
| zhangfei | 张飞 | 测试 | Playwright 测试、接口测试、回归测试 | | zhangfei | 张飞 | 测试 | 测试, QA, 回归 |
| huatuo | 华佗 | 验收 | 功能验收、质量确认、发布检查 | | huatuo | 华佗 | 验收 | 需求验收、质量确认 |
| chenlin | 陈琳 | 文档 | 归档记录、文档更新、Git 提交 | | chenlin | 陈琳 | 文档 | 文档、归档、Git提交 |
### 协作流水线 ### 协作流水线
``` ```
刘备(协调) → 诸葛亮(分析) → {关羽|赵云}(修复) → 荀彧(DB审查) → 张飞(测试) → 华佗(验收) → 陈琳(归档) 刘备(协调) → 诸葛亮(分析路由) → {关羽|赵云}(修复) → 荀彧(DB审查) → 张飞(测试) → 华佗(验收) → 陈琳(归档)
```
### Bug 修复完整管线（BDT 方法论）
```
获取Bug → 设计测试用例 → 基线测试(应失败) → 全链路修复 → 回归测试(应通过) → 扩展测试(无回归) → 提交
``` ```
### Bug 状态管理铁律 ### Bug 状态管理铁律
- 人类提的 Bug：只加备注，不改状态，不改分配 - 人类提的 Bug：只加备注，不改状态，不改分配
- 智能体提的 Bug：可以改分配和加备注 - 智能体提的 Bug：可以改分配和加备注
- 已关闭/已解决的 Bug 不再处理 - 已关闭/已解决的 Bug 不再处理
### 修复流程铁律 ---
- 一次只修一个 Bug，不扩大范围 ## 十一、审查与审计
- 修复前必须读 AGENTS.md
- 修复后必须验证编译
- 涉及 SQL 必须先查真实数据库
### 测试流程铁律 ### 三层审查体系
- Playwright 必须 `--workers=1` 单线程 | 层级 | 内容 | 时机 |
- 超时 120 秒 |------|------|------|
- 最多重试 3 次 | **L1 自审** | Agent 对照约束逐条检查 | 每次提交前 |
- 测试结果写入禅道备注 | **L2 配对审查** | Agent 生成变更摘要，人类终审 | PR/提交时 |
| **L3 合规审查** | 审计追踪，记录所有 AI 操作 | 持续 |
### 归档流程铁律 ### L1 自审清单
```yaml
self_review:
- "所有修改能通过编译？"
- "遵守命名规范？"
- "测试覆盖达标？"
- "没有遗漏的 TODO / DEBUG？"
- "变更范围没超出任务边界？"
```
- 三重归档：Git + SQLite + Redis ### 评审评分维度
- SQLite 必须使用完整字段 | 维度 | 问题 |
- 禅道备注格式：`[📝 陈琳归档] Bug #xxx` |------|------|
| 正确性 | 行为是否符合目标功能？ |
| 验证 | 检查是否真的跑过并留下证据？ |
| 范围纪律 | 是否保持在选定功能范围内？ |
| 可靠性 | 结果能否在重启后继续工作？ |
| 可维护性 | 代码和文档是否清楚到可交接？ |
--- ---
## 九、开发流程 ## 十二、标准工作循环
```
开始会话
├→ 1. Init — 读 AGENTS.md + PROGRESS.md + git log
├→ 2. Select — 只选一个未完成功能
├→ 3. Implement — 一次只做一个，不扩大范围
├→ 4. Verify — 运行验证命令，有证据才标记完成
└→ 5. Cleanup — 更新进度 + clean-state-checklist + git commit
```
### 会话结束前必须运行 Clean State Checklist
```
□ 标准启动路径仍然可用
□ 标准验证路径仍然可运行
□ 当前进度已记录到进度日志
□ 无半成品步骤处于未记录状态
□ 下一轮会话无需人工修复即可继续
```
---
## 十三、开发流程
``` ```
收到任务 收到任务
@@ -361,60 +405,56 @@ scope: 模块名(如 registration, billing, pharmacy)
--- ---
## 十、快速参考命令 ## 十四、快速参考命令
```bash ```bash
# === 后端 === # === 后端 ===
export JAVA_HOME=/opt/jdk-25 export JAVA_HOME=/opt/jdk-25
mvn clean compile -DskipTests # 编译 mvn clean compile -DskipTests # 编译
mvn install -DskipTests # 完整构建 mvn install -DskipTests # 构建
mvn test -pl healthlink-his-application -Dtest="XxxTest" -Dsurefire.failIfNoSpecifiedTests=false # 测试 mvn test -pl healthlink-his-application -Dtest="XxxTest" -Dsurefire.failIfNoSpecifiedTests=false
# === 前端 === # === 前端 ===
cd healthlink-his-ui cd healthlink-his-ui
npm run dev # 开发模式 npm run dev && npm run build:dev && npm run lint && npm run test:run
npm run build:dev # 构建
npm run lint # 代码检查
npm run test:run # 单元测试
# === Git === # === Git ===
git status # 查看变更 git status && git add -A && git commit -m "feat(module): desc" && git push origin develop
git add -A # 暂存所有
git commit -m "feat(module): description" # 提交
git push origin develop # 推送
``` ```
--- ---
## 十一、详细规范文档索引 ## 十五、详细规范文档索引
| 文档 | 路径 | 用途 | | 文档 | 路径 | 用途 |
|------|------|------| |------|------|------|
| 执行铁律 | `MD/specs/IRON_RULES.md` | 铁律完整版 | | 执行铁律 | `MD/specs/IRON_RULES.md` | 铁律完整版 |
| 后端规范 | `MD/specs/BACKEND_DEVELOPMENT_STANDARD.md` | 后端编码标准 | | 后端规范 | `MD/specs/BACKEND_DEVELOPMENT_STANDARD.md` | 后端编码标准 |
| 前端规范 | `MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md` | 前端编码标准 | | 前端规范 | `MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md` | 前端编码标准 |
| Harness方法论 | `MD/specs/HARNESS_ENGINEERING.md` | 完整Harness+Agent方法论 |
| 文档规范 | `MD/DOCUMENTATION_STANDARD.md` | 文档管理标准 | | 文档规范 | `MD/DOCUMENTATION_STANDARD.md` | 文档管理标准 |
| 后端清单 | `MD/specs/BACKEND_CHECKLIST.md` | 发布前检查 | | 后端清单 | `MD/specs/BACKEND_CHECKLIST.md` | 发布前检查 |
| 前端清单 | `MD/specs/FRONTEND_CHECKLIST.md` | 发布前检查 | | 前端清单 | `MD/specs/FRONTEND_CHECKLIST.md` | 发布前检查 |
| 三甲标准 | `MD/standards/GRADE3A_HIS_STANDARD.md` | 三甲医院达标标准 | | 三甲标准 | `MD/standards/GRADE3A_HIS_STANDARD.md` | 三甲医院达标标准 |
| Flyway指南 | `MD/guides/FLYWAY_USAGE_GUIDE.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: 签到设 BOOKED(1) 而非 CHECKED_IN(3)，前端映射缺失 → 必须走完整状态链路 |
| 盲删源文件 | Bug #574 | AI 看到编译错误直接删文件，没检查是否在 baseline → 必须先确认文件来源再操作 | | 盲删源文件 | AI 看到编译错误直接删文件，没检查 baseline → 必须先确认文件来源 |
| 修复方向偏差 | Bug #574 | 多次 fallback 改的是 OrderServiceImpl，完全没触及 TicketServiceImpl → 必须用 rg 搜索所有相关代码路径 | | 修复方向偏差 | 多次 fallback 改的是错误的 Service → 必须用 rg 搜索所有相关代码路径 |
| bug_reports 表缺少列 | 经验 | INSERT 会静默失败，必须检查表结构 | | bug_reports 缺列 | INSERT 静默失败 → 必须检查表结构 |
| 禅道 comment API | 经验 | API 不存在，必须用 resolve+activate workaround | | 禅道 comment API | API 不存在，用 resolve+activate workaround |
| SQLite WAL 并发 | 经验 | 多进程并发写需要 checkpoint | | SQLite WAL 并发 | 多进程并发写需要 checkpoint |
| UTF-8 切片 | 经验 | 多字节字符不能用 byte index 切片 | | UTF-8 切片 | 多字节字符不能用 byte index 切片 |
| 禅道图片附件 | 经验 | 必须 OCR 读取，不能直接解析 | | 上下文焦虑 | Agent 感觉上下文快满时会匆忙结束，跳过验证 → 注意 context 40% 阈值 |
| 过早宣告胜利 | 自评≠验证，分开"干活"和"检查" |
| 覆盖率幻觉 | 覆盖率达标但逻辑没测 → 引入变异测试 |
--- ---
> ⚠️ **警告**: 本文件是项目 AI 开发规范的唯一信源。各工具配置文件（AGENTS.md、.cursorrules 等）均通过 `bash scripts/sync-ai-rules.sh` 从本文件同步。修改规范请只修改本文件。 > ⚠️ 本文件是 AI 开发规范的唯一信源。各工具配置文件由 `bash scripts/sync-ai-rules.sh` 同步。