feat(GOV-007): 建立开发库 Schema 基线门禁

2026-08-13 12:50:37 +08:00
parent 2c502ebbec
commit da056681b6
30 changed files with 1734 additions and 18 deletions
@@ -123,6 +123,15 @@ count += 1;
 - 每份迁移脚本必须能够从上一版本基线在 MySQL 5.7 正向执行；禁止用直接修改共享数据库表代替迁移脚本。
 - 代码 Review 必须检查服务端版本、字符集、排序规则、SQL/迁移兼容性、索引长度和字符串比较语义；任一不符合项按 Important 处理并阻断发布。

+### Schema 基线规范
+
+- 每个新应用版本开发前必须封存上一已发布版本的开发库 Schema；只能读取 `APP_ENV=development`、`a_share_analysis_dev`，禁止连接、探测或读取生产数据库。
+- 导出使用 MySQL 5.7 `mysqldump` 的 `--no-data --routines --triggers --events`，完整保留表、索引、外键、视图、触发器、存储过程、函数和事件，不得包含任何表数据。
+- 规范化必须确定性删除导出时间、环境 `DEFINER` 和表选项中的当前 `AUTO_INCREMENT=<值>`，同时保留列定义的 `AUTO_INCREMENT` 属性和业务 SQL。
+- 账号密码只能通过受控子进程环境传递，不得进入参数、日志、SQL、清单或 checksum 文件。
+- `manifest.yaml`、`checksum.sha256` 和 `schema.sql` 的 SHA-256 必须一致；既有版本目录只允许内容完全一致的幂等验证，不允许覆盖。
+- MySQL 未启用时只创建状态为 `not_applicable` 的清单，不得创建空 `schema.sql`；启用后的缺失基线必须阻断下一版本开发。
+
 ## 12. 测试要求

 - 功能和缺陷修复遵循测试先行：先看到测试因缺少行为而失败，再实现最小代码。
@@ -16,22 +16,26 @@ released → superseded

 ## 3. 开发前流程

-1. 分配功能编号和英文短名称。
-2. 建立 `docs/features/<编号>-<短名称>/`。
-3. 编写 `prd.md`，明确用户问题、目标、范围、非目标、用户流程、指标、风险和验收标准。
-4. PRD 审核通过后，将产品需求转换为可测试的工程需求。
-5. 比较可选方案，记录设计与关键决策。
-6. 更新 API、事件和数据结构契约。
-7. 编写测试计划和实施计划。
-8. 明确功能需要的环境变量、功能开关和部署影响；同步更新开发/生产模板，禁止只修改本机真实 env。
-9. 确保 Git 工作区基线可识别，执行：
+1. 确认上一已发布语义化版本及标签提交，执行 `npm run schema:baseline` 和 `npm run schema:verify`。
+2. MySQL 已启用时只能从 `APP_ENV=development`、`a_share_analysis_dev` 和本机回环地址导出完整 Schema；MySQL 未启用时只保存 `not_applicable` 清单，不创建空 SQL。
+3. 将 `database/schema-baselines/<上一发布版本>/` 作为独立中文提交推送 Gitea，核对本地和远程 SHA；既有版本目录禁止覆盖。只有 Git 已跟踪、工作区无改动、当前分支已推送且远程发布标签提交一致时，`governance:start` 才会继续。
+4. 分配功能编号和英文短名称。
+5. 建立 `docs/features/<编号>-<短名称>/`。
+6. 编写 `prd.md`，明确用户问题、目标、范围、非目标、用户流程、指标、风险和验收标准。
+7. PRD 审核通过后，将产品需求转换为可测试的工程需求。
+8. 比较可选方案，记录设计与关键决策。
+9. 更新 API、事件和数据结构契约。
+10. 编写测试计划和实施计划。
+11. 明确功能需要的环境变量、功能开关和部署影响；同步更新开发/生产模板，禁止只修改本机真实 env。
+12. 确保 Git 工作区基线可识别，执行：

 ```bash
 npm run governance:start -- FEAT-MO-001 market-overview
 ```

-10. 运行 GitNexus 查询、上下文和影响分析，将结果写入 `gitnexus/impact-plan.md`。
-11. 高风险或关键路径变化必须先向用户说明影响，再进入开发。
+13. `governance:start` 会只读复核上一发布版本 Schema 基线；缺失、失效或版本不一致时立即阻断，不会代为生成。
+14. 运行 GitNexus 查询、上下文和影响分析，将结果写入 `gitnexus/impact-plan.md`。
+15. 高风险或关键路径变化必须先向用户说明影响，再进入开发。

 开发前必须至少回答：修改什么、为什么修改、影响谁、如何验证、失败后如何回退。

@@ -81,8 +85,18 @@ npm run governance:finish -- FEAT-MO-001 market-overview
 - 中文提交已关联功能编号。
 - 当前分支和本次新建标签已推送到 `origin`，功能档案保存远程核对结果。
 - 配置契约变化已同步开发/生产模板和适用的 Compose、systemd、Nginx及部署文档。
+- 下一版本开发前所需的上一发布版本 Schema 基线已验证、独立提交并推送 Gitea。

-## 7. 提交流程
+## 7. 数据库 Schema 基线
+
+- 基线目录固定为 `database/schema-baselines/vX.Y.Z/`，版本是被备份的已发布版本。
+- 真实基线由 `schema.sql`、`manifest.yaml`、`checksum.sha256` 组成；范围包括表、索引、外键、视图、触发器、存储过程、函数和 Event Scheduler 事件，不含数据。
+- MySQL 未启用时目录只能包含 `manifest.yaml`，状态为 `not_applicable`、原因为 `mysql_disabled`。
+- `schema:baseline` 不接受 env 路径、环境类型或数据库名参数；配置路径固定在开发环境，生产配置和生产数据库不属于该命令的权限范围。
+- 修正已发布基线必须新增治理记录说明原因，禁止静默覆盖或重写历史目录。
+- 首次启用 MySQL 的版本必须通过迁移建立开发库，并在 MySQL 5.7 开发环境生成第一份真实 Schema 基线。
+
+## 8. 提交流程

 提交格式：

@@ -114,7 +128,7 @@ git push origin <本次标签名>

 禁止使用 `--force`、`--force-with-lease` 或 `--tags` 代替精确推送。推送失败时不得宣称任务完成；应记录不含凭据的错误摘要，排查后重试同一精确命令。

-## 8. 发布与回退
+## 9. 发布与回退

 - 使用语义化版本和带注释 Git Tag。
 - 发布产物必须对应确定提交，不从浮动分支临时构建。