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	规范文档

---

二、铁律详细说明

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

---

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