docs(GOV-011): 统一运行时系列版本口径

2026-08-17 17:36:44 +08:00
parent dc8da80809
commit cce77aa884
9 changed files with 26 additions and 23 deletions
@@ -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. 当前实施顺序
@@ -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,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；项目不负责安装、升级、启动、停止、删除或修改这些系统软件与服务。

 ## 构建发布目录

@@ -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 要求

@@ -13,7 +13,7 @@ export interface RedisRuntimeConfig {
  tls: boolean;
 }

-/** MySQL 配置固定 5.7.42 兼容口径，启用状态决定凭据是否必填。 */
+/** MySQL 配置固定 5.7.x 兼容口径，启用状态决定凭据是否必填。 */
 export interface MysqlRuntimeConfig {
  enabled: boolean;
  host: string;
@@ -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 {
@@ -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,
  });
@@ -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/);
  }
 });

@@ -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/);
 });