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,57 @@
+# 纯 Node.js 开发库 Schema 导出器设计
+
+## 1. 架构
+
+保留 `tools/database/schema-baseline.mjs` 作为治理入口，继续负责固定配置、发布版本、产物构建、历史验证、原子持久化和远程发布核对。新增 `tools/database/mysql2-schema-exporter.mjs`，集中负责连接、元数据读取、`SHOW CREATE`、依赖排序和确定性 SQL 渲染，不把一次业务流程拆成过多小文件。
+
+```text
+development 配置
+  -> schema-baseline 安全边界
+  -> mysql2-schema-exporter
+  -> MySQL 5.7 元数据与 SHOW CREATE
+  -> 确定性 schema.sql
+  -> manifest.yaml + checksum.sha256
+  -> 原子版本目录
+```
+
+根工作区直接声明 `mysql2`，使治理工具拥有明确依赖。`runBaselineGeneration` 和 CLI 入口改为异步，外部 npm 命令保持不变。
+
+## 2. format v3 与历史兼容
+
+format v3 使用独立字段记录 Node 导出器名称、导出器版本、数据库驱动名称、驱动版本和 MySQL 服务端版本，不复用 v1/v2 的 `mysql_client_version` 或 `mysqldump_client_version` 含义。
+
+验证器按 `format_version` 分支：v1/v2 保留现有字段和校验规则；v3 校验新字段。既有目录不得自动升级、格式化或重写。`captured`、`captured_empty` 和 `not_applicable` 状态继续保留。
+
+## 3. 对象导出与顺序
+
+导出器先从 `information_schema` 获取固定库的对象清单和依赖，再对每个对象执行参数受控的 `SHOW CREATE`：
+
+1. 基础表按名称排序，保留列、索引、外键、表选项和注释。
+2. 存储过程与函数按类型和名称排序。
+3. 视图依据库内依赖拓扑排序；循环或未知依赖失败。
+4. 触发器按所属表、时机、事件和执行顺序排序。
+5. Event Scheduler 事件按名称排序。
+
+例程、触发器和事件使用稳定 `DELIMITER`。标识符只能来自元数据，并统一转义反引号。导出结果删除 `DEFINER`、当前 `AUTO_INCREMENT` 值、时间、主机、用户名和客户端噪声；同一结构必须产生逐字节一致结果。
+
+## 4. 完整性与安全
+
+导出前后分别计算对象摘要，包含对象类型、名称、依赖和定义可观察版本；摘要不一致表示并发 DDL，命令失败。任何对象无法 `SHOW CREATE`、结果为空或类型未知时禁止跳过。
+
+连接只允许固定 development 边界，禁用多语句，使用单连接、超时和对象数量限制。工具只查询元数据和 `SHOW CREATE`，不查询业务表、不锁表、不执行 DDL/DML。密码只存在于内存配置，并在所有路径通过 `finally` 关闭连接。
+
+现有 SQL 安全扫描继续拒绝顶层数据操作、连接串、疑似凭据和残留 `DEFINER`；对象体内部合法 DML 通过分隔符解析保留。
+
+## 5. 性能与异常恢复
+
+Schema 备份不在在线请求路径。使用单连接和有限并发，目标中小型开发库 30 秒内完成；连接、查询、总时长、对象数量或响应大小超过保护值时失败。
+
+产物先写入版本父目录中的临时目录，经过 SQL 扫描、对象计数、manifest 和 SHA-256 一致性校验后原子重命名。失败时删除临时目录，既有版本目录禁止覆盖。
+
+## 6. 实施迁移
+
+GOV-012 因缺少 `v0.0.9` 基线使用用户授权的一次性人工启动记录。实现通过后立即运行新导出器生成并推送 `v0.0.9` 基线，再重新执行自动 `governance:start`，证明后续开发不再依赖本机 MySQL CLI。
+
+## 7. 依赖评估
+
+选择已有技术栈中的 `mysql2`，避免引入不透明的第三方 dump 包。替代方案包括安装 MySQL 5.7 客户端或远程执行 `mysqldump`，前者在现代 macOS 上难以维护，后者增加 SSH、凭据和远程工具版本风险。退出时可替换 exporter 端口实现，但 format v3 历史基线验证必须永久保留。