29 · 数据库事实源与结构收敛规范（🔴 阻断）

📦 来源：wl-skills-bd v0.24.0 · standards/29-database-source-governance.md · 本文可判定条目由 wl-skills-bd validate（B 系列）与 mvn verify -Pwl-quality 自动执行。

适用于建表、加字段、代码生成、数据库迁移、结构审计和旧表退役。结构正确性不因 dev/sit 而降级；只有审批流程按环境分级。

1. 唯一事实源与四方闭环

顺序固定为：业务/数据库设计文档 → docs/db-spec/*.json 机器镜像 → wl-contract.json 与代码 → Flyway migration → 数据库只读快照。

• 文档镜像必须逐表记录表名、表注释和有序字段；能确定时同时记录字段类型、可空性、默认值和注释。
• 文档有的表必须同名复用，禁止另建同义表架空基线；发现文档不合理时先提出问题，由业务负责人确认后修订文档和镜像。
• Entity、Mapper、SQL、Flyway 与库快照必须使用同一物理名称。MySQL 为 lower_snake_case，Oracle 为 UPPER_SNAKE_CASE，同一 schema 禁止混用。
• B31、codegen validate/plan/apply 和 db preview 必须运行同一事实源门禁；门禁指纹进入 planHash，文档或审批登记变化后旧计划自动失效。
• 契约必须先分类：crud 是严格生成事实，schema-mirror 是数据库只读镜像，integration-projection 是跨系统投影。后两类可进入 Catalog/影响分析，但禁止假装满足 CRUD Schema 后进入 codegen。

2. 字段顺序与扩展规则

• 文档字段必须按文档顺序前置，名称、大小写、类型、可空性、默认值、注释逐项一致。
• 基线不足时优先在原表末尾追加字段。扩展字段不得插入文档字段中间，也不得借扩展名义复制一套同义字段。
• 只有原表无法合理承载独立生命周期、基数、权限或事务边界时才允许新建扩展表。
• 扩展表/字段必须登记到 .wl-skills-bd/db-governance.json，至少包含用途、原因、需求/上游来源、审批人和审批号。代码零引用不能单独证明字段可删；还需确认未开发需求和上下游契约。
• 退役表必须先证明代码零读写、数据已回填对账、业务冒烟通过，再用独立 contract migration 删除，并同步文档、契约、白名单和归档。

3. 禁止项

• 禁止先按代码随意建表，再反向修改文档为代码背书。
• 禁止用永久 waiver 掩盖表改名、漏字段或双表并存；表名争议必须回到文档决策。
• 禁止手工 ALTER 后只记账而不回写文档、契约和 Flyway。执行账本只是短期取证，不是第二事实源。
• 执行账本必须精确到表和列，绑定已审批 DDL 的 64 位 planHash、审批单、来源、执行人与执行时间；默认 24 小时、最长 7 天到期，禁止整表通配和永久宽限。
• 台账写入必须经过 preview → planHash → confirm → 受保护环境护栏 → 原子写入 → 哈希复核；账本 JSON 损坏时 fail closed，禁止按空账本覆盖。
• 禁止根据字段名猜字典、类型、默认值或外键；无可靠来源就标为待确认并阻断生成。
• 禁止修改已执行的 Flyway 文件；修复必须新增版本。

3.1 字段影响分析

加字段、改长度、改类型或退役前先执行 impact field --module <module> --field <name|column> [--table <table>]。报告至少给出契约类型、物理容量、所有权、Java 请求边界、Expand/Backfill/Contract 顺序以及带文件/行号的源码引用。

• 必须指定模块，禁止为“保险”隐式扫描全仓。
• DTO 最大长度超过物理容量时阻断；缺少可确定边界时只对直接关联的 Entity/DTO 报告，不能拿其他表的同名字段制造误报。
• contract 阶段必须有在先 expand 和 backfill 证据；所有权未知或冲突必须显式保留，不由工具猜测。

4. 环境分级：严结构、简流程

环境	结构门禁	执行流程
dev/sit	全量严格	一次审批冻结 planHash 后连续执行 precheck → migrate → validate → postcheck → 冒烟；只在真实门禁失败时停止
uat	全量严格	业务负责人 + 执行人确认，同一冻结包连续执行并留证
pre/prod	全量严格	变更单、DBA/CD、备份/恢复证据、窗口、观察与必要的恢复演练

SIT 不要求每个只读步骤重复审批，也不为无风险信息重复造多份附件。失败时一次性完成根因分析、修订 SQL/门禁及静态复算，再从 precheck 重跑整链；禁止一处一修、反复拉扯。

5. 最低验收证据

1. 文档镜像与契约对账：基线表/字段零缺失、顺序和属性零偏差，扩展均登记。
2. Flyway validate 成功、pending=0，迁移文件哈希可追溯。
3. 数据库快照与目标白名单对账：表、字段、顺序、类型、注释、索引和行数门禁符合计划。
4. 前后端关键查询/新增/修改/删除或状态流转冒烟通过；旧结构零读写后方可退役。
5. docs、契约、代码、migration、数据库终态同时更新，任何一方滞后都不算闭环。

6. 防漂移与快速恢复

• 正常恢复链是“数据备份/日志 + Git 中不可变的 Flyway 全历史”，不是从某位同事本地 DBeaver 导出临时 DDL。
• CI 对空 schema 执行全量 migrate + validate，并用结构快照跑 db drift；这同时证明新环境可重建、存量环境无漂移。
• 大量历史迁移需要收敛时，可在独立版本生成经评审的 baseline migration；旧环境保留原 Flyway history，新环境按 Flyway baseline 规则启用，禁止直接删除历史或修改 checksum。
• 每次发布归档目标 schema 的只读全属性快照和 fingerprint，作为诊断/对账证据；快照不能替代数据备份，也不能越过 migration 直接覆盖数据库。
• 数据恢复和结构恢复分开验收：结构恢复后仍需恢复数据、执行对账 SQL和关键业务冒烟。

变更记录

• 2026-08-31 v0.23：新增契约类型分流、字段影响证据、所有权和迁移链门禁。
• 2026-08-22 v0.20：将数据库基线复用、扩展登记、字段全属性/顺序门禁和环境分级流程固化为阻断规范。