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
@@ -29,6 +29,7 @@ database/schema-baselines/v0.0.5/
 - 只允许读取开发环境数据库。
 - 加载开发专用本地配置，要求 `APP_ENV=development`。
 - 数据库名固定为 `a_share_analysis_dev`；名称不匹配立即终止。
+- 启用真实导出时主机必须为 `127.0.0.1`、`localhost` 或 `::1`；远程开发库必须先通过运维建立本地 SSH 隧道，脚本不接受任意远程目标。
 - 禁止通过命令参数覆盖环境类型、数据库名或传入任意 env 文件路径。
 - 禁止连接、读取、探测或导出生产数据库；生产备份属于独立运维流程，不进入开发门禁。
 - 推荐使用只拥有开发库结构读取和例程查看权限的专用账号，不授予生产访问能力。
@@ -45,7 +46,7 @@ database/schema-baselines/v0.0.5/
 - 存储过程和函数。
 - Event Scheduler 事件。

-导出命令必须使用 `--no-data --routines --triggers --events`，并使用符合 MySQL 5.7 的选项。账号凭据通过开发 env 或受控客户端配置提供，禁止出现在命令参数、日志或清单中。
+导出命令必须使用 `--no-data --routines --triggers --events`，并使用符合 MySQL 5.7 的选项。执行元数据查询的 `mysql` 客户端和执行导出的 `mysqldump` 客户端必须分别验证为 5.7.x。账号凭据通过开发 env 或受控客户端配置提供，禁止出现在命令参数、日志或清单中。

 ## 规范化

@@ -91,7 +92,7 @@ database/schema-baselines/v0.0.5/
 - SQL 包含 `DEFINER`、不稳定导出注释、当前 AUTO_INCREMENT 值或疑似凭据。
 - 校验值不一致、目标版本目录已存在且内容不同，或 Git 工作区存在无法解释的 Schema 改动。

-禁止覆盖既有版本基线。需要修正时新增带原因的治理记录和修复提交，不静默重写已发布事实。
+禁止覆盖既有版本基线。需要修正时新增带原因的治理记录和修复提交，不静默重写已发布事实。`schema:verify` 是本地内容校验；`governance:start` 还要求基线文件已被 Git 跟踪、工作区无改动、当前分支已推送以及远程发布标签仍指向清单提交。

 ## 首次启用与未启用状态

@@ -0,0 +1,52 @@
+# GitNexus 开发后基线
+
+## GitNexus 状态
+
+```text
+Repository: /Users/citrons/Documents/Codex/2026-08-12/wo-x/a-share-analysis
+Indexed: 8/13/2026, 12:44:53 PM
+Indexed commit: 2c502eb
+Current commit: 2c502eb
+Status: ✅ up-to-date
+```
+
+## Git 已跟踪变更摘要
+
+```text
+AGENTS.md | 2 +-
+ 1 file changed, 1 insertion(+), 1 deletion(-)
+```
+
+## Git 工作区摘要
+
+```text
+MM AGENTS.md
+M  CHANGELOG.md
+M  README.md
+M  VERSION
+M  docs/features/GOV-007-development-schema-baseline/design.md
+A  docs/features/GOV-007-development-schema-baseline/gitnexus/comparison.md
+A  docs/features/GOV-007-development-schema-baseline/gitnexus/detected-changes.md
+A  docs/features/GOV-007-development-schema-baseline/gitnexus/impact-plan.md
+A  docs/features/GOV-007-development-schema-baseline/implementation-plan.md
+A  docs/features/GOV-007-development-schema-baseline/manifest.yaml
+A  docs/features/GOV-007-development-schema-baseline/prd.md
+A  docs/features/GOV-007-development-schema-baseline/qa/test-results.md
+A  docs/features/GOV-007-development-schema-baseline/qa/visual-qa.md
+A  docs/features/GOV-007-development-schema-baseline/release-notes.md
+A  docs/features/GOV-007-development-schema-baseline/requirements.md
+A  docs/features/GOV-007-development-schema-baseline/review/code-review.md
+A  docs/features/GOV-007-development-schema-baseline/review/standards-review.md
+A  docs/features/GOV-007-development-schema-baseline/rollback.md
+A  docs/features/GOV-007-development-schema-baseline/test-plan.md
+M  docs/governance/code-development-standards.md
+M  docs/governance/development-workflow.md
+M  docs/index.md
+M  package.json
+A  tools/database/fixtures/mysql57-schema-expected.sql
+A  tools/database/fixtures/mysql57-schema-input.sql
+A  tools/database/schema-baseline.mjs
+A  tools/database/schema-baseline.test.mjs
+M  tools/governance/finish.mjs
+M  tools/governance/start.mjs
+```
@@ -0,0 +1,17 @@
+# GitNexus 前后对比
+
+## 开发前
+
+- 基线提交：`e552b979b61342b9e3a47d463f0b9a821b0ad95d`
+- 索引：641 节点、671 关系、0 流程。
+- 影响：现有治理档案函数总体 LOW，无数据库 Schema 执行流。
+
+## 开发后
+
+- 基线提交：`2c502ebbec25e45ac2980c08ed288ace194b7a04`（先独立提交并推送 v0.0.5 N/A 基线）。
+- 索引：837 节点、997 关系、17 流程。
+- 暂存区：23 文件、179 符号、17 条流程，risk=critical。
+
+## 结论
+
+新增关系和流程全部来自 GOV-007 Schema 安全门禁及其测试，没有引入市场业务、HTTP、RabbitMQ 或页面流程。风险从 LOW 提升到 critical 是因为新的 `governance:start` 前置门禁属于关键开发路径且整个模块首次加入；对应流程已用失败测试、修复测试、远程实测和独立 Review 覆盖。
@@ -0,0 +1,23 @@
+# GitNexus 暂存区变更检测
+
+- 检测日期：2026-08-13
+- 检测范围：staged
+- 变更文件：23
+- 变更符号：179
+- 受影响流程：17
+- GitNexus 风险：critical（已按关键门禁完成专项验证）
+
+## 受影响流程
+
+变更集中在数据库 Schema 治理模块：
+
+- Schema 生成、规范化与敏感/数据写入扫描。
+- 清单、SHA-256 与目录文件集合验证。
+- MySQL 5.7 双客户端、服务端和字符规则验证。
+- 当前发布版本本地校验。
+- 已提交、已推送、远程分支和远程标签严格校验。
+- CLI 生成/验证和 `governance:start` 入口。
+
+## 风险解释
+
+GitNexus 以“新增模块的全部 17 条流程均在本次变更中”为依据给出 critical，而非发现了业务市场分析、生产数据库或跨服务调用回归。本功能本身是开发前关键门禁，因此该风险等级按关键路径处理：执行 20 项 Schema 行为测试、既有 13 项治理回归测试、真实 Gitea `ls-remote` 校验、三轮独立代码 Review 和完成门禁。任何 Review Important 项未关闭前不发布。
@@ -0,0 +1,32 @@
+# GitNexus 开发前影响分析
+
+- 分析日期：2026-08-13
+- 基线提交：`e552b979b61342b9e3a47d463f0b9a821b0ad95d`
+- 索引状态：up-to-date
+
+## 查询范围
+
+围绕 `governance start development gate feature record database schema baseline` 查询现有治理入口。GitNexus 未识别出业务执行流，相关定义集中在：
+
+- `tools/governance/start.mjs`
+- `tools/governance/finish.mjs`
+- `tools/governance/feature-record.mjs`
+- `tools/governance/feature-record.test.mjs`
+- `package.json`
+- 治理规范和 GOV-007 设计档案
+
+## 符号影响
+
+- `getFeatureDirectory`：LOW；3 个直接依赖，分别是 start、finish 和治理测试；0 个执行流、0 个跨模块影响。
+- `validateFeatureId`：LOW；GitNexus 没有发现上游执行流，实际文本导入由 start、finish 和测试覆盖。
+- `getRequiredFeatureFiles`：LOW；没有识别到执行流，完成门禁由现有自动化测试保护。
+
+## 实施边界
+
+本功能不修改上述已有公共函数语义。Schema 逻辑新增为独立模块，只让 `start.mjs` 调用一个只读的“当前已发布版本基线有效”入口。生成、规范化和写入由独立命令负责，因此不会让一般功能档案解析承担数据库职责。
+
+## 风险结论
+
+总体风险：LOW。
+
+没有 HIGH 或 CRITICAL 结果，不需要额外中止确认。主要回归面是治理开始命令可能因缺少上一版本基线被有意阻断；通过 N/A 与真实 Schema 两类测试、既有治理回归测试和命令级验证覆盖。
@@ -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 只消费这些接口，没有命名漂移。
+- 计划不包含待定项；真实数据库路径可实现但本次只以依赖注入和固定样本验证，符合禁止连接数据库的范围。
@@ -0,0 +1,18 @@
+id: GOV-007
+name: 开发数据库 Schema 基线与版本门禁
+slug: development-schema-baseline
+status: released
+owner: project
+created_at: 2026-08-13
+prd: prd.md
+requirements: requirements.md
+design: design.md
+implementation_plan: implementation-plan.md
+test_plan: test-plan.md
+gitnexus_before: gitnexus/before.md
+gitnexus_after: gitnexus/after.md
+gitnexus_comparison: gitnexus/comparison.md
+code_review: review/code-review.md
+standards_review: review/standards-review.md
+implementation_commit: pending
+release: v0.0.6
@@ -0,0 +1,50 @@
+# 开发数据库 Schema 基线与版本门禁 PRD
+
+- 功能编号：GOV-007
+- PRD 版本：0.1
+- 状态：approved
+- 日期：2026-08-13
+
+## 问题
+
+数据库迁移文件只能表达预期变化，不能证明每个版本开始前开发数据库的实际结构，也无法发现手工改表、对象遗漏或环境误连。当前 MySQL 尚未启用，还需要一种不伪造空 Schema 的可审计状态。
+
+## 目标
+
+- 每个新应用版本开发前，封存上一已发布版本的开发库完整 Schema。
+- 将环境、数据库名、MySQL 版本、字符集、排序规则和对象范围设置为强制门禁。
+- 生成确定性、可校验、可版本控制且不含数据或凭据的产物。
+- MySQL 未启用时生成可验证的不适用记录。
+- 在 `governance:start` 前阻断缺失或失效的上一版本基线。
+
+## 用户流程
+
+1. 开发者确认上一已发布语义化版本。
+2. 执行 `npm run schema:baseline` 生成或幂等验证对应目录。
+3. 执行 `npm run schema:verify` 复核清单、版本、提交和校验值。
+4. 将基线用中文提交推送项目 Gitea。
+5. 执行 `governance:start` 开始下一版本功能。
+
+## 非目标
+
+- 不备份任何业务数据、用户数据或生产数据。
+- 不连接、探测、读取或验证生产数据库。
+- 不替代生产运维备份、数据库恢复演练或迁移框架。
+- 本版本不启动 MySQL，也不对真实数据库执行命令。
+
+## 风险
+
+- `DEFINER`、导出时间和当前自增值会造成不可移植或无意义差异。
+- 参数可覆盖 env 或数据库名会扩大到生产资源的误操作范围。
+- 空 SQL 或可篡改的 N/A 清单会让门禁形式化而不可信。
+- 既有版本目录被覆盖会破坏发布历史。
+
+## 验收标准
+
+- 开发库、MySQL 5.7 和字符规则不符合时全部阻断。
+- 导出参数明确只含结构并覆盖表、视图、触发器、例程和事件。
+- 规范化固定样本精确保留业务对象和列自增属性。
+- 真实基线三方 SHA-256 一致；N/A 基线只有清单。
+- 版本、标签提交、对象范围、状态和文件集合都能自动校验。
+- 既有不同内容禁止覆盖，命令行不能切换 production env 或数据库。
+- 治理流程、双 Review、GitNexus、中文提交和 Gitea 推送完成。
@@ -0,0 +1,24 @@
+# 测试结果
+
+- 日期：2026-08-13
+- 环境：本地开发仓库；未启动 MySQL，未连接任何数据库。
+
+## 最新结果
+
+- Schema 基线测试：20/20 passed。
+- 治理测试：5/5 passed。
+- MySQL 兼容基线：2/2 passed。
+- 环境与部署基线：6/6 passed。
+- `npm run schema:verify`：`v0.0.5 (not_applicable)` passed。
+- 严格 `governance:start` smoke：基线未提交时按预期阻断；独立提交并推送后通过。
+- `git ls-remote origin refs/heads/main` 与 `refs/tags/v0.0.5^{}`：远程 SHA 均按实时查询核对通过。
+- `git diff --check`：passed。
+- Node 语法检查：passed。
+
+## 测试先行留痕
+
+首次测试因模块不存在以 `ERR_MODULE_NOT_FOUND` 失败。实现期间失败测试先后捕获：MySQL 密码条件必填、标签提交核对、清单篡改、标准 5.7 视图 DEFINER、例程字符串误改、顶层/例程 DML 区分、双客户端版本、未跟踪基线、陈旧 tracking ref、普通与可执行注释 DML 绕过。每项均在实现修复后转绿。
+
+## 未执行项
+
+当前 MySQL 功能开关为关闭，本功能范围明确禁止连接数据库，因此未执行真实 MySQL 5.7 导出。首次启用 MySQL 的版本必须在固定开发库补做真实集成验证。
@@ -0,0 +1,5 @@
+# 视觉 QA
+
+本功能没有页面、组件、样式、图表或浏览器交互变化，视觉 QA 不适用。
+
+结论：not_applicable
@@ -0,0 +1,11 @@
+# 发布说明
+
+## v0.0.6
+
+- 实现开发数据库 Schema 基线生成与只读验证命令。
+- 固定 MySQL 5.7、`a_share_analysis_dev`、`utf8mb4` 和 `utf8mb4_general_ci` 安全边界。
+- 增加完整对象导出参数、确定性 SQL 规范化、SHA-256 三方校验和禁止覆盖机制。
+- 为 MySQL 未启用状态建立不伪造空 SQL 的 `not_applicable` 基线。
+- 将上一发布版本 Schema 基线验证接入开发前和开发后治理门禁。
+- `governance:start` 仅接受已提交、已推送且远程标签一致的基线；真实导出限制在本机回环地址并分别校验 `mysql` 与 `mysqldump` 客户端版本。
+- 实现提交将在发布封存时回填。
@@ -0,0 +1,33 @@
+# 工程需求
+
+## 安全配置
+
+- `APP_ENV` 必须为 `development`，`MYSQL_DATABASE` 必须为 `a_share_analysis_dev`。
+- 字符集固定 `utf8mb4`，排序规则固定 `utf8mb4_general_ci`。
+- 启用 MySQL 后 host、port、username、password 均为必填；密码只通过子进程环境传递。
+- 启用 MySQL 时主机只能是本机回环地址；远程开发库必须先由运维建立本地 SSH 隧道，脚本不接受任意远程目标。
+- 命令行不接受 env 文件、环境类型、数据库名或其他覆盖参数。
+
+## 数据库与导出
+
+- 客户端和服务端版本必须匹配 MySQL 5.7.x。
+- 执行元数据查询的 `mysql` 客户端和执行导出的 `mysqldump` 客户端都必须分别验证为 5.7.x。
+- `mysqldump` 使用 `--no-data --routines --triggers --events`，不得输出 INSERT 或 REPLACE。
+- 完整对象范围为表、索引、外键、视图、触发器、存储过程、函数和事件。
+- 规范化删除不稳定注释、环境 `DEFINER` 和表选项当前自增值，保留列自增属性。
+
+## 产物与校验
+
+- 目录固定为 `database/schema-baselines/<已发布版本>/`。
+- 真实基线包含 `schema.sql`、`manifest.yaml`、`checksum.sha256`。
+- `manifest.yaml` 使用 JSON 兼容 YAML 的结构化格式，可由标准 JSON 解析器读取。
+- 清单记录版本、标签提交、来源环境、库名、版本、字符规则、对象范围、生成器和 SHA-256。
+- 目录采用同父目录临时写入后原子改名；既有目录只允许逐字节相同的幂等重跑。
+- MySQL 未启用时只生成 `manifest.yaml`，状态为 `not_applicable`，原因是 `mysql_disabled`，所有对象均为未捕获。
+
+## 流程
+
+- `governance:start` 在写入功能档案或刷新 GitNexus 前只读验证上一发布版本基线。
+- `governance:start` 还要求基线文件已被 Git 跟踪、无未提交改动、当前分支已推送且远程发布标签提交一致；`schema:verify` 只负责本地内容校验。
+- `governance:finish` 运行全部既有治理测试、Schema 测试和基线验证。
+- 本版本实际产物为 `v0.0.5` 的 N/A 清单，不连接任何数据库。
@@ -0,0 +1,24 @@
+# 代码 Review
+
+## 第一轮
+
+结论：changes_required。发现 5 个 Important 和 2 个 Minor：未提交基线可绕过门禁、远程生产主机可被误连、标准 MySQL 5.7 视图 DEFINER 不兼容、顶层 DML 扫描绕过/例程误拒、未校验 mysql 客户端、N/A 清单字段不严和缺少严格门禁测试。
+
+处置：全部补失败测试并修复。增加回环主机、双客户端、结构化清单、Git 跟踪与远程同步验证。
+
+## 第二轮
+
+结论：changes_required。发现普通/版本注释可绕过顶层 DML 扫描，远程分支校验依赖可能陈旧的 tracking ref。
+
+处置：按真实分隔符解析顶层语句，剥离前置普通注释但扫描 MySQL 可执行注释；远程分支改为实时 `git ls-remote origin refs/heads/<branch>`，并增加回归测试。
+
+## 最终复审
+
+- 普通注释、版本 SET 注释、MySQL 可执行注释中的顶层 INSERT/REPLACE 均被拒绝。
+- 例程内合法 DML 保留，标准 MySQL 5.7 视图 DEFINER 输出可规范化。
+- 远程分支使用实时 `git ls-remote`，远程标签提交与清单提交核对。
+- 20 项 Schema 测试、治理/数据库/环境回归测试均通过。
+
+问题处置：第一、二轮所有 Critical/Important/Minor 问题均已关闭并有回归测试；未保留延期问题。
+
+最终结论：passed
@@ -0,0 +1,20 @@
+# 开发规范符合性 Review
+
+## 检查范围
+
+- PRD、需求、确认设计、实施计划、测试计划、GitNexus 前后报告齐全。
+- 关键安全边界、规范化取舍、原子写入和远程门禁有中文原因注释。
+- 主要业务流程集中在一个可连续阅读的模块，没有过度拆分。
+- 测试遵循先失败后实现，固定样本和期望值独立维护。
+- MySQL 5.7、`utf8mb4`、`utf8mb4_general_ci` 和开发库限制符合规范。
+- 未写入密码、Token、真实 env、生产地址或生产数据。
+- `v0.0.5` N/A 基线已作为独立中文提交推送 Gitea。
+- 视觉变化不适用，已记录原因。
+
+## 复审结果
+
+- 最终代码复审已通过，所有 Important 问题均关闭并有测试证据。
+- `governance:finish` 将在发布前重新执行全部治理、Schema 和 GitNexus 门禁。
+- 实现提交、封存提交和 `v0.0.6` 标签推送属于本档案的发布步骤，完成后回填 SHA。
+
+最终结论：passed
@@ -0,0 +1,12 @@
+# 回退说明
+
+本功能没有连接数据库、执行迁移或修改任何开发/生产数据。回退应用代码时可以恢复上一提交中的治理脚本和文档，但不得删除或改写已经随版本发布的 `database/schema-baselines/` 历史事实。
+
+若工具实现存在缺陷，使用新的中文修复提交：
+
+1. 保留原版本基线目录和 Git 历史。
+2. 在新的治理档案中记录错误原因、影响范围和修复策略。
+3. 对尚未发布的错误产物可在审查后修正；已发布产物通过追加更正记录处理，不移动共享标签。
+4. 首次启用 MySQL 后，任何修复都只允许读取开发库，生产数据库仍属于禁止范围。
+
+N/A 清单没有 Schema 或数据可恢复。`v0.0.5` 目录证明当时 MySQL 功能开关关闭，不能在未来启用 MySQL 后追溯改写为真实 Schema。
@@ -0,0 +1,32 @@
+# 测试计划
+
+## 测试先行证据
+
+- 首次执行 `node --test tools/database/schema-baseline.test.mjs` 因生产模块不存在而失败，错误为 `ERR_MODULE_NOT_FOUND`。
+- 首轮实现后固定样本和清单嵌套字段测试暴露规范化与解析缺口，修正后转绿。
+- 安全自审再以失败测试发现密码未设为条件必填、标签提交未核对、真实清单版本可篡改和 N/A 对象范围可伪造，均已实现对应阻断。
+
+## 自动化范围
+
+- 配置：环境、库名、字符集、排序规则、启用后的必填凭据。
+- 版本：MySQL 客户端、服务端和发布标签提交。
+- 命令：完整结构参数、密码不进参数、额外参数拒绝。
+- SQL：时间注释、`DEFINER`、表级自增值、列自增属性和五类对象。
+- 产物：SHA-256、精确文件集合、禁止覆盖、篡改检测、空 SQL 拒绝。
+- N/A：零数据库调用、只有清单、明确关闭版本和对象范围。
+- 回归：治理测试、MySQL 基线测试、环境基线测试、Schema 验证。
+- 严格发布门禁：未跟踪基线、未提交改动、未推送分支或远程标签不一致均阻断；本地 `schema:verify` 与发布前 `governance:start` 的职责分别验证。
+
+## 最终命令
+
+```bash
+npm run test:governance
+npm run test:mysql-baseline
+npm run test:environment-baseline
+npm run test:schema-baseline
+npm run schema:verify
+npm run governance:finish -- GOV-007 development-schema-baseline
+git diff --check
+```
+
+本功能无 Web 页面、CSS 或图表变化，视觉 QA 记录为不适用。
@@ -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。
 - 发布产物必须对应确定提交，不从浮动分支临时构建。
@@ -21,6 +21,11 @@
 - [Docker Compose 生产部署](deployment/docker-compose-production.md)
 - [Ubuntu 源码生产部署](deployment/ubuntu-source-production.md)

+## 数据库版本基线
+
+- [Schema 基线目录](../database/schema-baselines/)
+- [GOV-007 设计规格](features/GOV-007-development-schema-baseline/design.md)
+
 ## GitNexus

 - [仓库基线](gitnexus/repository-baseline.md)
@@ -36,5 +41,6 @@
 - [GOV-004：提交后强制推送 Gitea](features/GOV-004-mandatory-gitea-push/manifest.yaml)
 - [GOV-005：MySQL 5.7 字符集与兼容性基线](features/GOV-005-mysql57-charset-baseline/manifest.yaml)
 - [GOV-006：开发、生产环境与双部署方式](features/GOV-006-environment-deployment-baseline/manifest.yaml)
+- [GOV-007：开发数据库 Schema 基线与版本门禁](features/GOV-007-development-schema-baseline/manifest.yaml)

 功能档案是需求、设计、代码、测试、版本和回退之间的唯一正式关联入口。