522 lines
24 KiB
Markdown
522 lines
24 KiB
Markdown
# 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：
|
||
|
||
```js
|
||
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 特征测试**
|
||
|
||
```bash
|
||
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、后缀及上下系列边界：
|
||
|
||
```js
|
||
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` 中服务端判断改为与两个客户端相同的系列格式，并更新注释与错误信息：
|
||
|
||
```js
|
||
/**
|
||
* 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 生成、验证和治理调用链，然后：
|
||
|
||
```bash
|
||
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 边界：
|
||
|
||
```ts
|
||
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` 漂移失败断言；如当前测试缺少字符集或时区样本，在同一测试中分别补入：
|
||
|
||
```ts
|
||
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` 中只解析一次版本，并使用捕获到的三段版本构造安全详情：
|
||
|
||
```ts
|
||
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 健康装配流程，然后：
|
||
|
||
```bash
|
||
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：
|
||
|
||
```js
|
||
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: 提交并推送规范同步**
|
||
|
||
```bash
|
||
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`：
|
||
|
||
```bash
|
||
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: 除 `pnpm verify:release` 因已授权的 v0.0.8 Schema 基线缺失而失败外，其余命令 PASS；`pnpm check:contracts` 执行后 OpenAPI 和 Web 生成类型没有非预期差异。必须继续手工执行 `verify:release` 在 Schema 失败点之后的构建、E2E 和源码发布门禁。
|
||
|
||
- [ ] **Step 3: 完成视觉验证**
|
||
|
||
启动 Web/API 的本地开发服务，复用既有 Playwright 桌面与移动视口检查首页健康展示及控制台；GOV-011 不改变页面布局，`qa/visual-qa.md` 仍须保存运行命令、视口、截图路径、控制台结果和“不发生视觉变化”的证据。服务结束后确认没有遗留进程。
|
||
|
||
- [ ] **Step 4: 执行 GitNexus 开发后检测与比较**
|
||
|
||
先执行 GitNexus detect-changes，保存受影响符号、执行流和风险到 `gitnexus/detected-changes.md`；再运行：
|
||
|
||
```bash
|
||
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 例外门禁证据**
|
||
|
||
运行：
|
||
|
||
```bash
|
||
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 与开发总结检查”。
|
||
|
||
只有所有重要问题关闭后，两份报告最后一个非空行才写：
|
||
|
||
```text
|
||
最终结论：passed
|
||
```
|
||
|
||
- [ ] **Step 7: 提交并推送完整验证档案**
|
||
|
||
```bash
|
||
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: 因已授权的一次性例外，在 v0.0.8 Schema 严格发布基线检查处失败；失败点之前的门禁和手工补跑的后续构建、E2E、源码发布验证必须全部通过，且真实结果写入 QA。
|
||
|
||
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: 创建并推送发布封存提交**
|
||
|
||
```bash
|
||
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: 创建并精确推送标签**
|
||
|
||
```bash
|
||
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/生成契约、不改数据库结构、不接触生产数据库、不批量改写历史证据。
|
||
- 占位符检查：未发现待补内容、跨任务省略引用或无验证方式的实现步骤；每个代码行为都有精确测试命令和预期结果。
|
||
- 回退可行：功能只修改判断、详情文字、注释和文档；出现历史基线失效或错误放行时，可用中文回退提交恢复基线行为，不需要数据回滚。
|