纯 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 实体定义当作现有数据库真实结构的替代品。

用户流程

开发者在开发下一版本前运行 npm run schema:baseline。
工具固定读取 development 配置并验证目标库边界。
Node 导出器连接开发库、读取完整对象定义并生成版本目录。
开发者运行 npm run schema:verify，提交并推送该目录。
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 前提交，已发布的历史基线保持不变。

3.8 KiB Raw Blame History Unescape Escape