From 91d9b9ce85b1c6262f1ebfef55276bbdb7b1ce6b Mon Sep 17 00:00:00 2001 From: Citrons <909229731@qq.com> Date: Thu, 13 Aug 2026 10:44:34 +0800 Subject: [PATCH] =?UTF-8?q?docs(GOV-005):=20=E5=BB=BA=E7=AB=8B=20MySQL=205?= =?UTF-8?q?.7=20=E5=85=BC=E5=AE=B9=E6=80=A7=E5=9F=BA=E7=BA=BF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 2 +- CHANGELOG.md | 6 ++ VERSION | 2 +- docs/architecture/system-architecture.md | 10 +- .../gitnexus/after.md | 9 ++ .../gitnexus/comparison.md | 10 ++ .../gitnexus/detected-changes.md | 8 ++ .../gitnexus/impact-plan.md | 7 ++ .../implementation-plan.md | 102 ++++++++++++++++++ .../manifest.yaml | 17 +++ .../GOV-005-mysql57-charset-baseline/prd.md | 32 ++++++ .../qa/test-results.md | 16 +++ .../qa/visual-qa.md | 3 + .../release-notes.md | 8 ++ .../requirements.md | 10 ++ .../review/code-review.md | 30 ++++++ .../review/standards-review.md | 21 ++++ .../rollback.md | 5 + .../test-plan.md | 10 ++ docs/governance/code-development-standards.md | 22 +++- docs/index.md | 1 + package.json | 1 + tools/governance/mysql-baseline.test.mjs | 34 ++++++ 23 files changed, 359 insertions(+), 7 deletions(-) create mode 100644 docs/features/GOV-005-mysql57-charset-baseline/gitnexus/after.md create mode 100644 docs/features/GOV-005-mysql57-charset-baseline/gitnexus/comparison.md create mode 100644 docs/features/GOV-005-mysql57-charset-baseline/gitnexus/detected-changes.md create mode 100644 docs/features/GOV-005-mysql57-charset-baseline/gitnexus/impact-plan.md create mode 100644 docs/features/GOV-005-mysql57-charset-baseline/implementation-plan.md create mode 100644 docs/features/GOV-005-mysql57-charset-baseline/manifest.yaml create mode 100644 docs/features/GOV-005-mysql57-charset-baseline/prd.md create mode 100644 docs/features/GOV-005-mysql57-charset-baseline/qa/test-results.md create mode 100644 docs/features/GOV-005-mysql57-charset-baseline/qa/visual-qa.md create mode 100644 docs/features/GOV-005-mysql57-charset-baseline/release-notes.md create mode 100644 docs/features/GOV-005-mysql57-charset-baseline/requirements.md create mode 100644 docs/features/GOV-005-mysql57-charset-baseline/review/code-review.md create mode 100644 docs/features/GOV-005-mysql57-charset-baseline/review/standards-review.md create mode 100644 docs/features/GOV-005-mysql57-charset-baseline/rollback.md create mode 100644 docs/features/GOV-005-mysql57-charset-baseline/test-plan.md create mode 100644 tools/governance/mysql-baseline.test.mjs diff --git a/AGENTS.md b/AGENTS.md index 07e2f7b..d49ecb6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,7 +23,7 @@ # 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. diff --git a/CHANGELOG.md b/CHANGELOG.md index 2e5fcc2..3bc0d0d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 - 将当前分支推送设为每次提交后的强制步骤，新标签采用精确推送。 diff --git a/VERSION b/VERSION index bcab45a..81340c7 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.0.3 +0.0.4 diff --git a/docs/architecture/system-architecture.md b/docs/architecture/system-architecture.md index 4138e6a..25ca6f3 100644 --- a/docs/architecture/system-architecture.md +++ b/docs/architecture/system-architecture.md @@ -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. 当前实施顺序 第一阶段先实现可交互的市场综合概览和稳定数据契约，再接入正式行情采集链路。用户、邀请、权限、会员和支付后置，不进入当前核心架构。 diff --git a/docs/features/GOV-005-mysql57-charset-baseline/gitnexus/after.md b/docs/features/GOV-005-mysql57-charset-baseline/gitnexus/after.md new file mode 100644 index 0000000..1211d28 --- /dev/null +++ b/docs/features/GOV-005-mysql57-charset-baseline/gitnexus/after.md @@ -0,0 +1,9 @@ +# GitNexus 开发后结果 + +- 执行：`npx gitnexus analyze`。 +- 工作区索引：528 个节点、553 条关系、5 个集群、0 条执行流程。 +- 增量分析：6 个已修改文件、18 个新增文件、0 个删除文件，并新增 1 个导入关系到可写集合。 +- 当前索引提交：`fa1df71`；工作区变化已进入增量图谱。 +- 状态：up-to-date。 + +实现提交后再次分析，把索引锚定到确定提交。 diff --git a/docs/features/GOV-005-mysql57-charset-baseline/gitnexus/comparison.md b/docs/features/GOV-005-mysql57-charset-baseline/gitnexus/comparison.md new file mode 100644 index 0000000..9efa0a9 --- /dev/null +++ b/docs/features/GOV-005-mysql57-charset-baseline/gitnexus/comparison.md @@ -0,0 +1,10 @@ +# GitNexus 前后对比 + +| 项目 | 开发前 | 开发后工作区 | 变化 | +|---|---:|---:|---:| +| 节点 | 432 | 528 | +96 | +| 关系 | 458 | 553 | +95 | +| 集群 | 5 | 5 | 0 | +| 执行流程 | 0 | 0 | 0 | + +增长来自数据库规范、契约测试与完整 GOV-005 档案；生产执行流程保持不变，符合影响预估。 diff --git a/docs/features/GOV-005-mysql57-charset-baseline/gitnexus/detected-changes.md b/docs/features/GOV-005-mysql57-charset-baseline/gitnexus/detected-changes.md new file mode 100644 index 0000000..b677aad --- /dev/null +++ b/docs/features/GOV-005-mysql57-charset-baseline/gitnexus/detected-changes.md @@ -0,0 +1,8 @@ +# GitNexus 变更检测 + +- 命令：`npx gitnexus detect-changes --repo a-share-analysis --scope staged`。 +- 最终暂存区：23 个文件、45 个符号。 +- 受影响流程：0。 +- 风险等级：低。 + +识别范围包含系统架构、开发规范、GOV-005 档案、测试与文档索引；版本纯文本和 Changelog 通过 Git diff 另行核对。 diff --git a/docs/features/GOV-005-mysql57-charset-baseline/gitnexus/impact-plan.md b/docs/features/GOV-005-mysql57-charset-baseline/gitnexus/impact-plan.md new file mode 100644 index 0000000..2c62479 --- /dev/null +++ b/docs/features/GOV-005-mysql57-charset-baseline/gitnexus/impact-plan.md @@ -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 实例。 diff --git a/docs/features/GOV-005-mysql57-charset-baseline/implementation-plan.md b/docs/features/GOV-005-mysql57-charset-baseline/implementation-plan.md new file mode 100644 index 0000000..70122e7 --- /dev/null +++ b/docs/features/GOV-005-mysql57-charset-baseline/implementation-plan.md @@ -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`，精确推送该标签并核对远程引用。 diff --git a/docs/features/GOV-005-mysql57-charset-baseline/manifest.yaml b/docs/features/GOV-005-mysql57-charset-baseline/manifest.yaml new file mode 100644 index 0000000..836a921 --- /dev/null +++ b/docs/features/GOV-005-mysql57-charset-baseline/manifest.yaml @@ -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 diff --git a/docs/features/GOV-005-mysql57-charset-baseline/prd.md b/docs/features/GOV-005-mysql57-charset-baseline/prd.md new file mode 100644 index 0000000..f80ffd7 --- /dev/null +++ b/docs/features/GOV-005-mysql57-charset-baseline/prd.md @@ -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 和完成门禁通过。 diff --git a/docs/features/GOV-005-mysql57-charset-baseline/qa/test-results.md b/docs/features/GOV-005-mysql57-charset-baseline/qa/test-results.md new file mode 100644 index 0000000..3c8b834 --- /dev/null +++ b/docs/features/GOV-005-mysql57-charset-baseline/qa/test-results.md @@ -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 验证属于首次启用持久化的后续功能门禁。 diff --git a/docs/features/GOV-005-mysql57-charset-baseline/qa/visual-qa.md b/docs/features/GOV-005-mysql57-charset-baseline/qa/visual-qa.md new file mode 100644 index 0000000..1e2e44a --- /dev/null +++ b/docs/features/GOV-005-mysql57-charset-baseline/qa/visual-qa.md @@ -0,0 +1,3 @@ +# 视觉验证 + +本功能只修改架构、开发规范、治理测试和追溯文档，不改变任何页面或交互，因此视觉验证不适用。 diff --git a/docs/features/GOV-005-mysql57-charset-baseline/release-notes.md b/docs/features/GOV-005-mysql57-charset-baseline/release-notes.md new file mode 100644 index 0000000..52ed0e9 --- /dev/null +++ b/docs/features/GOV-005-mysql57-charset-baseline/release-notes.md @@ -0,0 +1,8 @@ +# 发布说明 + +## v0.0.4 + +- 固定 MySQL 5.7.x、`utf8mb4` 和 `utf8mb4_general_ci`。 +- 增加 MySQL 8.x 禁用能力、排序语义、索引和迁移规范。 +- 新增数据库基线契约测试。 +- 第一阶段仍不启用 MySQL，只为后续 Repository 实现建立兼容基线。 diff --git a/docs/features/GOV-005-mysql57-charset-baseline/requirements.md b/docs/features/GOV-005-mysql57-charset-baseline/requirements.md new file mode 100644 index 0000000..b659cd6 --- /dev/null +++ b/docs/features/GOV-005-mysql57-charset-baseline/requirements.md @@ -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。 diff --git a/docs/features/GOV-005-mysql57-charset-baseline/review/code-review.md b/docs/features/GOV-005-mysql57-charset-baseline/review/code-review.md new file mode 100644 index 0000000..ad2ac19 --- /dev/null +++ b/docs/features/GOV-005-mysql57-charset-baseline/review/code-review.md @@ -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 diff --git a/docs/features/GOV-005-mysql57-charset-baseline/review/standards-review.md b/docs/features/GOV-005-mysql57-charset-baseline/review/standards-review.md new file mode 100644 index 0000000..1b653c6 --- /dev/null +++ b/docs/features/GOV-005-mysql57-charset-baseline/review/standards-review.md @@ -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 diff --git a/docs/features/GOV-005-mysql57-charset-baseline/rollback.md b/docs/features/GOV-005-mysql57-charset-baseline/rollback.md new file mode 100644 index 0000000..4583e9f --- /dev/null +++ b/docs/features/GOV-005-mysql57-charset-baseline/rollback.md @@ -0,0 +1,5 @@ +# 回退说明 + +本功能没有连接或修改数据库，回退不涉及数据操作。规则发布后如需修正，使用新的治理功能编号和中文修复提交更新架构、规范与测试，不移动或删除共享版本标签。 + +回退到 `v0.0.3` 只能用于读取升级前文档；后续已经按 MySQL 5.7 基线创建的迁移或部署不得通过改写历史撤销。 diff --git a/docs/features/GOV-005-mysql57-charset-baseline/test-plan.md b/docs/features/GOV-005-mysql57-charset-baseline/test-plan.md new file mode 100644 index 0000000..b785469 --- /dev/null +++ b/docs/features/GOV-005-mysql57-charset-baseline/test-plan.md @@ -0,0 +1,10 @@ +# 测试计划 + +- 先运行新增数据库基线测试，证明旧架构与规范因缺少 MySQL 5.7 约束而失败。 +- 更新文档后复测，要求数据库基线测试 2 个通过、0 个失败。 +- 运行治理测试，要求 5 个通过、0 个失败。 +- 运行 `git diff --check`。 +- 扫描仓库和暂存区，确认没有凭据或生产配置。 +- 执行 GitNexus 增量分析与最终暂存区变更检测。 +- 执行 `npm run governance:finish -- GOV-005 mysql57-charset-baseline`。 +- 本功能无界面变化，视觉验证不适用。 diff --git a/docs/governance/code-development-standards.md b/docs/governance/code-development-standards.md index f419921..76771dd 100644 --- a/docs/governance/code-development-standards.md +++ b/docs/governance/code-development-standards.md @@ -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 出发，检查： diff --git a/docs/index.md b/docs/index.md index 3b9c2f7..e663430 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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) 功能档案是需求、设计、代码、测试、版本和回退之间的唯一正式关联入口。 diff --git a/package.json b/package.json index ceb5c54..7636381 100644 --- a/package.json +++ b/package.json @@ -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" } diff --git a/tools/governance/mysql-baseline.test.mjs b/tools/governance/mysql-baseline.test.mjs new file mode 100644 index 0000000..7101f89 --- /dev/null +++ b/tools/governance/mysql-baseline.test.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}`); + } +});