# 纯 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 前提交，已发布的历史基线保持不变。