xuanzhi-service/server/.ai-specs/sys-specs/database-upgrade-doc-spec.md

数据库升级文档规范

• 当前数据库表结构版本：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。

文件格式

-- <业务说明> / <表名> / <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。