wdh-home
1e33640629
Some checks failed
CI / init (pull_request) Has been cancelled
CI / Frontend node 18.16.0 (pull_request) Has been cancelled
CI / Backend go (1.22) (pull_request) Has been cancelled
CI / release-pr (pull_request) Has been cancelled
CI / devops-test (1.22, 18.16.0) (pull_request) Has been cancelled
CI / release-please (pull_request) Has been cancelled
CI / devops-prod (1.22, 18.x) (pull_request) Has been cancelled
CI / docker (pull_request) Has been cancelled
60 lines
4.0 KiB
Markdown
60 lines
4.0 KiB
Markdown
# 数据库升级文档规范
|
||
|
||
- **当前数据库表结构版本**：`v1`
|
||
|
||
## 适用范围
|
||
|
||
- 当任务新增/修改 `.ai-specs\doc-sql\*.sql` 并导致数据库结构、字段、索引、约束、默认值或注释变化时，必须先读本文件。
|
||
- 当任务新增/修改 `.ai-specs\doc-dict\*.md` 并导致系统字典主数据或字典项变化时，必须先读本文件。
|
||
- 数据库升级 SQL 固定存放在 `.ai-transition\database-upgrade-doc`。
|
||
- 当前升级版本固定读取本文件中 `当前数据库表结构版本` 的值。
|
||
|
||
## 强制规则
|
||
|
||
- 升级 SQL 文件命名固定为 `<version>.sql`，例如 `v1.sql`、`v2.sql`、`v3.sql`。
|
||
- 当前数据库表结构版本声明为 `v1` 时，兼容变更 SQL 必须写入 `.ai-transition\database-upgrade-doc\v1.sql`。
|
||
- 默认版本文件为 `v1.sql`；不存在时，首次产生数据库结构变更必须创建。
|
||
- 修改 `.ai-specs\doc-sql\*.sql` 时，禁止只改文档；必须同步检查并补充当前版本 SQL 文件。
|
||
- 修改 `.ai-specs\doc-dict\*.md` 时，禁止只改文档；必须同步检查初始化数据和当前版本 SQL 文件。
|
||
- SQL 只记录从既有数据库升级到当前 `doc-sql` 目标结构所需的兼容变更，不重复粘贴完整建表基线。
|
||
- 同一次业务变更涉及多张表时，必须写在同一个当前版本 SQL 文件中，并按表分组。
|
||
- 修改字段名、类型、默认值、非空约束、唯一约束、普通索引、软硬删字段、注释时，都必须写对应升级 SQL。
|
||
- 新增/修改固定值域字典时，必须写入 `sys_dictionaries` 和 `sys_dictionary_details` 的幂等升级 SQL。
|
||
- 新增/修改动态值域字典时，必须至少写入 `sys_dictionaries` 的幂等升级 SQL；无固定值项时不写 `sys_dictionary_details`。
|
||
- 仅修改文档表述且不改变实际落库语义时，可以不写 SQL，但必须在最终说明中明确原因。
|
||
|
||
## SQL 要求
|
||
|
||
- SQL 默认使用 `PostgreSQL` 写法。
|
||
- 优先使用 `ALTER TABLE`、`CREATE INDEX`、`DROP INDEX`、`COMMENT ON TABLE`、`COMMENT ON COLUMN`、`UPDATE` 回填语句。
|
||
- 数据类升级 SQL 必须幂等，禁止裸 `INSERT`；必须使用 `WHERE NOT EXISTS`、`UPDATE ... FROM` 等方式兼容重复执行。
|
||
- 新增 `NOT NULL` 字段必须先给默认值或先回填历史数据，再追加 `NOT NULL` 约束。
|
||
- 新增唯一约束或唯一索引前，必须考虑历史重复数据；不能直接写会必然失败的 SQL。
|
||
- 索引创建应使用项目统一命名：唯一索引 `uk_<table_name>_<field>`，普通索引 `idx_<table_name>_<field>`。
|
||
- 字典主表重复判断固定使用 `sys_dictionaries.type`。
|
||
- 字典明细重复判断固定使用 `sys_dictionary_details.sys_dictionary_id + value`。
|
||
- 固定值域字典项变更时，先 `UPDATE` 已有 `value` 的 `label`、`sort`、`status`、`updated_at` 等展示字段，再 `INSERT` 缺失项。
|
||
- 字典主表或明细表命中已存在数据时，若表包含 `deleted_at`，恢复启用数据必须同步置空 `deleted_at`。
|
||
- 固定值域字典项废弃时，优先将 `status` 改为 `false`，禁止直接删除历史值项。
|
||
- 禁止混入 `MySQL` 方言，例如反引号、`AUTO_INCREMENT`、`ENGINE=InnoDB`、行内 `COMMENT`。
|
||
|
||
## 文件格式
|
||
|
||
```sql
|
||
-- <业务说明> / <表名> / <YYYY-MM-DD>
|
||
|
||
ALTER TABLE <table_name>
|
||
ADD COLUMN <field_name> <type>;
|
||
|
||
COMMENT ON COLUMN <table_name>.<field_name> IS '<字段说明>';
|
||
|
||
CREATE INDEX idx_<table_name>_<field_name> ON <table_name> (<field_name>);
|
||
```
|
||
|
||
## 联动关系
|
||
|
||
- 改 `doc-sql`：同步改 `Model`、`Service`、`initialize/gorm_biz.go`，并补当前版本升级 SQL。
|
||
- 改 `doc-dict`：同步改代码枚举/校验/展示逻辑、`source/system` 初始化数据，并补当前版本升级 SQL。
|
||
- 改当前版本升级 SQL：同步确认 `doc-sql`、`Model`、迁移注册与业务读写逻辑一致。
|
||
- 版本升级：先修改本文件的 `当前数据库表结构版本`，再在 `.ai-transition\database-upgrade-doc` 新增对应 `<version>.sql`。
|