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

feat: 整合Harness Engineering + AgentForge规范到AI开发规范

Browse Source 
RULES.md 218→420行，新增内容:
- AgentForge 10条铁律(状态一致性/禁删源文件/禁改方法签名等)
- Harness Engineering 4大组件(约束金字塔/反馈系统/控制平面/持久执行)
- 全链路6环分析(录入→验证→业务→持久化→存储→联动)
- 5级质量门禁(L1编译→L2测试→L3DB审查→L4验收→L5归档)
- 8个Agent角色定义和协作流水线
- 8条过往教训(Bug#574等)

7个AI工具配置文件同步更新(全部430行内嵌)
This commit is contained in:
华佗
2026-06-06 09:56:25 +08:00
parent 355c905026
commit 84ba9a4139
8 changed files with 1846 additions and 230 deletions
Download Patch File Download Diff File Expand all files Collapse all files

258
.aider.conf.yml
View File

@@ -5,6 +5,8 @@ instructions: |
# HealthLink-HIS — AI 开发规范（自动加载）
> 🤖 **本文件供所有 AI 编码工具自动读取**。无论使用 Claude Code、Cursor、Codex CLI、Copilot、Qwen、Cline 还是其他工具，进入本项目后必须遵守以下规范。
>
> **模型决定上限，Harness 决定底线。**
---
@@ -18,9 +20,12 @@ instructions: |
| 文档路径 | `MD/` |
| JDK | 25 (OpenJDK) |
| Spring Boot | 4.0.6 |
| MyBatis-Plus | 3.5.16 |
| Vue | 3.x + Vite + Element Plus |
| 数据库 | PostgreSQL 15+ |
| 包名 | `com.healthlink.his` |
| 后端端口 | 18082 |
| 前端端口 | 81 |
---
@@ -34,7 +39,7 @@ instructions: |
前端: npm run build:dev → npm run lint
```
- 白盒：编译通过，无 ERROR
- 黑盒：关键接口返回 `{code:200, data:...}`
- 黑盒：关键接口返回 `{code:200, data:...}`，验证业务逻辑
- 冒烟：应用正常启动，核心流程通畅
**铁律2: Flyway 数据库迁移**
@@ -52,28 +57,159 @@ instructions: |
- 前端 `request.js` 的 baseURL 必须与后端匹配
- 接口变更必须同步更新前后端代码
**铁律5: 状态值一致性（来自 Bug #574 教训）**
- 修改任何状态值前，必须先列出完整的状态流转链路
- 检查项：
1. 枚举定义的值是否正确
2. Service 层设置的状态值是否与枚举一致
3. 查询/列表接口的状态映射是否覆盖所有枚举值
4. 前端 `STATUS_CLASS_MAP` 是否包含新状态
5. 前端过滤条件（如 `v-if`）是否兼容新状态
6. 池/统计表的聚合 SQL 是否包含新状态值
- 禁止：只改一端不检查其他端
**铁律6: 禁止删除源文件（来自 Bug #574 教训）**
- 绝对禁止删除项目中已有的 Java/Vue/SQL 源文件
- 文件有编译错误 → 修复错误，不删除文件
- 文件是重复的 → 重构合并，不删除文件
- 文件是 AI 幻觉创建的 → 检查 git baseline 确认后再删除
- 唯一例外：明确由人类确认删除的文件
**铁律7: 禁止修改已有公开方法签名**
- 不能删除或重命名已有的 public 方法
- 不能修改已有方法的参数列表
- 需要新增功能时 → 添加新的重载方法
- 需要改行为时 → 修改方法内部实现，不改签名
### 🟡 P1 铁律 — 强烈建议
**铁律5: 先分解再行动**
**铁律8: 先分解再行动**
- 修改超过3个文件、涉及多模块、数据库变更，必须先制定计划
**铁律6: 验证后信**
**铁律9: 验证后信**
- 每次修改后必须验证编译通过，不信记忆
- 重新编译命令：`mvn clean compile -DskipTests`
**铁律7: 文档统一管理**
**铁律10: 文档统一管理**
- 所有文档存储在 `MD/` 目录
- 文件名：大写英文+下划线（如 `BACKEND_CHECKLIST.md`）
- 文档头部必须包含元数据块（文档类型、版本、日期）
**铁律8: 规范文档在 MD/specs/**
- 完整铁律：`MD/specs/IRON_RULES.md`
- 后端规范：`MD/specs/BACKEND_DEVELOPMENT_STANDARD.md`
- 前端规范：`MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md`
---
## 三、全链路 6 环分析
> ⚠️ **涉及数据库字段的 Bug / 需求，必须走完整链路，不得"就事论事"。**
```
前端/页面 → Controller → Service → Mapper → DB/SQL → 关联模块
①录入 ②验证 ③业务 ④持久化 ⑤存储 ⑥联动
```
### 每一环必须确认
| 环 | 检查内容 |
|----|---------|
| ① 录入 | 前端有无输入入口（弹窗、表格行编辑、表单） |
| ② 验证 | Controller 参数校验、@Valid、权限控制 |
| ③ 业务 | Service 业务逻辑、事务边界、多个 Service 实现类入口 |
| ④ 持久化 | Mapper XML、DTO 字段映射、类型转换 |
| ⑤ 存储 | 数据库表结构、索引、NOT NULL 约束 |
| ⑥ 联动 | 上游（医嘱→护士站）、下游（打印、计费、报表）是否同步 |
### 全链路验证顺序
修复涉及状态流转的问题后，必须按以下顺序验证：
1. **数据库**：确认状态值已正确写入
2. **后端接口**：确认返回的状态映射正确
3. **前端显示**：确认页面显示正确状态文本
4. **前端交互**：确认按钮/操作基于正确状态启用/禁用
5. **统计数据**：确认池/报表统计包含新状态
### 常见陷阱
- ❌ 只修了「主入口」的保存逻辑，忘了「批量保存」「签发保存」等其他入口
- ❌ 前端加了输入框，后端 Service 没传字段
- ❌ Mapper XML 是 UNION ALL 查询，只改了其中一个子查询
- ❌ DTO 层级继承关系没检查
- ❌ 只测了新增，没测编辑已有数据的回显和修改再保存
---
## 三、后端开发规范
## 四、Harness Engineering 方法论
> Harness = 约束 + 反馈 + 控制平面 + 持久执行
### 4.1 四层约束金字塔
| 层级 | 内容 | 落地方式 |
|------|------|---------|
| **L1 架构约束** | 接口合约、包结构、命名规范、禁止模式 | 本文件铁律、AGENTS.md |
| **L2 代码质量** | 圈复杂度、代码风格、类型提示 | 编译门禁 + ESLint |
| **L3 安全约束** | 敏感信息检测、权限检查、输入验证 | 配置不可硬编码 |
| **L4 业务规则** | 领域逻辑、数据一致性、事务边界 | 全链路 6 环验证 |
**约束优先级**：安全 > 架构 > 质量 > 业务
### 4.2 三层反馈系统
| 层级 | 速度 | 覆盖范围 | 失败处理 |
|------|------|---------|---------|
| **L1 编译检查** | <30 秒 | 语法、类型、签名 | 立即阻断，自行修复 |
| **L2 数据流验证** | <5 分钟 | 全链路字段、Mapper XML、DTO | 修复后上报 |
| **L3 人工审查** | 10-30 分钟 | 架构、设计、业务正确性 | 驳回 / 指导 / 批准 |
**反馈设计铁律**：
- 反馈必须可行动（指出：文件 + 行号 + 错误类型 + 修复方向）
- 反馈越及时越好（L1 即时 → L2 分钟 → L3 小时）
- 失败后先回滚到最近检查点，再重试
### 4.3 控制平面（Agent 协调）
```
┌─────────────────────────────────────────────┐
│ 战略层（人类主导） │
│ ├── 设定目标、审批关键决策 │
│ └── 异常升级处理 │
├─────────────────────────────────────────────┤
│ 战术层（Control Plane） │
│ ├── 任务分解 + update_plan │
│ ├── 依赖协调 + 资源分配 │
│ └── 检查点保存 + 恢复 │
├─────────────────────────────────────────────┤
│ 执行层（Agent 自主） │
│ ├── 代码生成、测试执行 │
│ └── 错误恢复 + 幂等重试 │
└─────────────────────────────────────────────┘
```
### 4.4 持久执行
- 每个关键步骤保存检查点（`update_plan` 进度）
- 失败后从最新检查点恢复，不从头开始
- 幂等设计：同一操作重复执行结果一致
---
## 五、质量门禁（5 级）
| 级别 | 门禁 | 通过标准 |
|------|------|---------|
| **L1** | 编译通过 | `mvn clean compile` + `npm run build:dev` 无 ERROR |
| **L2** | 测试通过 | 单元测试 + 接口测试全部通过 |
| **L3** | DB 审查 | Flyway 脚本规范、SQL 安全、索引合理 |
| **L4** | 验收通过 | 核心功能流程完整验证、全链路检查 |
| **L5** | 归档完成 | Git commit + 文档更新 + 代码推送 |
### 提交铁律
- L1-L2 必须通过才能 commit
- L3（如有DB变更）必须通过才能 push
- L4-L5 发布前必须完成
---
## 六、后端开发规范
### 分层架构
```
@@ -104,12 +240,9 @@ instructions: |
### 统一返回格式
```java
// 成功
AjaxResult.success(data)
// 失败
AjaxResult.error("错误信息")
// 列表
getDataTable(list)
AjaxResult.success(data) // 成功
AjaxResult.error("错误信息") // 失败
getDataTable(list) // 列表
```
### 关键约束
@@ -117,11 +250,13 @@ instructions: |
- `@Transactional(rollbackFor = Exception.class)` 管理事务
- 所有接口标注 `@PreAuthorize` 权限控制
- 患者敏感信息（身份证、手机号）在日志中脱敏
- 扩展功能不要修改原有函数签名，新建 Service/AppService
- **扩展功能不修改原有函数签名**，新建 Service/AppService
- 涉及多表写操作的方法标注 `@Transactional`
- 事务方法未被同一类内方法直接调用（避免自调用失效）
---
## 四、前端开发规范
## 七、前端开发规范
### 技术栈
- Vue 3 + Vite + Element Plus + Pinia + Axios
@@ -157,16 +292,67 @@ instructions: |
---
## 五、开发流程
## 八、Agent 体系（智能体协作）
### 角色定义
| 代号 | 名称 | 角色 | 职责 |
|------|------|------|------|
| liubei | 刘备 | 项目经理 | 总协调、任务分配、异常升级 |
| zhugeliang | 诸葛亮 | 架构师 | 需求分析、方案设计、技术决策 |
| guanyu | 关羽 | 后端开发 | Java 后端修复、API 开发 |
| zhaoyun | 赵云 | 前端开发 | Vue 前端修复、页面开发 |
| xunyu | 荀彧 | DBA | 数据库审查、SQL 优化、Flyway 脚本 |
| zhangfei | 张飞 | 测试 | Playwright 测试、接口测试、回归测试 |
| huatuo | 华佗 | 验收 | 功能验收、质量确认、发布检查 |
| chenlin | 陈琳 | 文档 | 归档记录、文档更新、Git 提交 |
### 协作流水线
```
1. 分析需求 → 读相关文档(MD/)
2. 制定计划 → update_plan
3. 后端开发 → Controller → AppService → Service → Mapper → Entity → Flyway
4. 后端测试 → mvn test → 接口测试通过
5. 前端开发 → API接口 → 页面组件 → 路由配置
6. 前端测试 → npm run build:dev → 功能验证
7. 提交代码 → git add → git commit(规范格式) → git push
刘备(协调) → 诸葛亮(分析) → {关羽|赵云}(修复) → 荀彧(DB审查) → 张飞(测试) → 华佗(验收) → 陈琳(归档)
```
### Bug 状态管理铁律
- 人类提的 Bug：只加备注，不改状态，不改分配
- 智能体提的 Bug：可以改分配和加备注
- 已关闭/已解决的 Bug 不再处理
### 修复流程铁律
- 一次只修一个 Bug，不扩大范围
- 修复前必须读 AGENTS.md
- 修复后必须验证编译
- 涉及 SQL 必须先查真实数据库
### 测试流程铁律
- Playwright 必须 `--workers=1` 单线程
- 超时 120 秒
- 最多重试 3 次
- 测试结果写入禅道备注
### 归档流程铁律
- 三重归档：Git + SQLite + Redis
- SQLite 必须使用完整字段
- 禅道备注格式：`[📝 陈琳归档] Bug #xxx`
---
## 九、开发流程
```
收到任务
├→ ① 分析需求 → 读相关文档(MD/)、读全链路6环
├→ ② 制定计划 → update_plan (3-6个阶段)
├→ ③ 后端开发 → Controller → AppService → Service → Mapper → Entity → Flyway
├→ ④ 后端测试 → mvn test → 接口测试(业务逻辑验证)
├→ ⑤ 前端开发 → API接口 → 页面组件 → 路由配置
├→ ⑥ 前端测试 → npm run build:dev → 功能验证
├→ ⑦ 质量门禁 → L1编译 → L2测试 → L3DB审查 → L4验收 → L5归档
└→ ⑧ 提交代码 → git commit(规范格式) → git push → 文档更新
```
### Git Commit 格式
@@ -179,7 +365,7 @@ instructions: |
---
## 六、快速参考命令
## 十、快速参考命令
```bash
# === 后端 ===
@@ -204,7 +390,7 @@ instructions: |
---
## 七、详细规范文档索引
## 十一、详细规范文档索引
| 文档 | 路径 | 用途 |
|------|------|------|
@@ -216,7 +402,23 @@ instructions: |
| 前端清单 | `MD/specs/FRONTEND_CHECKLIST.md` | 发布前检查 |
| 三甲标准 | `MD/standards/GRADE3A_HIS_STANDARD.md` | 三甲医院达标标准 |
| Flyway指南 | `MD/guides/FLYWAY_USAGE_GUIDE.md` | 数据库迁移指南 |
| E2E测试 | `MD/specs/PLAYWRIGHT_TESTING_PLAN.md` | Playwright测试方案 |
---
> ⚠️ **警告**: 本文件是项目 AI 开发规范的唯一信源。各工具配置文件（AGENTS.md、.cursorrules 等）均引用本文件。修改规范请只修改本文件。
## 十二、过往教训（必须铭记）
| 教训 | 来源 | 教训内容 |
|------|------|---------|
| 状态链路断裂 | Bug #574 | `checkInTicket()` 设 BOOKED(1) 而非 CHECKED_IN(3)，前端映射缺失，池统计漏计 → 必须走完整状态链路验证 |
| 盲删源文件 | Bug #574 | AI 看到编译错误直接删文件，没检查是否在 baseline → 必须先确认文件来源再操作 |
| 修复方向偏差 | Bug #574 | 多次 fallback 改的是 OrderServiceImpl，完全没触及 TicketServiceImpl → 必须用 rg 搜索所有相关代码路径 |
| bug_reports 表缺少列 | 经验 | INSERT 会静默失败，必须检查表结构 |
| 禅道 comment API | 经验 | API 不存在，必须用 resolve+activate workaround |
| SQLite WAL 并发 | 经验 | 多进程并发写需要 checkpoint |
| UTF-8 切片 | 经验 | 多字节字符不能用 byte index 切片 |
| 禅道图片附件 | 经验 | 必须 OCR 读取，不能直接解析 |
---
> ⚠️ **警告**: 本文件是项目 AI 开发规范的唯一信源。各工具配置文件（AGENTS.md、.cursorrules 等）均通过 `bash scripts/sync-ai-rules.sh` 从本文件同步。修改规范请只修改本文件。

260
.clinerules
View File

@@ -7,6 +7,8 @@
# HealthLink-HIS — AI 开发规范（自动加载）
> 🤖 **本文件供所有 AI 编码工具自动读取**。无论使用 Claude Code、Cursor、Codex CLI、Copilot、Qwen、Cline 还是其他工具，进入本项目后必须遵守以下规范。
>
> **模型决定上限，Harness 决定底线。**
---
@@ -20,9 +22,12 @@
| 文档路径 | `MD/` |
| JDK | 25 (OpenJDK) |
| Spring Boot | 4.0.6 |
| MyBatis-Plus | 3.5.16 |
| Vue | 3.x + Vite + Element Plus |
| 数据库 | PostgreSQL 15+ |
| 包名 | `com.healthlink.his` |
| 后端端口 | 18082 |
| 前端端口 | 81 |
---
@@ -36,7 +41,7 @@
前端: npm run build:dev → npm run lint
```
- 白盒：编译通过，无 ERROR
- 黑盒：关键接口返回 `{code:200, data:...}`
- 黑盒：关键接口返回 `{code:200, data:...}`，验证业务逻辑
- 冒烟：应用正常启动，核心流程通畅
**铁律2: Flyway 数据库迁移**
@@ -54,28 +59,159 @@
- 前端 `request.js` 的 baseURL 必须与后端匹配
- 接口变更必须同步更新前后端代码
**铁律5: 状态值一致性（来自 Bug #574 教训）**
- 修改任何状态值前，必须先列出完整的状态流转链路
- 检查项：
1. 枚举定义的值是否正确
2. Service 层设置的状态值是否与枚举一致
3. 查询/列表接口的状态映射是否覆盖所有枚举值
4. 前端 `STATUS_CLASS_MAP` 是否包含新状态
5. 前端过滤条件（如 `v-if`）是否兼容新状态
6. 池/统计表的聚合 SQL 是否包含新状态值
- 禁止：只改一端不检查其他端
**铁律6: 禁止删除源文件（来自 Bug #574 教训）**
- 绝对禁止删除项目中已有的 Java/Vue/SQL 源文件
- 文件有编译错误 → 修复错误，不删除文件
- 文件是重复的 → 重构合并，不删除文件
- 文件是 AI 幻觉创建的 → 检查 git baseline 确认后再删除
- 唯一例外：明确由人类确认删除的文件
**铁律7: 禁止修改已有公开方法签名**
- 不能删除或重命名已有的 public 方法
- 不能修改已有方法的参数列表
- 需要新增功能时 → 添加新的重载方法
- 需要改行为时 → 修改方法内部实现，不改签名
### 🟡 P1 铁律 — 强烈建议
**铁律5: 先分解再行动**
**铁律8: 先分解再行动**
- 修改超过3个文件、涉及多模块、数据库变更，必须先制定计划
**铁律6: 验证后信**
**铁律9: 验证后信**
- 每次修改后必须验证编译通过，不信记忆
- 重新编译命令：`mvn clean compile -DskipTests`
**铁律7: 文档统一管理**
**铁律10: 文档统一管理**
- 所有文档存储在 `MD/` 目录
- 文件名：大写英文+下划线（如 `BACKEND_CHECKLIST.md`）
- 文档头部必须包含元数据块（文档类型、版本、日期）
**铁律8: 规范文档在 MD/specs/**
- 完整铁律：`MD/specs/IRON_RULES.md`
- 后端规范：`MD/specs/BACKEND_DEVELOPMENT_STANDARD.md`
- 前端规范：`MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md`
---
## 三、全链路 6 环分析
> ⚠️ **涉及数据库字段的 Bug / 需求，必须走完整链路，不得"就事论事"。**
```
前端/页面 → Controller → Service → Mapper → DB/SQL → 关联模块
①录入 ②验证 ③业务 ④持久化 ⑤存储 ⑥联动
```
### 每一环必须确认
| 环 | 检查内容 |
|----|---------|
| ① 录入 | 前端有无输入入口（弹窗、表格行编辑、表单） |
| ② 验证 | Controller 参数校验、@Valid、权限控制 |
| ③ 业务 | Service 业务逻辑、事务边界、多个 Service 实现类入口 |
| ④ 持久化 | Mapper XML、DTO 字段映射、类型转换 |
| ⑤ 存储 | 数据库表结构、索引、NOT NULL 约束 |
| ⑥ 联动 | 上游（医嘱→护士站）、下游（打印、计费、报表）是否同步 |
### 全链路验证顺序
修复涉及状态流转的问题后，必须按以下顺序验证：
1. **数据库**：确认状态值已正确写入
2. **后端接口**：确认返回的状态映射正确
3. **前端显示**：确认页面显示正确状态文本
4. **前端交互**：确认按钮/操作基于正确状态启用/禁用
5. **统计数据**：确认池/报表统计包含新状态
### 常见陷阱
- ❌ 只修了「主入口」的保存逻辑，忘了「批量保存」「签发保存」等其他入口
- ❌ 前端加了输入框，后端 Service 没传字段
- ❌ Mapper XML 是 UNION ALL 查询，只改了其中一个子查询
- ❌ DTO 层级继承关系没检查
- ❌ 只测了新增，没测编辑已有数据的回显和修改再保存
---
## 三、后端开发规范
## 四、Harness Engineering 方法论
> Harness = 约束 + 反馈 + 控制平面 + 持久执行
### 4.1 四层约束金字塔
| 层级 | 内容 | 落地方式 |
|------|------|---------|
| **L1 架构约束** | 接口合约、包结构、命名规范、禁止模式 | 本文件铁律、AGENTS.md |
| **L2 代码质量** | 圈复杂度、代码风格、类型提示 | 编译门禁 + ESLint |
| **L3 安全约束** | 敏感信息检测、权限检查、输入验证 | 配置不可硬编码 |
| **L4 业务规则** | 领域逻辑、数据一致性、事务边界 | 全链路 6 环验证 |
**约束优先级**：安全 > 架构 > 质量 > 业务
### 4.2 三层反馈系统
| 层级 | 速度 | 覆盖范围 | 失败处理 |
|------|------|---------|---------|
| **L1 编译检查** | <30 秒 | 语法、类型、签名 | 立即阻断，自行修复 |
| **L2 数据流验证** | <5 分钟 | 全链路字段、Mapper XML、DTO | 修复后上报 |
| **L3 人工审查** | 10-30 分钟 | 架构、设计、业务正确性 | 驳回 / 指导 / 批准 |
**反馈设计铁律**：
- 反馈必须可行动（指出：文件 + 行号 + 错误类型 + 修复方向）
- 反馈越及时越好（L1 即时 → L2 分钟 → L3 小时）
- 失败后先回滚到最近检查点，再重试
### 4.3 控制平面（Agent 协调）
```
┌─────────────────────────────────────────────┐
│ 战略层（人类主导） │
│ ├── 设定目标、审批关键决策 │
│ └── 异常升级处理 │
├─────────────────────────────────────────────┤
│ 战术层（Control Plane） │
│ ├── 任务分解 + update_plan │
│ ├── 依赖协调 + 资源分配 │
│ └── 检查点保存 + 恢复 │
├─────────────────────────────────────────────┤
│ 执行层（Agent 自主） │
│ ├── 代码生成、测试执行 │
│ └── 错误恢复 + 幂等重试 │
└─────────────────────────────────────────────┘
```
### 4.4 持久执行
- 每个关键步骤保存检查点（`update_plan` 进度）
- 失败后从最新检查点恢复，不从头开始
- 幂等设计：同一操作重复执行结果一致
---
## 五、质量门禁（5 级）
| 级别 | 门禁 | 通过标准 |
|------|------|---------|
| **L1** | 编译通过 | `mvn clean compile` + `npm run build:dev` 无 ERROR |
| **L2** | 测试通过 | 单元测试 + 接口测试全部通过 |
| **L3** | DB 审查 | Flyway 脚本规范、SQL 安全、索引合理 |
| **L4** | 验收通过 | 核心功能流程完整验证、全链路检查 |
| **L5** | 归档完成 | Git commit + 文档更新 + 代码推送 |
### 提交铁律
- L1-L2 必须通过才能 commit
- L3（如有DB变更）必须通过才能 push
- L4-L5 发布前必须完成
---
## 六、后端开发规范
### 分层架构
```
@@ -106,12 +242,9 @@ com.healthlink.his.common.enums
### 统一返回格式
```java
// 成功
AjaxResult.success(data)
// 失败
AjaxResult.error("错误信息")
// 列表
getDataTable(list)
AjaxResult.success(data) // 成功
AjaxResult.error("错误信息") // 失败
getDataTable(list) // 列表
```
### 关键约束
@@ -119,11 +252,13 @@ getDataTable(list)
- `@Transactional(rollbackFor = Exception.class)` 管理事务
- 所有接口标注 `@PreAuthorize` 权限控制
- 患者敏感信息（身份证、手机号）在日志中脱敏
- 扩展功能不要修改原有函数签名，新建 Service/AppService
- **扩展功能不修改原有函数签名**，新建 Service/AppService
- 涉及多表写操作的方法标注 `@Transactional`
- 事务方法未被同一类内方法直接调用（避免自调用失效）
---
## 四、前端开发规范
## 七、前端开发规范
### 技术栈
- Vue 3 + Vite + Element Plus + Pinia + Axios
@@ -159,16 +294,67 @@ export function listXxx(query) {
---
## 五、开发流程
## 八、Agent 体系（智能体协作）
### 角色定义
| 代号 | 名称 | 角色 | 职责 |
|------|------|------|------|
| liubei | 刘备 | 项目经理 | 总协调、任务分配、异常升级 |
| zhugeliang | 诸葛亮 | 架构师 | 需求分析、方案设计、技术决策 |
| guanyu | 关羽 | 后端开发 | Java 后端修复、API 开发 |
| zhaoyun | 赵云 | 前端开发 | Vue 前端修复、页面开发 |
| xunyu | 荀彧 | DBA | 数据库审查、SQL 优化、Flyway 脚本 |
| zhangfei | 张飞 | 测试 | Playwright 测试、接口测试、回归测试 |
| huatuo | 华佗 | 验收 | 功能验收、质量确认、发布检查 |
| chenlin | 陈琳 | 文档 | 归档记录、文档更新、Git 提交 |
### 协作流水线
```
1. 分析需求 → 读相关文档(MD/)
2. 制定计划 → update_plan
3. 后端开发 → Controller → AppService → Service → Mapper → Entity → Flyway
4. 后端测试 → mvn test → 接口测试通过
5. 前端开发 → API接口 → 页面组件 → 路由配置
6. 前端测试 → npm run build:dev → 功能验证
7. 提交代码 → git add → git commit(规范格式) → git push
刘备(协调) → 诸葛亮(分析) → {关羽|赵云}(修复) → 荀彧(DB审查) → 张飞(测试) → 华佗(验收) → 陈琳(归档)
```
### Bug 状态管理铁律
- 人类提的 Bug：只加备注，不改状态，不改分配
- 智能体提的 Bug：可以改分配和加备注
- 已关闭/已解决的 Bug 不再处理
### 修复流程铁律
- 一次只修一个 Bug，不扩大范围
- 修复前必须读 AGENTS.md
- 修复后必须验证编译
- 涉及 SQL 必须先查真实数据库
### 测试流程铁律
- Playwright 必须 `--workers=1` 单线程
- 超时 120 秒
- 最多重试 3 次
- 测试结果写入禅道备注
### 归档流程铁律
- 三重归档：Git + SQLite + Redis
- SQLite 必须使用完整字段
- 禅道备注格式：`[📝 陈琳归档] Bug #xxx`
---
## 九、开发流程
```
收到任务
├→ ① 分析需求 → 读相关文档(MD/)、读全链路6环
├→ ② 制定计划 → update_plan (3-6个阶段)
├→ ③ 后端开发 → Controller → AppService → Service → Mapper → Entity → Flyway
├→ ④ 后端测试 → mvn test → 接口测试(业务逻辑验证)
├→ ⑤ 前端开发 → API接口 → 页面组件 → 路由配置
├→ ⑥ 前端测试 → npm run build:dev → 功能验证
├→ ⑦ 质量门禁 → L1编译 → L2测试 → L3DB审查 → L4验收 → L5归档
└→ ⑧ 提交代码 → git commit(规范格式) → git push → 文档更新
```
### Git Commit 格式
@@ -181,7 +367,7 @@ scope: 模块名(如 registration, billing, pharmacy)
---
## 六、快速参考命令
## 十、快速参考命令
```bash
# === 后端 ===
@@ -206,7 +392,7 @@ git push origin develop # 推送
---
## 七、详细规范文档索引
## 十一、详细规范文档索引
| 文档 | 路径 | 用途 |
|------|------|------|
@@ -218,11 +404,27 @@ git push origin develop # 推送
| 前端清单 | `MD/specs/FRONTEND_CHECKLIST.md` | 发布前检查 |
| 三甲标准 | `MD/standards/GRADE3A_HIS_STANDARD.md` | 三甲医院达标标准 |
| Flyway指南 | `MD/guides/FLYWAY_USAGE_GUIDE.md` | 数据库迁移指南 |
| E2E测试 | `MD/specs/PLAYWRIGHT_TESTING_PLAN.md` | Playwright测试方案 |
---
> ⚠️ **警告**: 本文件是项目 AI 开发规范的唯一信源。各工具配置文件（AGENTS.md、.cursorrules 等）均引用本文件。修改规范请只修改本文件。
## 十二、过往教训（必须铭记）
| 教训 | 来源 | 教训内容 |
|------|------|---------|
| 状态链路断裂 | Bug #574 | `checkInTicket()` 设 BOOKED(1) 而非 CHECKED_IN(3)，前端映射缺失，池统计漏计 → 必须走完整状态链路验证 |
| 盲删源文件 | Bug #574 | AI 看到编译错误直接删文件，没检查是否在 baseline → 必须先确认文件来源再操作 |
| 修复方向偏差 | Bug #574 | 多次 fallback 改的是 OrderServiceImpl，完全没触及 TicketServiceImpl → 必须用 rg 搜索所有相关代码路径 |
| bug_reports 表缺少列 | 经验 | INSERT 会静默失败，必须检查表结构 |
| 禅道 comment API | 经验 | API 不存在，必须用 resolve+activate workaround |
| SQLite WAL 并发 | 经验 | 多进程并发写需要 checkpoint |
| UTF-8 切片 | 经验 | 多字节字符不能用 byte index 切片 |
| 禅道图片附件 | 经验 | 必须 OCR 读取，不能直接解析 |
---
> 📅 最后同步: 2026-06-06 09:46 | 源文件: RULES.md | 重新同步: `bash scripts/sync-ai-rules.sh`
> ⚠️ **警告**: 本文件是项目 AI 开发规范的唯一信源。各工具配置文件（AGENTS.md、.cursorrules 等）均通过 `bash scripts/sync-ai-rules.sh` 从本文件同步。修改规范请只修改本文件。
---
> 📅 最后同步: 2026-06-06 09:56 | 源文件: RULES.md | 重新同步: `bash scripts/sync-ai-rules.sh`

260
.cursorrules
View File

@@ -7,6 +7,8 @@
# HealthLink-HIS — AI 开发规范（自动加载）
> 🤖 **本文件供所有 AI 编码工具自动读取**。无论使用 Claude Code、Cursor、Codex CLI、Copilot、Qwen、Cline 还是其他工具，进入本项目后必须遵守以下规范。
>
> **模型决定上限，Harness 决定底线。**
---
@@ -20,9 +22,12 @@
| 文档路径 | `MD/` |
| JDK | 25 (OpenJDK) |
| Spring Boot | 4.0.6 |
| MyBatis-Plus | 3.5.16 |
| Vue | 3.x + Vite + Element Plus |
| 数据库 | PostgreSQL 15+ |
| 包名 | `com.healthlink.his` |
| 后端端口 | 18082 |
| 前端端口 | 81 |
---
@@ -36,7 +41,7 @@
前端: npm run build:dev → npm run lint
```
- 白盒：编译通过，无 ERROR
- 黑盒：关键接口返回 `{code:200, data:...}`
- 黑盒：关键接口返回 `{code:200, data:...}`，验证业务逻辑
- 冒烟：应用正常启动，核心流程通畅
**铁律2: Flyway 数据库迁移**
@@ -54,28 +59,159 @@
- 前端 `request.js` 的 baseURL 必须与后端匹配
- 接口变更必须同步更新前后端代码
**铁律5: 状态值一致性（来自 Bug #574 教训）**
- 修改任何状态值前，必须先列出完整的状态流转链路
- 检查项：
1. 枚举定义的值是否正确
2. Service 层设置的状态值是否与枚举一致
3. 查询/列表接口的状态映射是否覆盖所有枚举值
4. 前端 `STATUS_CLASS_MAP` 是否包含新状态
5. 前端过滤条件（如 `v-if`）是否兼容新状态
6. 池/统计表的聚合 SQL 是否包含新状态值
- 禁止：只改一端不检查其他端
**铁律6: 禁止删除源文件（来自 Bug #574 教训）**
- 绝对禁止删除项目中已有的 Java/Vue/SQL 源文件
- 文件有编译错误 → 修复错误，不删除文件
- 文件是重复的 → 重构合并，不删除文件
- 文件是 AI 幻觉创建的 → 检查 git baseline 确认后再删除
- 唯一例外：明确由人类确认删除的文件
**铁律7: 禁止修改已有公开方法签名**
- 不能删除或重命名已有的 public 方法
- 不能修改已有方法的参数列表
- 需要新增功能时 → 添加新的重载方法
- 需要改行为时 → 修改方法内部实现，不改签名
### 🟡 P1 铁律 — 强烈建议
**铁律5: 先分解再行动**
**铁律8: 先分解再行动**
- 修改超过3个文件、涉及多模块、数据库变更，必须先制定计划
**铁律6: 验证后信**
**铁律9: 验证后信**
- 每次修改后必须验证编译通过，不信记忆
- 重新编译命令：`mvn clean compile -DskipTests`
**铁律7: 文档统一管理**
**铁律10: 文档统一管理**
- 所有文档存储在 `MD/` 目录
- 文件名：大写英文+下划线（如 `BACKEND_CHECKLIST.md`）
- 文档头部必须包含元数据块（文档类型、版本、日期）
**铁律8: 规范文档在 MD/specs/**
- 完整铁律：`MD/specs/IRON_RULES.md`
- 后端规范：`MD/specs/BACKEND_DEVELOPMENT_STANDARD.md`
- 前端规范：`MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md`
---
## 三、全链路 6 环分析
> ⚠️ **涉及数据库字段的 Bug / 需求，必须走完整链路，不得"就事论事"。**
```
前端/页面 → Controller → Service → Mapper → DB/SQL → 关联模块
①录入 ②验证 ③业务 ④持久化 ⑤存储 ⑥联动
```
### 每一环必须确认
| 环 | 检查内容 |
|----|---------|
| ① 录入 | 前端有无输入入口（弹窗、表格行编辑、表单） |
| ② 验证 | Controller 参数校验、@Valid、权限控制 |
| ③ 业务 | Service 业务逻辑、事务边界、多个 Service 实现类入口 |
| ④ 持久化 | Mapper XML、DTO 字段映射、类型转换 |
| ⑤ 存储 | 数据库表结构、索引、NOT NULL 约束 |
| ⑥ 联动 | 上游（医嘱→护士站）、下游（打印、计费、报表）是否同步 |
### 全链路验证顺序
修复涉及状态流转的问题后，必须按以下顺序验证：
1. **数据库**：确认状态值已正确写入
2. **后端接口**：确认返回的状态映射正确
3. **前端显示**：确认页面显示正确状态文本
4. **前端交互**：确认按钮/操作基于正确状态启用/禁用
5. **统计数据**：确认池/报表统计包含新状态
### 常见陷阱
- ❌ 只修了「主入口」的保存逻辑，忘了「批量保存」「签发保存」等其他入口
- ❌ 前端加了输入框，后端 Service 没传字段
- ❌ Mapper XML 是 UNION ALL 查询，只改了其中一个子查询
- ❌ DTO 层级继承关系没检查
- ❌ 只测了新增，没测编辑已有数据的回显和修改再保存
---
## 三、后端开发规范
## 四、Harness Engineering 方法论
> Harness = 约束 + 反馈 + 控制平面 + 持久执行
### 4.1 四层约束金字塔
| 层级 | 内容 | 落地方式 |
|------|------|---------|
| **L1 架构约束** | 接口合约、包结构、命名规范、禁止模式 | 本文件铁律、AGENTS.md |
| **L2 代码质量** | 圈复杂度、代码风格、类型提示 | 编译门禁 + ESLint |
| **L3 安全约束** | 敏感信息检测、权限检查、输入验证 | 配置不可硬编码 |
| **L4 业务规则** | 领域逻辑、数据一致性、事务边界 | 全链路 6 环验证 |
**约束优先级**：安全 > 架构 > 质量 > 业务
### 4.2 三层反馈系统
| 层级 | 速度 | 覆盖范围 | 失败处理 |
|------|------|---------|---------|
| **L1 编译检查** | <30 秒 | 语法、类型、签名 | 立即阻断，自行修复 |
| **L2 数据流验证** | <5 分钟 | 全链路字段、Mapper XML、DTO | 修复后上报 |
| **L3 人工审查** | 10-30 分钟 | 架构、设计、业务正确性 | 驳回 / 指导 / 批准 |
**反馈设计铁律**：
- 反馈必须可行动（指出：文件 + 行号 + 错误类型 + 修复方向）
- 反馈越及时越好（L1 即时 → L2 分钟 → L3 小时）
- 失败后先回滚到最近检查点，再重试
### 4.3 控制平面（Agent 协调）
```
┌─────────────────────────────────────────────┐
│ 战略层（人类主导） │
│ ├── 设定目标、审批关键决策 │
│ └── 异常升级处理 │
├─────────────────────────────────────────────┤
│ 战术层（Control Plane） │
│ ├── 任务分解 + update_plan │
│ ├── 依赖协调 + 资源分配 │
│ └── 检查点保存 + 恢复 │
├─────────────────────────────────────────────┤
│ 执行层（Agent 自主） │
│ ├── 代码生成、测试执行 │
│ └── 错误恢复 + 幂等重试 │
└─────────────────────────────────────────────┘
```
### 4.4 持久执行
- 每个关键步骤保存检查点（`update_plan` 进度）
- 失败后从最新检查点恢复，不从头开始
- 幂等设计：同一操作重复执行结果一致
---
## 五、质量门禁（5 级）
| 级别 | 门禁 | 通过标准 |
|------|------|---------|
| **L1** | 编译通过 | `mvn clean compile` + `npm run build:dev` 无 ERROR |
| **L2** | 测试通过 | 单元测试 + 接口测试全部通过 |
| **L3** | DB 审查 | Flyway 脚本规范、SQL 安全、索引合理 |
| **L4** | 验收通过 | 核心功能流程完整验证、全链路检查 |
| **L5** | 归档完成 | Git commit + 文档更新 + 代码推送 |
### 提交铁律
- L1-L2 必须通过才能 commit
- L3（如有DB变更）必须通过才能 push
- L4-L5 发布前必须完成
---
## 六、后端开发规范
### 分层架构
```
@@ -106,12 +242,9 @@ com.healthlink.his.common.enums
### 统一返回格式
```java
// 成功
AjaxResult.success(data)
// 失败
AjaxResult.error("错误信息")
// 列表
getDataTable(list)
AjaxResult.success(data) // 成功
AjaxResult.error("错误信息") // 失败
getDataTable(list) // 列表
```
### 关键约束
@@ -119,11 +252,13 @@ getDataTable(list)
- `@Transactional(rollbackFor = Exception.class)` 管理事务
- 所有接口标注 `@PreAuthorize` 权限控制
- 患者敏感信息（身份证、手机号）在日志中脱敏
- 扩展功能不要修改原有函数签名，新建 Service/AppService
- **扩展功能不修改原有函数签名**，新建 Service/AppService
- 涉及多表写操作的方法标注 `@Transactional`
- 事务方法未被同一类内方法直接调用（避免自调用失效）
---
## 四、前端开发规范
## 七、前端开发规范
### 技术栈
- Vue 3 + Vite + Element Plus + Pinia + Axios
@@ -159,16 +294,67 @@ export function listXxx(query) {
---
## 五、开发流程
## 八、Agent 体系（智能体协作）
### 角色定义
| 代号 | 名称 | 角色 | 职责 |
|------|------|------|------|
| liubei | 刘备 | 项目经理 | 总协调、任务分配、异常升级 |
| zhugeliang | 诸葛亮 | 架构师 | 需求分析、方案设计、技术决策 |
| guanyu | 关羽 | 后端开发 | Java 后端修复、API 开发 |
| zhaoyun | 赵云 | 前端开发 | Vue 前端修复、页面开发 |
| xunyu | 荀彧 | DBA | 数据库审查、SQL 优化、Flyway 脚本 |
| zhangfei | 张飞 | 测试 | Playwright 测试、接口测试、回归测试 |
| huatuo | 华佗 | 验收 | 功能验收、质量确认、发布检查 |
| chenlin | 陈琳 | 文档 | 归档记录、文档更新、Git 提交 |
### 协作流水线
```
1. 分析需求 → 读相关文档(MD/)
2. 制定计划 → update_plan
3. 后端开发 → Controller → AppService → Service → Mapper → Entity → Flyway
4. 后端测试 → mvn test → 接口测试通过
5. 前端开发 → API接口 → 页面组件 → 路由配置
6. 前端测试 → npm run build:dev → 功能验证
7. 提交代码 → git add → git commit(规范格式) → git push
刘备(协调) → 诸葛亮(分析) → {关羽|赵云}(修复) → 荀彧(DB审查) → 张飞(测试) → 华佗(验收) → 陈琳(归档)
```
### Bug 状态管理铁律
- 人类提的 Bug：只加备注，不改状态，不改分配
- 智能体提的 Bug：可以改分配和加备注
- 已关闭/已解决的 Bug 不再处理
### 修复流程铁律
- 一次只修一个 Bug，不扩大范围
- 修复前必须读 AGENTS.md
- 修复后必须验证编译
- 涉及 SQL 必须先查真实数据库
### 测试流程铁律
- Playwright 必须 `--workers=1` 单线程
- 超时 120 秒
- 最多重试 3 次
- 测试结果写入禅道备注
### 归档流程铁律
- 三重归档：Git + SQLite + Redis
- SQLite 必须使用完整字段
- 禅道备注格式：`[📝 陈琳归档] Bug #xxx`
---
## 九、开发流程
```
收到任务
├→ ① 分析需求 → 读相关文档(MD/)、读全链路6环
├→ ② 制定计划 → update_plan (3-6个阶段)
├→ ③ 后端开发 → Controller → AppService → Service → Mapper → Entity → Flyway
├→ ④ 后端测试 → mvn test → 接口测试(业务逻辑验证)
├→ ⑤ 前端开发 → API接口 → 页面组件 → 路由配置
├→ ⑥ 前端测试 → npm run build:dev → 功能验证
├→ ⑦ 质量门禁 → L1编译 → L2测试 → L3DB审查 → L4验收 → L5归档
└→ ⑧ 提交代码 → git commit(规范格式) → git push → 文档更新
```
### Git Commit 格式
@@ -181,7 +367,7 @@ scope: 模块名(如 registration, billing, pharmacy)
---
## 六、快速参考命令
## 十、快速参考命令
```bash
# === 后端 ===
@@ -206,7 +392,7 @@ git push origin develop # 推送
---
## 七、详细规范文档索引
## 十一、详细规范文档索引
| 文档 | 路径 | 用途 |
|------|------|------|
@@ -218,11 +404,27 @@ git push origin develop # 推送
| 前端清单 | `MD/specs/FRONTEND_CHECKLIST.md` | 发布前检查 |
| 三甲标准 | `MD/standards/GRADE3A_HIS_STANDARD.md` | 三甲医院达标标准 |
| Flyway指南 | `MD/guides/FLYWAY_USAGE_GUIDE.md` | 数据库迁移指南 |
| E2E测试 | `MD/specs/PLAYWRIGHT_TESTING_PLAN.md` | Playwright测试方案 |
---
> ⚠️ **警告**: 本文件是项目 AI 开发规范的唯一信源。各工具配置文件（AGENTS.md、.cursorrules 等）均引用本文件。修改规范请只修改本文件。
## 十二、过往教训（必须铭记）
| 教训 | 来源 | 教训内容 |
|------|------|---------|
| 状态链路断裂 | Bug #574 | `checkInTicket()` 设 BOOKED(1) 而非 CHECKED_IN(3)，前端映射缺失，池统计漏计 → 必须走完整状态链路验证 |
| 盲删源文件 | Bug #574 | AI 看到编译错误直接删文件，没检查是否在 baseline → 必须先确认文件来源再操作 |
| 修复方向偏差 | Bug #574 | 多次 fallback 改的是 OrderServiceImpl，完全没触及 TicketServiceImpl → 必须用 rg 搜索所有相关代码路径 |
| bug_reports 表缺少列 | 经验 | INSERT 会静默失败，必须检查表结构 |
| 禅道 comment API | 经验 | API 不存在，必须用 resolve+activate workaround |
| SQLite WAL 并发 | 经验 | 多进程并发写需要 checkpoint |
| UTF-8 切片 | 经验 | 多字节字符不能用 byte index 切片 |
| 禅道图片附件 | 经验 | 必须 OCR 读取，不能直接解析 |
---
> 📅 最后同步: 2026-06-06 09:46 | 源文件: RULES.md | 重新同步: `bash scripts/sync-ai-rules.sh`
> ⚠️ **警告**: 本文件是项目 AI 开发规范的唯一信源。各工具配置文件（AGENTS.md、.cursorrules 等）均通过 `bash scripts/sync-ai-rules.sh` 从本文件同步。修改规范请只修改本文件。
---
> 📅 最后同步: 2026-06-06 09:56 | 源文件: RULES.md | 重新同步: `bash scripts/sync-ai-rules.sh`

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

@@ -7,6 +7,8 @@
# HealthLink-HIS — AI 开发规范（自动加载）
> 🤖 **本文件供所有 AI 编码工具自动读取**。无论使用 Claude Code、Cursor、Codex CLI、Copilot、Qwen、Cline 还是其他工具，进入本项目后必须遵守以下规范。
>
> **模型决定上限，Harness 决定底线。**
---
@@ -20,9 +22,12 @@
| 文档路径 | `MD/` |
| JDK | 25 (OpenJDK) |
| Spring Boot | 4.0.6 |
| MyBatis-Plus | 3.5.16 |
| Vue | 3.x + Vite + Element Plus |
| 数据库 | PostgreSQL 15+ |
| 包名 | `com.healthlink.his` |
| 后端端口 | 18082 |
| 前端端口 | 81 |
---
@@ -36,7 +41,7 @@
前端: npm run build:dev → npm run lint
```
- 白盒：编译通过，无 ERROR
- 黑盒：关键接口返回 `{code:200, data:...}`
- 黑盒：关键接口返回 `{code:200, data:...}`，验证业务逻辑
- 冒烟：应用正常启动，核心流程通畅
**铁律2: Flyway 数据库迁移**
@@ -54,28 +59,159 @@
- 前端 `request.js` 的 baseURL 必须与后端匹配
- 接口变更必须同步更新前后端代码
**铁律5: 状态值一致性（来自 Bug #574 教训）**
- 修改任何状态值前，必须先列出完整的状态流转链路
- 检查项：
1. 枚举定义的值是否正确
2. Service 层设置的状态值是否与枚举一致
3. 查询/列表接口的状态映射是否覆盖所有枚举值
4. 前端 `STATUS_CLASS_MAP` 是否包含新状态
5. 前端过滤条件（如 `v-if`）是否兼容新状态
6. 池/统计表的聚合 SQL 是否包含新状态值
- 禁止：只改一端不检查其他端
**铁律6: 禁止删除源文件（来自 Bug #574 教训）**
- 绝对禁止删除项目中已有的 Java/Vue/SQL 源文件
- 文件有编译错误 → 修复错误，不删除文件
- 文件是重复的 → 重构合并，不删除文件
- 文件是 AI 幻觉创建的 → 检查 git baseline 确认后再删除
- 唯一例外：明确由人类确认删除的文件
**铁律7: 禁止修改已有公开方法签名**
- 不能删除或重命名已有的 public 方法
- 不能修改已有方法的参数列表
- 需要新增功能时 → 添加新的重载方法
- 需要改行为时 → 修改方法内部实现，不改签名
### 🟡 P1 铁律 — 强烈建议
**铁律5: 先分解再行动**
**铁律8: 先分解再行动**
- 修改超过3个文件、涉及多模块、数据库变更，必须先制定计划
**铁律6: 验证后信**
**铁律9: 验证后信**
- 每次修改后必须验证编译通过，不信记忆
- 重新编译命令：`mvn clean compile -DskipTests`
**铁律7: 文档统一管理**
**铁律10: 文档统一管理**
- 所有文档存储在 `MD/` 目录
- 文件名：大写英文+下划线（如 `BACKEND_CHECKLIST.md`）
- 文档头部必须包含元数据块（文档类型、版本、日期）
**铁律8: 规范文档在 MD/specs/**
- 完整铁律：`MD/specs/IRON_RULES.md`
- 后端规范：`MD/specs/BACKEND_DEVELOPMENT_STANDARD.md`
- 前端规范：`MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md`
---
## 三、全链路 6 环分析
> ⚠️ **涉及数据库字段的 Bug / 需求，必须走完整链路，不得"就事论事"。**
```
前端/页面 → Controller → Service → Mapper → DB/SQL → 关联模块
①录入 ②验证 ③业务 ④持久化 ⑤存储 ⑥联动
```
### 每一环必须确认
| 环 | 检查内容 |
|----|---------|
| ① 录入 | 前端有无输入入口（弹窗、表格行编辑、表单） |
| ② 验证 | Controller 参数校验、@Valid、权限控制 |
| ③ 业务 | Service 业务逻辑、事务边界、多个 Service 实现类入口 |
| ④ 持久化 | Mapper XML、DTO 字段映射、类型转换 |
| ⑤ 存储 | 数据库表结构、索引、NOT NULL 约束 |
| ⑥ 联动 | 上游（医嘱→护士站）、下游（打印、计费、报表）是否同步 |
### 全链路验证顺序
修复涉及状态流转的问题后，必须按以下顺序验证：
1. **数据库**：确认状态值已正确写入
2. **后端接口**：确认返回的状态映射正确
3. **前端显示**：确认页面显示正确状态文本
4. **前端交互**：确认按钮/操作基于正确状态启用/禁用
5. **统计数据**：确认池/报表统计包含新状态
### 常见陷阱
- ❌ 只修了「主入口」的保存逻辑，忘了「批量保存」「签发保存」等其他入口
- ❌ 前端加了输入框，后端 Service 没传字段
- ❌ Mapper XML 是 UNION ALL 查询，只改了其中一个子查询
- ❌ DTO 层级继承关系没检查
- ❌ 只测了新增，没测编辑已有数据的回显和修改再保存
---
## 三、后端开发规范
## 四、Harness Engineering 方法论
> Harness = 约束 + 反馈 + 控制平面 + 持久执行
### 4.1 四层约束金字塔
| 层级 | 内容 | 落地方式 |
|------|------|---------|
| **L1 架构约束** | 接口合约、包结构、命名规范、禁止模式 | 本文件铁律、AGENTS.md |
| **L2 代码质量** | 圈复杂度、代码风格、类型提示 | 编译门禁 + ESLint |
| **L3 安全约束** | 敏感信息检测、权限检查、输入验证 | 配置不可硬编码 |
| **L4 业务规则** | 领域逻辑、数据一致性、事务边界 | 全链路 6 环验证 |
**约束优先级**：安全 > 架构 > 质量 > 业务
### 4.2 三层反馈系统
| 层级 | 速度 | 覆盖范围 | 失败处理 |
|------|------|---------|---------|
| **L1 编译检查** | <30 秒 | 语法、类型、签名 | 立即阻断，自行修复 |
| **L2 数据流验证** | <5 分钟 | 全链路字段、Mapper XML、DTO | 修复后上报 |
| **L3 人工审查** | 10-30 分钟 | 架构、设计、业务正确性 | 驳回 / 指导 / 批准 |
**反馈设计铁律**：
- 反馈必须可行动（指出：文件 + 行号 + 错误类型 + 修复方向）
- 反馈越及时越好（L1 即时 → L2 分钟 → L3 小时）
- 失败后先回滚到最近检查点，再重试
### 4.3 控制平面（Agent 协调）
```
┌─────────────────────────────────────────────┐
│ 战略层（人类主导） │
│ ├── 设定目标、审批关键决策 │
│ └── 异常升级处理 │
├─────────────────────────────────────────────┤
│ 战术层（Control Plane） │
│ ├── 任务分解 + update_plan │
│ ├── 依赖协调 + 资源分配 │
│ └── 检查点保存 + 恢复 │
├─────────────────────────────────────────────┤
│ 执行层（Agent 自主） │
│ ├── 代码生成、测试执行 │
│ └── 错误恢复 + 幂等重试 │
└─────────────────────────────────────────────┘
```
### 4.4 持久执行
- 每个关键步骤保存检查点（`update_plan` 进度）
- 失败后从最新检查点恢复，不从头开始
- 幂等设计：同一操作重复执行结果一致
---
## 五、质量门禁（5 级）
| 级别 | 门禁 | 通过标准 |
|------|------|---------|
| **L1** | 编译通过 | `mvn clean compile` + `npm run build:dev` 无 ERROR |
| **L2** | 测试通过 | 单元测试 + 接口测试全部通过 |
| **L3** | DB 审查 | Flyway 脚本规范、SQL 安全、索引合理 |
| **L4** | 验收通过 | 核心功能流程完整验证、全链路检查 |
| **L5** | 归档完成 | Git commit + 文档更新 + 代码推送 |
### 提交铁律
- L1-L2 必须通过才能 commit
- L3（如有DB变更）必须通过才能 push
- L4-L5 发布前必须完成
---
## 六、后端开发规范
### 分层架构
```
@@ -106,12 +242,9 @@ com.healthlink.his.common.enums
### 统一返回格式
```java
// 成功
AjaxResult.success(data)
// 失败
AjaxResult.error("错误信息")
// 列表
getDataTable(list)
AjaxResult.success(data) // 成功
AjaxResult.error("错误信息") // 失败
getDataTable(list) // 列表
```
### 关键约束
@@ -119,11 +252,13 @@ getDataTable(list)
- `@Transactional(rollbackFor = Exception.class)` 管理事务
- 所有接口标注 `@PreAuthorize` 权限控制
- 患者敏感信息（身份证、手机号）在日志中脱敏
- 扩展功能不要修改原有函数签名，新建 Service/AppService
- **扩展功能不修改原有函数签名**，新建 Service/AppService
- 涉及多表写操作的方法标注 `@Transactional`
- 事务方法未被同一类内方法直接调用（避免自调用失效）
---
## 四、前端开发规范
## 七、前端开发规范
### 技术栈
- Vue 3 + Vite + Element Plus + Pinia + Axios
@@ -159,16 +294,67 @@ export function listXxx(query) {
---
## 五、开发流程
## 八、Agent 体系（智能体协作）
### 角色定义
| 代号 | 名称 | 角色 | 职责 |
|------|------|------|------|
| liubei | 刘备 | 项目经理 | 总协调、任务分配、异常升级 |
| zhugeliang | 诸葛亮 | 架构师 | 需求分析、方案设计、技术决策 |
| guanyu | 关羽 | 后端开发 | Java 后端修复、API 开发 |
| zhaoyun | 赵云 | 前端开发 | Vue 前端修复、页面开发 |
| xunyu | 荀彧 | DBA | 数据库审查、SQL 优化、Flyway 脚本 |
| zhangfei | 张飞 | 测试 | Playwright 测试、接口测试、回归测试 |
| huatuo | 华佗 | 验收 | 功能验收、质量确认、发布检查 |
| chenlin | 陈琳 | 文档 | 归档记录、文档更新、Git 提交 |
### 协作流水线
```
1. 分析需求 → 读相关文档(MD/)
2. 制定计划 → update_plan
3. 后端开发 → Controller → AppService → Service → Mapper → Entity → Flyway
4. 后端测试 → mvn test → 接口测试通过
5. 前端开发 → API接口 → 页面组件 → 路由配置
6. 前端测试 → npm run build:dev → 功能验证
7. 提交代码 → git add → git commit(规范格式) → git push
刘备(协调) → 诸葛亮(分析) → {关羽|赵云}(修复) → 荀彧(DB审查) → 张飞(测试) → 华佗(验收) → 陈琳(归档)
```
### Bug 状态管理铁律
- 人类提的 Bug：只加备注，不改状态，不改分配
- 智能体提的 Bug：可以改分配和加备注
- 已关闭/已解决的 Bug 不再处理
### 修复流程铁律
- 一次只修一个 Bug，不扩大范围
- 修复前必须读 AGENTS.md
- 修复后必须验证编译
- 涉及 SQL 必须先查真实数据库
### 测试流程铁律
- Playwright 必须 `--workers=1` 单线程
- 超时 120 秒
- 最多重试 3 次
- 测试结果写入禅道备注
### 归档流程铁律
- 三重归档：Git + SQLite + Redis
- SQLite 必须使用完整字段
- 禅道备注格式：`[📝 陈琳归档] Bug #xxx`
---
## 九、开发流程
```
收到任务
├→ ① 分析需求 → 读相关文档(MD/)、读全链路6环
├→ ② 制定计划 → update_plan (3-6个阶段)
├→ ③ 后端开发 → Controller → AppService → Service → Mapper → Entity → Flyway
├→ ④ 后端测试 → mvn test → 接口测试(业务逻辑验证)
├→ ⑤ 前端开发 → API接口 → 页面组件 → 路由配置
├→ ⑥ 前端测试 → npm run build:dev → 功能验证
├→ ⑦ 质量门禁 → L1编译 → L2测试 → L3DB审查 → L4验收 → L5归档
└→ ⑧ 提交代码 → git commit(规范格式) → git push → 文档更新
```
### Git Commit 格式
@@ -181,7 +367,7 @@ scope: 模块名(如 registration, billing, pharmacy)
---
## 六、快速参考命令
## 十、快速参考命令
```bash
# === 后端 ===
@@ -206,7 +392,7 @@ git push origin develop # 推送
---
## 七、详细规范文档索引
## 十一、详细规范文档索引
| 文档 | 路径 | 用途 |
|------|------|------|
@@ -218,11 +404,27 @@ git push origin develop # 推送
| 前端清单 | `MD/specs/FRONTEND_CHECKLIST.md` | 发布前检查 |
| 三甲标准 | `MD/standards/GRADE3A_HIS_STANDARD.md` | 三甲医院达标标准 |
| Flyway指南 | `MD/guides/FLYWAY_USAGE_GUIDE.md` | 数据库迁移指南 |
| E2E测试 | `MD/specs/PLAYWRIGHT_TESTING_PLAN.md` | Playwright测试方案 |
---
> ⚠️ **警告**: 本文件是项目 AI 开发规范的唯一信源。各工具配置文件（AGENTS.md、.cursorrules 等）均引用本文件。修改规范请只修改本文件。
## 十二、过往教训（必须铭记）
| 教训 | 来源 | 教训内容 |
|------|------|---------|
| 状态链路断裂 | Bug #574 | `checkInTicket()` 设 BOOKED(1) 而非 CHECKED_IN(3)，前端映射缺失，池统计漏计 → 必须走完整状态链路验证 |
| 盲删源文件 | Bug #574 | AI 看到编译错误直接删文件，没检查是否在 baseline → 必须先确认文件来源再操作 |
| 修复方向偏差 | Bug #574 | 多次 fallback 改的是 OrderServiceImpl，完全没触及 TicketServiceImpl → 必须用 rg 搜索所有相关代码路径 |
| bug_reports 表缺少列 | 经验 | INSERT 会静默失败，必须检查表结构 |
| 禅道 comment API | 经验 | API 不存在，必须用 resolve+activate workaround |
| SQLite WAL 并发 | 经验 | 多进程并发写需要 checkpoint |
| UTF-8 切片 | 经验 | 多字节字符不能用 byte index 切片 |
| 禅道图片附件 | 经验 | 必须 OCR 读取，不能直接解析 |
---
> 📅 最后同步: 2026-06-06 09:46 | 源文件: RULES.md | 重新同步: `bash scripts/sync-ai-rules.sh`
> ⚠️ **警告**: 本文件是项目 AI 开发规范的唯一信源。各工具配置文件（AGENTS.md、.cursorrules 等）均通过 `bash scripts/sync-ai-rules.sh` 从本文件同步。修改规范请只修改本文件。
---
> 📅 最后同步: 2026-06-06 09:56 | 源文件: RULES.md | 重新同步: `bash scripts/sync-ai-rules.sh`

260
.qwenrules
View File

@@ -7,6 +7,8 @@
# HealthLink-HIS — AI 开发规范（自动加载）
> 🤖 **本文件供所有 AI 编码工具自动读取**。无论使用 Claude Code、Cursor、Codex CLI、Copilot、Qwen、Cline 还是其他工具，进入本项目后必须遵守以下规范。
>
> **模型决定上限，Harness 决定底线。**
---
@@ -20,9 +22,12 @@
| 文档路径 | `MD/` |
| JDK | 25 (OpenJDK) |
| Spring Boot | 4.0.6 |
| MyBatis-Plus | 3.5.16 |
| Vue | 3.x + Vite + Element Plus |
| 数据库 | PostgreSQL 15+ |
| 包名 | `com.healthlink.his` |
| 后端端口 | 18082 |
| 前端端口 | 81 |
---
@@ -36,7 +41,7 @@
前端: npm run build:dev → npm run lint
```
- 白盒：编译通过，无 ERROR
- 黑盒：关键接口返回 `{code:200, data:...}`
- 黑盒：关键接口返回 `{code:200, data:...}`，验证业务逻辑
- 冒烟：应用正常启动，核心流程通畅
**铁律2: Flyway 数据库迁移**
@@ -54,28 +59,159 @@
- 前端 `request.js` 的 baseURL 必须与后端匹配
- 接口变更必须同步更新前后端代码
**铁律5: 状态值一致性（来自 Bug #574 教训）**
- 修改任何状态值前，必须先列出完整的状态流转链路
- 检查项：
1. 枚举定义的值是否正确
2. Service 层设置的状态值是否与枚举一致
3. 查询/列表接口的状态映射是否覆盖所有枚举值
4. 前端 `STATUS_CLASS_MAP` 是否包含新状态
5. 前端过滤条件（如 `v-if`）是否兼容新状态
6. 池/统计表的聚合 SQL 是否包含新状态值
- 禁止：只改一端不检查其他端
**铁律6: 禁止删除源文件（来自 Bug #574 教训）**
- 绝对禁止删除项目中已有的 Java/Vue/SQL 源文件
- 文件有编译错误 → 修复错误，不删除文件
- 文件是重复的 → 重构合并，不删除文件
- 文件是 AI 幻觉创建的 → 检查 git baseline 确认后再删除
- 唯一例外：明确由人类确认删除的文件
**铁律7: 禁止修改已有公开方法签名**
- 不能删除或重命名已有的 public 方法
- 不能修改已有方法的参数列表
- 需要新增功能时 → 添加新的重载方法
- 需要改行为时 → 修改方法内部实现，不改签名
### 🟡 P1 铁律 — 强烈建议
**铁律5: 先分解再行动**
**铁律8: 先分解再行动**
- 修改超过3个文件、涉及多模块、数据库变更，必须先制定计划
**铁律6: 验证后信**
**铁律9: 验证后信**
- 每次修改后必须验证编译通过，不信记忆
- 重新编译命令：`mvn clean compile -DskipTests`
**铁律7: 文档统一管理**
**铁律10: 文档统一管理**
- 所有文档存储在 `MD/` 目录
- 文件名：大写英文+下划线（如 `BACKEND_CHECKLIST.md`）
- 文档头部必须包含元数据块（文档类型、版本、日期）
**铁律8: 规范文档在 MD/specs/**
- 完整铁律：`MD/specs/IRON_RULES.md`
- 后端规范：`MD/specs/BACKEND_DEVELOPMENT_STANDARD.md`
- 前端规范：`MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md`
---
## 三、全链路 6 环分析
> ⚠️ **涉及数据库字段的 Bug / 需求，必须走完整链路，不得"就事论事"。**
```
前端/页面 → Controller → Service → Mapper → DB/SQL → 关联模块
①录入 ②验证 ③业务 ④持久化 ⑤存储 ⑥联动
```
### 每一环必须确认
| 环 | 检查内容 |
|----|---------|
| ① 录入 | 前端有无输入入口（弹窗、表格行编辑、表单） |
| ② 验证 | Controller 参数校验、@Valid、权限控制 |
| ③ 业务 | Service 业务逻辑、事务边界、多个 Service 实现类入口 |
| ④ 持久化 | Mapper XML、DTO 字段映射、类型转换 |
| ⑤ 存储 | 数据库表结构、索引、NOT NULL 约束 |
| ⑥ 联动 | 上游（医嘱→护士站）、下游（打印、计费、报表）是否同步 |
### 全链路验证顺序
修复涉及状态流转的问题后，必须按以下顺序验证：
1. **数据库**：确认状态值已正确写入
2. **后端接口**：确认返回的状态映射正确
3. **前端显示**：确认页面显示正确状态文本
4. **前端交互**：确认按钮/操作基于正确状态启用/禁用
5. **统计数据**：确认池/报表统计包含新状态
### 常见陷阱
- ❌ 只修了「主入口」的保存逻辑，忘了「批量保存」「签发保存」等其他入口
- ❌ 前端加了输入框，后端 Service 没传字段
- ❌ Mapper XML 是 UNION ALL 查询，只改了其中一个子查询
- ❌ DTO 层级继承关系没检查
- ❌ 只测了新增，没测编辑已有数据的回显和修改再保存
---
## 三、后端开发规范
## 四、Harness Engineering 方法论
> Harness = 约束 + 反馈 + 控制平面 + 持久执行
### 4.1 四层约束金字塔
| 层级 | 内容 | 落地方式 |
|------|------|---------|
| **L1 架构约束** | 接口合约、包结构、命名规范、禁止模式 | 本文件铁律、AGENTS.md |
| **L2 代码质量** | 圈复杂度、代码风格、类型提示 | 编译门禁 + ESLint |
| **L3 安全约束** | 敏感信息检测、权限检查、输入验证 | 配置不可硬编码 |
| **L4 业务规则** | 领域逻辑、数据一致性、事务边界 | 全链路 6 环验证 |
**约束优先级**：安全 > 架构 > 质量 > 业务
### 4.2 三层反馈系统
| 层级 | 速度 | 覆盖范围 | 失败处理 |
|------|------|---------|---------|
| **L1 编译检查** | <30 秒 | 语法、类型、签名 | 立即阻断，自行修复 |
| **L2 数据流验证** | <5 分钟 | 全链路字段、Mapper XML、DTO | 修复后上报 |
| **L3 人工审查** | 10-30 分钟 | 架构、设计、业务正确性 | 驳回 / 指导 / 批准 |
**反馈设计铁律**：
- 反馈必须可行动（指出：文件 + 行号 + 错误类型 + 修复方向）
- 反馈越及时越好（L1 即时 → L2 分钟 → L3 小时）
- 失败后先回滚到最近检查点，再重试
### 4.3 控制平面（Agent 协调）
```
┌─────────────────────────────────────────────┐
│ 战略层（人类主导） │
│ ├── 设定目标、审批关键决策 │
│ └── 异常升级处理 │
├─────────────────────────────────────────────┤
│ 战术层（Control Plane） │
│ ├── 任务分解 + update_plan │
│ ├── 依赖协调 + 资源分配 │
│ └── 检查点保存 + 恢复 │
├─────────────────────────────────────────────┤
│ 执行层（Agent 自主） │
│ ├── 代码生成、测试执行 │
│ └── 错误恢复 + 幂等重试 │
└─────────────────────────────────────────────┘
```
### 4.4 持久执行
- 每个关键步骤保存检查点（`update_plan` 进度）
- 失败后从最新检查点恢复，不从头开始
- 幂等设计：同一操作重复执行结果一致
---
## 五、质量门禁（5 级）
| 级别 | 门禁 | 通过标准 |
|------|------|---------|
| **L1** | 编译通过 | `mvn clean compile` + `npm run build:dev` 无 ERROR |
| **L2** | 测试通过 | 单元测试 + 接口测试全部通过 |
| **L3** | DB 审查 | Flyway 脚本规范、SQL 安全、索引合理 |
| **L4** | 验收通过 | 核心功能流程完整验证、全链路检查 |
| **L5** | 归档完成 | Git commit + 文档更新 + 代码推送 |
### 提交铁律
- L1-L2 必须通过才能 commit
- L3（如有DB变更）必须通过才能 push
- L4-L5 发布前必须完成
---
## 六、后端开发规范
### 分层架构
```
@@ -106,12 +242,9 @@ com.healthlink.his.common.enums
### 统一返回格式
```java
// 成功
AjaxResult.success(data)
// 失败
AjaxResult.error("错误信息")
// 列表
getDataTable(list)
AjaxResult.success(data) // 成功
AjaxResult.error("错误信息") // 失败
getDataTable(list) // 列表
```
### 关键约束
@@ -119,11 +252,13 @@ getDataTable(list)
- `@Transactional(rollbackFor = Exception.class)` 管理事务
- 所有接口标注 `@PreAuthorize` 权限控制
- 患者敏感信息（身份证、手机号）在日志中脱敏
- 扩展功能不要修改原有函数签名，新建 Service/AppService
- **扩展功能不修改原有函数签名**，新建 Service/AppService
- 涉及多表写操作的方法标注 `@Transactional`
- 事务方法未被同一类内方法直接调用（避免自调用失效）
---
## 四、前端开发规范
## 七、前端开发规范
### 技术栈
- Vue 3 + Vite + Element Plus + Pinia + Axios
@@ -159,16 +294,67 @@ export function listXxx(query) {
---
## 五、开发流程
## 八、Agent 体系（智能体协作）
### 角色定义
| 代号 | 名称 | 角色 | 职责 |
|------|------|------|------|
| liubei | 刘备 | 项目经理 | 总协调、任务分配、异常升级 |
| zhugeliang | 诸葛亮 | 架构师 | 需求分析、方案设计、技术决策 |
| guanyu | 关羽 | 后端开发 | Java 后端修复、API 开发 |
| zhaoyun | 赵云 | 前端开发 | Vue 前端修复、页面开发 |
| xunyu | 荀彧 | DBA | 数据库审查、SQL 优化、Flyway 脚本 |
| zhangfei | 张飞 | 测试 | Playwright 测试、接口测试、回归测试 |
| huatuo | 华佗 | 验收 | 功能验收、质量确认、发布检查 |
| chenlin | 陈琳 | 文档 | 归档记录、文档更新、Git 提交 |
### 协作流水线
```
1. 分析需求 → 读相关文档(MD/)
2. 制定计划 → update_plan
3. 后端开发 → Controller → AppService → Service → Mapper → Entity → Flyway
4. 后端测试 → mvn test → 接口测试通过
5. 前端开发 → API接口 → 页面组件 → 路由配置
6. 前端测试 → npm run build:dev → 功能验证
7. 提交代码 → git add → git commit(规范格式) → git push
刘备(协调) → 诸葛亮(分析) → {关羽|赵云}(修复) → 荀彧(DB审查) → 张飞(测试) → 华佗(验收) → 陈琳(归档)
```
### Bug 状态管理铁律
- 人类提的 Bug：只加备注，不改状态，不改分配
- 智能体提的 Bug：可以改分配和加备注
- 已关闭/已解决的 Bug 不再处理
### 修复流程铁律
- 一次只修一个 Bug，不扩大范围
- 修复前必须读 AGENTS.md
- 修复后必须验证编译
- 涉及 SQL 必须先查真实数据库
### 测试流程铁律
- Playwright 必须 `--workers=1` 单线程
- 超时 120 秒
- 最多重试 3 次
- 测试结果写入禅道备注
### 归档流程铁律
- 三重归档：Git + SQLite + Redis
- SQLite 必须使用完整字段
- 禅道备注格式：`[📝 陈琳归档] Bug #xxx`
---
## 九、开发流程
```
收到任务
├→ ① 分析需求 → 读相关文档(MD/)、读全链路6环
├→ ② 制定计划 → update_plan (3-6个阶段)
├→ ③ 后端开发 → Controller → AppService → Service → Mapper → Entity → Flyway
├→ ④ 后端测试 → mvn test → 接口测试(业务逻辑验证)
├→ ⑤ 前端开发 → API接口 → 页面组件 → 路由配置
├→ ⑥ 前端测试 → npm run build:dev → 功能验证
├→ ⑦ 质量门禁 → L1编译 → L2测试 → L3DB审查 → L4验收 → L5归档
└→ ⑧ 提交代码 → git commit(规范格式) → git push → 文档更新
```
### Git Commit 格式
@@ -181,7 +367,7 @@ scope: 模块名(如 registration, billing, pharmacy)
---
## 六、快速参考命令
## 十、快速参考命令
```bash
# === 后端 ===
@@ -206,7 +392,7 @@ git push origin develop # 推送
---
## 七、详细规范文档索引
## 十一、详细规范文档索引
| 文档 | 路径 | 用途 |
|------|------|------|
@@ -218,11 +404,27 @@ git push origin develop # 推送
| 前端清单 | `MD/specs/FRONTEND_CHECKLIST.md` | 发布前检查 |
| 三甲标准 | `MD/standards/GRADE3A_HIS_STANDARD.md` | 三甲医院达标标准 |
| Flyway指南 | `MD/guides/FLYWAY_USAGE_GUIDE.md` | 数据库迁移指南 |
| E2E测试 | `MD/specs/PLAYWRIGHT_TESTING_PLAN.md` | Playwright测试方案 |
---
> ⚠️ **警告**: 本文件是项目 AI 开发规范的唯一信源。各工具配置文件（AGENTS.md、.cursorrules 等）均引用本文件。修改规范请只修改本文件。
## 十二、过往教训（必须铭记）
| 教训 | 来源 | 教训内容 |
|------|------|---------|
| 状态链路断裂 | Bug #574 | `checkInTicket()` 设 BOOKED(1) 而非 CHECKED_IN(3)，前端映射缺失，池统计漏计 → 必须走完整状态链路验证 |
| 盲删源文件 | Bug #574 | AI 看到编译错误直接删文件，没检查是否在 baseline → 必须先确认文件来源再操作 |
| 修复方向偏差 | Bug #574 | 多次 fallback 改的是 OrderServiceImpl，完全没触及 TicketServiceImpl → 必须用 rg 搜索所有相关代码路径 |
| bug_reports 表缺少列 | 经验 | INSERT 会静默失败，必须检查表结构 |
| 禅道 comment API | 经验 | API 不存在，必须用 resolve+activate workaround |
| SQLite WAL 并发 | 经验 | 多进程并发写需要 checkpoint |
| UTF-8 切片 | 经验 | 多字节字符不能用 byte index 切片 |
| 禅道图片附件 | 经验 | 必须 OCR 读取，不能直接解析 |
---
> 📅 最后同步: 2026-06-06 09:46 | 源文件: RULES.md | 重新同步: `bash scripts/sync-ai-rules.sh`
> ⚠️ **警告**: 本文件是项目 AI 开发规范的唯一信源。各工具配置文件（AGENTS.md、.cursorrules 等）均通过 `bash scripts/sync-ai-rules.sh` 从本文件同步。修改规范请只修改本文件。
---
> 📅 最后同步: 2026-06-06 09:56 | 源文件: RULES.md | 重新同步: `bash scripts/sync-ai-rules.sh`

260
.windsurfrules
View File

@@ -7,6 +7,8 @@
# HealthLink-HIS — AI 开发规范（自动加载）
> 🤖 **本文件供所有 AI 编码工具自动读取**。无论使用 Claude Code、Cursor、Codex CLI、Copilot、Qwen、Cline 还是其他工具，进入本项目后必须遵守以下规范。
>
> **模型决定上限，Harness 决定底线。**
---
@@ -20,9 +22,12 @@
| 文档路径 | `MD/` |
| JDK | 25 (OpenJDK) |
| Spring Boot | 4.0.6 |
| MyBatis-Plus | 3.5.16 |
| Vue | 3.x + Vite + Element Plus |
| 数据库 | PostgreSQL 15+ |
| 包名 | `com.healthlink.his` |
| 后端端口 | 18082 |
| 前端端口 | 81 |
---
@@ -36,7 +41,7 @@
前端: npm run build:dev → npm run lint
```
- 白盒：编译通过，无 ERROR
- 黑盒：关键接口返回 `{code:200, data:...}`
- 黑盒：关键接口返回 `{code:200, data:...}`，验证业务逻辑
- 冒烟：应用正常启动，核心流程通畅
**铁律2: Flyway 数据库迁移**
@@ -54,28 +59,159 @@
- 前端 `request.js` 的 baseURL 必须与后端匹配
- 接口变更必须同步更新前后端代码
**铁律5: 状态值一致性（来自 Bug #574 教训）**
- 修改任何状态值前，必须先列出完整的状态流转链路
- 检查项：
1. 枚举定义的值是否正确
2. Service 层设置的状态值是否与枚举一致
3. 查询/列表接口的状态映射是否覆盖所有枚举值
4. 前端 `STATUS_CLASS_MAP` 是否包含新状态
5. 前端过滤条件（如 `v-if`）是否兼容新状态
6. 池/统计表的聚合 SQL 是否包含新状态值
- 禁止：只改一端不检查其他端
**铁律6: 禁止删除源文件（来自 Bug #574 教训）**
- 绝对禁止删除项目中已有的 Java/Vue/SQL 源文件
- 文件有编译错误 → 修复错误，不删除文件
- 文件是重复的 → 重构合并，不删除文件
- 文件是 AI 幻觉创建的 → 检查 git baseline 确认后再删除
- 唯一例外：明确由人类确认删除的文件
**铁律7: 禁止修改已有公开方法签名**
- 不能删除或重命名已有的 public 方法
- 不能修改已有方法的参数列表
- 需要新增功能时 → 添加新的重载方法
- 需要改行为时 → 修改方法内部实现，不改签名
### 🟡 P1 铁律 — 强烈建议
**铁律5: 先分解再行动**
**铁律8: 先分解再行动**
- 修改超过3个文件、涉及多模块、数据库变更，必须先制定计划
**铁律6: 验证后信**
**铁律9: 验证后信**
- 每次修改后必须验证编译通过，不信记忆
- 重新编译命令：`mvn clean compile -DskipTests`
**铁律7: 文档统一管理**
**铁律10: 文档统一管理**
- 所有文档存储在 `MD/` 目录
- 文件名：大写英文+下划线（如 `BACKEND_CHECKLIST.md`）
- 文档头部必须包含元数据块（文档类型、版本、日期）
**铁律8: 规范文档在 MD/specs/**
- 完整铁律：`MD/specs/IRON_RULES.md`
- 后端规范：`MD/specs/BACKEND_DEVELOPMENT_STANDARD.md`
- 前端规范：`MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md`
---
## 三、全链路 6 环分析
> ⚠️ **涉及数据库字段的 Bug / 需求，必须走完整链路，不得"就事论事"。**
```
前端/页面 → Controller → Service → Mapper → DB/SQL → 关联模块
①录入 ②验证 ③业务 ④持久化 ⑤存储 ⑥联动
```
### 每一环必须确认
| 环 | 检查内容 |
|----|---------|
| ① 录入 | 前端有无输入入口（弹窗、表格行编辑、表单） |
| ② 验证 | Controller 参数校验、@Valid、权限控制 |
| ③ 业务 | Service 业务逻辑、事务边界、多个 Service 实现类入口 |
| ④ 持久化 | Mapper XML、DTO 字段映射、类型转换 |
| ⑤ 存储 | 数据库表结构、索引、NOT NULL 约束 |
| ⑥ 联动 | 上游（医嘱→护士站）、下游（打印、计费、报表）是否同步 |
### 全链路验证顺序
修复涉及状态流转的问题后，必须按以下顺序验证：
1. **数据库**：确认状态值已正确写入
2. **后端接口**：确认返回的状态映射正确
3. **前端显示**：确认页面显示正确状态文本
4. **前端交互**：确认按钮/操作基于正确状态启用/禁用
5. **统计数据**：确认池/报表统计包含新状态
### 常见陷阱
- ❌ 只修了「主入口」的保存逻辑，忘了「批量保存」「签发保存」等其他入口
- ❌ 前端加了输入框，后端 Service 没传字段
- ❌ Mapper XML 是 UNION ALL 查询，只改了其中一个子查询
- ❌ DTO 层级继承关系没检查
- ❌ 只测了新增，没测编辑已有数据的回显和修改再保存
---
## 三、后端开发规范
## 四、Harness Engineering 方法论
> Harness = 约束 + 反馈 + 控制平面 + 持久执行
### 4.1 四层约束金字塔
| 层级 | 内容 | 落地方式 |
|------|------|---------|
| **L1 架构约束** | 接口合约、包结构、命名规范、禁止模式 | 本文件铁律、AGENTS.md |
| **L2 代码质量** | 圈复杂度、代码风格、类型提示 | 编译门禁 + ESLint |
| **L3 安全约束** | 敏感信息检测、权限检查、输入验证 | 配置不可硬编码 |
| **L4 业务规则** | 领域逻辑、数据一致性、事务边界 | 全链路 6 环验证 |
**约束优先级**：安全 > 架构 > 质量 > 业务
### 4.2 三层反馈系统
| 层级 | 速度 | 覆盖范围 | 失败处理 |
|------|------|---------|---------|
| **L1 编译检查** | <30 秒 | 语法、类型、签名 | 立即阻断，自行修复 |
| **L2 数据流验证** | <5 分钟 | 全链路字段、Mapper XML、DTO | 修复后上报 |
| **L3 人工审查** | 10-30 分钟 | 架构、设计、业务正确性 | 驳回 / 指导 / 批准 |
**反馈设计铁律**：
- 反馈必须可行动（指出：文件 + 行号 + 错误类型 + 修复方向）
- 反馈越及时越好（L1 即时 → L2 分钟 → L3 小时）
- 失败后先回滚到最近检查点，再重试
### 4.3 控制平面（Agent 协调）
```
┌─────────────────────────────────────────────┐
│ 战略层（人类主导） │
│ ├── 设定目标、审批关键决策 │
│ └── 异常升级处理 │
├─────────────────────────────────────────────┤
│ 战术层（Control Plane） │
│ ├── 任务分解 + update_plan │
│ ├── 依赖协调 + 资源分配 │
│ └── 检查点保存 + 恢复 │
├─────────────────────────────────────────────┤
│ 执行层（Agent 自主） │
│ ├── 代码生成、测试执行 │
│ └── 错误恢复 + 幂等重试 │
└─────────────────────────────────────────────┘
```
### 4.4 持久执行
- 每个关键步骤保存检查点（`update_plan` 进度）
- 失败后从最新检查点恢复，不从头开始
- 幂等设计：同一操作重复执行结果一致
---
## 五、质量门禁（5 级）
| 级别 | 门禁 | 通过标准 |
|------|------|---------|
| **L1** | 编译通过 | `mvn clean compile` + `npm run build:dev` 无 ERROR |
| **L2** | 测试通过 | 单元测试 + 接口测试全部通过 |
| **L3** | DB 审查 | Flyway 脚本规范、SQL 安全、索引合理 |
| **L4** | 验收通过 | 核心功能流程完整验证、全链路检查 |
| **L5** | 归档完成 | Git commit + 文档更新 + 代码推送 |
### 提交铁律
- L1-L2 必须通过才能 commit
- L3（如有DB变更）必须通过才能 push
- L4-L5 发布前必须完成
---
## 六、后端开发规范
### 分层架构
```
@@ -106,12 +242,9 @@ com.healthlink.his.common.enums
### 统一返回格式
```java
// 成功
AjaxResult.success(data)
// 失败
AjaxResult.error("错误信息")
// 列表
getDataTable(list)
AjaxResult.success(data) // 成功
AjaxResult.error("错误信息") // 失败
getDataTable(list) // 列表
```
### 关键约束
@@ -119,11 +252,13 @@ getDataTable(list)
- `@Transactional(rollbackFor = Exception.class)` 管理事务
- 所有接口标注 `@PreAuthorize` 权限控制
- 患者敏感信息（身份证、手机号）在日志中脱敏
- 扩展功能不要修改原有函数签名，新建 Service/AppService
- **扩展功能不修改原有函数签名**，新建 Service/AppService
- 涉及多表写操作的方法标注 `@Transactional`
- 事务方法未被同一类内方法直接调用（避免自调用失效）
---
## 四、前端开发规范
## 七、前端开发规范
### 技术栈
- Vue 3 + Vite + Element Plus + Pinia + Axios
@@ -159,16 +294,67 @@ export function listXxx(query) {
---
## 五、开发流程
## 八、Agent 体系（智能体协作）
### 角色定义
| 代号 | 名称 | 角色 | 职责 |
|------|------|------|------|
| liubei | 刘备 | 项目经理 | 总协调、任务分配、异常升级 |
| zhugeliang | 诸葛亮 | 架构师 | 需求分析、方案设计、技术决策 |
| guanyu | 关羽 | 后端开发 | Java 后端修复、API 开发 |
| zhaoyun | 赵云 | 前端开发 | Vue 前端修复、页面开发 |
| xunyu | 荀彧 | DBA | 数据库审查、SQL 优化、Flyway 脚本 |
| zhangfei | 张飞 | 测试 | Playwright 测试、接口测试、回归测试 |
| huatuo | 华佗 | 验收 | 功能验收、质量确认、发布检查 |
| chenlin | 陈琳 | 文档 | 归档记录、文档更新、Git 提交 |
### 协作流水线
```
1. 分析需求 → 读相关文档(MD/)
2. 制定计划 → update_plan
3. 后端开发 → Controller → AppService → Service → Mapper → Entity → Flyway
4. 后端测试 → mvn test → 接口测试通过
5. 前端开发 → API接口 → 页面组件 → 路由配置
6. 前端测试 → npm run build:dev → 功能验证
7. 提交代码 → git add → git commit(规范格式) → git push
刘备(协调) → 诸葛亮(分析) → {关羽|赵云}(修复) → 荀彧(DB审查) → 张飞(测试) → 华佗(验收) → 陈琳(归档)
```
### Bug 状态管理铁律
- 人类提的 Bug：只加备注，不改状态，不改分配
- 智能体提的 Bug：可以改分配和加备注
- 已关闭/已解决的 Bug 不再处理
### 修复流程铁律
- 一次只修一个 Bug，不扩大范围
- 修复前必须读 AGENTS.md
- 修复后必须验证编译
- 涉及 SQL 必须先查真实数据库
### 测试流程铁律
- Playwright 必须 `--workers=1` 单线程
- 超时 120 秒
- 最多重试 3 次
- 测试结果写入禅道备注
### 归档流程铁律
- 三重归档：Git + SQLite + Redis
- SQLite 必须使用完整字段
- 禅道备注格式：`[📝 陈琳归档] Bug #xxx`
---
## 九、开发流程
```
收到任务
├→ ① 分析需求 → 读相关文档(MD/)、读全链路6环
├→ ② 制定计划 → update_plan (3-6个阶段)
├→ ③ 后端开发 → Controller → AppService → Service → Mapper → Entity → Flyway
├→ ④ 后端测试 → mvn test → 接口测试(业务逻辑验证)
├→ ⑤ 前端开发 → API接口 → 页面组件 → 路由配置
├→ ⑥ 前端测试 → npm run build:dev → 功能验证
├→ ⑦ 质量门禁 → L1编译 → L2测试 → L3DB审查 → L4验收 → L5归档
└→ ⑧ 提交代码 → git commit(规范格式) → git push → 文档更新
```
### Git Commit 格式
@@ -181,7 +367,7 @@ scope: 模块名(如 registration, billing, pharmacy)
---
## 六、快速参考命令
## 十、快速参考命令
```bash
# === 后端 ===
@@ -206,7 +392,7 @@ git push origin develop # 推送
---
## 七、详细规范文档索引
## 十一、详细规范文档索引
| 文档 | 路径 | 用途 |
|------|------|------|
@@ -218,11 +404,27 @@ git push origin develop # 推送
| 前端清单 | `MD/specs/FRONTEND_CHECKLIST.md` | 发布前检查 |
| 三甲标准 | `MD/standards/GRADE3A_HIS_STANDARD.md` | 三甲医院达标标准 |
| Flyway指南 | `MD/guides/FLYWAY_USAGE_GUIDE.md` | 数据库迁移指南 |
| E2E测试 | `MD/specs/PLAYWRIGHT_TESTING_PLAN.md` | Playwright测试方案 |
---
> ⚠️ **警告**: 本文件是项目 AI 开发规范的唯一信源。各工具配置文件（AGENTS.md、.cursorrules 等）均引用本文件。修改规范请只修改本文件。
## 十二、过往教训（必须铭记）
| 教训 | 来源 | 教训内容 |
|------|------|---------|
| 状态链路断裂 | Bug #574 | `checkInTicket()` 设 BOOKED(1) 而非 CHECKED_IN(3)，前端映射缺失，池统计漏计 → 必须走完整状态链路验证 |
| 盲删源文件 | Bug #574 | AI 看到编译错误直接删文件，没检查是否在 baseline → 必须先确认文件来源再操作 |
| 修复方向偏差 | Bug #574 | 多次 fallback 改的是 OrderServiceImpl，完全没触及 TicketServiceImpl → 必须用 rg 搜索所有相关代码路径 |
| bug_reports 表缺少列 | 经验 | INSERT 会静默失败，必须检查表结构 |
| 禅道 comment API | 经验 | API 不存在，必须用 resolve+activate workaround |
| SQLite WAL 并发 | 经验 | 多进程并发写需要 checkpoint |
| UTF-8 切片 | 经验 | 多字节字符不能用 byte index 切片 |
| 禅道图片附件 | 经验 | 必须 OCR 读取，不能直接解析 |
---
> 📅 最后同步: 2026-06-06 09:46 | 源文件: RULES.md | 重新同步: `bash scripts/sync-ai-rules.sh`
> ⚠️ **警告**: 本文件是项目 AI 开发规范的唯一信源。各工具配置文件（AGENTS.md、.cursorrules 等）均通过 `bash scripts/sync-ai-rules.sh` 从本文件同步。修改规范请只修改本文件。
---
> 📅 最后同步: 2026-06-06 09:56 | 源文件: RULES.md | 重新同步: `bash scripts/sync-ai-rules.sh`

260
AGENTS.md
View File

@@ -8,6 +8,8 @@
# HealthLink-HIS — AI 开发规范（自动加载）
> 🤖 **本文件供所有 AI 编码工具自动读取**。无论使用 Claude Code、Cursor、Codex CLI、Copilot、Qwen、Cline 还是其他工具，进入本项目后必须遵守以下规范。
>
> **模型决定上限，Harness 决定底线。**
---
@@ -21,9 +23,12 @@
| 文档路径 | `MD/` |
| JDK | 25 (OpenJDK) |
| Spring Boot | 4.0.6 |
| MyBatis-Plus | 3.5.16 |
| Vue | 3.x + Vite + Element Plus |
| 数据库 | PostgreSQL 15+ |
| 包名 | `com.healthlink.his` |
| 后端端口 | 18082 |
| 前端端口 | 81 |
---
@@ -37,7 +42,7 @@
前端: npm run build:dev → npm run lint
```
- 白盒：编译通过，无 ERROR
- 黑盒：关键接口返回 `{code:200, data:...}`
- 黑盒：关键接口返回 `{code:200, data:...}`，验证业务逻辑
- 冒烟：应用正常启动，核心流程通畅
**铁律2: Flyway 数据库迁移**
@@ -55,28 +60,159 @@
- 前端 `request.js` 的 baseURL 必须与后端匹配
- 接口变更必须同步更新前后端代码
**铁律5: 状态值一致性（来自 Bug #574 教训）**
- 修改任何状态值前，必须先列出完整的状态流转链路
- 检查项：
1. 枚举定义的值是否正确
2. Service 层设置的状态值是否与枚举一致
3. 查询/列表接口的状态映射是否覆盖所有枚举值
4. 前端 `STATUS_CLASS_MAP` 是否包含新状态
5. 前端过滤条件（如 `v-if`）是否兼容新状态
6. 池/统计表的聚合 SQL 是否包含新状态值
- 禁止：只改一端不检查其他端
**铁律6: 禁止删除源文件（来自 Bug #574 教训）**
- 绝对禁止删除项目中已有的 Java/Vue/SQL 源文件
- 文件有编译错误 → 修复错误，不删除文件
- 文件是重复的 → 重构合并，不删除文件
- 文件是 AI 幻觉创建的 → 检查 git baseline 确认后再删除
- 唯一例外：明确由人类确认删除的文件
**铁律7: 禁止修改已有公开方法签名**
- 不能删除或重命名已有的 public 方法
- 不能修改已有方法的参数列表
- 需要新增功能时 → 添加新的重载方法
- 需要改行为时 → 修改方法内部实现，不改签名
### 🟡 P1 铁律 — 强烈建议
**铁律5: 先分解再行动**
**铁律8: 先分解再行动**
- 修改超过3个文件、涉及多模块、数据库变更，必须先制定计划
**铁律6: 验证后信**
**铁律9: 验证后信**
- 每次修改后必须验证编译通过，不信记忆
- 重新编译命令：`mvn clean compile -DskipTests`
**铁律7: 文档统一管理**
**铁律10: 文档统一管理**
- 所有文档存储在 `MD/` 目录
- 文件名：大写英文+下划线（如 `BACKEND_CHECKLIST.md`）
- 文档头部必须包含元数据块（文档类型、版本、日期）
**铁律8: 规范文档在 MD/specs/**
- 完整铁律：`MD/specs/IRON_RULES.md`
- 后端规范：`MD/specs/BACKEND_DEVELOPMENT_STANDARD.md`
- 前端规范：`MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md`
---
## 三、全链路 6 环分析
> ⚠️ **涉及数据库字段的 Bug / 需求，必须走完整链路，不得"就事论事"。**
```
前端/页面 → Controller → Service → Mapper → DB/SQL → 关联模块
①录入 ②验证 ③业务 ④持久化 ⑤存储 ⑥联动
```
### 每一环必须确认
| 环 | 检查内容 |
|----|---------|
| ① 录入 | 前端有无输入入口（弹窗、表格行编辑、表单） |
| ② 验证 | Controller 参数校验、@Valid、权限控制 |
| ③ 业务 | Service 业务逻辑、事务边界、多个 Service 实现类入口 |
| ④ 持久化 | Mapper XML、DTO 字段映射、类型转换 |
| ⑤ 存储 | 数据库表结构、索引、NOT NULL 约束 |
| ⑥ 联动 | 上游（医嘱→护士站）、下游（打印、计费、报表）是否同步 |
### 全链路验证顺序
修复涉及状态流转的问题后，必须按以下顺序验证：
1. **数据库**：确认状态值已正确写入
2. **后端接口**：确认返回的状态映射正确
3. **前端显示**：确认页面显示正确状态文本
4. **前端交互**：确认按钮/操作基于正确状态启用/禁用
5. **统计数据**：确认池/报表统计包含新状态
### 常见陷阱
- ❌ 只修了「主入口」的保存逻辑，忘了「批量保存」「签发保存」等其他入口
- ❌ 前端加了输入框，后端 Service 没传字段
- ❌ Mapper XML 是 UNION ALL 查询，只改了其中一个子查询
- ❌ DTO 层级继承关系没检查
- ❌ 只测了新增，没测编辑已有数据的回显和修改再保存
---
## 三、后端开发规范
## 四、Harness Engineering 方法论
> Harness = 约束 + 反馈 + 控制平面 + 持久执行
### 4.1 四层约束金字塔
| 层级 | 内容 | 落地方式 |
|------|------|---------|
| **L1 架构约束** | 接口合约、包结构、命名规范、禁止模式 | 本文件铁律、AGENTS.md |
| **L2 代码质量** | 圈复杂度、代码风格、类型提示 | 编译门禁 + ESLint |
| **L3 安全约束** | 敏感信息检测、权限检查、输入验证 | 配置不可硬编码 |
| **L4 业务规则** | 领域逻辑、数据一致性、事务边界 | 全链路 6 环验证 |
**约束优先级**：安全 > 架构 > 质量 > 业务
### 4.2 三层反馈系统
| 层级 | 速度 | 覆盖范围 | 失败处理 |
|------|------|---------|---------|
| **L1 编译检查** | <30 秒 | 语法、类型、签名 | 立即阻断，自行修复 |
| **L2 数据流验证** | <5 分钟 | 全链路字段、Mapper XML、DTO | 修复后上报 |
| **L3 人工审查** | 10-30 分钟 | 架构、设计、业务正确性 | 驳回 / 指导 / 批准 |
**反馈设计铁律**：
- 反馈必须可行动（指出：文件 + 行号 + 错误类型 + 修复方向）
- 反馈越及时越好（L1 即时 → L2 分钟 → L3 小时）
- 失败后先回滚到最近检查点，再重试
### 4.3 控制平面（Agent 协调）
```
┌─────────────────────────────────────────────┐
│ 战略层（人类主导） │
│ ├── 设定目标、审批关键决策 │
│ └── 异常升级处理 │
├─────────────────────────────────────────────┤
│ 战术层（Control Plane） │
│ ├── 任务分解 + update_plan │
│ ├── 依赖协调 + 资源分配 │
│ └── 检查点保存 + 恢复 │
├─────────────────────────────────────────────┤
│ 执行层（Agent 自主） │
│ ├── 代码生成、测试执行 │
│ └── 错误恢复 + 幂等重试 │
└─────────────────────────────────────────────┘
```
### 4.4 持久执行
- 每个关键步骤保存检查点（`update_plan` 进度）
- 失败后从最新检查点恢复，不从头开始
- 幂等设计：同一操作重复执行结果一致
---
## 五、质量门禁（5 级）
| 级别 | 门禁 | 通过标准 |
|------|------|---------|
| **L1** | 编译通过 | `mvn clean compile` + `npm run build:dev` 无 ERROR |
| **L2** | 测试通过 | 单元测试 + 接口测试全部通过 |
| **L3** | DB 审查 | Flyway 脚本规范、SQL 安全、索引合理 |
| **L4** | 验收通过 | 核心功能流程完整验证、全链路检查 |
| **L5** | 归档完成 | Git commit + 文档更新 + 代码推送 |
### 提交铁律
- L1-L2 必须通过才能 commit
- L3（如有DB变更）必须通过才能 push
- L4-L5 发布前必须完成
---
## 六、后端开发规范
### 分层架构
```
@@ -107,12 +243,9 @@ com.healthlink.his.common.enums
### 统一返回格式
```java
// 成功
AjaxResult.success(data)
// 失败
AjaxResult.error("错误信息")
// 列表
getDataTable(list)
AjaxResult.success(data) // 成功
AjaxResult.error("错误信息") // 失败
getDataTable(list) // 列表
```
### 关键约束
@@ -120,11 +253,13 @@ getDataTable(list)
- `@Transactional(rollbackFor = Exception.class)` 管理事务
- 所有接口标注 `@PreAuthorize` 权限控制
- 患者敏感信息（身份证、手机号）在日志中脱敏
- 扩展功能不要修改原有函数签名，新建 Service/AppService
- **扩展功能不修改原有函数签名**，新建 Service/AppService
- 涉及多表写操作的方法标注 `@Transactional`
- 事务方法未被同一类内方法直接调用（避免自调用失效）
---
## 四、前端开发规范
## 七、前端开发规范
### 技术栈
- Vue 3 + Vite + Element Plus + Pinia + Axios
@@ -160,16 +295,67 @@ export function listXxx(query) {
---
## 五、开发流程
## 八、Agent 体系（智能体协作）
### 角色定义
| 代号 | 名称 | 角色 | 职责 |
|------|------|------|------|
| liubei | 刘备 | 项目经理 | 总协调、任务分配、异常升级 |
| zhugeliang | 诸葛亮 | 架构师 | 需求分析、方案设计、技术决策 |
| guanyu | 关羽 | 后端开发 | Java 后端修复、API 开发 |
| zhaoyun | 赵云 | 前端开发 | Vue 前端修复、页面开发 |
| xunyu | 荀彧 | DBA | 数据库审查、SQL 优化、Flyway 脚本 |
| zhangfei | 张飞 | 测试 | Playwright 测试、接口测试、回归测试 |
| huatuo | 华佗 | 验收 | 功能验收、质量确认、发布检查 |
| chenlin | 陈琳 | 文档 | 归档记录、文档更新、Git 提交 |
### 协作流水线
```
1. 分析需求 → 读相关文档(MD/)
2. 制定计划 → update_plan
3. 后端开发 → Controller → AppService → Service → Mapper → Entity → Flyway
4. 后端测试 → mvn test → 接口测试通过
5. 前端开发 → API接口 → 页面组件 → 路由配置
6. 前端测试 → npm run build:dev → 功能验证
7. 提交代码 → git add → git commit(规范格式) → git push
刘备(协调) → 诸葛亮(分析) → {关羽|赵云}(修复) → 荀彧(DB审查) → 张飞(测试) → 华佗(验收) → 陈琳(归档)
```
### Bug 状态管理铁律
- 人类提的 Bug：只加备注，不改状态，不改分配
- 智能体提的 Bug：可以改分配和加备注
- 已关闭/已解决的 Bug 不再处理
### 修复流程铁律
- 一次只修一个 Bug，不扩大范围
- 修复前必须读 AGENTS.md
- 修复后必须验证编译
- 涉及 SQL 必须先查真实数据库
### 测试流程铁律
- Playwright 必须 `--workers=1` 单线程
- 超时 120 秒
- 最多重试 3 次
- 测试结果写入禅道备注
### 归档流程铁律
- 三重归档：Git + SQLite + Redis
- SQLite 必须使用完整字段
- 禅道备注格式：`[📝 陈琳归档] Bug #xxx`
---
## 九、开发流程
```
收到任务
├→ ① 分析需求 → 读相关文档(MD/)、读全链路6环
├→ ② 制定计划 → update_plan (3-6个阶段)
├→ ③ 后端开发 → Controller → AppService → Service → Mapper → Entity → Flyway
├→ ④ 后端测试 → mvn test → 接口测试(业务逻辑验证)
├→ ⑤ 前端开发 → API接口 → 页面组件 → 路由配置
├→ ⑥ 前端测试 → npm run build:dev → 功能验证
├→ ⑦ 质量门禁 → L1编译 → L2测试 → L3DB审查 → L4验收 → L5归档
└→ ⑧ 提交代码 → git commit(规范格式) → git push → 文档更新
```
### Git Commit 格式
@@ -182,7 +368,7 @@ scope: 模块名(如 registration, billing, pharmacy)
---
## 六、快速参考命令
## 十、快速参考命令
```bash
# === 后端 ===
@@ -207,7 +393,7 @@ git push origin develop # 推送
---
## 七、详细规范文档索引
## 十一、详细规范文档索引
| 文档 | 路径 | 用途 |
|------|------|------|
@@ -219,11 +405,27 @@ git push origin develop # 推送
| 前端清单 | `MD/specs/FRONTEND_CHECKLIST.md` | 发布前检查 |
| 三甲标准 | `MD/standards/GRADE3A_HIS_STANDARD.md` | 三甲医院达标标准 |
| Flyway指南 | `MD/guides/FLYWAY_USAGE_GUIDE.md` | 数据库迁移指南 |
| E2E测试 | `MD/specs/PLAYWRIGHT_TESTING_PLAN.md` | Playwright测试方案 |
---
> ⚠️ **警告**: 本文件是项目 AI 开发规范的唯一信源。各工具配置文件（AGENTS.md、.cursorrules 等）均引用本文件。修改规范请只修改本文件。
## 十二、过往教训（必须铭记）
| 教训 | 来源 | 教训内容 |
|------|------|---------|
| 状态链路断裂 | Bug #574 | `checkInTicket()` 设 BOOKED(1) 而非 CHECKED_IN(3)，前端映射缺失，池统计漏计 → 必须走完整状态链路验证 |
| 盲删源文件 | Bug #574 | AI 看到编译错误直接删文件，没检查是否在 baseline → 必须先确认文件来源再操作 |
| 修复方向偏差 | Bug #574 | 多次 fallback 改的是 OrderServiceImpl，完全没触及 TicketServiceImpl → 必须用 rg 搜索所有相关代码路径 |
| bug_reports 表缺少列 | 经验 | INSERT 会静默失败，必须检查表结构 |
| 禅道 comment API | 经验 | API 不存在，必须用 resolve+activate workaround |
| SQLite WAL 并发 | 经验 | 多进程并发写需要 checkpoint |
| UTF-8 切片 | 经验 | 多字节字符不能用 byte index 切片 |
| 禅道图片附件 | 经验 | 必须 OCR 读取，不能直接解析 |
---
> 📅 最后同步: 2026-06-06 09:46 | 源文件: RULES.md | 重新同步: `bash scripts/sync-ai-rules.sh`
> ⚠️ **警告**: 本文件是项目 AI 开发规范的唯一信源。各工具配置文件（AGENTS.md、.cursorrules 等）均通过 `bash scripts/sync-ai-rules.sh` 从本文件同步。修改规范请只修改本文件。
---
> 📅 最后同步: 2026-06-06 09:56 | 源文件: RULES.md | 重新同步: `bash scripts/sync-ai-rules.sh`

258
RULES.md
View File

@@ -1,6 +1,8 @@
# HealthLink-HIS — AI 开发规范（自动加载）
> 🤖 **本文件供所有 AI 编码工具自动读取**。无论使用 Claude Code、Cursor、Codex CLI、Copilot、Qwen、Cline 还是其他工具，进入本项目后必须遵守以下规范。
>
> **模型决定上限，Harness 决定底线。**
---
@@ -14,9 +16,12 @@
| 文档路径 | `MD/` |
| JDK | 25 (OpenJDK) |
| Spring Boot | 4.0.6 |
| MyBatis-Plus | 3.5.16 |
| Vue | 3.x + Vite + Element Plus |
| 数据库 | PostgreSQL 15+ |
| 包名 | `com.healthlink.his` |
| 后端端口 | 18082 |
| 前端端口 | 81 |
---
@@ -30,7 +35,7 @@
前端: npm run build:dev → npm run lint
```
- 白盒：编译通过，无 ERROR
- 黑盒：关键接口返回 `{code:200, data:...}`
- 黑盒：关键接口返回 `{code:200, data:...}`，验证业务逻辑
- 冒烟：应用正常启动，核心流程通畅
**铁律2: Flyway 数据库迁移**
@@ -48,28 +53,159 @@
- 前端 `request.js` 的 baseURL 必须与后端匹配
- 接口变更必须同步更新前后端代码
**铁律5: 状态值一致性（来自 Bug #574 教训）**
- 修改任何状态值前，必须先列出完整的状态流转链路
- 检查项：
1. 枚举定义的值是否正确
2. Service 层设置的状态值是否与枚举一致
3. 查询/列表接口的状态映射是否覆盖所有枚举值
4. 前端 `STATUS_CLASS_MAP` 是否包含新状态
5. 前端过滤条件（如 `v-if`）是否兼容新状态
6. 池/统计表的聚合 SQL 是否包含新状态值
- 禁止：只改一端不检查其他端
**铁律6: 禁止删除源文件（来自 Bug #574 教训）**
- 绝对禁止删除项目中已有的 Java/Vue/SQL 源文件
- 文件有编译错误 → 修复错误，不删除文件
- 文件是重复的 → 重构合并，不删除文件
- 文件是 AI 幻觉创建的 → 检查 git baseline 确认后再删除
- 唯一例外：明确由人类确认删除的文件
**铁律7: 禁止修改已有公开方法签名**
- 不能删除或重命名已有的 public 方法
- 不能修改已有方法的参数列表
- 需要新增功能时 → 添加新的重载方法
- 需要改行为时 → 修改方法内部实现，不改签名
### 🟡 P1 铁律 — 强烈建议
**铁律5: 先分解再行动**
**铁律8: 先分解再行动**
- 修改超过3个文件、涉及多模块、数据库变更，必须先制定计划
**铁律6: 验证后信**
**铁律9: 验证后信**
- 每次修改后必须验证编译通过，不信记忆
- 重新编译命令：`mvn clean compile -DskipTests`
**铁律7: 文档统一管理**
**铁律10: 文档统一管理**
- 所有文档存储在 `MD/` 目录
- 文件名：大写英文+下划线（如 `BACKEND_CHECKLIST.md`）
- 文档头部必须包含元数据块（文档类型、版本、日期）
**铁律8: 规范文档在 MD/specs/**
- 完整铁律：`MD/specs/IRON_RULES.md`
- 后端规范：`MD/specs/BACKEND_DEVELOPMENT_STANDARD.md`
- 前端规范：`MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md`
---
## 三、全链路 6 环分析
> ⚠️ **涉及数据库字段的 Bug / 需求，必须走完整链路，不得"就事论事"。**
```
前端/页面 → Controller → Service → Mapper → DB/SQL → 关联模块
①录入 ②验证 ③业务 ④持久化 ⑤存储 ⑥联动
```
### 每一环必须确认
| 环 | 检查内容 |
|----|---------|
| ① 录入 | 前端有无输入入口（弹窗、表格行编辑、表单） |
| ② 验证 | Controller 参数校验、@Valid、权限控制 |
| ③ 业务 | Service 业务逻辑、事务边界、多个 Service 实现类入口 |
| ④ 持久化 | Mapper XML、DTO 字段映射、类型转换 |
| ⑤ 存储 | 数据库表结构、索引、NOT NULL 约束 |
| ⑥ 联动 | 上游（医嘱→护士站）、下游（打印、计费、报表）是否同步 |
### 全链路验证顺序
修复涉及状态流转的问题后，必须按以下顺序验证：
1. **数据库**：确认状态值已正确写入
2. **后端接口**：确认返回的状态映射正确
3. **前端显示**：确认页面显示正确状态文本
4. **前端交互**：确认按钮/操作基于正确状态启用/禁用
5. **统计数据**：确认池/报表统计包含新状态
### 常见陷阱
- ❌ 只修了「主入口」的保存逻辑，忘了「批量保存」「签发保存」等其他入口
- ❌ 前端加了输入框，后端 Service 没传字段
- ❌ Mapper XML 是 UNION ALL 查询，只改了其中一个子查询
- ❌ DTO 层级继承关系没检查
- ❌ 只测了新增，没测编辑已有数据的回显和修改再保存
---
## 三、后端开发规范
## 四、Harness Engineering 方法论
> Harness = 约束 + 反馈 + 控制平面 + 持久执行
### 4.1 四层约束金字塔
| 层级 | 内容 | 落地方式 |
|------|------|---------|
| **L1 架构约束** | 接口合约、包结构、命名规范、禁止模式 | 本文件铁律、AGENTS.md |
| **L2 代码质量** | 圈复杂度、代码风格、类型提示 | 编译门禁 + ESLint |
| **L3 安全约束** | 敏感信息检测、权限检查、输入验证 | 配置不可硬编码 |
| **L4 业务规则** | 领域逻辑、数据一致性、事务边界 | 全链路 6 环验证 |
**约束优先级**：安全 > 架构 > 质量 > 业务
### 4.2 三层反馈系统
| 层级 | 速度 | 覆盖范围 | 失败处理 |
|------|------|---------|---------|
| **L1 编译检查** | <30 秒 | 语法、类型、签名 | 立即阻断，自行修复 |
| **L2 数据流验证** | <5 分钟 | 全链路字段、Mapper XML、DTO | 修复后上报 |
| **L3 人工审查** | 10-30 分钟 | 架构、设计、业务正确性 | 驳回 / 指导 / 批准 |
**反馈设计铁律**：
- 反馈必须可行动（指出：文件 + 行号 + 错误类型 + 修复方向）
- 反馈越及时越好（L1 即时 → L2 分钟 → L3 小时）
- 失败后先回滚到最近检查点，再重试
### 4.3 控制平面（Agent 协调）
```
┌─────────────────────────────────────────────┐
│ 战略层（人类主导） │
│ ├── 设定目标、审批关键决策 │
│ └── 异常升级处理 │
├─────────────────────────────────────────────┤
│ 战术层（Control Plane） │
│ ├── 任务分解 + update_plan │
│ ├── 依赖协调 + 资源分配 │
│ └── 检查点保存 + 恢复 │
├─────────────────────────────────────────────┤
│ 执行层（Agent 自主） │
│ ├── 代码生成、测试执行 │
│ └── 错误恢复 + 幂等重试 │
└─────────────────────────────────────────────┘
```
### 4.4 持久执行
- 每个关键步骤保存检查点（`update_plan` 进度）
- 失败后从最新检查点恢复，不从头开始
- 幂等设计：同一操作重复执行结果一致
---
## 五、质量门禁（5 级）
| 级别 | 门禁 | 通过标准 |
|------|------|---------|
| **L1** | 编译通过 | `mvn clean compile` + `npm run build:dev` 无 ERROR |
| **L2** | 测试通过 | 单元测试 + 接口测试全部通过 |
| **L3** | DB 审查 | Flyway 脚本规范、SQL 安全、索引合理 |
| **L4** | 验收通过 | 核心功能流程完整验证、全链路检查 |
| **L5** | 归档完成 | Git commit + 文档更新 + 代码推送 |
### 提交铁律
- L1-L2 必须通过才能 commit
- L3（如有DB变更）必须通过才能 push
- L4-L5 发布前必须完成
---
## 六、后端开发规范
### 分层架构
```
@@ -100,12 +236,9 @@ com.healthlink.his.common.enums
### 统一返回格式
```java
// 成功
AjaxResult.success(data)
// 失败
AjaxResult.error("错误信息")
// 列表
getDataTable(list)
AjaxResult.success(data) // 成功
AjaxResult.error("错误信息") // 失败
getDataTable(list) // 列表
```
### 关键约束
@@ -113,11 +246,13 @@ getDataTable(list)
- `@Transactional(rollbackFor = Exception.class)` 管理事务
- 所有接口标注 `@PreAuthorize` 权限控制
- 患者敏感信息（身份证、手机号）在日志中脱敏
- 扩展功能不要修改原有函数签名，新建 Service/AppService
- **扩展功能不修改原有函数签名**，新建 Service/AppService
- 涉及多表写操作的方法标注 `@Transactional`
- 事务方法未被同一类内方法直接调用（避免自调用失效）
---
## 四、前端开发规范
## 七、前端开发规范
### 技术栈
- Vue 3 + Vite + Element Plus + Pinia + Axios
@@ -153,16 +288,67 @@ export function listXxx(query) {
---
## 五、开发流程
## 八、Agent 体系（智能体协作）
### 角色定义
| 代号 | 名称 | 角色 | 职责 |
|------|------|------|------|
| liubei | 刘备 | 项目经理 | 总协调、任务分配、异常升级 |
| zhugeliang | 诸葛亮 | 架构师 | 需求分析、方案设计、技术决策 |
| guanyu | 关羽 | 后端开发 | Java 后端修复、API 开发 |
| zhaoyun | 赵云 | 前端开发 | Vue 前端修复、页面开发 |
| xunyu | 荀彧 | DBA | 数据库审查、SQL 优化、Flyway 脚本 |
| zhangfei | 张飞 | 测试 | Playwright 测试、接口测试、回归测试 |
| huatuo | 华佗 | 验收 | 功能验收、质量确认、发布检查 |
| chenlin | 陈琳 | 文档 | 归档记录、文档更新、Git 提交 |
### 协作流水线
```
1. 分析需求 → 读相关文档(MD/)
2. 制定计划 → update_plan
3. 后端开发 → Controller → AppService → Service → Mapper → Entity → Flyway
4. 后端测试 → mvn test → 接口测试通过
5. 前端开发 → API接口 → 页面组件 → 路由配置
6. 前端测试 → npm run build:dev → 功能验证
7. 提交代码 → git add → git commit(规范格式) → git push
刘备(协调) → 诸葛亮(分析) → {关羽|赵云}(修复) → 荀彧(DB审查) → 张飞(测试) → 华佗(验收) → 陈琳(归档)
```
### Bug 状态管理铁律
- 人类提的 Bug：只加备注，不改状态，不改分配
- 智能体提的 Bug：可以改分配和加备注
- 已关闭/已解决的 Bug 不再处理
### 修复流程铁律
- 一次只修一个 Bug，不扩大范围
- 修复前必须读 AGENTS.md
- 修复后必须验证编译
- 涉及 SQL 必须先查真实数据库
### 测试流程铁律
- Playwright 必须 `--workers=1` 单线程
- 超时 120 秒
- 最多重试 3 次
- 测试结果写入禅道备注
### 归档流程铁律
- 三重归档：Git + SQLite + Redis
- SQLite 必须使用完整字段
- 禅道备注格式：`[📝 陈琳归档] Bug #xxx`
---
## 九、开发流程
```
收到任务
├→ ① 分析需求 → 读相关文档(MD/)、读全链路6环
├→ ② 制定计划 → update_plan (3-6个阶段)
├→ ③ 后端开发 → Controller → AppService → Service → Mapper → Entity → Flyway
├→ ④ 后端测试 → mvn test → 接口测试(业务逻辑验证)
├→ ⑤ 前端开发 → API接口 → 页面组件 → 路由配置
├→ ⑥ 前端测试 → npm run build:dev → 功能验证
├→ ⑦ 质量门禁 → L1编译 → L2测试 → L3DB审查 → L4验收 → L5归档
└→ ⑧ 提交代码 → git commit(规范格式) → git push → 文档更新
```
### Git Commit 格式
@@ -175,7 +361,7 @@ scope: 模块名(如 registration, billing, pharmacy)
---
## 六、快速参考命令
## 十、快速参考命令
```bash
# === 后端 ===
@@ -200,7 +386,7 @@ git push origin develop # 推送
---
## 七、详细规范文档索引
## 十一、详细规范文档索引
| 文档 | 路径 | 用途 |
|------|------|------|
@@ -212,7 +398,23 @@ git push origin develop # 推送
| 前端清单 | `MD/specs/FRONTEND_CHECKLIST.md` | 发布前检查 |
| 三甲标准 | `MD/standards/GRADE3A_HIS_STANDARD.md` | 三甲医院达标标准 |
| Flyway指南 | `MD/guides/FLYWAY_USAGE_GUIDE.md` | 数据库迁移指南 |
| E2E测试 | `MD/specs/PLAYWRIGHT_TESTING_PLAN.md` | Playwright测试方案 |
---
> ⚠️ **警告**: 本文件是项目 AI 开发规范的唯一信源。各工具配置文件（AGENTS.md、.cursorrules 等）均引用本文件。修改规范请只修改本文件。
## 十二、过往教训（必须铭记）
| 教训 | 来源 | 教训内容 |
|------|------|---------|
| 状态链路断裂 | Bug #574 | `checkInTicket()` 设 BOOKED(1) 而非 CHECKED_IN(3)，前端映射缺失，池统计漏计 → 必须走完整状态链路验证 |
| 盲删源文件 | Bug #574 | AI 看到编译错误直接删文件，没检查是否在 baseline → 必须先确认文件来源再操作 |
| 修复方向偏差 | Bug #574 | 多次 fallback 改的是 OrderServiceImpl，完全没触及 TicketServiceImpl → 必须用 rg 搜索所有相关代码路径 |
| bug_reports 表缺少列 | 经验 | INSERT 会静默失败，必须检查表结构 |
| 禅道 comment API | 经验 | API 不存在，必须用 resolve+activate workaround |
| SQLite WAL 并发 | 经验 | 多进程并发写需要 checkpoint |
| UTF-8 切片 | 经验 | 多字节字符不能用 byte index 切片 |
| 禅道图片附件 | 经验 | 必须 OCR 读取，不能直接解析 |
---
> ⚠️ **警告**: 本文件是项目 AI 开发规范的唯一信源。各工具配置文件（AGENTS.md、.cursorrules 等）均通过 `bash scripts/sync-ai-rules.sh` 从本文件同步。修改规范请只修改本文件。