feat(GOV-007): 建立开发库 Schema 基线门禁
This commit is contained in:
@@ -0,0 +1,124 @@
|
||||
# GOV-007 开发数据库 Schema 基线与版本门禁实施计划
|
||||
|
||||
> **执行要求：** 按测试驱动方式逐项实施；每个行为先观察失败，再写最小实现。实施期间不得连接、探测或读取任何数据库，真实导出入口仅通过固定样本和依赖注入验证。
|
||||
|
||||
**目标：** 建立只允许读取固定开发库、可确定性规范化和校验完整 MySQL 5.7 Schema，并在下一版本开发前强制验证上一已发布版本基线的治理门禁。
|
||||
|
||||
**架构：** `tools/database/schema-baseline.mjs` 集中维护安全配置、命令构造、SQL 规范化、产物生成及校验，避免将一条连续的安全流程过度拆分。`governance:start` 只调用“当前已发布版本基线是否存在且有效”的纯门禁，不负责静默生成或覆盖产物；生成基线必须先由独立命令完成、提交并推送。
|
||||
|
||||
**技术栈：** Node.js 22 LTS、Node 内置测试运行器、MySQL 5.7 `mysql`/`mysqldump` 客户端、SHA-256、GitNexus、Git/Gitea。
|
||||
|
||||
## 全局约束
|
||||
|
||||
- 数据来源只能是 `APP_ENV=development`、数据库 `a_share_analysis_dev`。
|
||||
- MySQL 客户端与服务端只能是 5.7.x，字符集固定 `utf8mb4`，排序规则固定 `utf8mb4_general_ci`。
|
||||
- 导出必须包含 `--no-data --routines --triggers --events`，密码不得出现在参数、日志、SQL 或清单中。
|
||||
- 不接受环境类型、数据库名或 env 路径的命令行覆盖。
|
||||
- 当前 MySQL 未启用，不运行真实数据库命令，只生成可验证的 `not_applicable` 清单，且不创建空 `schema.sql`。
|
||||
- 已存在版本目录不得静默覆盖；真实 Schema 只含结构，不含任何数据。
|
||||
- 修改关键符号前执行 GitNexus impact，提交前执行 GitNexus detect-changes。
|
||||
|
||||
---
|
||||
|
||||
### 任务 1：锁定安全边界和可观察契约
|
||||
|
||||
**文件：**
|
||||
|
||||
- 新建：`tools/database/schema-baseline.test.mjs`
|
||||
- 新建：`tools/database/fixtures/mysql57-schema-input.sql`
|
||||
- 新建：`tools/database/fixtures/mysql57-schema-expected.sql`
|
||||
- 新建：`docs/features/GOV-007-development-schema-baseline/test-plan.md`
|
||||
|
||||
**接口：**
|
||||
|
||||
- 消费：设计规格中固定的环境、版本、Schema 范围和禁止覆盖规则。
|
||||
- 产出：后续实现必须满足的公开函数行为和固定 SQL 输入/输出。
|
||||
|
||||
- [ ] 编写配置测试，分别证明非 `development`、非 `a_share_analysis_dev`、非 MySQL 5.7、错误字符集和错误排序规则被拒绝。
|
||||
- [ ] 运行 `node --test tools/database/schema-baseline.test.mjs`，确认因实现模块不存在而失败。
|
||||
- [ ] 编写命令构造测试，手工断言参数包含 `--no-data`、`--routines`、`--triggers`、`--events`，且密码字符串不出现在参数中。
|
||||
- [ ] 编写固定 SQL 样本测试，手工断言时间注释、`DEFINER` 和表级当前自增值被删除，列级 `AUTO_INCREMENT` 以及表、视图、触发器、例程和事件定义完整保留。
|
||||
- [ ] 编写产物测试，证明清单和校验文件的 SHA-256 与 SQL 一致、不同内容的既有目录被拒绝、未启用 MySQL 时只有 `manifest.yaml` 而没有 `schema.sql`。
|
||||
|
||||
### 任务 2：实现纯函数和文件产物
|
||||
|
||||
**文件：**
|
||||
|
||||
- 新建：`tools/database/schema-baseline.mjs`
|
||||
- 修改：`package.json`
|
||||
|
||||
**接口：**
|
||||
|
||||
- 产出：`assertSafeDevelopmentConfiguration(config)`、`assertMysql57Metadata(metadata)`、`buildMysqldumpArguments(config)`、`normalizeSchemaSql(sql)`、`buildCapturedArtifacts(metadata, sql)`、`buildNotApplicableArtifacts(metadata)`、`persistBaselineArtifacts(target, artifacts)`、`verifyBaselineDirectory(target, expectedRelease)`。
|
||||
|
||||
- [ ] 实现最小配置与元数据校验，使安全边界测试通过。
|
||||
- [ ] 实现参数数组构造；连接密码只允许由子进程环境传递，不进入参数。
|
||||
- [ ] 实现确定性 SQL 规范化和敏感内容扫描，使固定样本逐字节匹配期望文件。
|
||||
- [ ] 实现 SHA-256、平面可审计清单、标准 checksum 文件和目录校验。
|
||||
- [ ] 采用同目录临时目录加原子改名写入；目标已存在时仅允许逐字节相同内容复用，其他情况报错。
|
||||
- [ ] 运行 Schema 测试，确认所有测试转绿；再运行既有治理、MySQL 与环境基线测试，确认没有回归。
|
||||
|
||||
### 任务 3：实现真实入口但不连接数据库
|
||||
|
||||
**文件：**
|
||||
|
||||
- 修改：`tools/database/schema-baseline.mjs`
|
||||
- 修改：`package.json`
|
||||
- 修改：`deploy/env/development/api.env.example`（仅在契约字段缺失时修改）
|
||||
|
||||
**接口：**
|
||||
|
||||
- 消费：固定路径 `deploy/env/development/api.env`；文件不存在且仓库模板明确 `MYSQL_ENABLED=false` 时允许生成不适用记录。
|
||||
- 产出：`npm run schema:baseline` 与 `npm run schema:verify`，版本自动从最近语义化版本标签解析。
|
||||
|
||||
- [ ] 测试命令行拒绝额外参数，证明不能传入 production env、数据库名或任意 env 路径。
|
||||
- [ ] 测试未启用 MySQL 的入口不会调用数据库执行器，并为最近发布标签创建可验证不适用记录。
|
||||
- [ ] 测试启用分支只构造固定 `mysql`/`mysqldump` 参数，并在客户端/服务端版本或数据库字符规则不符时阻断。
|
||||
- [ ] 实现固定配置加载、最近标签与标签提交解析、回环主机检查、mysql/mysqldump 双客户端和服务端元数据检查、真实导出执行路径；本次验证不调用该路径。
|
||||
- [ ] 运行 `npm run schema:baseline` 为 `v0.0.5` 生成 `not_applicable` 清单，并运行 `npm run schema:verify` 验证；确认不存在 `schema.sql`。
|
||||
|
||||
### 任务 4：接入版本开发前门禁与治理规范
|
||||
|
||||
**文件：**
|
||||
|
||||
- 修改：`tools/governance/start.mjs`
|
||||
- 修改：`tools/governance/feature-record.test.mjs` 或新增对应集成测试。
|
||||
- 修改：`AGENTS.md`
|
||||
- 修改：`docs/governance/development-workflow.md`
|
||||
- 修改：`docs/governance/code-development-standards.md`
|
||||
- 修改：`README.md`
|
||||
- 修改：`docs/index.md`
|
||||
|
||||
**接口：**
|
||||
|
||||
- 消费：`assertCurrentReleasedBaselinePublished(repositoryRoot)`。
|
||||
- 产出：治理开始命令只有在上一已发布版本 Schema 基线有效时才继续 GitNexus 开发前流程。
|
||||
|
||||
- [ ] 先写失败测试：基线缺失或失效时 `governance:start` 的前置检查拒绝继续，有效 N/A 或真实基线时允许继续。
|
||||
- [ ] 在 `start.mjs` 刷新 GitNexus 之前调用严格发布验证，检查 Git 跟踪、工作区、origin 分支和远程标签；不自动生成、不覆盖基线。
|
||||
- [ ] 文档明确顺序为“生成并验证基线 → 中文提交 → 推送 Gitea → 治理开始”，以及首次启用 MySQL 时必须从真实开发库导出。
|
||||
- [ ] 代码规范增加 Schema 仅结构、MySQL 5.7 完整对象范围、确定性规范化、禁止生产数据库和禁止直接改共享表的规则。
|
||||
|
||||
### 任务 5：验证、Review 与发布
|
||||
|
||||
**文件：**
|
||||
|
||||
- 新建或更新：GOV-007 完整功能档案。
|
||||
- 修改：`VERSION`、`CHANGELOG.md`、`docs/index.md`。
|
||||
|
||||
**接口：**
|
||||
|
||||
- 产出：可追溯的 `v0.0.6` 治理版本。
|
||||
|
||||
- [ ] 执行 Schema、治理、MySQL、环境测试，执行 `git diff --check`、敏感信息扫描和适用构建检查。
|
||||
- [ ] 执行 `npx gitnexus analyze` 与变更检测，保存开发前后差异和风险结论。
|
||||
- [ ] 完成代码 Review 与开发规范符合性 Review；两份报告必须包含独立一行 `最终结论：passed`。
|
||||
- [ ] 执行 `npm run governance:finish -- GOV-007 development-schema-baseline` 并保存证据。
|
||||
- [ ] 使用中文 Conventional Commit 提交并立即推送 `origin/main`，回填实现提交和远程 SHA。
|
||||
- [ ] 封存最终验证结果，提交并推送；创建带注释标签 `v0.0.6` 并只精确推送该标签。
|
||||
|
||||
## 计划自审
|
||||
|
||||
- 设计中的安全配置、完整对象范围、规范化、清单校验、禁止覆盖、未启用路径、治理门禁、双 Review 和发布要求均有对应任务。
|
||||
- 所有实现接口在任务 2 明确定义，任务 3、4 只消费这些接口，没有命名漂移。
|
||||
- 计划不包含待定项；真实数据库路径可实现但本次只以依赖注入和固定样本验证，符合禁止连接数据库的范围。
|
||||
Reference in New Issue
Block a user