docs(GOV-012): 确认纯 Node Schema 导出器设计

2026-08-18 00:46:03 +08:00
parent 3555b7c222
commit c605935403
10 changed files with 309 additions and 0 deletions
@@ -0,0 +1,68 @@
+# 纯 Node.js 开发库 Schema 导出器 PRD
+
+- 功能编号：GOV-012
+- PRD 版本：0.1
+- 状态：approved
+- 日期：2026-08-18
+
+## 背景与问题
+
+当前 `schema:baseline` 依赖本机 MySQL 5.7.x 的 `mysql` 和 `mysqldump` 可执行文件。开发机无法安装这些客户端时，命令在连接数据库前以 `spawnSync mysql ENOENT` 失败，导致上一发布版本无法形成 Schema 基线，后续 `governance:start` 和版本开发流程持续阻断。
+
+项目已经采用 Node.js 22.x、pnpm 和 `mysql2`，不应要求开发机额外安装 MySQL Server，也不应通过 Docker、远程 shell 或非版本化人工导出绕过治理门禁。
+
+## 产品目标
+
+- 使用纯 Node.js 和 `mysql2` 从固定开发库导出完整、确定性、可验证的 Schema。
+- 保持 `npm run schema:baseline`、`npm run schema:verify` 和 `governance:start` 的外部用法不变。
+- 保留历史 format v1/v2 基线的只读兼容，不重写既有发布证据。
+- 在实现完成后生成并推送 `v0.0.9` 基线，恢复自动版本开发流程。
+
+## 范围
+
+- 导出表、索引、外键、视图、触发器、存储过程、函数和 Event Scheduler 事件。
+- 新增 format v3 清单，记录 Node 导出器、`mysql2` 驱动和 MySQL 5.7.x 服务端信息。
+- 使用开发环境白名单、对象摘要前后校验、SQL 安全扫描、原子写入和 SHA-256 校验。
+- 为导出、验证、历史兼容、错误恢复和真实空开发库补充测试。
+
+## 非目标
+
+- 不备份任何表数据。
+- 不连接、探测或读取生产数据库。
+- 不安装 MySQL Server、MySQL CLI、Docker 或远程导出服务。
+- 不修改业务数据库结构、迁移、实体或应用查询。
+- 不把 TypeORM 实体定义当作现有数据库真实结构的替代品。
+
+## 用户流程
+
+1. 开发者在开发下一版本前运行 `npm run schema:baseline`。
+2. 工具固定读取 development 配置并验证目标库边界。
+3. Node 导出器连接开发库、读取完整对象定义并生成版本目录。
+4. 开发者运行 `npm run schema:verify`，提交并推送该目录。
+5. `governance:start` 核对基线、远程分支和发布标签后允许下一功能开发。
+
+## 成功指标
+
+- 未安装 `mysql` 和 `mysqldump` 的开发机能够完成真实 Schema 基线生成。
+- 相同结构重复导出产生逐字节一致的 SQL 和 SHA-256。
+- format v1/v2 历史基线继续通过原有验证。
+- 空开发库生成 `captured_empty`，非空开发库生成完整 `schema.sql`。
+- 失败时不留下目标版本目录或半成品。
+
+## 验收标准
+
+- Given 本机不存在 MySQL CLI，When 执行 `schema:baseline`，Then 工具通过 `mysql2` 连接固定开发库且不调用外部数据库命令。
+- Given 数据库包含所有受支持对象，When 导出完成，Then SQL 包含完整对象定义且不包含数据、凭据和 `DEFINER`。
+- Given 历史 format v1/v2 基线，When 执行 `schema:verify`，Then 继续按原规则通过或失败，文件不被重写。
+- Given 导出期间对象摘要变化，When 执行完成前复核，Then 命令失败并清理临时目录。
+- Given `v0.0.9` 基线已提交推送，When 执行 `governance:start`，Then 不再因本机缺少 MySQL CLI 被阻断。
+
+## 风险
+
+- `SHOW CREATE` 权限不足会阻断完整导出，必须明确报错，不能跳过对象。
+- 视图依赖和例程分隔符处理错误会降低恢复能力，必须用固定夹具和恢复顺序测试覆盖。
+- 本功能位于版本治理关键路径，任何历史兼容回归都可能阻断全部后续开发。
+
+## 发布与回退
+
+GOV-012 作为独立治理版本发布。若新导出器不能生成确定性完整结构、历史基线验证回归或 `governance:start` 无法恢复，则不得发布；代码回退到 GOV-012 前提交，已发布的历史基线保持不变。