docs(GOV-011): 确认系列版本约束设计

2026-08-17 17:01:39 +08:00
parent 9e85809096
commit fcfef2d524
9 changed files with 234 additions and 1 deletions
@@ -0,0 +1,74 @@
+# Node 与 MySQL 系列版本约束设计
+
+- 功能编号：GOV-011
+- 设计状态：已获用户方向确认，等待书面规格复核
+- 日期：2026-08-17
+
+## 设计决策
+
+采用真实系列校验，而不是只改文案或增加最低补丁版本：Node.js 通过语义版本解析后要求 `major === 22`；MySQL 客户端、mysqldump 和服务端要求版本字符串满足 `5.7.<非负整数>`，允许 `-log` 等既有后缀。用户已明确选择完整 5.7.x，不设置 5.7.9 等最低补丁版本。
+
+历史 QA、Schema manifest 和已发布功能档案中的 5.7.42、22.11.0、22.22.0 是真实验证事实，不改写。只有当前生效的代码注释、错误提示、架构规范和部署前置条件统一改为系列口径。
+
+## 代码边界
+
+### Node.js
+
+`tools/runtime/verify-runtime.mjs` 已经只校验 Node 主版本 22，不需要修改生产判断。测试补充 22 系列内边界以及 21/23 拒绝，注释和当前文档明确写成 22.x。pnpm 继续按 10.x 校验，不属于本次变化。
+
+### Schema 工具
+
+`assertMysql57Metadata` 继续作为唯一 Schema 版本判断入口，但服务端正则从精确 5.7.42 收敛为与两个客户端相同的 5.7.x 规则。历史真实/captured_empty manifest 仍保存实际版本并由同一入口验证；不改 manifest 格式，不重写历史目录。
+
+### API 健康检查
+
+`MysqlHealthClient.check` 接受 5.7.x，继续逐项校验目标库、`utf8mb4`、`utf8mb4_general_ci` 和 `+08:00`。成功详情使用查询返回的实际版本，例如 `MySQL 5.7.41 / a_share_analysis_dev / +08:00`；失败提示统一为“需要 MySQL 5.7.x”。
+
+### 配置与 TypeORM
+
+`MysqlRuntimeConfig` 和 `buildTypeOrmOptions` 没有版本字段或版本分支，只需把说明性注释由 5.7.42 修正为 5.7.x。连接选项、`synchronize: false`、迁移策略和字符规则保持不变。
+
+## GitNexus 影响
+
+- `assertMysql57Metadata`：CRITICAL，5 个直接调用方、10 个受影响符号和 5 组流程，覆盖 captured/captured_empty 产物、历史目录验证、当前发布基线、基线生成和 `governance:start`。
+- `MysqlHealthClient`：LOW，4 个直接依赖、7 个受影响符号和 1 组 API 装配流程。
+- `assertSupportedRuntime`：LOW，只有运行时测试直接调用，0 条业务流程。
+
+CRITICAL 来自 Schema 门禁的中心位置，不代表改动复杂。实施必须先增加精确失败用例，再完整回归 Schema 28 项及治理前后门禁；如出现历史 manifest 失效或非 5.7 版本被放行，立即停止并回退。
+
+## 跨模块同步修改
+
+- HTTP/OpenAPI：响应结构不变，仅健康 `detail` 文本显示实际版本；无需重新定义 DTO。
+- Web API：不修改请求函数或 adapter；现有健康展示把 detail 当普通文本。
+- 消息、Redis、Scheduler、Worker：无行为变化。
+- 数据库：不修改 Schema、迁移、查询范围或凭据，只放宽补丁版本判断。
+- 部署：继续仅支持 Ubuntu 源码部署，前置条件改写为 Node.js 22.x、MySQL 5.7.x。
+- 测试与文档：运行时、Schema、健康客户端、架构规范、开发规范、本地和生产部署手册同步更新。
+
+## 错误处理
+
+- 版本为空、格式异常或系列不符时立即失败，并只输出检测到的版本字符串。
+- 版本符合 5.7.x 但字符集、排序规则、库名或时区不符时，保持现有专用错误，不把问题误报为版本错误。
+- 不捕获或降级版本错误，不因个人部署场景跳过生产启动校验。
+
+## 安全策略与评估
+
+资产和信任边界不变：Node 版本来自本机运行时；MySQL 版本来自客户端 `--version` 和只读元数据查询。固定正则只接受数字版本与既有后缀，不执行输入。数据库凭据继续由忽略的本地 env 或生产 EnvironmentFile 注入，错误和健康详情不输出账号、密码或地址。
+
+残余风险是 MySQL 5.7 不同补丁可能存在已知缺陷；用户已明确接受系列级约束，项目不承诺补丁级兼容矩阵。字符规则、SQL 5.7 能力上限和迁移测试继续作为实际兼容门禁。
+
+## 性能目标与评估
+
+版本判断是启动或治理阶段的常数时间字符串匹配，健康检查仍只执行一次既有元数据查询。无新增网络调用、重试、数据库扫描、缓存操作或消息流，因此无需负载测试；目标是全量验证前后构建体积和运行流程不变。
+
+## 测试设计
+
+1. RED：新增 Schema 用例要求 5.7.41 通过，确认当前精确 5.7.42 实现失败。
+2. GREEN：服务端版本改为 5.7.x 后，验证 5.7.0、5.7.41、5.7.42-log 通过，5.6.51 与 8.0.40 拒绝。
+3. RED/GREEN：健康客户端先新增 5.7.41 成功详情断言，再修改实现；保留 8.0 拒绝和字符/排序规则/时区失败用例。
+4. Node：补充 22.0.0、22.x 高补丁和 21/23 边界，验证现有实现无需行为变更。
+5. 回归：运行 runtime、Schema、MySQL 规范、Server、全量 `pnpm verify:release` 和两个 Review 门禁。
+
+## 回退
+
+若系列校验导致历史基线失效或错误放行非 5.7 服务端，以新的中文回退提交恢复精确判断并同步恢复当前文档；禁止改写已推送历史。功能不涉及数据库结构或数据，因此无数据回滚。