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	全量模块优化
#13	开发必须深度分析+深度设计，禁止浅层糊弄	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: 验证后信

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

验证命令

# 后端编译
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 违规	文档不规范	补充元数据和格式

---

四、快速参考

后端开发速查

# 编译
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

前端开发速查

# 开发模式
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
• ❌ 已有功能重复实现
• ❌ 废弃原有代码另写一套
• ❌ 创建与现有模块功能重叠的新模块

---

---

---

---

铁律 #13: 开发必须深度分析+深度设计，禁止浅层糊弄

如果一个模块不能在真实医院环境中使用，就不算完成。

禁止行为（红线）

❌ 禁止	说明
写空壳页面就宣称"功能完成"	页面有内容但没有实际业务逻辑
只做CRUD就宣称"模块开发完毕"	缺少业务规则/状态流转/异常处理
设计文档只有标题没有内容	设计文档是"施工图纸"，必须有实质内容
接口只返回200不验证业务逻辑	测试必须验证业务正确性，不只是HTTP状态码
前端只有表格没有交互	缺少搜索/筛选/分页/操作反馈/空状态
后端没有参数校验	缺少必填校验/格式校验/业务规则校验

每个模块必须达到的标准

维度	必须具备	自检方法
前端	搜索/筛选/分页/新增编辑弹窗/操作反馈/空状态/加载态	能否正常操作每个功能
后端	参数校验/业务规则校验/异常处理/日志记录	能否处理正常+异常场景
数据	完整字段/关联关系/索引/Flyway迁移	数据库能否支撑业务
业务	正常流程/异常流程/边界场景/状态机	能否覆盖真实业务场景
设计	业务背景/流程图/规则清单/时序图/测试用例	设计文档是否可执行
测试	接口测试/业务逻辑测试/异常测试	能否在真实环境使用

质量自检清单

开发完成后必须回答以下问题：

□ 这个模块放到医院里，医生/护士/收费员能直接用吗？
□ 搜索条件是否覆盖了真实使用场景？
□ 表单校验是否覆盖了所有必填项和格式要求？
□ 操作反馈是否清晰（成功/失败/加载中/空数据）？
□ 后端是否有完整的参数校验和业务规则校验？
□ 异常场景（网络断开/数据不存在/权限不足）是否处理？
□ 状态流转是否完整（每个状态都能正确转换）？
□ 设计文档是否足够详细，其他人能据此开发？
□ 测试用例是否覆盖了正常流程和异常流程？
□ 接口返回的数据结构是否前后端对齐？

深度设计文档标准

文档部分	最低要求	优秀标准
业务背景	说明做什么	说明为什么做+参考什么标准
业务流程	正常流程文字描述	正常+异常+边界+流程图
状态流转	状态列表	状态机图+转换条件+权限
业务规则	规则名称	规则编号+描述+触发时机+处理方式
数据模型	表名+字段	ER图+字段说明+索引+关联
接口设计	API路径	请求/响应示例+错误码+版本
前端设计	页面列表	UI线框+交互时序+组件选型
测试用例	功能清单	正常/异常/边界/性能测试用例

---

铁律 #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

铁律18: 禁止破坏原有功能（绝对铁律）

原则: 完善增加功能和流程时，绝对不能破坏或者让原有功能不能用。

执行要求:

1. 修改已有实体前必须对比: 用 git show HEAD~N:./file.java 对比原始文件，保留所有原有字段和方法
2. 新增字段只能追加: 在实体类末尾追加新字段，不能删除或重命名已有字段
3. 新增方法只能追加: 在Service接口末尾追加新方法，不能修改已有方法签名
4. SQL迁移只能ADD: Flyway迁移脚本只允许 ALTER TABLE ADD COLUMN，不允许 DROP COLUMN 或 RENAME COLUMN
5. Controller新端点: 新增 @PostMapping / @GetMapping，不能修改已有端点的路径或参数
6. 前端新页面: 新增页面目录，不能修改已有页面的组件结构
7. 编译必须通过: 每次修改后必须 mvn clean compile -DskipTests 验证
8. 回归验证: 修改后检查所有引用该类/方法的文件是否仍能编译

违规判定: 如果因为本次修改导致原有代码编译失败或运行报错，视为违反铁律18，必须立即回滚修复。

铁律编号: 18 优先级: P0（绝对） 适用范围: 全项目