97 lines
5.3 KiB
Markdown
97 lines
5.3 KiB
Markdown
# 数据库中文注释维护规范
|
||
|
||
## 目标与适用范围
|
||
|
||
本规范适用于 `baiyue-firstleg/` 各服务拥有的 MySQL 业务表。目标是让表和字段语义可以直接从数据库元数据理解，并通过自动检查防止新增无注释结构。
|
||
|
||
SQL 是数据库结构和注释的事实来源。数据字典应从 `information_schema` 生成，不维护 Excel、Markdown 字段清单等并行事实来源。
|
||
|
||
## 职责
|
||
|
||
- 数据库注释总控：维护本规范、统一术语、审计整体覆盖率、协调统一部署 SQL，并完成最终验收。
|
||
- 模块负责人：依据 Controller、DTO、Service、状态机和已确认需求解释本模块字段，维护模块 SQL。
|
||
- 业务审核人：确认状态、金额、时间、快照、审计和数据隔离字段的业务口径。
|
||
- 发布执行人：按发布规范执行已审核的幂等迁移；未经当前对话授权不得直接修改测试、预发布或生产数据库。
|
||
|
||
## 必须遵守的规则
|
||
|
||
1. 每张业务表和每个业务字段都必须有非空中文注释。
|
||
2. 英文缩写和枚举值可以保留，但注释必须包含中文业务含义。
|
||
3. 模块 `src/main/resources/db/`、统一部署 SQL 和实际数据库的注释必须一致。
|
||
4. 同一张表在基线与迁移脚本中重复定义时，每个可执行定义都必须有完整注释。
|
||
5. 注释变更不得改变字段类型、长度、精度、字符集、默认值、可空性、索引或约束。
|
||
6. `CREATE TABLE IF NOT EXISTS` 不会更新存量表注释；存量环境必须使用可重复执行的兼容迁移。
|
||
7. 注释不得写密钥、令牌、客户真实数据、环境地址或其他敏感值。
|
||
|
||
## 中文口径
|
||
|
||
| 字段类型 | 注释要求 | 示例 |
|
||
|---|---|---|
|
||
| `tenant_id` | 客户数据统一说明客户与隔离语义；公共数据明确平台作用域 | `客户ID和数据隔离键`；`平台公共数据作用域，固定为0` |
|
||
| 状态 | 列出允许值及每个值的中文含义 | `状态：DRAFT草稿、ISSUED已出账、PAID已收清` |
|
||
| 金额 | 说明金额口径、币种来源，必要时说明含税口径 | `账单含税总金额；币种由currency_code指定` |
|
||
| 时间 | 说明事件语义，不只写“时间” | `财务确认实际收款时间` |
|
||
| JSON | 说明结构、元素类型、来源及敏感性 | `File服务文件ID字符串数组` |
|
||
| 快照 | 说明来源和是否随源数据回写 | `创建账单时的客户名称快照；客户档案变化不回写` |
|
||
| 布尔值 | 明确 `0` 和 `1` 的含义 | `尾差归集标记：0否、1是` |
|
||
| ID | 说明关联对象和逻辑属性 | `Firstleg入库单逻辑ID，不建立跨库外键` |
|
||
| 版本 | 说明版本用途 | `乐观锁版本号，每次更新递增` |
|
||
| 审计 | 区分业务操作人、系统创建人和链路标识 | `执行本次业务操作的平台用户ID` |
|
||
|
||
不要把 `tenant_id` 用户可见地解释为“租户”。当前产品只有“平台、客户”两级，后端兼容字段不能扩展产品层级。
|
||
|
||
## 变更流程
|
||
|
||
1. 盘点模块 SQL 中缺失、空白或纯英文注释。
|
||
2. 根据需求确认文档和真实代码确认字段语义；不凭字段名猜测高风险业务口径。
|
||
3. 先更新模块 SQL，再由总控同步统一部署 SQL。
|
||
4. 为存量环境编写幂等注释迁移。MySQL `MODIFY COLUMN` 必须完整复述原类型、默认值、可空性及其他属性。
|
||
5. 对比迁移前后 `information_schema.columns`，除 `column_comment` 外的结构签名必须完全一致。
|
||
6. 运行静态审计、模块测试、统一 SQL 空库与重复执行验证。
|
||
7. 从实际数据库元数据生成数据字典和覆盖率报告。
|
||
|
||
## 自动审计
|
||
|
||
在 `baiyue-firstleg` 根目录执行：
|
||
|
||
```powershell
|
||
.\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 中启用强制门禁，禁止覆盖率回退。
|
||
|
||
## 数据库实值验收
|
||
|
||
部署后使用只读元数据查询验收：
|
||
|
||
```sql
|
||
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 强制模式下通过。
|