From fcfef2d52423eb81425f194e6c6dd3dae0a492ae Mon Sep 17 00:00:00 2001 From: Citrons <909229731@qq.com> Date: Mon, 17 Aug 2026 17:01:39 +0800 Subject: [PATCH] =?UTF-8?q?docs(GOV-011):=20=E7=A1=AE=E8=AE=A4=E7=B3=BB?= =?UTF-8?q?=E5=88=97=E7=89=88=E6=9C=AC=E7=BA=A6=E6=9D=9F=E8=AE=BE=E8=AE=A1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 2 +- .../GOV-011-runtime-version-series/design.md | 74 +++++++++++++++++++ .../gitnexus/before.md | 29 ++++++++ .../gitnexus/impact-plan.md | 39 ++++++++++ .../manifest.yaml | 13 ++++ .../GOV-011-runtime-version-series/prd.md | 33 +++++++++ .../requirements.md | 22 ++++++ .../schema-baseline-waiver.md | 22 ++++++ docs/index.md | 1 + 9 files changed, 234 insertions(+), 1 deletion(-) create mode 100644 docs/features/GOV-011-runtime-version-series/design.md create mode 100644 docs/features/GOV-011-runtime-version-series/gitnexus/before.md create mode 100644 docs/features/GOV-011-runtime-version-series/gitnexus/impact-plan.md create mode 100644 docs/features/GOV-011-runtime-version-series/manifest.yaml create mode 100644 docs/features/GOV-011-runtime-version-series/prd.md create mode 100644 docs/features/GOV-011-runtime-version-series/requirements.md create mode 100644 docs/features/GOV-011-runtime-version-series/schema-baseline-waiver.md diff --git a/AGENTS.md b/AGENTS.md index a894f06..b1aa141 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,7 +29,7 @@ # GitNexus — Code Intelligence -This project is indexed by GitNexus as **a-share-analysis** (1957 symbols, 2634 relationships, 50 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** (2004 symbols, 2681 relationships, 50 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/docs/features/GOV-011-runtime-version-series/design.md b/docs/features/GOV-011-runtime-version-series/design.md new file mode 100644 index 0000000..68df3ba --- /dev/null +++ b/docs/features/GOV-011-runtime-version-series/design.md @@ -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 服务端，以新的中文回退提交恢复精确判断并同步恢复当前文档；禁止改写已推送历史。功能不涉及数据库结构或数据，因此无数据回滚。 diff --git a/docs/features/GOV-011-runtime-version-series/gitnexus/before.md b/docs/features/GOV-011-runtime-version-series/gitnexus/before.md new file mode 100644 index 0000000..99cc114 --- /dev/null +++ b/docs/features/GOV-011-runtime-version-series/gitnexus/before.md @@ -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` 自动门禁通过。 diff --git a/docs/features/GOV-011-runtime-version-series/gitnexus/impact-plan.md b/docs/features/GOV-011-runtime-version-series/gitnexus/impact-plan.md new file mode 100644 index 0000000..7d1f6b7 --- /dev/null +++ b/docs/features/GOV-011-runtime-version-series/gitnexus/impact-plan.md @@ -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 并确认实际执行流未超出本计划。 diff --git a/docs/features/GOV-011-runtime-version-series/manifest.yaml b/docs/features/GOV-011-runtime-version-series/manifest.yaml new file mode 100644 index 0000000..f774517 --- /dev/null +++ b/docs/features/GOV-011-runtime-version-series/manifest.yaml @@ -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 diff --git a/docs/features/GOV-011-runtime-version-series/prd.md b/docs/features/GOV-011-runtime-version-series/prd.md new file mode 100644 index 0000000..e8dcb9c --- /dev/null +++ b/docs/features/GOV-011-runtime-version-series/prd.md @@ -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 通过。 diff --git a/docs/features/GOV-011-runtime-version-series/requirements.md b/docs/features/GOV-011-runtime-version-series/requirements.md new file mode 100644 index 0000000..f00ee29 --- /dev/null +++ b/docs/features/GOV-011-runtime-version-series/requirements.md @@ -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。 +- 数据库访问仍限于既有只读元数据查询；本功能不连接生产数据库。 +- 运行时只增加常数时间字符串判断，不产生可测量的吞吐或内存影响。 diff --git a/docs/features/GOV-011-runtime-version-series/schema-baseline-waiver.md b/docs/features/GOV-011-runtime-version-series/schema-baseline-waiver.md new file mode 100644 index 0000000..87aaa85 --- /dev/null +++ b/docs/features/GOV-011-runtime-version-series/schema-baseline-waiver.md @@ -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 或数据写入。 diff --git a/docs/index.md b/docs/index.md index 96084e8..4d57261 100644 --- a/docs/index.md +++ b/docs/index.md @@ -47,5 +47,6 @@ - [GOV-008：RocketMQ 消息队列架构调整](features/GOV-008-rocketmq-adoption/manifest.yaml) - [GOV-009：应用工程脚手架基线](features/GOV-009-application-scaffold-baseline/manifest.yaml) - [GOV-010：开发质量与前后端架构规范](features/GOV-010-development-quality-architecture/manifest.yaml) +- [GOV-011：Node 与 MySQL 系列版本约束](features/GOV-011-runtime-version-series/manifest.yaml) 功能档案是需求、设计、代码、测试、版本和回退之间的唯一正式关联入口。