docs(GOV-005): 建立 MySQL 5.7 兼容性基线

2026-08-13 10:44:34 +08:00
parent fa1df71eac
commit 91d9b9ce85
23 changed files with 359 additions and 7 deletions
@@ -23,7 +23,7 @@
 <!-- gitnexus:start -->
 # GitNexus — Code Intelligence

-This project is indexed by GitNexus as **a-share-analysis** (432 symbols, 458 relationships, 0 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** (528 symbols, 553 relationships, 0 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.

@@ -2,6 +2,12 @@

 本项目采用语义化版本。功能级变化请从 `docs/features/` 按功能编号追溯。

+## 0.0.4 - 2026-08-13
+
+- 固定 MySQL 5.7.x、`utf8mb4` 和 `utf8mb4_general_ci` 技术基线。
+- 增加 MySQL 8.x 禁用能力、迁移、索引、比较语义和 Review 规则。
+- 新增数据库基线自动化契约测试。
+
 ## 0.0.3 - 2026-08-12

 - 将当前分支推送设为每次提交后的强制步骤，新标签采用精确推送。
@@ -1 +1 @@
-0.0.3
+0.0.4
@@ -36,6 +36,14 @@ tools/      可重复执行的治理和开发工具
 - Redis保存最新快照、缓存、锁和限流状态。
 - Vue前端只读后端 API，不直接接触外部数据源和密钥。

-## 3. 当前实施顺序
+## 3. 数据库技术基线
+
+- 数据库服务端固定使用 MySQL 5.7.x，开发、测试和生产环境禁止使用 MySQL 8.x 代替兼容性验证。
+- 数据库与表默认字符集固定为 `utf8mb4`，排序规则固定为 `utf8mb4_general_ci`。
+- 数据库初始化、表结构、连接会话、ORM 配置和迁移脚本必须显式声明或验证该字符集与排序规则，不能依赖服务器默认值。
+- 正式启用持久化前，必须在真实 MySQL 5.7 环境验证服务端版本、Schema/表排序规则、迁移和关键查询。
+- 第一阶段市场概览只定义 MySQL Repository 接口并使用内存实现，不启动数据库、不建立生产连接；后续启用时不得改变前端 API 和核心分析契约。
+
+## 4. 当前实施顺序

 第一阶段先实现可交互的市场综合概览和稳定数据契约，再接入正式行情采集链路。用户、邀请、权限、会员和支付后置，不进入当前核心架构。
@@ -0,0 +1,9 @@
+# GitNexus 开发后结果
+
+- 执行：`npx gitnexus analyze`。
+- 工作区索引：528 个节点、553 条关系、5 个集群、0 条执行流程。
+- 增量分析：6 个已修改文件、18 个新增文件、0 个删除文件，并新增 1 个导入关系到可写集合。
+- 当前索引提交：`fa1df71`；工作区变化已进入增量图谱。
+- 状态：up-to-date。
+
+实现提交后再次分析，把索引锚定到确定提交。
@@ -0,0 +1,10 @@
+# GitNexus 前后对比
+
+| 项目 | 开发前 | 开发后工作区 | 变化 |
+|---|---:|---:|---:|
+| 节点 | 432 | 528 | +96 |
+| 关系 | 458 | 553 | +95 |
+| 集群 | 5 | 5 | 0 |
+| 执行流程 | 0 | 0 | 0 |
+
+增长来自数据库规范、契约测试与完整 GOV-005 档案；生产执行流程保持不变，符合影响预估。
@@ -0,0 +1,8 @@
+# GitNexus 变更检测
+
+- 命令：`npx gitnexus detect-changes --repo a-share-analysis --scope staged`。
+- 最终暂存区：23 个文件、45 个符号。
+- 受影响流程：0。
+- 风险等级：低。
+
+识别范围包含系统架构、开发规范、GOV-005 档案、测试与文档索引；版本纯文本和 Changelog 通过 Git diff 另行核对。
@@ -0,0 +1,7 @@
+# GitNexus 开发前影响分析
+
+- 查询主题：`MySQL 5.7 utf8mb4 general ci compatibility architecture standards`。
+- 主要关联：`docs/architecture/system-architecture.md`、`docs/governance/code-development-standards.md`、README、文档索引和治理 Review。
+- 本次不修改既有函数、类或方法；新增测试文件不参与生产调用链，因此没有生产符号需要上游影响分析。
+- GitNexus 查询没有识别业务执行流程，预计影响限于架构规范、治理测试和版本档案。
+- 风险控制：测试先行锁定文字契约；不连接数据库、不创建部署配置、不声称已验证真实 MySQL 实例。
@@ -0,0 +1,102 @@
+# MySQL 5.7 字符集与兼容性基线实施计划
+
+> **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:** 将 MySQL 5.7.x、`utf8mb4`、`utf8mb4_general_ci` 和禁止 MySQL 8.x 专属能力写入系统架构与开发规范，并以自动化测试锁定。
+
+**Architecture:** 约束以系统架构定义全局技术基线，以代码开发规范定义实现与 Review 门禁。新增独立 Node.js 静态契约测试读取这两份文档，防止后续删除版本、字符集、排序规则或兼容性要求。
+
+**Tech Stack:** Markdown、Node.js 内置测试运行器、GitNexus、Git/Gitea。
+
+## Global Constraints
+
+- 数据库服务端固定 MySQL 5.7.x，禁止 MySQL 8.x。
+- 字符集固定 `utf8mb4`，排序规则固定 `utf8mb4_general_ci`。
+- 数据库、表、连接、迁移和测试环境必须显式声明或验证基线。
+- 禁止依赖 CTE、窗口函数、函数索引、不可见索引和 `utf8mb4_0900_*`。
+- 当前只建立规范，不创建数据库、容器、ORM 或生产连接。
+
+---
+
+### Task 1: 建立失败的数据库基线契约测试
+
+**Files:**
+- Create: `tools/governance/mysql-baseline.test.mjs`
+- Modify: `package.json`
+
+**Interfaces:**
+- Consumes: `docs/architecture/system-architecture.md` 与 `docs/governance/code-development-standards.md`。
+- Produces: `npm run test:mysql-baseline`，验证数据库基线的机器可读证据。
+
+- [ ] **Step 1: 编写测试**
+
+测试必须断言两份文档包含 `MySQL 5.7`、`utf8mb4`、`utf8mb4_general_ci`，并断言开发规范包含 MySQL 8.x 禁用能力、大小写语义、索引长度、迁移与 Review 要求。
+
+- [ ] **Step 2: 验证测试因规范缺失而失败**
+
+运行：`npm run test:mysql-baseline`
+
+预期：失败原因明确指向系统架构或开发规范缺少 MySQL 基线文本。
+
+### Task 2: 更新架构与开发规范
+
+**Files:**
+- Modify: `docs/architecture/system-architecture.md`
+- Modify: `docs/governance/code-development-standards.md`
+
+**Interfaces:**
+- Consumes: Task 1 的断言。
+- Produces: 所有后续数据库、ORM、迁移和部署功能必须遵守的规范。
+
+- [ ] **Step 1: 更新系统架构**
+
+增加数据库技术基线、第一阶段接口边界以及正式启用 MySQL 时的验证条件。
+
+- [ ] **Step 2: 更新开发规范**
+
+增加 Schema/表/连接/迁移显式配置、5.7 禁用能力、排序语义、索引预算和 Review 检查。
+
+- [ ] **Step 3: 验证测试转绿**
+
+运行：`npm run test:mysql-baseline && npm run test:governance`
+
+预期：全部通过。
+
+### Task 3: 完成追溯、Review 与发布
+
+**Files:**
+- Create: `docs/features/GOV-005-mysql57-charset-baseline/manifest.yaml`
+- Create: `docs/features/GOV-005-mysql57-charset-baseline/prd.md`
+- Create: `docs/features/GOV-005-mysql57-charset-baseline/requirements.md`
+- Create: `docs/features/GOV-005-mysql57-charset-baseline/test-plan.md`
+- Create: `docs/features/GOV-005-mysql57-charset-baseline/gitnexus/impact-plan.md`
+- Create: `docs/features/GOV-005-mysql57-charset-baseline/gitnexus/after.md`
+- Create: `docs/features/GOV-005-mysql57-charset-baseline/gitnexus/detected-changes.md`
+- Create: `docs/features/GOV-005-mysql57-charset-baseline/gitnexus/comparison.md`
+- Create: `docs/features/GOV-005-mysql57-charset-baseline/qa/test-results.md`
+- Create: `docs/features/GOV-005-mysql57-charset-baseline/qa/visual-qa.md`
+- Create: `docs/features/GOV-005-mysql57-charset-baseline/review/code-review.md`
+- Create: `docs/features/GOV-005-mysql57-charset-baseline/review/standards-review.md`
+- Create: `docs/features/GOV-005-mysql57-charset-baseline/release-notes.md`
+- Create: `docs/features/GOV-005-mysql57-charset-baseline/rollback.md`
+- Modify: `docs/index.md`
+- Modify: `CHANGELOG.md`
+- Modify: `VERSION`
+
+**Interfaces:**
+- Consumes: 通过测试的架构和规范。
+- Produces: 可审查、可发布、可回退的 GOV-005 完整档案和 `v0.0.4`。
+
+- [ ] **Step 1: 完成 GitNexus 分析和全部档案**
+
+重新索引，检测完整暂存区，记录前后节点、关系、流程和风险。
+
+- [ ] **Step 2: 完成双 Review 与门禁**
+
+运行：`npm run governance:finish -- GOV-005 mysql57-charset-baseline`
+
+预期：两份 Review 均为 `passed`，门禁退出码为 0。
+
+- [ ] **Step 3: 中文提交、推送与标签**
+
+提交规范变化并推送 `main`；封存验证结果后创建带注释 `v0.0.4`，精确推送该标签并核对远程引用。
@@ -0,0 +1,17 @@
+id: GOV-005
+name: MySQL 5.7 字符集与兼容性基线
+slug: mysql57-charset-baseline
+status: verifying
+owner: project
+created_at: 2026-08-13
+prd: prd.md
+requirements: requirements.md
+design: design.md
+implementation_plan: implementation-plan.md
+gitnexus_before: gitnexus/before.md
+gitnexus_after: gitnexus/after.md
+gitnexus_comparison: gitnexus/comparison.md
+code_review: review/code-review.md
+standards_review: review/standards-review.md
+implementation_commit: pending
+release: v0.0.4
@@ -0,0 +1,32 @@
+# MySQL 5.7 字符集与兼容性基线 PRD
+
+- 功能编号：GOV-005
+- PRD 版本：0.1
+- 状态：approved
+- 日期：2026-08-13
+
+## 问题
+
+项目只写明使用 MySQL，没有固定版本、字符集和排序规则。开发或部署人员可能使用 MySQL 8.x 或不同默认排序规则，造成 SQL、迁移、索引和字符串比较行为不一致。
+
+## 目标
+
+- 固定 MySQL 5.7.x、`utf8mb4` 和 `utf8mb4_general_ci`。
+- 在架构和开发规范中覆盖数据库、表、连接、迁移、测试与 Review。
+- 禁止无意引入 MySQL 8.x 专属能力。
+- 用自动化契约测试防止规范回退。
+
+## 非目标
+
+- 不安装或启动 MySQL。
+- 不创建 Schema、表、迁移或 ORM 配置。
+- 不连接开发或生产数据库。
+- 不启用市场概览持久化。
+
+## 验收标准
+
+- 系统架构明确 MySQL 5.7.x、字符集和排序规则。
+- 开发规范明确全链路显式配置、禁止能力、大小写语义和索引预算。
+- 新契约测试在旧规范上失败，在新规范上通过。
+- 原治理测试无回归。
+- 双 Review 和完成门禁通过。
@@ -0,0 +1,16 @@
+# 测试结果
+
+## 测试先行证据
+
+新增 `mysql-baseline.test.mjs` 后首次运行：2 个测试失败。架构测试明确因缺少 `MySQL 5.7` 失败，开发规范测试明确因缺少数据库基线失败，证明测试能够捕获目标缺陷。
+
+补充架构和开发规范后复测：
+
+- `npm run test:mysql-baseline`：2 个通过，0 个失败。
+- `npm run test:governance`：5 个通过，0 个失败。
+- `git diff --check`：通过。
+- GitNexus 最终暂存区：23 个文件、45 个符号、0 条流程，风险为低。
+
+## 适用性
+
+本功能只建立设计与规范，没有 MySQL 实例、Schema 或连接，因此不执行数据库连通性测试。真实 MySQL 5.7 验证属于首次启用持久化的后续功能门禁。
@@ -0,0 +1,3 @@
+# 视觉验证
+
+本功能只修改架构、开发规范、治理测试和追溯文档，不改变任何页面或交互，因此视觉验证不适用。
@@ -0,0 +1,8 @@
+# 发布说明
+
+## v0.0.4
+
+- 固定 MySQL 5.7.x、`utf8mb4` 和 `utf8mb4_general_ci`。
+- 增加 MySQL 8.x 禁用能力、排序语义、索引和迁移规范。
+- 新增数据库基线契约测试。
+- 第一阶段仍不启用 MySQL，只为后续 Repository 实现建立兼容基线。
@@ -0,0 +1,10 @@
+# 工程需求
+
+- 系统架构增加独立数据库技术基线章节。
+- 开发规范固定 MySQL 5.7.x、`utf8mb4`、`utf8mb4_general_ci`。
+- 禁止 CTE、窗口函数、函数索引、不可见索引和 `utf8mb4_0900_*`。
+- 解释默认排序不区分大小写对身份字段和唯一键的影响。
+- 规定 MySQL 5.7 下索引长度预算、JSON 使用边界和 `CHECK` 约束替代方案。
+- 迁移必须从上一版本基线正向验证，禁止直接修改共享表代替迁移。
+- 新增 Node.js 静态契约测试并加入 npm 脚本。
+- 第一阶段只定义 Repository 接口，不启用 MySQL。
@@ -0,0 +1,30 @@
+# 代码与规范 Review
+
+- reviewer_type：self
+- reviewer：Codex
+- 基线提交：`6aa9fed`
+- 设计提交：`0328f9e`
+- 实现提交：`pending`
+- 日期：2026-08-13
+
+## PRD 与设计符合性
+
+架构固定数据库服务端、字符集、排序规则和第一阶段接口边界；开发规范覆盖 Schema、表、连接、迁移、查询、索引、测试和 Review；自动化测试锁定关键文本。
+
+## 发现与处置
+
+| 严重程度 | 发现 | 处置 |
+|---|---|---|
+| Important | 只写 MySQL 无法防止开发环境使用 8.x | 架构和规范固定 5.7.x，并要求真实环境验证 |
+| Important | 只依赖服务器默认字符集可能产生混合排序规则 | 要求数据库、表、连接与迁移显式声明或验证 |
+| Important | `utf8mb4_general_ci` 不区分大小写，身份字段可能发生碰撞 | 规范要求输入标准化或经批准的二进制比较与唯一键 |
+| Minor | 纯文档约束容易被后续编辑删除 | 新增静态契约测试并完成红绿验证 |
+
+## 验证
+
+- 数据库基线测试 2/2 通过。
+- 治理测试 5/5 通过。
+- GitNexus 最终暂存区检测为 23 个文件、45 个符号、0 条流程、低风险。
+- 未连接或修改任何数据库。
+
+最终结论：passed
@@ -0,0 +1,21 @@
+# 开发规范符合性 Review
+
+- reviewer_type：self
+- reviewer：Codex
+- 实现提交：`pending`
+- 日期：2026-08-13
+
+## 检查结果
+
+- [x] 开发前运行治理启动和 GitNexus 查询。
+- [x] 设计经用户确认后实施。
+- [x] 新行为先有失败测试，再修改规范使其通过。
+- [x] 变更集中在架构、开发规范和一个可连续阅读的测试文件。
+- [x] 没有连接生产或开发数据库。
+- [x] 没有新增依赖、秘密、环境配置或业务数据。
+- [x] MySQL 5.7、字符集、排序规则和 8.x 禁用能力均可机器验证。
+- [x] 无界面变化，视觉验证标记不适用。
+
+没有未解决的 Critical 或 Important 不符合项。
+
+最终结论：passed
@@ -0,0 +1,5 @@
+# 回退说明
+
+本功能没有连接或修改数据库，回退不涉及数据操作。规则发布后如需修正，使用新的治理功能编号和中文修复提交更新架构、规范与测试，不移动或删除共享版本标签。
+
+回退到 `v0.0.3` 只能用于读取升级前文档；后续已经按 MySQL 5.7 基线创建的迁移或部署不得通过改写历史撤销。
@@ -0,0 +1,10 @@
+# 测试计划
+
+- 先运行新增数据库基线测试，证明旧架构与规范因缺少 MySQL 5.7 约束而失败。
+- 更新文档后复测，要求数据库基线测试 2 个通过、0 个失败。
+- 运行治理测试，要求 5 个通过、0 个失败。
+- 运行 `git diff --check`。
+- 扫描仓库和暂存区，确认没有凭据或生产配置。
+- 执行 GitNexus 增量分析与最终暂存区变更检测。
+- 执行 `npm run governance:finish -- GOV-005 mysql57-charset-baseline`。
+- 本功能无界面变化，视觉验证不适用。
@@ -8,7 +8,7 @@

 - 前端：Vue 3、Vite、TypeScript、Dart Sass、Naive UI。
 - 后端：NestJS、TypeScript。
- 数据库：MySQL；缓存：Redis；消息队列：RabbitMQ。
+- 数据库：MySQL 5.7.x，字符集 `utf8mb4`，排序规则 `utf8mb4_general_ci`；缓存：Redis；消息队列：RabbitMQ。
 - 图表：Lightweight Charts负责K线和分时，ECharts负责热力图、分布和资金趋势。
 - AI：由服务端调用兼容 OpenAI 格式的付费 API，密钥不得下发浏览器。

@@ -98,7 +98,21 @@ count += 1;
 - 消费者必须幂等，消息确认只能发生在持久化或可验证处理完成后。
 - 免费数据源通过 Adapter 统一为内部模型，上层不得依赖供应商原始字段。

-## 10. 测试要求
+## 10. MySQL 5.7 兼容规范
+
+- 开发、测试、Docker 和生产环境必须使用明确的 MySQL 5.7 补丁版本，禁止使用 `latest`、MySQL 8.x 或其他数据库代替兼容性验证。
+- 创建数据库必须显式声明 `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 下的业务约束必须由边界校验、普通索引或可测试的写入逻辑保证。
+- `utf8mb4_general_ci` 不区分大小写。证券代码、外部事件 ID、幂等键等身份字段必须规范化输入，或显式采用经设计批准的二进制比较与唯一键，不能误把默认比较当成大小写敏感。
+- 索引长度按 MySQL 5.7 和 `utf8mb4` 最多四字节字符预算；超长标识使用受控长度、前缀索引或稳定摘要时，必须说明唯一性和碰撞处理。
+- JSON 字段只能使用 MySQL 5.7 已支持并经过真实环境验证的能力，查询和索引不得建立在 8.x 特性上。
+- 每份迁移脚本必须能够从上一版本基线在 MySQL 5.7 正向执行；禁止用直接修改共享数据库表代替迁移脚本。
+- 代码 Review 必须检查服务端版本、字符集、排序规则、SQL/迁移兼容性、索引长度和字符串比较语义；任一不符合项按 Important 处理并阻断发布。
+
+## 11. 测试要求

 - 功能和缺陷修复遵循测试先行：先看到测试因缺少行为而失败，再实现最小代码。
 - 纯规则和指标计算使用单元测试，期望值必须手工推导。
@@ -107,14 +121,14 @@ count += 1;
 - 关键页面使用 Playwright流程测试和视觉截图对比。
 - 合并前必须通过类型检查、测试、构建和适用的视觉验证。

-## 11. 安全要求
+## 12. 安全要求

 - 禁止提交 `.env`、API Key、密码、真实账号和生产数据。
 - AI 密钥、数据源凭证和支付凭证仅存在服务端密钥管理中。
 - SQL必须参数化；外部输入必须在边界处校验。
 - 日志和异常报告必须脱敏。

-## 12. 代码 Review 要求
+## 13. 代码 Review 要求

 开发者完成自测不等于 Review 完成。审查者必须从功能 PRD、设计和 Git diff 出发，检查：

@@ -28,5 +28,6 @@
 - [GOV-002：PRD 与 Review 门禁](features/GOV-002-prd-review-gates/manifest.yaml)
 - [GOV-003：项目专用 Gitea 远程仓库](features/GOV-003-gitea-local-remote/manifest.yaml)
 - [GOV-004：提交后强制推送 Gitea](features/GOV-004-mandatory-gitea-push/manifest.yaml)
+- [GOV-005：MySQL 5.7 字符集与兼容性基线](features/GOV-005-mysql57-charset-baseline/manifest.yaml)

 功能档案是需求、设计、代码、测试、版本和回退之间的唯一正式关联入口。
@@ -5,6 +5,7 @@
  "type": "module",
  "scripts": {
    "test:governance": "node --test tools/governance/feature-record.test.mjs",
+    "test:mysql-baseline": "node --test tools/governance/mysql-baseline.test.mjs",
    "governance:start": "node tools/governance/start.mjs",
    "governance:finish": "node tools/governance/finish.mjs"
  }
@@ -0,0 +1,34 @@
+import assert from 'node:assert/strict';
+import { readFile } from 'node:fs/promises';
+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 () => {
+  const architecture = await readFile(architecturePath, 'utf8');
+
+  assert.match(architecture, /MySQL 5\.7/);
+  assert.match(architecture, /utf8mb4/);
+  assert.match(architecture, /utf8mb4_general_ci/);
+});
+
+test('开发规范覆盖 MySQL 5.7 全链路兼容性要求', async () => {
+  const standards = await readFile(standardsPath, 'utf8');
+
+  for (const requiredText of [
+    'MySQL 5.7',
+    'utf8mb4',
+    'utf8mb4_general_ci',
+    '公用表表达式',
+    '窗口函数',
+    '函数索引',
+    'utf8mb4_0900_',
+    '不区分大小写',
+    '索引长度',
+    '迁移脚本',
+    '代码 Review',
+  ]) {
+    assert.ok(standards.includes(requiredText), `开发规范缺少数据库基线：${requiredText}`);
+  }
+});
@@ -1 +1 @@
 .0.3
 .0.4