数据库设计文档模板

本模板用于模块 database-design.md。新增表、结构重构和正式数据库设计交付按范围记录全量字段；既有表的普通局部变更只维护受影响字段、约束及关联差异。不得以“核心字段”为由筛掉应记录的字段。

1. 设计范围与核验状态

项目	内容
模块名称
文档版本	0.01
最近核对日期
设计数据库	逻辑类型：可迁移；物理类型：按当前数据库记录
数据库交付基线
实体/Mapper 来源
MCP 结构核验	查询时间、环境、核验人/Agent
数据库核验状态	待核对 / 已按交付基线核对 / 已按实际库核对 / 存在差异

未执行实际结构核验时，不得把字段写成“已实现”；无法确认的内容标记为“待核对”，不能靠猜测补齐。

2. 实体关系

[表/实体] 1 ── N [表/实体]

补充每条关系的主键、外键、删除策略、是否允许孤儿记录，以及逻辑外键是否由数据库约束还是服务端保证。

3. 字段矩阵与局部差异

新增表、结构重构和正式数据库设计交付，对范围内每张实际持久化表单独列完整矩阵，包含数据库中存在的每个字段，包括页面不展示的主键、审计及继承字段、公共字段、流程字段、快照字段、派生字段、兼容历史字段和只追加日志字段。每个字段独占一行，必须填写中文含义，并按适用范围记录类型、可空性、默认值、约束/索引、来源与核验状态；不得把多个字段压缩到同一个单元格。中文含义优先采用已核实的数据库字段注释，再结合实体、页面与业务基线；注释缺失或有歧义而无法确认时标记“待核对”，不得猜测。既有表的普通局部变更只更新受影响的字段行及第 2、4～6 节中相关的关联、约束、差异和迁移说明；已有完整矩阵时在原文维护，不为本次局部任务补齐无关历史字段。

3.1 [表名]（表用途；全量范围或局部受影响字段）

字段名	中文含义	逻辑类型	物理类型（含长度/精度）	可空	默认值	约束/索引
ID	主键	64 位整数	BIGINT	否	无	主键

字段矩阵填写要求：

• 一行一个物理字段；字段名、中文含义、逻辑与物理类型、长度/精度、可空性、默认值，以及适用的主键、外键、唯一和索引均须记录。使用“无”表示确实没有默认值，无法确认时写“待核对”。
• 逻辑类型用于业务设计；物理类型按实际交付基线或数据库记录。不同环境存在差异时，在第 5 节列明环境及差异，不能把一个环境的结果套用于另一个环境。
• 表下补充字段来源或生成规则，以及核验状态和证据；相同来源、环境和核验时间可合并说明，有差异的字段分别注明。状态使用文档控制栏的取值，并记录交付基线标识、实际库环境及 MCP 查询时间，或待核对原因。
• 可空、默认值以 DDL 或实际库为证据；业务必填与数据库 NOT NULL 分开说明。中文含义无法确认时标“待核对”，不得猜测。

字段来源与核验证据： [填写字段来源或生成规则、环境、时间和核验结果；存在差异的字段单独说明。]

4. 约束、索引与字典

类型	名称/表达式	作用	设计/物理差异	核验状态
PK/UK/FK/CHECK
普通/联合/条件索引
字典

5. 设计字段与实际字段差异

表	差异字段	差异类型	设计值	实际值	处理方式	状态
		新增 / 缺失 / 类型不一致 / 默认值不一致 / 约束不一致			迁移、调整设计或保留兼容

6. 迁移与兼容说明

• 当前数据库专属语法、类型和索引写在数据库变更记录或适配说明，不把厂商实现误写成业务规则。
• 影响 DM8、人大金仓、openGauss 等目标库的字段类型、精度、默认值、空值策略和索引差异逐项列出。
• 字段删除、重命名、缩短长度、改变可空性和改变默认值必须说明存量数据处理与回滚策略。