数据库中文注释维护规范

目标与适用范围

本规范适用于 baiyue-firstleg/ 各服务拥有的 MySQL 业务表。目标是让表和字段语义可以直接从数据库元数据理解，并通过自动检查防止新增无注释结构。

SQL 是数据库结构和注释的事实来源。数据字典应从 information_schema 生成，不维护 Excel、Markdown 字段清单等并行事实来源。

职责

数据库注释总控：维护本规范、统一术语、审计整体覆盖率、协调统一部署 SQL，并完成最终验收。
模块负责人：依据 Controller、DTO、Service、状态机和已确认需求解释本模块字段，维护模块 SQL。
业务审核人：确认状态、金额、时间、快照、审计和数据隔离字段的业务口径。
发布执行人：按发布规范执行已审核的幂等迁移；未经当前对话授权不得直接修改测试、预发布或生产数据库。

必须遵守的规则

每张业务表和每个业务字段都必须有非空中文注释。
英文缩写和枚举值可以保留，但注释必须包含中文业务含义。
模块 src/main/resources/db/、统一部署 SQL 和实际数据库的注释必须一致。
同一张表在基线与迁移脚本中重复定义时，每个可执行定义都必须有完整注释。
注释变更不得改变字段类型、长度、精度、字符集、默认值、可空性、索引或约束。
CREATE TABLE IF NOT EXISTS 不会更新存量表注释；存量环境必须使用可重复执行的兼容迁移。
注释不得写密钥、令牌、客户真实数据、环境地址或其他敏感值。

中文口径

字段类型	注释要求	示例
`tenant_id`	客户数据统一说明客户与隔离语义；公共数据明确平台作用域	`客户ID和数据隔离键`；`平台公共数据作用域，固定为0`
状态	列出允许值及每个值的中文含义	`状态：DRAFT草稿、ISSUED已出账、PAID已收清`
金额	说明金额口径、币种来源，必要时说明含税口径	`账单含税总金额；币种由currency_code指定`
时间	说明事件语义，不只写“时间”	`财务确认实际收款时间`
JSON	说明结构、元素类型、来源及敏感性	`File服务文件ID字符串数组`
快照	说明来源和是否随源数据回写	`创建账单时的客户名称快照；客户档案变化不回写`
布尔值	明确 `0` 和 `1` 的含义	`尾差归集标记：0否、1是`
ID	说明关联对象和逻辑属性	`Firstleg入库单逻辑ID，不建立跨库外键`
版本	说明版本用途	`乐观锁版本号，每次更新递增`
审计	区分业务操作人、系统创建人和链路标识	`执行本次业务操作的平台用户ID`

不要把 tenant_id 用户可见地解释为“租户”。当前产品只有“平台、客户”两级，后端兼容字段不能扩展产品层级。

变更流程

盘点模块 SQL 中缺失、空白或纯英文注释。
根据需求确认文档和真实代码确认字段语义；不凭字段名猜测高风险业务口径。
先更新模块 SQL，再由总控同步统一部署 SQL。
为存量环境编写幂等注释迁移。MySQL MODIFY COLUMN 必须完整复述原类型、默认值、可空性及其他属性。
对比迁移前后 information_schema.columns，除 column_comment 外的结构签名必须完全一致。
运行静态审计、模块测试、统一 SQL 空库与重复执行验证。
从实际数据库元数据生成数据字典和覆盖率报告。

自动审计

在 baiyue-firstleg 根目录执行：

.\scripts\database-comment-audit.ps1
.\scripts\database-comment-audit.ps1 -Modules finance,order
.\scripts\database-comment-audit.ps1 -Modules finance -SummaryOnly
.\scripts\database-comment-audit.ps1 -Format Json
.\scripts\database-comment-audit.ps1 -FailOnIssues
.\scripts\database-comment-audit.ps1 -SelfTest

脚本只读取模块 src/main/resources/db/*.sql，不连接数据库、不启动服务、不执行 SQL。默认输出报告且退出码为 0；CI 使用 -FailOnIssues，发现缺失或纯英文注释时退出码为 1；配置或路径错误退出码为 2。

当前存量缺口允许通过不带 -FailOnIssues 的报告模式逐模块治理。模块达到 100% 后，应在其 CI 中启用强制门禁，禁止覆盖率回退。

数据库实值验收

部署后使用只读元数据查询验收：

SELECT table_schema, table_name, table_comment
  FROM information_schema.tables
 WHERE table_schema LIKE 'baiyue_%'
   AND table_type = 'BASE TABLE'
 ORDER BY table_schema, table_name;

SELECT table_schema, table_name, column_name, column_type, is_nullable,
       column_default, extra, column_comment
  FROM information_schema.columns
 WHERE table_schema LIKE 'baiyue_%'
 ORDER BY table_schema, table_name, ordinal_position;

数据字典以第二个查询为基础，可追加索引元数据；不得把生成文件改造成另一份手工契约。

验收门槛

目标模块表注释和字段中文注释覆盖率均为 100%。
模块 SQL、统一部署 SQL和数据库实值一致。
空库执行、存量升级和重复执行均通过。
注释迁移前后，除注释外的表结构零变化。
新增 SQL 在 CI 强制模式下通过。

5.3 KiB Raw Permalink Blame History Unescape Escape