From f1c412b6a397b31987bc4c9c09a12dcc53f5be0d Mon Sep 17 00:00:00 2001 From: Citrons <909229731@qq.com> Date: Tue, 18 Aug 2026 03:00:47 +0800 Subject: [PATCH] =?UTF-8?q?docs(GOV-012):=20=E6=9B=B4=E6=96=B0=E7=BA=AF=20?= =?UTF-8?q?Node=20Schema=20=E5=9F=BA=E7=BA=BF=E8=A7=84=E8=8C=83?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 2 +- README.md | 2 +- docs/features/GOV-012-node-schema-exporter/design.md | 8 ++++---- docs/features/GOV-012-node-schema-exporter/test-plan.md | 7 ++++++- docs/governance/code-development-standards.md | 8 +++++--- docs/governance/development-workflow.md | 6 +++--- 6 files changed, 20 insertions(+), 13 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 47e3edf..99a61fb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,7 +29,7 @@ # GitNexus — Code Intelligence -This project is indexed by GitNexus as **a-share-analysis** (2382 symbols, 3233 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** (2383 symbols, 3234 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/README.md b/README.md index 417068f..486ce2f 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ npm run schema:verify npm run governance:start -- FEAT-MO-001 market-overview ``` -Schema 命令只允许处理固定开发库；当前 MySQL 未启用时会为上一发布版本生成可验证的不适用清单，不会连接数据库或创建空 SQL。完整规则见 [开发流程规范](docs/governance/development-workflow.md)。 +Schema 命令只允许处理固定开发库；导出器使用 Node.js `mysql2`，本机无需安装 MySQL Server 或 CLI。当前 MySQL 未启用时会为上一发布版本生成可验证的不适用清单，不会连接数据库或创建空 SQL；启用但无对象时生成 format v3 `captured_empty` 清单。完整规则见 [开发流程规范](docs/governance/development-workflow.md)。 ## 项目仓库 diff --git a/docs/features/GOV-012-node-schema-exporter/design.md b/docs/features/GOV-012-node-schema-exporter/design.md index 566b012..156e102 100644 --- a/docs/features/GOV-012-node-schema-exporter/design.md +++ b/docs/features/GOV-012-node-schema-exporter/design.md @@ -34,7 +34,7 @@ format v3 使用独立字段记录 Node 导出器名称、导出器版本、数 例程、触发器和事件使用稳定 `DELIMITER`。标识符只能来自元数据，并统一转义反引号。导出结果删除 `DEFINER`、当前 `AUTO_INCREMENT` 值、时间、主机、用户名和客户端噪声；同一结构必须产生逐字节一致结果。 -## 4. 完整性与安全 +## 4. 安全策略与评估 导出前后分别计算对象摘要，包含对象类型、名称、依赖和定义可观察版本；摘要不一致表示并发 DDL，命令失败。任何对象无法 `SHOW CREATE`、结果为空或类型未知时禁止跳过。 @@ -42,15 +42,15 @@ format v3 使用独立字段记录 Node 导出器名称、导出器版本、数 现有 SQL 安全扫描继续拒绝顶层数据操作、连接串、疑似凭据和残留 `DEFINER`；对象体内部合法 DML 通过分隔符解析保留。 -## 5. 性能与异常恢复 +## 5. 性能目标与评估 Schema 备份不在在线请求路径。使用单连接和有限并发，目标中小型开发库 30 秒内完成；连接、查询、总时长、对象数量或响应大小超过保护值时失败。 产物先写入版本父目录中的临时目录，经过 SQL 扫描、对象计数、manifest 和 SHA-256 一致性校验后原子重命名。失败时删除临时目录，既有版本目录禁止覆盖。 -## 6. 实施迁移 +## 6. 异常恢复与实施迁移 -GOV-012 因缺少 `v0.0.9` 基线使用用户授权的一次性人工启动记录。实现通过后立即运行新导出器生成并推送 `v0.0.9` 基线，再重新执行自动 `governance:start`，证明后续开发不再依赖本机 MySQL CLI。 +GOV-012 因缺少 `v0.0.9` 基线使用用户授权的一次性人工启动记录。实现通过后已使用 development 配置连接 MySQL 5.7.x，生成并推送 `v0.0.9` format v3 `captured_empty` 基线；随后重新执行自动 `governance:start`，证明后续开发不再依赖本机 MySQL CLI。MySQL 5.7.x 缺少 `VIEW_TABLE_USAGE` 时，导出器回退读取 `information_schema.VIEWS`，其余查询错误不降级。 ## 7. 依赖评估 diff --git a/docs/features/GOV-012-node-schema-exporter/test-plan.md b/docs/features/GOV-012-node-schema-exporter/test-plan.md index e251735..e600206 100644 --- a/docs/features/GOV-012-node-schema-exporter/test-plan.md +++ b/docs/features/GOV-012-node-schema-exporter/test-plan.md @@ -25,8 +25,13 @@ - 当前为空时生成 `captured_empty`；发现实际对象时生成完整 `captured`，不得按预期强制为空。 - 运行 `schema:verify`、治理测试、格式、lint、类型检查和完整仓库验证。 -## 安全与性能 +## 安全验证 - 证明没有子进程数据库客户端调用、业务表数据查询、生产配置读取或多语句执行。 - 固定夹具验证对象数量、响应大小、查询和总时长保护。 - 残余风险包括真实库权限差异和并发 DDL；通过失败关闭、摘要复核和人工重跑控制。 + +## 性能验证 + +- 假连接验证单连接、5 秒查询超时、30 秒总时长、5,000 对象和 1 MiB 单定义限制；真实开发库记录导出状态和耗时，不记录 SQL 或凭据。 +- 本功能是低频治理命令，不在 API 请求路径，也不承载在线行情吞吐；因此不执行业务负载压测，边界是版本基线生成和验证命令本身。 diff --git a/docs/governance/code-development-standards.md b/docs/governance/code-development-standards.md index e281023..e7ec7f7 100644 --- a/docs/governance/code-development-standards.md +++ b/docs/governance/code-development-standards.md @@ -144,11 +144,13 @@ count += 1; ### Schema 基线规范 - 每个新应用版本开发前必须封存上一已发布版本的开发库 Schema；只能读取 `APP_ENV=development`、`a_share_analysis_dev` 和 MySQL 5.7.x，主机仅允许回环地址或固定开发白名单 `112.192.20.11`，禁止连接、探测或读取生产数据库。配置优先读取 Git 忽略的 `deploy/env/development/api.env.local`。 -- 导出使用 MySQL 5.7.x `mysqldump` 的 `--no-data --routines --triggers --events`，完整保留表、索引、外键、视图、触发器、存储过程、函数和事件，不得包含任何表数据。 +- 导出使用 Node.js 22.x 与 `mysql2` 连接 MySQL 5.7.x，读取固定 `information_schema` 元数据并执行 `SHOW CREATE`，完整保留表、索引、外键、视图、触发器、存储过程、函数和事件，不得包含任何表数据；本机不要求安装 MySQL Server、`mysql` 或 `mysqldump`。 - 规范化必须确定性删除导出时间、环境 `DEFINER` 和表选项中的当前 `AUTO_INCREMENT=<值>`，同时保留列定义的 `AUTO_INCREMENT` 属性和业务 SQL。 -- 账号密码只能通过受控子进程环境传递，不得进入参数、日志、SQL、清单或 checksum 文件。 +- 账号密码只存在于内存连接配置，不得进入命令参数、日志、异常、SQL、清单或 checksum 文件。 - `manifest.yaml`、`checksum.sha256` 和 `schema.sql` 的 SHA-256 必须一致；既有版本目录只允许内容完全一致的幂等验证，不允许覆盖。 -- MySQL 未启用时只创建状态为 `not_applicable` 的清单，不得创建空 `schema.sql`；启用但无对象时创建 format v2 的 `captured_empty` 清单和零对象计数，不伪造空 SQL；启用后的缺失基线必须阻断下一版本开发。既有 format v1 基线必须继续只读验证，不得静默升级或重写。 +- 导出前后必须复核对象目录和定义摘要，发现并发 DDL 或定义变化立即失败；MySQL 5.7.x 不提供 `VIEW_TABLE_USAGE` 时，只能回退读取 `information_schema.VIEWS.VIEW_DEFINITION` 解析视图依赖。 +- MySQL 未启用时只创建状态为 `not_applicable` 的清单，不得创建空 `schema.sql`；启用但无对象时创建 format v3 的 `captured_empty` 清单和零对象计数，不伪造空 SQL；启用后的缺失基线必须阻断下一版本开发。既有 format v1/v2 基线必须继续只读验证，不得静默升级或重写。 +- format v3 清单记录 Node exporter 和数据库驱动版本，不复用 v1/v2 的 `mysql_client_version` 与 `mysqldump_client_version` 字段。 ## 12. 测试要求 diff --git a/docs/governance/development-workflow.md b/docs/governance/development-workflow.md index 91e1267..443d00b 100644 --- a/docs/governance/development-workflow.md +++ b/docs/governance/development-workflow.md @@ -17,7 +17,7 @@ released → superseded ## 3. 开发前流程 1. 确认上一已发布语义化版本及标签提交，执行 `npm run schema:baseline` 和 `npm run schema:verify`。 -2. MySQL 已启用时只能从 `APP_ENV=development`、`a_share_analysis_dev`、MySQL 5.7、`utf8mb4_general_ci` 和固定开发主机白名单（回环地址或 `112.192.20.11`）导出 Schema；配置优先读取被 Git 忽略的 `deploy/env/development/api.env.local`，不存在时才读取无秘密模板。空开发库保存 format v2 的 `captured_empty` 清单，不创建空 SQL；MySQL 未启用时只保存 `not_applicable` 清单。 +2. MySQL 已启用时只能从 `APP_ENV=development`、`a_share_analysis_dev`、MySQL 5.7.x、`utf8mb4_general_ci` 和固定开发主机白名单（回环地址或 `112.192.20.11`）导出 Schema；配置优先读取被 Git 忽略的 `deploy/env/development/api.env.local`，不存在时才读取无秘密模板。空开发库保存 format v3 的 `captured_empty` 清单，不创建空 SQL；MySQL 未启用时只保存 `not_applicable` 清单。 3. 将 `database/schema-baselines/<上一发布版本>/` 作为独立中文提交推送 Gitea，核对本地和远程 SHA；既有版本目录禁止覆盖。只有 Git 已跟踪、工作区无改动、当前分支已推送且远程发布标签提交一致时，`governance:start` 才会继续。 4. 分配功能编号和英文短名称。 5. 建立 `docs/features/<编号>-<短名称>/`。 @@ -101,10 +101,10 @@ npm run governance:finish -- FEAT-MO-001 market-overview - 基线目录固定为 `database/schema-baselines/vX.Y.Z/`，版本是被备份的已发布版本。 - 真实基线由 `schema.sql`、`manifest.yaml`、`checksum.sha256` 组成；范围包括表、索引、外键、视图、触发器、存储过程、函数和 Event Scheduler 事件，不含数据。 -- MySQL 未启用时目录只能包含 `manifest.yaml`，状态为 `not_applicable`、原因为 `mysql_disabled`；启用但无对象时目录也只包含 `manifest.yaml`，状态为 format v2 的 `captured_empty` 并记录零对象计数。 +- MySQL 未启用时目录只能包含 `manifest.yaml`，状态为 `not_applicable`、原因为 `mysql_disabled`；启用但无对象时目录也只包含 `manifest.yaml`，状态为 format v3 的 `captured_empty` 并记录零对象计数。 - `schema:baseline` 不接受 env 路径、环境类型或数据库名参数；配置路径固定在开发环境，生产配置和生产数据库不属于该命令的权限范围。 - 修正已发布基线必须新增治理记录说明原因，禁止静默覆盖或重写历史目录。 -- 首次启用 MySQL 的版本必须在 MySQL 5.7 开发环境生成第一份真实或 `captured_empty` Schema 基线；format v1 历史清单保持只读兼容，禁止因工具升级重写。 +- 首次启用 MySQL 的版本必须在 MySQL 5.7 开发环境生成第一份真实或 `captured_empty` Schema 基线；format v1/v2 历史清单保持只读兼容，禁止因工具升级重写。 ## 8. 提交流程