华佗
35d193d9f2
- 任何新功能开发前必须先搜索项目中是否已有相关代码 - 已有部分功能 → 在原基础上升级优化完善，禁止另起炉灶 - 已有接口缺前端 → 只补前端；已有前端缺后端 → 只补后端 - 搜索清单：Controller/AppService/Service/Mapper/Entity/前端页面/API/数据库 - 禁止行为：不看代码就新建、重复实现、废弃原有代码另写一套 - 同步7个AI工具配置
341 lines
10 KiB
Markdown
341 lines
10 KiB
Markdown
# 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 | 设计文档/前端开发 |
|
||
|
||
---
|
||
|
||
## 二、铁律详细说明
|
||
|
||
### 铁律 #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
|
||
- ❌ 已有功能重复实现
|
||
- ❌ 废弃原有代码另写一套
|
||
- ❌ 创建与现有模块功能重叠的新模块
|
||
|
||
---
|
||
|
||
### 铁律 #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`
|
||
|