75 lines
5.2 KiB
Markdown
75 lines
5.2 KiB
Markdown
# 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 服务端，以新的中文回退提交恢复精确判断并同步恢复当前文档；禁止改写已推送历史。功能不涉及数据库结构或数据，因此无数据回滚。
|