diff --git a/AGENTS.md b/AGENTS.md index 99a61fb..81e6312 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,7 +29,7 @@ # 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. diff --git a/docs/features/GOV-012-node-schema-exporter/development-summary.md b/docs/features/GOV-012-node-schema-exporter/development-summary.md new file mode 100644 index 0000000..575c16b --- /dev/null +++ b/docs/features/GOV-012-node-schema-exporter/development-summary.md @@ -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 已提交并推送。 diff --git a/docs/features/GOV-012-node-schema-exporter/gitnexus/after.md b/docs/features/GOV-012-node-schema-exporter/gitnexus/after.md new file mode 100644 index 0000000..bfa4860 --- /dev/null +++ b/docs/features/GOV-012-node-schema-exporter/gitnexus/after.md @@ -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`；没有生产数据库访问。 diff --git a/docs/features/GOV-012-node-schema-exporter/gitnexus/comparison.md b/docs/features/GOV-012-node-schema-exporter/gitnexus/comparison.md new file mode 100644 index 0000000..70b1240 --- /dev/null +++ b/docs/features/GOV-012-node-schema-exporter/gitnexus/comparison.md @@ -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、运行时服务变更 | 符合影响计划 | diff --git a/docs/features/GOV-012-node-schema-exporter/gitnexus/detected-changes.md b/docs/features/GOV-012-node-schema-exporter/gitnexus/detected-changes.md new file mode 100644 index 0000000..9043dfe --- /dev/null +++ b/docs/features/GOV-012-node-schema-exporter/gitnexus/detected-changes.md @@ -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 传输故障作为残余工具风险保留，不解释为无影响。 diff --git a/docs/features/GOV-012-node-schema-exporter/qa/test-results.md b/docs/features/GOV-012-node-schema-exporter/qa/test-results.md new file mode 100644 index 0000000..0e41b4f --- /dev/null +++ b/docs/features/GOV-012-node-schema-exporter/qa/test-results.md @@ -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` 和独立远程基线检查替代验证。 diff --git a/docs/features/GOV-012-node-schema-exporter/qa/visual-qa.md b/docs/features/GOV-012-node-schema-exporter/qa/visual-qa.md new file mode 100644 index 0000000..a6b532a --- /dev/null +++ b/docs/features/GOV-012-node-schema-exporter/qa/visual-qa.md @@ -0,0 +1,9 @@ +# 视觉 QA + +## 适用性 + +GOV-012 只修改数据库治理工具、测试、文档和 Schema 清单，不修改 Web 页面、样式、图表或交互流程，因此不适用浏览器截图和视觉回归。 + +## 边界 + +下一项市场概览业务功能涉及 Web 页面时，必须按现行规范补充 Playwright 流程和同视口视觉证据；本结论不能外推到后续前端功能。 diff --git a/docs/features/GOV-012-node-schema-exporter/release-notes.md b/docs/features/GOV-012-node-schema-exporter/release-notes.md new file mode 100644 index 0000000..b65218e --- /dev/null +++ b/docs/features/GOV-012-node-schema-exporter/release-notes.md @@ -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 基线。 diff --git a/docs/features/GOV-012-node-schema-exporter/review/code-review.md b/docs/features/GOV-012-node-schema-exporter/review/code-review.md new file mode 100644 index 0000000..7bf3f3b --- /dev/null +++ b/docs/features/GOV-012-node-schema-exporter/review/code-review.md @@ -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 diff --git a/docs/features/GOV-012-node-schema-exporter/review/standards-review.md b/docs/features/GOV-012-node-schema-exporter/review/standards-review.md new file mode 100644 index 0000000..bd442cc --- /dev/null +++ b/docs/features/GOV-012-node-schema-exporter/review/standards-review.md @@ -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