03 — 数据库设计规范
📦 来源：
wl-skills-designv0.11.1 ·standards/03-database.md· 可判定条目由verify（[M] 机械项）自动执行。
✅ v1.0 — 工具无关（MySQL / PostgreSQL / Oracle / 达梦 均适用） 维护者：@ChenyCHENYU
§零 本规范的定位
本文件是数据库设计的唯一权威来源，约定：设计 profile、库表命名、系统字段策略、主键与索引、文档结构、数据字典格式、变更设计、与需求说明书（spec）的字段联动、验证清单（34 项）与闭环修复协议。
配套技能：
.github/skills/data-database-design/SKILL.md（操作流程） +.github/prompts/create-db-design.prompt.md（生成） +validate-db-design.prompt.md（验证）。 规范定义"做什么"，Skill 定义"怎么做"，两者不重复。
设计哲学（沿用复杂项目数据字典 10 列结构，叠加最佳实践）：
匿名基线样例（保留） 本规范叠加（最佳实践）
────────────────── ──────────────────────
ER 图 + DB 清单 + 数据字典 + 可配置系统字段 profile
逐表字段定义（10 列） + 索引设计独立章节
模块分组（订单/计划…） + 命名前缀强制约定
+ 变更履历表设计规则
+ 与 spec IPO 字段联动验证
+ 34 项验证清单 + 闭环报告0.1 设计 profile（生成前必填）
| 决策 | 可选值 | 未确认时处理 |
|---|---|---|
| 数据库方言/版本 | MySQL / PostgreSQL / Oracle / 达梦 / 其他 | 必须追问，不静默默认 |
| 租户模式 | 单租户 / 多租户 | 标记 Pending |
| 删除策略 | 软删除 / 硬删除 / 归档 | 标记 Pending |
| 审计字段 | 创建/更新人时 / 数据库审计 / 事件审计 | 推荐创建/更新人时并标注假设 |
| 主键策略 | 雪花 ID / UUID / 自增 / 其他 | 必须说明选择理由 |
| 并发控制 | 无 / 乐观锁 / 悲观锁 | 按写冲突风险决定 |
| 命名与类型映射 | 团队约定 / 本规范推荐 | 未提供时使用推荐并显式记录 |
验证时先判断 profile 是否完整，再检查设计是否与 profile 一致。项目决策优先于本规范的推荐默认值。
§一 命名约定（默认推荐）
1.1 表命名
格式：[领域码][模块码]_[业务含义]，全小写蛇形（snake_case）。
| 部位 | 规则 | 示例 |
|---|---|---|
| 领域码 | 2 位小写，标识业务域 | pm（生产）、qm（品质）、wm（仓储） |
| 模块码 | 2 位小写，标识子模块 | om（订单）、pm（计划） |
| 业务含义 | 蛇形小写，名词，可多段 | order_main、plan_detail |
示例：
ordr_order_main（订单域-订单-订单主表）、plan_plan_detail（计划域-计划-计划明细表）。
1.2 表后缀语义（固定词表）
| 后缀 | 含义 | 使用场景 |
|---|---|---|
_main | 主档表 | 一张单据的头信息 |
_detail / _dtl | 明细表 | 主档下的行项目 |
_log | 操作/历程日志表 | 记录状态流转历程 |
_resume | 变更履历表 | 记录字段级变更（含版本号） |
_rel | 关系/中间表 | 多对多关联 |
_cfg / _dict | 配置表 / 字典表 | 枚举、参数 |
1.3 字段命名
- 全部使用 小驼峰英文名记录于数据字典（与接口字段英文名保持一致），物理 DDL 落库可按数据库习惯转蛇形（如
orderNo↔order_no），但同一字段的英文名在 DB / 接口 / spec 三处必须可一一映射。 - 禁止使用数据库保留字（
order、group、level、desc、type等）作裸字段名，须加业务前缀（orderType、sortLevel）。 - 布尔/标志字段统一
xxxFlag（值 0/1）；时间字段统一xxxTime（datetime）或xxxDate（date）；金额统一xxxAmt，数量xxxQty，重量xxxWt。
1.4 索引命名
| 类型 | 格式 | 示例 |
|---|---|---|
| 普通索引 | idx_[表名去前缀]_[字段] | idx_order_main_orderNo |
| 唯一索引 | uk_[表名去前缀]_[字段] | uk_order_main_orderNo |
| 联合索引 | idx_[表名去前缀]_[字段1]_[字段2] | idx_plan_dtl_planNo_seqNo |
| 主键 | pk_[表名去前缀] | pk_order_main |
§二 系统字段 profile
以下是推荐字段集合，不是跨项目无条件强制项。根据 §零 profile 启用；启用的字段统一置于字段清单末尾审计区，并在分册中记录适用范围。
| 序号 | 字段英文名 | 字段中文名 | 类型 | 说明 |
|---|---|---|---|---|
| S1 | id | 主键 | bigint / varchar(32) | 业务表通常必备；策略见 §三 |
| S2 | createdBy | 创建人 | varchar(32) | 启用“创建/更新人时”审计时使用 |
| S3 | createdTime | 创建时间 | datetime | 启用审计时使用 |
| S4 | updatedBy | 更新人 | varchar(32) | 启用审计时使用 |
| S5 | updatedTime | 更新时间 | datetime | 启用审计时使用 |
| S6 | deletedFlag | 删除标志 | tinyint | 仅软删除 profile 使用 |
| S7 | tenantId | 租户号 | varchar(32) | 仅多租户 profile 使用 |
删除和租户策略必须成对落地：软删除查询才附加
deletedFlag = 0；多租户查询才附加租户条件。单租户或硬删除项目不得为凑字段而保留无语义列。
可选系统字段
| 序号 | 字段英文名 | 字段中文名 | 类型 | 说明 |
|---|---|---|---|---|
| S8 | version | 乐观锁版本 | int | 并发控制；高并发可被并发修改的表建议补充，默认 0，每次更新 +1 |
version（S8 乐观锁）与revNo（§六 业务履历版本号）职责不同，勿混用：
version：并发控制字段，更新时WHERE version = ?防止覆盖，应用层自增，业务无感知。revNo：业务履历版本号，与_resume变更履历表对应，业务可见、可追溯。 一张表可同时有两者（一个防并发、一个记履历），不冲突。
§三 主键与索引设计
3.1 主键选型
| 方案 | 适用 | 类型 |
|---|---|---|
| 雪花 ID（推荐） | 高并发、分布式 | bigint |
| UUID | 跨系统数据交换、对外暴露 | varchar(32) |
| 自增 | 单库单表、内部字典 | bigint auto_increment |
禁止使用业务字段（订单号等）作物理主键；业务唯一键用唯一索引（
uk_*）保证。
3.2 索引设计原则
- 外键字段、高频
WHERE/JOIN/ORDER BY字段建索引。 - 区分度低的字段（性别、状态等）不单独建索引，可作联合索引的次列。
- 联合索引遵循最左前缀：把等值查询字段放左、范围字段放右。
- 单表索引数量建议 ≤ 5，避免写放大。
- 业务唯一性必须由
uk_*唯一索引保证，不依赖应用层判重。
3.3 索引清单（每张表必须列出）
每张表的设计需含一张索引清单：
| 索引名 | 类型 | 字段 | 用途 |
|---|---|---|---|
pk_order_main | 主键 | id | 主键 |
uk_order_main_orderNo | 唯一 | orderNo | 订单号业务唯一 |
idx_order_main_custId | 普通 | custId | 按客户查询 |
§四 文档结构（每个模块固定 4 节）
沿用复杂项目结构：一个数据库分册按模块组织，每个模块固定输出以下 4 节，顺序不可变。
[模块名] 数据库设计
├── (1) ER 图 ← 实体关系图（占位 + 实体清单）
├── (2) DB 清单 ← 本模块所有表的一览表（表名/中文名/说明/记录量级）
├── (3) 数据字典 ← 逐表字段定义（10 列标准表，见 §五）
└── (4) DDL 脚本 ← 建表语句（含注释、索引、系统字段）4.1 ER 图（节 1）
- 图片占位：
【此处插入 [模块名] ER 图】 - 附实体清单表：实体名 / 对应物理表 / 与其他实体的关系（1:1 / 1:N / M:N）。
- 实体应来源于 spec 的 IPO 输出对象，做到可追溯。
4.2 DB 清单（节 2）
| 序号 | 表名 | 中文名称 | 表类型 | 说明 | 预估量级 |
|---|---|---|---|---|---|
| 1 | ordr_order_main | 订单主表 | 主档 | 订单头信息 | 万级 |
| 2 | ordr_order_dtl | 订单明细表 | 明细 | 订单行项目 | 十万级 |
4.3 数据字典（节 3）→ 见 §五
4.4 DDL 脚本（节 4）
- 每张表一段
CREATE TABLE，字段顺序 = 数据字典顺序（业务字段在前、7 个系统字段在末）。 - 每个字段带
COMMENT（= 字段中文名）；表带COMMENT（= 表中文名）。 - 含索引定义（§3.3 的索引清单逐条落地）。
§五 数据字典格式（10 列标准表 · 唯一权威格式）
直接采用复杂项目数据字典的 10 列结构，不得增删列。每张表一张表格。
| 序号 | 字段英文名 | 字段中文名 | 主/外键 | 是否索引 | 类型 | 长度 | 空否 | 缺省 | 备注 |
|---|---|---|---|---|---|---|---|---|---|
| 1 | id | 主键 | PK | 是 | bigint | - | N | - | 雪花 ID |
| 2 | orderNo | 订单号 | - | 是(UK) | varchar | 40 | N | - | 业务唯一 |
| 3 | custId | 客户 ID | FK | 是 | varchar | 32 | N | - | 关联客户表 |
| 4 | targetQuantity | 目标件重 | - | 否 | decimal | 10,2 | Y | - | 精度,小数 |
| ... | ... | ... | ... | ... | ... | ... | ... | ... | ... |
| 末 | createdBy | 创建人 | - | 否 | varchar | 32 | N | - | 系统字段 |
列填写规则
| 列 | 规则 |
|---|---|
| 序号 | 从 1 连续递增 |
| 字段英文名 | 小驼峰，与接口/spec 一致 |
| 字段中文名 | 业务术语，与 spec IPO 字段名一致 |
| 主/外键 | PK / FK / 空 |
| 是否索引 | 是 / 是(UK) / 否 |
| 类型 | 逻辑类型：varchar / decimal / int / bigint / datetime / date / tinyint / text |
| 长度 | varchar 写长度；decimal 写 精度,小数（如 10,2）；无长度写 - |
| 空否 | N（NOT NULL）/ Y（可空） |
| 缺省 | 默认值，无则 - |
| 备注 | 取值范围 / 枚举 / 关联表 / 业务说明 |
关键业务字段（主键、业务唯一键、外键）建议加粗或标色，便于评审快速定位。
§五·补 字段类型与工程约定
5b.1 逻辑类型 → 物理类型映射
数据字典用逻辑类型（工具无关）；落 DDL 时按目标数据库映射。
| 逻辑类型 | MySQL | PostgreSQL | Oracle | 达梦 DM |
|---|---|---|---|---|
varchar(n) | varchar(n) | varchar(n) | varchar2(n) | varchar(n) |
text | text | text | clob | text / clob |
int | int | integer | number(10) | int |
bigint | bigint | bigint | number(19) | bigint |
tinyint | tinyint | smallint | number(3) | tinyint |
decimal(p,s) | decimal(p,s) | numeric(p,s) | number(p,s) | decimal(p,s) |
datetime | datetime | timestamp | date / timestamp | datetime / timestamp |
date | date | date | date | date |
PostgreSQL 无
tinyint，用smallint；Oracle 无datetime/tinyint，分别用date/timestamp与number。
5b.2 长度、精度与字符集约定
| 项 | 约定 |
|---|---|
| 字符集 | 统一 utf8mb4（MySQL）/ UTF8，支持 emoji 与多语言 |
| 排序规则 | MySQL 统一 utf8mb4_general_ci（或团队统一一种，全库一致） |
| 变长文本上限 | varchar ≤ 2000；超过改 text（避免行溢出） |
| 金额 | 统一 decimal(18,2)（金额）；单价等高精度用 decimal(18,4)，全库口径一致 |
| 数量 / 重量 | 统一 decimal(18,3)（按业务最小计量精度统一） |
| 主键 bigint | 雪花 ID 用 bigint；UUID 用 varchar(32) |
同一类业务字段（金额/数量/重量）的精度必须全库统一，禁止
10,2与12,2混用。
5b.3 冗余字段标注
工业系统允许适度反范式（如下单时快照客户名）。冗余字段必须在数据字典「备注」列显式标注来源：
备注：[冗余:base_customer.custName]，下单时快照，不随客户主数据变更规则：冗余仅用于快照/性能两类场景；标注来源表.字段；说明是否随源更新。
5b.4 外键约束策略
| 策略 | 说明 |
|---|---|
| 逻辑外键（推荐） | 字段命名体现关联（custId）+ 建索引，不建物理 FOREIGN KEY，由应用层保证完整性 |
| 物理外键 | 仅在强一致、低并发的内部配置库可用；高并发业务库禁止（影响分库分表与写性能） |
默认采用逻辑外键；数据字典「主/外键」列标
FK表示逻辑外键关系，不代表物理约束。
§六 变更与历史设计
凡涉及状态流转或字段级留痕的单据，必须配套设计历史表：
| 需求 | 表设计 | 关键字段 |
|---|---|---|
| 记录状态变更历程 | [主表]_log | bizId(关联主表)、fromStatus、toStatus、operator、opTime |
| 记录字段级修改履历 | [主表]_resume | bizId、revNo(版本号)、fieldName、oldValue、newValue、changedTime |
| 需要版本号的主表 | 主表加 revNo 字段 | 每次修改 +1，与 _resume 表对应 |
选择规则：单据有审批/作废/完工等状态机 → 必建
_log；单据关键字段（金额、数量、交期）可被修改且需追溯 → 必建_resume。 ⚠️revNo（业务履历版本号，业务可见）≠version（§二 S8 乐观锁，并发控制，业务无感知）。两者职责不同，需要并发控制时另加version。
§七 与需求说明书（spec）的字段联动
数据库不是孤立设计，必须与 spec 的 IPO 表对齐，形成 spec → DB 可追溯链路。
7.1 联动规则
| 规则 | 说明 |
|---|---|
| L1 — 输出对象覆盖 | spec IPO 表 Output 列涉及的每个持久化数据对象，DB 中必须有对应表 |
| L2 — 输入字段落库 | spec IPO 表 Input/字段信息行中需持久化的字段，DB 对应表必须有对应列 |
| L3 — 中文名一致 | 同一业务字段，DB 数据字典「字段中文名」与 spec IPO「字段名」一致 |
| L4 — 英文名一致 | 同一业务字段，DB「字段英文名」与接口报文「英文字段」一致（见 04 规范） |
7.2 联动矩阵（设计产物，置于数据库分册末尾）
| spec 功能编码 | IPO 字段（中文） | DB 表 | DB 字段（英文） | 状态 |
|---|---|---|---|---|
| PLAN007 | 订单号 | ordr_order_main | orderNo | ✅ 已覆盖 |
| PLAN007 | 目标件重 | ordr_order_main | targetQuantity | ✅ 已覆盖 |
§八 验证清单（34 项）
生成或审查数据库设计时，按组逐项检查。DB-X 组（与 spec 联动）对所有数据库设计强制执行。
执行方式标记：[M] 机械可判、[J] 语义判断。四域 [M] 项均由
wl-skills-design verify执行（未覆盖时输出 skip）；Agent 先取机械结论，再判 [J] 项，合并为同一编号的报告。
DB-A 命名规范（8 项）
- [ ] A01 [M] — 表名符合
[领域码][模块码]_[业务含义]格式，全小写蛇形 - [ ] A02 [M] — 表后缀使用固定词表（
_main/_dtl/_log/_resume/_rel/_cfg） - [ ] A03 [M] — 字段英文名为小驼峰，且与接口/spec 可一一映射
- [ ] A04 [M] — 无数据库保留字裸用作字段名
- [ ] A05 [M] — 布尔/时间/金额/数量/重量字段遵循
xxxFlag/xxxTime/xxxAmt/xxxQty/xxxWt后缀约定 - [ ] A06 [M] — 普通索引命名符合
idx_[表名去前缀]_[字段] - [ ] A07 [M] — 唯一索引命名符合
uk_[表名去前缀]_[字段] - [ ] A08 [M] — 主键命名符合
pk_[表名去前缀]
DB-B 系统字段与 profile（7 项）
- [ ] B01 [J] — 分册声明方言、租户、删除、审计、主键和并发控制 profile
- [ ] B02 [M] — 每张业务表有明确主键，策略与 profile 一致
- [ ] B03 [J] — 启用审计时包含约定的创建/更新字段；未启用时给出替代审计方式
- [ ] B04 [J] — 软删除 profile 含
deletedFlag；硬删除/归档 profile 明确约束与审计 - [ ] B05 [J] — 多租户 profile 含
tenantId和隔离索引；单租户不保留无语义租户列 - [ ] B06 [M] — 已启用系统字段名称、类型、默认值和位置保持一致
- [ ] B07 [J] — 查询、唯一索引和删除操作与删除/租户 profile 一致
DB-C 主键与索引（5 项）
- [ ] C01 [J] — 主键选型明确（雪花/UUID/自增），未用业务字段作物理主键
- [ ] C02 [M] — 每张表有索引清单，列出索引名/类型/字段/用途
- [ ] C03 [M] — 业务唯一键由
uk_*唯一索引保证 - [ ] C04 [J] — 外键字段、高频查询字段已建索引
- [ ] C05 [J] — 联合索引遵循最左前缀，单表索引数 ≤ 5
DB-D 文档完整性（5 项）
- [ ] D01 [M] — 每个模块含固定 4 节：ER 图 / DB 清单 / 数据字典 / DDL
- [ ] D02 [M] — ER 图含图片占位 + 实体清单（实体名/物理表/关系）
- [ ] D03 [M] — 数据字典严格使用 10 列标准格式，列无增删
- [ ] D04 [M] — DDL 字段带 COMMENT、表带 COMMENT，含索引定义
- [ ] D05 [J] — 有状态流转/字段留痕需求的单据，配套设计
_log/_resume表
DB-E 字段类型与工程约定（4 项）
- [ ] E01 [M] — 逻辑类型在目标数据库有明确物理映射（§5b.1），DDL 类型与之一致
- [ ] E02 [M] — 同类业务字段精度全库统一（金额/数量/重量口径一致，无
10,2与12,2混用）；变长文本 > 2000 改text - [ ] E03 [J] — 冗余字段在备注列标注
[冗余:来源表.字段]及是否随源更新 - [ ] E04 [J] — 外键策略明确（默认逻辑外键，不建物理 FK；
FK列仅表关联关系）
DB-X 与 spec 联动（5 项）⬅ 闭环核心
- [ ] X01 [M] — 输出对象覆盖：spec IPO Output 涉及的每个持久化对象在 DB 中有对应表
- [ ] X02 [M] — 输入字段落库：spec IPO 需持久化字段在 DB 对应表有对应列
- [ ] X03 [M] — 中文名一致：DB「字段中文名」与 spec IPO「字段名」一致
- [ ] X04 [M] — 英文名一致：DB「字段英文名」与接口报文「英文字段」一致
- [ ] X05 [M] — 联动矩阵存在：数据库分册末尾有 spec 功能编码 → DB 表/字段 的联动矩阵，无遗漏
§九 跨文档一致性规则（集合比对算法）
DB-X 组验证时，构建集合并比对，任一不满足即为失败项：
SET_SPEC_OUT = { spec 各 IPO 表 Output 列涉及的持久化数据对象 }
SET_DB_TABLE = { 数据库分册中所有业务表的业务实体 }
SET_SPEC_FLD = { spec IPO 需持久化字段（功能编码 + 字段中文名）}
SET_DB_FLD = { DB 数据字典所有字段（表名 + 字段中文名 + 字段英文名）}
SET_API_FLD = { 接口报文所有字段英文名（见 04 规范）}
X01：SET_SPEC_OUT ⊆ {SET_DB_TABLE 的业务实体}（每个输出对象有落库表）
X02：SET_SPEC_FLD 中每个字段 ∈ SET_DB_FLD（按中文名匹配）
X03：对 X02 匹配上的字段，中文名一一对应
X04：SET_DB_FLD 的英文名 ⊇ SET_API_FLD ∩ 本模块（接口字段英文名都能在 DB 找到）
X05：联动矩阵行数 == |SET_SPEC_FLD|（无遗漏）若 spec 或接口文档不在当前工作区，标注对应 X 项为「跨文件暂挂」，提示合并后整卷复验。
§十 闭环修复协议（生成 → 验证 → 修复 → 复验）
[阶段1] 生成（按模块逐节：ER → DB清单 → 数据字典 → DDL）
↓
[阶段2] 验证（执行 34 项检查清单）
↓ 有失败项？
[阶段3] 修复（按下表优先级）
↓
[阶段4] 复验（全部 34 项通过）→ ✅ DONE修复优先级
| 优先级 | 组 | 理由 |
|---|---|---|
| 1 | DB-X 与 spec 联动 | 字段不一致会击穿整个设计链路 |
| 2 | DB-B 系统字段 | 缺系统字段无法上线，影响所有表 |
| 3 | DB-C 主键索引 | 影响性能与数据完整性 |
| 4 | DB-A 命名 | 影响可维护性 |
| 5 | DB-E 字段类型与工程约定 | 影响落库正确性与全库口径一致 |
| 6 | DB-D 文档完整性 | 影响交付质量 |
暂挂项规则
缺少调研数据无法填写时，写 【待补充：{描述}】，标注「Pending」，不算失败项。跨文件比对缺对端文档时，标注「跨文件暂挂」。
验证报告格式（每次验证后必须输出）
数据库设计验证报告 — [模块名]
验证时间：[时间]
覆盖表数：N
总项数：34 | 通过：N | 失败：M | 暂挂：K
[✅ 全部通过 / ❌ 存在失败项 / ⚠️ 含暂挂项]
失败项：
[B04] ordr_order_main 缺少 deletedFlag 字段
[X03] orderNo 在 DB 中文名"订单编号"与 spec IPO"订单号"不一致
修复动作：
[B04] 已在 ordr_order_main 审计区补 deletedFlag tinyint default 0
[X03] 已统一为"订单号"
复验：34/34 通过 → ✅ DONE