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
@@ -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`。
+- 本功能无界面变化，视觉验证不适用。