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 能力上限和迁移测试继续作为实际兼容门禁。

性能目标与评估

版本判断是启动或治理阶段的常数时间字符串匹配，健康检查仍只执行一次既有元数据查询。无新增网络调用、重试、数据库扫描、缓存操作或消息流，因此无需负载测试；目标是全量验证前后构建体积和运行流程不变。

测试设计

RED：新增 Schema 用例要求 5.7.41 通过，确认当前精确 5.7.42 实现失败。
GREEN：服务端版本改为 5.7.x 后，验证 5.7.0、5.7.41、5.7.42-log 通过，5.6.51 与 8.0.40 拒绝。
RED/GREEN：健康客户端先新增 5.7.41 成功详情断言，再修改实现；保留 8.0 拒绝和字符/排序规则/时区失败用例。
Node：补充 22.0.0、22.x 高补丁和 21/23 边界，验证现有实现无需行为变更。
回归：运行 runtime、Schema、MySQL 规范、Server、全量 pnpm verify:release 和两个 Review 门禁。

回退

若系列校验导致历史基线失效或错误放行非 5.7 服务端，以新的中文回退提交恢复精确判断并同步恢复当前文档；禁止改写已推送历史。功能不涉及数据库结构或数据，因此无数据回滚。

5.2 KiB Raw Permalink Blame History Unescape Escape