docs(GOV-011): 确认系列版本约束设计
This commit is contained in:
@@ -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 服务端，以新的中文回退提交恢复精确判断并同步恢复当前文档；禁止改写已推送历史。功能不涉及数据库结构或数据，因此无数据回滚。
|
||||
@@ -0,0 +1,29 @@
|
||||
# GitNexus 开发前基线
|
||||
|
||||
- 功能编号：GOV-011
|
||||
- 记录时间：2026年08月17日 16:57:31 CST
|
||||
- 分支：main
|
||||
- 基线提交：`9e858090966e`
|
||||
- 创建方式：用户授权跳过 v0.0.8 Schema 备份后，按 `governance:start` 输出结构手工留痕
|
||||
|
||||
## 工作区
|
||||
|
||||
```text
|
||||
(干净)
|
||||
```
|
||||
|
||||
## GitNexus 状态
|
||||
|
||||
```text
|
||||
Repository: /Users/citrons/Documents/Codex/2026-08-12/wo-x/a-share-analysis
|
||||
Indexed commit: 9e85809
|
||||
Current commit: 9e85809
|
||||
Status: up-to-date
|
||||
Nodes: 1,957
|
||||
Edges: 2,634
|
||||
Flows: 50
|
||||
```
|
||||
|
||||
## Schema 门禁例外
|
||||
|
||||
未运行成功的原因、用户决定、禁止伪造边界和残余风险见 `../schema-baseline-waiver.md`。本记录不表示 `governance:start` 自动门禁通过。
|
||||
@@ -0,0 +1,39 @@
|
||||
# GitNexus 开发前影响计划
|
||||
|
||||
- 功能编号：GOV-011
|
||||
- 基线提交：`9e858090966e`
|
||||
- 总体风险：CRITICAL（Schema 门禁中心符号）
|
||||
|
||||
## 直接与间接影响
|
||||
|
||||
### `assertMysql57Metadata`
|
||||
|
||||
- 风险：CRITICAL。
|
||||
- 直接调用方：5 个，包括 Schema 测试、captured、captured_empty、历史目录验证和基线生成。
|
||||
- 间接影响：10 个符号、5 组流程；深度 2 包含当前发布基线验证和远程发布核对，深度 3 到达 `governance:start`。
|
||||
- 控制：测试先行，系列内/外边界、历史 manifest、当前发布门禁和生成路径完整回归。
|
||||
|
||||
### `MysqlHealthClient`
|
||||
|
||||
- 风险：LOW。
|
||||
- 直接依赖：4 个；总计 7 个受影响符号、1 组 API 装配流程。
|
||||
- 控制：健康客户端测试覆盖实际版本详情、8.x 拒绝和字符/时区边界，API DTO 不变。
|
||||
|
||||
### `assertSupportedRuntime`
|
||||
|
||||
- 风险：LOW。
|
||||
- 只有运行时测试 1 个直接调用者，0 条业务流程；现有实现已按主版本 22 校验。
|
||||
- 控制：只补系列边界测试和现行文档，不改变生产判断。
|
||||
|
||||
## 跨模块同步修改
|
||||
|
||||
- HTTP/OpenAPI：结构不变，健康 detail 文本显示实际 5.7.x；不改 DTO。
|
||||
- Web API：无需修改，现有 adapter 透传 detail。
|
||||
- 消息、Redis、Scheduler、Worker：无影响。
|
||||
- 数据库：只调整版本判断，不改 Schema、迁移、查询或数据。
|
||||
- 配置部署：注释和前置条件改为 Node.js 22.x、MySQL 5.7.x；源码部署方式不变。
|
||||
- 测试文档：runtime、Schema、健康客户端、MySQL 规范、架构、开发规范和部署手册同步修改；历史已发布事实不改写。
|
||||
|
||||
## 高风险处置
|
||||
|
||||
若 Schema 历史清单验证失败、5.6/8.x 被放行、字符规则校验被绕过或 `governance:start` 相关回归失败，立即停止实施并恢复到基线提交的行为。提交前必须执行 GitNexus detect-changes 并确认实际执行流未超出本计划。
|
||||
@@ -0,0 +1,13 @@
|
||||
id: GOV-011
|
||||
name: Node 与 MySQL 系列版本约束
|
||||
slug: runtime-version-series
|
||||
status: designing
|
||||
owner: project
|
||||
created_at: 2026-08-17
|
||||
prd: prd.md
|
||||
requirements: requirements.md
|
||||
design: design.md
|
||||
schema_baseline_waiver: schema-baseline-waiver.md
|
||||
gitnexus_before: gitnexus/before.md
|
||||
gitnexus_impact: gitnexus/impact-plan.md
|
||||
release: unreleased
|
||||
@@ -0,0 +1,33 @@
|
||||
# Node 与 MySQL 系列版本约束 PRD
|
||||
|
||||
- 功能编号：GOV-011
|
||||
- 状态：设计复核
|
||||
- 日期：2026-08-17
|
||||
|
||||
## 背景
|
||||
|
||||
项目目标基线一直是 Node.js 22.x 与 MySQL 5.7.x，但部分实现、错误提示和现行规范把实际开发环境的 MySQL 5.7.42 写成了唯一允许的补丁版本。Node 运行时已经按 22 主版本校验，只是历史验证记录会显示实际使用的 22.11.0 或 22.22.0。用户明确说明本项目主要由本人部署，不需要锁定某个补丁版本，希望现行口径统一为系列版本。
|
||||
|
||||
## 目标
|
||||
|
||||
- Node.js 接受全部格式合法的 22.x，拒绝其他主版本。
|
||||
- MySQL 客户端、mysqldump、服务端和运行时健康检查接受全部格式合法的 5.7.x，拒绝 5.6.x、8.x 及其他系列。
|
||||
- 字符集 `utf8mb4`、排序规则 `utf8mb4_general_ci`、会话时区 `+08:00`、固定开发库和主机白名单继续严格校验。
|
||||
- 健康结果展示服务端返回的实际版本，不再硬编码 5.7.42。
|
||||
- 当前规范统一使用系列口径，历史 QA、Schema 清单和已发布档案继续保留当时真实补丁版本。
|
||||
|
||||
## 非目标
|
||||
|
||||
- 不升级 Node、MySQL、pnpm、数据库驱动或 ORM。
|
||||
- 不修改数据库结构、数据、账号、网络或部署方式。
|
||||
- 不支持 Node 23、MySQL 8.x、MariaDB 或其他“兼容 MySQL”数据库。
|
||||
- 不为各补丁版本建立兼容矩阵或自动安装运行时。
|
||||
|
||||
## 验收标准
|
||||
|
||||
1. Node 22.0.0、22.11.0 和带预发布/构建后缀的合法 22.x 版本通过；21.x、23.x 和无效格式拒绝。
|
||||
2. MySQL 5.7.0、5.7.41、5.7.42-log 等合法 5.7.x 通过；5.6.x、8.0.x 和无效格式拒绝。
|
||||
3. MySQL 5.7.x 即使版本通过，字符集、排序规则、库名或时区错误仍拒绝。
|
||||
4. 既有 v0.0.5 至 v0.0.7 Schema 历史清单继续验证，不被改写。
|
||||
5. 健康详情包含实际服务端版本；不泄漏连接地址、账号或密码。
|
||||
6. 全量测试、构建、Playwright、源码发布门禁和两类 Review 通过。
|
||||
@@ -0,0 +1,22 @@
|
||||
# Node 与 MySQL 系列版本约束需求
|
||||
|
||||
## 功能需求
|
||||
|
||||
- FR-001：运行时门禁必须以主版本 22 判断 Node.js，不绑定 minor 或 patch。
|
||||
- FR-002：Schema 生成与验证必须以 major/minor 5.7 判断 mysql 客户端、mysqldump 客户端和 MySQL 服务端，不绑定 patch。
|
||||
- FR-003：API MySQL 健康检查必须接受任意 5.7.x，并在成功详情中显示实际版本。
|
||||
- FR-004：MySQL 5.7.x 系列校验不得放宽数据库名、字符集、排序规则、时区或开发环境安全边界。
|
||||
- FR-005：现行架构、开发规范和部署手册必须使用 Node.js 22.x、MySQL 5.7.x；历史证据中的实际版本不批量改写。
|
||||
|
||||
## 质量需求
|
||||
|
||||
- 必须测试系列内至少两个不同补丁版本和系列外上下边界。
|
||||
- 必须遵循 RED → GREEN：先让 5.7.41 被精确 5.7.42 校验拒绝，再实施系列校验。
|
||||
- `assertMysql57Metadata` 的 GitNexus 风险为 CRITICAL，必须完整回归 Schema 生成、历史验证、当前发布基线和治理启动相关测试。
|
||||
- 不新增依赖，不增加生产请求、数据库查询或后台任务。
|
||||
|
||||
## 安全与性能
|
||||
|
||||
- 版本字符串只做固定格式匹配，不执行命令、不拼接 SQL。
|
||||
- 数据库访问仍限于既有只读元数据查询；本功能不连接生产数据库。
|
||||
- 运行时只增加常数时间字符串判断，不产生可测量的吞吐或内存影响。
|
||||
@@ -0,0 +1,22 @@
|
||||
# v0.0.8 Schema 基线一次性例外
|
||||
|
||||
- 功能编号：GOV-011
|
||||
- 日期：2026-08-17
|
||||
- 适用范围：仅 GOV-011 开发启动
|
||||
|
||||
## 事实记录
|
||||
|
||||
按常规流程执行 `pnpm schema:baseline` 时，本机因不存在 MySQL 5.7 `mysql`/`mysqldump` 客户端而在执行 `mysql --version` 前失败，未连接数据库、未生成目录或半成品；随后 `schema:verify` 因 `database/schema-baselines/v0.0.8` 不存在而按设计阻断。
|
||||
|
||||
用户确认当前开发库没有业务结构，并明确要求本次先跳过备份。GOV-011 只调整 Node/MySQL 版本系列判断，不创建表、迁移或数据，不读取生产数据库。
|
||||
|
||||
## 处理决定
|
||||
|
||||
- 不伪造 `not_applicable`、`captured_empty`、空 SQL、版本信息或校验摘要。
|
||||
- 不修改 `governance:start` 或 Schema 工具增加通用跳过开关。
|
||||
- 手工保存与 `governance:start` 同等的 GitNexus before/impact 文档，并在 GOV-011 Review 中核对本例外。
|
||||
- 本例外不自动适用于后续功能；下一次需要 Schema 基线时仍应提供可验证的 MySQL 5.7.x 客户端或由用户再次明确决定。
|
||||
|
||||
## 风险
|
||||
|
||||
缺少 v0.0.8 Schema 基线意味着无法用仓库证据证明当时开发库为空。该风险由用户接受；GOV-011 不修改数据库，不能借本例外执行任何 Schema 或数据写入。
|
||||
Reference in New Issue
Block a user