From cce77aa884e460e58f5a60f93b509f55c4aa30b2 Mon Sep 17 00:00:00 2001 From: Citrons <909229731@qq.com> Date: Mon, 17 Aug 2026 17:36:44 +0800 Subject: [PATCH] =?UTF-8?q?docs(GOV-011):=20=E7=BB=9F=E4=B8=80=E8=BF=90?= =?UTF-8?q?=E8=A1=8C=E6=97=B6=E7=B3=BB=E5=88=97=E7=89=88=E6=9C=AC=E5=8F=A3?= =?UTF-8?q?=E5=BE=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/architecture/system-architecture.md | 4 ++-- docs/deployment/local-development.md | 4 ++-- docs/deployment/ubuntu-source-production.md | 2 +- docs/governance/code-development-standards.md | 20 +++++++++---------- server/libs/config/src/runtime-config.ts | 2 +- .../infrastructure/src/typeorm-options.ts | 2 +- tools/database/schema-baseline.mjs | 2 +- .../governance/environment-baseline.test.mjs | 3 ++- tools/governance/mysql-baseline.test.mjs | 10 ++++++---- 9 files changed, 26 insertions(+), 23 deletions(-) diff --git a/docs/architecture/system-architecture.md b/docs/architecture/system-architecture.md index 8b2f11f..3cd789a 100644 --- a/docs/architecture/system-architecture.md +++ b/docs/architecture/system-architecture.md @@ -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. 当前实施顺序 diff --git a/docs/deployment/local-development.md b/docs/deployment/local-development.md index a0e878e..9a224d9 100644 --- a/docs/deployment/local-development.md +++ b/docs/deployment/local-development.md @@ -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 工具和开发检查禁止连接、探测或读取生产库。 ## 启动顺序 diff --git a/docs/deployment/ubuntu-source-production.md b/docs/deployment/ubuntu-source-production.md index 5ee9883..e8d68ca 100644 --- a/docs/deployment/ubuntu-source-production.md +++ b/docs/deployment/ubuntu-source-production.md @@ -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；项目不负责安装、升级、启动、停止、删除或修改这些系统软件与服务。 ## 构建发布目录 diff --git a/docs/governance/code-development-standards.md b/docs/governance/code-development-standards.md index 00e8d0d..e281023 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；浏览器 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 要求 diff --git a/server/libs/config/src/runtime-config.ts b/server/libs/config/src/runtime-config.ts index 7f169c5..d1363ee 100644 --- a/server/libs/config/src/runtime-config.ts +++ b/server/libs/config/src/runtime-config.ts @@ -13,7 +13,7 @@ export interface RedisRuntimeConfig { tls: boolean; } -/** MySQL 配置固定 5.7.42 兼容口径，启用状态决定凭据是否必填。 */ +/** MySQL 配置固定 5.7.x 兼容口径，启用状态决定凭据是否必填。 */ export interface MysqlRuntimeConfig { enabled: boolean; host: string; diff --git a/server/libs/infrastructure/src/typeorm-options.ts b/server/libs/infrastructure/src/typeorm-options.ts index cdd819f..5a50535 100644 --- a/server/libs/infrastructure/src/typeorm-options.ts +++ b/server/libs/infrastructure/src/typeorm-options.ts @@ -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 { diff --git a/tools/database/schema-baseline.mjs b/tools/database/schema-baseline.mjs index fc64742..928dda3 100644 --- a/tools/database/schema-baseline.mjs +++ b/tools/database/schema-baseline.mjs @@ -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, }); diff --git a/tools/governance/environment-baseline.test.mjs b/tools/governance/environment-baseline.test.mjs index 45179de..bfd35e9 100644 --- a/tools/governance/environment-baseline.test.mjs +++ b/tools/governance/environment-baseline.test.mjs @@ -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/); } }); diff --git a/tools/governance/mysql-baseline.test.mjs b/tools/governance/mysql-baseline.test.mjs index 7101f89..730f344 100644 --- a/tools/governance/mysql-baseline.test.mjs +++ b/tools/governance/mysql-baseline.test.mjs @@ -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/); });