his/MD/specs/IRON_RULES.md

# HealthLink-HIS 执行铁律

> **文档类型**: 技术规范
> **适用范围**: 全项目开发流程
> **版本**: v2.0
> **编制日期**: 2026-06-06
> **最后更新**: 2026-06-06

---

## 一、铁律总览

| 编号 | 铁律名称 | 优先级 | 适用范围 |
|------|---------|--------|---------|
| #1 | 修改完必须测试 | P0 | 全量代码 |
| #2 | Flyway 数据库迁移 | P0 | 数据库变更 |
| #3 | 先分解再行动 | P1 | 非平凡任务 |
| #4 | 验证后信 | P1 | 编译/构建 |
| #5 | 文档统一管理 | P1 | 文档产出 |
| #6 | 测试通过后才提交 | P0 | 代码提交 |
| #7 | 前后端API路径对齐 | P0 | 接口开发 |
| #8 | 铁律和规范文档放MD目录 | P1 | 规范文档 |
| #9 | 开发前必须审核原有代码 | P0 | 全量开发 |
| #10 | 设计文档必须包含UI设计和调用流程 | P0 | 设计文档/前端开发 |
| #11 | 模块设计必须分析业务逻辑，不能只做CRUD | P0 | 全量模块设计 |
| #12 | 模块优化必须分析现有业务流并说明促进作用 | P0 | 全量模块优化 |

---

## 二、铁律详细说明

### 铁律 #1: 修改完必须测试

**任何代码修改后，必须完成以下测试才能提交：**

#### 白盒测试
- `mvn clean compile` 编译通过，无ERROR
- 单元测试全部通过（如有）
- 代码无新增编译警告（或有书面说明可忽略）

#### 黑盒测试
- 启动应用，验证无启动报错
- 测试关键接口（登录、核心业务接口）
- 验证请求响应结构正确（`{code, msg, data}`）
- 验证业务逻辑正确性（非仅HTTP状态码）

#### 冒烟测试
- 应用正常启动（端口监听）
- 健康检查接口返回正常
- 基础 CRUD 操作正常
- 登录→获取菜单→核心业务流程通畅

#### 前端测试
- `npm run build:dev` 构建成功
- ESLint 无错误
- 页面无控制台报错
- 核心业务页面功能正常

---

### 铁律 #2: Flyway 数据库迁移

**但凡遇到有新建表和字段的，必须通过 Flyway 框架去实现。**

#### 操作规范
1. 在 `healthlink-his-domain/src/main/resources/db/migration/` 下创建迁移脚本
2. 命名格式：`V{版本号}__{描述}.sql`（双下划线分隔）
3. 示例：`V2.0.1__add_patient_allergy_table.sql`
4. 迁移脚本必须包含完整的 DDL（CREATE TABLE / ALTER TABLE）
5. 必须提供回滚方案（文档记录，非自动回滚）

#### 禁止事项
- ❌ 直接在数据库执行 SQL 不走 Flyway
- ❌ 修改已执行的迁移脚本
- ❌ 迁移脚本中使用 `DROP TABLE`（除非明确需要）
- ❌ 跳过版本号

---

### 铁律 #3: 先分解再行动

**任何非平凡任务先出 plan 再执行。**

#### 触发条件
- 修改超过 3 个文件的任务
- 涉及多个模块的变更
- 数据库结构变更
- 新功能开发

#### 执行步骤
1. 分析现有代码和架构
2. 制定分步计划（使用 `update_plan`）
3. 确认测试方案
4. 逐步执行并验证

---

### 铁律 #4: 验证后信

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

#### 验证命令
```bash
# 后端编译
export JAVA_HOME=/opt/jdk-25
mvn clean compile -DskipTests

# 完整构建
mvn install -DskipTests

# 前端构建
cd healthlink-his-ui && npm run build:dev
```

---

### 铁律 #5: 文档统一管理

**所有文档必须存储在 `MD/` 目录中，遵循文档规范。**

#### 目录结构
```
MD/
├── DOCUMENTATION_STANDARD.md    # 文档管理规范
├── architecture/                # 架构设计
├── development/                 # 开发计划与记录
├── standards/                   # 国家/行业标准
├── specs/                       # 技术规范与流程
├── bugs/                        # Bug分析与修复记录
├── guides/                      # 使用指南
└── upgrade/                     # 升级记录
```

#### 命名规范
- 文件名使用 **大写英文+下划线**（如 `GRADE3A_DETAILED_DESIGN.md`）
- 不使用中文作文件名
- 不使用空格分隔单词
- 版本号标注在文件名末尾（如 `_V2`）

#### 格式要求
- 文档头部必须包含元数据块（文档类型、版本、日期）
- 代码块必须标注语言类型
- 表格使用标准Markdown格式

#### 详细规范
参见 `MD/DOCUMENTATION_STANDARD.md`

---

### 铁律 #6: 测试通过后才提交

**代码修改必须通过完整测试后才能提交到远程仓库。**

#### 提交前检查
1. `mvn clean compile` 编译通过
2. 接口测试全部通过（88/88）
3. 前端构建成功
4. 无新增编译警告
5. 代码变更范围已确认（`git status`）

#### 提交规范
- 使用标准 Commit Message 格式
- 参见 `MD/specs/COMMIT_TEMPLATE.md`
- 不提交未完成的功能
- 不提交调试代码和临时文件

---

### 铁律 #7: 前后端API路径对齐

**前后端API路径必须保持一致。**

#### 规范要求
1. 后端接口路径统一前缀：`/healthlink-his/`
2. 前端 `request.js` 中配置的 `baseURL` 必须与后端匹配
3. 接口变更必须同步更新前后端代码
4. 新增接口必须在 Swagger 文档中注册
5. 接口路径命名使用小写字母和连字符（kebab-case）

---

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

**设计文档一旦确认，后续开发必须按文档自主执行。**

#### 核心要求
- **禁止反复询问**"是否继续""下一步做什么""是否开始"——直接按计划推进
- 每完成一个 Sprint，自动提交推送，然后立即开始下一个 Sprint
- 设计文档是"**已签合同**"，不是"参考意见"
- 只在遇到**无法解决的阻塞**时才暂停询问

#### 触发条件
- 设计文档已确认（如 `MD/architecture/GRADE3A_GAP_ANALYSIS_AND_DESIGN.md`）
- Sprint 计划已制定
- 代码编译通过

#### 禁止事项
- ❌ 完成一个模块后问"继续吗？"
- ❌ 完成一个 Sprint 后问"下一步？"
- ❌ 每次工具调用前问"开始了吗？"

### 铁律 #8: 铁律和规范文档放MD目录

**所有铁律和规范文档统一存放在 `MD/specs/` 目录中。**

#### 已有规范文档
| 文档 | 路径 | 说明 |
|------|------|------|
| 执行铁律 | `MD/specs/IRON_RULES.md` | 本文档 |
| 后端开发规范 | `MD/specs/BACKEND_DEVELOPMENT_STANDARD.md` | 后端编码规范 |
| 前端开发规范 | `MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md` | 前端编码规范 |
| 后端检查清单 | `MD/specs/BACKEND_CHECKLIST.md` | 发布前检查 |
| 前端检查清单 | `MD/specs/FRONTEND_CHECKLIST.md` | 发布前检查 |
| CI/CD门禁 | `MD/specs/CICD_GATEKEEPER.md` | 构建门禁 |
| 提交模板 | `MD/specs/COMMIT_TEMPLATE.md` | Commit规范 |
| 发布清单 | `MD/specs/RELEASE_CHECKLIST.md` | 发布流程 |
| E2E测试计划 | `MD/specs/PLAYWRIGHT_TESTING_PLAN.md` | Playwright测试 |

#### AGENTS.md 同步
- 后端 `healthlink-his-server/AGENTS.md` 必须引用本文档
- 新增铁律必须同步更新本文档和 AGENTS.md

---

## 三、违规处理

| 级别 | 描述 | 处理方式 |
|------|------|---------|
| P0 违规 | 跳过测试直接提交 | 必须回滚并重新测试 |
| P0 违规 | 数据库变更不走Flyway | 回滚数据库变更，重新用Flyway执行 |
| P1 违规 | 未分解就行动 | 补充分析和计划文档 |
| P1 违规 | 文档不规范 | 补充元数据和格式 |

---

## 四、快速参考

### 后端开发速查
```bash
# 编译
export JAVA_HOME=/opt/jdk-25 && mvn clean compile -DskipTests

# 完整构建
mvn install -DskipTests

# 运行测试
mvn test -pl healthlink-his-application -Dtest="ClassName" -Dsurefire.failIfNoSpecifiedTests=false

# 启动应用
java -jar healthlink-his-application/target/*.jar --spring.profiles.active=dev
```

### 前端开发速查
```bash
# 开发模式
npm run dev

# 构建
npm run build:dev

# 测试
npm run test:run

# Lint
npm run lint
```

---

> **文档版本**: v2.0
> **最后更新**: 2026-06-06


---

---

### 铁律 #9: 开发前必须审核原有代码

**任何新功能开发前，必须先搜索项目中是否已有相关代码。**

#### 搜索清单

| 搜索目标 | 搜索路径 | 命令 |
|---------|---------|------|
| 后端Controller | `healthlink-his-server/**/controller/` | `rg -l "关键词" ...` |
| AppService | `healthlink-his-server/**/appservice/` | 同上 |
| Service/ServiceImpl | `healthlink-his-server/**/service/` | 同上 |
| Mapper | `healthlink-his-server/**/mapper/` | 同上 |
| Entity/Domain | `healthlink-his-server/**/domain/` | 同上 |
| 前端页面 | `healthlink-his-ui/src/views/` | 同上 |
| 前端API | `healthlink-his-ui/src/api/` | 同上 |
| 数据库表 | Flyway迁移脚本 | `rg "CREATE TABLE" ...` |

#### 判定规则

| 情况 | 处理方式 |
|------|---------|
| 后端+前端都已有 | 审查现有实现，找出缺陷/遗漏，在原基础上优化 |
| 只有后端，前端缺失 | 只补前端页面，调用现有API |
| 只有前端，后端缺失 | 只补后端接口，前端API对齐 |
| 前端壳子存在但功能不完整 | 分析壳子现有逻辑，补充完善 |
| 后端接口存在但业务逻辑不完整 | 在原Service基础上扩展，不新建 |
| 完全没有 | 从零开发，但先检查是否有可复用的组件/工具类 |

#### 禁止行为
- ❌ 不看代码就新建Controller/Service
- ❌ 已有功能重复实现
- ❌ 废弃原有代码另写一套
- ❌ 创建与现有模块功能重叠的新模块

---

---

---

### 铁律 #12: 模块优化必须分析现有业务流并说明促进作用

**任何模块新增/优化前，必须先分析现有业务流程全貌。**

#### 必须回答的5个问题

| # | 问题 | 说明 |
|---|------|------|
| 1 | 该模块在整体业务流中处于什么位置？ | 上游/下游/并行 |
| 2 | 该模块与哪些现有模块有数据流转关系？ | 列出所有关联模块 |
| 3 | 优化对上下游模块有什么促进作用？ | 减少重复、提升一致性、加快流程 |
| 4 | 变更是否影响现有业务流程？ | 兼容性评估 |
| 5 | 业务规则是否与现有模块冲突？ | 规则一致性检查 |

#### 业务逻辑分析文档模板

```
# 模块名 — 业务逻辑分析

## 1. 整体业务流程定位
[该模块在HIS系统中的位置，上下游关系图]

## 2. 关联模块分析
| 关联模块 | 数据流向 | 交互方式 | 影响程度 |
|---------|---------|---------|---------|

## 3. 优化促进作用
| 维度 | 优化前 | 优化后 | 提升效果 |
|------|--------|--------|---------|

## 4. 兼容性评估
- 对现有模块的影响
- 数据迁移需求
- 接口变更影响

## 5. 规则一致性检查
- 新增规则是否与现有规则冲突
- 状态流转是否与现有状态机兼容
```

---

### 铁律 #11: 模块设计必须分析业务逻辑，不能只做CRUD

**任何新模块/功能开发前，必须先进行业务逻辑分析和梳理。**

#### 禁止行为
- ❌ 拿到需求就直接写CRUD，不思考业务流程
- ❌ 不查阅标准规范就开发医疗业务模块
- ❌ 没有设计文档就直接编码
- ❌ 把"能增删改查"当成"功能完成"

#### 必须完成的设计步骤

| # | 步骤 | 产出物 | 说明 |
|---|------|--------|------|
| 1 | 查阅标准规范 | 参考文档清单 | 国家卫健委标准、医保局规范、HL7/FHIR、三甲评审标准 |
| 2 | 梳理业务流程 | 流程图/文字描述 | 正常流程 + 异常流程 + 边界场景 |
| 3 | 设计状态流转 | 状态机图 | 每个实体的生命周期、状态转换条件 |
| 4 | 定义业务规则 | 规则清单 | 如：药品相互作用规则、医保审核规则、危急值判定规则 |
| 5 | 设计交互时序 | 时序图 | 用户操作 → 前端事件 → API → 后端处理 → 持久化 → 响应 |
| 6 | 编写设计文档 | MD文件 | 保存到 `MD/specs/` 或 `MD/architecture/` |

#### 医疗HIS业务逻辑参考标准

| 标准/规范 | 适用模块 | 获取途径 |
|----------|---------|---------|
| 三级医院评审标准(2022版) | 全量 | 卫健委官网 |
| 电子病历应用水平分级评价 | 电子病历/质控 | 卫健委官网 |
| 互联互通标准化成熟度测评 | ESB/集成平台 | 卫健委官网 |
| 医保基金使用监督管理条例 | 医保审核/结算 | 医保局官网 |
| HL7 FHIR R4 | 数据交换/ESB | hl7.org |
| 处方管理办法 | 合理用药/处方 | 卫健委官网 |
| 抗菌药物临床应用管理办法 | 抗菌药物管理 | 卫健委官网 |
| 医院感染管理办法 | 院感管理 | 卫健委官网 |
| 病案管理与质量控制标准 | 病案管理 | 卫健委官网 |

#### 设计文档模板

```
# 模块名 设计文档

## 1. 业务背景
- 依据什么标准/规范
- 解决什么业务问题

## 2. 业务流程
### 2.1 正常流程
[流程描述/流程图]

### 2.2 异常流程
[异常场景及处理方式]

### 2.3 边界场景
[特殊情况处理]

## 3. 状态流转
| 状态 | 值 | 触发条件 | 下一状态 |
|------|-----|---------|---------|

## 4. 业务规则
| 规则编号 | 规则名称 | 规则描述 | 触发时机 |
|---------|---------|---------|---------|

## 5. 数据模型
[实体关系图/表结构设计]

## 6. 接口设计
[API列表+参数+返回值]

## 7. 前端页面设计
[UI布局+交互+调用流程]

## 8. 测试用例
[关键业务场景测试]
```

---

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

**所有新模块/页面的设计文档必须包含以下要素，缺一不可：**

#### 必备要素

| # | 要素 | 说明 |
|---|------|------|
| 1 | 页面UI布局 | 每个区域放什么组件、尺寸比例、栅格布局（文字描述或线框图） |
| 2 | 交互效果清单 | 每个按钮/操作触发什么效果（弹窗、抽屉、跳转、动画） |
| 3 | 前后端调用流程 | 每个用户操作 → 对应API → 参数 → 返回数据 → 前端渲染 |
| 4 | 系统调用关系 | Controller → AppService → Service → Mapper 完整链路 |
| 5 | 方法函数调用关系 | 关键方法签名、参数、返回值、异常处理 |
| 6 | 状态流转图 | 数据状态变化 → UI如何响应 |
| 7 | 异常/边界处理 | 空数据、加载中、错误状态的UI表现 |

#### 前后端调用流程模板

```
用户操作: [具体按钮/操作]
  → 前端: [HTTP方法] [API路径] {参数}
  → 后端: Controller.method() → AppService.method() → Service.method() → Mapper.method()
  → 返回: {code, msg, data}
  → 前端: [渲染逻辑]
```

#### 详细规范
参见 `MD/specs/UI_DESIGN_IRON_RULES.md`