Compare commits

8 Commits
38 changed files with 1260 additions and 54 deletions
+1 -1
View File
@@ -29,7 +29,7 @@
<!-- gitnexus:start -->
# 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** (2015 symbols, 2692 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.
+8
View File
@@ -4,6 +4,14 @@
## Unreleased
## 0.0.9 - 2026-08-17
- Node.js 运行时约束明确为完整 22.x,不绑定 minor 或 patch。
- MySQL 客户端、mysqldump、服务端和健康检查统一接受完整 5.7.x,不设置最低补丁版本。
- MySQL 健康详情改为展示服务端实际三段版本,字符集、排序规则、库名和东八区时区继续严格校验。
- 系统架构、开发规范、本地开发和 Ubuntu 源码部署手册统一采用系列版本口径,历史版本证据保持原样。
- 用户确认开发库为空并授权 GOV-011 一次性跳过 v0.0.8 Schema 基线;仓库未伪造基线或增加通用绕过开关。
## 0.0.8 - 2026-08-17
- 新增安全、性能、GitNexus 跨模块影响和独立开发总结的可执行治理门禁。
+1 -1
View File
@@ -1 +1 @@
0.0.8
0.0.9
+2 -2
View File
@@ -60,10 +60,10 @@ OpenAPI 负责描述本项目 HTTP 契约,Axios 负责浏览器实际请求。
## 4. 数据库技术基线
- 数据库服务端固定使用 MySQL 5.7.42;开发、测试和生产环境禁止使用其他补丁版本或 MySQL 8.x 代替兼容性验证。
- 数据库服务端统一使用 MySQL 5.7.x;开发、测试和生产环境禁止使用 MySQL 5.6.x、8.x、MariaDB 或其他数据库代替兼容性验证,但不锁定 5.7 系列内的补丁版本。
- 数据库与表默认字符集固定为 `utf8mb4`,排序规则固定为 `utf8mb4_general_ci`。
- 数据库初始化、表结构、连接会话、ORM 配置和迁移脚本必须显式声明或验证该字符集与排序规则,不能依赖服务器默认值。
- 正式启用持久化前,必须在真实 MySQL 5.7 环境验证服务端版本、Schema/表排序规则、迁移和关键查询。
- 正式启用持久化前,必须在真实 MySQL 5.7.x 环境验证服务端版本、Schema/表排序规则、迁移和关键查询。
- 第一阶段市场概览只定义 MySQL Repository 接口并使用内存实现,不启动数据库、不建立生产连接;后续启用时不得改变前端 API 和核心分析契约。
## 5. 当前实施顺序
+2 -2
View File
@@ -1,6 +1,6 @@
# 本地开发环境
本地开发由开发机提供 Node.js 22.x、pnpm 10.25.0 和已开机自启的 Redis `127.0.0.1:6379`。Web、API、Scheduler 与 Worker 全部从源码启动;MySQL 5.7.42 和 RocketMQ 5.x 也是外部服务,项目脚本不负责安装、启动、停止或删除任何基础设施。
本地开发由开发机提供 Node.js 22.x、pnpm 10.25.0 和已开机自启的 Redis `127.0.0.1:6379`。Web、API、Scheduler 与 Worker 全部从源码启动;MySQL 5.7.x 和 RocketMQ 5.x 也是外部服务,项目脚本不负责安装、启动、停止或删除任何基础设施。
## 首次准备
@@ -16,7 +16,7 @@ Redis 必须返回 `PONG`。如果不可达,应先修复开发机外部服务
把 `deploy/env/development/*.env.example` 复制为同目录的 `*.env.local`。四份 local 文件被 Git 忽略:Web 只能含 `VITE_` 公开变量;API、Scheduler、Worker 按最小权限分别读取自己的配置,不共享一份全能 env。
固定开发 MySQL 只允许 `a_share_analysis_dev`,主机必须是回环地址或代码内白名单 `112.192.20.11`,服务端固定为 MySQL 5.7.42,字符集为 `utf8mb4`、排序规则为 `utf8mb4_general_ci`、会话时区为 `+08:00`。Schema 工具和开发检查禁止连接、探测或读取生产库。
固定开发 MySQL 只允许 `a_share_analysis_dev`,主机必须是回环地址或代码内白名单 `112.192.20.11`,服务端必须属于 MySQL 5.7.x 且不限制系列内补丁版本,字符集为 `utf8mb4`、排序规则为 `utf8mb4_general_ci`、会话时区为 `+08:00`。Schema 工具和开发检查禁止连接、探测或读取生产库。
## 启动顺序
+1 -1
View File
@@ -1,6 +1,6 @@
# Ubuntu 源码生产部署
这是项目唯一生产部署方式,支持 Ubuntu 22.04 LTS 与 Ubuntu 24.04 LTS x86_64。服务器管理员预先提供 Node.js 22.x、pnpm 10.25.0、Nginx,以及外部 MySQL 5.7.42、Redis、RocketMQ 5.x;项目不负责安装、升级、启动、停止、删除或修改这些系统软件与服务。
这是项目唯一生产部署方式,支持 Ubuntu 22.04 LTS 与 Ubuntu 24.04 LTS x86_64。服务器管理员预先提供 Node.js 22.x、pnpm 10.25.0、Nginx,以及外部 MySQL 5.7.x、Redis、RocketMQ 5.x;项目不负责安装、升级、启动、停止、删除或修改这些系统软件与服务。
## 构建发布目录
@@ -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,59 @@
# GOV-011 开发总结
- 功能编号:GOV-011
- 日期:2026-08-17
- 当前状态:已随 v0.0.9 发布
## 原始开发需求
用户要求 Node.js 和 MySQL 不绑定具体小版本:Node.js 使用 22.x,MySQL 使用完整 5.7.x,不设置最低补丁版本。`utf8mb4`、`utf8mb4_general_ci` 和东八区时区等既有严格约束继续保留;历史证据中的实际版本不得改写。
## 需求与范围变化
- Node 生产判断原本已经按主版本 22 校验,本次只补充系列内/外特征测试,没有改写生产逻辑。
- MySQL 服务端从精确 5.7.42 调整为合法 5.7.x,客户端和 mysqldump 原有 5.7.x 约束保持不变。
- 健康详情从硬编码 patch 改为服务端元数据中的三段版本;`-log` 等附加文本不回显。
- 现行架构、开发规范、本地/Ubuntu 部署手册统一为系列口径;v0.0.8 CHANGELOG、历史 QA、Schema manifest 和已发布档案继续保存真实 5.7.42、22.11.0、22.22.0。
- 用户确认当前开发库无业务结构并授权本次跳过 v0.0.8 Schema 备份。该决定只形成 GOV-011 一次性例外,不增加通用跳过开关。
## 实际完成需求
| 需求 | 状态 | 实际结果 |
|---|---|---|
| Node.js 22.x 系列约束 | 已完成 | 覆盖 22.0.0、常规 22.x、带后缀 22.x 与 21/23 边界;生产判断保持 `major === 22`。 |
| MySQL 服务端完整 5.7.x | 已完成 | Schema 元数据接受 5.7.0、5.7.41、5.7.42-log,拒绝 5.6、8.0 和无效格式。 |
| 健康检查实际版本 | 已完成 | `5.7.41-log` 返回 `MySQL 5.7.41 / ...`;DTO 与查询结构不变。 |
| 字符规则和时区保持严格 | 已完成 | `utf8mb4`、`utf8mb4_general_ci`、库名和 `+08:00` 失败用例全部保留并扩充。 |
| 当前规范统一系列口径 | 已完成 | 架构、开发规范、本地开发、Ubuntu 生产和说明性代码注释已更新。 |
| 历史证据保持原样 | 已完成 | 未批量改写历史功能档案、QA、Schema 基线或 v0.0.8 发布事实。 |
## 修复缺陷
- 修复 Schema 服务端校验把开发机实际 5.7.42 当作唯一合法 patch 的约束错误。
- 修复 API 健康检查拒绝其他合法 5.7.x 且成功详情硬编码 5.7.42 的问题。
- 修复当前架构、开发规范和部署手册将补丁版本误写成跨环境强制基线的问题。
- 完整 Schema 回归发现一处测试仍断言旧错误文案,已同步为 `5.7.x` 并重新验证。
## 未完成与延期项
- 本功能没有数据库结构、迁移或数据变更,因此不存在数据回滚或真实 Schema 导出结果。
- v0.0.8 Schema 基线没有生成。`verify:release`、`schema:verify` 和 `governance:finish` 会在该缺失条件失败;这是用户已接受的追溯风险,不代表其他测试通过,也不会延伸到后续功能。
- 不建立 MySQL 各 patch 的自动兼容矩阵;未来遇到特定补丁缺陷时通过独立功能或 ADR 决定是否提高最低版本。
## 关键提交
| 提交 | 中文摘要 | 推送状态 |
|---|---|---|
| `426870b` | `docs(GOV-011): 制定运行时系列版本实施计划` | 已推送 Gitea |
| `c8277ef` | `test(GOV-011): 补充 Node 22 系列边界验证` | 已推送 Gitea |
| `54499f0` | `fix(GOV-011): 放宽 MySQL 服务端为完整 5.7 系列` | 已推送 Gitea |
| `dc8da80` | `fix(GOV-011): 支持 MySQL 5.7 系列健康检查` | 已推送 Gitea |
| `cce77aa` | `docs(GOV-011): 统一运行时系列版本口径` | 已推送 Gitea |
## 验证证据
- TDD:Schema 的 5.7.0/5.7.41 成功用例先被旧精确判断拒绝;健康检查的 5.7.41-log 用例先被旧实现拒绝,随后最小修改转绿。
- 排除已授权严格发布基线用例后,Schema 28/28;runtime 3/3、governance 10/10、MySQL 2/2、环境 10/10、契约 3/3、边界 16/16、部署 6/6、Web 11/11、Server 30/30、API 预检 2/2。
- lint、格式、类型检查、OpenAPI 契约、Web/Server 构建、Playwright 4/4 和源码发布验证通过。
- GitNexus 相对 v0.0.8 检测为 23 个文件、70 个符号、11 条受影响流程、HIGH;运行流仅落在既定 Schema 与健康检查边界,详见 `gitnexus/`。
- 依赖审计为 0 已知漏洞,Redis 返回 `PONG`;两张视觉截图无溢出或控制台错误。
@@ -0,0 +1,17 @@
# GitNexus 开发后基线
- 索引提交:`cce77aa`
- 索引时间:2026-08-17 17:43(Asia/Shanghai)
- 状态:up-to-date
- 节点:2015
- 关系:2692
- 集群:49
- 执行流:50
## 工作区状态
实现提交均已推送 `origin/main`。索引刷新后仅有 GitNexus 自动更新的 `AGENTS.md` 计数、GOV-011 最终证据和视觉截图等待后续文档提交。
## 运行边界
开发后新增或变化的运行流程仍只有 Schema 治理和 API 健康装配。Web 页面、Scheduler、Worker、Redis 与 RocketMQ 没有新增执行流。
@@ -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,29 @@
# GitNexus 前后对比
- before:1894 个符号、2569 条关系、50 条流程(GOV-011 启动记录)
- after:2015 个节点、2692 条关系、50 条流程(`cce77aa`)
- 相对 v0.0.8 detect-changes:23 个文件、70 个符号、11 条受影响流程、HIGH
## 差异解释
节点与关系增长主要来自 GOV-011 新增功能档案、实施计划、测试名称和当前规范标题。执行流总数仍为 50,没有出现新的生产流程。HIGH 风险由 Schema 中心函数的多条既有调用链贡献,和开发前 CRITICAL 评估方向一致。
## 跨模块核对
| 模块 | 结论 |
|---|---|
| HTTP/OpenAPI | DTO 和字段不变;健康 `detail` 文本显示实际 patch。 |
| Web API | 请求函数、adapter 和页面均未修改。 |
| 消息 | RocketMQ 契约、Topic、Group 和 Adapter 未修改。 |
| 数据库 | 不改 Schema、迁移、数据和查询范围;只放宽版本判断。 |
| Redis | 无代码和配置变化。 |
| API | MySQL 健康版本判断和详情变化,完整 Server 回归通过。 |
| Scheduler | 无行为变化,构建和进程测试通过。 |
| Worker | 无行为变化,构建和进程测试通过。 |
| 部署 | 拓扑不变,只把前置 MySQL 文案改为 5.7.x。 |
| 测试 | 新增系列边界、实际版本详情和当前文档契约。 |
| 文档 | 架构、规范、部署和功能档案同步更新;历史证据保留。 |
## 风险结论
没有发现计划外模块影响。残余风险是不同 MySQL 5.7 patch 自身可能存在缺陷,以及 v0.0.8 缺少可验证 Schema 基线;前者由真实迁移/查询验证控制,后者由用户接受的一次性例外记录控制。
@@ -0,0 +1,34 @@
# GitNexus 实际变更检测
- 比较基线:`v0.0.8` / `9e85809`
- 实现提交:`cce77aa`
- 结果:23 个文件、70 个符号、11 条受影响流程
- 风险:HIGH
## 变更符号
核心运行时符号为:
- `assertMysql57Metadata`
- `runBaselineGeneration`
- `MysqlHealthClient`
- `MysqlHealthClient.check`
- `createMysqlHealthClient`
- `assertSupportedRuntime` 只新增测试,没有生产实现变化
其余符号主要来自架构、规范、部署和 GOV-011 功能档案的 Markdown 标题,以及治理测试中的局部变量。
## 受影响执行流
- `RunBaselineGeneration → RequireExactValue`
- `AssertCurrentReleasedBaselinePublished → RequireExactValue`
- `BuildCapturedArtifacts → RequireExactValue`
- `AssertCurrentReleasedBaseline → RequireExactValue`
- `RunCommandLine` 到 `RequireExactValue`、`IsEnabled`、`ParseManifest`、`AssertExactFileSet`、`BuildManifest` 和 `ParseEnvironmentFile`
- `UseFactory → MysqlHealthClient`
HIGH 来自 Schema 中心入口映射到多条治理流程,不是新增网络、数据库写入或消息链路。排除用户已授权的 v0.0.8 基线缺失用例后,Schema 28 项全部通过;API 健康、Server 测试、类型和构建也全部通过。
## 范围结论
实际变化与开发前影响计划一致。没有新的 HTTP 字段、OpenAPI DTO、Web API、Redis、RocketMQ、Scheduler、Worker、数据库 Schema 或部署拓扑变化。
@@ -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,521 @@
# 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/生成契约、不改数据库结构、不接触生产数据库、不批量改写历史证据。
- 占位符检查:未发现待补内容、跨任务省略引用或无验证方式的实现步骤;每个代码行为都有精确测试命令和预期结果。
- 回退可行:功能只修改判断、详情文字、注释和文档;出现历史基线失效或错误放行时,可用中文回退提交恢复基线行为,不需要数据回滚。
@@ -0,0 +1,21 @@
id: GOV-011
name: Node 与 MySQL 系列版本约束
slug: runtime-version-series
status: released
owner: project
created_at: 2026-08-17
prd: prd.md
requirements: requirements.md
design: design.md
implementation_plan: implementation-plan.md
test_plan: test-plan.md
development_summary: development-summary.md
schema_baseline_waiver: schema-baseline-waiver.md
gitnexus_before: gitnexus/before.md
gitnexus_impact: gitnexus/impact-plan.md
gitnexus_detected_changes: gitnexus/detected-changes.md
gitnexus_after: gitnexus/after.md
gitnexus_comparison: gitnexus/comparison.md
code_review: review/code-review.md
standards_review: review/standards-review.md
release: v0.0.9
@@ -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,63 @@
# GOV-011 测试与质量证据
- 验证提交:`cce77aa`
- 验证日期:2026-08-17
- 运行时:Node.js 22.11.0、pnpm 10.25.0
## RED-GREEN 证据
| 行为 | RED | GREEN |
|---|---|---|
| Schema 接受完整 5.7.x | `5.7.0` 被旧实现以“必须为 5.7.42”拒绝 | 系列内/外定向测试 2/2 通过 |
| 健康检查接受 5.7.41-log | 旧实现拒绝并输出 5.7.42 文案 | 健康客户端 5/5 通过,详情为 `MySQL 5.7.41 / ...` |
| 当前文档采用系列口径 | 架构/规范 0/2,部署文档测试 9/10 | MySQL 2/2、环境 10/10、部署 6/6 |
## 自动化验证
| 命令或测试组 | 结果 | 关键证据 |
|---|---|---|
| `pnpm check:runtime` | passed | Node.js 22.11.0、pnpm 10.25.0 |
| `pnpm check:contracts` | passed | OpenAPI 与 Web 生成类型无漂移,项目边界通过 |
| `pnpm lint` | passed | Web/Server ESLint 无错误 |
| `pnpm format:check` | passed | 全仓 Prettier 通过 |
| `pnpm typecheck` | passed | Web、Vite 和 Server TypeScript 通过 |
| runtime | 3/3 | 22.x 系列与相邻主版本 |
| governance | 10/10 | 功能档案和 Review 门禁 |
| MySQL 规范 | 2/2 | 当前架构/规范使用 5.7.x |
| 环境 | 10/10 | 部署手册使用 5.7.x,其他环境边界保持 |
| Schema(跳过严格发布基线) | 28/28 | 生成、验证、历史 manifest 和字符规则回归 |
| contracts | 3/3 | 生成契约跟踪与漂移阻断 |
| boundaries | 16/16 | 前后端与 HTTP 边界 |
| deployment | 6/6 | 唯一 Ubuntu 源码发布边界 |
| Web | 11/11 | 请求、adapter 与外壳 |
| Server | 30/30 | API、配置、基础设施和进程 |
| API 预检 | 2/2 | Redis 可达/不可达分支 |
| `pnpm build` | passed | Web、API、Scheduler、Worker 构建成功 |
| `pnpm verify:e2e` | 4/4 | Chromium 桌面/移动页面和健康 API |
| `pnpm verify:source` | passed | 构建产物、systemd、Nginx 一致 |
## 一次性例外失败证据
`pnpm verify:release` 退出码非 0。它依次通过 runtime、契约、lint、格式、类型以及 Schema 之前的测试,随后在 Schema 第 28 个严格发布基线用例失败;实际错误为缺少 `database/schema-baselines/v0.0.8`。Schema 总计 29 项,其中 28 项通过、1 项为该已知失败。
`pnpm schema:verify` 在直接目录校验处失败;`pnpm governance:finish GOV-011 runtime-version-series` 在其前置 `test:schema-baseline` 的严格发布基线用例处失败。两者根因都是同一个 v0.0.8 目录缺失条件。原因、用户授权和禁止伪造边界见 `schema-baseline-waiver.md`;其余等价门禁已逐项执行并保存上表证据。
## 安全证据
- `pnpm audit --prod --registry=https://registry.npmjs.org/`:`No known vulnerabilities found`。
- `redis-cli -h 127.0.0.1 -p 6379 ping`:`PONG`,只验证本机开发 Redis。
- 构建产物扫描只命中 `MYSQL_PASSWORD`、`AI_API_KEY` 等配置键和必填错误文案,没有真实值、连接串或 Authorization 头。
- 本次没有新增依赖、SQL、命令执行、数据库写入、生产连接或外部网络请求。
- 健康详情只返回三段版本、库名和时区,不返回原始后缀、地址、账号或密码。
## 性能证据
- Web JS:163908 字节;CSS:805 字节,与 v0.0.8 记录一致。
- 健康检查仍为一次元数据查询,连接池上限 2;无重试、扫描、缓存或消息增量。
- Schema 与 runtime 判断只在启动/治理阶段执行常数时间正则匹配,不进入行情请求热路径。
## GitNexus 证据
- after:2015 节点、2692 关系、49 集群、50 流程,索引 `cce77aa` 为 up-to-date。
- compare:23 文件、70 符号、11 流程、HIGH;运行影响仅在既有 Schema 与 API 健康路径。
- `AGENTS.md` 的 GitNexus 计数由 `analyze` 自动从 2004/2681 更新为 2015/2692。
@@ -0,0 +1,21 @@
# GOV-011 视觉回归记录
- 页面:应用工程基础外壳
- 变更类型:后端版本判断、测试、注释和文档;无页面样式或交互修改
- 结论:无可观察视觉回归
## 桌面
- Chromium 视口:1440×900
- 截图:[app-shell-desktop-1440x900-cce77aa.png](/Users/citrons/Documents/Codex/2026-08-12/wo-x/a-share-analysis/docs/features/GOV-011-runtime-version-series/screenshots/iterations/app-shell-desktop-1440x900-cce77aa.png)
- 检查:`main` 可见,标题正常,无横向溢出,控制台 warning/error 为空。
## 移动
- Chromium 视口:390×844
- 截图:[app-shell-mobile-390x844-cce77aa.png](/Users/citrons/Documents/Codex/2026-08-12/wo-x/a-share-analysis/docs/features/GOV-011-runtime-version-series/screenshots/iterations/app-shell-mobile-390x844-cce77aa.png)
- 检查:标题与主内容正常换行和留白,无横向溢出、遮挡或裁切,控制台 warning/error 为空。
## 自动化证据
`pnpm verify:e2e` 在 desktop-chromium 与 mobile-chromium 共执行 4 项,全部通过;覆盖页面可见性、横向溢出、运行时错误和同源 `/api/v1/health` 契约。截图生成后测试 API 与 Vite 服务均通过 SIGINT 关闭,端口 3000/5173 无遗留监听。
@@ -0,0 +1,22 @@
# GOV-011 发布说明
- 发布版本:v0.0.9
- 状态:已发布
- 发布日期:2026-08-17
## 调整
- Node.js 运行时约束明确为完整 22.x,不绑定 minor 或 patch。
- MySQL 客户端、mysqldump、服务端和 API 健康检查统一接受完整 5.7.x,不设置最低 patch。
- MySQL 健康详情显示服务端实际三段版本,不再硬编码 5.7.42。
- 系统架构、代码开发规范、本地开发和 Ubuntu 源码部署手册统一使用系列版本口径。
## 保持不变
- `utf8mb4`、`utf8mb4_general_ci`、`+08:00`、固定开发库和主机白名单继续严格校验。
- HTTP/OpenAPI 响应结构、Web API、Redis、RocketMQ、Scheduler、Worker、数据库 Schema 和源码部署拓扑不变。
- 历史 QA、Schema 清单、CHANGELOG 历史版本和已发布功能档案继续记录当时真实 patch。
## 已知例外
v0.0.8 没有开发库 Schema 基线。用户确认开发库为空并授权 GOV-011 一次性跳过;仓库没有伪造基线或增加通用绕过开关。该例外导致 `verify:release`、`schema:verify` 和 `governance:finish` 在同一基线存在性检查失败,其他门禁已逐项执行并留证。
@@ -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,52 @@
# GOV-011 代码 Review
- reviewer_type:self
- reviewer:当前实现代理结构化自审
- 基线:`v0.0.8` / `9e85809`
- 审查实现:`cce77aa`
- 日期:2026-08-17
## 审查范围
审查 Node 特征测试、Schema 元数据校验、MySQL 健康客户端、治理测试、现行架构/规范/部署文档、GitNexus 影响和一次性 Schema 例外。重点检查版本格式、错误边界、历史清单兼容、健康信息泄漏和门禁真实性。
## 发现
### 已关闭问题
| 严重程度 | 位置 | 问题 | 处置 |
|---|---|---|---|
| Important | `tools/database/schema-baseline.test.mjs` 历史清单篡改测试 | 完整回归仍断言旧的“服务端必须为 5.7.42”文案,导致生产实现转为系列口径后测试失败。 | 更新为 `5.7.x` 断言;排除已授权发布基线用例后 Schema 28/28。 |
| Minor | `implementation-plan.md` 全量门禁预期 | 原计划把 `verify:release` 写为 PASS,但该命令包含必然触发一次性 Schema 例外的测试。 | 修正文档为真实失败并要求手工执行其余等价门禁。 |
### 未发现问题
未发现未关闭的 Critical、Important 或阻塞性 Minor。服务端正则只接受 `5.7.<数字>` 与 `-`/`+` 后缀;5.6、8.0、无 patch 和文字 patch 均拒绝。字符集、排序规则、库名、时区和生产数据库边界没有放宽。
## 测试缺口
没有针对每个 MySQL 5.7 patch 建立真实数据库兼容矩阵;这是用户明确接受的系列版本策略。本次使用纯函数、固定元数据和现有集成测试验证判断边界,不证明第三方数据库每个 patch 都没有厂商缺陷。首次真实迁移和查询仍必须在目标 5.7.x 环境验证。
## 安全与残余风险
- 版本字符串不执行、不进入 SQL;健康详情不回显原始后缀、地址、账号或密码。
- Schema 入口仍固定 development、开发库和主机白名单;本次未连接生产数据库。
- 残余风险一是不同 5.7 patch 的已知缺陷,二是 v0.0.8 缺少可验证 Schema 基线。前者由真实部署验证控制,后者由用户授权的一次性例外承担。
## 性能与资源影响
- 只增加常数时间正则捕获,没有新增查询、网络、重试、缓存、任务或依赖。
- 健康查询次数和连接池上限不变;Web 构建体积与 v0.0.8 一致。
- 不进入行情采集、分析、Redis、RocketMQ 或图表热路径,无需负载测试。
## GitNexus 与同步修改
开发前 `assertMysql57Metadata` 为 CRITICAL,5 个直接调用方、10 个受影响符号、5 组流程;`MysqlHealthClient` 为 LOW。开发后相对 v0.0.8 为 HIGH、23 文件、70 符号、11 流程,运行影响均属于计划中的 Schema 与 API 健康路径。HTTP/OpenAPI、Web API、消息、数据库 Schema、Redis、Scheduler、Worker 和部署拓扑没有计划外修改。
## v0.0.9 发布封存复核
- 发布只增加版本、CHANGELOG、索引和功能状态,不修改运行时判断、健康查询或数据库边界。
- 一次性 Schema 例外、HIGH GitNexus 风险和手工等价门禁证据均保留,没有改写为全量门禁通过。
- 发布标签必须指向通过上述 Review 的封存提交,并与 Gitea 远程引用核对。
最终结论:passed
@@ -0,0 +1,39 @@
# GOV-011 开发规范符合性 Review
- reviewer_type:self
- reviewer:当前实现代理结构化自审
- 审查提交:`cce77aa`
- 日期:2026-08-17
## 检查结果
- [x] PRD、需求、设计、实施计划、测试计划、开发总结、QA、GitNexus、Review、发布与回退资料齐全。
- [x] 修改关键符号前执行 GitNexus 上游影响分析,提交前执行 detect-changes。
- [x] HIGH/CRITICAL 风险已向用户说明,并以完整 Schema 与健康回归控制。
- [x] 行为修改遵循 RED-GREEN,测试失败原因来自旧实现而非语法或夹具。
- [x] 关键版本口径和安全边界使用准确中文注释,没有逐行复述。
- [x] 未新增依赖、预测性抽象、空分层或过度文件拆分。
- [x] 没有修改前端 Axios/API 分域、后端业务模块分层或 OpenAPI DTO。
- [x] 所有阶段提交使用中文 Conventional Commit 和 GOV-011,并立即推送 Gitea。
- [x] 没有使用 GitHub、强推、生产数据库或真实凭据。
- [x] 历史 QA、Schema 清单和已发布档案保持原样。
## 不符合项与处置
完成门禁无法通过 v0.0.8 Schema 基线存在性校验。该项不是静默忽略:用户在开发前明确确认当前开发库为空并要求本次跳过,仓库保存 `schema-baseline-waiver.md`,实际失败命令和风险写入 QA。没有修改治理工具,也没有伪造 `not_applicable`、`captured_empty` 或空 SQL。除此之外未发现未处置的不符合项。
## 安全、性能与架构检查
安全边界保持固定开发环境、库名、主机白名单、字符集、排序规则和时区;健康输出已脱敏,依赖审计 0 漏洞。性能只增加常数时间字符串匹配,查询、连接池、构建体积和执行流数量没有增加。架构仍为 Vue 3 Web 与 NestJS API/Scheduler/Worker 独立项目、Ubuntu 源码部署和外部 MySQL/Redis/RocketMQ。
## GitNexus 与开发总结检查
before、impact-plan、detected-changes、after、comparison 互相对应;最终索引为 2015 节点、2692 关系、50 流程。开发总结包含七个固定章节,明确原始需求、范围变化、实际完成、缺陷、延期、提交和验证证据;HIGH 风险与一次性 Schema 例外均有具体边界,不以空占位通过门禁。
## v0.0.9 发布封存复核
- VERSION、CHANGELOG、文档索引、manifest、开发总结和发布说明的 v0.0.9 状态必须一致。
- 发布提交和标签分别精确推送;禁止强推、批量推送标签或移动已发布标签。
- 历史 v0.0.8 的 5.7.42 事实不因当前系列口径反向改写。
最终结论:passed
@@ -0,0 +1,24 @@
# GOV-011 回退说明
GOV-011 不修改数据库结构、迁移或数据,不写 Redis,不操作 RocketMQ,也不修改生产配置。回退只涉及版本判断、健康详情、测试、注释和当前规范文档。
## 触发条件
- 合法 MySQL 5.7.x 被错误拒绝,或 5.6/8.x 被错误放行。
- 历史 captured/captured_empty manifest 无法验证。
- 健康接口泄漏原始版本后缀或返回错误 patch。
- 系列判断导致 Schema 生成、治理启动或 API 启动出现无法修复的回归。
## 回退步骤
1. 使用新的中文 Conventional Commit 恢复 `assertMysql57Metadata` 和 `MysqlHealthClient` 到上一已验证行为;禁止重写 Gitea 历史、强推或移动已发布标签。
2. 同步恢复对应测试、代码注释和当前架构/部署文档,避免实现与规范不一致。
3. 不改写已经发布的 GOV-011 档案;通过后续回退记录说明原因、范围和提交。
4. 因无数据库结构或数据变化,不执行数据库回滚。
## 回退验证
- 重新执行 runtime、Schema、MySQL 规范、环境、Server 健康、类型和构建测试。
- 执行 OpenAPI 契约、Playwright 双视口和源码发布验证。
- 运行 GitNexus impact、detect-changes 与 analyze,记录回退实际流程影响。
- v0.0.8 Schema 一次性例外仍只作为历史事实存在,不因代码回退生成伪造基线。
@@ -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 或数据写入。
Binary file not shown.

After

Width:  |  Height:  |  Size: 12 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 8.7 KiB

@@ -0,0 +1,58 @@
# GOV-011 测试计划
- 功能编号:GOV-011
- 验证环境:Node.js 22.11.0、pnpm 10.25.0、macOS 开发机
- 数据库边界:不连接、探测或读取生产数据库;本次不执行真实 Schema 导出
## 1. Node.js 系列验证
- 接受 `22.0.0`、`22.11.0` 和带预发布/构建后缀的合法 22.x。
- 拒绝 21.x、23.x、空字符串、`v22` 和其他无法解析格式。
- pnpm 继续只接受 10.x,不因 Node 约束调整而放宽。
## 2. Schema 元数据验证
- 接受 MySQL 服务端 `5.7.0`、`5.7.41`、`5.7.42-log`。
- 拒绝 `5.6.51`、`8.0.40`、`5.7`、`5.7.x` 和空字符串。
- mysql 与 mysqldump 客户端继续要求合法 5.7.x。
- 服务端版本通过后,字符集仍必须为 `utf8mb4`,排序规则仍必须为 `utf8mb4_general_ci`。
- 回归 captured、captured_empty、not_applicable、历史 manifest、生成入口和发布门禁调用链。
- 因用户授权的 v0.0.8 基线一次性例外,严格发布基线用例预期只在目录缺失处失败;使用 `--test-skip-pattern='严格发布门禁'` 验证其余 28 项全部通过。
## 3. API 健康检查验证
- `5.7.41-log` 返回 `MySQL 5.7.41 / <数据库> / +08:00`,证明 patch 来自服务端元数据而非硬编码。
- 拒绝 5.6.x、8.x 和无效版本格式。
- 拒绝错误库名、`utf8`、`utf8mb4_0900_ai_ci` 和 `SYSTEM` 时区。
- 保持固定只读元数据查询、健康 DTO 结构和生产库名按当前配置校验。
- 执行 Server 全量测试、类型检查和 API/Scheduler/Worker 三进程构建。
## 4. 规范与部署验证
- 当前系统架构、代码开发规范、本地开发和 Ubuntu 源码部署文档必须写明 `MySQL 5.7.x`。
- 上述四份当前文档不得再出现 `MySQL 5.7.42`;历史 QA、Schema 清单、CHANGELOG 历史版本和已发布功能档案不参与该否定扫描。
- Node.js 22.x、pnpm 10.25.0、Ubuntu 源码部署、systemd、Nginx、Redis 和 RocketMQ 约束保持不变。
## 安全验证
- 版本字符串仅进入固定正则,不执行命令、不拼接 SQL。
- MySQL 健康错误不回显服务端原始附加文本、连接地址、账号或密码。
- Schema 测试使用固定夹具和依赖注入,不连接真实数据库;本功能不执行 `schema:baseline`。
- `pnpm audit --prod --registry=https://registry.npmjs.org/` 必须为 0 已知漏洞。
- 扫描 Web/Server 构建产物中的凭据模式;配置键名允许存在,真实值、连接串和授权头不得存在。
- `git diff --check`、GitNexus detect-changes 和 Review 核对没有生产数据、真实 `.env` 或凭据进入提交。
## 性能验证
- 版本解析为启动/治理阶段常数时间正则匹配,不增加数据库查询、网络调用、重试、缓存或消息操作。
- 健康检查继续只执行一次既有元数据查询,连接池上限仍为 2。
- Web 页面和依赖未变化,生产 JS/CSS 体积应与 v0.0.8 基线一致。
- 本功能不改变行情计算、数据库扫描、Redis 热点、RocketMQ 吞吐、Worker 并发或图表渲染,因此不执行负载测试;后续触及这些路径的业务功能必须重新设定性能目标。
## 7. 全量与视觉验证
- 执行 runtime、governance、MySQL、环境、Schema、契约、边界、部署、Web 和 Server 测试。
- 执行 OpenAPI 重新生成、lint、格式、类型检查、Web/Server 构建和源码发布验证。
- Playwright 在 Chromium 1440×900 与 390×844 下验证页面、同源健康 API、横向溢出和控制台。
- 保存桌面/移动截图并人工检查无重叠、裁切或空白渲染回归。
- 真实执行 `pnpm verify:release`、`pnpm schema:verify` 和 `pnpm governance:finish GOV-011 runtime-version-series`;三者因同一个已授权 v0.0.8 基线缺失条件失败,必须保存失败证据并手工执行其余等价门禁。
+10 -10
View File
@@ -8,7 +8,7 @@
- 前端:Vue 3、Vite、TypeScript、Dart Sass、Naive UI;浏览器 HTTP 请求统一使用 Axios,接口类型由 OpenAPI 生成。
- 后端:NestJS、TypeScript。
- 数据库:MySQL 5.7.42,字符集 `utf8mb4`,排序规则 `utf8mb4_general_ci`;缓存:Redis;消息队列:RocketMQ 5.x。
- 数据库:MySQL 5.7.x,字符集 `utf8mb4`,排序规则 `utf8mb4_general_ci`;缓存:Redis;消息队列:RocketMQ 5.x。
- 图表:Lightweight Charts负责K线和分时,ECharts负责热力图、分布和资金趋势。
- AI:由服务端调用兼容 OpenAI 格式的付费 API,密钥不得下发浏览器。
@@ -127,24 +127,24 @@ count += 1;
- 业务代码只依赖项目定义的 `MessageBusAdapter` 和版本化事件契约,禁止直接依赖 RocketMQ SDK 类型;客户端、NameServer 或 Proxy 接入方式由基础设施适配层决定。
- 免费数据源通过 Adapter 统一为内部模型,上层不得依赖供应商原始字段。
## 11. MySQL 5.7 兼容规范
## 11. MySQL 5.7.x 兼容规范
- 开发、测试和生产环境统一使用 MySQL 5.7.42,禁止使用其他 5.7 补丁、`latest`、MySQL 8.x 或其他数据库代替兼容性验证。
- 开发、测试和生产环境统一使用 MySQL 5.7.x,不设置最低补丁版本;禁止使用 `latest`、MySQL 5.6.x、8.x、MariaDB 或其他数据库代替兼容性验证。
- 创建数据库必须显式声明 `DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci`;建表与迁移脚本必须显式保持 `DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci`。
- ORM 和数据库驱动必须声明 `utf8mb4`,连接建立后验证会话、数据库和表的排序规则为 `utf8mb4_general_ci`,不得依赖服务器默认值。
- 文本列默认继承表级规则。列级改变字符集或排序规则必须由具体功能设计解释,并通过 ADR 审批。
- 禁止使用 MySQL 8.x 专属或在 5.7 行为不同的公用表表达式、递归 CTE、窗口函数、函数索引、不可见索引、`utf8mb4_0900_*` 排序规则和 JSON 增强能力。
- 不得依赖 `CHECK` 约束在 MySQL 8.x 的强制执行语义;MySQL 5.7 下的业务约束必须由边界校验、普通索引或可测试的写入逻辑保证。
- 不得依赖 `CHECK` 约束在 MySQL 8.x 的强制执行语义;MySQL 5.7.x 下的业务约束必须由边界校验、普通索引或可测试的写入逻辑保证。
- `utf8mb4_general_ci` 不区分大小写。证券代码、外部事件 ID、幂等键等身份字段必须规范化输入,或显式采用经设计批准的二进制比较与唯一键,不能误把默认比较当成大小写敏感。
- 索引长度按 MySQL 5.7 和 `utf8mb4` 最多四字节字符预算;超长标识使用受控长度、前缀索引或稳定摘要时,必须说明唯一性和碰撞处理。
- JSON 字段只能使用 MySQL 5.7 已支持并经过真实环境验证的能力,查询和索引不得建立在 8.x 特性上。
- 每份迁移脚本必须能够从上一版本基线在 MySQL 5.7 正向执行;禁止用直接修改共享数据库表代替迁移脚本。
- 索引长度按 MySQL 5.7.x 和 `utf8mb4` 最多四字节字符预算;超长标识使用受控长度、前缀索引或稳定摘要时,必须说明唯一性和碰撞处理。
- JSON 字段只能使用 MySQL 5.7.x 已支持并经过真实环境验证的能力,查询和索引不得建立在 8.x 特性上。
- 每份迁移脚本必须能够从上一版本基线在 MySQL 5.7.x 正向执行;禁止用直接修改共享数据库表代替迁移脚本。
- 代码 Review 必须检查服务端版本、字符集、排序规则、SQL/迁移兼容性、索引长度和字符串比较语义;任一不符合项按 Important 处理并阻断发布。
### Schema 基线规范
- 每个新应用版本开发前必须封存上一已发布版本的开发库 Schema;只能读取 `APP_ENV=development`、`a_share_analysis_dev` 和 MySQL 5.7,主机仅允许回环地址或固定开发白名单 `112.192.20.11`,禁止连接、探测或读取生产数据库。配置优先读取 Git 忽略的 `deploy/env/development/api.env.local`。
- 导出使用 MySQL 5.7 `mysqldump` 的 `--no-data --routines --triggers --events`,完整保留表、索引、外键、视图、触发器、存储过程、函数和事件,不得包含任何表数据。
- 每个新应用版本开发前必须封存上一已发布版本的开发库 Schema;只能读取 `APP_ENV=development`、`a_share_analysis_dev` 和 MySQL 5.7.x,主机仅允许回环地址或固定开发白名单 `112.192.20.11`,禁止连接、探测或读取生产数据库。配置优先读取 Git 忽略的 `deploy/env/development/api.env.local`。
- 导出使用 MySQL 5.7.x `mysqldump` 的 `--no-data --routines --triggers --events`,完整保留表、索引、外键、视图、触发器、存储过程、函数和事件,不得包含任何表数据。
- 规范化必须确定性删除导出时间、环境 `DEFINER` 和表选项中的当前 `AUTO_INCREMENT=<值>`,同时保留列定义的 `AUTO_INCREMENT` 属性和业务 SQL。
- 账号密码只能通过受控子进程环境传递,不得进入参数、日志、SQL、清单或 checksum 文件。
- `manifest.yaml`、`checksum.sha256` 和 `schema.sql` 的 SHA-256 必须一致;既有版本目录只允许内容完全一致的幂等验证,不允许覆盖。
@@ -176,7 +176,7 @@ count += 1;
- 后端评估数据量与算法复杂度、MySQL 查询/索引/N+1、Redis 用途/TTL/一致性/击穿、API 载荷与分页、Scheduler/Worker 并发/幂等/背压,以及外部数据源和 AI 的超时/重试/批处理/成本。
- 前端评估依赖与构建体积、渲染次数、长列表、图表数据量、交互响应和内存占用;不能只以开发环境主观感觉作为证据。
- 高风险路径必须提供 benchmark、profile 或负载测试;低频治理逻辑等不适用场景必须写明无需负载测试的原因和边界。
- 性能优化不得牺牲数据口径、安全、可观察性、异常恢复或 MySQL 5.7 兼容性;禁止无证据的预优化。
- 性能优化不得牺牲数据口径、安全、可观察性、异常恢复或 MySQL 5.7.x 兼容性;禁止无证据的预优化。
## 15. 代码 Review 要求
+1
View File
@@ -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 系列版本约束(v0.0.9)](features/GOV-011-runtime-version-series/manifest.yaml)
功能档案是需求、设计、代码、测试、版本和回退之间的唯一正式关联入口。
+1 -1
View File
@@ -13,7 +13,7 @@ export interface RedisRuntimeConfig {
tls: boolean;
}
/** MySQL 配置固定 5.7.42 兼容口径,启用状态决定凭据是否必填。 */
/** MySQL 配置固定 5.7.x 兼容口径,启用状态决定凭据是否必填。 */
export interface MysqlRuntimeConfig {
enabled: boolean;
host: string;
@@ -23,7 +23,7 @@ describe('基础设施只读健康客户端', () => {
expect(commands).toEqual(['CONNECT', 'PING']);
});
it('MySQL 使用固定元数据查询并校验 5.7 与数据库口径', async () => {
it('MySQL 使用固定元数据查询并返回实际 5.7.x 版本', async () => {
const queries: string[] = [];
const client = new MysqlHealthClient(
{
@@ -32,7 +32,7 @@ describe('基础设施只读健康客户端', () => {
return [
[
{
version: '5.7.42-log',
version: '5.7.41-log',
databaseName: 'a_share_analysis_dev',
charset: 'utf8mb4',
collation: 'utf8mb4_general_ci',
@@ -49,7 +49,7 @@ describe('基础设施只读健康客户端', () => {
await expect(client.check()).resolves.toEqual({
status: 'healthy',
detail: 'MySQL 5.7.42 / a_share_analysis_dev / +08:00',
detail: 'MySQL 5.7.41 / a_share_analysis_dev / +08:00',
});
expect(queries).toEqual([MYSQL_HEALTH_QUERY]);
});
@@ -76,14 +76,17 @@ describe('基础设施只读健康客户端', () => {
'a_share_analysis_dev',
);
await expect(createClient({ version: '8.0.40' }).check()).rejects.toThrow(/MySQL 5.7/);
await expect(createClient({ version: '5.7.41' }).check()).rejects.toThrow(/5\.7\.42/);
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/);
}
await expect(createClient({ databaseName: 'a_share_analysis' }).check()).rejects.toThrow(
/a_share_analysis_dev/,
);
await expect(createClient({ charset: 'utf8' }).check()).rejects.toThrow(/utf8mb4/);
await expect(createClient({ collation: 'utf8mb4_0900_ai_ci' }).check()).rejects.toThrow(
/utf8mb4_general_ci/,
);
await expect(createClient({ timezone: 'SYSTEM' }).check()).rejects.toThrow(/\+08:00/);
});
it('MySQL 按当前配置校验生产库名', async () => {
@@ -36,8 +36,9 @@ export class MysqlHealthClient implements OnModuleDestroy {
const [rows] = await this.client.query(MYSQL_HEALTH_QUERY);
const row = (rows as unknown as MysqlMetadataRow[])[0];
if (!row) throw new Error('MySQL 未返回元数据');
if (!/^5\.7\.42(?:[-+.]|$)/.test(row.version)) {
throw new Error('MySQL 5.7.42 版本要求未满足');
const versionMatch = /^(5\.7\.\d+)(?:[-+].*)?$/.exec(row.version ?? '');
if (!versionMatch) {
throw new Error('MySQL 5.7.x 版本要求未满足');
}
if (row.databaseName !== this.expectedDatabase) {
throw new Error(`MySQL 健康检查必须连接 ${this.expectedDatabase}`);
@@ -50,7 +51,7 @@ export class MysqlHealthClient implements OnModuleDestroy {
return {
status: 'healthy',
detail: `MySQL 5.7.42 / ${row.databaseName} / ${row.timezone}`,
detail: `MySQL ${versionMatch[1]} / ${row.databaseName} / ${row.timezone}`,
};
}
@@ -63,7 +64,7 @@ export class MysqlHealthClient implements OnModuleDestroy {
}
}
/** 创建最多两个连接的只读健康池,并显式应用 MySQL 5.7.42 会话时区。 */
/** 创建最多两个连接的只读健康池,并显式应用 MySQL 5.7.x 会话时区。 */
export function createMysqlHealthClient(config: MysqlRuntimeConfig): MysqlHealthClient {
const pool: Pool = createPool({
host: config.host,
@@ -3,7 +3,7 @@ import type { MysqlConnectionOptions } from 'typeorm/driver/mysql/MysqlConnectio
import type { MysqlRuntimeConfig } from '../../config/src/runtime-config';
/**
* 生成 MySQL 5.7.42 TypeORM 基线选项;迁移未落地前不自动运行,且永久禁止 synchronize。
* 生成 MySQL 5.7.x TypeORM 基线选项;迁移未落地前不自动运行,且永久禁止 synchronize。
*/
export function buildTypeOrmOptions(config: MysqlRuntimeConfig): MysqlConnectionOptions {
return {
+5 -5
View File
@@ -73,8 +73,8 @@ export function assertSafeDevelopmentConfiguration(config) {
}
/**
* 客户端保持 5.7 系列以生成兼容导出;服务端固定 5.7.42,避免开发、测试和生产
* 由不同补丁行为产生漂移。同时核对数据库真实字符规则,而不是信任 env 声明。
* mysql、mysqldump 与服务端统一接受完整 5.7.x;字符集和排序规则仍按精确值
* 校验,避免放宽补丁版本时意外放宽数据库结构兼容边界。
*/
export function assertMysql57Metadata(metadata) {
if (!/^5\.7\.\d+(?:[-+].*)?$/.test(metadata.mysqlClientVersion ?? '')) {
@@ -85,8 +85,8 @@ export function assertMysql57Metadata(metadata) {
`mysqldump 客户端必须为 5.7.x,实际 ${metadata.mysqldumpClientVersion || '(空)'}`,
);
}
if (!/^5\.7\.42(?:[-+].*)?$/.test(metadata.serverVersion ?? '')) {
throw new Error(`MySQL 服务端必须为 5.7.42,实际 ${metadata.serverVersion || '(空)'}`);
if (!/^5\.7\.\d+(?:[-+].*)?$/.test(metadata.serverVersion ?? '')) {
throw new Error(`MySQL 服务端必须为 5.7.x,实际 ${metadata.serverVersion || '(空)'}`);
}
requireExactValue(metadata.databaseCharset, REQUIRED_CHARSET, '开发数据库字符集不符合要求');
requireExactValue(
@@ -663,7 +663,7 @@ export function runBaselineGeneration(options) {
assertMysql57Metadata({
mysqlClientVersion,
mysqldumpClientVersion,
serverVersion: '5.7.42-pending-server-check',
serverVersion: '5.7.0-pending-server-check',
databaseCharset: REQUIRED_CHARSET,
databaseCollation: REQUIRED_COLLATION,
});
+20 -11
View File
@@ -132,19 +132,28 @@ test('拒绝错误字符集、排序规则和不完整的启用配置', () => {
);
});
test('只接受 MySQL 5.7 客户端、5.7.42 服务端和固定数据库字符规则', () => {
assert.doesNotThrow(() => assertMysql57Metadata(validMetadata));
test('接受完整 MySQL 5.7.x 服务端系列', () => {
for (const serverVersion of ['5.7.0', '5.7.41', '5.7.42-log']) {
assert.doesNotThrow(() =>
assertMysql57Metadata({ ...validMetadata, serverVersion }),
);
}
});
test('拒绝非 MySQL 5.7.x 版本并保持固定数据库字符规则', () => {
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, serverVersion: '8.0.39' }),
/服务端必须为 5\.7\.42/,
() => assertMysql57Metadata({ ...validMetadata, mysqlClientVersion: '8.0.40' }),
/mysql 客户端必须为 5\.7\.x/,
);
assert.throws(
() => assertMysql57Metadata({ ...validMetadata, serverVersion: '5.7.41' }),
/服务端必须为 5\.7\.42/,
);
assert.throws(
() => assertMysql57Metadata({ ...validMetadata, mysqlClientVersion: '8.0.39' }),
/mysql 客户端必须为 5\.7/,
() => assertMysql57Metadata({ ...validMetadata, mysqldumpClientVersion: '8.0.40' }),
/mysqldump 客户端必须为 5\.7\.x/,
);
assert.throws(
() => assertMysql57Metadata({ ...validMetadata, databaseCollation: 'utf8mb4_bin' }),
@@ -501,7 +510,7 @@ test('校验拒绝篡改成错误 MySQL 版本或伪造对象范围的真实清
const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
manifest.mysql_server_version = '8.0.39';
writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
assert.throws(() => verifyBaselineDirectory(target, 'v0.0.5'), /服务端必须为 5\.7\.42/);
assert.throws(() => verifyBaselineDirectory(target, 'v0.0.5'), /服务端必须为 5\.7\.x/);
manifest.mysql_server_version = '5.7.42-log';
manifest.objects.events = false;
@@ -181,7 +181,8 @@ test('部署文档要求本机外部 Redis 和唯一 Ubuntu 源码生产路径',
assert.doesNotMatch(source, /systemctl (?:restart|status) a-share-\w+\.service\.example/);
assert.match(source, /不负责安装/);
for (const document of [local, source]) {
assert.match(document, /MySQL 5\.7\.42/);
assert.match(document, /MySQL 5\.7\.x/);
assert.doesNotMatch(document, /MySQL 5\.7\.42/);
}
});
+6 -4
View File
@@ -5,19 +5,20 @@ import test from 'node:test';
const architecturePath = new URL('../../docs/architecture/system-architecture.md', import.meta.url);
const standardsPath = new URL('../../docs/governance/code-development-standards.md', import.meta.url);
test('系统架构固定 MySQL 5.7 字符集与排序规则', async () => {
test('系统架构固定 MySQL 5.7.x 系列、字符集与排序规则', async () => {
const architecture = await readFile(architecturePath, 'utf8');
assert.match(architecture, /MySQL 5\.7/);
assert.match(architecture, /MySQL 5\.7\.x/);
assert.doesNotMatch(architecture, /MySQL 5\.7\.42/);
assert.match(architecture, /utf8mb4/);
assert.match(architecture, /utf8mb4_general_ci/);
});
test('开发规范覆盖 MySQL 5.7 全链路兼容性要求', async () => {
test('开发规范覆盖 MySQL 5.7.x 全链路兼容性要求', async () => {
const standards = await readFile(standardsPath, 'utf8');
for (const requiredText of [
'MySQL 5.7',
'MySQL 5.7.x',
'utf8mb4',
'utf8mb4_general_ci',
'公用表表达式',
@@ -31,4 +32,5 @@ test('开发规范覆盖 MySQL 5.7 全链路兼容性要求', async () => {
]) {
assert.ok(standards.includes(requiredText), `开发规范缺少数据库基线:${requiredText}`);
}
assert.doesNotMatch(standards, /MySQL 5\.7\.42/);
});
+7 -5
View File
@@ -3,18 +3,20 @@ import test from 'node:test';
import { assertSupportedRuntime } from './verify-runtime.mjs';
test('只接受 Node 22 与 pnpm 10', () => {
assert.doesNotThrow(() =>
assertSupportedRuntime({ nodeVersion: '22.11.0', pnpmVersion: '10.25.0' }),
);
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 ['20.20.2', '24.0.0']) {
for (const nodeVersion of ['21.7.3', '23.0.0']) {
assert.throws(
() => assertSupportedRuntime({ nodeVersion, pnpmVersion: '10.25.0' }),
new RegExp(`Node\\.js 必须为 22\\.x,实际 ${nodeVersion.replaceAll('.', '\\.')}`),
);
}
});
test('只接受 pnpm 10.x', () => {
for (const pnpmVersion of ['9.15.0', '11.0.0']) {
assert.throws(
() => assertSupportedRuntime({ nodeVersion: '22.11.0', pnpmVersion }),