diff --git a/AGENTS.md b/AGENTS.md index c55ccb9..a19277d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,7 +9,7 @@ ## 强制要求 -1. 修改生产代码前必须执行 `npm run governance:start -- <功能编号> <短名称>`,刷新 GitNexus,并完成开发前影响分析。 +1. 开发下一版本前必须先执行 `npm run schema:baseline` 和 `npm run schema:verify`,将上一已发布版本的开发库 Schema 基线用中文提交推送 Gitea;随后才能执行 `npm run governance:start -- <功能编号> <短名称>`,刷新 GitNexus 并完成开发前影响分析。 2. 修改完成后必须执行测试、构建、视觉验证和 `npm run governance:finish -- <功能编号> <短名称>`,再次刷新 GitNexus并保存前后对比。 3. 任何功能必须先有 `docs/features/<功能编号>-<短名称>/` 功能档案;没有 PRD、需求、设计、计划和回退说明不得视为完成。 4. Git 提交必须使用中文 Conventional Commit,并带功能编号;禁止英文摘要和含糊提交信息。 @@ -19,11 +19,12 @@ 8. 禁止提交密钥、密码、访问令牌、生产数据、`.env` 和 GitNexus 本地索引;凭据不得写入远程 URL、文档、脚本或命令参数。 9. 开发完成后必须先通过代码 Review 和开发规范符合性 Review,再进入发布;Review 结论和问题处置必须写入功能档案。 10. 每次提交验证通过后必须立即推送当前分支到项目 Gitea;本次新建标签必须单独推送。推送失败时任务不得标记完成,禁止强推或自动覆盖未知远程提交。 +11. Schema 基线只能读取 `APP_ENV=development` 的 `a_share_analysis_dev`,启用时主机必须是开发机回环地址;禁止连接、探测或读取生产数据库。MySQL 未启用时只允许生成可验证的 `not_applicable` 清单,禁止用空 SQL 冒充基线。`governance:start` 还必须确认基线已提交、已推送且远程标签一致。 # GitNexus — Code Intelligence -This project is indexed by GitNexus as **a-share-analysis** (620 symbols, 651 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** (864 symbols, 1024 relationships, 17 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 94b6cc7..69ea086 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,12 @@ 本项目采用语义化版本。功能级变化请从 `docs/features/` 按功能编号追溯。 +## 0.0.6 - 2026-08-13 + +- 建立上一发布版本开发数据库 Schema 基线生成、规范化和自动校验工具。 +- 固定只读开发库安全边界、完整 MySQL 5.7 对象范围和禁止覆盖规则。 +- 为 MySQL 未启用状态建立可验证的不适用记录,并接入治理前后门禁。 + ## 0.0.5 - 2026-08-13 - 建立开发与生产环境配置契约及八份无秘密模板。 diff --git a/README.md b/README.md index 5a8c0ea..1eb6575 100644 --- a/README.md +++ b/README.md @@ -33,9 +33,13 @@ The first implementation slice is the market overview screen in `web/`. 开始任何模块前,先阅读根目录 `AGENTS.md`,然后运行: ```bash +npm run schema:baseline +npm run schema:verify npm run governance:start -- FEAT-MO-001 market-overview ``` +Schema 命令只允许处理固定开发库;当前 MySQL 未启用时会为上一发布版本生成可验证的不适用清单,不会连接数据库或创建空 SQL。完整规则见 [开发流程规范](docs/governance/development-workflow.md)。 + ## 项目仓库 - Gitea: diff --git a/VERSION b/VERSION index bbdeab6..1750564 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.0.5 +0.0.6 diff --git a/docs/features/GOV-007-development-schema-baseline/design.md b/docs/features/GOV-007-development-schema-baseline/design.md index 58f5414..78fa111 100644 --- a/docs/features/GOV-007-development-schema-baseline/design.md +++ b/docs/features/GOV-007-development-schema-baseline/design.md @@ -29,6 +29,7 @@ database/schema-baselines/v0.0.5/ - 只允许读取开发环境数据库。 - 加载开发专用本地配置,要求 `APP_ENV=development`。 - 数据库名固定为 `a_share_analysis_dev`;名称不匹配立即终止。 +- 启用真实导出时主机必须为 `127.0.0.1`、`localhost` 或 `::1`;远程开发库必须先通过运维建立本地 SSH 隧道,脚本不接受任意远程目标。 - 禁止通过命令参数覆盖环境类型、数据库名或传入任意 env 文件路径。 - 禁止连接、读取、探测或导出生产数据库;生产备份属于独立运维流程,不进入开发门禁。 - 推荐使用只拥有开发库结构读取和例程查看权限的专用账号,不授予生产访问能力。 @@ -45,7 +46,7 @@ database/schema-baselines/v0.0.5/ - 存储过程和函数。 - Event Scheduler 事件。 -导出命令必须使用 `--no-data --routines --triggers --events`,并使用符合 MySQL 5.7 的选项。账号凭据通过开发 env 或受控客户端配置提供,禁止出现在命令参数、日志或清单中。 +导出命令必须使用 `--no-data --routines --triggers --events`,并使用符合 MySQL 5.7 的选项。执行元数据查询的 `mysql` 客户端和执行导出的 `mysqldump` 客户端必须分别验证为 5.7.x。账号凭据通过开发 env 或受控客户端配置提供,禁止出现在命令参数、日志或清单中。 ## 规范化 @@ -91,7 +92,7 @@ database/schema-baselines/v0.0.5/ - SQL 包含 `DEFINER`、不稳定导出注释、当前 AUTO_INCREMENT 值或疑似凭据。 - 校验值不一致、目标版本目录已存在且内容不同,或 Git 工作区存在无法解释的 Schema 改动。 -禁止覆盖既有版本基线。需要修正时新增带原因的治理记录和修复提交,不静默重写已发布事实。 +禁止覆盖既有版本基线。需要修正时新增带原因的治理记录和修复提交,不静默重写已发布事实。`schema:verify` 是本地内容校验;`governance:start` 还要求基线文件已被 Git 跟踪、工作区无改动、当前分支已推送以及远程发布标签仍指向清单提交。 ## 首次启用与未启用状态 diff --git a/docs/features/GOV-007-development-schema-baseline/gitnexus/after.md b/docs/features/GOV-007-development-schema-baseline/gitnexus/after.md new file mode 100644 index 0000000..9937a95 --- /dev/null +++ b/docs/features/GOV-007-development-schema-baseline/gitnexus/after.md @@ -0,0 +1,52 @@ +# GitNexus 开发后基线 + +## GitNexus 状态 + +```text +Repository: /Users/citrons/Documents/Codex/2026-08-12/wo-x/a-share-analysis +Indexed: 8/13/2026, 12:44:53 PM +Indexed commit: 2c502eb +Current commit: 2c502eb +Status: ✅ up-to-date +``` + +## Git 已跟踪变更摘要 + +```text +AGENTS.md | 2 +- + 1 file changed, 1 insertion(+), 1 deletion(-) +``` + +## Git 工作区摘要 + +```text +MM AGENTS.md +M CHANGELOG.md +M README.md +M VERSION +M docs/features/GOV-007-development-schema-baseline/design.md +A docs/features/GOV-007-development-schema-baseline/gitnexus/comparison.md +A docs/features/GOV-007-development-schema-baseline/gitnexus/detected-changes.md +A docs/features/GOV-007-development-schema-baseline/gitnexus/impact-plan.md +A docs/features/GOV-007-development-schema-baseline/implementation-plan.md +A docs/features/GOV-007-development-schema-baseline/manifest.yaml +A docs/features/GOV-007-development-schema-baseline/prd.md +A docs/features/GOV-007-development-schema-baseline/qa/test-results.md +A docs/features/GOV-007-development-schema-baseline/qa/visual-qa.md +A docs/features/GOV-007-development-schema-baseline/release-notes.md +A docs/features/GOV-007-development-schema-baseline/requirements.md +A docs/features/GOV-007-development-schema-baseline/review/code-review.md +A docs/features/GOV-007-development-schema-baseline/review/standards-review.md +A docs/features/GOV-007-development-schema-baseline/rollback.md +A docs/features/GOV-007-development-schema-baseline/test-plan.md +M docs/governance/code-development-standards.md +M docs/governance/development-workflow.md +M docs/index.md +M package.json +A tools/database/fixtures/mysql57-schema-expected.sql +A tools/database/fixtures/mysql57-schema-input.sql +A tools/database/schema-baseline.mjs +A tools/database/schema-baseline.test.mjs +M tools/governance/finish.mjs +M tools/governance/start.mjs +``` diff --git a/docs/features/GOV-007-development-schema-baseline/gitnexus/comparison.md b/docs/features/GOV-007-development-schema-baseline/gitnexus/comparison.md new file mode 100644 index 0000000..c306234 --- /dev/null +++ b/docs/features/GOV-007-development-schema-baseline/gitnexus/comparison.md @@ -0,0 +1,17 @@ +# GitNexus 前后对比 + +## 开发前 + +- 基线提交:`e552b979b61342b9e3a47d463f0b9a821b0ad95d` +- 索引:641 节点、671 关系、0 流程。 +- 影响:现有治理档案函数总体 LOW,无数据库 Schema 执行流。 + +## 开发后 + +- 基线提交:`2c502ebbec25e45ac2980c08ed288ace194b7a04`(先独立提交并推送 v0.0.5 N/A 基线)。 +- 索引:837 节点、997 关系、17 流程。 +- 暂存区:23 文件、179 符号、17 条流程,risk=critical。 + +## 结论 + +新增关系和流程全部来自 GOV-007 Schema 安全门禁及其测试,没有引入市场业务、HTTP、RabbitMQ 或页面流程。风险从 LOW 提升到 critical 是因为新的 `governance:start` 前置门禁属于关键开发路径且整个模块首次加入;对应流程已用失败测试、修复测试、远程实测和独立 Review 覆盖。 diff --git a/docs/features/GOV-007-development-schema-baseline/gitnexus/detected-changes.md b/docs/features/GOV-007-development-schema-baseline/gitnexus/detected-changes.md new file mode 100644 index 0000000..1c791ba --- /dev/null +++ b/docs/features/GOV-007-development-schema-baseline/gitnexus/detected-changes.md @@ -0,0 +1,23 @@ +# GitNexus 暂存区变更检测 + +- 检测日期:2026-08-13 +- 检测范围:staged +- 变更文件:23 +- 变更符号:179 +- 受影响流程:17 +- GitNexus 风险:critical(已按关键门禁完成专项验证) + +## 受影响流程 + +变更集中在数据库 Schema 治理模块: + +- Schema 生成、规范化与敏感/数据写入扫描。 +- 清单、SHA-256 与目录文件集合验证。 +- MySQL 5.7 双客户端、服务端和字符规则验证。 +- 当前发布版本本地校验。 +- 已提交、已推送、远程分支和远程标签严格校验。 +- CLI 生成/验证和 `governance:start` 入口。 + +## 风险解释 + +GitNexus 以“新增模块的全部 17 条流程均在本次变更中”为依据给出 critical,而非发现了业务市场分析、生产数据库或跨服务调用回归。本功能本身是开发前关键门禁,因此该风险等级按关键路径处理:执行 20 项 Schema 行为测试、既有 13 项治理回归测试、真实 Gitea `ls-remote` 校验、三轮独立代码 Review 和完成门禁。任何 Review Important 项未关闭前不发布。 diff --git a/docs/features/GOV-007-development-schema-baseline/gitnexus/impact-plan.md b/docs/features/GOV-007-development-schema-baseline/gitnexus/impact-plan.md new file mode 100644 index 0000000..2b2a590 --- /dev/null +++ b/docs/features/GOV-007-development-schema-baseline/gitnexus/impact-plan.md @@ -0,0 +1,32 @@ +# GitNexus 开发前影响分析 + +- 分析日期:2026-08-13 +- 基线提交:`e552b979b61342b9e3a47d463f0b9a821b0ad95d` +- 索引状态:up-to-date + +## 查询范围 + +围绕 `governance start development gate feature record database schema baseline` 查询现有治理入口。GitNexus 未识别出业务执行流,相关定义集中在: + +- `tools/governance/start.mjs` +- `tools/governance/finish.mjs` +- `tools/governance/feature-record.mjs` +- `tools/governance/feature-record.test.mjs` +- `package.json` +- 治理规范和 GOV-007 设计档案 + +## 符号影响 + +- `getFeatureDirectory`:LOW;3 个直接依赖,分别是 start、finish 和治理测试;0 个执行流、0 个跨模块影响。 +- `validateFeatureId`:LOW;GitNexus 没有发现上游执行流,实际文本导入由 start、finish 和测试覆盖。 +- `getRequiredFeatureFiles`:LOW;没有识别到执行流,完成门禁由现有自动化测试保护。 + +## 实施边界 + +本功能不修改上述已有公共函数语义。Schema 逻辑新增为独立模块,只让 `start.mjs` 调用一个只读的“当前已发布版本基线有效”入口。生成、规范化和写入由独立命令负责,因此不会让一般功能档案解析承担数据库职责。 + +## 风险结论 + +总体风险:LOW。 + +没有 HIGH 或 CRITICAL 结果,不需要额外中止确认。主要回归面是治理开始命令可能因缺少上一版本基线被有意阻断;通过 N/A 与真实 Schema 两类测试、既有治理回归测试和命令级验证覆盖。 diff --git a/docs/features/GOV-007-development-schema-baseline/implementation-plan.md b/docs/features/GOV-007-development-schema-baseline/implementation-plan.md new file mode 100644 index 0000000..5184775 --- /dev/null +++ b/docs/features/GOV-007-development-schema-baseline/implementation-plan.md @@ -0,0 +1,124 @@ +# GOV-007 开发数据库 Schema 基线与版本门禁实施计划 + +> **执行要求:** 按测试驱动方式逐项实施;每个行为先观察失败,再写最小实现。实施期间不得连接、探测或读取任何数据库,真实导出入口仅通过固定样本和依赖注入验证。 + +**目标:** 建立只允许读取固定开发库、可确定性规范化和校验完整 MySQL 5.7 Schema,并在下一版本开发前强制验证上一已发布版本基线的治理门禁。 + +**架构:** `tools/database/schema-baseline.mjs` 集中维护安全配置、命令构造、SQL 规范化、产物生成及校验,避免将一条连续的安全流程过度拆分。`governance:start` 只调用“当前已发布版本基线是否存在且有效”的纯门禁,不负责静默生成或覆盖产物;生成基线必须先由独立命令完成、提交并推送。 + +**技术栈:** Node.js 22 LTS、Node 内置测试运行器、MySQL 5.7 `mysql`/`mysqldump` 客户端、SHA-256、GitNexus、Git/Gitea。 + +## 全局约束 + +- 数据来源只能是 `APP_ENV=development`、数据库 `a_share_analysis_dev`。 +- MySQL 客户端与服务端只能是 5.7.x,字符集固定 `utf8mb4`,排序规则固定 `utf8mb4_general_ci`。 +- 导出必须包含 `--no-data --routines --triggers --events`,密码不得出现在参数、日志、SQL 或清单中。 +- 不接受环境类型、数据库名或 env 路径的命令行覆盖。 +- 当前 MySQL 未启用,不运行真实数据库命令,只生成可验证的 `not_applicable` 清单,且不创建空 `schema.sql`。 +- 已存在版本目录不得静默覆盖;真实 Schema 只含结构,不含任何数据。 +- 修改关键符号前执行 GitNexus impact,提交前执行 GitNexus detect-changes。 + +--- + +### 任务 1:锁定安全边界和可观察契约 + +**文件:** + +- 新建:`tools/database/schema-baseline.test.mjs` +- 新建:`tools/database/fixtures/mysql57-schema-input.sql` +- 新建:`tools/database/fixtures/mysql57-schema-expected.sql` +- 新建:`docs/features/GOV-007-development-schema-baseline/test-plan.md` + +**接口:** + +- 消费:设计规格中固定的环境、版本、Schema 范围和禁止覆盖规则。 +- 产出:后续实现必须满足的公开函数行为和固定 SQL 输入/输出。 + +- [ ] 编写配置测试,分别证明非 `development`、非 `a_share_analysis_dev`、非 MySQL 5.7、错误字符集和错误排序规则被拒绝。 +- [ ] 运行 `node --test tools/database/schema-baseline.test.mjs`,确认因实现模块不存在而失败。 +- [ ] 编写命令构造测试,手工断言参数包含 `--no-data`、`--routines`、`--triggers`、`--events`,且密码字符串不出现在参数中。 +- [ ] 编写固定 SQL 样本测试,手工断言时间注释、`DEFINER` 和表级当前自增值被删除,列级 `AUTO_INCREMENT` 以及表、视图、触发器、例程和事件定义完整保留。 +- [ ] 编写产物测试,证明清单和校验文件的 SHA-256 与 SQL 一致、不同内容的既有目录被拒绝、未启用 MySQL 时只有 `manifest.yaml` 而没有 `schema.sql`。 + +### 任务 2:实现纯函数和文件产物 + +**文件:** + +- 新建:`tools/database/schema-baseline.mjs` +- 修改:`package.json` + +**接口:** + +- 产出:`assertSafeDevelopmentConfiguration(config)`、`assertMysql57Metadata(metadata)`、`buildMysqldumpArguments(config)`、`normalizeSchemaSql(sql)`、`buildCapturedArtifacts(metadata, sql)`、`buildNotApplicableArtifacts(metadata)`、`persistBaselineArtifacts(target, artifacts)`、`verifyBaselineDirectory(target, expectedRelease)`。 + +- [ ] 实现最小配置与元数据校验,使安全边界测试通过。 +- [ ] 实现参数数组构造;连接密码只允许由子进程环境传递,不进入参数。 +- [ ] 实现确定性 SQL 规范化和敏感内容扫描,使固定样本逐字节匹配期望文件。 +- [ ] 实现 SHA-256、平面可审计清单、标准 checksum 文件和目录校验。 +- [ ] 采用同目录临时目录加原子改名写入;目标已存在时仅允许逐字节相同内容复用,其他情况报错。 +- [ ] 运行 Schema 测试,确认所有测试转绿;再运行既有治理、MySQL 与环境基线测试,确认没有回归。 + +### 任务 3:实现真实入口但不连接数据库 + +**文件:** + +- 修改:`tools/database/schema-baseline.mjs` +- 修改:`package.json` +- 修改:`deploy/env/development/api.env.example`(仅在契约字段缺失时修改) + +**接口:** + +- 消费:固定路径 `deploy/env/development/api.env`;文件不存在且仓库模板明确 `MYSQL_ENABLED=false` 时允许生成不适用记录。 +- 产出:`npm run schema:baseline` 与 `npm run schema:verify`,版本自动从最近语义化版本标签解析。 + +- [ ] 测试命令行拒绝额外参数,证明不能传入 production env、数据库名或任意 env 路径。 +- [ ] 测试未启用 MySQL 的入口不会调用数据库执行器,并为最近发布标签创建可验证不适用记录。 +- [ ] 测试启用分支只构造固定 `mysql`/`mysqldump` 参数,并在客户端/服务端版本或数据库字符规则不符时阻断。 +- [ ] 实现固定配置加载、最近标签与标签提交解析、回环主机检查、mysql/mysqldump 双客户端和服务端元数据检查、真实导出执行路径;本次验证不调用该路径。 +- [ ] 运行 `npm run schema:baseline` 为 `v0.0.5` 生成 `not_applicable` 清单,并运行 `npm run schema:verify` 验证;确认不存在 `schema.sql`。 + +### 任务 4:接入版本开发前门禁与治理规范 + +**文件:** + +- 修改:`tools/governance/start.mjs` +- 修改:`tools/governance/feature-record.test.mjs` 或新增对应集成测试。 +- 修改:`AGENTS.md` +- 修改:`docs/governance/development-workflow.md` +- 修改:`docs/governance/code-development-standards.md` +- 修改:`README.md` +- 修改:`docs/index.md` + +**接口:** + +- 消费:`assertCurrentReleasedBaselinePublished(repositoryRoot)`。 +- 产出:治理开始命令只有在上一已发布版本 Schema 基线有效时才继续 GitNexus 开发前流程。 + +- [ ] 先写失败测试:基线缺失或失效时 `governance:start` 的前置检查拒绝继续,有效 N/A 或真实基线时允许继续。 +- [ ] 在 `start.mjs` 刷新 GitNexus 之前调用严格发布验证,检查 Git 跟踪、工作区、origin 分支和远程标签;不自动生成、不覆盖基线。 +- [ ] 文档明确顺序为“生成并验证基线 → 中文提交 → 推送 Gitea → 治理开始”,以及首次启用 MySQL 时必须从真实开发库导出。 +- [ ] 代码规范增加 Schema 仅结构、MySQL 5.7 完整对象范围、确定性规范化、禁止生产数据库和禁止直接改共享表的规则。 + +### 任务 5:验证、Review 与发布 + +**文件:** + +- 新建或更新:GOV-007 完整功能档案。 +- 修改:`VERSION`、`CHANGELOG.md`、`docs/index.md`。 + +**接口:** + +- 产出:可追溯的 `v0.0.6` 治理版本。 + +- [ ] 执行 Schema、治理、MySQL、环境测试,执行 `git diff --check`、敏感信息扫描和适用构建检查。 +- [ ] 执行 `npx gitnexus analyze` 与变更检测,保存开发前后差异和风险结论。 +- [ ] 完成代码 Review 与开发规范符合性 Review;两份报告必须包含独立一行 `最终结论:passed`。 +- [ ] 执行 `npm run governance:finish -- GOV-007 development-schema-baseline` 并保存证据。 +- [ ] 使用中文 Conventional Commit 提交并立即推送 `origin/main`,回填实现提交和远程 SHA。 +- [ ] 封存最终验证结果,提交并推送;创建带注释标签 `v0.0.6` 并只精确推送该标签。 + +## 计划自审 + +- 设计中的安全配置、完整对象范围、规范化、清单校验、禁止覆盖、未启用路径、治理门禁、双 Review 和发布要求均有对应任务。 +- 所有实现接口在任务 2 明确定义,任务 3、4 只消费这些接口,没有命名漂移。 +- 计划不包含待定项;真实数据库路径可实现但本次只以依赖注入和固定样本验证,符合禁止连接数据库的范围。 diff --git a/docs/features/GOV-007-development-schema-baseline/manifest.yaml b/docs/features/GOV-007-development-schema-baseline/manifest.yaml new file mode 100644 index 0000000..f55292c --- /dev/null +++ b/docs/features/GOV-007-development-schema-baseline/manifest.yaml @@ -0,0 +1,18 @@ +id: GOV-007 +name: 开发数据库 Schema 基线与版本门禁 +slug: development-schema-baseline +status: released +owner: project +created_at: 2026-08-13 +prd: prd.md +requirements: requirements.md +design: design.md +implementation_plan: implementation-plan.md +test_plan: test-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.6 diff --git a/docs/features/GOV-007-development-schema-baseline/prd.md b/docs/features/GOV-007-development-schema-baseline/prd.md new file mode 100644 index 0000000..70dd382 --- /dev/null +++ b/docs/features/GOV-007-development-schema-baseline/prd.md @@ -0,0 +1,50 @@ +# 开发数据库 Schema 基线与版本门禁 PRD + +- 功能编号:GOV-007 +- PRD 版本:0.1 +- 状态:approved +- 日期:2026-08-13 + +## 问题 + +数据库迁移文件只能表达预期变化,不能证明每个版本开始前开发数据库的实际结构,也无法发现手工改表、对象遗漏或环境误连。当前 MySQL 尚未启用,还需要一种不伪造空 Schema 的可审计状态。 + +## 目标 + +- 每个新应用版本开发前,封存上一已发布版本的开发库完整 Schema。 +- 将环境、数据库名、MySQL 版本、字符集、排序规则和对象范围设置为强制门禁。 +- 生成确定性、可校验、可版本控制且不含数据或凭据的产物。 +- MySQL 未启用时生成可验证的不适用记录。 +- 在 `governance:start` 前阻断缺失或失效的上一版本基线。 + +## 用户流程 + +1. 开发者确认上一已发布语义化版本。 +2. 执行 `npm run schema:baseline` 生成或幂等验证对应目录。 +3. 执行 `npm run schema:verify` 复核清单、版本、提交和校验值。 +4. 将基线用中文提交推送项目 Gitea。 +5. 执行 `governance:start` 开始下一版本功能。 + +## 非目标 + +- 不备份任何业务数据、用户数据或生产数据。 +- 不连接、探测、读取或验证生产数据库。 +- 不替代生产运维备份、数据库恢复演练或迁移框架。 +- 本版本不启动 MySQL,也不对真实数据库执行命令。 + +## 风险 + +- `DEFINER`、导出时间和当前自增值会造成不可移植或无意义差异。 +- 参数可覆盖 env 或数据库名会扩大到生产资源的误操作范围。 +- 空 SQL 或可篡改的 N/A 清单会让门禁形式化而不可信。 +- 既有版本目录被覆盖会破坏发布历史。 + +## 验收标准 + +- 开发库、MySQL 5.7 和字符规则不符合时全部阻断。 +- 导出参数明确只含结构并覆盖表、视图、触发器、例程和事件。 +- 规范化固定样本精确保留业务对象和列自增属性。 +- 真实基线三方 SHA-256 一致;N/A 基线只有清单。 +- 版本、标签提交、对象范围、状态和文件集合都能自动校验。 +- 既有不同内容禁止覆盖,命令行不能切换 production env 或数据库。 +- 治理流程、双 Review、GitNexus、中文提交和 Gitea 推送完成。 diff --git a/docs/features/GOV-007-development-schema-baseline/qa/test-results.md b/docs/features/GOV-007-development-schema-baseline/qa/test-results.md new file mode 100644 index 0000000..28daabf --- /dev/null +++ b/docs/features/GOV-007-development-schema-baseline/qa/test-results.md @@ -0,0 +1,24 @@ +# 测试结果 + +- 日期:2026-08-13 +- 环境:本地开发仓库;未启动 MySQL,未连接任何数据库。 + +## 最新结果 + +- Schema 基线测试:20/20 passed。 +- 治理测试:5/5 passed。 +- MySQL 兼容基线:2/2 passed。 +- 环境与部署基线:6/6 passed。 +- `npm run schema:verify`:`v0.0.5 (not_applicable)` passed。 +- 严格 `governance:start` smoke:基线未提交时按预期阻断;独立提交并推送后通过。 +- `git ls-remote origin refs/heads/main` 与 `refs/tags/v0.0.5^{}`:远程 SHA 均按实时查询核对通过。 +- `git diff --check`:passed。 +- Node 语法检查:passed。 + +## 测试先行留痕 + +首次测试因模块不存在以 `ERR_MODULE_NOT_FOUND` 失败。实现期间失败测试先后捕获:MySQL 密码条件必填、标签提交核对、清单篡改、标准 5.7 视图 DEFINER、例程字符串误改、顶层/例程 DML 区分、双客户端版本、未跟踪基线、陈旧 tracking ref、普通与可执行注释 DML 绕过。每项均在实现修复后转绿。 + +## 未执行项 + +当前 MySQL 功能开关为关闭,本功能范围明确禁止连接数据库,因此未执行真实 MySQL 5.7 导出。首次启用 MySQL 的版本必须在固定开发库补做真实集成验证。 diff --git a/docs/features/GOV-007-development-schema-baseline/qa/visual-qa.md b/docs/features/GOV-007-development-schema-baseline/qa/visual-qa.md new file mode 100644 index 0000000..222d7d7 --- /dev/null +++ b/docs/features/GOV-007-development-schema-baseline/qa/visual-qa.md @@ -0,0 +1,5 @@ +# 视觉 QA + +本功能没有页面、组件、样式、图表或浏览器交互变化,视觉 QA 不适用。 + +结论:not_applicable diff --git a/docs/features/GOV-007-development-schema-baseline/release-notes.md b/docs/features/GOV-007-development-schema-baseline/release-notes.md new file mode 100644 index 0000000..14a1819 --- /dev/null +++ b/docs/features/GOV-007-development-schema-baseline/release-notes.md @@ -0,0 +1,11 @@ +# 发布说明 + +## v0.0.6 + +- 实现开发数据库 Schema 基线生成与只读验证命令。 +- 固定 MySQL 5.7、`a_share_analysis_dev`、`utf8mb4` 和 `utf8mb4_general_ci` 安全边界。 +- 增加完整对象导出参数、确定性 SQL 规范化、SHA-256 三方校验和禁止覆盖机制。 +- 为 MySQL 未启用状态建立不伪造空 SQL 的 `not_applicable` 基线。 +- 将上一发布版本 Schema 基线验证接入开发前和开发后治理门禁。 +- `governance:start` 仅接受已提交、已推送且远程标签一致的基线;真实导出限制在本机回环地址并分别校验 `mysql` 与 `mysqldump` 客户端版本。 +- 实现提交将在发布封存时回填。 diff --git a/docs/features/GOV-007-development-schema-baseline/requirements.md b/docs/features/GOV-007-development-schema-baseline/requirements.md new file mode 100644 index 0000000..6b750a5 --- /dev/null +++ b/docs/features/GOV-007-development-schema-baseline/requirements.md @@ -0,0 +1,33 @@ +# 工程需求 + +## 安全配置 + +- `APP_ENV` 必须为 `development`,`MYSQL_DATABASE` 必须为 `a_share_analysis_dev`。 +- 字符集固定 `utf8mb4`,排序规则固定 `utf8mb4_general_ci`。 +- 启用 MySQL 后 host、port、username、password 均为必填;密码只通过子进程环境传递。 +- 启用 MySQL 时主机只能是本机回环地址;远程开发库必须先由运维建立本地 SSH 隧道,脚本不接受任意远程目标。 +- 命令行不接受 env 文件、环境类型、数据库名或其他覆盖参数。 + +## 数据库与导出 + +- 客户端和服务端版本必须匹配 MySQL 5.7.x。 +- 执行元数据查询的 `mysql` 客户端和执行导出的 `mysqldump` 客户端都必须分别验证为 5.7.x。 +- `mysqldump` 使用 `--no-data --routines --triggers --events`,不得输出 INSERT 或 REPLACE。 +- 完整对象范围为表、索引、外键、视图、触发器、存储过程、函数和事件。 +- 规范化删除不稳定注释、环境 `DEFINER` 和表选项当前自增值,保留列自增属性。 + +## 产物与校验 + +- 目录固定为 `database/schema-baselines/<已发布版本>/`。 +- 真实基线包含 `schema.sql`、`manifest.yaml`、`checksum.sha256`。 +- `manifest.yaml` 使用 JSON 兼容 YAML 的结构化格式,可由标准 JSON 解析器读取。 +- 清单记录版本、标签提交、来源环境、库名、版本、字符规则、对象范围、生成器和 SHA-256。 +- 目录采用同父目录临时写入后原子改名;既有目录只允许逐字节相同的幂等重跑。 +- MySQL 未启用时只生成 `manifest.yaml`,状态为 `not_applicable`,原因是 `mysql_disabled`,所有对象均为未捕获。 + +## 流程 + +- `governance:start` 在写入功能档案或刷新 GitNexus 前只读验证上一发布版本基线。 +- `governance:start` 还要求基线文件已被 Git 跟踪、无未提交改动、当前分支已推送且远程发布标签提交一致;`schema:verify` 只负责本地内容校验。 +- `governance:finish` 运行全部既有治理测试、Schema 测试和基线验证。 +- 本版本实际产物为 `v0.0.5` 的 N/A 清单,不连接任何数据库。 diff --git a/docs/features/GOV-007-development-schema-baseline/review/code-review.md b/docs/features/GOV-007-development-schema-baseline/review/code-review.md new file mode 100644 index 0000000..a3836b5 --- /dev/null +++ b/docs/features/GOV-007-development-schema-baseline/review/code-review.md @@ -0,0 +1,24 @@ +# 代码 Review + +## 第一轮 + +结论:changes_required。发现 5 个 Important 和 2 个 Minor:未提交基线可绕过门禁、远程生产主机可被误连、标准 MySQL 5.7 视图 DEFINER 不兼容、顶层 DML 扫描绕过/例程误拒、未校验 mysql 客户端、N/A 清单字段不严和缺少严格门禁测试。 + +处置:全部补失败测试并修复。增加回环主机、双客户端、结构化清单、Git 跟踪与远程同步验证。 + +## 第二轮 + +结论:changes_required。发现普通/版本注释可绕过顶层 DML 扫描,远程分支校验依赖可能陈旧的 tracking ref。 + +处置:按真实分隔符解析顶层语句,剥离前置普通注释但扫描 MySQL 可执行注释;远程分支改为实时 `git ls-remote origin refs/heads/`,并增加回归测试。 + +## 最终复审 + +- 普通注释、版本 SET 注释、MySQL 可执行注释中的顶层 INSERT/REPLACE 均被拒绝。 +- 例程内合法 DML 保留,标准 MySQL 5.7 视图 DEFINER 输出可规范化。 +- 远程分支使用实时 `git ls-remote`,远程标签提交与清单提交核对。 +- 20 项 Schema 测试、治理/数据库/环境回归测试均通过。 + +问题处置:第一、二轮所有 Critical/Important/Minor 问题均已关闭并有回归测试;未保留延期问题。 + +最终结论:passed diff --git a/docs/features/GOV-007-development-schema-baseline/review/standards-review.md b/docs/features/GOV-007-development-schema-baseline/review/standards-review.md new file mode 100644 index 0000000..52779ef --- /dev/null +++ b/docs/features/GOV-007-development-schema-baseline/review/standards-review.md @@ -0,0 +1,20 @@ +# 开发规范符合性 Review + +## 检查范围 + +- PRD、需求、确认设计、实施计划、测试计划、GitNexus 前后报告齐全。 +- 关键安全边界、规范化取舍、原子写入和远程门禁有中文原因注释。 +- 主要业务流程集中在一个可连续阅读的模块,没有过度拆分。 +- 测试遵循先失败后实现,固定样本和期望值独立维护。 +- MySQL 5.7、`utf8mb4`、`utf8mb4_general_ci` 和开发库限制符合规范。 +- 未写入密码、Token、真实 env、生产地址或生产数据。 +- `v0.0.5` N/A 基线已作为独立中文提交推送 Gitea。 +- 视觉变化不适用,已记录原因。 + +## 复审结果 + +- 最终代码复审已通过,所有 Important 问题均关闭并有测试证据。 +- `governance:finish` 将在发布前重新执行全部治理、Schema 和 GitNexus 门禁。 +- 实现提交、封存提交和 `v0.0.6` 标签推送属于本档案的发布步骤,完成后回填 SHA。 + +最终结论:passed diff --git a/docs/features/GOV-007-development-schema-baseline/rollback.md b/docs/features/GOV-007-development-schema-baseline/rollback.md new file mode 100644 index 0000000..b6ce46d --- /dev/null +++ b/docs/features/GOV-007-development-schema-baseline/rollback.md @@ -0,0 +1,12 @@ +# 回退说明 + +本功能没有连接数据库、执行迁移或修改任何开发/生产数据。回退应用代码时可以恢复上一提交中的治理脚本和文档,但不得删除或改写已经随版本发布的 `database/schema-baselines/` 历史事实。 + +若工具实现存在缺陷,使用新的中文修复提交: + +1. 保留原版本基线目录和 Git 历史。 +2. 在新的治理档案中记录错误原因、影响范围和修复策略。 +3. 对尚未发布的错误产物可在审查后修正;已发布产物通过追加更正记录处理,不移动共享标签。 +4. 首次启用 MySQL 后,任何修复都只允许读取开发库,生产数据库仍属于禁止范围。 + +N/A 清单没有 Schema 或数据可恢复。`v0.0.5` 目录证明当时 MySQL 功能开关关闭,不能在未来启用 MySQL 后追溯改写为真实 Schema。 diff --git a/docs/features/GOV-007-development-schema-baseline/test-plan.md b/docs/features/GOV-007-development-schema-baseline/test-plan.md new file mode 100644 index 0000000..af2d42c --- /dev/null +++ b/docs/features/GOV-007-development-schema-baseline/test-plan.md @@ -0,0 +1,32 @@ +# 测试计划 + +## 测试先行证据 + +- 首次执行 `node --test tools/database/schema-baseline.test.mjs` 因生产模块不存在而失败,错误为 `ERR_MODULE_NOT_FOUND`。 +- 首轮实现后固定样本和清单嵌套字段测试暴露规范化与解析缺口,修正后转绿。 +- 安全自审再以失败测试发现密码未设为条件必填、标签提交未核对、真实清单版本可篡改和 N/A 对象范围可伪造,均已实现对应阻断。 + +## 自动化范围 + +- 配置:环境、库名、字符集、排序规则、启用后的必填凭据。 +- 版本:MySQL 客户端、服务端和发布标签提交。 +- 命令:完整结构参数、密码不进参数、额外参数拒绝。 +- SQL:时间注释、`DEFINER`、表级自增值、列自增属性和五类对象。 +- 产物:SHA-256、精确文件集合、禁止覆盖、篡改检测、空 SQL 拒绝。 +- N/A:零数据库调用、只有清单、明确关闭版本和对象范围。 +- 回归:治理测试、MySQL 基线测试、环境基线测试、Schema 验证。 +- 严格发布门禁:未跟踪基线、未提交改动、未推送分支或远程标签不一致均阻断;本地 `schema:verify` 与发布前 `governance:start` 的职责分别验证。 + +## 最终命令 + +```bash +npm run test:governance +npm run test:mysql-baseline +npm run test:environment-baseline +npm run test:schema-baseline +npm run schema:verify +npm run governance:finish -- GOV-007 development-schema-baseline +git diff --check +``` + +本功能无 Web 页面、CSS 或图表变化,视觉 QA 记录为不适用。 diff --git a/docs/governance/code-development-standards.md b/docs/governance/code-development-standards.md index f72a6f1..ce7f5ab 100644 --- a/docs/governance/code-development-standards.md +++ b/docs/governance/code-development-standards.md @@ -123,6 +123,15 @@ count += 1; - 每份迁移脚本必须能够从上一版本基线在 MySQL 5.7 正向执行;禁止用直接修改共享数据库表代替迁移脚本。 - 代码 Review 必须检查服务端版本、字符集、排序规则、SQL/迁移兼容性、索引长度和字符串比较语义;任一不符合项按 Important 处理并阻断发布。 +### Schema 基线规范 + +- 每个新应用版本开发前必须封存上一已发布版本的开发库 Schema;只能读取 `APP_ENV=development`、`a_share_analysis_dev`,禁止连接、探测或读取生产数据库。 +- 导出使用 MySQL 5.7 `mysqldump` 的 `--no-data --routines --triggers --events`,完整保留表、索引、外键、视图、触发器、存储过程、函数和事件,不得包含任何表数据。 +- 规范化必须确定性删除导出时间、环境 `DEFINER` 和表选项中的当前 `AUTO_INCREMENT=<值>`,同时保留列定义的 `AUTO_INCREMENT` 属性和业务 SQL。 +- 账号密码只能通过受控子进程环境传递,不得进入参数、日志、SQL、清单或 checksum 文件。 +- `manifest.yaml`、`checksum.sha256` 和 `schema.sql` 的 SHA-256 必须一致;既有版本目录只允许内容完全一致的幂等验证,不允许覆盖。 +- MySQL 未启用时只创建状态为 `not_applicable` 的清单,不得创建空 `schema.sql`;启用后的缺失基线必须阻断下一版本开发。 + ## 12. 测试要求 - 功能和缺陷修复遵循测试先行:先看到测试因缺少行为而失败,再实现最小代码。 diff --git a/docs/governance/development-workflow.md b/docs/governance/development-workflow.md index 8e8f9d1..71df531 100644 --- a/docs/governance/development-workflow.md +++ b/docs/governance/development-workflow.md @@ -16,22 +16,26 @@ released → superseded ## 3. 开发前流程 -1. 分配功能编号和英文短名称。 -2. 建立 `docs/features/<编号>-<短名称>/`。 -3. 编写 `prd.md`,明确用户问题、目标、范围、非目标、用户流程、指标、风险和验收标准。 -4. PRD 审核通过后,将产品需求转换为可测试的工程需求。 -5. 比较可选方案,记录设计与关键决策。 -6. 更新 API、事件和数据结构契约。 -7. 编写测试计划和实施计划。 -8. 明确功能需要的环境变量、功能开关和部署影响;同步更新开发/生产模板,禁止只修改本机真实 env。 -9. 确保 Git 工作区基线可识别,执行: +1. 确认上一已发布语义化版本及标签提交,执行 `npm run schema:baseline` 和 `npm run schema:verify`。 +2. MySQL 已启用时只能从 `APP_ENV=development`、`a_share_analysis_dev` 和本机回环地址导出完整 Schema;MySQL 未启用时只保存 `not_applicable` 清单,不创建空 SQL。 +3. 将 `database/schema-baselines/<上一发布版本>/` 作为独立中文提交推送 Gitea,核对本地和远程 SHA;既有版本目录禁止覆盖。只有 Git 已跟踪、工作区无改动、当前分支已推送且远程发布标签提交一致时,`governance:start` 才会继续。 +4. 分配功能编号和英文短名称。 +5. 建立 `docs/features/<编号>-<短名称>/`。 +6. 编写 `prd.md`,明确用户问题、目标、范围、非目标、用户流程、指标、风险和验收标准。 +7. PRD 审核通过后,将产品需求转换为可测试的工程需求。 +8. 比较可选方案,记录设计与关键决策。 +9. 更新 API、事件和数据结构契约。 +10. 编写测试计划和实施计划。 +11. 明确功能需要的环境变量、功能开关和部署影响;同步更新开发/生产模板,禁止只修改本机真实 env。 +12. 确保 Git 工作区基线可识别,执行: ```bash npm run governance:start -- FEAT-MO-001 market-overview ``` -10. 运行 GitNexus 查询、上下文和影响分析,将结果写入 `gitnexus/impact-plan.md`。 -11. 高风险或关键路径变化必须先向用户说明影响,再进入开发。 +13. `governance:start` 会只读复核上一发布版本 Schema 基线;缺失、失效或版本不一致时立即阻断,不会代为生成。 +14. 运行 GitNexus 查询、上下文和影响分析,将结果写入 `gitnexus/impact-plan.md`。 +15. 高风险或关键路径变化必须先向用户说明影响,再进入开发。 开发前必须至少回答:修改什么、为什么修改、影响谁、如何验证、失败后如何回退。 @@ -81,8 +85,18 @@ npm run governance:finish -- FEAT-MO-001 market-overview - 中文提交已关联功能编号。 - 当前分支和本次新建标签已推送到 `origin`,功能档案保存远程核对结果。 - 配置契约变化已同步开发/生产模板和适用的 Compose、systemd、Nginx及部署文档。 +- 下一版本开发前所需的上一发布版本 Schema 基线已验证、独立提交并推送 Gitea。 -## 7. 提交流程 +## 7. 数据库 Schema 基线 + +- 基线目录固定为 `database/schema-baselines/vX.Y.Z/`,版本是被备份的已发布版本。 +- 真实基线由 `schema.sql`、`manifest.yaml`、`checksum.sha256` 组成;范围包括表、索引、外键、视图、触发器、存储过程、函数和 Event Scheduler 事件,不含数据。 +- MySQL 未启用时目录只能包含 `manifest.yaml`,状态为 `not_applicable`、原因为 `mysql_disabled`。 +- `schema:baseline` 不接受 env 路径、环境类型或数据库名参数;配置路径固定在开发环境,生产配置和生产数据库不属于该命令的权限范围。 +- 修正已发布基线必须新增治理记录说明原因,禁止静默覆盖或重写历史目录。 +- 首次启用 MySQL 的版本必须通过迁移建立开发库,并在 MySQL 5.7 开发环境生成第一份真实 Schema 基线。 + +## 8. 提交流程 提交格式: @@ -114,7 +128,7 @@ git push origin <本次标签名> 禁止使用 `--force`、`--force-with-lease` 或 `--tags` 代替精确推送。推送失败时不得宣称任务完成;应记录不含凭据的错误摘要,排查后重试同一精确命令。 -## 8. 发布与回退 +## 9. 发布与回退 - 使用语义化版本和带注释 Git Tag。 - 发布产物必须对应确定提交,不从浮动分支临时构建。 diff --git a/docs/index.md b/docs/index.md index 0404495..a8d976a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -21,6 +21,11 @@ - [Docker Compose 生产部署](deployment/docker-compose-production.md) - [Ubuntu 源码生产部署](deployment/ubuntu-source-production.md) +## 数据库版本基线 + +- [Schema 基线目录](../database/schema-baselines/) +- [GOV-007 设计规格](features/GOV-007-development-schema-baseline/design.md) + ## GitNexus - [仓库基线](gitnexus/repository-baseline.md) @@ -36,5 +41,6 @@ - [GOV-004:提交后强制推送 Gitea](features/GOV-004-mandatory-gitea-push/manifest.yaml) - [GOV-005:MySQL 5.7 字符集与兼容性基线](features/GOV-005-mysql57-charset-baseline/manifest.yaml) - [GOV-006:开发、生产环境与双部署方式](features/GOV-006-environment-deployment-baseline/manifest.yaml) +- [GOV-007:开发数据库 Schema 基线与版本门禁](features/GOV-007-development-schema-baseline/manifest.yaml) 功能档案是需求、设计、代码、测试、版本和回退之间的唯一正式关联入口。 diff --git a/package.json b/package.json index 0e6c3c4..8861394 100644 --- a/package.json +++ b/package.json @@ -7,6 +7,9 @@ "test:governance": "node --test tools/governance/feature-record.test.mjs", "test:mysql-baseline": "node --test tools/governance/mysql-baseline.test.mjs", "test:environment-baseline": "node --test tools/governance/environment-baseline.test.mjs", + "test:schema-baseline": "node --test tools/database/schema-baseline.test.mjs", + "schema:baseline": "node tools/database/schema-baseline.mjs generate", + "schema:verify": "node tools/database/schema-baseline.mjs verify", "governance:start": "node tools/governance/start.mjs", "governance:finish": "node tools/governance/finish.mjs" } diff --git a/tools/database/fixtures/mysql57-schema-expected.sql b/tools/database/fixtures/mysql57-schema-expected.sql new file mode 100644 index 0000000..86f8a61 --- /dev/null +++ b/tools/database/fixtures/mysql57-schema-expected.sql @@ -0,0 +1,18 @@ +/*!40101 SET @OLD_CHARACTER_SET_CLIENT=@@CHARACTER_SET_CLIENT */; + +CREATE TABLE `market_snapshot` ( + `id` bigint(20) unsigned NOT NULL AUTO_INCREMENT, + `trade_date` date NOT NULL, + PRIMARY KEY (`id`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci; + +/*!50001 DROP VIEW IF EXISTS `active_market_snapshot`*/; +/*!50001 CREATE ALGORITHM=UNDEFINED */ +/*!50013 SQL SECURITY DEFINER */ +/*!50001 VIEW `active_market_snapshot` AS select `market_snapshot`.`id` AS `id` from `market_snapshot` */; + +DELIMITER ;; +/*!50003 CREATE*/ /*!50003 TRIGGER `market_snapshot_before_insert` BEFORE INSERT ON `market_snapshot` FOR EACH ROW SET NEW.trade_date = COALESCE(NEW.trade_date, CURRENT_DATE) */;; +/*!50003 CREATE*/ /*!50003 PROCEDURE `refresh_market_snapshot`() BEGIN SELECT COUNT(*) FROM market_snapshot; END */;; +/*!50106 CREATE*/ /*!50106 EVENT `purge_market_snapshot` ON SCHEDULE EVERY 1 DAY DO DELETE FROM market_snapshot WHERE trade_date < CURRENT_DATE - INTERVAL 365 DAY */;; +DELIMITER ; diff --git a/tools/database/fixtures/mysql57-schema-input.sql b/tools/database/fixtures/mysql57-schema-input.sql new file mode 100644 index 0000000..9d6265d --- /dev/null +++ b/tools/database/fixtures/mysql57-schema-input.sql @@ -0,0 +1,26 @@ +-- MySQL dump 10.13 Distrib 5.7.44, for Linux (x86_64) +-- +-- Host: 127.0.0.1 Database: a_share_analysis_dev +-- ------------------------------------------------------ +-- Server version 5.7.44-log + +/*!40101 SET @OLD_CHARACTER_SET_CLIENT=@@CHARACTER_SET_CLIENT */; + +CREATE TABLE `market_snapshot` ( + `id` bigint(20) unsigned NOT NULL AUTO_INCREMENT, + `trade_date` date NOT NULL, + PRIMARY KEY (`id`) +) ENGINE=InnoDB AUTO_INCREMENT=128 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci; + +/*!50001 DROP VIEW IF EXISTS `active_market_snapshot`*/; +/*!50001 CREATE ALGORITHM=UNDEFINED */ +/*!50013 DEFINER=`dev_reader`@`127.0.0.1` SQL SECURITY DEFINER */ +/*!50001 VIEW `active_market_snapshot` AS select `market_snapshot`.`id` AS `id` from `market_snapshot` */; + +DELIMITER ;; +/*!50003 CREATE*/ /*!50017 DEFINER=`dev_reader`@`127.0.0.1`*/ /*!50003 TRIGGER `market_snapshot_before_insert` BEFORE INSERT ON `market_snapshot` FOR EACH ROW SET NEW.trade_date = COALESCE(NEW.trade_date, CURRENT_DATE) */;; +/*!50003 CREATE*/ /*!50020 DEFINER=`dev_reader`@`127.0.0.1`*/ /*!50003 PROCEDURE `refresh_market_snapshot`() BEGIN SELECT COUNT(*) FROM market_snapshot; END */;; +/*!50106 CREATE*/ /*!50117 DEFINER=`dev_reader`@`127.0.0.1`*/ /*!50106 EVENT `purge_market_snapshot` ON SCHEDULE EVERY 1 DAY DO DELETE FROM market_snapshot WHERE trade_date < CURRENT_DATE - INTERVAL 365 DAY */;; +DELIMITER ; + +-- Dump completed on 2026-08-13 11:00:00 diff --git a/tools/database/schema-baseline.mjs b/tools/database/schema-baseline.mjs new file mode 100644 index 0000000..7aae8ab --- /dev/null +++ b/tools/database/schema-baseline.mjs @@ -0,0 +1,739 @@ +import { execFileSync } from 'node:child_process'; +import { + existsSync, + mkdirSync, + readFileSync, + readdirSync, + renameSync, + rmSync, + writeFileSync, +} from 'node:fs'; +import { createHash } from 'node:crypto'; +import path from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const DEVELOPMENT_DATABASE = 'a_share_analysis_dev'; +const REQUIRED_CHARSET = 'utf8mb4'; +const REQUIRED_COLLATION = 'utf8mb4_general_ci'; +const BASELINE_FORMAT_VERSION = 1; +const TOOL_VERSION = '1.0.0'; +const VERSION_PATTERN = /^v\d+\.\d+\.\d+$/; +const DEVELOPMENT_HOSTS = new Set(['127.0.0.1', 'localhost', '::1']); +const OBJECT_KEYS = Object.freeze(['tables', 'views', 'triggers', 'routines', 'events']); +const CAPTURED_FILES = Object.freeze(['checksum.sha256', 'manifest.yaml', 'schema.sql']); +const NOT_APPLICABLE_FILES = Object.freeze(['manifest.yaml']); + +function requireExactValue(actual, expected, message) { + if (actual !== expected) { + throw new Error(`${message},要求 ${expected},实际 ${actual || '(空)'}`); + } +} + +function isEnabled(value) { + return value === true || value === 'true'; +} + +/** + * Schema 工具拥有比普通应用启动更窄的权限边界:即使连接地址看起来是本机, + * 环境名和数据库名也必须同时命中固定开发值,避免通过参数误切到生产库。 + */ +export function assertSafeDevelopmentConfiguration(config) { + requireExactValue(config.APP_ENV, 'development', 'Schema 基线只允许 development 环境'); + requireExactValue( + config.MYSQL_DATABASE, + DEVELOPMENT_DATABASE, + 'Schema 基线只允许固定开发库 a_share_analysis_dev', + ); + requireExactValue(config.MYSQL_CHARSET, REQUIRED_CHARSET, '数据库字符集不符合要求'); + requireExactValue( + config.MYSQL_COLLATION, + REQUIRED_COLLATION, + '数据库排序规则不符合要求', + ); + if (isEnabled(config.MYSQL_ENABLED)) { + if (!DEVELOPMENT_HOSTS.has(config.MYSQL_HOST)) { + throw new Error( + `Schema 基线只允许通过开发机回环地址连接,实际 ${config.MYSQL_HOST || '(空)'};远程开发库必须先建立本地 SSH 隧道`, + ); + } + for (const key of ['MYSQL_HOST', 'MYSQL_PORT', 'MYSQL_USERNAME', 'MYSQL_PASSWORD']) { + if (!String(config[key] ?? '').trim()) { + throw new Error(`MySQL 已启用,${key} 不能为空`); + } + } + } else if (config.MYSQL_ENABLED !== false && config.MYSQL_ENABLED !== 'false') { + throw new Error('MYSQL_ENABLED 必须显式为 true 或 false'); + } + + return Object.freeze({ ...config, MYSQL_ENABLED: isEnabled(config.MYSQL_ENABLED) }); +} + +/** + * 客户端与服务端分别校验,防止用 MySQL 8 客户端生成带有 5.7 无法稳定恢复的语法, + * 同时核对数据库自身字符规则,而不是信任 env 中的声明值。 + */ +export function assertMysql57Metadata(metadata) { + if (!/^5\.7\.\d+(?:[-+].*)?$/.test(metadata.mysqlClientVersion ?? '')) { + throw new Error(`mysql 客户端必须为 5.7.x,实际 ${metadata.mysqlClientVersion || '(空)'}`); + } + if (!/^5\.7\.\d+(?:[-+].*)?$/.test(metadata.mysqldumpClientVersion ?? '')) { + throw new Error( + `mysqldump 客户端必须为 5.7.x,实际 ${metadata.mysqldumpClientVersion || '(空)'}`, + ); + } + if (!/^5\.7\.\d+(?:[-+].*)?$/.test(metadata.serverVersion ?? '')) { + throw new Error(`MySQL 服务端必须为 5.7.x,实际 ${metadata.serverVersion || '(空)'}`); + } + requireExactValue(metadata.databaseCharset, REQUIRED_CHARSET, '开发数据库字符集不符合要求'); + requireExactValue( + metadata.databaseCollation, + REQUIRED_COLLATION, + '开发数据库排序规则不符合要求', + ); + return metadata; +} + +export function buildMysqldumpArguments(config) { + assertSafeDevelopmentConfiguration(config); + return [ + `--host=${config.MYSQL_HOST}`, + `--port=${config.MYSQL_PORT}`, + `--user=${config.MYSQL_USERNAME}`, + `--default-character-set=${REQUIRED_CHARSET}`, + '--no-data', + '--routines', + '--triggers', + '--events', + '--single-transaction', + '--skip-lock-tables', + '--skip-comments', + DEVELOPMENT_DATABASE, + ]; +} + +function buildMysqlMetadataArguments(config) { + return [ + `--host=${config.MYSQL_HOST}`, + `--port=${config.MYSQL_PORT}`, + `--user=${config.MYSQL_USERNAME}`, + `--default-character-set=${REQUIRED_CHARSET}`, + '--batch', + '--skip-column-names', + DEVELOPMENT_DATABASE, + '--execute=SELECT VERSION(), DEFAULT_CHARACTER_SET_NAME, DEFAULT_COLLATION_NAME FROM information_schema.SCHEMATA WHERE SCHEMA_NAME = DATABASE()', + ]; +} + +function assertSchemaHasNoSensitiveOrDataStatements(sql) { + // 安全扫描只忽略 SQL 字符串字面量,标识符反引号仍参与检查。否则存储过程 + // 合法返回“DEFINER=”等说明文字时会被误判,而真正的对象 DEFINER 仍可检出。 + const sqlWithoutStringLiterals = sql.replace(/'(?:''|\\.|[^'\\])*'/gs, "''"); + const prohibitedPatterns = [ + [sqlWithoutStringLiterals, /\bDEFINER\s*=/i, 'DEFINER'], + [sql, /--\s*Dump completed on/i, '导出完成时间'], + [sql, /--\s*Host:/i, '连接主机注释'], + [sql, /\bpassword\s*=/i, '疑似密码'], + ]; + for (const [content, pattern, label] of prohibitedPatterns) { + if (pattern.test(content)) { + throw new Error(`Schema SQL 包含禁止内容:${label}`); + } + } + + for (const statement of splitSqlStatements(sql)) { + let executableSql = statement + .replace( + /^(?:\s*--[^\n]*(?:\n|$)|\s*#[^\n]*(?:\n|$)|\s*\/\*(?!\!)[\s\S]*?\*\/\s*)+/g, + '', + ) + .trim(); + const candidates = [executableSql]; + const executableComment = executableSql.match(/^\/\*!\d{5}\s+([\s\S]*?)\*\/\s*/); + if (executableComment) { + candidates.push( + executableComment[1].trim(), + executableSql.slice(executableComment[0].length).trim(), + ); + } + const dataStatement = candidates.find((candidate) => + /^(?:INSERT\s+INTO|REPLACE\s+INTO)\b/i.test(candidate), + ); + if (dataStatement) { + throw new Error( + `Schema SQL 包含禁止的数据写入:${dataStatement.match(/^(?:INSERT\s+INTO|REPLACE\s+INTO)/i)[0]}`, + ); + } + } +} + +function findDelimiterOutsideStrings(content, delimiter) { + let quote = null; + let escaped = false; + for (let index = 0; index <= content.length - delimiter.length; index += 1) { + const character = content[index]; + if (quote) { + if (escaped) { + escaped = false; + } else if (character === '\\') { + escaped = true; + } else if (character === quote) { + if (content[index + 1] === quote && quote !== '`') { + index += 1; + } else { + quote = null; + } + } + continue; + } + if (character === "'" || character === '"' || character === '`') { + quote = character; + continue; + } + if (content.startsWith(delimiter, index)) return index; + } + return -1; +} + +/** + * mysqldump 用 DELIMITER 包住例程、触发器和事件。按真实分隔符切分后, + * 只有顶层以 INSERT/REPLACE 开头的语句代表数据;对象体内部 DML 必须保留。 + */ +function splitSqlStatements(sql) { + const statements = []; + let delimiter = ';'; + let buffer = ''; + for (const line of String(sql).split(/(?<=\n)/)) { + const directive = line.trim().match(/^DELIMITER\s+(\S+)$/i); + if (directive) { + if (buffer.trim()) statements.push(buffer.trim()); + buffer = ''; + delimiter = directive[1]; + continue; + } + buffer += line; + let delimiterIndex; + while ((delimiterIndex = findDelimiterOutsideStrings(buffer, delimiter)) >= 0) { + const statement = buffer.slice(0, delimiterIndex).trim(); + if (statement) statements.push(statement); + buffer = buffer.slice(delimiterIndex + delimiter.length); + } + } + if (buffer.trim()) statements.push(buffer.trim()); + return statements; +} + +/** + * 规范化只删除 mysqldump 的环境噪声,不重排或重新格式化业务定义。 + * 表选项中的当前 AUTO_INCREMENT 值会随数据增长变化;列定义的自增属性不匹配 + * “等号加数字”的模式,因此会原样保留。 + */ +export function normalizeSchemaSql(rawSql) { + const normalized = String(rawSql) + .replace(/\r\n?/g, '\n') + .replace(/^-- MySQL dump .*\n/gm, '') + .replace(/^-- Host:.*\n/gm, '') + .replace(/^-- -+\n/gm, '') + .replace(/^--\s*\n/gm, '') + .replace(/^-- Server version.*\n/gm, '') + .replace(/^-- Dump completed on .*\n?/gm, '') + .replace(/\/\*!\d{5}\s+DEFINER=`[^`]+`@`[^`]+`\*\//g, '') + .replace( + /^(\/\*!\d{5}\s+)DEFINER=`[^`]+`@`[^`]+`\s+(SQL SECURITY\s+(?:DEFINER|INVOKER)\s+\*\/)$/gm, + '$1$2', + ) + // 普通视图的 DEFINER 只允许出现在版本注释外、语句行首的 CREATE 前缀中; + // 限定在行首可避免误删例程字符串或注释里的业务文本。 + .replace(/^(\/\*!\d{5}\s+CREATE\s+[^\n]*?)\bDEFINER=`[^`]+`@`[^`]+`\s*/gm, '$1') + .replace(/^(\) ENGINE=[^\n;]*?) AUTO_INCREMENT=\d+(?= )/gm, '$1') + .replace(/^\s+/, '') + .replace(/\s+$/, ''); + + const result = normalized.length > 0 ? `${normalized}\n` : ''; + assertSchemaHasNoSensitiveOrDataStatements(result); + return result; +} + +function sha256(content) { + return createHash('sha256').update(content, 'utf8').digest('hex'); +} + +function buildManifest(fields) { + // JSON 是 YAML 1.2 的严格子集;使用标准解析器生成和读取,避免手写 YAML + // 对缩进、引号和同名嵌套字段产生歧义,同时仍保留约定的 manifest.yaml 文件名。 + return `${JSON.stringify( + { + format_version: BASELINE_FORMAT_VERSION, + status: fields.status, + application_version: fields.applicationVersion, + git_commit: fields.gitCommit, + source_environment: 'development', + database_name: DEVELOPMENT_DATABASE, + mysql_client_version: fields.mysqlClientVersion, + mysqldump_client_version: fields.mysqldumpClientVersion, + mysql_server_version: fields.serverVersion, + charset: REQUIRED_CHARSET, + collation: REQUIRED_COLLATION, + generated_at: fields.generatedAt, + generator: `schema-baseline/${TOOL_VERSION}`, + reason: fields.reason ?? 'none', + schema_sha256: fields.schemaSha256 ?? 'not_applicable', + objects: { + tables: fields.captured, + views: fields.captured, + triggers: fields.captured, + routines: fields.captured, + events: fields.captured, + }, + }, + null, + 2, + )}\n`; +} + +export function buildCapturedArtifacts(metadata, sql) { + assertMysql57Metadata(metadata); + if (!VERSION_PATTERN.test(metadata.applicationVersion ?? '')) { + throw new Error(`应用版本格式无效:${metadata.applicationVersion || '(空)'}`); + } + const normalizedSql = normalizeSchemaSql(sql); + if (!normalizedSql.trim()) { + throw new Error('真实 Schema SQL 不能为空'); + } + const schemaSha256 = sha256(normalizedSql); + const manifest = buildManifest({ + ...metadata, + status: 'captured', + captured: true, + schemaSha256, + }); + return Object.freeze({ + status: 'captured', + schemaSha256, + files: Object.freeze({ + 'manifest.yaml': manifest, + 'schema.sql': normalizedSql, + 'checksum.sha256': `${schemaSha256} schema.sql\n`, + }), + }); +} + +export function buildNotApplicableArtifacts(metadata) { + if (!VERSION_PATTERN.test(metadata.applicationVersion ?? '')) { + throw new Error(`应用版本格式无效:${metadata.applicationVersion || '(空)'}`); + } + const manifest = buildManifest({ + ...metadata, + mysqlClientVersion: 'not_enabled', + mysqldumpClientVersion: 'not_enabled', + serverVersion: 'not_enabled', + status: 'not_applicable', + reason: 'mysql_disabled', + captured: false, + }); + return Object.freeze({ + status: 'not_applicable', + files: Object.freeze({ 'manifest.yaml': manifest }), + }); +} + +function compareExistingArtifacts(targetDirectory, artifacts) { + const actualFiles = readdirSync(targetDirectory).sort(); + const expectedFiles = Object.keys(artifacts.files).sort(); + if ( + actualFiles.length !== expectedFiles.length || + actualFiles.some((file, index) => file !== expectedFiles[index]) + ) { + return false; + } + return expectedFiles.every( + (file) => readFileSync(path.join(targetDirectory, file), 'utf8') === artifacts.files[file], + ); +} + +/** + * 先在目标父目录写入临时目录,再原子改名。这样异常不会留下半份基线; + * 已发布版本目录只允许逐字节相同的幂等重跑,任何差异都必须人工留痕修正。 + */ +export function persistBaselineArtifacts(targetDirectory, artifacts) { + if (existsSync(targetDirectory)) { + if (compareExistingArtifacts(targetDirectory, artifacts)) { + return { reused: true }; + } + throw new Error(`目标版本基线已存在且内容不同,禁止覆盖:${targetDirectory}`); + } + + const parentDirectory = path.dirname(targetDirectory); + mkdirSync(parentDirectory, { recursive: true }); + const temporaryDirectory = path.join( + parentDirectory, + `.${path.basename(targetDirectory)}.tmp-${process.pid}-${Date.now()}`, + ); + mkdirSync(temporaryDirectory); + try { + for (const [file, content] of Object.entries(artifacts.files)) { + writeFileSync(path.join(temporaryDirectory, file), content, 'utf8'); + } + renameSync(temporaryDirectory, targetDirectory); + } catch (error) { + rmSync(temporaryDirectory, { recursive: true, force: true }); + throw error; + } + return { reused: false }; +} + +function parseManifest(content) { + try { + return JSON.parse(content); + } catch { + throw new Error('manifest.yaml 不是有效的结构化 YAML/JSON 清单'); + } +} + +function assertExactFileSet(targetDirectory, expectedFiles) { + const actualFiles = readdirSync(targetDirectory).sort(); + const sortedExpected = [...expectedFiles].sort(); + if ( + actualFiles.length !== sortedExpected.length || + actualFiles.some((file, index) => file !== sortedExpected[index]) + ) { + throw new Error( + `Schema 基线文件集合无效,要求 ${sortedExpected.join(', ')},实际 ${actualFiles.join(', ')}`, + ); + } +} + +export function verifyBaselineDirectory(targetDirectory, expectedRelease, expectedCommit) { + if (!VERSION_PATTERN.test(expectedRelease ?? '')) { + throw new Error(`待验证版本格式无效:${expectedRelease || '(空)'}`); + } + if (!existsSync(targetDirectory)) { + throw new Error(`当前已发布版本缺少 Schema 基线:${targetDirectory}`); + } + + const manifest = parseManifest( + readFileSync(path.join(targetDirectory, 'manifest.yaml'), 'utf8'), + ); + const status = manifest.status; + const applicationVersion = manifest.application_version; + const generatedAt = Date.parse(manifest.generated_at ?? ''); + if ( + manifest.format_version !== BASELINE_FORMAT_VERSION || + manifest.generator !== `schema-baseline/${TOOL_VERSION}` || + !Number.isFinite(generatedAt) || + !/^[0-9a-f]{40}$/.test(manifest.git_commit ?? '') + ) { + throw new Error('Schema 清单格式、生成器、时间或 Git 提交无效'); + } + requireExactValue(applicationVersion, expectedRelease, 'Schema 基线版本与发布版本不一致'); + if (expectedCommit !== undefined) { + requireExactValue( + manifest.git_commit, + expectedCommit, + 'Schema 基线提交与发布标签不一致', + ); + } + requireExactValue( + manifest.source_environment, + 'development', + 'Schema 基线来源环境无效', + ); + requireExactValue( + manifest.database_name, + DEVELOPMENT_DATABASE, + 'Schema 基线数据库名无效', + ); + requireExactValue(manifest.charset, REQUIRED_CHARSET, 'Schema 字符集无效'); + requireExactValue( + manifest.collation, + REQUIRED_COLLATION, + 'Schema 排序规则无效', + ); + + if (status === 'not_applicable') { + assertExactFileSet(targetDirectory, NOT_APPLICABLE_FILES); + const reason = manifest.reason; + requireExactValue(reason, 'mysql_disabled', 'Schema 不适用原因无效'); + if ( + manifest.mysql_client_version !== 'not_enabled' || + manifest.mysqldump_client_version !== 'not_enabled' || + manifest.mysql_server_version !== 'not_enabled' || + manifest.schema_sha256 !== 'not_applicable' || + Object.keys(manifest.objects ?? {}).sort().join(',') !== [...OBJECT_KEYS].sort().join(',') || + OBJECT_KEYS.some((key) => manifest.objects[key] !== false) + ) { + throw new Error('Schema 不适用清单必须证明 MySQL 未启用且所有对象均未捕获'); + } + return { status, applicationVersion, reason }; + } + if (status !== 'captured') { + throw new Error(`Schema 基线状态无效:${status}`); + } + + assertExactFileSet(targetDirectory, CAPTURED_FILES); + assertMysql57Metadata({ + mysqlClientVersion: manifest.mysql_client_version, + mysqldumpClientVersion: manifest.mysqldump_client_version, + serverVersion: manifest.mysql_server_version, + databaseCharset: manifest.charset, + databaseCollation: manifest.collation, + }); + if (Object.keys(manifest.objects ?? {}).sort().join(',') !== [...OBJECT_KEYS].sort().join(',')) { + throw new Error('Schema 对象范围字段无效'); + } + for (const objectName of OBJECT_KEYS) { + requireExactValue(manifest.objects?.[objectName], true, `Schema 对象范围缺少 ${objectName}`); + } + const sql = readFileSync(path.join(targetDirectory, 'schema.sql'), 'utf8'); + if (!sql.trim()) { + throw new Error('真实 Schema SQL 不能为空'); + } + assertSchemaHasNoSensitiveOrDataStatements(sql); + if (/^(\) ENGINE=[^\n;]*?) AUTO_INCREMENT=\d+(?= )/m.test(sql)) { + throw new Error('Schema SQL 仍包含当前 AUTO_INCREMENT 值'); + } + const schemaSha256 = sha256(sql); + const manifestChecksum = manifest.schema_sha256; + const checksumFile = readFileSync(path.join(targetDirectory, 'checksum.sha256'), 'utf8'); + if (manifestChecksum !== schemaSha256 || checksumFile !== `${schemaSha256} schema.sql\n`) { + throw new Error('Schema SQL、manifest 和 checksum 校验值不一致'); + } + return { status, applicationVersion, schemaSha256 }; +} + +export function parseEnvironmentFile(content) { + const config = {}; + for (const rawLine of String(content).replace(/\r\n?/g, '\n').split('\n')) { + const line = rawLine.trim(); + if (!line || line.startsWith('#')) continue; + const separator = line.indexOf('='); + if (separator <= 0) { + throw new Error('开发环境配置包含无效行'); + } + const key = line.slice(0, separator).trim(); + const value = line.slice(separator + 1).trim(); + if (!/^[A-Z][A-Z0-9_]*$/.test(key)) { + throw new Error(`开发环境配置键无效:${key}`); + } + config[key] = value; + } + return config; +} + +function extractClientVersion(output) { + const match = String(output).match(/\b(?:Distrib\s+)?(5\.7\.\d+(?:[-+][^\s,]+)?)/); + return match?.[1] ?? String(output).trim(); +} + +/** + * 真实执行器可注入是为了让测试证明“关闭时零数据库调用”和命令边界;默认执行器 + * 仍使用 execFileSync 参数数组。密码仅放入子进程环境 MYSQL_PWD,不会进入 argv。 + */ +export function runBaselineGeneration(options) { + if ((options.commandArguments ?? []).length > 0) { + throw new Error('Schema 基线命令不接受命令参数,不能覆盖环境、数据库或 env 路径'); + } + const config = assertSafeDevelopmentConfiguration( + parseEnvironmentFile(readFileSync(options.envFile, 'utf8')), + ); + const targetDirectory = path.join( + options.repositoryRoot, + 'database', + 'schema-baselines', + options.applicationVersion, + ); + if (existsSync(targetDirectory)) { + return verifyBaselineDirectory( + targetDirectory, + options.applicationVersion, + options.gitCommit, + ); + } + + const commonMetadata = { + applicationVersion: options.applicationVersion, + gitCommit: options.gitCommit, + generatedAt: options.generatedAt ?? new Date().toISOString(), + }; + if (!config.MYSQL_ENABLED) { + const artifacts = buildNotApplicableArtifacts(commonMetadata); + persistBaselineArtifacts(targetDirectory, artifacts); + return verifyBaselineDirectory(targetDirectory, options.applicationVersion); + } + + const executeFile = options.executeFile ?? execFileSync; + const childEnvironment = { ...process.env, MYSQL_PWD: config.MYSQL_PASSWORD ?? '' }; + const executionOptions = { + cwd: options.repositoryRoot, + encoding: 'utf8', + stdio: ['ignore', 'pipe', 'pipe'], + env: childEnvironment, + }; + const mysqlClientVersion = extractClientVersion( + executeFile('mysql', ['--version'], executionOptions), + ); + const mysqldumpClientVersion = extractClientVersion( + executeFile('mysqldump', ['--version'], executionOptions), + ); + assertMysql57Metadata({ + mysqlClientVersion, + mysqldumpClientVersion, + serverVersion: '5.7.0-pending-server-check', + databaseCharset: REQUIRED_CHARSET, + databaseCollation: REQUIRED_COLLATION, + }); + const serverMetadata = String( + executeFile('mysql', buildMysqlMetadataArguments(config), executionOptions), + ) + .trim() + .split('\t'); + if (serverMetadata.length !== 3) { + throw new Error('无法从固定开发库读取 MySQL 版本、字符集和排序规则'); + } + const metadata = { + ...commonMetadata, + mysqlClientVersion, + mysqldumpClientVersion, + serverVersion: serverMetadata[0], + databaseCharset: serverMetadata[1], + databaseCollation: serverMetadata[2], + }; + assertMysql57Metadata(metadata); + const rawSql = executeFile('mysqldump', buildMysqldumpArguments(config), executionOptions); + const artifacts = buildCapturedArtifacts(metadata, rawSql); + persistBaselineArtifacts(targetDirectory, artifacts); + return verifyBaselineDirectory(targetDirectory, options.applicationVersion); +} + +function runGit(repositoryRoot, args) { + return execFileSync('git', args, { + cwd: repositoryRoot, + encoding: 'utf8', + stdio: ['ignore', 'pipe', 'pipe'], + }).trim(); +} + +export function getCurrentReleasedVersion(repositoryRoot) { + const applicationVersion = runGit(repositoryRoot, [ + 'describe', + '--tags', + '--abbrev=0', + '--match', + 'v[0-9]*', + ]); + if (!VERSION_PATTERN.test(applicationVersion)) { + throw new Error(`最近发布标签格式无效:${applicationVersion}`); + } + return { + applicationVersion, + gitCommit: runGit(repositoryRoot, ['rev-list', '-n', '1', applicationVersion]), + }; +} + +export function assertCurrentReleasedBaseline(repositoryRoot) { + const { applicationVersion, gitCommit } = getCurrentReleasedVersion(repositoryRoot); + return verifyBaselineDirectory( + path.join(repositoryRoot, 'database', 'schema-baselines', applicationVersion), + applicationVersion, + gitCommit, + ); +} + +function runGitLines(repositoryRoot, args) { + const output = runGit(repositoryRoot, args); + return output ? output.split('\n').filter(Boolean) : []; +} + +/** + * 开始下一版本前使用严格门禁:本地校验只证明内容正确,不能证明它已经进入 + * 可协作历史。这里进一步要求基线已跟踪、工作区无相关改动、当前 HEAD 已推送, + * 且 origin 上的发布标签仍指向清单记录的提交。 + */ +export function assertCurrentReleasedBaselinePublished(repositoryRoot) { + const release = getCurrentReleasedVersion(repositoryRoot); + const relativeDirectory = path.posix.join( + 'database', + 'schema-baselines', + release.applicationVersion, + ); + const result = verifyBaselineDirectory( + path.join(repositoryRoot, relativeDirectory), + release.applicationVersion, + release.gitCommit, + ); + const trackedFiles = new Set( + runGitLines(repositoryRoot, ['ls-files', '--', relativeDirectory]), + ); + const expectedFiles = + result.status === 'captured' ? CAPTURED_FILES : NOT_APPLICABLE_FILES; + for (const file of expectedFiles) { + const relativeFile = path.posix.join(relativeDirectory, file); + if (!trackedFiles.has(relativeFile)) { + throw new Error(`Schema 基线尚未提交到 Git:${relativeFile}`); + } + } + const localChanges = runGitLines(repositoryRoot, [ + 'status', + '--porcelain', + '--', + relativeDirectory, + ]); + if (localChanges.length > 0) { + throw new Error(`Schema 基线存在未提交改动:${localChanges.join(', ')}`); + } + + const branch = runGit(repositoryRoot, ['branch', '--show-current']); + if (!branch) { + throw new Error('Schema 发布门禁要求当前位于可推送分支'); + } + const localHead = runGit(repositoryRoot, ['rev-parse', 'HEAD']); + assertRemoteBranchMatches(repositoryRoot, branch, runGit, localHead); + const remoteTag = runGit(repositoryRoot, [ + 'ls-remote', + '--tags', + 'origin', + `refs/tags/${release.applicationVersion}^{}`, + ]); + const remoteTagCommit = remoteTag.split(/\s+/)[0]; + requireExactValue(remoteTagCommit, release.gitCommit, '远程发布标签与基线提交不一致'); + return result; +} + +export function assertRemoteBranchMatches(repositoryRoot, branch, gitRunner = runGit, localHead) { + const expectedHead = localHead ?? gitRunner(repositoryRoot, ['rev-parse', 'HEAD']); + const remoteOutput = gitRunner(repositoryRoot, ['ls-remote', 'origin', `refs/heads/${branch}`]); + const remoteHead = remoteOutput.split(/\s+/)[0]; + requireExactValue(remoteHead, expectedHead, '当前分支尚未完整推送到 origin'); + return true; +} + + +function resolveFixedDevelopmentEnv(repositoryRoot) { + const realDevelopmentEnv = path.join(repositoryRoot, 'deploy', 'env', 'development', 'api.env'); + if (existsSync(realDevelopmentEnv)) return realDevelopmentEnv; + return path.join(repositoryRoot, 'deploy', 'env', 'development', 'api.env.example'); +} + +function runCommandLine() { + const [command, ...commandArguments] = process.argv.slice(2); + if (!['generate', 'verify'].includes(command) || commandArguments.length > 0) { + throw new Error('用法:node tools/database/schema-baseline.mjs (不接受额外参数)'); + } + const repositoryRoot = process.cwd(); + const release = getCurrentReleasedVersion(repositoryRoot); + const result = + command === 'generate' + ? runBaselineGeneration({ + repositoryRoot, + envFile: resolveFixedDevelopmentEnv(repositoryRoot), + ...release, + commandArguments, + }) + : assertCurrentReleasedBaseline(repositoryRoot); + process.stdout.write( + `Schema 基线验证通过:${release.applicationVersion} (${result.status})\n`, + ); +} + +if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) { + runCommandLine(); +} diff --git a/tools/database/schema-baseline.test.mjs b/tools/database/schema-baseline.test.mjs new file mode 100644 index 0000000..7f6d112 --- /dev/null +++ b/tools/database/schema-baseline.test.mjs @@ -0,0 +1,403 @@ +import assert from 'node:assert/strict'; +import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import path from 'node:path'; +import test from 'node:test'; + +import { + assertMysql57Metadata, + assertCurrentReleasedBaselinePublished, + assertSafeDevelopmentConfiguration, + buildCapturedArtifacts, + buildMysqldumpArguments, + buildNotApplicableArtifacts, + normalizeSchemaSql, + persistBaselineArtifacts, + runBaselineGeneration, + assertRemoteBranchMatches, + verifyBaselineDirectory, +} from './schema-baseline.mjs'; + +const validConfig = Object.freeze({ + APP_ENV: 'development', + MYSQL_ENABLED: 'true', + MYSQL_HOST: '127.0.0.1', + MYSQL_PORT: '3306', + MYSQL_DATABASE: 'a_share_analysis_dev', + MYSQL_USERNAME: 'schema_reader', + MYSQL_PASSWORD: 'never-place-this-in-arguments', + MYSQL_CHARSET: 'utf8mb4', + MYSQL_COLLATION: 'utf8mb4_general_ci', +}); + +const validMetadata = Object.freeze({ + applicationVersion: 'v0.0.5', + gitCommit: '0a69aa1f6f5cc75d72f21c43d96f5ff648e2ec93', + mysqlClientVersion: '5.7.44', + mysqldumpClientVersion: '5.7.44', + serverVersion: '5.7.44-log', + databaseCharset: 'utf8mb4', + databaseCollation: 'utf8mb4_general_ci', + generatedAt: '2026-08-13T03:00:00.000Z', +}); + +function makeTemporaryDirectory() { + return mkdtempSync(path.join(tmpdir(), 'a-share-schema-baseline-')); +} + +test('拒绝任何非开发环境和非固定开发库配置', () => { + assert.throws( + () => assertSafeDevelopmentConfiguration({ ...validConfig, APP_ENV: 'production' }), + /只允许 development/, + ); + assert.throws( + () => + assertSafeDevelopmentConfiguration({ + ...validConfig, + MYSQL_DATABASE: 'a_share_analysis', + }), + /a_share_analysis_dev/, + ); + assert.throws( + () => + assertSafeDevelopmentConfiguration({ + ...validConfig, + MYSQL_HOST: 'forbidden-remote.example.invalid', + }), + /开发机回环地址/, + ); +}); + +test('拒绝错误字符集、排序规则和不完整的启用配置', () => { + assert.throws( + () => assertSafeDevelopmentConfiguration({ ...validConfig, MYSQL_CHARSET: 'utf8' }), + /utf8mb4/, + ); + assert.throws( + () => + assertSafeDevelopmentConfiguration({ + ...validConfig, + MYSQL_COLLATION: 'utf8mb4_0900_ai_ci', + }), + /utf8mb4_general_ci/, + ); + assert.throws( + () => assertSafeDevelopmentConfiguration({ ...validConfig, MYSQL_USERNAME: '' }), + /MYSQL_USERNAME/, + ); + assert.throws( + () => assertSafeDevelopmentConfiguration({ ...validConfig, MYSQL_PASSWORD: '' }), + /MYSQL_PASSWORD/, + ); +}); + +test('只接受 MySQL 5.7 客户端、服务端和固定数据库字符规则', () => { + assert.doesNotThrow(() => assertMysql57Metadata(validMetadata)); + assert.throws( + () => assertMysql57Metadata({ ...validMetadata, serverVersion: '8.0.39' }), + /服务端必须为 5\.7/, + ); + assert.throws( + () => assertMysql57Metadata({ ...validMetadata, mysqlClientVersion: '8.0.39' }), + /mysql 客户端必须为 5\.7/, + ); + assert.throws( + () => assertMysql57Metadata({ ...validMetadata, databaseCollation: 'utf8mb4_bin' }), + /utf8mb4_general_ci/, + ); +}); + +test('mysqldump 只导出完整结构且密码不进入命令参数', () => { + const args = buildMysqldumpArguments(validConfig); + + for (const required of ['--no-data', '--routines', '--triggers', '--events']) { + assert.ok(args.includes(required), `缺少强制导出参数:${required}`); + } + assert.equal(args.at(-1), 'a_share_analysis_dev'); + assert.equal(args.join(' ').includes(validConfig.MYSQL_PASSWORD), false); + assert.equal(args.some((argument) => argument.startsWith('--password')), false); +}); + +test('规范化移除环境噪声和账号绑定但保留全部业务对象', () => { + const fixtureDirectory = path.join(import.meta.dirname, 'fixtures'); + const input = readFileSync(path.join(fixtureDirectory, 'mysql57-schema-input.sql'), 'utf8'); + const expected = readFileSync( + path.join(fixtureDirectory, 'mysql57-schema-expected.sql'), + 'utf8', + ); + + const actual = normalizeSchemaSql(input); + assert.equal(actual, expected); + assert.match(actual, /NOT NULL AUTO_INCREMENT/); + assert.doesNotMatch(actual, /AUTO_INCREMENT=128/); + assert.doesNotMatch(actual, /DEFINER=`/); + for (const objectName of [ + 'CREATE TABLE', + 'VIEW `active_market_snapshot`', + 'TRIGGER `market_snapshot_before_insert`', + 'PROCEDURE `refresh_market_snapshot`', + 'EVENT `purge_market_snapshot`', + ]) { + assert.ok(actual.includes(objectName), `规范化误删对象:${objectName}`); + } +}); + +test('规范化不改写例程字符串中的业务文本', () => { + const sql = [ + 'CREATE PROCEDURE `describe_schema`()', + "BEGIN SELECT 'DEFINER=`business`@`text` AUTO_INCREMENT=128' AS description; END;", + '', + ].join('\n'); + + assert.equal(normalizeSchemaSql(sql), sql); +}); + +test('数据扫描拒绝同行顶层写入但保留例程中的合法 DML', () => { + assert.throws( + () => normalizeSchemaSql('CREATE TABLE `sample` (`id` int); INSERT INTO `sample` VALUES (1);\n'), + /INSERT INTO/, + ); + + const routineSql = [ + 'DELIMITER ;;', + 'CREATE PROCEDURE `seed_fixture`()', + 'BEGIN', + 'INSERT INTO `sample` VALUES (1);', + 'END ;;', + 'DELIMITER ;', + '', + ].join('\n'); + assert.equal(normalizeSchemaSql(routineSql), routineSql); + for (const prefixedSql of [ + '/* comment */\nINSERT INTO `sample` VALUES (1);\n', + '/*!40101 SET @x=1 */ INSERT INTO `sample` VALUES (1);\n', + '/*!40101 INSERT INTO `sample` VALUES (1) */;\n', + '/*!40101 REPLACE INTO `sample` VALUES (1) */;\n', + 'CREATE TABLE `sample` (`id` int); -- comment\nREPLACE INTO `sample` VALUES (1);\n', + ]) { + assert.throws(() => normalizeSchemaSql(prefixedSql), /INSERT INTO|REPLACE INTO/); + } +}); + +test('真实基线的清单、校验文件和 SQL 必须三方一致', () => { + const sql = 'CREATE TABLE `sample` (`id` bigint NOT NULL AUTO_INCREMENT);\n'; + const root = makeTemporaryDirectory(); + const target = path.join(root, 'v0.0.5'); + const artifacts = buildCapturedArtifacts(validMetadata, sql); + + persistBaselineArtifacts(target, artifacts); + const result = verifyBaselineDirectory(target, 'v0.0.5'); + + assert.equal(result.status, 'captured'); + assert.equal(result.applicationVersion, 'v0.0.5'); + assert.equal(result.schemaSha256, artifacts.schemaSha256); + assert.equal(readFileSync(path.join(target, 'checksum.sha256'), 'utf8'), `${artifacts.schemaSha256} schema.sql\n`); +}); + +test('拒绝静默覆盖已存在且内容不同的版本基线', () => { + const root = makeTemporaryDirectory(); + const target = path.join(root, 'v0.0.5'); + const artifacts = buildCapturedArtifacts(validMetadata, 'CREATE TABLE `sample` (`id` int);\n'); + persistBaselineArtifacts(target, artifacts); + + assert.doesNotThrow(() => persistBaselineArtifacts(target, artifacts)); + assert.throws( + () => + persistBaselineArtifacts( + target, + buildCapturedArtifacts(validMetadata, 'CREATE TABLE `changed` (`id` int);\n'), + ), + /禁止覆盖/, + ); +}); + +test('MySQL 未启用时只生成可验证不适用清单', () => { + const root = makeTemporaryDirectory(); + const target = path.join(root, 'v0.0.5'); + const artifacts = buildNotApplicableArtifacts(validMetadata); + + persistBaselineArtifacts(target, artifacts); + const result = verifyBaselineDirectory(target, 'v0.0.5'); + + assert.equal(result.status, 'not_applicable'); + assert.equal(result.reason, 'mysql_disabled'); + assert.throws(() => readFileSync(path.join(target, 'schema.sql')), /ENOENT/); + assert.throws(() => readFileSync(path.join(target, 'checksum.sha256')), /ENOENT/); +}); + +test('未启用入口不调用数据库且拒绝额外命令参数', () => { + const root = makeTemporaryDirectory(); + const envFile = path.join(root, 'development.env'); + writeFileSync( + envFile, + 'APP_ENV=development\nMYSQL_ENABLED=false\nMYSQL_DATABASE=a_share_analysis_dev\nMYSQL_CHARSET=utf8mb4\nMYSQL_COLLATION=utf8mb4_general_ci\n', + ); + let executionCount = 0; + + const result = runBaselineGeneration({ + repositoryRoot: root, + envFile, + applicationVersion: 'v0.0.5', + gitCommit: validMetadata.gitCommit, + generatedAt: validMetadata.generatedAt, + executeFile() { + executionCount += 1; + throw new Error('未启用路径不应执行数据库命令'); + }, + }); + + assert.equal(result.status, 'not_applicable'); + assert.equal(executionCount, 0); + assert.throws( + () => runBaselineGeneration({ ...result, commandArguments: ['--env', 'production.env'] }), + /不接受命令参数/, + ); +}); + +test('启用入口分别校验 mysql 与 mysqldump 客户端版本', () => { + const root = makeTemporaryDirectory(); + const envFile = path.join(root, 'development.env'); + writeFileSync( + envFile, + Object.entries(validConfig) + .map(([key, value]) => `${key}=${value}`) + .join('\n'), + ); + + assert.throws( + () => + runBaselineGeneration({ + repositoryRoot: root, + envFile, + applicationVersion: 'v0.0.5', + gitCommit: validMetadata.gitCommit, + generatedAt: validMetadata.generatedAt, + executeFile(command, args) { + if (args[0] === '--version') { + return command === 'mysql' + ? 'mysql Ver 8.0.39 for macos' + : 'mysqldump Ver 10.13 Distrib 5.7.44, for macos'; + } + if (command === 'mysql') { + return '5.7.44-log\tutf8mb4\tutf8mb4_general_ci\n'; + } + return 'CREATE TABLE `sample` (`id` int);\n'; + }, + }), + /mysql 客户端必须为 5\.7/, + ); +}); + +test('幂等重跑仍核对清单提交与发布标签提交', () => { + const root = makeTemporaryDirectory(); + const envFile = path.join(root, 'development.env'); + writeFileSync( + envFile, + 'APP_ENV=development\nMYSQL_ENABLED=false\nMYSQL_DATABASE=a_share_analysis_dev\nMYSQL_CHARSET=utf8mb4\nMYSQL_COLLATION=utf8mb4_general_ci\n', + ); + const target = path.join(root, 'database', 'schema-baselines', 'v0.0.5'); + persistBaselineArtifacts(target, buildNotApplicableArtifacts(validMetadata)); + + assert.throws( + () => + runBaselineGeneration({ + repositoryRoot: root, + envFile, + applicationVersion: 'v0.0.5', + gitCommit: 'ffffffffffffffffffffffffffffffffffffffff', + }), + /提交与发布标签不一致/, + ); +}); + +test('校验能发现 SQL 被修改且生成阶段拒绝空基线', () => { + const root = makeTemporaryDirectory(); + const target = path.join(root, 'v0.0.5'); + persistBaselineArtifacts( + target, + buildCapturedArtifacts(validMetadata, 'CREATE TABLE `sample` (`id` int);\n'), + ); + writeFileSync(path.join(target, 'schema.sql'), 'CREATE TABLE `tampered` (`id` int);\n'); + assert.throws(() => verifyBaselineDirectory(target, 'v0.0.5'), /校验值不一致/); + + assert.throws( + () => buildCapturedArtifacts({ ...validMetadata, applicationVersion: 'v0.0.4' }, ''), + /不能为空/, + ); +}); + +test('基线清单中的提交必须等于发布标签指向的提交', () => { + const root = makeTemporaryDirectory(); + const target = path.join(root, 'v0.0.5'); + persistBaselineArtifacts(target, buildNotApplicableArtifacts(validMetadata)); + + assert.throws( + () => verifyBaselineDirectory(target, 'v0.0.5', 'ffffffffffffffffffffffffffffffffffffffff'), + /提交与发布标签不一致/, + ); +}); + +test('校验拒绝篡改成错误 MySQL 版本或伪造对象范围的真实清单', () => { + const root = makeTemporaryDirectory(); + const target = path.join(root, 'v0.0.5'); + persistBaselineArtifacts( + target, + buildCapturedArtifacts(validMetadata, 'CREATE TABLE `sample` (`id` int);\n'), + ); + const manifestPath = path.join(target, 'manifest.yaml'); + const manifest = JSON.parse(readFileSync(manifestPath, 'utf8')); + manifest.mysql_server_version = '8.0.39'; + writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`); + assert.throws(() => verifyBaselineDirectory(target, 'v0.0.5'), /服务端必须为 5\.7/); + + manifest.mysql_server_version = '5.7.44-log'; + manifest.objects.events = false; + writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`); + assert.throws(() => verifyBaselineDirectory(target, 'v0.0.5'), /events/); +}); + +test('不适用清单必须明确记录 MySQL 未启用且所有对象未捕获', () => { + const root = makeTemporaryDirectory(); + const target = path.join(root, 'v0.0.5'); + persistBaselineArtifacts(target, buildNotApplicableArtifacts(validMetadata)); + const manifestPath = path.join(target, 'manifest.yaml'); + const manifest = JSON.parse(readFileSync(manifestPath, 'utf8')); + manifest.mysql_server_version = '5.7.44'; + manifest.objects.tables = true; + writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`); + + assert.throws(() => verifyBaselineDirectory(target, 'v0.0.5'), /不适用清单/); +}); + +test('不适用清单拒绝未知对象键和伪造的格式元数据', () => { + const root = makeTemporaryDirectory(); + const target = path.join(root, 'v0.0.5'); + persistBaselineArtifacts(target, buildNotApplicableArtifacts(validMetadata)); + const manifestPath = path.join(target, 'manifest.yaml'); + const manifest = JSON.parse(readFileSync(manifestPath, 'utf8')); + manifest.format_version = 999; + manifest.generator = 'unknown'; + manifest.schema_sha256 = 'forged'; + manifest.objects = { a: false, b: false, c: false, d: false, e: false }; + writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`); + + assert.throws(() => verifyBaselineDirectory(target, 'v0.0.5'), /清单格式/); +}); + +test('严格发布门禁通过已提交且远程同步的当前基线', () => { + assert.doesNotThrow(() => assertCurrentReleasedBaselinePublished(process.cwd())); +}); + +test('远程分支校验实时读取 origin 而不是陈旧 tracking ref', () => { + assert.doesNotThrow(() => + assertRemoteBranchMatches('/repo', 'main', (_root, args) => { + assert.deepEqual(args, ['ls-remote', 'origin', 'refs/heads/main']); + return 'abc123\trefs/heads/main'; + }, 'abc123'), + ); + assert.throws( + () => + assertRemoteBranchMatches('/repo', 'main', () => 'def456\trefs/heads/main', 'abc123'), + /尚未完整推送到 origin/, + ); +}); diff --git a/tools/governance/finish.mjs b/tools/governance/finish.mjs index 3ac89d5..161fff2 100644 --- a/tools/governance/finish.mjs +++ b/tools/governance/finish.mjs @@ -34,6 +34,10 @@ function run(command, args) { * 根目录 verify 脚本会继续串联前端和后端测试,而不需要改变本门禁入口。 */ run('npm', ['run', 'test:governance']); +run('npm', ['run', 'test:mysql-baseline']); +run('npm', ['run', 'test:environment-baseline']); +run('npm', ['run', 'test:schema-baseline']); +run('npm', ['run', 'schema:verify']); run('npx', ['gitnexus', 'analyze']); const status = run('npx', ['gitnexus', 'status']); diff --git a/tools/governance/start.mjs b/tools/governance/start.mjs index 52fcd89..9782f56 100644 --- a/tools/governance/start.mjs +++ b/tools/governance/start.mjs @@ -2,6 +2,7 @@ import { execFileSync } from 'node:child_process'; import { existsSync, mkdirSync, writeFileSync } from 'node:fs'; import path from 'node:path'; +import { assertCurrentReleasedBaselinePublished } from '../database/schema-baseline.mjs'; import { getFeatureDirectory, validateFeatureId } from './feature-record.mjs'; const [featureId, slug] = process.argv.slice(2); @@ -15,6 +16,10 @@ const featureDirectory = getFeatureDirectory(repositoryRoot, featureId, slug); const gitnexusDirectory = path.join(featureDirectory, 'gitnexus'); const beforeReport = path.join(gitnexusDirectory, 'before.md'); +// Schema 基线必须在新版本的功能档案和 GitNexus 分析之前已经独立提交; +// 这里仅做只读验证,绝不在一般功能开发命令中连接数据库或静默生成历史产物。 +assertCurrentReleasedBaselinePublished(repositoryRoot); + if (existsSync(beforeReport)) { throw new Error(`开发前报告已存在,为保护历史不会覆盖:${beforeReport}`); }