docs: 新增 Flyway 使用指南 + 铁律
- 新增 docs/FLYWAY_USAGE_GUIDE.md (326行完整使用指南) - AGENTS.md 新增铁律: 数据库变更必须通过 Flyway 迁移 - 禁止直接执行 DDL 而不创建迁移文件 - 禁止修改已执行的迁移文件 - 新表必须包含租户/审计/软删除字段
This commit is contained in:
10
AGENTS.md
10
AGENTS.md
@@ -189,6 +189,16 @@ Harness: .harness/ (init.sh, PROGRESS.md, feature_list.json, ...)
|
||||
⑤ 统计数据：检查聚合 SQL → 确认统计包含新状态
|
||||
```
|
||||
|
||||
### 数据库变更必须通过 Flyway 迁移（铁律）
|
||||
凡涉及**新建表、新增字段、修改字段、加索引**等 DDL 变更，**必须**通过 Flyway 框架实现：
|
||||
1. 在 `openhis-server-new/openhis-application/src/main/resources/db/migration/` 创建 `V{n}__描述.sql`
|
||||
2. 版本号递增（`V2`, `V3`, `V4`...），双下划线分隔
|
||||
3. **禁止**直接在数据库执行 DDL 而不创建迁移文件
|
||||
4. **禁止**修改已执行的迁移文件（Flyway 会校验 checksum）
|
||||
5. 新表必须包含：`tenant_id`, `create_by`, `create_time`, `update_by`, `update_time`, `valid_flag`
|
||||
6. 多租户表还需在 `MybatisPlusConfig.java` 的 `TENANT_TABLES` 中注册
|
||||
7. 详细使用指南见 `docs/FLYWAY_USAGE_GUIDE.md`
|
||||
|
||||
### 禁止修改已有公开方法签名
|
||||
- 不能删除或重命名已有的 public 方法
|
||||
- 不能修改已有方法的参数列表
|
||||
|
||||
326
docs/FLYWAY_USAGE_GUIDE.md
Normal file
326
docs/FLYWAY_USAGE_GUIDE.md
Normal file
@@ -0,0 +1,326 @@
|
||||
# Flyway 数据库迁移使用指南
|
||||
|
||||
> **项目**: OpenHIS 医院管理系统
|
||||
> **数据库**: PostgreSQL 192.168.110.252:15432 (schema: hisdev)
|
||||
> **Flyway 版本**: 8.5.x (Spring Boot 2.7 管理)
|
||||
> **编制日期**: 2026-06-04
|
||||
|
||||
---
|
||||
|
||||
## 一、当前配置
|
||||
|
||||
| 配置项 | 值 | 说明 |
|
||||
|---|---|---|
|
||||
| `spring.flyway.enabled` | `true` | 启用 Flyway |
|
||||
| `spring.flyway.baseline-on-migrate` | `true` | 首次启用时对现有表建基线 |
|
||||
| `spring.flyway.baseline-version` | `0` | 基线版本号 |
|
||||
| `spring.flyway.locations` | `classpath:db/migration` | 迁移文件目录 |
|
||||
| `spring.flyway.validate-on-migrate` | `true` | 执行前校验 |
|
||||
|
||||
**迁移文件目录：**
|
||||
```
|
||||
openhis-server-new/openhis-application/src/main/resources/db/migration/
|
||||
```
|
||||
|
||||
**当前状态：**
|
||||
```
|
||||
V0 << Flyway Baseline >> (自动基线，覆盖现有所有表)
|
||||
V1 baseline_marker (空标记文件)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 二、文件命名规范
|
||||
|
||||
```
|
||||
V{版本号}__{描述}.sql
|
||||
```
|
||||
|
||||
| 规则 | 示例 | 说明 |
|
||||
|---|---|---|
|
||||
| 版本号必须递增 | `V2`, `V3`, `V4` | 整数，不可重复 |
|
||||
| 双下划线分隔 | `V2__add_column.sql` | 单下划线会被当作版本号一部分 |
|
||||
| 描述用下划线连接 | `V2__add_user_avatar.sql` | 不要用空格或中文 |
|
||||
| 大小写敏感 | `V2__Add_Column.sql` | 建议全小写 |
|
||||
|
||||
**✅ 正确示例：**
|
||||
```
|
||||
V2__add_practitioner_avatar.sql
|
||||
V3__create_nurse_station_table.sql
|
||||
V4__modify_encounter_diagnosis_index.sql
|
||||
V5__add_yb_catalog_fields.sql
|
||||
```
|
||||
|
||||
**❌ 错误示例：**
|
||||
```
|
||||
v2__add_column.sql # 版本号必须大写 V
|
||||
V2 add column.sql # 缺少双下划线
|
||||
V2__Add Column.sql # 描述中有空格
|
||||
V2.1__add_column.sql # 不支持小数版本号
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、新增表（完整示例）
|
||||
|
||||
### 场景：新建一个「手术排班统计」表
|
||||
|
||||
**Step 1：创建迁移文件**
|
||||
|
||||
```sql
|
||||
-- 文件：db/migration/V2__create_surgery_schedule_stats.sql
|
||||
|
||||
CREATE TABLE IF NOT EXISTS surgery_schedule_stats (
|
||||
id BIGINT PRIMARY KEY,
|
||||
schedule_id BIGINT NOT NULL COMMENT '排程ID',
|
||||
doctor_code VARCHAR(64) COMMENT '医生编码',
|
||||
surgery_count INT DEFAULT 0 COMMENT '手术数量',
|
||||
total_duration INT DEFAULT 0 COMMENT '总时长(分钟)',
|
||||
tenant_id INT DEFAULT 1 COMMENT '租户ID',
|
||||
create_by VARCHAR(64) DEFAULT 'system' COMMENT '创建人',
|
||||
create_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
|
||||
update_by VARCHAR(64) COMMENT '更新人',
|
||||
update_time TIMESTAMP COMMENT '更新时间',
|
||||
valid_flag INT DEFAULT 1 COMMENT '有效标志 1=有效 0=无效'
|
||||
);
|
||||
|
||||
COMMENT ON TABLE surgery_schedule_stats IS '手术排班统计表';
|
||||
CREATE INDEX idx_surgery_stats_schedule ON surgery_schedule_stats(schedule_id);
|
||||
CREATE INDEX idx_surgery_stats_tenant ON surgery_schedule_stats(tenant_id);
|
||||
```
|
||||
|
||||
**Step 2：启动应用**
|
||||
|
||||
```bash
|
||||
cd openhis-server-new
|
||||
mvn clean package -DskipTests
|
||||
java -jar openhis-application/target/openhis-application.jar --spring.profiles.active=dev --server.port=18082
|
||||
```
|
||||
|
||||
**Step 3：Flyway 自动执行**
|
||||
|
||||
启动日志中会看到：
|
||||
```
|
||||
Flyway 迁移完成，执行了 1 个迁移
|
||||
```
|
||||
|
||||
数据库中 `flyway_schema_history` 表新增一条记录：
|
||||
```
|
||||
installed_rank | version | description | type | success
|
||||
---------------+---------+--------------------------+------+---------
|
||||
3 | 2 | create surgery schedule.. | SQL | t
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、修改表结构（ALTER）
|
||||
|
||||
### 场景：给 practitioners 表加一个 phone 字段
|
||||
|
||||
```sql
|
||||
-- 文件：db/migration/V3__add_practitioner_phone.sql
|
||||
|
||||
-- PostgreSQL
|
||||
ALTER TABLE practitioner ADD COLUMN IF NOT EXISTS phone VARCHAR(32) COMMENT '联系电话';
|
||||
```
|
||||
|
||||
### 场景：给表加索引
|
||||
|
||||
```sql
|
||||
-- 文件：db/migration/V4__add_encounter_index.sql
|
||||
|
||||
CREATE INDEX IF NOT EXISTS idx_encounter_patient ON adm_encounter(patient_id);
|
||||
CREATE INDEX IF NOT EXISTS idx_encounter_tenant ON adm_encounter(tenant_id);
|
||||
```
|
||||
|
||||
### 场景：修改字段类型
|
||||
|
||||
```sql
|
||||
-- 文件：db/migration/V5__extend_charge_item_code.sql
|
||||
|
||||
-- PostgreSQL: 修改 varchar 长度
|
||||
ALTER TABLE adm_charge_item ALTER COLUMN charge_item_code TYPE VARCHAR(128);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、多租户表迁移
|
||||
|
||||
项目有 50+ 张多租户表（`tenant_id` 字段），新增的多租户表需要：
|
||||
|
||||
```sql
|
||||
-- 文件：db/migration/V6__create_clinic_referral_table.sql
|
||||
|
||||
CREATE TABLE IF NOT EXISTS clinic_referral (
|
||||
id BIGINT PRIMARY KEY,
|
||||
encounter_id BIGINT NOT NULL,
|
||||
referral_reason TEXT,
|
||||
tenant_id INT DEFAULT 1,
|
||||
create_by VARCHAR(64) DEFAULT 'system',
|
||||
create_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
valid_flag INT DEFAULT 1
|
||||
);
|
||||
|
||||
COMMENT ON TABLE clinic_referral IS '转诊记录表';
|
||||
```
|
||||
|
||||
然后在 `MybatisPlusConfig.java` 的 `TENANT_TABLES` 集合中添加表名：
|
||||
|
||||
```java
|
||||
private static final Set<String> TENANT_TABLES = new HashSet<>(Arrays.asList(
|
||||
// ... 现有表 ...
|
||||
"clinic_referral" // 新增
|
||||
));
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 六、开发规范
|
||||
|
||||
### 必须遵守
|
||||
|
||||
| 规则 | 原因 |
|
||||
|---|---|
|
||||
| **不要修改已执行的迁移文件** | Flyway 会校验 checksum，修改后启动报错 |
|
||||
| **版本号只能递增** | 不能回退版本号 |
|
||||
| **每次只改一个表** | 方便回滚和排查 |
|
||||
| **使用 `IF NOT EXISTS`** | 防止重复执行报错 |
|
||||
| **迁移文件加入 Git** | 全团队共享迁移历史 |
|
||||
|
||||
### 推荐做法
|
||||
|
||||
| 做法 | 说明 |
|
||||
|---|---|
|
||||
| 先在测试环境验证 | 生产部署前确认迁移无误 |
|
||||
| 一个迁移文件改一张表 | 便于追踪和回滚 |
|
||||
| 文件名描述清晰 | `V2__add_yb_catalog_drug_name.sql` 比 `V2__update.sql` 好 |
|
||||
| DDL 和 DML 分开 | 建表用 `V2__create_xxx.sql`，数据初始化用 `V3__init_xxx_data.sql` |
|
||||
|
||||
---
|
||||
|
||||
## 七、回滚方案
|
||||
|
||||
Flyway **不支持自动回滚**，需要手动处理：
|
||||
|
||||
### 情况 1：迁移刚执行，还没提交代码
|
||||
|
||||
```bash
|
||||
# 1. 删除 flyway_schema_history 中的记录
|
||||
PGPASSWORD=Jchl1528 psql -h 192.168.110.252 -p 15432 -U postgresql -d postgresql \
|
||||
-c "SET search_path TO hisdev; DELETE FROM flyway_schema_history WHERE version = '6';"
|
||||
|
||||
# 2. 手动撤销 DDL
|
||||
PGPASSWORD=Jchl1528 psql -h 192.168.110.252 -p 15432 -U postgresql -d postgresql \
|
||||
-c "SET search_path TO hisdev; DROP TABLE IF EXISTS clinic_referral;"
|
||||
|
||||
# 3. 删除迁移文件
|
||||
rm openhis-server-new/openhis-application/src/main/resources/db/migration/V6__create_clinic_referral_table.sql
|
||||
|
||||
# 4. 重启应用
|
||||
```
|
||||
|
||||
### 情况 2：已提交代码，需要紧急回滚
|
||||
|
||||
```sql
|
||||
-- 手动执行逆向 SQL
|
||||
DROP TABLE IF EXISTS clinic_referral;
|
||||
DELETE FROM flyway_schema_history WHERE version = '6';
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 八、常用排查命令
|
||||
|
||||
```sql
|
||||
-- 查看所有已执行的迁移
|
||||
SELECT installed_rank, version, description, type, success, installed_on
|
||||
FROM flyway_schema_history
|
||||
ORDER BY installed_rank;
|
||||
|
||||
-- 查看是否有失败的迁移
|
||||
SELECT * FROM flyway_schema_history WHERE success = false;
|
||||
|
||||
-- 查看当前最新版本
|
||||
SELECT MAX(version) AS current_version FROM flyway_schema_history;
|
||||
|
||||
-- 手动标记某版本为成功（紧急修复用）
|
||||
-- UPDATE flyway_schema_history SET success = true WHERE version = '6';
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 九、文件清单
|
||||
|
||||
```
|
||||
openhis-server-new/openhis-application/src/main/resources/db/migration/
|
||||
├── README.md # 使用说明
|
||||
├── V1__baseline_marker.sql # 基线标记（空文件）
|
||||
├── V2__xxx.sql # 你的第一个迁移
|
||||
├── V3__xxx.sql # 第二个迁移
|
||||
└── ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 十、注意事项（HIS 系统特有）
|
||||
|
||||
| 场景 | 处理方式 |
|
||||
|---|---|
|
||||
| **新功能开发** | 建表/改表时创建 `V{n}__xxx.sql` |
|
||||
| **代码生成器生成的表** | 生成后把 DDL 放入迁移文件 |
|
||||
| **Flowable 工作流表** | 由 Flowable 自己管理，不要用 Flyway 管 |
|
||||
| **多租户字段** | 新表必须加 `tenant_id INT DEFAULT 1` |
|
||||
| **逻辑删除字段** | 新表必须加 `valid_flag INT DEFAULT 1` |
|
||||
| **审计字段** | 新表必须加 `create_by`, `create_time`, `update_by`, `update_time` |
|
||||
|
||||
---
|
||||
|
||||
## 十一、PostgreSQL 常用 DDL 速查
|
||||
|
||||
### 建表模板
|
||||
|
||||
```sql
|
||||
CREATE TABLE IF NOT EXISTS {表名} (
|
||||
id BIGINT PRIMARY KEY,
|
||||
{字段} {类型} {默认值} COMMENT '{说明}',
|
||||
tenant_id INT DEFAULT 1 COMMENT '租户ID',
|
||||
create_by VARCHAR(64) DEFAULT 'system' COMMENT '创建人',
|
||||
create_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
|
||||
update_by VARCHAR(64) COMMENT '更新人',
|
||||
update_time TIMESTAMP COMMENT '更新时间',
|
||||
valid_flag INT DEFAULT 1 COMMENT '有效标志 1=有效 0=无效'
|
||||
);
|
||||
|
||||
COMMENT ON TABLE {表名} IS '{表说明}';
|
||||
CREATE INDEX idx_{表名}_{字段} ON {表名}({字段});
|
||||
```
|
||||
|
||||
### 加字段
|
||||
|
||||
```sql
|
||||
ALTER TABLE {表名} ADD COLUMN IF NOT EXISTS {字段} {类型} COMMENT '{说明}';
|
||||
```
|
||||
|
||||
### 加索引
|
||||
|
||||
```sql
|
||||
CREATE INDEX IF NOT EXISTS idx_{表名}_{字段} ON {表名}({字段});
|
||||
```
|
||||
|
||||
### 改字段类型
|
||||
|
||||
```sql
|
||||
ALTER TABLE {表名} ALTER COLUMN {字段} TYPE {新类型};
|
||||
```
|
||||
|
||||
### 删字段
|
||||
|
||||
```sql
|
||||
ALTER TABLE {表名} DROP COLUMN IF EXISTS {字段};
|
||||
```
|
||||
|
||||
### 删表
|
||||
|
||||
```sql
|
||||
DROP TABLE IF EXISTS {表名};
|
||||
```
|
||||
Reference in New Issue
Block a user