feat(GOV-009): 支持固定开发库结构基线

2026-08-13 15:43:06 +08:00
parent c5a6e6a2c0
commit b3d8e29f52
6 changed files with 207 additions and 35 deletions
@@ -4,7 +4,16 @@

 ## 配置

-从 `deploy/env/development/` 中对应的 `*.env.example` 创建本机 `*.env.local`。真实文件被 Git 忽略，不得写入生产地址或真实密钥。
+从 `deploy/env/development/` 中对应的 `*.env.example` 创建本机 `*.env.local`。应用和 Schema 工具优先读取 `api.env.local`；真实文件被 Git 忽略，不得写入生产地址或真实密钥。当前固定开发 MySQL 可使用白名单地址 `112.192.20.11:3306`，Schema 工具仍只允许开发环境和 `a_share_analysis_dev`。
+
+开发环境配置文件约定：
+
+- `api.env.local`：API 的 Redis、MySQL 和可选 AI 配置。
+- `scheduler.env.local`：Scheduler 的 Redis、调度和可选 RocketMQ 配置。
+- `worker.env.local`：Worker 的 Redis、MySQL、行情、AI 和可选 RocketMQ 配置。
+- `web.env.local`：只包含 `VITE_` 前缀的前端变量。
+
+Schema 基线会在空开发库启用时生成 `captured_empty` 清单，记录 MySQL 5.7 元数据和零对象计数，不生成伪造的空 SQL；旧版本 format v1 基线保持可验证且不会被当前配置反向改写。

 ## Redis

@@ -130,12 +130,12 @@ count += 1;

 ### Schema 基线规范

- 每个新应用版本开发前必须封存上一已发布版本的开发库 Schema；只能读取 `APP_ENV=development`、`a_share_analysis_dev`，禁止连接、探测或读取生产数据库。
+- 每个新应用版本开发前必须封存上一已发布版本的开发库 Schema；只能读取 `APP_ENV=development`、`a_share_analysis_dev` 和 MySQL 5.7，主机仅允许回环地址或固定开发白名单 `112.192.20.11`，禁止连接、探测或读取生产数据库。配置优先读取 Git 忽略的 `deploy/env/development/api.env.local`。
 - 导出使用 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`；启用后的缺失基线必须阻断下一版本开发。
+- MySQL 未启用时只创建状态为 `not_applicable` 的清单，不得创建空 `schema.sql`；启用但无对象时创建 format v2 的 `captured_empty` 清单和零对象计数，不伪造空 SQL；启用后的缺失基线必须阻断下一版本开发。既有 format v1 基线必须继续只读验证，不得静默升级或重写。

 ## 12. 测试要求

@@ -17,7 +17,7 @@ released → superseded
 ## 3. 开发前流程

 1. 确认上一已发布语义化版本及标签提交，执行 `npm run schema:baseline` 和 `npm run schema:verify`。
-2. MySQL 已启用时只能从 `APP_ENV=development`、`a_share_analysis_dev` 和本机回环地址导出完整 Schema；MySQL 未启用时只保存 `not_applicable` 清单，不创建空 SQL。
+2. MySQL 已启用时只能从 `APP_ENV=development`、`a_share_analysis_dev`、MySQL 5.7、`utf8mb4_general_ci` 和固定开发主机白名单（回环地址或 `112.192.20.11`）导出 Schema；配置优先读取被 Git 忽略的 `deploy/env/development/api.env.local`，不存在时才读取无秘密模板。空开发库保存 format v2 的 `captured_empty` 清单，不创建空 SQL；MySQL 未启用时只保存 `not_applicable` 清单。
 3. 将 `database/schema-baselines/<上一发布版本>/` 作为独立中文提交推送 Gitea，核对本地和远程 SHA；既有版本目录禁止覆盖。只有 Git 已跟踪、工作区无改动、当前分支已推送且远程发布标签提交一致时，`governance:start` 才会继续。
 4. 分配功能编号和英文短名称。
 5. 建立 `docs/features/<编号>-<短名称>/`。
@@ -91,10 +91,10 @@ npm run governance:finish -- FEAT-MO-001 market-overview

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

 ## 8. 提交流程