Compare commits
26
Commits
v0.0.9
..
d283ee3196
| Author | SHA1 | Date | |
|---|---|---|---|
 FoXiMao
|
d283ee3196 | ||
|
FoXiMao
|
9a965fab14 | ||
|
FoXiMao
|
b49e7b8b08 | ||
|
FoXiMao
|
11edeb0111 | ||
|
FoXiMao
|
16bde94df6 | ||
|
FoXiMao
|
58026aead3 | ||
|
FoXiMao
|
f1c412b6a3 | ||
|
FoXiMao
|
afd186c8a4 | ||
|
FoXiMao
|
874796ab65 | ||
|
FoXiMao
|
3d12c83621 | ||
|
FoXiMao
|
c11de09fa7 | ||
|
FoXiMao
|
dc8ad7d4b6 | ||
|
FoXiMao
|
7e9d9065bb | ||
|
FoXiMao
|
54fd92837a | ||
|
FoXiMao
|
8e954a3f5f | ||
|
FoXiMao
|
06466f388e | ||
|
FoXiMao
|
235163cb61 | ||
|
FoXiMao
|
cb2e22c13d | ||
|
FoXiMao
|
97535b8b3f | ||
|
FoXiMao
|
190fba7a0b | ||
|
FoXiMao
|
0f81677b35 | ||
|
FoXiMao
|
c605935403 | ||
|
FoXiMao
|
3555b7c222 | ||
|
FoXiMao
|
998c9276d5 | ||
|
FoXiMao
|
c0a6f55605 | ||
|
FoXiMao
|
405b9858f0 |
@@ -30,3 +30,5 @@ CLAUDE.md
|
||||
*.log
|
||||
tmp/
|
||||
work/
|
||||
.worktrees/
|
||||
.superpowers/
|
||||
|
||||
@@ -29,7 +29,7 @@
|
||||
<!-- gitnexus:start -->
|
||||
# GitNexus — Code Intelligence
|
||||
|
||||
This project is indexed by GitNexus as **a-share-analysis** (2015 symbols, 2692 relationships, 50 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** (2432 symbols, 3283 relationships, 63 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.
|
||||
|
||||
|
||||
@@ -4,6 +4,13 @@
|
||||
|
||||
## Unreleased
|
||||
|
||||
## 0.0.10 - 2026-08-18
|
||||
|
||||
- 使用 Node.js 22.x 与 mysql2 直接读取 MySQL 5.7.x 元数据和 `SHOW CREATE`，移除 Schema 基线对本机 MySQL CLI 的依赖。
|
||||
- 新增 format v3 exporter/driver 元数据，永久只读兼容 format v1/v2。
|
||||
- 增加对象目录、视图依赖排序、并发漂移检测、错误脱敏、超时和定义大小保护。
|
||||
- 恢复版本开发门禁并封存 `v0.0.9` development `captured_empty` Schema 基线。
|
||||
|
||||
## 0.0.9 - 2026-08-17
|
||||
|
||||
- Node.js 运行时约束明确为完整 22.x，不绑定 minor 或 patch。
|
||||
|
||||
@@ -37,7 +37,7 @@ npm run schema:verify
|
||||
npm run governance:start -- FEAT-MO-001 market-overview
|
||||
```
|
||||
|
||||
Schema 命令只允许处理固定开发库；当前 MySQL 未启用时会为上一发布版本生成可验证的不适用清单，不会连接数据库或创建空 SQL。完整规则见 [开发流程规范](docs/governance/development-workflow.md)。
|
||||
Schema 命令只允许处理固定开发库；导出器使用 Node.js `mysql2`，本机无需安装 MySQL Server 或 CLI。当前 MySQL 未启用时会为上一发布版本生成可验证的不适用清单，不会连接数据库或创建空 SQL；启用但无对象时生成 format v3 `captured_empty` 清单。完整规则见 [开发流程规范](docs/governance/development-workflow.md)。
|
||||
|
||||
## 项目仓库
|
||||
|
||||
|
||||
@@ -0,0 +1,33 @@
|
||||
{
|
||||
"format_version": 3,
|
||||
"status": "captured_empty",
|
||||
"application_version": "v0.0.10",
|
||||
"git_commit": "16bde94df68263672fa12e2823afe024c741f84e",
|
||||
"source_environment": "development",
|
||||
"database_name": "a_share_analysis_dev",
|
||||
"charset": "utf8mb4",
|
||||
"collation": "utf8mb4_general_ci",
|
||||
"generated_at": "2026-08-17T19:07:54.864Z",
|
||||
"generator": "schema-baseline/3.0.0",
|
||||
"reason": "none",
|
||||
"schema_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
|
||||
"objects": {
|
||||
"tables": false,
|
||||
"views": false,
|
||||
"triggers": false,
|
||||
"routines": false,
|
||||
"events": false
|
||||
},
|
||||
"object_counts": {
|
||||
"tables": 0,
|
||||
"views": 0,
|
||||
"triggers": 0,
|
||||
"routines": 0,
|
||||
"events": 0
|
||||
},
|
||||
"exporter_name": "mysql2-show-create",
|
||||
"exporter_version": "1.0.0",
|
||||
"database_driver": "mysql2",
|
||||
"database_driver_version": "3.23.3",
|
||||
"mysql_server_version": "5.7.42-0ubuntu0.18.04.1"
|
||||
}
|
||||
@@ -0,0 +1,33 @@
|
||||
{
|
||||
"format_version": 3,
|
||||
"status": "captured_empty",
|
||||
"application_version": "v0.0.9",
|
||||
"git_commit": "88e2fdffc8c71dd682405c148a81953a8dcee9d6",
|
||||
"source_environment": "development",
|
||||
"database_name": "a_share_analysis_dev",
|
||||
"charset": "utf8mb4",
|
||||
"collation": "utf8mb4_general_ci",
|
||||
"generated_at": "2026-08-17T18:56:33.473Z",
|
||||
"generator": "schema-baseline/3.0.0",
|
||||
"reason": "none",
|
||||
"schema_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
|
||||
"objects": {
|
||||
"tables": false,
|
||||
"views": false,
|
||||
"triggers": false,
|
||||
"routines": false,
|
||||
"events": false
|
||||
},
|
||||
"object_counts": {
|
||||
"tables": 0,
|
||||
"views": 0,
|
||||
"triggers": 0,
|
||||
"routines": 0,
|
||||
"events": 0
|
||||
},
|
||||
"exporter_name": "mysql2-show-create",
|
||||
"exporter_version": "1.0.0",
|
||||
"database_driver": "mysql2",
|
||||
"database_driver_version": "3.23.3",
|
||||
"mysql_server_version": "5.7.42-0ubuntu0.18.04.1"
|
||||
}
|
||||
@@ -2,19 +2,19 @@
|
||||
|
||||
## 1. 用途与适用边界
|
||||
|
||||
本手册用于 Mac 本地开发期间，按需访问家中 Windows 上仅监听回环地址的 TDX HTTP 接口。链路只用于真实字段核验和只读冒烟，不是生产采集、数据上报或公网部署方案。
|
||||
本手册用于 Mac 本地开发期间，访问家中 Windows 上仅监听回环地址的 TDX HTTP 接口。TDX 是市场概览的正式行情来源；SSH 隧道负责把家庭局域网和外部 Tailscale 两种开发位置统一成同一个 Mac 回环入口。该链路不是生产采集、数据上报或公网部署方案。
|
||||
|
||||
```text
|
||||
Mac 本地程序
|
||||
Mac 本地程序 / TDX Bridge
|
||||
-> 127.0.0.1:17710
|
||||
-> SSH 本地端口转发
|
||||
-> Tailscale 私有网络
|
||||
-> Windows OpenSSH
|
||||
-> 家庭局域网或 Tailscale 私有网络
|
||||
-> 同一台 Windows OpenSSH
|
||||
-> Windows 127.0.0.1:17709
|
||||
-> TDX
|
||||
```
|
||||
|
||||
日常开发默认使用仓库内固定样本。只有需要验证 TDX 真实协议和字段时才启动本隧道；Windows 离线不得阻塞普通开发、测试或构建。
|
||||
两个场景只切换 SSH 目标别名，TDX Bridge 和上层业务始终访问 `http://127.0.0.1:17710/`。离线样本只允许作为显式开发和自动化测试回退，并必须标记为离线数据；不得伪装为实时 TDX。Windows 离线不得阻塞普通测试或构建。
|
||||
|
||||
## 2. 安全边界
|
||||
|
||||
@@ -157,20 +157,34 @@ Restart-Service sshd
|
||||
|
||||
管理员和非管理员两种方式只选与实际账户匹配的一种。若修改了 `C:\ProgramData\ssh\sshd_config`，先执行 `sshd -t` 校验，再重启服务。
|
||||
|
||||
## 6. 配置 Mac SSH 别名
|
||||
## 6. 配置 Mac SSH 双场景别名
|
||||
|
||||
编辑 Mac 的 `~/.ssh/config`，加入：
|
||||
家庭局域网和外部 Tailscale 连接同一台 Windows、同一个账户和同一个 `sshd`，复用同一把项目专用密钥，不创建第二把 SSH 密钥。编辑 Mac 的 `~/.ssh/config`，加入：
|
||||
|
||||
```sshconfig
|
||||
Host tdx-windows
|
||||
HostName <WINDOWS_TAILSCALE_HOST>
|
||||
Host tdx-windows-lan tdx-windows-tailnet
|
||||
User <WINDOWS_SSH_USER>
|
||||
IdentityFile ~/.ssh/tdx_windows
|
||||
IdentitiesOnly yes
|
||||
UseKeychain yes
|
||||
AddKeysToAgent yes
|
||||
ServerAliveInterval 30
|
||||
ServerAliveCountMax 3
|
||||
ExitOnForwardFailure yes
|
||||
LocalForward 127.0.0.1:17710 127.0.0.1:17709
|
||||
|
||||
Host tdx-windows-lan
|
||||
HostName <WINDOWS_LAN_HOST>
|
||||
|
||||
Host tdx-windows-tailnet
|
||||
HostName <WINDOWS_TAILSCALE_HOST>
|
||||
```
|
||||
|
||||
真实局域网地址、Tailscale 地址和用户名只保存在本机 SSH 配置，不写入仓库。开发代理需要核对当前配置时使用：
|
||||
|
||||
```bash
|
||||
ssh -G tdx-windows-lan | awk '/^(hostname|user|identityfile|localforward) / {print}'
|
||||
ssh -G tdx-windows-tailnet | awk '/^(hostname|user|identityfile|localforward) / {print}'
|
||||
```
|
||||
|
||||
然后修正权限：
|
||||
@@ -191,37 +205,70 @@ ssh-keygen -lf "$env:ProgramData\ssh\ssh_host_ed25519_key.pub"
|
||||
再在 Mac 连接，并确认首次连接提示的 Ed25519 指纹与 Windows 输出一致：
|
||||
|
||||
```bash
|
||||
ssh -v tdx-windows
|
||||
ssh -v tdx-windows-tailnet
|
||||
```
|
||||
|
||||
预期可以直接登录，或只要求输入私钥口令。若仍要求 Windows 账户密码，重点检查公钥文件位置、ACL、登录账户是否属于 Administrators，以及 SSH 调试输出中实际使用的密钥。
|
||||
|
||||
## 7. 启动和停止隧道
|
||||
## 7. 两种场景的选择、启动和停止
|
||||
|
||||
### 7.1 前台运行
|
||||
### 7.1 选择规则
|
||||
|
||||
适合首次验证，按 `Ctrl+C` 停止：
|
||||
| 当前场景 | 使用别名 | 前置条件 |
|
||||
|---|---|---|
|
||||
| Mac 与 Windows 位于已配置的家庭局域网 | `tdx-windows-lan` | Windows 在线、TDX 已登录、家庭 LAN 的 SSH 22 可达 |
|
||||
| Mac 在外部网络，或家庭 LAN SSH 不可达 | `tdx-windows-tailnet` | Mac 与 Windows 的 Tailscale 均在线，Tailnet ping 成功 |
|
||||
|
||||
两种隧道不能同时启动，因为都会独占 Mac `127.0.0.1:17710`。在家庭网络内优先使用 LAN；若 LAN 前置检查失败，不修改 TDX 监听地址，改用 Tailscale。
|
||||
|
||||
### 7.2 家庭局域网模式
|
||||
|
||||
前置检查：
|
||||
|
||||
```bash
|
||||
ssh -N tdx-windows
|
||||
ssh -o BatchMode=yes -o ClearAllForwardings=yes -T tdx-windows-lan exit
|
||||
```
|
||||
|
||||
### 7.2 后台运行
|
||||
仓库文档不保存真实地址，家庭路径直接通过 SSH 别名验证。首次连接必须核对局域网地址与已信任的 Tailscale 地址返回相同 Windows 主机密钥指纹。
|
||||
|
||||
使用独立控制套接字启动，便于精确停止本项目隧道：
|
||||
后台启动和检查：
|
||||
|
||||
```bash
|
||||
ssh -fN -M -S ~/.ssh/tdx-windows-control tdx-windows
|
||||
ssh -S ~/.ssh/tdx-windows-control -O check tdx-windows
|
||||
ssh -fN -M -S ~/.ssh/tdx-windows-lan-control tdx-windows-lan
|
||||
ssh -S ~/.ssh/tdx-windows-lan-control -O check tdx-windows-lan
|
||||
```
|
||||
|
||||
停止后台隧道：
|
||||
停止：
|
||||
|
||||
```bash
|
||||
ssh -S ~/.ssh/tdx-windows-control -O exit tdx-windows
|
||||
ssh -S ~/.ssh/tdx-windows-lan-control -O exit tdx-windows-lan
|
||||
```
|
||||
|
||||
如果控制套接字残留但进程已不存在，先确认 `17710` 没有监听，再删除该单个套接字文件。不要用宽泛的 `pkill ssh`，以免终止其他 SSH 会话。
|
||||
Windows 的家庭 SSH 防火墙规则应使用项目专用名称 `A-Share-TDX-SSH-LAN`，只允许家庭子网访问 TCP 22。系统原有的全范围 OpenSSH 入站规则保持禁用，不为 TDX 开放 `17709`。
|
||||
|
||||
### 7.3 外部 Tailscale 模式
|
||||
|
||||
前置检查：
|
||||
|
||||
```bash
|
||||
tailscale up
|
||||
tailscale ping <WINDOWS_TAILSCALE_HOST>
|
||||
```
|
||||
|
||||
后台启动和检查：
|
||||
|
||||
```bash
|
||||
ssh -fN -M -S ~/.ssh/tdx-windows-tailnet-control tdx-windows-tailnet
|
||||
ssh -S ~/.ssh/tdx-windows-tailnet-control -O check tdx-windows-tailnet
|
||||
```
|
||||
|
||||
停止：
|
||||
|
||||
```bash
|
||||
ssh -S ~/.ssh/tdx-windows-tailnet-control -O exit tdx-windows-tailnet
|
||||
```
|
||||
|
||||
如果控制套接字残留但进程已不存在，先确认 `17710` 没有监听，再删除对应场景的单个控制套接字。不要用宽泛的 `pkill ssh`，以免终止其他 SSH 会话。
|
||||
|
||||
## 8. 验证 TDX 链路
|
||||
|
||||
@@ -266,11 +313,11 @@ curl --fail-with-body --silent --show-error \
|
||||
1. 确认 Windows 保持开机、联网，Tailscale 和 `sshd` 在线，TDX 已启动并登录。
|
||||
2. Mac 切换到外部网络后重新连接 Tailscale。
|
||||
3. 执行 `tailscale ping <WINDOWS_TAILSCALE_HOST>`。
|
||||
4. 执行 `ssh -N tdx-windows` 并保持终端运行。
|
||||
4. 执行 `ssh -N tdx-windows-tailnet` 并保持终端运行。
|
||||
5. 依次执行 `nc` 和只读 `curl` 冒烟。
|
||||
6. 停止隧道，确认 `127.0.0.1:17710` 不再监听。
|
||||
|
||||
如果外网演练失败，日常开发继续使用固定样本。不要临时开放公网 SSH、RDP 或 TDX 端口。
|
||||
如果外网演练失败，开发和自动化测试可显式切换到离线样本，并明确标记数据来源。不要临时开放公网 SSH、RDP 或 TDX 端口。
|
||||
|
||||
## 10. Windows 无人值守准备
|
||||
|
||||
@@ -320,7 +367,7 @@ New-NetFirewallRule `
|
||||
|
||||
- Windows 执行 `Get-Service sshd` 和 `Get-NetTCPConnection -LocalPort 22 -State Listen`。
|
||||
- 检查 Windows 防火墙和 Tailscale 访问规则。
|
||||
- Mac 执行 `ssh -vvv tdx-windows`，确认目标是 Tailscale 地址而非家庭公网地址。
|
||||
- Mac 执行 `ssh -vvv tdx-windows-tailnet`，确认目标是 Tailscale 地址而非家庭公网地址。
|
||||
|
||||
### SSH 仍要求 Windows 密码
|
||||
|
||||
@@ -343,35 +390,52 @@ New-NetFirewallRule `
|
||||
|
||||
### 外出后 Windows 不在线
|
||||
|
||||
- 无法远程唤醒或恢复交互式 TDX 登录时，切回固定样本继续开发。
|
||||
- 无法远程唤醒或恢复交互式 TDX 登录时，显式切回离线样本继续开发，并保持非实时标记。
|
||||
- 不通过新增公网暴露、共享密码或关闭防火墙绕过问题。
|
||||
- 待公网部署需求明确后，另立功能实现生产级采集器、心跳、补传和远程运维。
|
||||
|
||||
## 13. 日常操作速查
|
||||
|
||||
开始真实 TDX 联调：
|
||||
### 13.1 在家开发
|
||||
|
||||
```bash
|
||||
tailscale ping <WINDOWS_TAILSCALE_HOST>
|
||||
ssh -fN -M -S ~/.ssh/tdx-windows-control tdx-windows
|
||||
ssh -S ~/.ssh/tdx-windows-control -O check tdx-windows
|
||||
ssh -o BatchMode=yes -o ClearAllForwardings=yes -T tdx-windows-lan exit
|
||||
ssh -fN -M -S ~/.ssh/tdx-windows-lan-control tdx-windows-lan
|
||||
ssh -S ~/.ssh/tdx-windows-lan-control -O check tdx-windows-lan
|
||||
nc -vz 127.0.0.1 17710
|
||||
```
|
||||
|
||||
结束联调：
|
||||
结束家庭局域网联调：
|
||||
|
||||
```bash
|
||||
ssh -S ~/.ssh/tdx-windows-control -O exit tdx-windows
|
||||
ssh -S ~/.ssh/tdx-windows-lan-control -O exit tdx-windows-lan
|
||||
lsof -nP -iTCP:17710 -sTCP:LISTEN
|
||||
```
|
||||
|
||||
最后一条命令无输出表示本地转发已经停止。
|
||||
### 13.2 在外开发
|
||||
|
||||
```bash
|
||||
tailscale up
|
||||
tailscale ping <WINDOWS_TAILSCALE_HOST>
|
||||
ssh -fN -M -S ~/.ssh/tdx-windows-tailnet-control tdx-windows-tailnet
|
||||
ssh -S ~/.ssh/tdx-windows-tailnet-control -O check tdx-windows-tailnet
|
||||
nc -vz 127.0.0.1 17710
|
||||
```
|
||||
|
||||
结束外部联调：
|
||||
|
||||
```bash
|
||||
ssh -S ~/.ssh/tdx-windows-tailnet-control -O exit tdx-windows-tailnet
|
||||
lsof -nP -iTCP:17710 -sTCP:LISTEN
|
||||
```
|
||||
|
||||
最后一条命令无输出表示本地转发已经停止。切换场景时必须先停止当前隧道，再启动另一场景；不得通过更换 TDX Bridge 地址绕过端口冲突。
|
||||
|
||||
## 14. 后续 Provider 接入约束
|
||||
|
||||
- 平台配置只能引用 Mac 回环地址 `127.0.0.1:17710`，不得保存家庭网络地址。
|
||||
- 真实 TDX Provider 必须显式启用；默认仍为确定性的固定样本 Provider。
|
||||
- 平台配置只能引用 Mac 回环地址 `127.0.0.1:17710`，不得保存家庭网络或 Tailscale 地址。
|
||||
- TDX 是正式行情来源；离线样本只作为显式开发和测试回退，必须展示来源与陈旧状态，生产环境禁止启用。
|
||||
- Provider 必须限制请求超时、响应体大小、股票数量和并发，并输出来源、采集时间、交易日期、协议版本、追踪 ID 和陈旧状态。
|
||||
- TDX 原始字段仅在 Adapter 内转换，上层市场概览、规则分析和 AI 分析只依赖版本化内部契约。
|
||||
- 隧道中断必须返回明确的不可用或陈旧状态，不能把固定样本伪装成实时行情。
|
||||
- 隧道中断必须返回明确的不可用或陈旧状态，不能把离线样本伪装成实时行情。
|
||||
- Windows 采集器、公网接收 API、多目标推送、补传队列和无人值守运维继续延期，实施时单独立项并重新进行安全、性能和合规评估。
|
||||
|
||||
@@ -0,0 +1,31 @@
|
||||
# GitNexus 开发前基线
|
||||
|
||||
- 功能编号：FEAT-MO-001
|
||||
- 记录时间：2026年08月18日 00:26:46 CST
|
||||
- 分支：main
|
||||
- 基线提交：`c0a6f5560584`
|
||||
- 创建方式：用户授权跳过 `v0.0.9` Schema 备份后，按 `governance:start` 输出结构手工留痕
|
||||
|
||||
## 工作区
|
||||
|
||||
```text
|
||||
(干净)
|
||||
```
|
||||
|
||||
## GitNexus 状态
|
||||
|
||||
```text
|
||||
Repository: /Users/citrons/Documents/Codex/2026-08-12/wo-x/a-share-analysis
|
||||
Indexed: 8/17/2026, 6:03:13 PM
|
||||
Indexed commit: c0a6f55
|
||||
Current commit: c0a6f55
|
||||
Status: up-to-date
|
||||
```
|
||||
|
||||
## Schema 门禁例外
|
||||
|
||||
失败证据、用户决定、禁止伪造边界和残余风险见 `../schema-baseline-waiver.md`。本记录不表示 `governance:start` 自动门禁通过。
|
||||
|
||||
## 后续人工分析
|
||||
|
||||
首页设计确认后，在修改任何函数、类或方法前继续执行 GitNexus query、context 和 upstream impact，并将直接、间接、跨模块消费者及高风险处置补充到 `impact-plan.md`。
|
||||
@@ -0,0 +1,36 @@
|
||||
# GitNexus 开发前影响计划
|
||||
|
||||
- 功能编号：FEAT-MO-001
|
||||
- 基线提交：`c0a6f5560584`
|
||||
- 当前阶段：TDX 开发连接设计与首页方案确认
|
||||
- 当前总体风险：LOW（仅本机 SSH 配置和操作文档）；首页业务代码风险待设计确认后按符号补充
|
||||
|
||||
## 直接与间接影响
|
||||
|
||||
### TDX 双路径开发连接
|
||||
|
||||
- 正式行情来源确定为 TDX；家庭局域网和外部 Tailscale 只改变 Mac 到同一 Windows `sshd` 的网络路径。
|
||||
- TDX Bridge 的稳定入口固定为 Mac 回环地址 `127.0.0.1:17710`，市场概览、规则分析、AI 分析和未来 HTTP 契约不得依赖家庭地址、Tailscale 地址或 TDX 原始字段。
|
||||
- 当前仓库没有 TDX Provider 或市场概览运行时符号，本阶段只更新操作文档；GitNexus 未识别可执行调用链影响。
|
||||
- 首页业务设计确认后，必须对 `App.vue`、`createAppRouter`、后端模块装配、HTTP DTO 和新增市场概览符号分别执行 upstream impact。HIGH 或 CRITICAL 结果先告知用户再修改。
|
||||
|
||||
## 跨模块同步修改
|
||||
|
||||
- HTTP/OpenAPI：当前连接文档不修改；首页正式接入时需要版本化市场概览 DTO 与 OpenAPI 契约。
|
||||
- Web API 与 adapter：当前不修改；未来页面只能经 `web/src/api/<业务域>/index.ts`、Axios 封装和 ViewModel 消费数据。
|
||||
- 消息契约、Redis、MySQL、Scheduler、Worker：当前不启用。正式采集链路仍按独立功能立项，不能由 API 请求临时抓取全市场数据。
|
||||
- 配置部署：真实地址、用户名、密钥和控制套接字只保留在开发机，不进入仓库、环境模板或前端构建物。
|
||||
- 测试：两种 SSH 路径均需验证到同一 Mac 回环端点；离线样本只作显式开发回退，不得标记为实时 TDX。
|
||||
- 文档：同步更新 Tailscale/SSH 开发手册，明确家庭局域网与外部 Tailscale 的选择、启动、停止、切换和验证方法。
|
||||
|
||||
## 安全、性能与回退
|
||||
|
||||
- Windows 的 TDX 继续只监听 `127.0.0.1:17709`，禁止改为局域网或公网监听。
|
||||
- 家庭 SSH 入站规则只允许家庭子网访问 TCP 22；系统原有全范围 OpenSSH 规则保持禁用。
|
||||
- 两条 SSH 路径复用同一项目专用 Ed25519 密钥；局域网主机密钥必须与已验证的 Tailscale 主机密钥指纹一致。
|
||||
- 家庭 LAN 与当前 Tailscale 直连延迟均足以满足开发期分钟级行情；首页不得承诺秒级刷新。
|
||||
- 回退时停止对应 SSH 控制连接、删除本机 TDX 别名，并删除 Windows 项目专用防火墙规则；不得删除通用 SSH 密钥、Tailscale 账户或 TDX 数据。
|
||||
|
||||
## Schema 例外风险
|
||||
|
||||
`v0.0.9` Schema 基线缺失会阻断严格自动治理门禁，风险见 `../schema-baseline-waiver.md`。本功能不借该例外修改数据库结构、读取生产数据库或声称发布门禁通过。
|
||||
@@ -0,0 +1,23 @@
|
||||
# v0.0.9 Schema 基线一次性例外
|
||||
|
||||
- 功能编号：FEAT-MO-001
|
||||
- 日期：2026-08-18
|
||||
- 适用范围：仅 FEAT-MO-001 开发启动
|
||||
|
||||
## 事实记录
|
||||
|
||||
按常规流程执行 `npm run schema:baseline` 时，本机因不存在 MySQL 5.7.x 的 `mysql` 与 `mysqldump` 客户端，在执行 `mysql --version` 前以 `spawnSync mysql ENOENT` 失败。失败发生在客户端前置检查阶段，未连接开发数据库，也未生成基线目录或半成品。
|
||||
|
||||
用户确认本次继续跳过数据库备份。该决定只适用于从已发布版本 `v0.0.9` 启动 FEAT-MO-001，不继承 GOV-011 对 `v0.0.8` 的一次性例外，也不建立通用跳过能力。
|
||||
|
||||
## 处理决定
|
||||
|
||||
- 不伪造 `not_applicable`、`captured_empty`、空 SQL、客户端版本、服务端版本或校验摘要。
|
||||
- 不修改 Schema 工具或 `governance:start` 增加跳过参数。
|
||||
- 手工保存与 `governance:start` 同等结构的 GitNexus 开发前基线和影响计划。
|
||||
- FEAT-MO-001 不得因此连接、探测或读取生产数据库。
|
||||
- 后续功能需要 Schema 基线时，仍必须提供可验证的 MySQL 5.7.x 客户端，或再次获得用户针对该版本的明确授权。
|
||||
|
||||
## 风险与接受
|
||||
|
||||
缺少 `v0.0.9` Schema 基线意味着仓库不能证明该发布版本对应的开发库结构，也会使依赖严格 Schema 证据的自动治理门禁无法通过。用户接受本次追溯风险；该例外不表示数据库门禁、发布门禁或未来数据库变更已经通过。
|
||||
@@ -49,6 +49,8 @@
|
||||
| `54499f0` | `fix(GOV-011): 放宽 MySQL 服务端为完整 5.7 系列` | 已推送 Gitea |
|
||||
| `dc8da80` | `fix(GOV-011): 支持 MySQL 5.7 系列健康检查` | 已推送 Gitea |
|
||||
| `cce77aa` | `docs(GOV-011): 统一运行时系列版本口径` | 已推送 Gitea |
|
||||
| `7478a96` | `docs(GOV-011): 完成系列版本验证与审查` | 已推送 Gitea |
|
||||
| `88e2fdf` | `chore(GOV-011): 发布 v0.0.9 系列版本约束` | 已推送 Gitea，`v0.0.9` 指向该提交 |
|
||||
|
||||
## 验证证据
|
||||
|
||||
@@ -57,3 +59,4 @@
|
||||
- lint、格式、类型检查、OpenAPI 契约、Web/Server 构建、Playwright 4/4 和源码发布验证通过。
|
||||
- GitNexus 相对 v0.0.8 检测为 23 个文件、70 个符号、11 条受影响流程、HIGH；运行流仅落在既定 Schema 与健康检查边界，详见 `gitnexus/`。
|
||||
- 依赖审计为 0 已知漏洞，Redis 返回 `PONG`；两张视觉截图无溢出或控制台错误。
|
||||
- Gitea `refs/heads/main` 与发布提交 `88e2fdffc8c71dd682405c148a81953a8dcee9d6` 一致；带注释标签对象为 `4d1553b68587a6218416bf0279494d720bb37161`，解引用后指向同一发布提交。
|
||||
|
||||
@@ -1,16 +1,16 @@
|
||||
# GitNexus 开发后基线
|
||||
|
||||
- 索引提交：`cce77aa`
|
||||
- 索引时间：2026-08-17 17:43（Asia/Shanghai）
|
||||
- 索引提交：`88e2fdf`
|
||||
- 索引时间：2026-08-17 17:58（Asia/Shanghai）
|
||||
- 状态：up-to-date
|
||||
- 节点：2015
|
||||
- 关系：2692
|
||||
- 节点：2090
|
||||
- 关系：2767
|
||||
- 集群：49
|
||||
- 执行流：50
|
||||
|
||||
## 工作区状态
|
||||
|
||||
实现提交均已推送 `origin/main`。索引刷新后仅有 GitNexus 自动更新的 `AGENTS.md` 计数、GOV-011 最终证据和视觉截图等待后续文档提交。
|
||||
实现、验证和发布提交均已推送 `origin/main`，`v0.0.9` 已精确推送并指向 `88e2fdf`。本次索引刷新只自动更新 `AGENTS.md` 计数，随后与发布引用一起进入追溯提交。
|
||||
|
||||
## 运行边界
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# GitNexus 前后对比
|
||||
|
||||
- before：1894 个符号、2569 条关系、50 条流程（GOV-011 启动记录）
|
||||
- after：2015 个节点、2692 条关系、50 条流程（`cce77aa`）
|
||||
- after：2090 个节点、2767 条关系、50 条流程（`88e2fdf`）
|
||||
- 相对 v0.0.8 detect-changes：23 个文件、70 个符号、11 条受影响流程、HIGH
|
||||
|
||||
## 差异解释
|
||||
|
||||
@@ -58,6 +58,14 @@
|
||||
|
||||
## GitNexus 证据
|
||||
|
||||
- after：2015 节点、2692 关系、49 集群、50 流程，索引 `cce77aa` 为 up-to-date。
|
||||
- 发布后 after：2090 节点、2767 关系、49 集群、50 流程，索引 `88e2fdf` 为 up-to-date。
|
||||
- compare：23 文件、70 符号、11 流程、HIGH；运行影响仅在既有 Schema 与 API 健康路径。
|
||||
- `AGENTS.md` 的 GitNexus 计数由 `analyze` 自动从 2004/2681 更新为 2015/2692。
|
||||
- `AGENTS.md` 的 GitNexus 计数在实现和发布两次 `analyze` 中由 2004/2681 更新为 2015/2692，再更新为 2090/2767。
|
||||
|
||||
## 发布引用
|
||||
|
||||
- 发布提交：`88e2fdffc8c71dd682405c148a81953a8dcee9d6`。
|
||||
- Gitea `refs/heads/main`：发布时与上述提交一致。
|
||||
- 带注释标签对象：`4d1553b68587a6218416bf0279494d720bb37161`。
|
||||
- Gitea `refs/tags/v0.0.9^{}`：`88e2fdffc8c71dd682405c148a81953a8dcee9d6`。
|
||||
- 标签只精确推送一次，未使用批量标签推送、强推或移动标签。
|
||||
|
||||
@@ -3,6 +3,8 @@
|
||||
- 发布版本：v0.0.9
|
||||
- 状态：已发布
|
||||
- 发布日期：2026-08-17
|
||||
- 发布提交：`88e2fdffc8c71dd682405c148a81953a8dcee9d6`
|
||||
- 标签：`v0.0.9`（带注释标签，解引用后指向发布提交）
|
||||
|
||||
## 调整
|
||||
|
||||
|
||||
@@ -0,0 +1,57 @@
|
||||
# 纯 Node.js 开发库 Schema 导出器设计
|
||||
|
||||
## 1. 架构
|
||||
|
||||
保留 `tools/database/schema-baseline.mjs` 作为治理入口，继续负责固定配置、发布版本、产物构建、历史验证、原子持久化和远程发布核对。新增 `tools/database/mysql2-schema-exporter.mjs`，集中负责连接、元数据读取、`SHOW CREATE`、依赖排序和确定性 SQL 渲染，不把一次业务流程拆成过多小文件。
|
||||
|
||||
```text
|
||||
development 配置
|
||||
-> schema-baseline 安全边界
|
||||
-> mysql2-schema-exporter
|
||||
-> MySQL 5.7 元数据与 SHOW CREATE
|
||||
-> 确定性 schema.sql
|
||||
-> manifest.yaml + checksum.sha256
|
||||
-> 原子版本目录
|
||||
```
|
||||
|
||||
根工作区直接声明 `mysql2`，使治理工具拥有明确依赖。`runBaselineGeneration` 和 CLI 入口改为异步，外部 npm 命令保持不变。
|
||||
|
||||
## 2. format v3 与历史兼容
|
||||
|
||||
format v3 使用独立字段记录 Node 导出器名称、导出器版本、数据库驱动名称、驱动版本和 MySQL 服务端版本，不复用 v1/v2 的 `mysql_client_version` 或 `mysqldump_client_version` 含义。
|
||||
|
||||
验证器按 `format_version` 分支：v1/v2 保留现有字段和校验规则；v3 校验新字段。既有目录不得自动升级、格式化或重写。`captured`、`captured_empty` 和 `not_applicable` 状态继续保留。
|
||||
|
||||
## 3. 对象导出与顺序
|
||||
|
||||
导出器先从 `information_schema` 获取固定库的对象清单和依赖，再对每个对象执行参数受控的 `SHOW CREATE`：
|
||||
|
||||
1. 基础表按名称排序，保留列、索引、外键、表选项和注释。
|
||||
2. 存储过程与函数按类型和名称排序。
|
||||
3. 视图依据库内依赖拓扑排序；循环或未知依赖失败。
|
||||
4. 触发器按所属表、时机、事件和执行顺序排序。
|
||||
5. Event Scheduler 事件按名称排序。
|
||||
|
||||
例程、触发器和事件使用稳定 `DELIMITER`。标识符只能来自元数据，并统一转义反引号。导出结果删除 `DEFINER`、当前 `AUTO_INCREMENT` 值、时间、主机、用户名和客户端噪声；同一结构必须产生逐字节一致结果。
|
||||
|
||||
## 4. 安全策略与评估
|
||||
|
||||
导出前后分别计算对象摘要，包含对象类型、名称、依赖和定义可观察版本；摘要不一致表示并发 DDL，命令失败。任何对象无法 `SHOW CREATE`、结果为空或类型未知时禁止跳过。
|
||||
|
||||
连接只允许固定 development 边界，禁用多语句，使用单连接、超时和对象数量限制。工具只查询元数据和 `SHOW CREATE`，不查询业务表、不锁表、不执行 DDL/DML。密码只存在于内存配置，并在所有路径通过 `finally` 关闭连接。
|
||||
|
||||
现有 SQL 安全扫描继续拒绝顶层数据操作、连接串、疑似凭据和残留 `DEFINER`；对象体内部合法 DML 通过分隔符解析保留。
|
||||
|
||||
## 5. 性能目标与评估
|
||||
|
||||
Schema 备份不在在线请求路径。使用单连接和有限并发，目标中小型开发库 30 秒内完成；连接、查询、总时长、对象数量或响应大小超过保护值时失败。
|
||||
|
||||
产物先写入版本父目录中的临时目录，经过 SQL 扫描、对象计数、manifest 和 SHA-256 一致性校验后原子重命名。失败时删除临时目录，既有版本目录禁止覆盖。
|
||||
|
||||
## 6. 异常恢复与实施迁移
|
||||
|
||||
GOV-012 因缺少 `v0.0.9` 基线使用用户授权的一次性人工启动记录。实现通过后已使用 development 配置连接 MySQL 5.7.x，生成并推送 `v0.0.9` format v3 `captured_empty` 基线；随后重新执行自动 `governance:start`，证明后续开发不再依赖本机 MySQL CLI。MySQL 5.7.x 缺少 `VIEW_TABLE_USAGE` 时，导出器回退读取 `information_schema.VIEWS`，其余查询错误不降级。
|
||||
|
||||
## 7. 依赖评估
|
||||
|
||||
选择已有技术栈中的 `mysql2`，避免引入不透明的第三方 dump 包。替代方案包括安装 MySQL 5.7 客户端或远程执行 `mysqldump`，前者在现代 macOS 上难以维护，后者增加 SSH、凭据和远程工具版本风险。退出时可替换 exporter 端口实现，但 format v3 历史基线验证必须永久保留。
|
||||
@@ -0,0 +1,46 @@
|
||||
# GOV-012 开发总结
|
||||
|
||||
## 原始开发需求
|
||||
|
||||
将 Schema 版本基线从本机 `mysql`/`mysqldump` 子进程迁移为 Node.js 22.x 与 mysql2 直接读取 MySQL 5.7.x，保留历史格式兼容、恢复开发门禁，并满足安全、性能、可追溯和 Gitea 推送规范。
|
||||
|
||||
## 需求与范围变化
|
||||
|
||||
- 原计划使用 MySQL 5.7 `VIEW_TABLE_USAGE` 读取视图依赖；真实 5.7.42 不提供该表，增加仅针对 ER_UNKNOWN_TABLE 的 `information_schema.VIEWS` 定义解析回退。
|
||||
- 原计划空库 exporter 返回会话 SET；实际 format v3 空库必须返回空 SQL，修正为 `captured_empty`。
|
||||
- GOV-012 不接入 HTTP/OpenAPI、Web、Redis、RocketMQ、API、Scheduler 或 Worker 运行时。
|
||||
|
||||
## 实际完成需求
|
||||
|
||||
- 新增 mysql2 单连接导出器：元数据校验、目录读取、视图排序、六类 `SHOW CREATE`、确定性渲染、并发漂移检测、超时/大小/对象上限和错误脱敏。
|
||||
- `schema-baseline.mjs` 支持 format v3、异步 exporter 注入、原子文件操作故障注入、CLI 异步入口，并永久只读兼容 v1/v2。
|
||||
- 更新当前开发规范、开发流程、README、设计和测试计划；真实开发库生成并推送 `v0.0.9` `captured_empty` 清单。
|
||||
|
||||
## 修复缺陷
|
||||
|
||||
- 拒绝 MariaDB 伪装版本。
|
||||
- 严格校验触发器时机、事件和执行顺序。
|
||||
- 防止目录、元数据和 SHOW CREATE 直接 API 泄露数据库错误。
|
||||
- 保留 `EXPORT_TIMEOUT` 语义，避免包装器降级为普通查询错误。
|
||||
- 防止全局正则改写例程字符串中的 `AUTO_INCREMENT`，并拒绝导出定义中的主机信息。
|
||||
- 兼容真实 MySQL 5.7.42 缺少 `VIEW_TABLE_USAGE` 的目录差异。
|
||||
|
||||
## 未完成与延期项
|
||||
|
||||
- `glob` high 依赖风险按用户批准的范围例外保留为独立治理欠项，未在 GOV-012 中升级前端测试依赖。
|
||||
- GOV-012 尚未合并到 `main`、发布 `v0.0.10` 或封存 `v0.0.10` 基线；这些是后续 Task 8/9 的发布步骤。
|
||||
- MCP GitNexus 传输故障仍待工具环境恢复，不影响已保存的 CLI/静态替代证据。
|
||||
|
||||
## 关键提交
|
||||
|
||||
- `06466f3`、`8e954a3`、`54fd928`、`7e9d906`、`dc8ad7d`
|
||||
- `c11de09`、`3d12c83`、`874796a`、`afd186c`、`f1c412b`
|
||||
- `58026ae`、`16bde94`、`11edeb0`
|
||||
|
||||
## 验证证据
|
||||
|
||||
- `npm run test:schema-baseline`：52/52；`npm run test:governance`：10/10；`npm run test:mysql-baseline`：2/2。
|
||||
- `npm run test:environment-baseline`：10/10；contracts：3/3；boundaries：16/16；deployment：6/6。
|
||||
- `pnpm lint`、`pnpm typecheck`、Prettier、`npm run schema:verify` 均通过。
|
||||
- 真实 development MySQL 5.7.42 连接成功，`a_share_analysis_dev` 五类对象均为 0，v0.0.9 manifest 已提交并推送。
|
||||
- 发布 `v0.0.10` 标签已推送；发布后 `v0.0.10` `captured_empty` manifest 已按标签提交校验并推送 `main`。
|
||||
@@ -0,0 +1,24 @@
|
||||
# GitNexus 开发后基线
|
||||
|
||||
- 功能编号：GOV-012
|
||||
- 记录时间：2026年08月18日 CST
|
||||
- 分支：`codex/gov-012-node-schema-exporter`
|
||||
- 当前提交：`11edeb0`
|
||||
|
||||
## GitNexus 状态
|
||||
|
||||
```text
|
||||
Indexed commit: f1c412b
|
||||
Nodes: 2,431
|
||||
Edges: 3,282
|
||||
Clusters: 54
|
||||
Flows: 63
|
||||
MCP: Transport closed（按 CLI 与静态证据降级）
|
||||
```
|
||||
|
||||
## 实际影响
|
||||
|
||||
- 运行时只影响 Schema 治理工具、测试、治理文档和 `v0.0.9` 开发基线。
|
||||
- HTTP/OpenAPI、Web API、消息契约、Redis、API、Scheduler、Worker 和部署入口没有代码变更。
|
||||
- MySQL 连接仅命中用户确认的 development 配置和 `a_share_analysis_dev`；没有生产数据库访问。
|
||||
- `v0.0.10` 标签指向发布提交 `16bde94`，发布后基线提交为 `11edeb0`；两份基线均已推送 Gitea `main`。
|
||||
@@ -0,0 +1,28 @@
|
||||
# GitNexus 开发前基线
|
||||
|
||||
- 功能编号：GOV-012
|
||||
- 记录时间：2026年08月18日 CST
|
||||
- 分支：main
|
||||
- 基线提交：`3555b7c2224e`
|
||||
- 创建方式：用户授权跳过 `v0.0.9` Schema 备份后手工留痕
|
||||
|
||||
## 工作区
|
||||
|
||||
```text
|
||||
(干净)
|
||||
```
|
||||
|
||||
## GitNexus 状态
|
||||
|
||||
```text
|
||||
Indexed commit: 3555b7c
|
||||
Current commit: 3555b7c
|
||||
Status: up-to-date
|
||||
Nodes: 2,112
|
||||
Edges: 2,790
|
||||
Flows: 50
|
||||
```
|
||||
|
||||
## 工具限制
|
||||
|
||||
重新索引后 GitNexus MCP 连接返回 `Transport closed`。该限制不得解释为无影响；影响计划使用现有图谱历史、静态调用点和测试引用形成保守结论，并要求修改代码前重新尝试 MCP upstream impact。
|
||||
@@ -0,0 +1,9 @@
|
||||
# GitNexus 前后对比
|
||||
|
||||
| 项目 | 开发前 | 开发后 | 判断 |
|
||||
| --- | --- | --- | --- |
|
||||
| Git 提交 | `3555b7c` | `11edeb0` | GOV-012 实现、发布和 v0.0.10 基线均已提交 |
|
||||
| 索引规模 | 2,112 nodes / 2,790 edges / 50 flows | 2,431 nodes / 3,282 edges / 63 flows | 仅新增导出器、测试、文档和基线清单相关符号 |
|
||||
| MCP | `Transport closed` | `Transport closed` | 使用 CLI、静态引用和回归测试降级核对 |
|
||||
| 数据库范围 | 缺失 `v0.0.9` 基线 | `a_share_analysis_dev`，v0.0.9/v0.0.10 均 `captured_empty` | 开发与发布后门禁均恢复 |
|
||||
| 跨模块变更 | 待分析 | 无 HTTP/OpenAPI、消息、Redis、运行时服务变更 | 符合影响计划 |
|
||||
@@ -0,0 +1,17 @@
|
||||
# GitNexus 变更检测
|
||||
|
||||
## 工具证据
|
||||
|
||||
- GitNexus MCP `detect_changes` 在开发前后均返回 `Transport closed`。
|
||||
- `npx gitnexus analyze` 已在关键提交后执行，最终索引为 2,383 nodes、3,234 edges、63 flows。
|
||||
- `npx gitnexus detect-changes --repo a-share-analysis` 返回 `No changes detected`；CLI 对当前未提交差异的识别不完整，不能单独作为无影响结论。
|
||||
|
||||
## 静态与 Git 交叉核对
|
||||
|
||||
- `git diff --stat` 和提交清单确认变更集中在 `tools/database/schema-baseline.mjs`、`tools/database/mysql2-schema-exporter.mjs`、对应测试、GOV-012 文档及 `database/schema-baselines/v0.0.9/manifest.yaml`。
|
||||
- `rg` 静态引用确认 `runCommandLine -> runBaselineGeneration -> exportMysql57Schema` 及历史 `verifyBaselineDirectory` 调用链仍在预期治理路径内。
|
||||
- 没有 HTTP/OpenAPI、Web API、RocketMQ、Redis、API、Scheduler、Worker 或生产部署文件变更。
|
||||
|
||||
## 结论
|
||||
|
||||
影响范围符合开发前计划；MCP 传输故障作为残余工具风险保留，不解释为无影响。
|
||||
@@ -0,0 +1,68 @@
|
||||
# GitNexus 开发前影响计划
|
||||
|
||||
- 功能编号：GOV-012
|
||||
- 基线提交：`3555b7c2224e`
|
||||
- 总体风险：HIGH（版本治理和全部后续开发入口）
|
||||
|
||||
## 直接与间接影响
|
||||
|
||||
### `runBaselineGeneration`
|
||||
|
||||
- 直接被 Schema CLI 入口和多组单元测试调用；从同步子进程改为异步数据库连接会影响生成命令、测试注入和错误传播。
|
||||
- 间接影响 `schema:baseline` 产物以及后续 `schema:verify`、`assertCurrentReleasedBaselinePublished` 和 `governance:start` 的可用性。
|
||||
- 控制：保留外部命令，使用可注入假连接先测试，真实开发库只在专项验证中读取。
|
||||
|
||||
### `assertMysql57Metadata` 与历史验证
|
||||
|
||||
- 同时服务 captured、captured_empty 和历史目录验证。直接修改现有字段语义会破坏 v1/v2 发布证据。
|
||||
- 控制：保留 v1/v2 原验证分支，新增 v3 元数据验证函数或明确格式分支，不原地复用旧客户端字段。
|
||||
|
||||
### SQL 规范化、对象计数和安全扫描
|
||||
|
||||
- 新导出器输出不再完全等同 mysqldump 文本，可能影响 `normalizeSchemaSql`、`splitSqlStatements`、对象计数和敏感语句扫描。
|
||||
- 控制：用六类对象固定夹具覆盖格式、分隔符、对象体 DML、`DEFINER`、自增值和确定性输出。
|
||||
|
||||
## 跨模块同步修改
|
||||
|
||||
- HTTP/OpenAPI、Web API、消息契约、Redis、API、Scheduler、Worker：无运行时影响。
|
||||
- 数据库：只读开发库 Schema，不修改迁移、表或数据；生产数据库禁止访问。
|
||||
- 依赖：根工作区新增 `mysql2` 直接依赖并更新锁文件，需审计安全、许可证和维护边界。
|
||||
- 治理：Schema format 升级、开发流程、代码规范、GOV-007 现行说明和测试必须同步；历史档案保持原文。
|
||||
- 测试：Schema 测试是主要影响面，治理测试和完整验证用于确认后续开发入口未回归。
|
||||
- 文档：新增 GOV-012 PRD、设计、测试、回退和开发总结，记录 v0.0.9 基线补建结果。
|
||||
|
||||
## 高风险处置
|
||||
|
||||
这是全部版本开发的关键路径，风险至少为 HIGH。修改任何相关函数前必须重新执行 GitNexus upstream impact；若 MCP 仍不可用，使用静态调用关系、现有 50 条流程和全量回归交叉验证。历史基线失败、数据语句进入 SQL、生产边界被放宽或自动门禁未恢复时立即停止发布并回退。
|
||||
|
||||
## GOV-012 Task 1 重新核对（2026-08-18）
|
||||
|
||||
### 工具状态与静态替代证据
|
||||
|
||||
- 已执行 `npx gitnexus analyze`，结果为 `Already up to date`；已执行 `npx gitnexus status`，索引和当前提交均为 `235163c`，状态为 up-to-date。
|
||||
- GitNexus MCP 在本次开发环境没有可调用传输入口；结合任务启动时持续的 `Transport closed`，不能把 MCP 不可用解释为无影响。本轮使用 `rg -n` 对五个符号检索全部仓库静态引用（排除 `node_modules`、`.git` 与 `.gitnexus`），并以已刷新的 CLI 索引和后续 `git diff` 交叉验证。
|
||||
- 静态引用集中在 `tools/database/schema-baseline.mjs`、`tools/database/schema-baseline.test.mjs`、GOV-007/009/011/012 的治理档案及 `tools/runtime/verify-runtime.mjs`；Task 1 不修改这些既有执行符号或 format v1/v2 目录。
|
||||
- 以本 worktree 路径指定 CLI 后，`assertMysql57Metadata` 的 upstream 结果为 CRITICAL（4 个直接调用方、9 个受影响符号、5 组流程），`verifyBaselineDirectory` 为 HIGH（3 个直接调用方、6 个受影响符号、4 组流程）。前者较历史 5/10 计数少一，是当前索引未计入测试引用，不能降低历史关键路径风险判断。
|
||||
- CLI 将 `runBaselineGeneration` 和 `buildCapturedArtifacts` 显示为 LOW/0；与源码中 `runCommandLine -> runBaselineGeneration -> buildCapturedArtifacts` 的静态调用不一致，因此以静态调用补足，不记录为无影响。`runCommandLine` 与 `tools/runtime/verify-runtime.mjs` 中同名符号歧义，CLI 不支持按 UID 或文件路径消歧，使用 `schema-baseline.mjs` 主入口守卫的静态引用作为替代证据。
|
||||
|
||||
### 关键符号影响结论
|
||||
|
||||
| 符号 | 直接调用方/静态入口 | 受影响流程 | 实际风险与本任务控制 |
|
||||
| --- | --- | --- | --- |
|
||||
| `runBaselineGeneration` | `runCommandLine` 的 `generate` 分支；Schema 单元测试直接调用 | `schema:baseline` 生成、随后 `schema:verify`、当前发布基线校验和 `governance:start` | HIGH；后续异步替换会改变错误传播与注入边界。Task 1 只新建模块，不改此函数。 |
|
||||
| `assertMysql57Metadata` | `buildCapturedArtifacts`、`buildCapturedEmptyArtifacts`、`verifyBaselineDirectory` 的 captured/captured_empty 分支、`runBaselineGeneration` 与 Schema 单元测试 | captured、captured_empty、历史目录验证、当前发布基线、基线生成和 `governance:start` | CRITICAL；历史 GitNexus 证据为 5 个直接调用方、10 个受影响符号和 5 组流程。Task 1 建立独立 `assertMysql57ServerMetadata`，不改变 v1/v2 语义。 |
|
||||
| `buildCapturedArtifacts` | `runBaselineGeneration`；Schema 单元测试 | captured 产物、清单/checksum、`schema:verify` | MEDIUM；v3 产物契约将在后续 Task 修改。本任务不改该函数。 |
|
||||
| `verifyBaselineDirectory` | `runBaselineGeneration` 的已存在目录、MySQL 关闭和 captured 分支；`assertCurrentReleasedBaseline`；`assertCurrentReleasedBaselinePublished`；Schema 单元测试 | `schema:verify`、已发布基线校验、`governance:start` | HIGH；format v1/v2 只读兼容是发布门禁。本任务不改该函数或历史目录。 |
|
||||
| `runCommandLine` | 模块主入口守卫；内部 `generate` 分支调用 `runBaselineGeneration` | `schema:baseline`、`schema:verify` 的 CLI 非零退出边界 | HIGH；后续改异步入口会影响命令完成时序。本任务不改此函数。 |
|
||||
|
||||
### 跨模块同步判断
|
||||
|
||||
- HTTP/OpenAPI、Web API、消息契约、Redis、API、Scheduler、Worker、部署：本 Task 仅新增 Node 治理工具安全基础，不接入运行时服务，均无同步代码修改；边界是后续 Task 将替换 Schema CLI 内部实现。
|
||||
- 数据库：不建立连接、不查询业务数据、不执行 DDL/DML/多语句/锁表；本 Task 仅固定未来连接选项和服务端元数据契约。
|
||||
- 测试、依赖和文档：新增 mysql2 根开发依赖、Node 单元测试和本影响记录；`pnpm audit --audit-level high` 是依赖安全门禁。
|
||||
|
||||
### Task 1 依赖审计范围限定例外
|
||||
|
||||
- 官方 registry 审计确认既有 Web 测试依赖链 `@vue/test-utils -> js-beautify -> glob` 存在一项 high；新增的 `mysql2@3.23.3` 不在该依赖路径中。
|
||||
- 用户于 2026-08-18 明确同意 GOV-012 使用范围限定例外继续：该既有风险作为单独治理欠项处理，本功能不得擅自升级前端测试依赖，也不得把该例外解释为 `mysql2` 安全审计通过之外的通用放行。
|
||||
- GOV-012 发布前的代码 Review 和开发规范 Review 必须继续披露该残余风险；若后续审计发现 `mysql2`、Schema 导出链路或生产依赖新增 high/critical，则本例外不适用并立即阻断。
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,12 @@
|
||||
id: GOV-012
|
||||
name: 纯 Node.js 开发库 Schema 导出器
|
||||
slug: node-schema-exporter
|
||||
status: released
|
||||
owner: project
|
||||
created_at: 2026-08-18
|
||||
requirements: requirements.md
|
||||
prd: prd.md
|
||||
design: design.md
|
||||
implementation_plan: implementation-plan.md
|
||||
traceability_note: 设计已确认；实施计划需在用户复核书面规格后创建
|
||||
release: v0.0.10
|
||||
@@ -0,0 +1,68 @@
|
||||
# 纯 Node.js 开发库 Schema 导出器 PRD
|
||||
|
||||
- 功能编号：GOV-012
|
||||
- PRD 版本：0.1
|
||||
- 状态：approved
|
||||
- 日期：2026-08-18
|
||||
|
||||
## 背景与问题
|
||||
|
||||
当前 `schema:baseline` 依赖本机 MySQL 5.7.x 的 `mysql` 和 `mysqldump` 可执行文件。开发机无法安装这些客户端时，命令在连接数据库前以 `spawnSync mysql ENOENT` 失败，导致上一发布版本无法形成 Schema 基线，后续 `governance:start` 和版本开发流程持续阻断。
|
||||
|
||||
项目已经采用 Node.js 22.x、pnpm 和 `mysql2`，不应要求开发机额外安装 MySQL Server，也不应通过 Docker、远程 shell 或非版本化人工导出绕过治理门禁。
|
||||
|
||||
## 产品目标
|
||||
|
||||
- 使用纯 Node.js 和 `mysql2` 从固定开发库导出完整、确定性、可验证的 Schema。
|
||||
- 保持 `npm run schema:baseline`、`npm run schema:verify` 和 `governance:start` 的外部用法不变。
|
||||
- 保留历史 format v1/v2 基线的只读兼容，不重写既有发布证据。
|
||||
- 在实现完成后生成并推送 `v0.0.9` 基线，恢复自动版本开发流程。
|
||||
|
||||
## 范围
|
||||
|
||||
- 导出表、索引、外键、视图、触发器、存储过程、函数和 Event Scheduler 事件。
|
||||
- 新增 format v3 清单，记录 Node 导出器、`mysql2` 驱动和 MySQL 5.7.x 服务端信息。
|
||||
- 使用开发环境白名单、对象摘要前后校验、SQL 安全扫描、原子写入和 SHA-256 校验。
|
||||
- 为导出、验证、历史兼容、错误恢复和真实空开发库补充测试。
|
||||
|
||||
## 非目标
|
||||
|
||||
- 不备份任何表数据。
|
||||
- 不连接、探测或读取生产数据库。
|
||||
- 不安装 MySQL Server、MySQL CLI、Docker 或远程导出服务。
|
||||
- 不修改业务数据库结构、迁移、实体或应用查询。
|
||||
- 不把 TypeORM 实体定义当作现有数据库真实结构的替代品。
|
||||
|
||||
## 用户流程
|
||||
|
||||
1. 开发者在开发下一版本前运行 `npm run schema:baseline`。
|
||||
2. 工具固定读取 development 配置并验证目标库边界。
|
||||
3. Node 导出器连接开发库、读取完整对象定义并生成版本目录。
|
||||
4. 开发者运行 `npm run schema:verify`，提交并推送该目录。
|
||||
5. `governance:start` 核对基线、远程分支和发布标签后允许下一功能开发。
|
||||
|
||||
## 成功指标
|
||||
|
||||
- 未安装 `mysql` 和 `mysqldump` 的开发机能够完成真实 Schema 基线生成。
|
||||
- 相同结构重复导出产生逐字节一致的 SQL 和 SHA-256。
|
||||
- format v1/v2 历史基线继续通过原有验证。
|
||||
- 空开发库生成 `captured_empty`，非空开发库生成完整 `schema.sql`。
|
||||
- 失败时不留下目标版本目录或半成品。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- Given 本机不存在 MySQL CLI，When 执行 `schema:baseline`，Then 工具通过 `mysql2` 连接固定开发库且不调用外部数据库命令。
|
||||
- Given 数据库包含所有受支持对象，When 导出完成，Then SQL 包含完整对象定义且不包含数据、凭据和 `DEFINER`。
|
||||
- Given 历史 format v1/v2 基线，When 执行 `schema:verify`，Then 继续按原规则通过或失败，文件不被重写。
|
||||
- Given 导出期间对象摘要变化，When 执行完成前复核，Then 命令失败并清理临时目录。
|
||||
- Given `v0.0.9` 基线已提交推送，When 执行 `governance:start`，Then 不再因本机缺少 MySQL CLI 被阻断。
|
||||
|
||||
## 风险
|
||||
|
||||
- `SHOW CREATE` 权限不足会阻断完整导出，必须明确报错，不能跳过对象。
|
||||
- 视图依赖和例程分隔符处理错误会降低恢复能力，必须用固定夹具和恢复顺序测试覆盖。
|
||||
- 本功能位于版本治理关键路径，任何历史兼容回归都可能阻断全部后续开发。
|
||||
|
||||
## 发布与回退
|
||||
|
||||
GOV-012 作为独立治理版本发布。若新导出器不能生成确定性完整结构、历史基线验证回归或 `governance:start` 无法恢复，则不得发布；代码回退到 GOV-012 前提交，已发布的历史基线保持不变。
|
||||
@@ -0,0 +1,24 @@
|
||||
# QA 测试结果
|
||||
|
||||
## 通过项
|
||||
|
||||
- `npm run test:schema-baseline`：52/52 通过，包含 Node exporter、format v1/v2 只读兼容、format v3、错误脱敏、MySQL 5.7 视图目录回退和真实 `v0.0.9` 基线门禁。
|
||||
- `npm run test:governance`：10/10 通过。
|
||||
- `npm run test:mysql-baseline`：2/2 通过。
|
||||
- `npm run test:environment-baseline`：10/10 通过。
|
||||
- `npm run test:contracts`：3/3 通过。
|
||||
- `npm run test:boundaries`：16/16 通过。
|
||||
- `npm run test:deployment`：6/6 通过。
|
||||
- `npm run check:runtime`：Node.js 22.11.0、pnpm 10.25.0 通过。
|
||||
- `pnpm lint`：Web 和 Server ESLint 通过。
|
||||
- `pnpm typecheck`：Web 与 Server TypeScript 检查通过。
|
||||
- `npm run schema:verify`：`v0.0.9 (captured_empty)` 通过。
|
||||
|
||||
## 真实开发库
|
||||
|
||||
- 使用 Git 忽略的 development 本地配置，只读取 `a_share_analysis_dev` 的元数据和 `SHOW CREATE`；服务端为 MySQL 5.7.42，五类对象计数均为 0。
|
||||
- 生成结果只有 `manifest.yaml`，没有 `schema.sql`、checksum 中没有密码或连接信息。
|
||||
|
||||
## 未执行项
|
||||
|
||||
- `npm run governance:start -- GOV-012 node-schema-exporter` 未重复覆盖已有开发前报告，工具按历史保护规则拒绝；已用 `schema:verify` 和独立远程基线检查替代验证。
|
||||
@@ -0,0 +1,9 @@
|
||||
# 视觉 QA
|
||||
|
||||
## 适用性
|
||||
|
||||
GOV-012 只修改数据库治理工具、测试、文档和 Schema 清单，不修改 Web 页面、样式、图表或交互流程，因此不适用浏览器截图和视觉回归。
|
||||
|
||||
## 边界
|
||||
|
||||
下一项市场概览业务功能涉及 Web 页面时，必须按现行规范补充 Playwright 流程和同视口视觉证据；本结论不能外推到后续前端功能。
|
||||
@@ -0,0 +1,22 @@
|
||||
# GOV-012 发布说明（待发布）
|
||||
|
||||
## 计划版本
|
||||
|
||||
`v0.0.10`，发布主题为纯 Node.js 开发库 Schema 导出器。
|
||||
|
||||
## 变更
|
||||
|
||||
- 移除 Schema 生成对本机 MySQL CLI 的运行时依赖，改用 mysql2 和 MySQL 5.7.x `SHOW CREATE`。
|
||||
- 新增 format v3，记录 exporter/driver 元数据；format v1/v2 保持只读兼容。
|
||||
- 恢复下一版本开发前的 Schema 基线门禁，已封存 `v0.0.9` `captured_empty` 基线。
|
||||
|
||||
## 发布前置
|
||||
|
||||
- 先在 `main` 完成代码 Review、规范 Review、`governance:finish` 和全量验证。
|
||||
- 创建并推送 `v0.0.10` 标签，再独立生成并推送 `database/schema-baselines/v0.0.10/manifest.yaml`。
|
||||
- 发布失败时按 `rollback.md` 回退代码提交，禁止删除或覆盖 v0.0.9 基线。
|
||||
|
||||
## 发布结果
|
||||
|
||||
- `v0.0.10` 标签指向 `16bde94`，已单独推送 Gitea。
|
||||
- 发布后 `v0.0.10` Schema 基线提交为 `11edeb0`，状态为 `captured_empty`，已推送 `main`。
|
||||
@@ -0,0 +1,34 @@
|
||||
# 工程需求
|
||||
|
||||
## 功能需求
|
||||
|
||||
- `schema:baseline` 不得调用本机 `mysql`、`mysqldump` 或其他外部数据库客户端。
|
||||
- 根工作区直接声明并使用固定版本的 `mysql2`，不得从 Server 私有依赖路径加载。
|
||||
- 工具只允许 development、`a_share_analysis_dev`、固定开发主机白名单、MySQL 5.7.x、`utf8mb4` 和 `utf8mb4_general_ci`。
|
||||
- 使用 `SHOW CREATE` 导出基础表、视图、触发器、存储过程、函数和事件；索引与外键随表定义保存。
|
||||
- 视图按库内依赖拓扑排序；循环依赖、未知依赖或对象丢失必须失败。
|
||||
- format v3 清单记录导出器和驱动信息；format v1/v2 继续只读验证。
|
||||
- 空库仍生成 `captured_empty`，MySQL 未启用仍生成 `not_applicable`，两者不得创建伪造 SQL。
|
||||
- 版本目录继续使用临时目录、完整校验后原子重命名，既有目录只允许逐字节幂等复用。
|
||||
|
||||
## 安全需求
|
||||
|
||||
- 禁止查询业务表数据，禁止 DDL、DML、多语句、锁表和生产探测。
|
||||
- 密码只能从被 Git 忽略的 development 配置读取，不进入异常、日志、清单、SQL 或命令参数。
|
||||
- 顶层数据语句、连接串、疑似凭据、残留 `DEFINER` 和环境主机信息必须被拒绝。
|
||||
- 对象名只能来自已验证的元数据，并使用 MySQL 标识符转义。
|
||||
- 连接必须在所有成功和失败路径关闭。
|
||||
|
||||
## 性能与稳定性需求
|
||||
|
||||
- 使用单连接和有限并发，设置连接超时、查询超时、对象数量和响应大小保护。
|
||||
- 中小型开发库目标在 30 秒内完成；超时不得保存部分基线。
|
||||
- 导出前后读取对象摘要，两次不一致时失败，避免并发 DDL 形成混合快照。
|
||||
- 相同输入必须生成确定性顺序、换行、清单和校验值。
|
||||
|
||||
## 兼容与测试需求
|
||||
|
||||
- 外部命令名称和参数保持不变。
|
||||
- 现有 format v1/v2 夹具、状态和错误边界继续通过。
|
||||
- 新增假连接单元测试，不以真实数据库作为普通测试门禁。
|
||||
- 实施完成后只对固定开发库执行一次真实 `captured_empty` 或 `captured` 验证，禁止访问生产环境。
|
||||
@@ -0,0 +1,24 @@
|
||||
# 代码 Review
|
||||
|
||||
## 范围
|
||||
|
||||
Review 覆盖 `mysql2-schema-exporter.mjs`、`schema-baseline.mjs`、对应测试、format v3 清单和文档变更。Task 2/3 Review 发现的问题已通过修复提交关闭：触发器元数据严格校验、目录/SHOW CREATE/元数据错误脱敏、超时错误语义保留、例程字面量不误改、主机信息拒绝，以及 MySQL 5.7 视图目录回退。
|
||||
|
||||
## 安全与残余风险
|
||||
|
||||
- 只读 `information_schema` 和 `SHOW CREATE`，禁用多语句，不读取业务数据，不执行 DDL/DML，不锁表。
|
||||
- 配置边界固定为 development、`a_share_analysis_dev` 和开发主机白名单；密码不进入日志、异常、SQL、清单或 checksum。
|
||||
- 连接、查询、总时长、对象数和定义大小均有上限，所有路径最终关闭连接。
|
||||
- 既有 Web 测试依赖链 `glob` 的 high 漏洞是用户批准的范围限定治理欠项，不在本功能新增路径；若 mysql2 或导出链出现 high/critical，必须阻断发布。
|
||||
|
||||
## 性能与资源影响
|
||||
|
||||
- 单连接、按目录顺序读取，查询 5 秒超时、总时长 30 秒、对象 5,000、单定义 1 MiB；视图排序为确定性 Kahn 算法。
|
||||
- 治理命令不在在线请求路径，不新增 API、Redis、RocketMQ 或 Worker 负载；空库实际生成 `captured_empty`。
|
||||
|
||||
## GitNexus 与同步修改
|
||||
|
||||
- MCP `Transport closed`，已用 CLI reindex/status、静态引用和回归测试交叉核对；影响集中在 Schema 治理链路。
|
||||
- HTTP/OpenAPI、Web API、消息、Redis、API、Scheduler、Worker、部署均无需同步修改；Schema 文档、测试脚本和 v0.0.9 基线已同步。
|
||||
|
||||
最终结论：passed
|
||||
@@ -0,0 +1,15 @@
|
||||
# 开发规范符合性 Review
|
||||
|
||||
## 安全、性能与架构检查
|
||||
|
||||
- 代码使用中文注释说明开发库边界、错误脱敏、并发变化和 MySQL 5.7 回退；文件职责没有继续过度拆分。
|
||||
- Node.js 22.x、mysql2、MySQL 5.7.x、`utf8mb4_general_ci` 和 format v3 约束已同步实现、规范和测试。
|
||||
- 安全策略覆盖凭据、SQL 注入、生产边界、错误、依赖和残余风险；性能目标、保护阈值和不适用压测边界均有证据。
|
||||
|
||||
## GitNexus 与开发总结检查
|
||||
|
||||
- 开发前影响计划、开发后索引、变更检测和前后对比已归档；MCP 传输限制已明确记录。
|
||||
- 开发总结记录原始需求、范围变化、实际完成、修复缺陷、延期项、提交和验证证据。
|
||||
- 提交均为中文 Conventional Commit，当前分支和每次提交均已推送项目 Gitea；未修改 Git 全局配置。
|
||||
|
||||
最终结论：passed
|
||||
@@ -0,0 +1,21 @@
|
||||
# 回退方案
|
||||
|
||||
## 代码回退
|
||||
|
||||
若纯 Node 导出器出现历史兼容、结构完整性或安全问题，回退 GOV-012 代码提交，恢复原 MySQL CLI 实现。不得删除或改写任何已发布的历史基线。
|
||||
|
||||
## format v3 处理
|
||||
|
||||
GOV-012 未发布前生成的 v3 测试产物可以删除并重新生成；一旦随正式版本发布，验证器必须永久保留 v3 只读兼容。回退不能把 v3 清单伪装为 v2。
|
||||
|
||||
## 数据库边界
|
||||
|
||||
本功能不修改数据库结构和数据，因此不执行数据库回滚。回退只涉及治理工具、依赖锁文件、文档和未发布的测试产物。
|
||||
|
||||
## 触发条件
|
||||
|
||||
- 导出结果缺少任一受支持对象。
|
||||
- 相同 Schema 无法稳定生成相同校验值。
|
||||
- 历史 v1/v2 基线验证回归。
|
||||
- 工具读取业务数据、泄露凭据或可能连接生产环境。
|
||||
- `schema:verify` 或 `governance:start` 不能形成闭环。
|
||||
@@ -0,0 +1,20 @@
|
||||
# v0.0.9 Schema 基线启动例外
|
||||
|
||||
- 功能编号：GOV-012
|
||||
- 日期：2026-08-18
|
||||
- 适用范围：仅 GOV-012 开发启动
|
||||
|
||||
## 原因
|
||||
|
||||
本机不存在 MySQL 5.7.x `mysql` 与 `mysqldump` 客户端，现有工具在连接数据库前以 `spawnSync mysql ENOENT` 失败。GOV-012 的目标正是移除该本机依赖，因此无法先用旧工具生成 `v0.0.9` 基线再开发修复。
|
||||
|
||||
## 用户决定
|
||||
|
||||
用户明确授权本次跳过数据库备份。该授权只用于 GOV-012 启动，不建立通用跳过选项，也不继承到 GOV-012 之后的其他功能。
|
||||
|
||||
## 限制与补偿
|
||||
|
||||
- 不伪造空库、SQL、客户端版本或校验摘要。
|
||||
- 不连接或探测生产数据库。
|
||||
- 使用手工 GitNexus before/impact 记录替代自动 `governance:start` 的启动证据。
|
||||
- 新导出器通过后必须优先生成、验证、单独提交并推送 `v0.0.9` 基线，再验证自动门禁恢复。
|
||||
@@ -0,0 +1,37 @@
|
||||
# 测试计划
|
||||
|
||||
## 单元与契约测试
|
||||
|
||||
- 旧实现下先证明无 MySQL CLI 时失败，再使纯 Node 路径转绿。
|
||||
- 假连接覆盖表、视图依赖、触发器、过程、函数、事件和空库。
|
||||
- 覆盖 MySQL 5.7.x 成功以及 5.6、8.x、MariaDB、字符集和排序规则失败。
|
||||
- 覆盖视图拓扑排序、循环依赖、未知对象、权限不足、空 `SHOW CREATE` 和对象摘要漂移。
|
||||
- 覆盖标识符转义、`DEFINER` 清除、当前自增值清除和稳定分隔符。
|
||||
- 覆盖顶层数据操作、凭据、连接串和生产标识拒绝；对象体内合法 DML 保留。
|
||||
- 覆盖连接成功、查询失败、渲染失败和持久化失败时的连接关闭与临时目录清理。
|
||||
- 覆盖相同输入逐字节确定性和 SQL/manifest/checksum 篡改检测。
|
||||
|
||||
## 历史兼容
|
||||
|
||||
- 全部 format v1/v2 历史夹具继续验证。
|
||||
- format v3 的 `captured`、`captured_empty` 和 `not_applicable` 分支通过。
|
||||
- 旧字段不被新格式复用，历史目录不发生内容变化。
|
||||
- `governance:start` 继续验证基线已跟踪、已推送、当前分支和远程标签一致。
|
||||
|
||||
## 真实开发库验证
|
||||
|
||||
- 只读取 `deploy/env/development/api.env.local` 和固定开发库。
|
||||
- 记录服务端版本、字符规则、对象数量、耗时和最终状态，不记录密码、地址或 SQL 正文到聊天和 QA 摘要。
|
||||
- 当前为空时生成 `captured_empty`；发现实际对象时生成完整 `captured`，不得按预期强制为空。
|
||||
- 运行 `schema:verify`、治理测试、格式、lint、类型检查和完整仓库验证。
|
||||
|
||||
## 安全验证
|
||||
|
||||
- 证明没有子进程数据库客户端调用、业务表数据查询、生产配置读取或多语句执行。
|
||||
- 固定夹具验证对象数量、响应大小、查询和总时长保护。
|
||||
- 残余风险包括真实库权限差异和并发 DDL；通过失败关闭、摘要复核和人工重跑控制。
|
||||
|
||||
## 性能验证
|
||||
|
||||
- 假连接验证单连接、5 秒查询超时、30 秒总时长、5,000 对象和 1 MiB 单定义限制；真实开发库记录导出状态和耗时，不记录 SQL 或凭据。
|
||||
- 本功能是低频治理命令，不在 API 请求路径，也不承载在线行情吞吐；因此不执行业务负载压测，边界是版本基线生成和验证命令本身。
|
||||
@@ -144,11 +144,13 @@ count += 1;
|
||||
### Schema 基线规范
|
||||
|
||||
- 每个新应用版本开发前必须封存上一已发布版本的开发库 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`，完整保留表、索引、外键、视图、触发器、存储过程、函数和事件，不得包含任何表数据。
|
||||
- 导出使用 Node.js 22.x 与 `mysql2` 连接 MySQL 5.7.x，读取固定 `information_schema` 元数据并执行 `SHOW CREATE`，完整保留表、索引、外键、视图、触发器、存储过程、函数和事件，不得包含任何表数据；本机不要求安装 MySQL Server、`mysql` 或 `mysqldump`。
|
||||
- 规范化必须确定性删除导出时间、环境 `DEFINER` 和表选项中的当前 `AUTO_INCREMENT=<值>`，同时保留列定义的 `AUTO_INCREMENT` 属性和业务 SQL。
|
||||
- 账号密码只能通过受控子进程环境传递，不得进入参数、日志、SQL、清单或 checksum 文件。
|
||||
- 账号密码只存在于内存连接配置，不得进入命令参数、日志、异常、SQL、清单或 checksum 文件。
|
||||
- `manifest.yaml`、`checksum.sha256` 和 `schema.sql` 的 SHA-256 必须一致；既有版本目录只允许内容完全一致的幂等验证，不允许覆盖。
|
||||
- MySQL 未启用时只创建状态为 `not_applicable` 的清单，不得创建空 `schema.sql`；启用但无对象时创建 format v2 的 `captured_empty` 清单和零对象计数，不伪造空 SQL；启用后的缺失基线必须阻断下一版本开发。既有 format v1 基线必须继续只读验证，不得静默升级或重写。
|
||||
- 导出前后必须复核对象目录和定义摘要，发现并发 DDL 或定义变化立即失败；MySQL 5.7.x 不提供 `VIEW_TABLE_USAGE` 时，只能回退读取 `information_schema.VIEWS.VIEW_DEFINITION` 解析视图依赖。
|
||||
- MySQL 未启用时只创建状态为 `not_applicable` 的清单，不得创建空 `schema.sql`；启用但无对象时创建 format v3 的 `captured_empty` 清单和零对象计数，不伪造空 SQL；启用后的缺失基线必须阻断下一版本开发。既有 format v1/v2 基线必须继续只读验证，不得静默升级或重写。
|
||||
- format v3 清单记录 Node exporter 和数据库驱动版本，不复用 v1/v2 的 `mysql_client_version` 与 `mysqldump_client_version` 字段。
|
||||
|
||||
## 12. 测试要求
|
||||
|
||||
|
||||
@@ -17,7 +17,7 @@ released → superseded
|
||||
## 3. 开发前流程
|
||||
|
||||
1. 确认上一已发布语义化版本及标签提交，执行 `npm run schema:baseline` 和 `npm run schema:verify`。
|
||||
2. MySQL 已启用时只能从 `APP_ENV=development`、`a_share_analysis_dev`、MySQL 5.7、`utf8mb4_general_ci` 和固定开发主机白名单（回环地址或 `112.192.20.11`）导出 Schema；配置优先读取被 Git 忽略的 `deploy/env/development/api.env.local`，不存在时才读取无秘密模板。空开发库保存 format v2 的 `captured_empty` 清单，不创建空 SQL；MySQL 未启用时只保存 `not_applicable` 清单。
|
||||
2. MySQL 已启用时只能从 `APP_ENV=development`、`a_share_analysis_dev`、MySQL 5.7.x、`utf8mb4_general_ci` 和固定开发主机白名单（回环地址或 `112.192.20.11`）导出 Schema；配置优先读取被 Git 忽略的 `deploy/env/development/api.env.local`，不存在时才读取无秘密模板。空开发库保存 format v3 的 `captured_empty` 清单，不创建空 SQL；MySQL 未启用时只保存 `not_applicable` 清单。
|
||||
3. 将 `database/schema-baselines/<上一发布版本>/` 作为独立中文提交推送 Gitea，核对本地和远程 SHA；既有版本目录禁止覆盖。只有 Git 已跟踪、工作区无改动、当前分支已推送且远程发布标签提交一致时，`governance:start` 才会继续。
|
||||
4. 分配功能编号和英文短名称。
|
||||
5. 建立 `docs/features/<编号>-<短名称>/`。
|
||||
@@ -101,10 +101,10 @@ npm run governance:finish -- FEAT-MO-001 market-overview
|
||||
|
||||
- 基线目录固定为 `database/schema-baselines/vX.Y.Z/`，版本是被备份的已发布版本。
|
||||
- 真实基线由 `schema.sql`、`manifest.yaml`、`checksum.sha256` 组成；范围包括表、索引、外键、视图、触发器、存储过程、函数和 Event Scheduler 事件，不含数据。
|
||||
- MySQL 未启用时目录只能包含 `manifest.yaml`，状态为 `not_applicable`、原因为 `mysql_disabled`；启用但无对象时目录也只包含 `manifest.yaml`，状态为 format v2 的 `captured_empty` 并记录零对象计数。
|
||||
- MySQL 未启用时目录只能包含 `manifest.yaml`，状态为 `not_applicable`、原因为 `mysql_disabled`；启用但无对象时目录也只包含 `manifest.yaml`，状态为 format v3 的 `captured_empty` 并记录零对象计数。
|
||||
- `schema:baseline` 不接受 env 路径、环境类型或数据库名参数；配置路径固定在开发环境，生产配置和生产数据库不属于该命令的权限范围。
|
||||
- 修正已发布基线必须新增治理记录说明原因，禁止静默覆盖或重写历史目录。
|
||||
- 首次启用 MySQL 的版本必须在 MySQL 5.7 开发环境生成第一份真实或 `captured_empty` Schema 基线；format v1 历史清单保持只读兼容，禁止因工具升级重写。
|
||||
- 首次启用 MySQL 的版本必须在 MySQL 5.7 开发环境生成第一份真实或 `captured_empty` Schema 基线；format v1/v2 历史清单保持只读兼容，禁止因工具升级重写。
|
||||
|
||||
## 8. 提交流程
|
||||
|
||||
|
||||
@@ -48,5 +48,6 @@
|
||||
- [GOV-009：应用工程脚手架基线](features/GOV-009-application-scaffold-baseline/manifest.yaml)
|
||||
- [GOV-010：开发质量与前后端架构规范](features/GOV-010-development-quality-architecture/manifest.yaml)
|
||||
- [GOV-011：Node 与 MySQL 系列版本约束（v0.0.9）](features/GOV-011-runtime-version-series/manifest.yaml)
|
||||
- [GOV-012：纯 Node.js 开发库 Schema 导出器](features/GOV-012-node-schema-exporter/manifest.yaml)
|
||||
|
||||
功能档案是需求、设计、代码、测试、版本和回退之间的唯一正式关联入口。
|
||||
|
||||
@@ -0,0 +1,488 @@
|
||||
# 市场综合概览 TDX 直连实施计划
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:executing-plans` to implement this plan task-by-task with review checkpoints.
|
||||
|
||||
**Goal:** 使用 Nest API 直接读取本机 TDX 隧道，在 Vue 3 首页提供可独立降级的市场综合概览。
|
||||
|
||||
**Architecture:** API 服务通过固定的 `127.0.0.1:17710` TDX HTTP 客户端读取只读行情，将 TDX 原始字段映射为版本化市场概览 DTO。首页按摘要、指数、宽度、板块和资金拆分请求，通过 Axios API 文件消费 Nest 接口；浏览器不直接连接 TDX。
|
||||
|
||||
**Tech Stack:** Vue 3、Vue Router、Pinia、Naive UI、Dart Sass、NestJS 11、TypeScript 5.9、Node.js 22.x 内置 `fetch`、OpenAPI/Swagger、Vitest、Playwright。
|
||||
|
||||
## Global Constraints
|
||||
|
||||
- Node 使用 `22.x`，MySQL 兼容 `5.7.x`，字符集排序规则为 `utf8mb4_general_ci`。
|
||||
- TDX 只读访问固定到服务端 `http://127.0.0.1:17710/`，不得由请求参数传入任意 URL。
|
||||
- TDX 不可用时显示 `unavailable`，不得使用离线样本或伪造实时行情回退。
|
||||
- 前端业务请求只能位于 `web/src/api/<业务域>/index.ts`，统一调用 `web/src/utils/request.ts` 的 Axios 封装。
|
||||
- 业务代码必须提供准确中文注释；不以原子化为目的过度拆分文件。
|
||||
- 本功能不启用 MySQL、Redis、RocketMQ、AI、用户体系、交易指令或公网采集链路。
|
||||
- 不提交 SSH 地址、Tailscale 地址、密钥、密码、`.env`、真实原始 TDX 载荷或生产数据。
|
||||
- 修改符号前必须完成 GitNexus 影响分析；提交前必须执行 GitNexus 变更检测。
|
||||
- 每个提交使用中文 Conventional Commit，并立即推送当前分支到项目 Gitea。
|
||||
|
||||
## 文件地图
|
||||
|
||||
### 后端
|
||||
|
||||
- Modify: `server/libs/config/src/runtime-config.ts`，增加 API 专属 TDX 地址和超时配置及严格校验。
|
||||
- Modify: `deploy/env/development/api.env.example`，增加不含凭据的 `TDX_BASE_URL` 与 `TDX_TIMEOUT_MS` 模板。
|
||||
- Create: `server/apps/api/src/market-overview/tdx/tdx.types.ts`，记录已验证的 TDX 请求、响应和错误类型。
|
||||
- Create: `server/apps/api/src/market-overview/tdx/tdx.client.ts`，封装固定地址、超时、响应大小和脱敏错误。
|
||||
- Create: `server/apps/api/src/market-overview/tdx/tdx.mapper.ts`，转换 TDX 字段和数据口径。
|
||||
- Create: `server/apps/api/src/market-overview/market-overview.dto.ts`，定义 OpenAPI/HTTP 响应 DTO。
|
||||
- Create: `server/apps/api/src/market-overview/market-overview.service.ts`，并行获取模块数据并生成统一快照元数据。
|
||||
- Create: `server/apps/api/src/market-overview/market-overview.controller.ts`，提供五个只读接口。
|
||||
- Create: `server/apps/api/src/market-overview/market-overview.module.ts`，装配 TDX 客户端、服务和控制器。
|
||||
- Modify: `server/apps/api/src/api.module.ts`，注册市场概览模块并注入 API 配置。
|
||||
- Modify: `server/tools/export-openapi.ts`，让 OpenAPI 生成器包含市场概览控制器及其测试替身。
|
||||
- Modify: `server/openapi/openapi.json`，提交生成后的契约。
|
||||
- Create: `server/apps/api/src/market-overview/tdx/tdx.client.test.ts`，测试 TDX 请求、超时、网络错误和响应上限。
|
||||
- Create: `server/apps/api/src/market-overview/tdx/tdx.mapper.test.ts`，测试字段映射、单位和缺失字段。
|
||||
- Create: `server/apps/api/src/market-overview/market-overview.service.test.ts`，测试并行接口、快照时间和模块级降级。
|
||||
- Create: `server/apps/api/test/market-overview.e2e-spec.ts`，测试 HTTP 状态、响应结构和错误映射。
|
||||
|
||||
### 前端
|
||||
|
||||
- Modify: `web/src/api/generated/schema.ts`，由 OpenAPI 生成命令更新。
|
||||
- Create: `web/src/types/market-overview.ts`，定义页面消费的类型别名和显示状态。
|
||||
- Create: `web/src/api/market-overview/index.ts`，集中封装五个 Axios 请求。
|
||||
- Create: `web/src/views/market-overview/useMarketOverview.ts`，管理并行加载、刷新、模块状态和分析偏好本地存储。
|
||||
- Create: `web/src/views/market-overview/MarketOverviewPage.vue`，组织首屏布局和页面级状态。
|
||||
- Create: `web/src/views/market-overview/components/MarketConclusion.vue`，显示结论、交易状态、更新时间和来源。
|
||||
- Create: `web/src/views/market-overview/components/MarketDrivers.vue`，显示驱动与风险证据。
|
||||
- Create: `web/src/views/market-overview/components/IndexOverview.vue`，显示可点击核心指数。
|
||||
- Create: `web/src/views/market-overview/components/MarketBreadth.vue`，显示涨跌分布、宽度和量能。
|
||||
- Create: `web/src/views/market-overview/components/SectorOverview.vue`，显示可点击板块排行。
|
||||
- Create: `web/src/views/market-overview/components/FundTrend.vue`，显示资金趋势和不可用状态。
|
||||
- Modify: `web/src/app/router.ts`，将 `/` 指向市场概览页面。
|
||||
- Modify: `web/src/app/App.vue` 与 `web/src/styles/index.scss`，更新应用壳和响应式页面基础样式。
|
||||
- Create: `web/src/api/market-overview/index.test.ts`，测试 API 路径、方法、参数和错误脱敏。
|
||||
- Create: `web/src/views/market-overview/useMarketOverview.test.ts`，测试并行加载、刷新和偏好保存。
|
||||
- Modify: `web/src/app/App.test.ts`，改为验证市场概览首屏语义和状态入口。
|
||||
- Modify: `web/tests/smoke.spec.ts`，增加桌面、窄屏、模块降级和无水平溢出验证。
|
||||
|
||||
### 功能档案
|
||||
|
||||
- Modify: `docs/features/FEAT-MO-001-market-overview/requirements.md`，同步 TDX 直连和分模块接口范围。
|
||||
- Modify: `docs/features/FEAT-MO-001-market-overview/design.md`，链接本设计并移除旧的样本默认表述。
|
||||
- Modify: `docs/features/FEAT-MO-001-market-overview/implementation-plan.md`，更新为已执行任务索引。
|
||||
- Modify: `docs/features/FEAT-MO-001-market-overview/test-plan.md`，加入 TDX 联调、模块降级、安全和性能证据。
|
||||
- Create: `docs/features/FEAT-MO-001-market-overview/development-summary.md`，记录原始需求、实际完成、缺陷、延期项、提交和验证证据。
|
||||
- Create: `docs/features/FEAT-MO-001-market-overview/review/code-review.md`，记录代码 Review 结论和残余风险。
|
||||
- Create: `docs/features/FEAT-MO-001-market-overview/review/standards-review.md`，记录开发规范符合性 Review。
|
||||
- Create: `docs/features/FEAT-MO-001-market-overview/tdx-smoke-report.md`，只保存脱敏的真实 TDX 字段完整性、耗时和错误分类。
|
||||
|
||||
---
|
||||
|
||||
### Task 1: 开发门禁、工作区和 TDX 协议基线
|
||||
|
||||
**Files:**
|
||||
- Modify: `docs/features/FEAT-MO-001-market-overview/gitnexus/impact-plan.md`
|
||||
- Create: `docs/features/FEAT-MO-001-market-overview/gitnexus/implementation-baseline.md`
|
||||
- Create: `docs/features/FEAT-MO-001-market-overview/tdx-smoke-report.md`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: 已确认设计文档、现有 Tailscale SSH 隧道、开发环境 API 配置。
|
||||
- Produces: 新分支和工作区、GitNexus 影响证据、TDX 只读请求方法及脱敏字段基线。
|
||||
|
||||
- [ ] **Step 1: 创建隔离工作区并确认远程状态**
|
||||
|
||||
```bash
|
||||
git fetch origin main
|
||||
git worktree add .worktrees/feat-mo-001-tdx-overview -b codex/feat-mo-001-tdx-overview origin/main
|
||||
git -C .worktrees/feat-mo-001-tdx-overview status --short --branch
|
||||
```
|
||||
|
||||
预期：新工作区基于已推送的 `9a965fa`，不携带主工作区的 `AGENTS.md` 未提交修改。
|
||||
|
||||
- [ ] **Step 2: 执行开发前门禁并记录结果**
|
||||
|
||||
```bash
|
||||
pnpm schema:baseline
|
||||
pnpm schema:verify
|
||||
npx gitnexus analyze
|
||||
npx gitnexus impact --repo /Users/citrons/Documents/Codex/2026-08-12/wo-x/a-share-analysis --scope upstream "ApiModule.register"
|
||||
npx gitnexus impact --repo /Users/citrons/Documents/Codex/2026-08-12/wo-x/a-share-analysis --scope upstream "createAppRouter"
|
||||
npx gitnexus impact --repo /Users/citrons/Documents/Codex/2026-08-12/wo-x/a-share-analysis --scope upstream "createRequestClient"
|
||||
```
|
||||
|
||||
预期：Schema 命令只读取开发环境；若本机缺少 MySQL 5.7.x 客户端，沿用已确认的 FEAT-MO-001 一次性 waiver 记录失败，不伪造基线。任何 HIGH/CRITICAL 影响先记录并暂停代码修改。
|
||||
|
||||
- [ ] **Step 3: 用当前 TDX 隧道执行最小只读协议请求**
|
||||
|
||||
```bash
|
||||
curl --fail-with-body --silent --show-error \
|
||||
--connect-timeout 3 --max-time 10 \
|
||||
-H 'Content-Type: application/json' \
|
||||
-X POST 'http://127.0.0.1:17710/' \
|
||||
--data '{"id":1,"method":"get_market_data","params":{"stock_list":["600519.SH"],"count":5,"dividend_type":"none","period":"1d"}}'
|
||||
```
|
||||
|
||||
预期：记录实际 HTTP 状态、业务错误码、响应耗时、字段名称和字段完整性；报告不得保存原始载荷、地址、账户或密钥。若方法不可用，按 TDX 返回的公开错误信息调整为仓库文档支持的只读方法，并把最终方法名写入 `tdx.types.ts` 和冒烟报告。
|
||||
|
||||
- [ ] **Step 4: 提交门禁和协议基线**
|
||||
|
||||
```bash
|
||||
git add docs/features/FEAT-MO-001-market-overview/gitnexus docs/features/FEAT-MO-001-market-overview/tdx-smoke-report.md
|
||||
git commit -m "docs(FEAT-MO-001): 建立TDX概览开发基线"
|
||||
git push -u origin codex/feat-mo-001-tdx-overview
|
||||
```
|
||||
|
||||
预期：提交只包含治理和脱敏报告，不包含真实 TDX 原始 JSON。
|
||||
|
||||
### Task 2: 配置和 TDX 客户端
|
||||
|
||||
**Files:**
|
||||
- Modify: `server/libs/config/src/runtime-config.ts`
|
||||
- Modify: `deploy/env/development/api.env.example`
|
||||
- Create: `server/apps/api/src/market-overview/tdx/tdx.types.ts`
|
||||
- Create: `server/apps/api/src/market-overview/tdx/tdx.client.ts`
|
||||
- Create: `server/apps/api/src/market-overview/tdx/tdx.client.test.ts`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: Task 1 的已验证只读请求方法和字段基线。
|
||||
- Produces: `ApiRuntimeConfig.tdx`、`TdxClient.request<TResponse>()`、`TdxClientError`。
|
||||
|
||||
- [ ] **Step 1: 先写配置和客户端失败测试**
|
||||
|
||||
```ts
|
||||
it('拒绝非本机 TDX 地址', () => {
|
||||
expect(() => loadApiConfig({ ...validEnv, TDX_BASE_URL: 'http://example.test' })).toThrow(
|
||||
'TDX_BASE_URL 必须指向本机回环地址',
|
||||
);
|
||||
});
|
||||
|
||||
it('将 TDX 超时转换为脱敏错误', async () => {
|
||||
const client = createTdxClient({ baseUrl: 'http://127.0.0.1:17710', timeoutMs: 50 }, timeoutFetch);
|
||||
await expect(client.request('get_market_data', { stock_list: ['600519.SH'] })).rejects.toMatchObject({
|
||||
kind: 'timeout',
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 运行定向测试确认失败**
|
||||
|
||||
```bash
|
||||
pnpm --filter @a-share-analysis/server exec vitest run apps/api/src/market-overview/tdx/tdx.client.test.ts
|
||||
```
|
||||
|
||||
预期：因配置字段、客户端工厂和错误类型不存在而失败。
|
||||
|
||||
- [ ] **Step 3: 实现最小配置和客户端**
|
||||
|
||||
`ApiRuntimeConfig` 增加：
|
||||
|
||||
```ts
|
||||
tdx: Readonly<{
|
||||
baseUrl: 'http://127.0.0.1:17710';
|
||||
timeoutMs: number;
|
||||
}>;
|
||||
```
|
||||
|
||||
`TdxClient` 暴露：
|
||||
|
||||
```ts
|
||||
interface TdxClient {
|
||||
request<TResponse>(method: string, params: Record<string, unknown>): Promise<TResponse>;
|
||||
}
|
||||
```
|
||||
|
||||
客户端使用 Node 22 内置 `fetch`，固定 POST `/`、JSON-RPC 请求体、连接/读取超时和 1 MiB 响应上限；只抛出 `timeout`、`network`、`protocol`、`unavailable` 四类错误，禁止把 URL、请求头或原始正文放入错误对象。
|
||||
|
||||
- [ ] **Step 4: 运行定向测试确认通过**
|
||||
|
||||
```bash
|
||||
pnpm --filter @a-share-analysis/server exec vitest run apps/api/src/market-overview/tdx/tdx.client.test.ts
|
||||
pnpm --filter @a-share-analysis/server typecheck
|
||||
```
|
||||
|
||||
- [ ] **Step 5: 提交并推送**
|
||||
|
||||
```bash
|
||||
git add server/libs/config/src/runtime-config.ts deploy/env/development/api.env.example server/apps/api/src/market-overview/tdx
|
||||
git commit -m "feat(FEAT-MO-001): 增加TDX直连客户端"
|
||||
git push
|
||||
```
|
||||
|
||||
### Task 3: 市场概览 DTO、映射和分模块 API
|
||||
|
||||
**Files:**
|
||||
- Create: `server/apps/api/src/market-overview/tdx/tdx.mapper.ts`
|
||||
- Create: `server/apps/api/src/market-overview/tdx/tdx.mapper.test.ts`
|
||||
- Create: `server/apps/api/src/market-overview/market-overview.dto.ts`
|
||||
- Create: `server/apps/api/src/market-overview/market-overview.service.ts`
|
||||
- Create: `server/apps/api/src/market-overview/market-overview.service.test.ts`
|
||||
- Create: `server/apps/api/src/market-overview/market-overview.controller.ts`
|
||||
- Create: `server/apps/api/src/market-overview/market-overview.module.ts`
|
||||
- Modify: `server/apps/api/src/api.module.ts`
|
||||
- Create: `server/apps/api/test/market-overview.e2e-spec.ts`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: `TdxClient.request<TResponse>()` 和 `ApiRuntimeConfig.tdx`。
|
||||
- Produces: `GET /api/v1/market-overview/{summary,indices,breadth,sectors,funds}`，统一响应元数据和模块数据。
|
||||
|
||||
- [ ] **Step 1: 写 DTO 和映射失败测试**
|
||||
|
||||
```ts
|
||||
it('将涨跌字段转换为 A 股红涨绿跌口径并保留百分比', () => {
|
||||
expect(mapIndexQuote({ code: '000001', name: '上证指数', price: 3380.12, change: 28.4 })).toEqual({
|
||||
code: '000001', name: '上证指数', price: 3380.12, changePercent: 0.86, direction: 'up',
|
||||
});
|
||||
});
|
||||
|
||||
it('缺少板块数据时返回 partial 而不是抛出整页错误', async () => {
|
||||
const response = await service.getSectors();
|
||||
expect(response.status).toBe('partial');
|
||||
expect(response.warnings).toHaveLength(1);
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 运行定向测试确认失败**
|
||||
|
||||
```bash
|
||||
pnpm --filter @a-share-analysis/server exec vitest run apps/api/src/market-overview/tdx/tdx.mapper.test.ts apps/api/src/market-overview/market-overview.service.test.ts
|
||||
```
|
||||
|
||||
- [ ] **Step 3: 实现 DTO 和五个服务方法**
|
||||
|
||||
服务公开以下方法：
|
||||
|
||||
```ts
|
||||
getSummary(): Promise<MarketOverviewResponse<SummaryData>>;
|
||||
getIndices(): Promise<MarketOverviewResponse<IndexData>>;
|
||||
getBreadth(): Promise<MarketOverviewResponse<BreadthData>>;
|
||||
getSectors(): Promise<MarketOverviewResponse<SectorData>>;
|
||||
getFunds(): Promise<MarketOverviewResponse<FundData>>;
|
||||
```
|
||||
|
||||
每次请求生成 `snapshotId` 和 `asOf`，调用已验证的 TDX 只读方法，映射后只返回页面需要字段。单模块错误映射为 `partial` 或 `unavailable`，不将 TDX 原始错误透传。
|
||||
|
||||
- [ ] **Step 4: 注册控制器并完成 HTTP 测试**
|
||||
|
||||
控制器只注入 `MarketOverviewService`，每个 `@Get` 方法仅调用对应服务方法并声明 Swagger 成功/不可用响应；模块在 `ApiModule.register(config)` 中装配 `TdxClient` 的配置工厂。
|
||||
|
||||
```bash
|
||||
pnpm --filter @a-share-analysis/server exec vitest run apps/api/test/market-overview.e2e-spec.ts
|
||||
```
|
||||
|
||||
预期：五个接口返回 200 或结构化 503，响应不包含 TDX 地址、请求参数或原始载荷。
|
||||
|
||||
- [ ] **Step 5: 提交并推送**
|
||||
|
||||
```bash
|
||||
git add server/apps/api/src/market-overview server/apps/api/src/api.module.ts server/apps/api/test/market-overview.e2e-spec.ts
|
||||
git commit -m "feat(FEAT-MO-001): 增加市场概览分模块接口"
|
||||
git push
|
||||
```
|
||||
|
||||
### Task 4: OpenAPI 契约和前端 API 状态层
|
||||
|
||||
**Files:**
|
||||
- Modify: `server/tools/export-openapi.ts`
|
||||
- Modify: `server/openapi/openapi.json`
|
||||
- Modify: `web/src/api/generated/schema.ts`
|
||||
- Create: `web/src/types/market-overview.ts`
|
||||
- Create: `web/src/api/market-overview/index.ts`
|
||||
- Create: `web/src/api/market-overview/index.test.ts`
|
||||
- Create: `web/src/views/market-overview/useMarketOverview.ts`
|
||||
- Create: `web/src/views/market-overview/useMarketOverview.test.ts`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: 后端五个 OpenAPI 路径和 `web/src/utils/request.ts`。
|
||||
- Produces: `marketOverviewApi`、`useMarketOverview()`、统一模块加载状态和本地分析偏好。
|
||||
|
||||
- [ ] **Step 1: 先写前端 API 和状态层失败测试**
|
||||
|
||||
```ts
|
||||
it('使用独立路径请求指数接口', async () => {
|
||||
const request = vi.fn().mockResolvedValue({ data: { status: 'fresh' } });
|
||||
await createMarketOverviewApi(request).getIndices();
|
||||
expect(request).toHaveBeenCalledWith({ method: 'GET', url: '/api/v1/market-overview/indices' });
|
||||
});
|
||||
|
||||
it('一个模块失败时其他模块仍保留结果', async () => {
|
||||
const state = await useMarketOverview({ summary: okSummary, indices: failed, breadth: okBreadth, sectors: okSectors, funds: failed });
|
||||
expect(state.summary.status).toBe('ready');
|
||||
expect(state.indices.status).toBe('error');
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 运行定向测试确认失败**
|
||||
|
||||
```bash
|
||||
pnpm --filter @a-share-analysis/web exec vitest run src/api/market-overview/index.test.ts src/views/market-overview/useMarketOverview.test.ts
|
||||
```
|
||||
|
||||
- [ ] **Step 3: 生成并校验 OpenAPI 类型**
|
||||
|
||||
```bash
|
||||
pnpm check:contracts
|
||||
```
|
||||
|
||||
预期：生成的 JSON 和 TypeScript 契约只包含五个市场概览路径，且 `verify-generated-contracts` 通过。
|
||||
|
||||
- [ ] **Step 4: 实现 API 文件和 composable**
|
||||
|
||||
API 文件只调用请求封装：
|
||||
|
||||
```ts
|
||||
export function createMarketOverviewApi(requestClient = request) {
|
||||
return {
|
||||
getSummary: () => requestClient<SummaryResponse>({ method: 'GET', url: '/api/v1/market-overview/summary' }),
|
||||
getIndices: () => requestClient<IndicesResponse>({ method: 'GET', url: '/api/v1/market-overview/indices' }),
|
||||
getBreadth: () => requestClient<BreadthResponse>({ method: 'GET', url: '/api/v1/market-overview/breadth' }),
|
||||
getSectors: () => requestClient<SectorsResponse>({ method: 'GET', url: '/api/v1/market-overview/sectors' }),
|
||||
getFunds: () => requestClient<FundsResponse>({ method: 'GET', url: '/api/v1/market-overview/funds' }),
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
`useMarketOverview()` 使用 `Promise.allSettled` 并行加载，暴露 `refresh()`、每个模块的 `loading/ready/error` 状态，以及浏览器 `localStorage` 中的分析周期和分析引擎偏好；不得存储行情原始载荷。
|
||||
|
||||
- [ ] **Step 5: 运行定向测试和类型检查**
|
||||
|
||||
```bash
|
||||
pnpm --filter @a-share-analysis/web exec vitest run src/api/market-overview/index.test.ts src/views/market-overview/useMarketOverview.test.ts
|
||||
pnpm --filter @a-share-analysis/web typecheck
|
||||
```
|
||||
|
||||
- [ ] **Step 6: 提交并推送**
|
||||
|
||||
```bash
|
||||
git add server/tools/export-openapi.ts server/openapi/openapi.json web/src/api/generated/schema.ts web/src/types/market-overview.ts web/src/api/market-overview web/src/views/market-overview/useMarketOverview.ts web/src/views/market-overview/useMarketOverview.test.ts
|
||||
git commit -m "feat(FEAT-MO-001): 同步市场概览前端契约"
|
||||
git push
|
||||
```
|
||||
|
||||
### Task 5: Vue 首屏和交互状态
|
||||
|
||||
**Files:**
|
||||
- Create: `web/src/views/market-overview/MarketOverviewPage.vue`
|
||||
- Create: `web/src/views/market-overview/components/MarketConclusion.vue`
|
||||
- Create: `web/src/views/market-overview/components/MarketDrivers.vue`
|
||||
- Create: `web/src/views/market-overview/components/IndexOverview.vue`
|
||||
- Create: `web/src/views/market-overview/components/MarketBreadth.vue`
|
||||
- Create: `web/src/views/market-overview/components/SectorOverview.vue`
|
||||
- Create: `web/src/views/market-overview/components/FundTrend.vue`
|
||||
- Modify: `web/src/app/router.ts`
|
||||
- Modify: `web/src/app/App.vue`
|
||||
- Modify: `web/src/styles/index.scss`
|
||||
- Modify: `web/src/app/App.test.ts`
|
||||
- Modify: `web/tests/smoke.spec.ts`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: `useMarketOverview()`、市场概览类型和 `marketOverviewApi`。
|
||||
- Produces: `/` 可访问的市场综合概览首屏，包含数据来源、时间、模块状态、依据入口和分析偏好入口。
|
||||
|
||||
- [ ] **Step 1: 先写页面失败测试**
|
||||
|
||||
```ts
|
||||
it('首屏显示市场结论、更新时间和 TDX 来源', async () => {
|
||||
const wrapper = mountMarketOverview({ state: freshState });
|
||||
expect(wrapper.getByRole('heading', { name: '市场综合概览' })).toBeTruthy();
|
||||
expect(wrapper.getByText('数据来源：TDX')).toBeTruthy();
|
||||
expect(wrapper.getByText('更新时间')).toBeTruthy();
|
||||
});
|
||||
|
||||
it('TDX 不可用时显示错误状态而不是实时数据', async () => {
|
||||
const wrapper = mountMarketOverview({ state: unavailableState });
|
||||
expect(wrapper.getByText('TDX 数据不可用')).toBeTruthy();
|
||||
expect(wrapper.queryByText('实时行情')).toBeNull();
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 运行前端测试确认失败**
|
||||
|
||||
```bash
|
||||
pnpm --filter @a-share-analysis/web exec vitest run src/app/App.test.ts
|
||||
```
|
||||
|
||||
- [ ] **Step 3: 实现首屏和组件状态**
|
||||
|
||||
页面保持结论优先顺序；指数、板块使用按钮/链接样式保留未来详情页入口；加载、空、部分、过期、错误状态均有明确文案和稳定尺寸。分析周期和分析引擎使用 Naive UI 的选择控件，偏好保存在本地，不触发 TDX 请求参数变化。
|
||||
|
||||
- [ ] **Step 4: 接入路由和应用壳**
|
||||
|
||||
`createAppRouter()` 的 `/` 路由渲染 `MarketOverviewPage`；应用壳保留可访问 header、main 和 `NMessageProvider`，不新增无业务意义的导航菜单。
|
||||
|
||||
- [ ] **Step 5: 运行组件、构建和浏览器冒烟**
|
||||
|
||||
```bash
|
||||
pnpm --filter @a-share-analysis/web exec vitest run src/app/App.test.ts src/views/market-overview
|
||||
pnpm --filter @a-share-analysis/web build
|
||||
pnpm verify:e2e -- --project=chromium
|
||||
```
|
||||
|
||||
预期：桌面和窄屏无横向溢出，TDX 连接不可用时页面仍可读但明确标记不可用。
|
||||
|
||||
- [ ] **Step 6: 提交并推送**
|
||||
|
||||
```bash
|
||||
git add web/src/views/market-overview web/src/app/router.ts web/src/app/App.vue web/src/styles/index.scss web/src/app/App.test.ts web/tests/smoke.spec.ts
|
||||
git commit -m "feat(FEAT-MO-001): 完成TDX市场概览首屏"
|
||||
git push
|
||||
```
|
||||
|
||||
### Task 6: 真实 TDX 联调、文档追踪和 Review
|
||||
|
||||
**Files:**
|
||||
- Modify: `docs/features/FEAT-MO-001-market-overview/requirements.md`
|
||||
- Modify: `docs/features/FEAT-MO-001-market-overview/design.md`
|
||||
- Modify: `docs/features/FEAT-MO-001-market-overview/implementation-plan.md`
|
||||
- Modify: `docs/features/FEAT-MO-001-market-overview/test-plan.md`
|
||||
- Create: `docs/features/FEAT-MO-001-market-overview/development-summary.md`
|
||||
- Create: `docs/features/FEAT-MO-001-market-overview/review/code-review.md`
|
||||
- Create: `docs/features/FEAT-MO-001-market-overview/review/standards-review.md`
|
||||
- Modify: `docs/features/FEAT-MO-001-market-overview/manifest.yaml`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: 已完成的 API、前端页面、脱敏 TDX 基线和测试结果。
|
||||
- Produces: 完整功能档案、开发总结、安全/性能证据、代码 Review 和规范 Review。
|
||||
|
||||
- [ ] **Step 1: 外出 Tailscale 隧道执行真实只读联调**
|
||||
|
||||
```bash
|
||||
ssh -S "$HOME/.ssh/tdx-windows-tailnet-control" -O check tdx-windows-tailnet
|
||||
lsof -nP -iTCP:17710 -sTCP:LISTEN
|
||||
pnpm --filter @a-share-analysis/server exec vitest run apps/api/test/market-overview.e2e-spec.ts
|
||||
```
|
||||
|
||||
记录接口耗时、字段完整性、模块状态和 TDX 错误分类；报告不保存地址、密钥、完整请求或完整响应。
|
||||
|
||||
- [ ] **Step 2: 更新功能档案**
|
||||
|
||||
开发总结必须明确：原始需求、范围变化（由分层混合改为 TDX 单路径）、实际完成、修复缺陷、延期项、关键提交、测试/构建/视觉证据和残余风险。需求、设计、测试计划和 manifest 的状态必须一致。
|
||||
|
||||
- [ ] **Step 3: 执行代码 Review 和规范 Review**
|
||||
|
||||
Review 至少检查：TDX 地址白名单、错误脱敏、模块级降级、请求超时、响应大小、DTO 不透传原始字段、Axios API 边界、中文注释、性能目标、无凭据提交和移动端溢出。问题及处置写入两个 Review 文档。
|
||||
|
||||
- [ ] **Step 4: 完成全量验证和 GitNexus 变更检测**
|
||||
|
||||
```bash
|
||||
npx gitnexus analyze
|
||||
npx gitnexus detect-changes --repo /Users/citrons/Documents/Codex/2026-08-12/wo-x/a-share-analysis --scope all
|
||||
pnpm verify
|
||||
pnpm verify:source
|
||||
```
|
||||
|
||||
预期：GitNexus 只显示市场概览、配置、OpenAPI、前端路由和测试相关变更；任何未预期跨模块影响必须先处置。
|
||||
|
||||
- [ ] **Step 5: 执行治理收尾并推送标签（仅在用户批准发布时）**
|
||||
|
||||
```bash
|
||||
pnpm governance:finish -- FEAT-MO-001 market-overview
|
||||
git add docs/features/FEAT-MO-001-market-overview
|
||||
git commit -m "docs(FEAT-MO-001): 完成市场概览开发收尾"
|
||||
git push
|
||||
```
|
||||
|
||||
未获发布批准前不创建或推送版本标签；所有提交推送失败时不得标记功能完成。
|
||||
|
||||
## 计划自审
|
||||
|
||||
- 设计中的五个分模块接口均在 Task 3、Task 4、Task 5 有对应实现和测试。
|
||||
- TDX 单一路径、无样本回退、安全、性能、分钟级刷新、错误状态和脱敏报告均有明确任务。
|
||||
- OpenAPI、前端 Axios API 文件、Nest 分层、中文注释和 GitNexus 门禁均有明确文件及命令。
|
||||
- 没有 `TODO`、`TBD` 或未定义的后续函数；TDX 方法名在 Task 1 以实际只读协议验证结果为准并写入类型，避免臆测字段。
|
||||
- MySQL/Redis/RocketMQ/AI/用户体系未被实现任务隐式引入。
|
||||
@@ -0,0 +1,140 @@
|
||||
# 市场综合概览 TDX 直连设计
|
||||
|
||||
- 功能编号：FEAT-MO-001
|
||||
- 设计版本：0.2
|
||||
- 状态：已获用户确认，待实现计划
|
||||
- 日期：2026-08-18
|
||||
|
||||
## 1. 设计目标
|
||||
|
||||
首页市场概览直接使用 TDX 行情数据，向用户提供结论优先的综合盘面视图。数据链路不保留离线样本 Provider 或运行时数据源切换，TDX 不可用时明确展示不可用状态，不伪造实时行情。
|
||||
|
||||
首屏支持综合、短线和中长线视角，以及规则、AI、混合和对照模式的状态入口；本次 TDX 首屏只提供统一的市场快照和规则事实展示，不在本轮实现付费 AI 结论。
|
||||
|
||||
## 2. 系统边界
|
||||
|
||||
浏览器不得直接连接 TDX。Nest API 在服务端调用本机 TDX 隧道端点，Vue 通过既有 Axios 封装访问 Nest API。
|
||||
|
||||
```text
|
||||
Vue 市场概览
|
||||
-> Axios request 封装
|
||||
-> Nest 市场概览 API
|
||||
-> TDX HTTP 客户端
|
||||
-> 127.0.0.1:17710
|
||||
-> SSH / Tailscale 隧道
|
||||
-> Windows 127.0.0.1:17709
|
||||
-> TDX
|
||||
```
|
||||
|
||||
家庭局域网和外出 Tailscale 只改变 SSH 别名和网络路径，业务服务始终访问本机 `127.0.0.1:17710`。真实地址、用户、密钥和控制套接字只保存在开发机，不进入仓库。
|
||||
|
||||
## 3. 后端模块设计
|
||||
|
||||
后端按市场概览业务模块组织，保持连续可读的职责边界：
|
||||
|
||||
```text
|
||||
server/apps/api/src/market-overview/
|
||||
├── market-overview.module.ts
|
||||
├── market-overview.controller.ts
|
||||
├── market-overview.service.ts
|
||||
├── market-overview.dto.ts
|
||||
└── tdx/
|
||||
├── tdx.client.ts
|
||||
├── tdx.mapper.ts
|
||||
└── tdx.types.ts
|
||||
```
|
||||
|
||||
- `controller`：提供按业务模块拆分的只读 HTTP 接口。
|
||||
- `service`：组织 TDX 数据、统一快照时间并生成规则事实摘要。
|
||||
- `dto`：定义 HTTP 响应契约，禁止把 TDX 原始字段直接暴露给前端。
|
||||
- `tdx.client`：只负责请求本机 TDX 端点、超时和协议级错误。
|
||||
- `tdx.mapper`：把 TDX 原始字段转换为领域字段和展示口径。
|
||||
- `tdx.types`：描述经过确认的 TDX 原始响应结构。
|
||||
|
||||
首版接口：
|
||||
|
||||
```text
|
||||
GET /api/market-overview/summary
|
||||
GET /api/market-overview/indices
|
||||
GET /api/market-overview/breadth
|
||||
GET /api/market-overview/sectors
|
||||
GET /api/market-overview/funds
|
||||
```
|
||||
|
||||
接口按模块拆分，页面进入时可并行请求；每个接口失败不会使其他模块整体失败。未来详情页可以复用指数和板块的业务边界，不通过新增巨型首页接口解决。
|
||||
|
||||
## 4. 前端模块设计
|
||||
|
||||
```text
|
||||
web/src/
|
||||
├── api/market-overview/index.ts
|
||||
├── views/market-overview/
|
||||
│ ├── MarketOverviewPage.vue
|
||||
│ ├── useMarketOverview.ts
|
||||
│ └── components/
|
||||
└── types/market-overview.ts
|
||||
```
|
||||
|
||||
业务请求只能通过 `web/src/api/market-overview/index.ts` 调用 `web/src/utils/request.ts`。页面组件不直接使用 Axios、不拼接 TDX 地址，也不读取服务端环境变量。
|
||||
|
||||
首屏顺序：市场结论、驱动与风险、核心指数、涨跌分布与市场宽度、成交量与成交额、板块强弱、资金趋势、更新时间和 TDX 连接状态。指数和板块保留进入未来详情页的可识别入口。
|
||||
|
||||
## 5. 响应契约与状态
|
||||
|
||||
每个业务接口采用统一外层结构：
|
||||
|
||||
```json
|
||||
{
|
||||
"snapshotId": "20260818-101500",
|
||||
"asOf": "2026-08-18T10:15:00+08:00",
|
||||
"source": "tdx",
|
||||
"status": "fresh",
|
||||
"data": {},
|
||||
"warnings": []
|
||||
}
|
||||
```
|
||||
|
||||
`status` 取值为 `fresh`、`delayed`、`partial` 或 `unavailable`。`snapshotId` 和 `asOf` 用于让并行接口在同一次市场快照下可对照；数据日期、更新时间和来源状态必须在页面可见。
|
||||
|
||||
- TDX 单个模块失败：只显示对应模块错误。
|
||||
- TDX 返回部分字段：保留可用字段并标记 `partial`。
|
||||
- TDX 超时或完全不可用：显示连接状态和重试入口，不显示虚假行情。
|
||||
- 后端日志只记录脱敏错误摘要，不保存完整原始行情载荷。
|
||||
|
||||
## 6. 安全策略
|
||||
|
||||
- TDX 地址固定来自服务端配置，禁止由 HTTP 请求参数传入任意 URL，避免 SSRF。
|
||||
- TDX 仅通过本机回环端点访问；Windows TDX 继续只监听 `127.0.0.1:17709`。
|
||||
- API 只读，不提供交易指令、买卖建议、目标价或仓位建议。
|
||||
- SSH、Tailscale、TDX 账号、密钥、密码、本地环境文件和生产地址不提交 Git。
|
||||
- 真实行情只用于只读联调，日志、测试报告和截图不得保存家庭网络信息或完整原始载荷。
|
||||
|
||||
## 7. 性能策略
|
||||
|
||||
- 页面并行请求各业务接口，避免串行阻塞整页。
|
||||
- TDX 客户端设置连接超时和读取超时，并记录请求耗时。
|
||||
- DTO 只返回页面需要字段，不透传完整 TDX 原始响应。
|
||||
- 首版采用分钟级刷新，不承诺秒级实时；暂不启用 Redis 缓存，待数据口径和刷新频率稳定后评估。
|
||||
- 前端使用模块级加载、空、部分数据和错误状态，避免一个模块阻断首屏。
|
||||
|
||||
## 8. 测试与验证
|
||||
|
||||
- TDX 类型转换和展示口径的单元测试。
|
||||
- 每个接口的成功、超时、空数据、部分字段和不可用测试。
|
||||
- Nest API 响应契约和错误状态测试。
|
||||
- Vue API 模块、页面状态和模块级失败降级测试。
|
||||
- 家庭局域网 SSH 路径和外出 Tailscale SSH 路径的端到端只读联调。
|
||||
- 桌面与窄屏视觉验证，确认结论、更新时间和错误状态不重叠。
|
||||
- 开发前和提交前执行 GitNexus 影响分析与变更检测；开发完成执行代码 Review、规范 Review、测试、构建和 `governance:finish`。
|
||||
|
||||
## 9. 明确不在本次实现范围
|
||||
|
||||
- 离线样本 Provider、运行时数据源切换和自动回退。
|
||||
- MySQL、Redis、RocketMQ 的正式行情存储或采集链路。
|
||||
- 付费 AI 请求和 AI 结论生成。
|
||||
- 用户、邀请、会员、订阅、社区、自选股、笔记、计划和交易功能。
|
||||
- 指数或板块详情页的完整实现；本次只保留入口和接口边界。
|
||||
|
||||
## 10. 回退方案
|
||||
|
||||
若 TDX 协议字段无法稳定确认、首屏核心模块无法独立降级或隧道联调影响本地构建，则停止 TDX 直连功能提交，回退到上一个本地标签；不得以样本数据冒充 TDX 实时结果。回退只撤销本功能提交，不删除开发机 SSH、Tailscale 或 TDX 配置。
|
||||
+2
-1
@@ -19,7 +19,7 @@
|
||||
"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",
|
||||
"test:schema-baseline": "node --test tools/database/schema-baseline.test.mjs tools/database/mysql2-schema-exporter.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",
|
||||
@@ -44,6 +44,7 @@
|
||||
"eslint": "9.39.5",
|
||||
"eslint-plugin-vue": "9.33.0",
|
||||
"globals": "17.11.0",
|
||||
"mysql2": "3.23.3",
|
||||
"prettier": "3.9.6",
|
||||
"typescript": "5.9.3",
|
||||
"typescript-eslint": "8.46.2"
|
||||
|
||||
Generated
+3
@@ -26,6 +26,9 @@ importers:
|
||||
globals:
|
||||
specifier: 17.11.0
|
||||
version: 17.11.0
|
||||
mysql2:
|
||||
specifier: 3.23.3
|
||||
version: 3.23.3(@types/node@22.20.0)
|
||||
prettier:
|
||||
specifier: 3.9.6
|
||||
version: 3.9.6
|
||||
|
||||
@@ -0,0 +1,606 @@
|
||||
import { createHash } from 'node:crypto';
|
||||
import { createRequire } from 'node:module';
|
||||
|
||||
import mysql from 'mysql2/promise';
|
||||
|
||||
const require = createRequire(import.meta.url);
|
||||
const mysql2Version = require('mysql2/package.json').version;
|
||||
const DEVELOPMENT_DATABASE = 'a_share_analysis_dev';
|
||||
const VALID_TRIGGER_TIMINGS = new Set(['BEFORE', 'AFTER']);
|
||||
const VALID_TRIGGER_EVENTS = new Set(['INSERT', 'UPDATE', 'DELETE']);
|
||||
|
||||
const CATALOG_QUERIES = Object.freeze({
|
||||
tables: `SELECT TABLE_NAME, TABLE_TYPE
|
||||
FROM information_schema.TABLES
|
||||
WHERE TABLE_SCHEMA = ?
|
||||
ORDER BY TABLE_NAME`,
|
||||
viewDependencies: `SELECT VIEW_NAME, TABLE_SCHEMA AS REFERENCED_SCHEMA_NAME,
|
||||
TABLE_NAME AS REFERENCED_TABLE_NAME
|
||||
FROM information_schema.VIEW_TABLE_USAGE
|
||||
WHERE VIEW_SCHEMA = ?
|
||||
ORDER BY VIEW_NAME, REFERENCED_SCHEMA_NAME, REFERENCED_TABLE_NAME`,
|
||||
viewDefinitions: `SELECT TABLE_NAME AS VIEW_NAME, VIEW_DEFINITION
|
||||
FROM information_schema.VIEWS
|
||||
WHERE TABLE_SCHEMA = ?
|
||||
ORDER BY TABLE_NAME`,
|
||||
routines: `SELECT ROUTINE_NAME, ROUTINE_TYPE
|
||||
FROM information_schema.ROUTINES
|
||||
WHERE ROUTINE_SCHEMA = ?
|
||||
ORDER BY ROUTINE_TYPE, ROUTINE_NAME`,
|
||||
triggers: `SELECT TRIGGER_NAME, EVENT_OBJECT_TABLE, ACTION_TIMING,
|
||||
EVENT_MANIPULATION, ACTION_ORDER
|
||||
FROM information_schema.TRIGGERS
|
||||
WHERE TRIGGER_SCHEMA = ?
|
||||
ORDER BY EVENT_OBJECT_TABLE, ACTION_TIMING, EVENT_MANIPULATION,
|
||||
ACTION_ORDER, TRIGGER_NAME`,
|
||||
events: `SELECT EVENT_NAME
|
||||
FROM information_schema.EVENTS
|
||||
WHERE EVENT_SCHEMA = ?
|
||||
ORDER BY EVENT_NAME`,
|
||||
});
|
||||
|
||||
const SERVER_METADATA_QUERY = `SELECT VERSION() AS SERVER_VERSION,
|
||||
DEFAULT_CHARACTER_SET_NAME AS DATABASE_CHARSET,
|
||||
DEFAULT_COLLATION_NAME AS DATABASE_COLLATION
|
||||
FROM information_schema.SCHEMATA
|
||||
WHERE SCHEMA_NAME = ?`;
|
||||
|
||||
const CREATE_RESULT_COLUMNS = Object.freeze({
|
||||
TABLE: 'Create Table',
|
||||
VIEW: 'Create View',
|
||||
PROCEDURE: 'Create Procedure',
|
||||
FUNCTION: 'Create Function',
|
||||
TRIGGER: 'SQL Original Statement',
|
||||
EVENT: 'Create Event',
|
||||
});
|
||||
|
||||
export const MYSQL2_EXPORTER_METADATA = Object.freeze({
|
||||
name: 'mysql2-show-create',
|
||||
version: '1.0.0',
|
||||
driverName: 'mysql2',
|
||||
driverVersion: mysql2Version,
|
||||
});
|
||||
|
||||
export const DEFAULT_EXPORT_LIMITS = Object.freeze({
|
||||
connectTimeoutMs: 5_000,
|
||||
queryTimeoutMs: 5_000,
|
||||
totalTimeoutMs: 30_000,
|
||||
maxObjects: 5_000,
|
||||
maxDefinitionBytes: 1_048_576,
|
||||
});
|
||||
|
||||
export class SchemaExportError extends Error {
|
||||
constructor(code, message) {
|
||||
super(message);
|
||||
this.name = 'SchemaExportError';
|
||||
this.code = code;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 配置在 Schema 治理入口已完成 development、主机白名单和固定库名校验；这里仅映射
|
||||
* 连接所需字段，固定禁用多语句以防止未来元数据查询被拼接为任意 SQL。
|
||||
*/
|
||||
export function buildConnectionOptions(config) {
|
||||
return {
|
||||
host: config.MYSQL_HOST,
|
||||
port: Number(config.MYSQL_PORT),
|
||||
user: config.MYSQL_USERNAME,
|
||||
password: config.MYSQL_PASSWORD,
|
||||
database: config.MYSQL_DATABASE,
|
||||
charset: 'utf8mb4',
|
||||
timezone: '+08:00',
|
||||
connectTimeout: DEFAULT_EXPORT_LIMITS.connectTimeoutMs,
|
||||
multipleStatements: false,
|
||||
enableKeepAlive: true,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* 元数据对象名仍需防御性转义，避免控制字符破坏 `SHOW CREATE` 查询边界；名称不合法时
|
||||
* 不回显输入，确保异常路径不会把潜在敏感值写入日志。
|
||||
*/
|
||||
export function quoteIdentifier(identifier) {
|
||||
if (typeof identifier !== 'string' || identifier.length === 0 || /[\u0000-\u001F\u007F]/.test(identifier)) {
|
||||
throw new SchemaExportError('INVALID_IDENTIFIER', 'Schema 标识符不能为空且不得包含控制字符');
|
||||
}
|
||||
|
||||
return `\`${identifier.replaceAll('`', '``')}\``;
|
||||
}
|
||||
|
||||
/**
|
||||
* 导出器只接受项目数据库兼容基线，拒绝 MariaDB 和 MySQL 5.7 之外的服务器，避免相同
|
||||
* `SHOW CREATE` 文本在不兼容语义下被误认为可恢复的 Schema 快照。
|
||||
*/
|
||||
export function assertMysql57ServerMetadata(metadata) {
|
||||
const serverVersion = metadata?.serverVersion ?? '';
|
||||
if (!/^5\.7\.\d+(?:[-+].*)?$/.test(serverVersion) || /mariadb/i.test(serverVersion)) {
|
||||
throw new SchemaExportError('UNSUPPORTED_SERVER_VERSION', 'MySQL 服务端必须为 5.7.x');
|
||||
}
|
||||
if (metadata.databaseCharset !== 'utf8mb4') {
|
||||
throw new SchemaExportError('INVALID_DATABASE_CHARSET', '数据库字符集必须为 utf8mb4');
|
||||
}
|
||||
if (metadata.databaseCollation !== 'utf8mb4_general_ci') {
|
||||
throw new SchemaExportError('INVALID_DATABASE_COLLATION', '数据库排序规则必须为 utf8mb4_general_ci');
|
||||
}
|
||||
}
|
||||
|
||||
function requireCatalogText(value) {
|
||||
if (typeof value !== 'string' || value.length === 0) {
|
||||
throw new SchemaExportError('CATALOG_SHAPE_INVALID', 'Schema 对象目录字段无效');
|
||||
}
|
||||
return value;
|
||||
}
|
||||
|
||||
async function queryCatalogRows(connection, sql, database, limits, options = {}) {
|
||||
let result;
|
||||
try {
|
||||
result = await connection.query({
|
||||
sql,
|
||||
values: [database],
|
||||
timeout: limits.queryTimeoutMs,
|
||||
});
|
||||
} catch (error) {
|
||||
if (options.allowMissingTable && error?.code === 'ER_UNKNOWN_TABLE') {
|
||||
throw new SchemaExportError('OPTIONAL_CATALOG_UNAVAILABLE', '可选 Schema 目录来源不可用');
|
||||
}
|
||||
// mysql2 错误可能包含连接 URL、用户名或密码，目录读取的公共接口一律不透传原始文本。
|
||||
sanitizeDatabaseQueryError(error);
|
||||
}
|
||||
if (!Array.isArray(result) || !Array.isArray(result[0])) {
|
||||
throw new SchemaExportError('CATALOG_SHAPE_INVALID', 'Schema 对象目录查询结果无效');
|
||||
}
|
||||
return result[0];
|
||||
}
|
||||
|
||||
function unquoteViewIdentifier(identifier) {
|
||||
const value = identifier.startsWith('`') && identifier.endsWith('`')
|
||||
? identifier.slice(1, -1).replaceAll('``', '`')
|
||||
: identifier;
|
||||
return value;
|
||||
}
|
||||
|
||||
function parseViewDependencies(viewRows, database) {
|
||||
const dependencies = [];
|
||||
for (const row of viewRows) {
|
||||
const view = requireCatalogText(row.VIEW_NAME);
|
||||
const definition = requireCatalogText(row.VIEW_DEFINITION);
|
||||
const inspectable = maskStringLiterals(definition);
|
||||
const referencePattern = /\b(?:FROM|JOIN)\s+((?:`[^`]+`|[A-Za-z0-9_$]+)(?:\s*\.\s*(?:`[^`]+`|[A-Za-z0-9_$]+))?)/gi;
|
||||
for (const match of inspectable.matchAll(referencePattern)) {
|
||||
const parts = match[1].split(/\s*\.\s*/).map(unquoteViewIdentifier);
|
||||
dependencies.push({
|
||||
view,
|
||||
referencedSchema: parts.length === 2 ? parts[0] : database,
|
||||
referencedObject: parts.length === 2 ? parts[1] : parts[0],
|
||||
});
|
||||
}
|
||||
}
|
||||
dependencies.sort(
|
||||
(left, right) =>
|
||||
left.view.localeCompare(right.view) ||
|
||||
left.referencedSchema.localeCompare(right.referencedSchema) ||
|
||||
left.referencedObject.localeCompare(right.referencedObject),
|
||||
);
|
||||
return dependencies;
|
||||
}
|
||||
|
||||
function assertObjectLimit(count, limits) {
|
||||
if (!Number.isInteger(limits.maxObjects) || limits.maxObjects < 0 || count > limits.maxObjects) {
|
||||
throw new SchemaExportError('OBJECT_LIMIT_EXCEEDED', 'Schema 对象数量超过安全上限');
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 目录查询只从 information_schema 读取固定列，库名始终作为参数传入。每类对象
|
||||
* 在进入后续 SHOW CREATE 前先转换成稳定的小对象，并在累计数量越界时立即停止。
|
||||
*/
|
||||
export async function readSchemaCatalog(connection, database, limits = DEFAULT_EXPORT_LIMITS) {
|
||||
const tableRows = await queryCatalogRows(connection, CATALOG_QUERIES.tables, database, limits);
|
||||
const tables = [];
|
||||
const views = [];
|
||||
for (const row of tableRows) {
|
||||
const name = requireCatalogText(row.TABLE_NAME);
|
||||
if (row.TABLE_TYPE === 'BASE TABLE') tables.push(name);
|
||||
else if (row.TABLE_TYPE === 'VIEW') views.push(name);
|
||||
else throw new SchemaExportError('UNKNOWN_TABLE_TYPE', 'Schema 目录包含未知表类型');
|
||||
}
|
||||
tables.sort();
|
||||
views.sort();
|
||||
let objectCount = tables.length + views.length;
|
||||
assertObjectLimit(objectCount, limits);
|
||||
|
||||
let viewDependencies;
|
||||
try {
|
||||
const dependencyRows = await queryCatalogRows(
|
||||
connection,
|
||||
CATALOG_QUERIES.viewDependencies,
|
||||
database,
|
||||
limits,
|
||||
{ allowMissingTable: true },
|
||||
);
|
||||
viewDependencies = dependencyRows.map((row) => ({
|
||||
view: requireCatalogText(row.VIEW_NAME),
|
||||
referencedSchema: requireCatalogText(row.REFERENCED_SCHEMA_NAME),
|
||||
referencedObject: requireCatalogText(row.REFERENCED_TABLE_NAME),
|
||||
}));
|
||||
} catch (error) {
|
||||
if (error.code !== 'OPTIONAL_CATALOG_UNAVAILABLE') throw error;
|
||||
const viewRows = await queryCatalogRows(
|
||||
connection,
|
||||
CATALOG_QUERIES.viewDefinitions,
|
||||
database,
|
||||
limits,
|
||||
);
|
||||
viewDependencies = parseViewDependencies(viewRows, database);
|
||||
}
|
||||
|
||||
const routineRows = await queryCatalogRows(connection, CATALOG_QUERIES.routines, database, limits);
|
||||
const routines = routineRows.map((row) => {
|
||||
const type = requireCatalogText(row.ROUTINE_TYPE);
|
||||
if (!['FUNCTION', 'PROCEDURE'].includes(type)) {
|
||||
throw new SchemaExportError('CATALOG_SHAPE_INVALID', 'Schema 目录包含未知例程类型');
|
||||
}
|
||||
return { name: requireCatalogText(row.ROUTINE_NAME), type };
|
||||
});
|
||||
routines.sort((left, right) => left.type.localeCompare(right.type) || left.name.localeCompare(right.name));
|
||||
objectCount += routines.length;
|
||||
assertObjectLimit(objectCount, limits);
|
||||
|
||||
const triggerRows = await queryCatalogRows(connection, CATALOG_QUERIES.triggers, database, limits);
|
||||
const triggers = triggerRows.map((row) => {
|
||||
const timing = requireCatalogText(row.ACTION_TIMING);
|
||||
const event = requireCatalogText(row.EVENT_MANIPULATION);
|
||||
const rawOrder = row.ACTION_ORDER;
|
||||
const order = Number(rawOrder);
|
||||
if (
|
||||
!VALID_TRIGGER_TIMINGS.has(timing) ||
|
||||
!VALID_TRIGGER_EVENTS.has(event) ||
|
||||
(typeof rawOrder !== 'number' && typeof rawOrder !== 'string') ||
|
||||
(typeof rawOrder === 'string' && rawOrder.trim().length === 0) ||
|
||||
!Number.isInteger(order) ||
|
||||
order < 1
|
||||
) {
|
||||
throw new SchemaExportError('CATALOG_SHAPE_INVALID', 'Schema 触发器执行顺序无效');
|
||||
}
|
||||
return {
|
||||
name: requireCatalogText(row.TRIGGER_NAME),
|
||||
table: requireCatalogText(row.EVENT_OBJECT_TABLE),
|
||||
timing,
|
||||
event,
|
||||
order,
|
||||
};
|
||||
});
|
||||
triggers.sort(
|
||||
(left, right) =>
|
||||
left.table.localeCompare(right.table) ||
|
||||
left.timing.localeCompare(right.timing) ||
|
||||
left.event.localeCompare(right.event) ||
|
||||
left.order - right.order ||
|
||||
left.name.localeCompare(right.name),
|
||||
);
|
||||
objectCount += triggers.length;
|
||||
assertObjectLimit(objectCount, limits);
|
||||
|
||||
const eventRows = await queryCatalogRows(connection, CATALOG_QUERIES.events, database, limits);
|
||||
const events = eventRows.map((row) => requireCatalogText(row.EVENT_NAME)).sort();
|
||||
objectCount += events.length;
|
||||
assertObjectLimit(objectCount, limits);
|
||||
|
||||
return Object.freeze({
|
||||
tables: Object.freeze(tables),
|
||||
views: Object.freeze(views),
|
||||
viewDependencies: Object.freeze(viewDependencies.map((dependency) => Object.freeze(dependency))),
|
||||
routines: Object.freeze(routines.map((routine) => Object.freeze(routine))),
|
||||
triggers: Object.freeze(triggers.map((trigger) => Object.freeze(trigger))),
|
||||
events: Object.freeze(events),
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* 视图恢复顺序使用稳定 Kahn 拓扑排序。跨库或未知依赖不能被默默忽略，否则恢复
|
||||
* 出来的 Schema 可能引用未捕获对象；同层节点始终按名称排序以保证逐字节确定性。
|
||||
*/
|
||||
export function orderViewNames(catalog) {
|
||||
const tables = new Set(catalog.tables ?? []);
|
||||
const views = new Set(catalog.views ?? []);
|
||||
const incoming = new Map([...views].map((view) => [view, 0]));
|
||||
const dependents = new Map([...views].map((view) => [view, []]));
|
||||
|
||||
for (const dependency of catalog.viewDependencies ?? []) {
|
||||
if (dependency.referencedSchema !== DEVELOPMENT_DATABASE) {
|
||||
throw new SchemaExportError(
|
||||
'CROSS_SCHEMA_VIEW_DEPENDENCY',
|
||||
'Schema 视图包含跨库依赖',
|
||||
);
|
||||
}
|
||||
if (!views.has(dependency.view)) {
|
||||
throw new SchemaExportError('UNKNOWN_VIEW_DEPENDENCY', 'Schema 视图依赖来源未知');
|
||||
}
|
||||
if (tables.has(dependency.referencedObject)) continue;
|
||||
if (!views.has(dependency.referencedObject)) {
|
||||
throw new SchemaExportError('UNKNOWN_VIEW_DEPENDENCY', 'Schema 视图依赖对象未知');
|
||||
}
|
||||
incoming.set(dependency.view, incoming.get(dependency.view) + 1);
|
||||
dependents.get(dependency.referencedObject).push(dependency.view);
|
||||
}
|
||||
|
||||
for (const names of dependents.values()) names.sort();
|
||||
const ready = [...views].filter((view) => incoming.get(view) === 0).sort();
|
||||
const ordered = [];
|
||||
while (ready.length > 0) {
|
||||
const view = ready.shift();
|
||||
ordered.push(view);
|
||||
for (const dependent of dependents.get(view)) {
|
||||
incoming.set(dependent, incoming.get(dependent) - 1);
|
||||
if (incoming.get(dependent) === 0) {
|
||||
ready.push(dependent);
|
||||
ready.sort();
|
||||
}
|
||||
}
|
||||
}
|
||||
if (ordered.length !== views.size) {
|
||||
throw new SchemaExportError('VIEW_DEPENDENCY_CYCLE', 'Schema 视图依赖存在循环');
|
||||
}
|
||||
return ordered;
|
||||
}
|
||||
|
||||
function sha256(content) {
|
||||
return createHash('sha256').update(content, 'utf8').digest('hex');
|
||||
}
|
||||
|
||||
/** 只屏蔽 SQL 字符串字面量，保留标识符参与 DEFINER 和凭据扫描。 */
|
||||
function maskStringLiterals(sql) {
|
||||
return String(sql).replace(/'(?:''|\\.|[^'\\])*'/gs, "''");
|
||||
}
|
||||
|
||||
function removeTableAutoIncrementOutsideLiterals(sql) {
|
||||
const literals = [];
|
||||
const masked = String(sql).replace(/'(?:''|\\.|[^'\\])*'/gs, (literal) => {
|
||||
const index = literals.push(literal) - 1;
|
||||
return `\u0001${index}\u0002`;
|
||||
});
|
||||
const cleaned = masked.replace(
|
||||
/\sAUTO_INCREMENT=\d+(?=\s(?:DEFAULT\s+)?CHARSET=)/i,
|
||||
'',
|
||||
);
|
||||
return cleaned.replace(/\u0001(\d+)\u0002/g, (_match, index) => literals[Number(index)]);
|
||||
}
|
||||
|
||||
/**
|
||||
* SHOW CREATE 的格式由服务端决定，这里只移除与结构无关的账号绑定、当前表自增值、
|
||||
* 行尾分号和换行差异，不重排对象体，也不删除字符串字面量中的业务文本。
|
||||
*/
|
||||
export function normalizeCreateDefinition(definition) {
|
||||
const normalized = String(definition)
|
||||
.replace(/\r\n?/g, '\n')
|
||||
.replace(
|
||||
/^(CREATE\s+(?:ALGORITHM=\S+\s+)?)DEFINER=`(?:``|[^`])+`@`(?:`(?:``|[^`])+`|'(?:''|[^'])+'|\S+)\s+/i,
|
||||
'$1',
|
||||
)
|
||||
.trim()
|
||||
.replace(/;+\s*$/, '');
|
||||
const withoutCurrentAutoIncrement = removeTableAutoIncrementOutsideLiterals(normalized);
|
||||
const inspectable = maskStringLiterals(withoutCurrentAutoIncrement);
|
||||
if (
|
||||
/\bDEFINER\s*=/i.test(inspectable) ||
|
||||
/\b(?:password|passwd|pwd|api[_-]?key|api[_-]?token|access[_-]?token|client[_-]?secret|secret)\s*[:=]/i.test(
|
||||
inspectable,
|
||||
) ||
|
||||
/\b(?:mysql|mariadb):\/\/[^\s'"`]+/i.test(inspectable) ||
|
||||
/(?:--|\/\*)\s*(?:host|hostname|server)\s*[:=]\s*[^\s*]+/i.test(inspectable)
|
||||
) {
|
||||
throw new SchemaExportError('UNSAFE_DEFINITION', 'Schema 对象定义包含禁止内容');
|
||||
}
|
||||
return withoutCurrentAutoIncrement;
|
||||
}
|
||||
|
||||
function sanitizeDatabaseQueryError(error) {
|
||||
if (error instanceof SchemaExportError) throw error;
|
||||
throw new SchemaExportError('DATABASE_QUERY_FAILED', '开发库 Schema 查询失败');
|
||||
}
|
||||
|
||||
export async function readMysql57ServerMetadata(
|
||||
connection,
|
||||
database,
|
||||
limits = DEFAULT_EXPORT_LIMITS,
|
||||
) {
|
||||
let rows;
|
||||
try {
|
||||
[rows] = await connection.query({
|
||||
sql: SERVER_METADATA_QUERY,
|
||||
values: [database],
|
||||
timeout: limits.queryTimeoutMs,
|
||||
});
|
||||
} catch (error) {
|
||||
sanitizeDatabaseQueryError(error);
|
||||
}
|
||||
if (!Array.isArray(rows) || rows.length !== 1) {
|
||||
throw new SchemaExportError('DATABASE_METADATA_INVALID', '开发库元数据查询结果无效');
|
||||
}
|
||||
const metadata = {
|
||||
serverVersion: rows[0].SERVER_VERSION,
|
||||
databaseCharset: rows[0].DATABASE_CHARSET,
|
||||
databaseCollation: rows[0].DATABASE_COLLATION,
|
||||
};
|
||||
assertMysql57ServerMetadata(metadata);
|
||||
return Object.freeze(metadata);
|
||||
}
|
||||
|
||||
function getCreateDescriptors(catalog) {
|
||||
const viewOrder = orderViewNames(catalog);
|
||||
const viewDefinitions = new Map((catalog.views ?? []).map((name) => [name, { name, type: 'VIEW' }]));
|
||||
return [
|
||||
...(catalog.tables ?? []).map((name) => ({ name, type: 'TABLE' })),
|
||||
...(catalog.routines ?? []).map(({ name, type }) => ({ name, type })),
|
||||
...viewOrder.map((name) => viewDefinitions.get(name)),
|
||||
...(catalog.triggers ?? []).map(({ name }) => ({ name, type: 'TRIGGER' })),
|
||||
...(catalog.events ?? []).map((name) => ({ name, type: 'EVENT' })),
|
||||
];
|
||||
}
|
||||
|
||||
async function readCreateDefinition(connection, descriptor, limits) {
|
||||
const sql = `SHOW CREATE ${descriptor.type} ${quoteIdentifier(DEVELOPMENT_DATABASE)}.${quoteIdentifier(descriptor.name)}`;
|
||||
let rows;
|
||||
try {
|
||||
[rows] = await connection.query({ sql, timeout: limits.queryTimeoutMs });
|
||||
} catch (error) {
|
||||
sanitizeDatabaseQueryError(error);
|
||||
}
|
||||
if (!Array.isArray(rows) || rows.length === 0) {
|
||||
throw new SchemaExportError('SHOW_CREATE_EMPTY', 'SHOW CREATE 未返回对象定义');
|
||||
}
|
||||
const rawDefinition = rows[0]?.[CREATE_RESULT_COLUMNS[descriptor.type]];
|
||||
if (typeof rawDefinition !== 'string' || rawDefinition.length === 0) {
|
||||
throw new SchemaExportError('SHOW_CREATE_SHAPE_INVALID', 'SHOW CREATE 返回列无效');
|
||||
}
|
||||
if (Buffer.byteLength(rawDefinition, 'utf8') > limits.maxDefinitionBytes) {
|
||||
throw new SchemaExportError('DEFINITION_LIMIT_EXCEEDED', 'Schema 对象定义超过安全上限');
|
||||
}
|
||||
return Object.freeze({
|
||||
...descriptor,
|
||||
definition: normalizeCreateDefinition(rawDefinition),
|
||||
sourceSha256: sha256(rawDefinition.replace(/\r\n?/g, '\n')),
|
||||
});
|
||||
}
|
||||
|
||||
export async function readDefinitions(connection, catalog, limits = DEFAULT_EXPORT_LIMITS) {
|
||||
const definitions = [];
|
||||
for (const descriptor of getCreateDescriptors(catalog)) {
|
||||
definitions.push(await readCreateDefinition(connection, descriptor, limits));
|
||||
}
|
||||
return Object.freeze(definitions);
|
||||
}
|
||||
|
||||
function appendDefinition(parts, definition) {
|
||||
if (['TABLE', 'VIEW'].includes(definition.type)) {
|
||||
parts.push(`${definition.definition};`);
|
||||
return;
|
||||
}
|
||||
parts.push(`DELIMITER ;;\n${definition.definition} ;;\nDELIMITER ;`);
|
||||
}
|
||||
|
||||
/** 固定恢复顺序和会话保护，不重新格式化对象体。 */
|
||||
export function renderSchemaSql(catalog, definitions) {
|
||||
const definitionsByKey = new Map(
|
||||
definitions.map((definition) => [`${definition.type}:${definition.name}`, definition]),
|
||||
);
|
||||
const parts = [
|
||||
'SET @OLD_FOREIGN_KEY_CHECKS=@@FOREIGN_KEY_CHECKS, FOREIGN_KEY_CHECKS=0;',
|
||||
'SET NAMES utf8mb4;',
|
||||
];
|
||||
for (const descriptor of getCreateDescriptors(catalog)) {
|
||||
const definition = definitionsByKey.get(`${descriptor.type}:${descriptor.name}`);
|
||||
if (!definition) {
|
||||
throw new SchemaExportError('SHOW_CREATE_SHAPE_INVALID', 'Schema 对象定义集合不完整');
|
||||
}
|
||||
appendDefinition(parts, definition);
|
||||
}
|
||||
parts.push('SET FOREIGN_KEY_CHECKS=@OLD_FOREIGN_KEY_CHECKS;');
|
||||
return `${parts.join('\n\n')}\n`;
|
||||
}
|
||||
|
||||
function assertWithinDeadline(startedAt, now, limits) {
|
||||
if (now() - startedAt > limits.totalTimeoutMs) {
|
||||
throw new SchemaExportError('EXPORT_TIMEOUT', 'Schema 导出超过总时长限制');
|
||||
}
|
||||
}
|
||||
|
||||
function buildObjectCounts(catalog) {
|
||||
return Object.freeze({
|
||||
tables: catalog.tables.length,
|
||||
views: catalog.views.length,
|
||||
triggers: catalog.triggers.length,
|
||||
routines: catalog.routines.length,
|
||||
events: catalog.events.length,
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* 单连接执行两轮目录和定义读取；任何漂移都失败。底层数据库异常统一脱敏，连接在
|
||||
* 成功、查询失败、校验失败和超时路径均只关闭一次。
|
||||
*/
|
||||
export async function exportMysql57Schema({
|
||||
config,
|
||||
createConnection = mysql.createConnection,
|
||||
now = Date.now,
|
||||
limits = DEFAULT_EXPORT_LIMITS,
|
||||
}) {
|
||||
const startedAt = now();
|
||||
let connection;
|
||||
let result;
|
||||
let failure;
|
||||
try {
|
||||
connection = await createConnection(buildConnectionOptions(config));
|
||||
const guardedConnection = {
|
||||
async query(options) {
|
||||
assertWithinDeadline(startedAt, now, limits);
|
||||
const queryResult = await connection.query(options);
|
||||
assertWithinDeadline(startedAt, now, limits);
|
||||
return queryResult;
|
||||
},
|
||||
};
|
||||
const serverMetadata = await readMysql57ServerMetadata(
|
||||
guardedConnection,
|
||||
config.MYSQL_DATABASE,
|
||||
limits,
|
||||
);
|
||||
const beforeCatalog = await readSchemaCatalog(
|
||||
guardedConnection,
|
||||
config.MYSQL_DATABASE,
|
||||
limits,
|
||||
);
|
||||
const beforeDefinitions = await readDefinitions(guardedConnection, beforeCatalog, limits);
|
||||
const afterCatalog = await readSchemaCatalog(
|
||||
guardedConnection,
|
||||
config.MYSQL_DATABASE,
|
||||
limits,
|
||||
);
|
||||
if (sha256(JSON.stringify(beforeCatalog)) !== sha256(JSON.stringify(afterCatalog))) {
|
||||
throw new SchemaExportError(
|
||||
'CATALOG_CHANGED_DURING_EXPORT',
|
||||
'Schema 对象目录在导出期间发生变化',
|
||||
);
|
||||
}
|
||||
const afterDefinitions = await readDefinitions(guardedConnection, afterCatalog, limits);
|
||||
if (sha256(JSON.stringify(beforeDefinitions)) !== sha256(JSON.stringify(afterDefinitions))) {
|
||||
throw new SchemaExportError(
|
||||
'DEFINITION_CHANGED_DURING_EXPORT',
|
||||
'Schema 对象定义在导出期间发生变化',
|
||||
);
|
||||
}
|
||||
assertWithinDeadline(startedAt, now, limits);
|
||||
const objectCounts = buildObjectCounts(beforeCatalog);
|
||||
result = Object.freeze({
|
||||
metadata: Object.freeze({
|
||||
exporterName: MYSQL2_EXPORTER_METADATA.name,
|
||||
exporterVersion: MYSQL2_EXPORTER_METADATA.version,
|
||||
driverName: MYSQL2_EXPORTER_METADATA.driverName,
|
||||
driverVersion: MYSQL2_EXPORTER_METADATA.driverVersion,
|
||||
...serverMetadata,
|
||||
}),
|
||||
rawSql: Object.values(objectCounts).every((count) => count === 0)
|
||||
? ''
|
||||
: renderSchemaSql(beforeCatalog, beforeDefinitions),
|
||||
objectCounts,
|
||||
durationMs: now() - startedAt,
|
||||
});
|
||||
} catch (error) {
|
||||
failure =
|
||||
error instanceof SchemaExportError
|
||||
? error
|
||||
: new SchemaExportError('DATABASE_QUERY_FAILED', '开发库 Schema 查询失败');
|
||||
} finally {
|
||||
if (connection) {
|
||||
try {
|
||||
await connection.end();
|
||||
} catch {
|
||||
if (!failure) {
|
||||
failure = new SchemaExportError('DATABASE_QUERY_FAILED', '开发库 Schema 连接关闭失败');
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
if (failure) throw failure;
|
||||
return result;
|
||||
}
|
||||
@@ -0,0 +1,705 @@
|
||||
import assert from 'node:assert/strict';
|
||||
import test from 'node:test';
|
||||
|
||||
import {
|
||||
DEFAULT_EXPORT_LIMITS,
|
||||
MYSQL2_EXPORTER_METADATA,
|
||||
SchemaExportError,
|
||||
assertMysql57ServerMetadata,
|
||||
buildConnectionOptions,
|
||||
exportMysql57Schema,
|
||||
normalizeCreateDefinition,
|
||||
orderViewNames,
|
||||
quoteIdentifier,
|
||||
readDefinitions,
|
||||
readMysql57ServerMetadata,
|
||||
readSchemaCatalog,
|
||||
renderSchemaSql,
|
||||
} from './mysql2-schema-exporter.mjs';
|
||||
|
||||
const config = Object.freeze({
|
||||
MYSQL_HOST: '127.0.0.1',
|
||||
MYSQL_PORT: '3306',
|
||||
MYSQL_DATABASE: 'a_share_analysis_dev',
|
||||
MYSQL_USERNAME: 'schema_reader',
|
||||
MYSQL_PASSWORD: 'not-for-logs',
|
||||
});
|
||||
|
||||
test('连接配置固定单连接、utf8mb4、东八区且禁用多语句', () => {
|
||||
const options = buildConnectionOptions(config);
|
||||
assert.deepEqual(options, {
|
||||
host: '127.0.0.1',
|
||||
port: 3306,
|
||||
user: 'schema_reader',
|
||||
password: 'not-for-logs',
|
||||
database: 'a_share_analysis_dev',
|
||||
charset: 'utf8mb4',
|
||||
timezone: '+08:00',
|
||||
connectTimeout: 5_000,
|
||||
multipleStatements: false,
|
||||
enableKeepAlive: true,
|
||||
});
|
||||
});
|
||||
|
||||
test('标识符转义反引号并拒绝空值和控制字符', () => {
|
||||
assert.equal(quoteIdentifier('market`view'), '`market``view`');
|
||||
for (const value of ['', 'line\nbreak', 'zero\0byte']) {
|
||||
assert.throws(() => quoteIdentifier(value), SchemaExportError);
|
||||
}
|
||||
});
|
||||
|
||||
test('只接受 MySQL 5.7.x 与固定字符规则', () => {
|
||||
const valid = {
|
||||
serverVersion: '5.7.42-log',
|
||||
databaseCharset: 'utf8mb4',
|
||||
databaseCollation: 'utf8mb4_general_ci',
|
||||
};
|
||||
assert.doesNotThrow(() => assertMysql57ServerMetadata(valid));
|
||||
for (const serverVersion of [
|
||||
'5.6.51',
|
||||
'8.0.40',
|
||||
'5.7.42-MariaDB',
|
||||
'10.6.18-MariaDB',
|
||||
]) {
|
||||
assert.throws(() => assertMysql57ServerMetadata({ ...valid, serverVersion }));
|
||||
}
|
||||
});
|
||||
|
||||
function createCatalogConnection(overrides = {}) {
|
||||
const rowsBySource = {
|
||||
'information_schema.TABLES': [
|
||||
{ TABLE_NAME: 'market_snapshot', TABLE_TYPE: 'BASE TABLE' },
|
||||
{ TABLE_NAME: 'market_dashboard', TABLE_TYPE: 'VIEW' },
|
||||
{ TABLE_NAME: 'market_summary', TABLE_TYPE: 'VIEW' },
|
||||
],
|
||||
'information_schema.VIEW_TABLE_USAGE': [
|
||||
{
|
||||
VIEW_NAME: 'market_dashboard',
|
||||
REFERENCED_SCHEMA_NAME: 'a_share_analysis_dev',
|
||||
REFERENCED_TABLE_NAME: 'market_summary',
|
||||
},
|
||||
{
|
||||
VIEW_NAME: 'market_summary',
|
||||
REFERENCED_SCHEMA_NAME: 'a_share_analysis_dev',
|
||||
REFERENCED_TABLE_NAME: 'market_snapshot',
|
||||
},
|
||||
],
|
||||
'information_schema.ROUTINES': [
|
||||
{ ROUTINE_NAME: 'calculate_breadth', ROUTINE_TYPE: 'FUNCTION' },
|
||||
{ ROUTINE_NAME: 'refresh_market_snapshot', ROUTINE_TYPE: 'PROCEDURE' },
|
||||
],
|
||||
'information_schema.TRIGGERS': [
|
||||
{
|
||||
TRIGGER_NAME: 'snapshot_before_insert',
|
||||
EVENT_OBJECT_TABLE: 'market_snapshot',
|
||||
ACTION_TIMING: 'BEFORE',
|
||||
EVENT_MANIPULATION: 'INSERT',
|
||||
ACTION_ORDER: 1,
|
||||
},
|
||||
],
|
||||
'information_schema.EVENTS': [{ EVENT_NAME: 'purge_market_snapshot' }],
|
||||
...overrides,
|
||||
};
|
||||
const calls = [];
|
||||
return {
|
||||
calls,
|
||||
async query(options) {
|
||||
calls.push(options);
|
||||
const source = Object.keys(rowsBySource).find((candidate) => options.sql.includes(candidate));
|
||||
assert.ok(source, `未识别的目录查询：${options.sql}`);
|
||||
return [rowsBySource[source], []];
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
test('目录查询使用固定参数和超时并返回稳定对象', async () => {
|
||||
const connection = createCatalogConnection();
|
||||
const catalog = await readSchemaCatalog(connection, 'a_share_analysis_dev', DEFAULT_EXPORT_LIMITS);
|
||||
|
||||
assert.deepEqual(catalog, {
|
||||
tables: ['market_snapshot'],
|
||||
views: ['market_dashboard', 'market_summary'],
|
||||
viewDependencies: [
|
||||
{
|
||||
view: 'market_dashboard',
|
||||
referencedSchema: 'a_share_analysis_dev',
|
||||
referencedObject: 'market_summary',
|
||||
},
|
||||
{
|
||||
view: 'market_summary',
|
||||
referencedSchema: 'a_share_analysis_dev',
|
||||
referencedObject: 'market_snapshot',
|
||||
},
|
||||
],
|
||||
routines: [
|
||||
{ name: 'calculate_breadth', type: 'FUNCTION' },
|
||||
{ name: 'refresh_market_snapshot', type: 'PROCEDURE' },
|
||||
],
|
||||
triggers: [
|
||||
{
|
||||
name: 'snapshot_before_insert',
|
||||
table: 'market_snapshot',
|
||||
timing: 'BEFORE',
|
||||
event: 'INSERT',
|
||||
order: 1,
|
||||
},
|
||||
],
|
||||
events: ['purge_market_snapshot'],
|
||||
});
|
||||
assert.equal(connection.calls.length, 5);
|
||||
for (const call of connection.calls) {
|
||||
assert.deepEqual(call.values, ['a_share_analysis_dev']);
|
||||
assert.equal(call.timeout, DEFAULT_EXPORT_LIMITS.queryTimeoutMs);
|
||||
}
|
||||
});
|
||||
|
||||
test('MySQL 5.7 缺少 VIEW_TABLE_USAGE 时从 VIEWS 定义解析依赖', async () => {
|
||||
const fallback = createCatalogConnection();
|
||||
const connection = {
|
||||
calls: fallback.calls,
|
||||
async query(options) {
|
||||
if (options.sql.includes('information_schema.VIEW_TABLE_USAGE')) {
|
||||
throw Object.assign(new Error('unknown metadata table'), { code: 'ER_UNKNOWN_TABLE' });
|
||||
}
|
||||
if (options.sql.includes('information_schema.VIEWS')) {
|
||||
return [
|
||||
[
|
||||
{
|
||||
VIEW_NAME: 'market_dashboard',
|
||||
VIEW_DEFINITION:
|
||||
'SELECT * FROM `a_share_analysis_dev`.`market_summary`',
|
||||
},
|
||||
{
|
||||
VIEW_NAME: 'market_summary',
|
||||
VIEW_DEFINITION: 'SELECT * FROM `market_snapshot`',
|
||||
},
|
||||
],
|
||||
[],
|
||||
];
|
||||
}
|
||||
return fallback.query(options);
|
||||
},
|
||||
};
|
||||
|
||||
const catalog = await readSchemaCatalog(connection, 'a_share_analysis_dev', DEFAULT_EXPORT_LIMITS);
|
||||
assert.deepEqual(catalog.viewDependencies, [
|
||||
{
|
||||
view: 'market_dashboard',
|
||||
referencedSchema: 'a_share_analysis_dev',
|
||||
referencedObject: 'market_summary',
|
||||
},
|
||||
{
|
||||
view: 'market_summary',
|
||||
referencedSchema: 'a_share_analysis_dev',
|
||||
referencedObject: 'market_snapshot',
|
||||
},
|
||||
]);
|
||||
});
|
||||
|
||||
test('视图按依赖拓扑排序且同层按名称稳定排序', () => {
|
||||
const catalog = {
|
||||
tables: ['market_snapshot'],
|
||||
views: ['z_dashboard', 'market_summary', 'a_dashboard'],
|
||||
viewDependencies: [
|
||||
{
|
||||
view: 'z_dashboard',
|
||||
referencedSchema: 'a_share_analysis_dev',
|
||||
referencedObject: 'market_summary',
|
||||
},
|
||||
{
|
||||
view: 'a_dashboard',
|
||||
referencedSchema: 'a_share_analysis_dev',
|
||||
referencedObject: 'market_summary',
|
||||
},
|
||||
{
|
||||
view: 'market_summary',
|
||||
referencedSchema: 'a_share_analysis_dev',
|
||||
referencedObject: 'market_snapshot',
|
||||
},
|
||||
],
|
||||
};
|
||||
|
||||
assert.deepEqual(orderViewNames(catalog), ['market_summary', 'a_dashboard', 'z_dashboard']);
|
||||
});
|
||||
|
||||
test('视图排序拒绝循环、跨库和未知依赖', () => {
|
||||
const base = { tables: ['market_snapshot'], views: ['first_view', 'second_view'] };
|
||||
const invalidCases = [
|
||||
{
|
||||
code: 'VIEW_DEPENDENCY_CYCLE',
|
||||
dependencies: [
|
||||
{ view: 'first_view', referencedSchema: 'a_share_analysis_dev', referencedObject: 'second_view' },
|
||||
{ view: 'second_view', referencedSchema: 'a_share_analysis_dev', referencedObject: 'first_view' },
|
||||
],
|
||||
},
|
||||
{
|
||||
code: 'CROSS_SCHEMA_VIEW_DEPENDENCY',
|
||||
dependencies: [
|
||||
{ view: 'first_view', referencedSchema: 'production', referencedObject: 'market_snapshot' },
|
||||
],
|
||||
},
|
||||
{
|
||||
code: 'UNKNOWN_VIEW_DEPENDENCY',
|
||||
dependencies: [
|
||||
{ view: 'first_view', referencedSchema: 'a_share_analysis_dev', referencedObject: 'missing_object' },
|
||||
],
|
||||
},
|
||||
];
|
||||
|
||||
for (const invalid of invalidCases) {
|
||||
assert.throws(
|
||||
() => orderViewNames({ ...base, viewDependencies: invalid.dependencies }),
|
||||
(error) => error instanceof SchemaExportError && error.code === invalid.code,
|
||||
);
|
||||
}
|
||||
});
|
||||
|
||||
test('目录拒绝未知表类型和超过对象上限', async () => {
|
||||
const unknownType = createCatalogConnection({
|
||||
'information_schema.TABLES': [{ TABLE_NAME: 'temporary_data', TABLE_TYPE: 'SYSTEM VIEW' }],
|
||||
});
|
||||
await assert.rejects(
|
||||
() => readSchemaCatalog(unknownType, 'a_share_analysis_dev', DEFAULT_EXPORT_LIMITS),
|
||||
(error) => error instanceof SchemaExportError && error.code === 'UNKNOWN_TABLE_TYPE',
|
||||
);
|
||||
|
||||
const overLimit = createCatalogConnection({
|
||||
'information_schema.TABLES': [
|
||||
{ TABLE_NAME: 'first_table', TABLE_TYPE: 'BASE TABLE' },
|
||||
{ TABLE_NAME: 'second_table', TABLE_TYPE: 'BASE TABLE' },
|
||||
],
|
||||
});
|
||||
await assert.rejects(
|
||||
() => readSchemaCatalog(overLimit, 'a_share_analysis_dev', { ...DEFAULT_EXPORT_LIMITS, maxObjects: 1 }),
|
||||
(error) => error instanceof SchemaExportError && error.code === 'OBJECT_LIMIT_EXCEEDED',
|
||||
);
|
||||
});
|
||||
|
||||
test('目录拒绝非法触发器时机、事件和空执行顺序', async () => {
|
||||
for (const trigger of [
|
||||
{
|
||||
TRIGGER_NAME: 'invalid_timing',
|
||||
EVENT_OBJECT_TABLE: 'market_snapshot',
|
||||
ACTION_TIMING: 'DURING',
|
||||
EVENT_MANIPULATION: 'INSERT',
|
||||
ACTION_ORDER: 1,
|
||||
},
|
||||
{
|
||||
TRIGGER_NAME: 'invalid_event',
|
||||
EVENT_OBJECT_TABLE: 'market_snapshot',
|
||||
ACTION_TIMING: 'BEFORE',
|
||||
EVENT_MANIPULATION: 'MERGE',
|
||||
ACTION_ORDER: 1,
|
||||
},
|
||||
{
|
||||
TRIGGER_NAME: 'empty_order',
|
||||
EVENT_OBJECT_TABLE: 'market_snapshot',
|
||||
ACTION_TIMING: 'BEFORE',
|
||||
EVENT_MANIPULATION: 'INSERT',
|
||||
ACTION_ORDER: '',
|
||||
},
|
||||
{
|
||||
TRIGGER_NAME: 'missing_order',
|
||||
EVENT_OBJECT_TABLE: 'market_snapshot',
|
||||
ACTION_TIMING: 'BEFORE',
|
||||
EVENT_MANIPULATION: 'INSERT',
|
||||
ACTION_ORDER: null,
|
||||
},
|
||||
]) {
|
||||
const connection = createCatalogConnection({
|
||||
'information_schema.TRIGGERS': [trigger],
|
||||
});
|
||||
await assert.rejects(
|
||||
() => readSchemaCatalog(connection, 'a_share_analysis_dev', DEFAULT_EXPORT_LIMITS),
|
||||
(error) => error instanceof SchemaExportError && error.code === 'CATALOG_SHAPE_INVALID',
|
||||
);
|
||||
}
|
||||
});
|
||||
|
||||
test('直接目录读取将数据库异常转为固定脱敏错误', async () => {
|
||||
const connection = {
|
||||
async query() {
|
||||
throw new Error('connect mysql://schema_reader:not-for-logs@127.0.0.1:3306/a_share_analysis_dev');
|
||||
},
|
||||
};
|
||||
|
||||
await assert.rejects(
|
||||
() => readSchemaCatalog(connection, 'a_share_analysis_dev', DEFAULT_EXPORT_LIMITS),
|
||||
(error) =>
|
||||
error instanceof SchemaExportError &&
|
||||
error.code === 'DATABASE_QUERY_FAILED' &&
|
||||
error.message === '开发库 Schema 查询失败',
|
||||
);
|
||||
});
|
||||
|
||||
const completeCatalog = Object.freeze({
|
||||
tables: ['market_snapshot'],
|
||||
views: ['market_dashboard', 'market_summary'],
|
||||
viewDependencies: [
|
||||
{
|
||||
view: 'market_dashboard',
|
||||
referencedSchema: 'a_share_analysis_dev',
|
||||
referencedObject: 'market_summary',
|
||||
},
|
||||
{
|
||||
view: 'market_summary',
|
||||
referencedSchema: 'a_share_analysis_dev',
|
||||
referencedObject: 'market_snapshot',
|
||||
},
|
||||
],
|
||||
routines: [
|
||||
{ name: 'calculate_breadth', type: 'FUNCTION' },
|
||||
{ name: 'refresh_market_snapshot', type: 'PROCEDURE' },
|
||||
],
|
||||
triggers: [
|
||||
{
|
||||
name: 'snapshot_before_insert',
|
||||
table: 'market_snapshot',
|
||||
timing: 'BEFORE',
|
||||
event: 'INSERT',
|
||||
order: 1,
|
||||
},
|
||||
],
|
||||
events: ['purge_market_snapshot'],
|
||||
});
|
||||
|
||||
const createRows = Object.freeze({
|
||||
'SHOW CREATE TABLE `a_share_analysis_dev`.`market_snapshot`': {
|
||||
'Create Table':
|
||||
'CREATE TABLE `market_snapshot` (`id` bigint NOT NULL AUTO_INCREMENT) ENGINE=InnoDB AUTO_INCREMENT=12 DEFAULT CHARSET=utf8mb4',
|
||||
},
|
||||
'SHOW CREATE VIEW `a_share_analysis_dev`.`market_summary`': {
|
||||
'Create View':
|
||||
'CREATE ALGORITHM=UNDEFINED DEFINER=`schema_user`@`192.168.1.10` SQL SECURITY DEFINER VIEW `market_summary` AS select `market_snapshot`.`id` AS `id` from `market_snapshot`',
|
||||
},
|
||||
'SHOW CREATE VIEW `a_share_analysis_dev`.`market_dashboard`': {
|
||||
'Create View':
|
||||
'CREATE ALGORITHM=UNDEFINED DEFINER=`schema_user`@`192.168.1.10` SQL SECURITY DEFINER VIEW `market_dashboard` AS select `market_summary`.`id` AS `id` from `market_summary`',
|
||||
},
|
||||
'SHOW CREATE FUNCTION `a_share_analysis_dev`.`calculate_breadth`': {
|
||||
'Create Function':
|
||||
"CREATE DEFINER=`schema_user`@`192.168.1.10` FUNCTION `calculate_breadth`() RETURNS int RETURN 1",
|
||||
},
|
||||
'SHOW CREATE PROCEDURE `a_share_analysis_dev`.`refresh_market_snapshot`': {
|
||||
'Create Procedure':
|
||||
'CREATE DEFINER=`schema_user`@`192.168.1.10` PROCEDURE `refresh_market_snapshot`()\nBEGIN\n UPDATE `market_snapshot` SET `id` = `id`;\nEND',
|
||||
},
|
||||
'SHOW CREATE TRIGGER `a_share_analysis_dev`.`snapshot_before_insert`': {
|
||||
'SQL Original Statement':
|
||||
'CREATE DEFINER=`schema_user`@`192.168.1.10` TRIGGER `snapshot_before_insert` BEFORE INSERT ON `market_snapshot` FOR EACH ROW SET NEW.id = NEW.id',
|
||||
},
|
||||
'SHOW CREATE EVENT `a_share_analysis_dev`.`purge_market_snapshot`': {
|
||||
'Create Event':
|
||||
'CREATE DEFINER=`schema_user`@`192.168.1.10` EVENT `purge_market_snapshot` ON SCHEDULE EVERY 1 DAY DO DELETE FROM `market_snapshot` WHERE `id` < 0',
|
||||
},
|
||||
});
|
||||
|
||||
function catalogRowsFor(sql) {
|
||||
if (sql.includes('information_schema.TABLES')) {
|
||||
return [
|
||||
{ TABLE_NAME: 'market_snapshot', TABLE_TYPE: 'BASE TABLE' },
|
||||
{ TABLE_NAME: 'market_dashboard', TABLE_TYPE: 'VIEW' },
|
||||
{ TABLE_NAME: 'market_summary', TABLE_TYPE: 'VIEW' },
|
||||
];
|
||||
}
|
||||
if (sql.includes('information_schema.VIEW_TABLE_USAGE')) {
|
||||
return [
|
||||
{
|
||||
VIEW_NAME: 'market_dashboard',
|
||||
REFERENCED_SCHEMA_NAME: 'a_share_analysis_dev',
|
||||
REFERENCED_TABLE_NAME: 'market_summary',
|
||||
},
|
||||
{
|
||||
VIEW_NAME: 'market_summary',
|
||||
REFERENCED_SCHEMA_NAME: 'a_share_analysis_dev',
|
||||
REFERENCED_TABLE_NAME: 'market_snapshot',
|
||||
},
|
||||
];
|
||||
}
|
||||
if (sql.includes('information_schema.ROUTINES')) {
|
||||
return [
|
||||
{ ROUTINE_NAME: 'calculate_breadth', ROUTINE_TYPE: 'FUNCTION' },
|
||||
{ ROUTINE_NAME: 'refresh_market_snapshot', ROUTINE_TYPE: 'PROCEDURE' },
|
||||
];
|
||||
}
|
||||
if (sql.includes('information_schema.TRIGGERS')) {
|
||||
return [
|
||||
{
|
||||
TRIGGER_NAME: 'snapshot_before_insert',
|
||||
EVENT_OBJECT_TABLE: 'market_snapshot',
|
||||
ACTION_TIMING: 'BEFORE',
|
||||
EVENT_MANIPULATION: 'INSERT',
|
||||
ACTION_ORDER: 1,
|
||||
},
|
||||
];
|
||||
}
|
||||
if (sql.includes('information_schema.EVENTS')) {
|
||||
return [{ EVENT_NAME: 'purge_market_snapshot' }];
|
||||
}
|
||||
return undefined;
|
||||
}
|
||||
|
||||
function createExportConnection({ mutateCatalog, mutateDefinition, queryError } = {}) {
|
||||
let catalogRound = 0;
|
||||
let definitionRound = 0;
|
||||
let tableCatalogCalls = 0;
|
||||
let tableDefinitionCalls = 0;
|
||||
const connection = {
|
||||
endCalls: 0,
|
||||
async query(options) {
|
||||
if (queryError) throw queryError;
|
||||
if (options.sql.includes('information_schema.SCHEMATA')) {
|
||||
return [
|
||||
[
|
||||
{
|
||||
SERVER_VERSION: '5.7.42-log',
|
||||
DATABASE_CHARSET: 'utf8mb4',
|
||||
DATABASE_COLLATION: 'utf8mb4_general_ci',
|
||||
},
|
||||
],
|
||||
[],
|
||||
];
|
||||
}
|
||||
const catalogRows = catalogRowsFor(options.sql);
|
||||
if (catalogRows) {
|
||||
if (options.sql.includes('information_schema.TABLES')) {
|
||||
tableCatalogCalls += 1;
|
||||
catalogRound = tableCatalogCalls > 1 ? 1 : 0;
|
||||
}
|
||||
const rows = mutateCatalog?.(options.sql, catalogRows, catalogRound) ?? catalogRows;
|
||||
return [rows, []];
|
||||
}
|
||||
const row = createRows[options.sql];
|
||||
assert.ok(row, `未识别的 SHOW CREATE：${options.sql}`);
|
||||
if (options.sql.includes('SHOW CREATE TABLE')) {
|
||||
tableDefinitionCalls += 1;
|
||||
definitionRound = tableDefinitionCalls > 1 ? 1 : 0;
|
||||
}
|
||||
const changed = mutateDefinition?.(options.sql, row, definitionRound);
|
||||
return [changed === undefined ? [row] : changed, []];
|
||||
},
|
||||
async end() {
|
||||
connection.endCalls += 1;
|
||||
},
|
||||
};
|
||||
return connection;
|
||||
}
|
||||
|
||||
test('读取并校验固定开发库服务端元数据', async () => {
|
||||
const connection = createExportConnection();
|
||||
assert.deepEqual(
|
||||
await readMysql57ServerMetadata(connection, 'a_share_analysis_dev', DEFAULT_EXPORT_LIMITS),
|
||||
{
|
||||
serverVersion: '5.7.42-log',
|
||||
databaseCharset: 'utf8mb4',
|
||||
databaseCollation: 'utf8mb4_general_ci',
|
||||
},
|
||||
);
|
||||
});
|
||||
|
||||
test('SHOW CREATE 覆盖全部对象并按可恢复顺序渲染', async () => {
|
||||
const connection = createExportConnection();
|
||||
const definitions = await readDefinitions(connection, completeCatalog, DEFAULT_EXPORT_LIMITS);
|
||||
const sql = renderSchemaSql(completeCatalog, definitions);
|
||||
|
||||
const order = [
|
||||
'CREATE TABLE `market_snapshot`',
|
||||
'FUNCTION `calculate_breadth`',
|
||||
'PROCEDURE `refresh_market_snapshot`',
|
||||
'VIEW `market_summary`',
|
||||
'VIEW `market_dashboard`',
|
||||
'TRIGGER `snapshot_before_insert`',
|
||||
'EVENT `purge_market_snapshot`',
|
||||
].map((fragment) => sql.indexOf(fragment));
|
||||
assert.ok(order.every((index) => index >= 0));
|
||||
assert.deepEqual(order, [...order].sort((left, right) => left - right));
|
||||
assert.match(sql, /DELIMITER ;;\nCREATE PROCEDURE[\s\S]+END ;;\nDELIMITER ;/);
|
||||
assert.doesNotMatch(sql, /DEFINER\s*=/i);
|
||||
assert.doesNotMatch(sql, /AUTO_INCREMENT=12/);
|
||||
assert.match(sql, /`id` bigint NOT NULL AUTO_INCREMENT/);
|
||||
assert.match(sql, /UPDATE `market_snapshot`/);
|
||||
});
|
||||
|
||||
test('定义规范化只移除账号绑定和当前自增值', () => {
|
||||
const routine = normalizeCreateDefinition(
|
||||
"CREATE DEFINER=`user`@`host` PROCEDURE `sample`() SELECT 'DEFINER=`kept`@`text` AUTO_INCREMENT=99'",
|
||||
);
|
||||
const table = normalizeCreateDefinition(
|
||||
'CREATE TABLE `sample` (`id` bigint AUTO_INCREMENT) ENGINE=InnoDB AUTO_INCREMENT=99 DEFAULT CHARSET=utf8mb4;',
|
||||
);
|
||||
assert.equal(
|
||||
routine,
|
||||
"CREATE PROCEDURE `sample`() SELECT 'DEFINER=`kept`@`text` AUTO_INCREMENT=99'",
|
||||
);
|
||||
assert.equal(
|
||||
table,
|
||||
'CREATE TABLE `sample` (`id` bigint AUTO_INCREMENT) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4',
|
||||
);
|
||||
});
|
||||
|
||||
test('规范化保留例程中的自增文本并拒绝主机信息', () => {
|
||||
const routine = normalizeCreateDefinition(
|
||||
"CREATE PROCEDURE `sample`() SELECT ' AUTO_INCREMENT=123 DEFAULT CHARSET=utf8mb4'",
|
||||
);
|
||||
assert.equal(
|
||||
routine,
|
||||
"CREATE PROCEDURE `sample`() SELECT ' AUTO_INCREMENT=123 DEFAULT CHARSET=utf8mb4'",
|
||||
);
|
||||
assert.throws(
|
||||
() => normalizeCreateDefinition('CREATE TABLE `sample` (`id` int) /* Host: prod-db.internal */'),
|
||||
(error) => error.code === 'UNSAFE_DEFINITION',
|
||||
);
|
||||
});
|
||||
|
||||
test('完整导出双重读取一致并始终关闭连接', async () => {
|
||||
const connection = createExportConnection();
|
||||
let receivedOptions;
|
||||
const result = await exportMysql57Schema({
|
||||
config,
|
||||
createConnection: async (options) => {
|
||||
receivedOptions = options;
|
||||
return connection;
|
||||
},
|
||||
now: () => 100,
|
||||
});
|
||||
|
||||
assert.equal(receivedOptions.multipleStatements, false);
|
||||
assert.equal(connection.endCalls, 1);
|
||||
assert.deepEqual(result.objectCounts, {
|
||||
tables: 1,
|
||||
views: 2,
|
||||
triggers: 1,
|
||||
routines: 2,
|
||||
events: 1,
|
||||
});
|
||||
assert.equal(result.durationMs, 0);
|
||||
assert.equal(result.metadata.driverName, 'mysql2');
|
||||
});
|
||||
|
||||
test('导出拒绝目录变化和定义变化', async () => {
|
||||
const catalogConnection = createExportConnection({
|
||||
mutateCatalog(sql, rows, round) {
|
||||
if (round === 1 && sql.includes('information_schema.TABLES')) {
|
||||
return [...rows, { TABLE_NAME: 'new_table', TABLE_TYPE: 'BASE TABLE' }];
|
||||
}
|
||||
return rows;
|
||||
},
|
||||
});
|
||||
await assert.rejects(
|
||||
() =>
|
||||
exportMysql57Schema({
|
||||
config,
|
||||
createConnection: async () => catalogConnection,
|
||||
now: () => 100,
|
||||
}),
|
||||
(error) => error.code === 'CATALOG_CHANGED_DURING_EXPORT',
|
||||
);
|
||||
assert.equal(catalogConnection.endCalls, 1);
|
||||
|
||||
const definitionConnection = createExportConnection({
|
||||
mutateDefinition(sql, row, round) {
|
||||
if (round === 1 && sql.includes('SHOW CREATE TABLE')) {
|
||||
return [{ ...row, 'Create Table': `${row['Create Table']} COMMENT='changed'` }];
|
||||
}
|
||||
return undefined;
|
||||
},
|
||||
});
|
||||
await assert.rejects(
|
||||
() =>
|
||||
exportMysql57Schema({
|
||||
config,
|
||||
createConnection: async () => definitionConnection,
|
||||
now: () => 100,
|
||||
}),
|
||||
(error) => error.code === 'DEFINITION_CHANGED_DURING_EXPORT',
|
||||
);
|
||||
assert.equal(definitionConnection.endCalls, 1);
|
||||
});
|
||||
|
||||
test('SHOW CREATE 拒绝空结果、错误形状和过大定义', async () => {
|
||||
for (const [changed, expectedCode] of [
|
||||
[[], 'SHOW_CREATE_EMPTY'],
|
||||
[[{ unexpected: 'value' }], 'SHOW_CREATE_SHAPE_INVALID'],
|
||||
]) {
|
||||
const connection = createExportConnection({
|
||||
mutateDefinition(sql) {
|
||||
return sql.includes('SHOW CREATE TABLE') ? changed : undefined;
|
||||
},
|
||||
});
|
||||
await assert.rejects(
|
||||
() => readDefinitions(connection, completeCatalog, DEFAULT_EXPORT_LIMITS),
|
||||
(error) => error.code === expectedCode,
|
||||
);
|
||||
}
|
||||
|
||||
const oversized = createExportConnection({
|
||||
mutateDefinition(sql, row) {
|
||||
return sql.includes('SHOW CREATE TABLE')
|
||||
? [{ ...row, 'Create Table': 'x'.repeat(100) }]
|
||||
: undefined;
|
||||
},
|
||||
});
|
||||
await assert.rejects(
|
||||
() =>
|
||||
readDefinitions(oversized, completeCatalog, {
|
||||
...DEFAULT_EXPORT_LIMITS,
|
||||
maxDefinitionBytes: 32,
|
||||
}),
|
||||
(error) => error.code === 'DEFINITION_LIMIT_EXCEEDED',
|
||||
);
|
||||
});
|
||||
|
||||
test('直接元数据和 SHOW CREATE 查询错误统一脱敏且保留既有业务错误', async () => {
|
||||
const rawFailure = new Error('host=prod-db.internal password=not-for-logs');
|
||||
await assert.rejects(
|
||||
() => readMysql57ServerMetadata({ query: async () => { throw rawFailure; } }, 'a_share_analysis_dev'),
|
||||
(error) =>
|
||||
error.code === 'DATABASE_QUERY_FAILED' &&
|
||||
!error.message.includes('prod-db.internal') &&
|
||||
!error.message.includes('not-for-logs'),
|
||||
);
|
||||
await assert.rejects(
|
||||
() => readDefinitions({ query: async () => { throw rawFailure; } }, completeCatalog),
|
||||
(error) =>
|
||||
error.code === 'DATABASE_QUERY_FAILED' &&
|
||||
!error.message.includes('prod-db.internal') &&
|
||||
!error.message.includes('not-for-logs'),
|
||||
);
|
||||
const timeout = new SchemaExportError('EXPORT_TIMEOUT', 'Schema 导出超过总时长限制');
|
||||
await assert.rejects(
|
||||
() => readDefinitions({ query: async () => { throw timeout; } }, completeCatalog),
|
||||
(error) => error === timeout,
|
||||
);
|
||||
});
|
||||
|
||||
test('查询失败和总超时只返回脱敏错误并关闭连接', async () => {
|
||||
const failed = createExportConnection({
|
||||
queryError: new Error('connect 127.0.0.1 password=not-for-logs'),
|
||||
});
|
||||
await assert.rejects(
|
||||
() =>
|
||||
exportMysql57Schema({
|
||||
config,
|
||||
createConnection: async () => failed,
|
||||
now: () => 100,
|
||||
}),
|
||||
(error) =>
|
||||
error.code === 'DATABASE_QUERY_FAILED' &&
|
||||
!error.message.includes('127.0.0.1') &&
|
||||
!error.message.includes('not-for-logs'),
|
||||
);
|
||||
assert.equal(failed.endCalls, 1);
|
||||
|
||||
const timedOut = createExportConnection();
|
||||
let tick = 0;
|
||||
await assert.rejects(
|
||||
() =>
|
||||
exportMysql57Schema({
|
||||
config,
|
||||
createConnection: async () => timedOut,
|
||||
now: () => (tick++ === 0 ? 0 : 30_001),
|
||||
}),
|
||||
(error) => error.code === 'EXPORT_TIMEOUT',
|
||||
);
|
||||
assert.equal(timedOut.endCalls, 1);
|
||||
});
|
||||
+256
-110
@@ -12,12 +12,20 @@ import { createHash } from 'node:crypto';
|
||||
import path from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
|
||||
import {
|
||||
MYSQL2_EXPORTER_METADATA,
|
||||
assertMysql57ServerMetadata as assertMysql57ServerMetadataV3,
|
||||
exportMysql57Schema,
|
||||
} from './mysql2-schema-exporter.mjs';
|
||||
|
||||
const DEVELOPMENT_DATABASE = 'a_share_analysis_dev';
|
||||
const REQUIRED_CHARSET = 'utf8mb4';
|
||||
const REQUIRED_COLLATION = 'utf8mb4_general_ci';
|
||||
const BASELINE_FORMAT_VERSION = 2;
|
||||
const BASELINE_FORMAT_VERSION = 3;
|
||||
const PREVIOUS_BASELINE_FORMAT_VERSION = 2;
|
||||
const LEGACY_BASELINE_FORMAT_VERSION = 1;
|
||||
const TOOL_VERSION = '2.0.0';
|
||||
const TOOL_VERSION = '3.0.0';
|
||||
const PREVIOUS_TOOL_VERSION = '2.0.0';
|
||||
const LEGACY_TOOL_VERSION = '1.0.0';
|
||||
const VERSION_PATTERN = /^v\d+\.\d+\.\d+$/;
|
||||
const DEVELOPMENT_HOSTS = new Set(['127.0.0.1', 'localhost', '::1', '112.192.20.11']);
|
||||
@@ -283,54 +291,108 @@ function countSchemaObjects(sql) {
|
||||
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,
|
||||
},
|
||||
object_counts: fields.objectCounts,
|
||||
const common = {
|
||||
format_version: fields.formatVersion,
|
||||
status: fields.status,
|
||||
application_version: fields.applicationVersion,
|
||||
git_commit: fields.gitCommit,
|
||||
source_environment: 'development',
|
||||
database_name: DEVELOPMENT_DATABASE,
|
||||
charset: REQUIRED_CHARSET,
|
||||
collation: REQUIRED_COLLATION,
|
||||
generated_at: fields.generatedAt,
|
||||
generator: `schema-baseline/${fields.formatVersion === 3 ? TOOL_VERSION : fields.formatVersion === 2 ? PREVIOUS_TOOL_VERSION : LEGACY_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`;
|
||||
object_counts: fields.objectCounts,
|
||||
};
|
||||
if (fields.formatVersion === 3) {
|
||||
common.exporter_name = fields.exporterName;
|
||||
common.exporter_version = fields.exporterVersion;
|
||||
common.database_driver = fields.driverName;
|
||||
common.database_driver_version = fields.driverVersion;
|
||||
common.mysql_server_version = fields.serverVersion;
|
||||
} else {
|
||||
common.mysql_client_version = fields.mysqlClientVersion;
|
||||
common.mysqldump_client_version = fields.mysqldumpClientVersion;
|
||||
common.mysql_server_version = fields.serverVersion;
|
||||
}
|
||||
return `${JSON.stringify(common, null, 2)}\n`;
|
||||
}
|
||||
|
||||
export function buildCapturedArtifacts(metadata, sql) {
|
||||
function assertNodeMetadata(metadata) {
|
||||
if (metadata.formatVersion !== 3) {
|
||||
throw new Error('Node Schema 基线必须使用 format v3');
|
||||
}
|
||||
for (const key of ['exporterName', 'exporterVersion', 'driverName', 'driverVersion']) {
|
||||
if (!String(metadata[key] ?? '').trim()) {
|
||||
throw new Error(`Node Schema 元数据缺少 ${key}`);
|
||||
}
|
||||
}
|
||||
assertMysql57ServerMetadataV3(metadata);
|
||||
}
|
||||
|
||||
export function buildCapturedArtifacts(metadata, sql, objectCounts) {
|
||||
if (metadata.formatVersion === 3) {
|
||||
assertNodeMetadata(metadata);
|
||||
if (!objectCounts || Object.keys(objectCounts).sort().join(',') !== [...OBJECT_KEYS].sort().join(',')) {
|
||||
throw new Error('Node Schema 对象计数字段无效');
|
||||
}
|
||||
const normalizedSql = normalizeSchemaSql(sql);
|
||||
const derivedCounts = countSchemaObjects(normalizedSql);
|
||||
for (const key of OBJECT_KEYS) {
|
||||
if (!Number.isInteger(objectCounts[key]) || objectCounts[key] < 0 || objectCounts[key] !== derivedCounts[key]) {
|
||||
throw new Error(`Node Schema 对象计数与 SQL 不一致：${key}`);
|
||||
}
|
||||
}
|
||||
if (String(sql).trim() && Object.values(objectCounts).every((count) => count === 0)) {
|
||||
throw new Error('Node Schema SQL 非空但对象计数全为零');
|
||||
}
|
||||
if (Object.values(objectCounts).every((count) => count === 0)) {
|
||||
return buildCapturedEmptyArtifacts(metadata);
|
||||
}
|
||||
const schemaSha256 = sha256(normalizedSql);
|
||||
const manifest = buildManifest({
|
||||
...metadata,
|
||||
status: 'captured',
|
||||
captured: true,
|
||||
objectCounts,
|
||||
schemaSha256,
|
||||
});
|
||||
return Object.freeze({
|
||||
status: 'captured',
|
||||
schemaSha256,
|
||||
files: Object.freeze({
|
||||
'manifest.yaml': manifest,
|
||||
'schema.sql': normalizedSql,
|
||||
'checksum.sha256': `${schemaSha256} schema.sql\n`,
|
||||
}),
|
||||
});
|
||||
}
|
||||
assertMysql57Metadata(metadata);
|
||||
if (!VERSION_PATTERN.test(metadata.applicationVersion ?? '')) {
|
||||
throw new Error(`应用版本格式无效：${metadata.applicationVersion || '(空)'}`);
|
||||
}
|
||||
const normalizedSql = normalizeSchemaSql(sql);
|
||||
const objectCounts = countSchemaObjects(normalizedSql);
|
||||
const derivedCounts = countSchemaObjects(normalizedSql);
|
||||
// mysqldump 对空库仍会输出会话 SET 与头尾注释；结构对象计数为零才是空库判据。
|
||||
if (Object.values(objectCounts).every((count) => count === 0)) {
|
||||
if (Object.values(derivedCounts).every((count) => count === 0)) {
|
||||
return buildCapturedEmptyArtifacts(metadata);
|
||||
}
|
||||
const schemaSha256 = sha256(normalizedSql);
|
||||
const manifest = buildManifest({
|
||||
...metadata,
|
||||
formatVersion: metadata.formatVersion ?? PREVIOUS_BASELINE_FORMAT_VERSION,
|
||||
status: 'captured',
|
||||
captured: true,
|
||||
objectCounts,
|
||||
objectCounts: derivedCounts,
|
||||
schemaSha256,
|
||||
});
|
||||
return Object.freeze({
|
||||
@@ -345,6 +407,23 @@ export function buildCapturedArtifacts(metadata, sql) {
|
||||
}
|
||||
|
||||
export function buildCapturedEmptyArtifacts(metadata) {
|
||||
if (metadata.formatVersion === 3) {
|
||||
assertNodeMetadata(metadata);
|
||||
const schemaSha256 = sha256('');
|
||||
const objectCounts = Object.freeze(Object.fromEntries(OBJECT_KEYS.map((key) => [key, 0])));
|
||||
const manifest = buildManifest({
|
||||
...metadata,
|
||||
status: 'captured_empty',
|
||||
captured: false,
|
||||
objectCounts,
|
||||
schemaSha256,
|
||||
});
|
||||
return Object.freeze({
|
||||
status: 'captured_empty',
|
||||
schemaSha256,
|
||||
files: Object.freeze({ 'manifest.yaml': manifest }),
|
||||
});
|
||||
}
|
||||
assertMysql57Metadata(metadata);
|
||||
if (!VERSION_PATTERN.test(metadata.applicationVersion ?? '')) {
|
||||
throw new Error(`应用版本格式无效：${metadata.applicationVersion || '(空)'}`);
|
||||
@@ -353,6 +432,7 @@ export function buildCapturedEmptyArtifacts(metadata) {
|
||||
const objectCounts = Object.freeze(Object.fromEntries(OBJECT_KEYS.map((key) => [key, 0])));
|
||||
const manifest = buildManifest({
|
||||
...metadata,
|
||||
formatVersion: metadata.formatVersion ?? PREVIOUS_BASELINE_FORMAT_VERSION,
|
||||
status: 'captured_empty',
|
||||
captured: false,
|
||||
objectCounts,
|
||||
@@ -369,8 +449,14 @@ export function buildNotApplicableArtifacts(metadata) {
|
||||
if (!VERSION_PATTERN.test(metadata.applicationVersion ?? '')) {
|
||||
throw new Error(`应用版本格式无效：${metadata.applicationVersion || '(空)'}`);
|
||||
}
|
||||
const manifest = buildManifest({
|
||||
const nodeMetadata = metadata.formatVersion === 3 ? metadata : {
|
||||
...metadata,
|
||||
formatVersion: PREVIOUS_BASELINE_FORMAT_VERSION,
|
||||
};
|
||||
const manifest = buildManifest({
|
||||
...nodeMetadata,
|
||||
...metadata,
|
||||
formatVersion: nodeMetadata.formatVersion,
|
||||
mysqlClientVersion: 'not_enabled',
|
||||
mysqldumpClientVersion: 'not_enabled',
|
||||
serverVersion: 'not_enabled',
|
||||
@@ -403,28 +489,65 @@ function compareExistingArtifacts(targetDirectory, artifacts) {
|
||||
* 先在目标父目录写入临时目录，再原子改名。这样异常不会留下半份基线；
|
||||
* 已发布版本目录只允许逐字节相同的幂等重跑，任何差异都必须人工留痕修正。
|
||||
*/
|
||||
export function persistBaselineArtifacts(targetDirectory, artifacts) {
|
||||
if (existsSync(targetDirectory)) {
|
||||
if (compareExistingArtifacts(targetDirectory, artifacts)) {
|
||||
const DEFAULT_FILE_OPERATIONS = Object.freeze({
|
||||
existsSync,
|
||||
mkdirSync,
|
||||
readFileSync,
|
||||
readdirSync,
|
||||
renameSync,
|
||||
rmSync,
|
||||
writeFileSync,
|
||||
});
|
||||
|
||||
export function persistBaselineArtifacts(
|
||||
targetDirectory,
|
||||
artifacts,
|
||||
fileOperations = DEFAULT_FILE_OPERATIONS,
|
||||
) {
|
||||
const operations = { ...DEFAULT_FILE_OPERATIONS, ...fileOperations };
|
||||
const {
|
||||
existsSync: fileExists,
|
||||
mkdirSync: makeDirectory,
|
||||
readFileSync: readFile,
|
||||
readdirSync: readDirectory,
|
||||
renameSync: renameFile,
|
||||
rmSync: removePath,
|
||||
writeFileSync: writeFile,
|
||||
} = operations;
|
||||
const compare = () => {
|
||||
const actualFiles = readDirectory(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) => readFile(path.join(targetDirectory, file), 'utf8') === artifacts.files[file],
|
||||
);
|
||||
};
|
||||
if (fileExists(targetDirectory)) {
|
||||
if (compare()) {
|
||||
return { reused: true };
|
||||
}
|
||||
throw new Error(`目标版本基线已存在且内容不同，禁止覆盖：${targetDirectory}`);
|
||||
}
|
||||
|
||||
const parentDirectory = path.dirname(targetDirectory);
|
||||
mkdirSync(parentDirectory, { recursive: true });
|
||||
makeDirectory(parentDirectory, { recursive: true });
|
||||
const temporaryDirectory = path.join(
|
||||
parentDirectory,
|
||||
`.${path.basename(targetDirectory)}.tmp-${process.pid}-${Date.now()}`,
|
||||
);
|
||||
mkdirSync(temporaryDirectory);
|
||||
makeDirectory(temporaryDirectory);
|
||||
try {
|
||||
for (const [file, content] of Object.entries(artifacts.files)) {
|
||||
writeFileSync(path.join(temporaryDirectory, file), content, 'utf8');
|
||||
writeFile(path.join(temporaryDirectory, file), content, 'utf8');
|
||||
}
|
||||
renameSync(temporaryDirectory, targetDirectory);
|
||||
renameFile(temporaryDirectory, targetDirectory);
|
||||
} catch (error) {
|
||||
rmSync(temporaryDirectory, { recursive: true, force: true });
|
||||
removePath(temporaryDirectory, { recursive: true, force: true });
|
||||
throw error;
|
||||
}
|
||||
return { reused: false };
|
||||
@@ -468,6 +591,8 @@ export function verifyBaselineDirectory(targetDirectory, expectedRelease, expect
|
||||
const supportedFormat =
|
||||
(manifest.format_version === LEGACY_BASELINE_FORMAT_VERSION &&
|
||||
manifest.generator === `schema-baseline/${LEGACY_TOOL_VERSION}`) ||
|
||||
(manifest.format_version === PREVIOUS_BASELINE_FORMAT_VERSION &&
|
||||
manifest.generator === `schema-baseline/${PREVIOUS_TOOL_VERSION}`) ||
|
||||
(manifest.format_version === BASELINE_FORMAT_VERSION &&
|
||||
manifest.generator === `schema-baseline/${TOOL_VERSION}`);
|
||||
if (
|
||||
@@ -506,30 +631,49 @@ export function verifyBaselineDirectory(targetDirectory, expectedRelease, expect
|
||||
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' ||
|
||||
const commonInvalid =
|
||||
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)
|
||||
) {
|
||||
Object.keys(manifest.objects ?? {}).sort().join(',') !==
|
||||
[...OBJECT_KEYS].sort().join(',') ||
|
||||
OBJECT_KEYS.some((key) => manifest.objects[key] !== false);
|
||||
const formatInvalid =
|
||||
manifest.format_version === BASELINE_FORMAT_VERSION
|
||||
? !String(manifest.exporter_name ?? '').trim() ||
|
||||
!String(manifest.exporter_version ?? '').trim() ||
|
||||
!String(manifest.database_driver ?? '').trim() ||
|
||||
!String(manifest.database_driver_version ?? '').trim() ||
|
||||
'mysql_client_version' in manifest ||
|
||||
'mysqldump_client_version' in manifest
|
||||
: manifest.mysql_client_version !== 'not_enabled' ||
|
||||
manifest.mysqldump_client_version !== 'not_enabled';
|
||||
if (commonInvalid || formatInvalid) {
|
||||
throw new Error('Schema 不适用清单必须证明 MySQL 未启用且所有对象均未捕获');
|
||||
}
|
||||
return { status, applicationVersion, reason };
|
||||
}
|
||||
if (status === 'captured_empty') {
|
||||
if (manifest.format_version !== BASELINE_FORMAT_VERSION) {
|
||||
throw new Error('空库 Schema 基线只允许 format v2');
|
||||
}
|
||||
assertExactFileSet(targetDirectory, CAPTURED_EMPTY_FILES);
|
||||
assertMysql57Metadata({
|
||||
mysqlClientVersion: manifest.mysql_client_version,
|
||||
mysqldumpClientVersion: manifest.mysqldump_client_version,
|
||||
serverVersion: manifest.mysql_server_version,
|
||||
databaseCharset: manifest.charset,
|
||||
databaseCollation: manifest.collation,
|
||||
});
|
||||
if (manifest.format_version === BASELINE_FORMAT_VERSION) {
|
||||
assertNodeMetadata({
|
||||
formatVersion: 3,
|
||||
exporterName: manifest.exporter_name,
|
||||
exporterVersion: manifest.exporter_version,
|
||||
driverName: manifest.database_driver,
|
||||
driverVersion: manifest.database_driver_version,
|
||||
serverVersion: manifest.mysql_server_version,
|
||||
databaseCharset: manifest.charset,
|
||||
databaseCollation: manifest.collation,
|
||||
});
|
||||
} else {
|
||||
assertMysql57Metadata({
|
||||
mysqlClientVersion: manifest.mysql_client_version,
|
||||
mysqldumpClientVersion: manifest.mysqldump_client_version,
|
||||
serverVersion: manifest.mysql_server_version,
|
||||
databaseCharset: manifest.charset,
|
||||
databaseCollation: manifest.collation,
|
||||
});
|
||||
}
|
||||
const expectedEmptyChecksum = sha256('');
|
||||
if (
|
||||
manifest.schema_sha256 !== expectedEmptyChecksum ||
|
||||
@@ -546,13 +690,26 @@ export function verifyBaselineDirectory(targetDirectory, expectedRelease, expect
|
||||
}
|
||||
|
||||
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 (manifest.format_version === BASELINE_FORMAT_VERSION) {
|
||||
assertNodeMetadata({
|
||||
formatVersion: 3,
|
||||
exporterName: manifest.exporter_name,
|
||||
exporterVersion: manifest.exporter_version,
|
||||
driverName: manifest.database_driver,
|
||||
driverVersion: manifest.database_driver_version,
|
||||
serverVersion: manifest.mysql_server_version,
|
||||
databaseCharset: manifest.charset,
|
||||
databaseCollation: manifest.collation,
|
||||
});
|
||||
} else {
|
||||
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 对象范围字段无效');
|
||||
}
|
||||
@@ -583,6 +740,14 @@ export function verifyBaselineDirectory(targetDirectory, expectedRelease, expect
|
||||
if (manifestChecksum !== schemaSha256 || checksumFile !== `${schemaSha256} schema.sql\n`) {
|
||||
throw new Error('Schema SQL、manifest 和 checksum 校验值不一致');
|
||||
}
|
||||
if (manifest.format_version === BASELINE_FORMAT_VERSION) {
|
||||
const derivedCounts = countSchemaObjects(sql);
|
||||
for (const key of OBJECT_KEYS) {
|
||||
if (manifest.object_counts[key] !== derivedCounts[key]) {
|
||||
throw new Error(`Schema 对象计数与 SQL 不一致：${key}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
return { status, applicationVersion, schemaSha256 };
|
||||
}
|
||||
|
||||
@@ -614,7 +779,7 @@ function extractClientVersion(output) {
|
||||
* 真实执行器可注入是为了让测试证明“关闭时零数据库调用”和命令边界；默认执行器
|
||||
* 仍使用 execFileSync 参数数组。密码仅放入子进程环境 MYSQL_PWD，不会进入 argv。
|
||||
*/
|
||||
export function runBaselineGeneration(options) {
|
||||
export async function runBaselineGeneration(options) {
|
||||
if ((options.commandArguments ?? []).length > 0) {
|
||||
throw new Error('Schema 基线命令不接受命令参数，不能覆盖环境、数据库或 env 路径');
|
||||
}
|
||||
@@ -641,52 +806,33 @@ export function runBaselineGeneration(options) {
|
||||
generatedAt: options.generatedAt ?? new Date().toISOString(),
|
||||
};
|
||||
if (!config.MYSQL_ENABLED) {
|
||||
const artifacts = buildNotApplicableArtifacts(commonMetadata);
|
||||
persistBaselineArtifacts(targetDirectory, artifacts);
|
||||
const artifacts = buildNotApplicableArtifacts({
|
||||
...commonMetadata,
|
||||
formatVersion: BASELINE_FORMAT_VERSION,
|
||||
exporterName: MYSQL2_EXPORTER_METADATA.name,
|
||||
exporterVersion: MYSQL2_EXPORTER_METADATA.version,
|
||||
driverName: MYSQL2_EXPORTER_METADATA.driverName,
|
||||
driverVersion: MYSQL2_EXPORTER_METADATA.driverVersion,
|
||||
serverVersion: 'not_enabled',
|
||||
databaseCharset: REQUIRED_CHARSET,
|
||||
databaseCollation: REQUIRED_COLLATION,
|
||||
});
|
||||
persistBaselineArtifacts(targetDirectory, artifacts, options.fileOperations);
|
||||
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 exported = await (options.exportSchema ?? exportMysql57Schema)({ config });
|
||||
const exportedMetadata = exported.metadata ?? {};
|
||||
const metadata = {
|
||||
...commonMetadata,
|
||||
mysqlClientVersion,
|
||||
mysqldumpClientVersion,
|
||||
serverVersion: serverMetadata[0],
|
||||
databaseCharset: serverMetadata[1],
|
||||
databaseCollation: serverMetadata[2],
|
||||
...exportedMetadata,
|
||||
applicationVersion: exportedMetadata.applicationVersion ?? commonMetadata.applicationVersion,
|
||||
gitCommit: exportedMetadata.gitCommit ?? commonMetadata.gitCommit,
|
||||
generatedAt: exportedMetadata.generatedAt ?? commonMetadata.generatedAt,
|
||||
formatVersion: BASELINE_FORMAT_VERSION,
|
||||
};
|
||||
assertMysql57Metadata(metadata);
|
||||
const rawSql = executeFile('mysqldump', buildMysqldumpArguments(config), executionOptions);
|
||||
const artifacts = buildCapturedArtifacts(metadata, rawSql);
|
||||
persistBaselineArtifacts(targetDirectory, artifacts);
|
||||
const artifacts = buildCapturedArtifacts(metadata, exported.rawSql, exported.objectCounts);
|
||||
persistBaselineArtifacts(targetDirectory, artifacts, options.fileOperations);
|
||||
return verifyBaselineDirectory(targetDirectory, options.applicationVersion);
|
||||
}
|
||||
|
||||
@@ -815,7 +961,7 @@ export function resolveFixedDevelopmentEnv(repositoryRoot) {
|
||||
return path.join(repositoryRoot, 'deploy', 'env', 'development', 'api.env.example');
|
||||
}
|
||||
|
||||
function runCommandLine() {
|
||||
export async 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 <generate|verify>（不接受额外参数）');
|
||||
@@ -824,7 +970,7 @@ function runCommandLine() {
|
||||
const release = getCurrentReleasedVersion(repositoryRoot);
|
||||
const result =
|
||||
command === 'generate'
|
||||
? runBaselineGeneration({
|
||||
? await runBaselineGeneration({
|
||||
repositoryRoot,
|
||||
envFile: resolveFixedDevelopmentEnv(repositoryRoot),
|
||||
...release,
|
||||
@@ -837,5 +983,5 @@ function runCommandLine() {
|
||||
}
|
||||
|
||||
if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
|
||||
runCommandLine();
|
||||
await runCommandLine();
|
||||
}
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
import assert from 'node:assert/strict';
|
||||
import { createHash } from 'node:crypto';
|
||||
import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
|
||||
import { mkdirSync, mkdtempSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
|
||||
import { tmpdir } from 'node:os';
|
||||
import path from 'node:path';
|
||||
import test from 'node:test';
|
||||
@@ -45,6 +45,20 @@ const validMetadata = Object.freeze({
|
||||
generatedAt: '2026-08-13T03:00:00.000Z',
|
||||
});
|
||||
|
||||
const validNodeMetadata = Object.freeze({
|
||||
formatVersion: 3,
|
||||
applicationVersion: 'v0.0.9',
|
||||
gitCommit: '88e2fdffc8c71dd682405c148a81953a8dcee9d6',
|
||||
exporterName: 'mysql2-show-create',
|
||||
exporterVersion: '1.0.0',
|
||||
driverName: 'mysql2',
|
||||
driverVersion: '3.23.3',
|
||||
serverVersion: '5.7.42-log',
|
||||
databaseCharset: 'utf8mb4',
|
||||
databaseCollation: 'utf8mb4_general_ci',
|
||||
generatedAt: '2026-08-18T00:00:00.000Z',
|
||||
});
|
||||
|
||||
function makeTemporaryDirectory() {
|
||||
return mkdtempSync(path.join(tmpdir(), 'a-share-schema-baseline-'));
|
||||
}
|
||||
@@ -300,6 +314,29 @@ test('拒绝静默覆盖已存在且内容不同的版本基线', () => {
|
||||
);
|
||||
});
|
||||
|
||||
test('写入第三个文件失败时清理目标目录和临时目录', () => {
|
||||
const root = makeTemporaryDirectory();
|
||||
const target = path.join(root, 'v0.0.5');
|
||||
const artifacts = buildCapturedArtifacts(
|
||||
validMetadata,
|
||||
'CREATE TABLE `sample` (`id` int);\n',
|
||||
);
|
||||
let writeCount = 0;
|
||||
assert.throws(
|
||||
() =>
|
||||
persistBaselineArtifacts(target, artifacts, {
|
||||
writeFileSync(...args) {
|
||||
writeCount += 1;
|
||||
if (writeCount === 3) throw new Error('injected write failure');
|
||||
return writeFileSync(...args);
|
||||
},
|
||||
}),
|
||||
/injected write failure/,
|
||||
);
|
||||
assert.equal(readdirSync(root).includes('v0.0.5'), false);
|
||||
assert.equal(readdirSync(root).some((entry) => entry.includes('.tmp-')), false);
|
||||
});
|
||||
|
||||
test('MySQL 未启用时只生成可验证不适用清单', () => {
|
||||
const root = makeTemporaryDirectory();
|
||||
const target = path.join(root, 'v0.0.5');
|
||||
@@ -314,7 +351,7 @@ test('MySQL 未启用时只生成可验证不适用清单', () => {
|
||||
assert.throws(() => readFileSync(path.join(target, 'checksum.sha256')), /ENOENT/);
|
||||
});
|
||||
|
||||
test('未启用入口不调用数据库且拒绝额外命令参数', () => {
|
||||
test('未启用入口不调用数据库且拒绝额外命令参数', async () => {
|
||||
const root = makeTemporaryDirectory();
|
||||
const envFile = path.join(root, 'development.env');
|
||||
writeFileSync(
|
||||
@@ -323,7 +360,7 @@ test('未启用入口不调用数据库且拒绝额外命令参数', () => {
|
||||
);
|
||||
let executionCount = 0;
|
||||
|
||||
const result = runBaselineGeneration({
|
||||
const result = await runBaselineGeneration({
|
||||
repositoryRoot: root,
|
||||
envFile,
|
||||
applicationVersion: 'v0.0.5',
|
||||
@@ -337,13 +374,13 @@ test('未启用入口不调用数据库且拒绝额外命令参数', () => {
|
||||
|
||||
assert.equal(result.status, 'not_applicable');
|
||||
assert.equal(executionCount, 0);
|
||||
assert.throws(
|
||||
await assert.rejects(
|
||||
() => runBaselineGeneration({ ...result, commandArguments: ['--env', 'production.env'] }),
|
||||
/不接受命令参数/,
|
||||
);
|
||||
});
|
||||
|
||||
test('启用入口分别校验 mysql 与 mysqldump 客户端版本', () => {
|
||||
test('启用入口使用异步 Node exporter', async () => {
|
||||
const root = makeTemporaryDirectory();
|
||||
const envFile = path.join(root, 'development.env');
|
||||
writeFileSync(
|
||||
@@ -353,31 +390,27 @@ test('启用入口分别校验 mysql 与 mysqldump 客户端版本', () => {
|
||||
.join('\n'),
|
||||
);
|
||||
|
||||
assert.throws(
|
||||
() =>
|
||||
runBaselineGeneration({
|
||||
const result = await 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.42-log\tutf8mb4\tutf8mb4_general_ci\n';
|
||||
}
|
||||
return 'CREATE TABLE `sample` (`id` int);\n';
|
||||
},
|
||||
}),
|
||||
/mysql 客户端必须为 5\.7/,
|
||||
);
|
||||
exportSchema: async () => ({
|
||||
metadata: {
|
||||
...validNodeMetadata,
|
||||
applicationVersion: undefined,
|
||||
gitCommit: undefined,
|
||||
generatedAt: undefined,
|
||||
},
|
||||
rawSql: '',
|
||||
objectCounts: { tables: 0, views: 0, triggers: 0, routines: 0, events: 0 },
|
||||
}),
|
||||
});
|
||||
assert.equal(result.status, 'captured_empty');
|
||||
});
|
||||
|
||||
test('幂等重跑仍核对清单提交与发布标签提交', () => {
|
||||
test('幂等重跑仍核对清单提交与发布标签提交', async () => {
|
||||
const root = makeTemporaryDirectory();
|
||||
const envFile = path.join(root, 'development.env');
|
||||
writeFileSync(
|
||||
@@ -387,9 +420,8 @@ test('幂等重跑仍核对清单提交与发布标签提交', () => {
|
||||
const target = path.join(root, 'database', 'schema-baselines', 'v0.0.5');
|
||||
persistBaselineArtifacts(target, buildNotApplicableArtifacts(validMetadata));
|
||||
|
||||
assert.throws(
|
||||
() =>
|
||||
runBaselineGeneration({
|
||||
await assert.rejects(
|
||||
() => runBaselineGeneration({
|
||||
repositoryRoot: root,
|
||||
envFile,
|
||||
applicationVersion: 'v0.0.5',
|
||||
@@ -451,7 +483,7 @@ test('仅含 mysqldump 会话设置的真实空库仍生成 captured_empty', ()
|
||||
assert.deepEqual(Object.keys(artifacts.files), ['manifest.yaml']);
|
||||
});
|
||||
|
||||
test('启用入口把 mysqldump 空结构持久化为 captured_empty', () => {
|
||||
test('启用入口把 Node exporter 空结构持久化为 captured_empty', async () => {
|
||||
const root = makeTemporaryDirectory();
|
||||
const envFile = path.join(root, 'development.env');
|
||||
writeFileSync(
|
||||
@@ -461,21 +493,17 @@ test('启用入口把 mysqldump 空结构持久化为 captured_empty', () => {
|
||||
.join('\n'),
|
||||
);
|
||||
|
||||
const result = runBaselineGeneration({
|
||||
const result = await runBaselineGeneration({
|
||||
repositoryRoot: root,
|
||||
envFile,
|
||||
applicationVersion: 'v0.0.8',
|
||||
gitCommit: validMetadata.gitCommit,
|
||||
generatedAt: validMetadata.generatedAt,
|
||||
executeFile(command, args) {
|
||||
if (args[0] === '--version') {
|
||||
return `${command} Ver 14.14 Distrib 5.7.44, for Linux`;
|
||||
}
|
||||
if (command === 'mysql') {
|
||||
return '5.7.42-log\tutf8mb4\tutf8mb4_general_ci\n';
|
||||
}
|
||||
return '';
|
||||
},
|
||||
exportSchema: async () => ({
|
||||
metadata: { ...validNodeMetadata, applicationVersion: 'v0.0.8' },
|
||||
rawSql: '',
|
||||
objectCounts: { tables: 0, views: 0, triggers: 0, routines: 0, events: 0 },
|
||||
}),
|
||||
});
|
||||
|
||||
assert.equal(result.status, 'captured_empty');
|
||||
@@ -488,6 +516,79 @@ test('启用入口把 mysqldump 空结构持久化为 captured_empty', () => {
|
||||
);
|
||||
});
|
||||
|
||||
test('format v3 清单使用 Node exporter/driver 字段且不复用 CLI 字段', () => {
|
||||
const artifacts = buildCapturedArtifacts(
|
||||
validNodeMetadata,
|
||||
'CREATE TABLE `sample` (`id` int);\n',
|
||||
{ tables: 1, views: 0, triggers: 0, routines: 0, events: 0 },
|
||||
);
|
||||
const manifest = JSON.parse(artifacts.files['manifest.yaml']);
|
||||
|
||||
assert.equal(manifest.format_version, 3);
|
||||
assert.equal(manifest.generator, 'schema-baseline/3.0.0');
|
||||
assert.equal(manifest.exporter_name, 'mysql2-show-create');
|
||||
assert.equal(manifest.exporter_version, '1.0.0');
|
||||
assert.equal(manifest.database_driver, 'mysql2');
|
||||
assert.equal(manifest.database_driver_version, '3.23.3');
|
||||
assert.equal('mysql_client_version' in manifest, false);
|
||||
assert.equal('mysqldump_client_version' in manifest, false);
|
||||
});
|
||||
|
||||
test('format v3 空库和不适用清单保留可验证状态', () => {
|
||||
const emptyManifest = JSON.parse(
|
||||
buildCapturedEmptyArtifacts(validNodeMetadata).files['manifest.yaml'],
|
||||
);
|
||||
assert.equal(emptyManifest.format_version, 3);
|
||||
assert.equal(emptyManifest.status, 'captured_empty');
|
||||
assert.equal(emptyManifest.object_counts.tables, 0);
|
||||
|
||||
const disabledManifest = JSON.parse(
|
||||
buildNotApplicableArtifacts(validNodeMetadata).files['manifest.yaml'],
|
||||
);
|
||||
assert.equal(disabledManifest.format_version, 3);
|
||||
assert.equal(disabledManifest.status, 'not_applicable');
|
||||
assert.equal(disabledManifest.database_driver, 'mysql2');
|
||||
assert.equal(disabledManifest.mysql_server_version, 'not_enabled');
|
||||
});
|
||||
|
||||
test('异步 Node exporter 注入路径生成 format v3 captured_empty', async () => {
|
||||
const root = makeTemporaryDirectory();
|
||||
const envFile = path.join(root, 'development.env');
|
||||
writeFileSync(
|
||||
envFile,
|
||||
Object.entries(validConfig)
|
||||
.map(([key, value]) => `${key}=${value}`)
|
||||
.join('\n'),
|
||||
);
|
||||
let exportCalls = 0;
|
||||
const result = await runBaselineGeneration({
|
||||
repositoryRoot: root,
|
||||
envFile,
|
||||
applicationVersion: 'v0.0.9',
|
||||
gitCommit: validNodeMetadata.gitCommit,
|
||||
generatedAt: validNodeMetadata.generatedAt,
|
||||
exportSchema: async () => {
|
||||
exportCalls += 1;
|
||||
return {
|
||||
metadata: validNodeMetadata,
|
||||
rawSql: '',
|
||||
objectCounts: { tables: 0, views: 0, triggers: 0, routines: 0, events: 0 },
|
||||
};
|
||||
},
|
||||
});
|
||||
assert.equal(result.status, 'captured_empty');
|
||||
assert.equal(exportCalls, 1);
|
||||
assert.equal(
|
||||
JSON.parse(
|
||||
readFileSync(
|
||||
path.join(root, 'database', 'schema-baselines', 'v0.0.9', 'manifest.yaml'),
|
||||
'utf8',
|
||||
),
|
||||
).format_version,
|
||||
3,
|
||||
);
|
||||
});
|
||||
|
||||
test('基线清单中的提交必须等于发布标签指向的提交', () => {
|
||||
const root = makeTemporaryDirectory();
|
||||
const target = path.join(root, 'v0.0.5');
|
||||
|
||||
Reference in New Issue
Block a user