docs(GOV-012): 完成功能质量与发布追溯档案

2026-08-18 03:04:59 +08:00
parent f1c412b6a3
commit 58026aead3
10 changed files with 183 additions and 1 deletions
@@ -29,7 +29,7 @@
 <!-- gitnexus:start -->
 # GitNexus — Code Intelligence
-This project is indexed by GitNexus as **a-share-analysis** (2383 symbols, 3234 relationships, 63 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+This project is indexed by GitNexus as **a-share-analysis** (2429 symbols, 3280 relationships, 63 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
 > If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
@@ -0,0 +1,44 @@
 # GOV-012 开发总结
 ## 原始开发需求
 将 Schema 版本基线从本机 `mysql`/`mysqldump` 子进程迁移为 Node.js 22.x 与 mysql2 直接读取 MySQL 5.7.x，保留历史格式兼容、恢复开发门禁，并满足安全、性能、可追溯和 Gitea 推送规范。
 ## 需求与范围变化
 - 原计划使用 MySQL 5.7 `VIEW_TABLE_USAGE` 读取视图依赖；真实 5.7.42 不提供该表，增加仅针对 ER_UNKNOWN_TABLE 的 `information_schema.VIEWS` 定义解析回退。
 - 原计划空库 exporter 返回会话 SET；实际 format v3 空库必须返回空 SQL，修正为 `captured_empty`。
 - GOV-012 不接入 HTTP/OpenAPI、Web、Redis、RocketMQ、API、Scheduler 或 Worker 运行时。
 ## 实际完成需求
 - 新增 mysql2 单连接导出器：元数据校验、目录读取、视图排序、六类 `SHOW CREATE`、确定性渲染、并发漂移检测、超时/大小/对象上限和错误脱敏。
 - `schema-baseline.mjs` 支持 format v3、异步 exporter 注入、原子文件操作故障注入、CLI 异步入口，并永久只读兼容 v1/v2。
 - 更新当前开发规范、开发流程、README、设计和测试计划；真实开发库生成并推送 `v0.0.9` `captured_empty` 清单。
 ## 修复缺陷
 - 拒绝 MariaDB 伪装版本。
 - 严格校验触发器时机、事件和执行顺序。
 - 防止目录、元数据和 SHOW CREATE 直接 API 泄露数据库错误。
 - 保留 `EXPORT_TIMEOUT` 语义，避免包装器降级为普通查询错误。
 - 防止全局正则改写例程字符串中的 `AUTO_INCREMENT`，并拒绝导出定义中的主机信息。
 - 兼容真实 MySQL 5.7.42 缺少 `VIEW_TABLE_USAGE` 的目录差异。
 ## 未完成与延期项
 - `glob` high 依赖风险按用户批准的范围例外保留为独立治理欠项，未在 GOV-012 中升级前端测试依赖。
 - GOV-012 尚未合并到 `main`、发布 `v0.0.10` 或封存 `v0.0.10` 基线；这些是后续 Task 8/9 的发布步骤。
 - MCP GitNexus 传输故障仍待工具环境恢复，不影响已保存的 CLI/静态替代证据。
 ## 关键提交
 - `06466f3`、`8e954a3`、`54fd928`、`7e9d906`、`dc8ad7d`
 - `c11de09`、`3d12c83`、`874796a`、`afd186c`、`f1c412b`
 ## 验证证据
 - `npm run test:schema-baseline`：52/52；`npm run test:governance`：10/10；`npm run test:mysql-baseline`：2/2。
 - `npm run test:environment-baseline`：10/10；contracts：3/3；boundaries：16/16；deployment：6/6。
 - `pnpm lint`、`pnpm typecheck`、Prettier、`npm run schema:verify` 均通过。
 - 真实 development MySQL 5.7.42 连接成功，`a_share_analysis_dev` 五类对象均为 0，v0.0.9 manifest 已提交并推送。
@@ -0,0 +1,23 @@
 # GitNexus 开发后基线
 - 功能编号：GOV-012
 - 记录时间：2026年08月18日 CST
 - 分支：`codex/gov-012-node-schema-exporter`
 - 当前提交：`f1c412b`
 ## GitNexus 状态
 ```text
 Indexed commit: f1c412b
 Nodes: 2,383
 Edges: 3,234
 Clusters: 54
 Flows: 63
 MCP: Transport closed（按 CLI 与静态证据降级）
 ```
 ## 实际影响
 - 运行时只影响 Schema 治理工具、测试、治理文档和 `v0.0.9` 开发基线。
 - HTTP/OpenAPI、Web API、消息契约、Redis、API、Scheduler、Worker 和部署入口没有代码变更。
 - MySQL 连接仅命中用户确认的 development 配置和 `a_share_analysis_dev`；没有生产数据库访问。
@@ -0,0 +1,9 @@
 # GitNexus 前后对比
 | 项目 | 开发前 | 开发后 | 判断 |
 | --- | --- | --- | --- |
 | Git 提交 | `3555b7c` | `f1c412b` | GOV-012 独立分支完成实现和文档提交 |
 | 索引规模 | 2,112 nodes / 2,790 edges / 50 flows | 2,383 nodes / 3,234 edges / 63 flows | 仅新增导出器、测试和文档相关符号 |
 | MCP | `Transport closed` | `Transport closed` | 使用 CLI、静态引用和回归测试降级核对 |
 | 数据库范围 | 缺失 `v0.0.9` 基线 | `a_share_analysis_dev`，`captured_empty` | 开发门禁恢复 |
 | 跨模块变更 | 待分析 | 无 HTTP/OpenAPI、消息、Redis、运行时服务变更 | 符合影响计划 |
@@ -0,0 +1,17 @@
 # GitNexus 变更检测
 ## 工具证据
 - GitNexus MCP `detect_changes` 在开发前后均返回 `Transport closed`。
 - `npx gitnexus analyze` 已在关键提交后执行，最终索引为 2,383 nodes、3,234 edges、63 flows。
 - `npx gitnexus detect-changes --repo a-share-analysis` 返回 `No changes detected`；CLI 对当前未提交差异的识别不完整，不能单独作为无影响结论。
 ## 静态与 Git 交叉核对
 - `git diff --stat` 和提交清单确认变更集中在 `tools/database/schema-baseline.mjs`、`tools/database/mysql2-schema-exporter.mjs`、对应测试、GOV-012 文档及 `database/schema-baselines/v0.0.9/manifest.yaml`。
 - `rg` 静态引用确认 `runCommandLine -> runBaselineGeneration -> exportMysql57Schema` 及历史 `verifyBaselineDirectory` 调用链仍在预期治理路径内。
 - 没有 HTTP/OpenAPI、Web API、RocketMQ、Redis、API、Scheduler、Worker 或生产部署文件变更。
 ## 结论
 影响范围符合开发前计划；MCP 传输故障作为残余工具风险保留，不解释为无影响。
@@ -0,0 +1,24 @@
 # QA 测试结果
 ## 通过项
 - `npm run test:schema-baseline`：52/52 通过，包含 Node exporter、format v1/v2 只读兼容、format v3、错误脱敏、MySQL 5.7 视图目录回退和真实 `v0.0.9` 基线门禁。
 - `npm run test:governance`：10/10 通过。
 - `npm run test:mysql-baseline`：2/2 通过。
 - `npm run test:environment-baseline`：10/10 通过。
 - `npm run test:contracts`：3/3 通过。
 - `npm run test:boundaries`：16/16 通过。
 - `npm run test:deployment`：6/6 通过。
 - `npm run check:runtime`：Node.js 22.11.0、pnpm 10.25.0 通过。
 - `pnpm lint`：Web 和 Server ESLint 通过。
 - `pnpm typecheck`：Web 与 Server TypeScript 检查通过。
 - `npm run schema:verify`：`v0.0.9 (captured_empty)` 通过。
 ## 真实开发库
 - 使用 Git 忽略的 development 本地配置，只读取 `a_share_analysis_dev` 的元数据和 `SHOW CREATE`；服务端为 MySQL 5.7.42，五类对象计数均为 0。
 - 生成结果只有 `manifest.yaml`，没有 `schema.sql`、checksum 中没有密码或连接信息。
 ## 未执行项
 - `npm run governance:start -- GOV-012 node-schema-exporter` 未重复覆盖已有开发前报告，工具按历史保护规则拒绝；已用 `schema:verify` 和独立远程基线检查替代验证。
@@ -0,0 +1,9 @@
 # 视觉 QA
 ## 适用性
 GOV-012 只修改数据库治理工具、测试、文档和 Schema 清单，不修改 Web 页面、样式、图表或交互流程，因此不适用浏览器截图和视觉回归。
 ## 边界
 下一项市场概览业务功能涉及 Web 页面时，必须按现行规范补充 Playwright 流程和同视口视觉证据；本结论不能外推到后续前端功能。
@@ -0,0 +1,17 @@
 # GOV-012 发布说明（待发布）
 ## 计划版本
 `v0.0.10`，发布主题为纯 Node.js 开发库 Schema 导出器。
 ## 变更
 - 移除 Schema 生成对本机 MySQL CLI 的运行时依赖，改用 mysql2 和 MySQL 5.7.x `SHOW CREATE`。
 - 新增 format v3，记录 exporter/driver 元数据；format v1/v2 保持只读兼容。
 - 恢复下一版本开发前的 Schema 基线门禁，已封存 `v0.0.9` `captured_empty` 基线。
 ## 发布前置
 - 先在 `main` 完成代码 Review、规范 Review、`governance:finish` 和全量验证。
 - 创建并推送 `v0.0.10` 标签，再独立生成并推送 `database/schema-baselines/v0.0.10/manifest.yaml`。
 - 发布失败时按 `rollback.md` 回退代码提交，禁止删除或覆盖 v0.0.9 基线。
@@ -0,0 +1,24 @@
 # 代码 Review
 ## 范围
 Review 覆盖 `mysql2-schema-exporter.mjs`、`schema-baseline.mjs`、对应测试、format v3 清单和文档变更。Task 2/3 Review 发现的问题已通过修复提交关闭：触发器元数据严格校验、目录/SHOW CREATE/元数据错误脱敏、超时错误语义保留、例程字面量不误改、主机信息拒绝，以及 MySQL 5.7 视图目录回退。
 ## 安全与残余风险
 - 只读 `information_schema` 和 `SHOW CREATE`，禁用多语句，不读取业务数据，不执行 DDL/DML，不锁表。
 - 配置边界固定为 development、`a_share_analysis_dev` 和开发主机白名单；密码不进入日志、异常、SQL、清单或 checksum。
 - 连接、查询、总时长、对象数和定义大小均有上限，所有路径最终关闭连接。
 - 既有 Web 测试依赖链 `glob` 的 high 漏洞是用户批准的范围限定治理欠项，不在本功能新增路径；若 mysql2 或导出链出现 high/critical，必须阻断发布。
 ## 性能与资源影响
 - 单连接、按目录顺序读取，查询 5 秒超时、总时长 30 秒、对象 5,000、单定义 1 MiB；视图排序为确定性 Kahn 算法。
 - 治理命令不在在线请求路径，不新增 API、Redis、RocketMQ 或 Worker 负载；空库实际生成 `captured_empty`。
 ## GitNexus 与同步修改
 - MCP `Transport closed`，已用 CLI reindex/status、静态引用和回归测试交叉核对；影响集中在 Schema 治理链路。
 - HTTP/OpenAPI、Web API、消息、Redis、API、Scheduler、Worker、部署均无需同步修改；Schema 文档、测试脚本和 v0.0.9 基线已同步。
 最终结论：passed
@@ -0,0 +1,15 @@
 # 开发规范符合性 Review
 ## 安全、性能与架构检查
 - 代码使用中文注释说明开发库边界、错误脱敏、并发变化和 MySQL 5.7 回退；文件职责没有继续过度拆分。
 - Node.js 22.x、mysql2、MySQL 5.7.x、`utf8mb4_general_ci` 和 format v3 约束已同步实现、规范和测试。
 - 安全策略覆盖凭据、SQL 注入、生产边界、错误、依赖和残余风险；性能目标、保护阈值和不适用压测边界均有证据。
 ## GitNexus 与开发总结检查
 - 开发前影响计划、开发后索引、变更检测和前后对比已归档；MCP 传输限制已明确记录。
 - 开发总结记录原始需求、范围变化、实际完成、修复缺陷、延期项、提交和验证证据。
 - 提交均为中文 Conventional Commit，当前分支和每次提交均已推送项目 Gitea；未修改 Git 全局配置。
 最终结论：passed