Files

T

FoXiMao 426870b704 docs(GOV-011): 制定运行时系列版本实施计划

2026-08-17 17:19:38 +08:00

23 KiB

Raw Blame History

GOV-011 Node 与 MySQL 系列版本约束实施计划

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 将当前生效的运行时约束统一为 Node.js 22.x 与完整 MySQL 5.7.x，同时保留数据库字符规则、时区、安全边界和历史版本证据。

Architecture: Node.js 继续由现有语义版本解析器按主版本判断，只补充特征测试。Schema 工具和 API 健康检查分别在既有职责边界内识别 MySQL 5.7.x，不新增共享版本工具，避免在只有两个简单且上下文不同的判断点时提前抽象；健康详情从服务端返回值提取实际三段版本。现行架构、开发规范和部署文档同步采用系列口径，历史 QA、Schema 清单和已发布档案保持原样。

Tech Stack: Node.js 22.x、pnpm 10.25.0、Node.js 内置测试运行器、TypeScript 5.9.3、Vitest 3.2.7、NestJS 11、mysql2 3.23.3、MySQL 5.7.x、GitNexus、Git/Gitea。

Global Constraints

Node.js 接受格式合法的 22.x，拒绝 21.x、23.x 和无效版本；pnpm 继续使用既有 10.x 门禁。
MySQL 客户端、mysqldump 客户端、服务端和健康检查接受完整 5.7.x，不设置最低 patch，不接受 5.6.x、8.x 或 MariaDB。
数据库字符集固定 utf8mb4，排序规则固定 utf8mb4_general_ci，会话时区固定 +08:00。
Schema 基线只允许 APP_ENV=development、数据库 a_share_analysis_dev 和代码内固定开发主机白名单；禁止连接、探测或读取生产数据库。
不修改数据库 Schema、迁移、数据、连接账号、网络、HTTP DTO、OpenAPI 字段、Web API、Redis、RocketMQ、Scheduler 或 Worker 行为。
历史 QA、Schema manifest 和已发布功能档案中的 5.7.42、22.11.0、22.22.0 是实际证据，不得批量改写。
版本判断使用固定格式匹配，不执行版本字符串，不拼接 SQL，不把连接地址、账号或密码写入错误和健康详情。
不新增依赖；关键版本口径、安全边界和架构取舍使用准确中文注释，不做逐行翻译式注释。
每个行为修改遵循 RED-GREEN：先证明旧精确补丁判断失败，再写最小实现并执行局部与完整回归。
修改关键符号前复核既有 GitNexus impact；提交前执行 GitNexus detect-changes，确认影响没有超出已批准范围。
每个提交使用中文 Conventional Commit 并带 GOV-011，验证后立即推送当前分支到项目 Gitea，禁止强推。
v0.0.8 Schema 基线按 schema-baseline-waiver.md 执行一次性例外：不得伪造 N/A、空库清单或空 SQL，也不得修改治理工具增加通用跳过能力。

Task 1: 锁定 Node.js 22.x 现有行为

Files:

Modify: tools/runtime/verify-runtime.test.mjs

Interfaces:

Consumes: assertSupportedRuntime({ nodeVersion, pnpmVersion })。
Produces: Node.js 22 系列内边界、相邻主版本和无效格式的特征测试。
Preserves: tools/runtime/verify-runtime.mjs 的生产判断和 pnpm 10.x 约束。
Step 1: 补充 Node.js 系列边界测试

将现有 Node 成功样本扩展为系列内多个版本，并把相邻失败样本明确为 21.x 与 23.x：

test('接受完整 Node.js 22.x 并拒绝相邻主版本', () => {
  for (const nodeVersion of ['22.0.0', '22.11.0', '22.99.123-beta.1+build.7']) {
    assert.doesNotThrow(() =>
      assertSupportedRuntime({ nodeVersion, pnpmVersion: '10.25.0' }),
    );
  }

  for (const nodeVersion of ['21.7.3', '23.0.0']) {
    assert.throws(
      () => assertSupportedRuntime({ nodeVersion, pnpmVersion: '10.25.0' }),
      /Node\.js 必须为 22\.x/,
    );
  }
});

保留 v22、空字符串、非数字 pnpm 等既有无效格式测试，不改变 parseVersion 的输入格式契约。

Step 2: 运行特征测试并确认现有实现已满足

Run: pnpm test:runtime

Expected: PASS。该任务是对已存在的 22.x 行为补证，不修改生产代码，也不制造无意义的 RED。

Step 3: 提交并推送 Node 特征测试

git add tools/runtime/verify-runtime.test.mjs
git commit -m "test(GOV-011): 补充 Node 22 系列边界验证"
git push origin main

Expected: 推送成功，本地 HEAD 与 Gitea refs/heads/main 一致。

Task 2: 让 Schema 元数据接受完整 MySQL 5.7.x

Files:

Modify: tools/database/schema-baseline.test.mjs
Modify: tools/database/schema-baseline.mjs

Interfaces:

Consumes: assertMysql57Metadata(metadata) 及既有 MysqlMetadata 形状。
Produces: 客户端、mysqldump 和服务端统一的 5.7.<非负整数> 系列判断。
Preserves: databaseCharset === 'utf8mb4'、databaseCollation === 'utf8mb4_general_ci'、历史 manifest 格式和所有 Schema 安全门禁。
Step 1: 写入服务端 5.7.x 失败测试

把现有“5.7.41 必须失败”改成系列内成功断言，并补齐最低 patch、后缀及上下系列边界：

test('接受完整 MySQL 5.7.x 并保持固定数据库字符规则', () => {
  for (const serverVersion of ['5.7.0', '5.7.41', '5.7.42-log']) {
    assert.doesNotThrow(() => assertMysql57Metadata({ ...validMetadata, serverVersion }));
  }

  for (const serverVersion of ['5.6.51', '8.0.40', '5.7', '5.7.x', '']) {
    assert.throws(
      () => assertMysql57Metadata({ ...validMetadata, serverVersion }),
      /MySQL 服务端必须为 5\.7\.x/,
    );
  }

  assert.throws(
    () => assertMysql57Metadata({ ...validMetadata, mysqlClientVersion: '8.0.40' }),
    /mysql 客户端必须为 5\.7\.x/,
  );
  assert.throws(
    () => assertMysql57Metadata({ ...validMetadata, databaseCollation: 'utf8mb4_bin' }),
    /utf8mb4_general_ci/,
  );
});

Step 2: 运行定向测试并确认 RED

Run: node --test --test-name-pattern='完整 MySQL 5.7.x' tools/database/schema-baseline.test.mjs

Expected: FAIL，5.7.0 或 5.7.41 被当前精确 5.7.42 服务端判断拒绝；失败原因不得来自测试语法或夹具。

Step 3: 最小修改服务端系列判断

将 assertMysql57Metadata 中服务端判断改为与两个客户端相同的系列格式，并更新注释与错误信息：

/**
 * mysql、mysqldump 与服务端统一接受完整 5.7.x；字符集和排序规则仍按精确值校验，
 * 避免放宽 patch 版本时意外放宽数据库结构兼容边界。
 */
export function assertMysql57Metadata(metadata) {
  // 两个既有客户端判断保持不变。
  if (!/^5\.7\.\d+(?:[-+].*)?$/.test(metadata.serverVersion ?? '')) {
    throw new Error(`MySQL 服务端必须为 5.7.x，实际 ${metadata.serverVersion || '(空)'}`);
  }
  // 既有字符集和排序规则精确校验保持不变。
}

实际编辑只替换服务端正则、对应注释和错误文案，不复制或重排函数内其他校验。

Step 4: 运行 Schema 局部与完整回归

Run: node --test --test-name-pattern='完整 MySQL 5.7.x' tools/database/schema-baseline.test.mjs

Expected: PASS。

Run: pnpm test:schema-baseline && pnpm test:mysql-baseline && pnpm test:governance

Expected: PASS。历史 captured、captured_empty、N/A、当前发布门禁、生成入口和远程核对测试均无回归；测试不得访问真实数据库。

Step 5: 提交并推送 Schema 系列判断

在提交前执行 GitNexus detect-changes，确认只影响已记录的 Schema 生成、验证和治理调用链，然后：

git add tools/database/schema-baseline.mjs tools/database/schema-baseline.test.mjs
git commit -m "fix(GOV-011): 放宽 MySQL 服务端为完整 5.7 系列"
git push origin main

Expected: 推送成功且没有新增 Schema 文件或数据库连接副作用。

Task 3: 健康检查返回实际 MySQL 5.7.x 版本

Files:

Modify: server/libs/infrastructure/src/health-clients.test.ts
Modify: server/libs/infrastructure/src/mysql-health.client.ts

Interfaces:

Consumes: MysqlHealthClient.check(): Promise<DependencyHealthDto> 与 MYSQL_HEALTH_QUERY。
Produces: 5.7.x 成功结果 MySQL <实际三段版本> / <database> / +08:00。
Preserves: DependencyHealthDto 结构、只读元数据查询、数据库名、字符集、排序规则、时区校验和最多两个连接的池配置。
Step 1: 写入健康检查 5.7.41 失败测试

将成功夹具改为 5.7.41-log，断言详情来自返回值；移除“5.7.41 必须失败”的旧断言，增加 5.6 与 8.0 边界：

await expect(client.check()).resolves.toEqual({
  status: 'healthy',
  detail: 'MySQL 5.7.41 / a_share_analysis_dev / +08:00',
});

for (const version of ['5.6.51', '8.0.40', '5.7', '5.7.x']) {
  await expect(createClient({ version }).check()).rejects.toThrow(/MySQL 5\.7\.x/);
}

保留库名、utf8mb4、utf8mb4_general_ci 和 +08:00 漂移失败断言；如当前测试缺少字符集或时区样本，在同一测试中分别补入：

await expect(createClient({ charset: 'utf8' }).check()).rejects.toThrow(/utf8mb4/);
await expect(createClient({ timezone: 'SYSTEM' }).check()).rejects.toThrow(/\+08:00/);

Step 2: 运行定向测试并确认 RED

Run: pnpm --filter @a-share-analysis/server exec vitest run libs/infrastructure/src/health-clients.test.ts

Expected: FAIL，当前实现拒绝 5.7.41-log 或仍返回硬编码的 MySQL 5.7.42。

Step 3: 最小实现系列判断和实际版本详情

在 MysqlHealthClient.check 中只解析一次版本，并使用捕获到的三段版本构造安全详情：

const versionMatch = /^(5\.7\.\d+)(?:[-+].*)?$/.exec(row.version);
if (!versionMatch) {
  throw new Error('MySQL 5.7.x 版本要求未满足');
}

return {
  status: 'healthy',
  detail: `MySQL ${versionMatch[1]} / ${row.databaseName} / ${row.timezone}`,
};

这里不回显 -log 等服务端后缀，避免把厂商或构建附加文本直接带到用户界面；显示的三段版本仍来自服务端元数据，不再硬编码 patch。

同步把健康池注释中的 5.7.42 改为 5.7.x，连接参数不变。

Step 4: 运行后端局部与完整回归

Run: pnpm --filter @a-share-analysis/server exec vitest run libs/infrastructure/src/health-clients.test.ts

Expected: PASS。

Run: pnpm --filter @a-share-analysis/server test && pnpm --filter @a-share-analysis/server typecheck && pnpm --filter @a-share-analysis/server build

Expected: PASS；OpenAPI DTO 和生成文件无变化。

Step 5: 提交并推送健康检查变化

在提交前执行 GitNexus detect-changes，确认影响仅进入 API 健康装配流程，然后：

git add server/libs/infrastructure/src/mysql-health.client.ts server/libs/infrastructure/src/health-clients.test.ts
git commit -m "fix(GOV-011): 支持 MySQL 5.7 系列健康检查"
git push origin main

Expected: 推送成功，健康响应结构没有契约漂移。

Task 4: 统一现行代码注释与规范部署口径

Files:

Modify: tools/governance/environment-baseline.test.mjs
Modify: server/libs/config/src/runtime-config.ts
Modify: server/libs/infrastructure/src/typeorm-options.ts
Modify: docs/architecture/system-architecture.md
Modify: docs/governance/code-development-standards.md
Modify: docs/deployment/local-development.md
Modify: docs/deployment/ubuntu-source-production.md

Interfaces:

Consumes: GOV-011 已确认的现行版本文字边界。
Produces: 可机器验证的 Node.js 22.x / MySQL 5.7.x 当前规范。
Preserves: pnpm 10.25.0、Ubuntu 源码部署、systemd、Nginx、Redis、RocketMQ 和环境变量模板。
Step 1: 先把文档契约测试改为系列口径

将环境基线测试的现行文档检查从精确 5.7.42 改为 5.7.x，并显式拒绝当前文档继续写死 patch：

for (const document of [local, source]) {
  assert.match(document, /MySQL 5\.7\.x/);
  assert.doesNotMatch(document, /MySQL 5\.7\.42/);
}

再读取系统架构和代码开发规范，执行相同断言；测试只扫描这四份当前生效文档，不扫描 docs/features/、database/schema-baselines/ 或历史 QA。

Step 2: 运行环境契约并确认 RED

Run: pnpm test:environment-baseline

Expected: FAIL，现行文档仍包含 MySQL 5.7.42。

Step 3: 更新代码说明性注释

把以下当前注释统一为 MySQL 5.7.x：

MysqlRuntimeConfig 的兼容口径说明。
buildTypeOrmOptions 的 MySQL 基线说明。
createMysqlHealthClient 的会话时区说明。
assertMysql57Metadata 的客户端/服务端系列说明。

不修改类型字段、连接选项、synchronize: false、迁移配置或配置解析行为。

Step 4: 更新四份当前生效文档

逐项修改：

系统架构：开发、测试和生产统一使用 MySQL 5.7.x，禁止 5.6、8.x、MariaDB 代替验证；不再禁止其他 5.7 patch。
代码开发规范：Node.js 22.x 和 MySQL 5.7.x 是系列约束；字符集、排序规则和时区仍为精确值。
本地开发：外部 MySQL 使用 5.7.x，固定开发库与主机白名单不变。
Ubuntu 生产：管理员提供 Node.js 22.x 与外部 MySQL 5.7.x，项目仍只验证、不安装基础设施。

历史功能档案、QA、Schema manifest 和既有版本记录不修改。

Step 5: 运行文档契约与格式验证

Run: pnpm test:environment-baseline && pnpm test:deployment && pnpm format:check

Expected: PASS。

Run: rg -n "MySQL 5\.7\.42" docs/architecture docs/governance docs/deployment server/libs tools/database/schema-baseline.mjs

Expected: 当前生效代码和文档无精确 MySQL 5.7.42 口径；若命中测试夹具中的真实输入版本，只核对其用途，不改写真实样本。

Step 6: 提交并推送规范同步

git add tools/governance/environment-baseline.test.mjs \
  server/libs/config/src/runtime-config.ts \
  server/libs/infrastructure/src/typeorm-options.ts \
  server/libs/infrastructure/src/mysql-health.client.ts \
  tools/database/schema-baseline.mjs \
  docs/architecture/system-architecture.md \
  docs/governance/code-development-standards.md \
  docs/deployment/local-development.md \
  docs/deployment/ubuntu-source-production.md
git commit -m "docs(GOV-011): 统一运行时系列版本口径"
git push origin main

Expected: 推送成功；git diff --name-only 不包含任何历史功能档案或 Schema 基线文件。

Task 5: 补齐功能档案和全量验证证据

Files:

Create: docs/features/GOV-011-runtime-version-series/test-plan.md
Create: docs/features/GOV-011-runtime-version-series/development-summary.md
Create: docs/features/GOV-011-runtime-version-series/gitnexus/detected-changes.md
Create: docs/features/GOV-011-runtime-version-series/gitnexus/after.md
Create: docs/features/GOV-011-runtime-version-series/gitnexus/comparison.md
Create: docs/features/GOV-011-runtime-version-series/qa/test-results.md
Create: docs/features/GOV-011-runtime-version-series/qa/visual-qa.md
Create: docs/features/GOV-011-runtime-version-series/review/code-review.md
Create: docs/features/GOV-011-runtime-version-series/review/standards-review.md
Create: docs/features/GOV-011-runtime-version-series/release-notes.md
Create: docs/features/GOV-011-runtime-version-series/rollback.md
Modify: docs/features/GOV-011-runtime-version-series/manifest.yaml

Interfaces:

Consumes: Tasks 1-4 的测试结果、提交 SHA、GitNexus before/impact 与一次性 Schema 例外。
Produces: governance:finish 所需的完整、可审查功能档案。
Step 1: 编写测试计划和开发总结骨架

test-plan.md 必须明确列出：

Node 22.0.0、其他 22.x、21.x、23.x 和无效格式。
MySQL 5.7.0、5.7.41、5.7.42-log、5.6.51、8.0.40 和无效格式。
字符集、排序规则、库名、时区与固定开发安全边界回归。
HTTP/OpenAPI 无结构变化验证；消息、Redis、Scheduler、Worker 不受影响的边界验证。
安全验证：无生产数据库访问、无凭据泄漏、固定格式匹配、依赖未变化。
性能验证：无新增查询/任务/重试，版本匹配为常数时间；无需负载测试的原因和边界。
全量 pnpm verify:release、桌面/移动视觉回归及源码部署验证。

development-summary.md 必须用七个固定二级标题记录原始开发需求、范围变化、实际完成需求、修复缺陷、未完成与延期项、关键提交和验证证据；“没有数据库变更”必须写明原因与边界，不能只写“不适用”。

Step 2: 执行局部和全量验证

依次运行并把命令、退出码、关键计数和日期保存到 qa/test-results.md：

pnpm test:runtime
pnpm test:schema-baseline
pnpm --filter @a-share-analysis/server exec vitest run libs/infrastructure/src/health-clients.test.ts
pnpm test:environment-baseline
pnpm check:contracts
pnpm lint
pnpm format:check
pnpm typecheck
pnpm test
pnpm build
pnpm verify:e2e
pnpm verify:release
git diff --check

Expected: 全部 PASS；pnpm check:contracts 执行后 OpenAPI 和 Web 生成类型没有非预期差异。

Step 3: 完成视觉验证

启动 Web/API 的本地开发服务，复用既有 Playwright 桌面与移动视口检查首页健康展示及控制台；GOV-011 不改变页面布局，qa/visual-qa.md 仍须保存运行命令、视口、截图路径、控制台结果和“不发生视觉变化”的证据。服务结束后确认没有遗留进程。

Step 4: 执行 GitNexus 开发后检测与比较

先执行 GitNexus detect-changes，保存受影响符号、执行流和风险到 gitnexus/detected-changes.md；再运行：

npx gitnexus analyze
npx gitnexus status

将开发后节点、关系、流程、工作区摘要写入 gitnexus/after.md，把 before/after 差异和以下逐项结论写入 gitnexus/comparison.md：HTTP/OpenAPI、Web API、消息、数据库、Redis、API、Scheduler、Worker、部署、测试、文档。若出现计划外 HIGH/CRITICAL 风险或新的执行流，停止发布并回到影响分析。

Step 5: 记录 Schema 例外门禁证据

运行：

pnpm schema:verify
pnpm governance:finish -- GOV-011 runtime-version-series

Expected: 两者均因 database/schema-baselines/v0.0.8 缺失而失败。把完整错误摘要和退出码写入 qa/test-results.md，并引用 schema-baseline-waiver.md；不得把预期失败写成通过，也不得生成伪造基线。

随后手工执行 governance:finish 在 Schema 失败前要求的治理、MySQL、环境和 Schema 测试，并人工核对全部必备档案、证据章节和 Review 末行。该一次性例外只替代 v0.0.8 基线存在性，不替代任何测试、GitNexus、Review、提交或推送门禁。

Step 6: 完成两类 Review

review/code-review.md 先列发现，按严重度记录文件/行、影响和处置；必须包含“安全与残余风险”“性能与资源影响”“GitNexus 与同步修改”。review/standards-review.md 逐项核对注释、职责拆分、TDD、规范、历史证据、中文提交、Gitea 推送和一次性例外边界；必须包含“安全、性能与架构检查”“GitNexus 与开发总结检查”。

只有所有重要问题关闭后，两份报告最后一个非空行才写：

最终结论：passed

Step 7: 提交并推送完整验证档案

git add docs/features/GOV-011-runtime-version-series
git commit -m "docs(GOV-011): 完成系列版本验证与审查"
git push origin main

Expected: 推送成功，远程包含完整功能档案；提交前 GitNexus detect-changes 已保存且实际范围与影响计划一致。

Task 6: 发布 v0.0.9 并封存追溯状态

Files:

Modify: VERSION
Modify: CHANGELOG.md
Modify: docs/index.md
Modify: docs/features/GOV-011-runtime-version-series/manifest.yaml
Modify: docs/features/GOV-011-runtime-version-series/development-summary.md
Modify: docs/features/GOV-011-runtime-version-series/release-notes.md
Modify: docs/features/GOV-011-runtime-version-series/qa/test-results.md
Modify: docs/features/GOV-011-runtime-version-series/review/code-review.md
Modify: docs/features/GOV-011-runtime-version-series/review/standards-review.md

Interfaces:

Consumes: 已通过的代码、测试、Review、GitNexus 证据与用户确认的一次性 Schema 例外。
Produces: 发布提交、Gitea main 与带注释标签 v0.0.9。
Step 1: 更新版本和发布文档

将 VERSION 更新为 0.0.9；CHANGELOG.md 和 docs/index.md 记录 GOV-011 的实际完成范围、Schema 一次性例外和历史证据不改写原则。manifest.yaml 更新为 status: released、release: v0.0.9，并补齐实施计划、测试、开发总结、GitNexus、Review 文件引用。

Step 2: 执行发布前最终验证

Run: pnpm verify:release

Expected: PASS。

Run: git diff --check && git status --short && git log -1 --oneline

Expected: 只有预期发布文档变更，格式无错误；提交前再次执行 GitNexus detect-changes。

按 Task 5 重跑 pnpm schema:verify 和 pnpm governance:finish -- GOV-011 runtime-version-series，Expected 仍是已记录的一次性例外失败；确认没有新增或变化的失败原因。

Step 3: 创建并推送发布封存提交

git add VERSION CHANGELOG.md docs/index.md docs/features/GOV-011-runtime-version-series
git commit -m "chore(GOV-011): 发布 v0.0.9 系列版本约束"
git push origin main

Expected: 推送成功，本地 HEAD、origin/main 和 Gitea refs/heads/main SHA 一致。

Step 4: 创建并精确推送标签

git tag -a v0.0.9 -m "发布 v0.0.9：统一 Node 与 MySQL 系列版本约束"
git push origin refs/tags/v0.0.9

Expected: Gitea refs/tags/v0.0.9^{} 指向发布封存提交；不使用 git push --tags，不覆盖未知远程标签。

Step 5: 最终核对并封存实际 SHA

将最终分支提交和标签 SHA 回填到 development-summary.md 与 qa/test-results.md 时，使用新的中文文档提交并立即推送；如回填会使标签不再指向最终文档提交，则明确记录“标签指向发布封存提交、追溯回填位于后续文档提交”，不得移动已推送标签。

计划自审

规格覆盖：FR-001 至 FR-005、全部验收标准、安全、性能、历史证据和一次性 Schema 例外均有对应任务。
影响覆盖：assertMysql57Metadata 的 CRITICAL 调用链由 Task 2 完整回归；MysqlHealthClient 与 assertSupportedRuntime 分别由 Task 3 和 Task 1 覆盖。
类型一致性：计划只消费既有 assertSupportedRuntime、assertMysql57Metadata、MysqlHealthClient.check 和 DependencyHealthDto，没有新增跨任务接口或命名漂移。
范围控制：不新增依赖、不改 DTO/生成契约、不改数据库结构、不接触生产数据库、不批量改写历史证据。
占位符检查：未发现待补内容、跨任务省略引用或无验证方式的实现步骤；每个代码行为都有精确测试命令和预期结果。
回退可行：功能只修改判断、详情文字、注释和文档；出现历史基线失效或错误放行时，可用中文回退提交恢复基线行为，不需要数据回滚。

23 KiB Raw Blame History Unescape Escape

GOV-011 Node 与 MySQL 系列版本约束实施计划

Global Constraints

Task 1: 锁定 Node.js 22.x 现有行为

Task 2: 让 Schema 元数据接受完整 MySQL 5.7.x

Task 3: 健康检查返回实际 MySQL 5.7.x 版本

Task 4: 统一现行代码注释与规范部署口径

Task 5: 补齐功能档案和全量验证证据

Task 6: 发布 v0.0.9 并封存追溯状态

计划自审

23 KiB

Raw Blame History