Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
 FoXiMao
|
7dc04a2671 | ||
|
FoXiMao
|
f5994ad77e | ||
|
FoXiMao
|
3cc00de8f6 | ||
|
FoXiMao
|
70f020f87c | ||
|
FoXiMao
|
d827bfadb1 | ||
|
FoXiMao
|
da056681b6 | ||
|
FoXiMao
|
2c502ebbec | ||
|
FoXiMao
|
e552b979b6 | ||
|
FoXiMao
|
0a69aa1d43 | ||
|
FoXiMao
|
9203fdd0c2 |
@@ -8,7 +8,11 @@ coverage/
|
||||
.env
|
||||
.env.*
|
||||
!.env.example
|
||||
*.env
|
||||
*.env.*
|
||||
!*.env.example
|
||||
*.local
|
||||
.local/
|
||||
|
||||
# 编辑器与操作系统
|
||||
.DS_Store
|
||||
|
||||
@@ -9,7 +9,7 @@
|
||||
|
||||
## 强制要求
|
||||
|
||||
1. 修改生产代码前必须执行 `npm run governance:start -- <功能编号> <短名称>`，刷新 GitNexus，并完成开发前影响分析。
|
||||
1. 开发下一版本前必须先执行 `npm run schema:baseline` 和 `npm run schema:verify`，将上一已发布版本的开发库 Schema 基线用中文提交推送 Gitea；随后才能执行 `npm run governance:start -- <功能编号> <短名称>`，刷新 GitNexus 并完成开发前影响分析。
|
||||
2. 修改完成后必须执行测试、构建、视觉验证和 `npm run governance:finish -- <功能编号> <短名称>`，再次刷新 GitNexus并保存前后对比。
|
||||
3. 任何功能必须先有 `docs/features/<功能编号>-<短名称>/` 功能档案；没有 PRD、需求、设计、计划和回退说明不得视为完成。
|
||||
4. Git 提交必须使用中文 Conventional Commit，并带功能编号；禁止英文摘要和含糊提交信息。
|
||||
@@ -19,11 +19,12 @@
|
||||
8. 禁止提交密钥、密码、访问令牌、生产数据、`.env` 和 GitNexus 本地索引；凭据不得写入远程 URL、文档、脚本或命令参数。
|
||||
9. 开发完成后必须先通过代码 Review 和开发规范符合性 Review，再进入发布；Review 结论和问题处置必须写入功能档案。
|
||||
10. 每次提交验证通过后必须立即推送当前分支到项目 Gitea；本次新建标签必须单独推送。推送失败时任务不得标记完成，禁止强推或自动覆盖未知远程提交。
|
||||
11. Schema 基线只能读取 `APP_ENV=development` 的 `a_share_analysis_dev`，启用时主机必须是开发机回环地址；禁止连接、探测或读取生产数据库。MySQL 未启用时只允许生成可验证的 `not_applicable` 清单，禁止用空 SQL 冒充基线。`governance:start` 还必须确认基线已提交、已推送且远程标签一致。
|
||||
|
||||
<!-- gitnexus:start -->
|
||||
# GitNexus — Code Intelligence
|
||||
|
||||
This project is indexed by GitNexus as **a-share-analysis** (528 symbols, 553 relationships, 0 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
|
||||
This project is indexed by GitNexus as **a-share-analysis** (958 symbols, 1141 relationships, 23 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.
|
||||
|
||||
|
||||
@@ -2,6 +2,25 @@
|
||||
|
||||
本项目采用语义化版本。功能级变化请从 `docs/features/` 按功能编号追溯。
|
||||
|
||||
## 0.0.7 - 2026-08-13
|
||||
|
||||
- 将项目唯一消息队列技术基线由 RabbitMQ 调整为 RocketMQ 5.x。
|
||||
- 建立 MessageBusAdapter、Topic/Group、重试、死信和顺序消息约束。
|
||||
- 更新 Scheduler/Worker 环境模板和双部署文档，并记录本机 NameServer 分层连接验证。
|
||||
|
||||
## 0.0.6 - 2026-08-13
|
||||
|
||||
- 建立上一发布版本开发数据库 Schema 基线生成、规范化和自动校验工具。
|
||||
- 固定只读开发库安全边界、完整 MySQL 5.7 对象范围和禁止覆盖规则。
|
||||
- 为 MySQL 未启用状态建立可验证的不适用记录，并接入治理前后门禁。
|
||||
|
||||
## 0.0.5 - 2026-08-13
|
||||
|
||||
- 建立开发与生产环境配置契约及八份无秘密模板。
|
||||
- 增加仅运行 Redis 的本地开发 Compose。
|
||||
- 建立 Docker Compose 与 Ubuntu 源码生产部署边界、systemd 和 Nginx 示例。
|
||||
- 增加环境配置自动化契约测试。
|
||||
|
||||
## 0.0.4 - 2026-08-13
|
||||
|
||||
- 固定 MySQL 5.7.x、`utf8mb4` 和 `utf8mb4_general_ci` 技术基线。
|
||||
|
||||
@@ -10,11 +10,19 @@ A read-only A-share market overview and analysis tool.
|
||||
|
||||
- `web/`: Vue 3 market terminal frontend.
|
||||
- `server/`: NestJS API, scheduler, and workers. Added in a later module.
|
||||
- `deploy/`: MySQL, Redis, and RabbitMQ deployment configuration. Added with the backend module.
|
||||
- `deploy/`: MySQL 5.7, Redis, and RocketMQ 5.x deployment configuration. Added with the backend module.
|
||||
- `docs/`: Product and implementation specifications.
|
||||
|
||||
The first implementation slice is the market overview screen in `web/`.
|
||||
|
||||
## 环境与部署
|
||||
|
||||
- [本地开发环境](docs/deployment/local-development.md)：Compose 只启动 Redis，应用从源码运行。
|
||||
- [Docker Compose 生产部署](docs/deployment/docker-compose-production.md)：当前为应用脚手架落地前的配置契约骨架。
|
||||
- [Ubuntu 源码生产部署](docs/deployment/ubuntu-source-production.md)：支持 Ubuntu 22.04/24.04 LTS x86_64。
|
||||
|
||||
无秘密环境模板位于 `deploy/env/`。生产配置不进入 Git 或发布目录；Node.js 22 LTS、pnpm 10、Nginx 和基础设施由服务器管理员提供。
|
||||
|
||||
## 开发入口
|
||||
|
||||
- [文档索引](docs/index.md)
|
||||
@@ -25,9 +33,13 @@ The first implementation slice is the market overview screen in `web/`.
|
||||
开始任何模块前，先阅读根目录 `AGENTS.md`，然后运行：
|
||||
|
||||
```bash
|
||||
npm run schema:baseline
|
||||
npm run schema:verify
|
||||
npm run governance:start -- FEAT-MO-001 market-overview
|
||||
```
|
||||
|
||||
Schema 命令只允许处理固定开发库；当前 MySQL 未启用时会为上一发布版本生成可验证的不适用清单，不会连接数据库或创建空 SQL。完整规则见 [开发流程规范](docs/governance/development-workflow.md)。
|
||||
|
||||
## 项目仓库
|
||||
|
||||
- Gitea：<https://git.foximao.com/FoXiMao/a-share-analysis>
|
||||
|
||||
@@ -0,0 +1,24 @@
|
||||
{
|
||||
"format_version": 1,
|
||||
"status": "not_applicable",
|
||||
"application_version": "v0.0.5",
|
||||
"git_commit": "0a69aa1d43f40093c6482f48a13d9d222f6faec5",
|
||||
"source_environment": "development",
|
||||
"database_name": "a_share_analysis_dev",
|
||||
"mysql_client_version": "not_enabled",
|
||||
"mysqldump_client_version": "not_enabled",
|
||||
"mysql_server_version": "not_enabled",
|
||||
"charset": "utf8mb4",
|
||||
"collation": "utf8mb4_general_ci",
|
||||
"generated_at": "2026-08-13T03:15:28.832Z",
|
||||
"generator": "schema-baseline/1.0.0",
|
||||
"reason": "mysql_disabled",
|
||||
"schema_sha256": "not_applicable",
|
||||
"objects": {
|
||||
"tables": false,
|
||||
"views": false,
|
||||
"triggers": false,
|
||||
"routines": false,
|
||||
"events": false
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,24 @@
|
||||
{
|
||||
"format_version": 1,
|
||||
"status": "not_applicable",
|
||||
"application_version": "v0.0.6",
|
||||
"git_commit": "70f020f87c0cf9e19512581d798a3491c9aae5f6",
|
||||
"source_environment": "development",
|
||||
"database_name": "a_share_analysis_dev",
|
||||
"mysql_client_version": "not_enabled",
|
||||
"mysqldump_client_version": "not_enabled",
|
||||
"mysql_server_version": "not_enabled",
|
||||
"charset": "utf8mb4",
|
||||
"collation": "utf8mb4_general_ci",
|
||||
"generated_at": "2026-08-13T05:58:53.506Z",
|
||||
"generator": "schema-baseline/1.0.0",
|
||||
"reason": "mysql_disabled",
|
||||
"schema_sha256": "not_applicable",
|
||||
"objects": {
|
||||
"tables": false,
|
||||
"views": false,
|
||||
"triggers": false,
|
||||
"routines": false,
|
||||
"events": false
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,23 @@
|
||||
name: a-share-analysis-development
|
||||
|
||||
services:
|
||||
redis:
|
||||
image: redis:7.2.5-alpine
|
||||
container_name: a-share-analysis-dev-redis
|
||||
command: ["redis-server", "--appendonly", "yes"]
|
||||
ports:
|
||||
- "127.0.0.1:6379:6379"
|
||||
volumes:
|
||||
- ../../.local/redis:/data
|
||||
healthcheck:
|
||||
test: ["CMD", "redis-cli", "ping"]
|
||||
interval: 5s
|
||||
timeout: 3s
|
||||
retries: 10
|
||||
restart: unless-stopped
|
||||
networks:
|
||||
- a-share-analysis-dev
|
||||
|
||||
networks:
|
||||
a-share-analysis-dev:
|
||||
name: a-share-analysis-dev
|
||||
@@ -0,0 +1,30 @@
|
||||
# 应用镜像和启动入口将在 Web/Server 脚手架落地后验证。本文件先固定生产配置边界。
|
||||
name: a-share-analysis-production
|
||||
|
||||
services:
|
||||
web:
|
||||
image: ${A_SHARE_WEB_IMAGE:?必须提供不可变 Web 镜像引用}
|
||||
env_file: ${A_SHARE_WEB_ENV_FILE:-/etc/a-share-analysis/web.env}
|
||||
ports:
|
||||
- "127.0.0.1:8080:80"
|
||||
restart: unless-stopped
|
||||
|
||||
api:
|
||||
image: ${A_SHARE_SERVER_IMAGE:?必须提供不可变 Server 镜像引用}
|
||||
command: ["node", "dist/apps/api/main.js"]
|
||||
env_file: ${A_SHARE_API_ENV_FILE:-/etc/a-share-analysis/api.env}
|
||||
ports:
|
||||
- "127.0.0.1:3000:3000"
|
||||
restart: unless-stopped
|
||||
|
||||
scheduler:
|
||||
image: ${A_SHARE_SERVER_IMAGE:?必须提供不可变 Server 镜像引用}
|
||||
command: ["node", "dist/apps/scheduler/main.js"]
|
||||
env_file: ${A_SHARE_SCHEDULER_ENV_FILE:-/etc/a-share-analysis/scheduler.env}
|
||||
restart: unless-stopped
|
||||
|
||||
worker:
|
||||
image: ${A_SHARE_SERVER_IMAGE:?必须提供不可变 Server 镜像引用}
|
||||
command: ["node", "dist/apps/worker/main.js"]
|
||||
env_file: ${A_SHARE_WORKER_ENV_FILE:-/etc/a-share-analysis/worker.env}
|
||||
restart: unless-stopped
|
||||
+31
@@ -0,0 +1,31 @@
|
||||
# 运行环境；本地源码运行固定为 development。
|
||||
APP_ENV=development
|
||||
# API 只监听本机，避免开发服务暴露到局域网。
|
||||
API_HOST=127.0.0.1
|
||||
API_PORT=3000
|
||||
LOG_LEVEL=debug
|
||||
|
||||
# 第一阶段实际启用的 Redis。
|
||||
REDIS_HOST=127.0.0.1
|
||||
REDIS_PORT=6379
|
||||
REDIS_USERNAME=
|
||||
REDIS_PASSWORD=
|
||||
REDIS_DATABASE=0
|
||||
REDIS_TLS=false
|
||||
|
||||
# 第一阶段关闭 MySQL；启用后下列连接变量变为必填。
|
||||
MYSQL_ENABLED=false
|
||||
MYSQL_HOST=127.0.0.1
|
||||
MYSQL_PORT=3306
|
||||
MYSQL_DATABASE=a_share_analysis_dev
|
||||
MYSQL_USERNAME=
|
||||
MYSQL_PASSWORD=
|
||||
MYSQL_CHARSET=utf8mb4
|
||||
MYSQL_COLLATION=utf8mb4_general_ci
|
||||
|
||||
# 第一阶段关闭付费 AI；启用后 BASE_URL、API_KEY 和 MODEL 变为必填。
|
||||
AI_ENABLED=false
|
||||
AI_BASE_URL=
|
||||
AI_API_KEY=
|
||||
AI_MODEL=
|
||||
AI_TIMEOUT_MS=30000
|
||||
+19
@@ -0,0 +1,19 @@
|
||||
# Scheduler 只负责触发时间和调度锁。
|
||||
APP_ENV=development
|
||||
LOG_LEVEL=debug
|
||||
SCHEDULER_TIMEZONE=Asia/Shanghai
|
||||
SCHEDULER_ENABLED=true
|
||||
|
||||
REDIS_HOST=127.0.0.1
|
||||
REDIS_PORT=6379
|
||||
REDIS_USERNAME=
|
||||
REDIS_PASSWORD=
|
||||
REDIS_DATABASE=1
|
||||
REDIS_TLS=false
|
||||
|
||||
# 第一阶段关闭 RocketMQ，任务通过服务内 MessageBusAdapter 调用。
|
||||
ROCKETMQ_ENABLED=false
|
||||
ROCKETMQ_NAMESRV_ADDR=127.0.0.1:9876
|
||||
ROCKETMQ_ENDPOINT=127.0.0.1:8081
|
||||
ROCKETMQ_TOPIC_PREFIX=a-share-analysis
|
||||
ROCKETMQ_SEND_TIMEOUT_MS=3000
|
||||
+5
@@ -0,0 +1,5 @@
|
||||
# VITE 变量会进入浏览器，只允许公开配置。
|
||||
VITE_APP_ENV=development
|
||||
VITE_APP_TITLE=A-Share Analysis
|
||||
VITE_API_BASE_URL=http://127.0.0.1:3000/api
|
||||
VITE_ENABLE_DEVTOOLS=true
|
||||
+36
@@ -0,0 +1,36 @@
|
||||
# 开发环境使用确定性模拟行情，不访问生产数据源。
|
||||
APP_ENV=development
|
||||
LOG_LEVEL=debug
|
||||
MARKET_DATA_MODE=mock
|
||||
MARKET_DATA_PROVIDER=deterministic-fixture
|
||||
MARKET_DATA_BASE_URL=
|
||||
MARKET_DATA_API_KEY=
|
||||
|
||||
REDIS_HOST=127.0.0.1
|
||||
REDIS_PORT=6379
|
||||
REDIS_USERNAME=
|
||||
REDIS_PASSWORD=
|
||||
REDIS_DATABASE=2
|
||||
REDIS_TLS=false
|
||||
|
||||
MYSQL_ENABLED=false
|
||||
MYSQL_HOST=127.0.0.1
|
||||
MYSQL_PORT=3306
|
||||
MYSQL_DATABASE=a_share_analysis_dev
|
||||
MYSQL_USERNAME=
|
||||
MYSQL_PASSWORD=
|
||||
MYSQL_CHARSET=utf8mb4
|
||||
MYSQL_COLLATION=utf8mb4_general_ci
|
||||
|
||||
ROCKETMQ_ENABLED=false
|
||||
ROCKETMQ_NAMESRV_ADDR=127.0.0.1:9876
|
||||
ROCKETMQ_ENDPOINT=127.0.0.1:8081
|
||||
ROCKETMQ_TOPIC_PREFIX=a-share-analysis
|
||||
ROCKETMQ_CONSUMER_GROUP=a-share-analysis-worker
|
||||
ROCKETMQ_CONSUMER_CONCURRENCY=4
|
||||
|
||||
AI_ENABLED=false
|
||||
AI_BASE_URL=
|
||||
AI_API_KEY=
|
||||
AI_MODEL=
|
||||
AI_TIMEOUT_MS=30000
|
||||
+28
@@ -0,0 +1,28 @@
|
||||
# 生产进程必须显式使用 production，禁止回退开发默认值。
|
||||
APP_ENV=production
|
||||
API_HOST=127.0.0.1
|
||||
API_PORT=3000
|
||||
LOG_LEVEL=info
|
||||
|
||||
REDIS_HOST=127.0.0.1
|
||||
REDIS_PORT=6379
|
||||
REDIS_USERNAME=
|
||||
REDIS_PASSWORD=
|
||||
REDIS_DATABASE=0
|
||||
REDIS_TLS=false
|
||||
|
||||
# 第一阶段关闭；启用后必须填写真实生产连接，但不得提交本文件副本。
|
||||
MYSQL_ENABLED=false
|
||||
MYSQL_HOST=127.0.0.1
|
||||
MYSQL_PORT=3306
|
||||
MYSQL_DATABASE=a_share_analysis
|
||||
MYSQL_USERNAME=
|
||||
MYSQL_PASSWORD=
|
||||
MYSQL_CHARSET=utf8mb4
|
||||
MYSQL_COLLATION=utf8mb4_general_ci
|
||||
|
||||
AI_ENABLED=false
|
||||
AI_BASE_URL=
|
||||
AI_API_KEY=
|
||||
AI_MODEL=
|
||||
AI_TIMEOUT_MS=30000
|
||||
+17
@@ -0,0 +1,17 @@
|
||||
APP_ENV=production
|
||||
LOG_LEVEL=info
|
||||
SCHEDULER_TIMEZONE=Asia/Shanghai
|
||||
SCHEDULER_ENABLED=true
|
||||
|
||||
REDIS_HOST=127.0.0.1
|
||||
REDIS_PORT=6379
|
||||
REDIS_USERNAME=
|
||||
REDIS_PASSWORD=
|
||||
REDIS_DATABASE=1
|
||||
REDIS_TLS=false
|
||||
|
||||
ROCKETMQ_ENABLED=false
|
||||
ROCKETMQ_NAMESRV_ADDR=
|
||||
ROCKETMQ_ENDPOINT=
|
||||
ROCKETMQ_TOPIC_PREFIX=a-share-analysis
|
||||
ROCKETMQ_SEND_TIMEOUT_MS=3000
|
||||
+5
@@ -0,0 +1,5 @@
|
||||
# VITE 变量会进入浏览器，只允许公开配置。
|
||||
VITE_APP_ENV=production
|
||||
VITE_APP_TITLE=A-Share Analysis
|
||||
VITE_API_BASE_URL=/api
|
||||
VITE_ENABLE_DEVTOOLS=false
|
||||
+36
@@ -0,0 +1,36 @@
|
||||
# 生产环境必须使用 live，启动校验拒绝 mock。
|
||||
APP_ENV=production
|
||||
LOG_LEVEL=info
|
||||
MARKET_DATA_MODE=live
|
||||
MARKET_DATA_PROVIDER=
|
||||
MARKET_DATA_BASE_URL=
|
||||
MARKET_DATA_API_KEY=
|
||||
|
||||
REDIS_HOST=127.0.0.1
|
||||
REDIS_PORT=6379
|
||||
REDIS_USERNAME=
|
||||
REDIS_PASSWORD=
|
||||
REDIS_DATABASE=2
|
||||
REDIS_TLS=false
|
||||
|
||||
MYSQL_ENABLED=false
|
||||
MYSQL_HOST=127.0.0.1
|
||||
MYSQL_PORT=3306
|
||||
MYSQL_DATABASE=a_share_analysis
|
||||
MYSQL_USERNAME=
|
||||
MYSQL_PASSWORD=
|
||||
MYSQL_CHARSET=utf8mb4
|
||||
MYSQL_COLLATION=utf8mb4_general_ci
|
||||
|
||||
ROCKETMQ_ENABLED=false
|
||||
ROCKETMQ_NAMESRV_ADDR=
|
||||
ROCKETMQ_ENDPOINT=
|
||||
ROCKETMQ_TOPIC_PREFIX=a-share-analysis
|
||||
ROCKETMQ_CONSUMER_GROUP=a-share-analysis-worker
|
||||
ROCKETMQ_CONSUMER_CONCURRENCY=4
|
||||
|
||||
AI_ENABLED=false
|
||||
AI_BASE_URL=
|
||||
AI_API_KEY=
|
||||
AI_MODEL=
|
||||
AI_TIMEOUT_MS=30000
|
||||
@@ -0,0 +1,20 @@
|
||||
server {
|
||||
listen 80;
|
||||
server_name _;
|
||||
|
||||
root /opt/a-share-analysis/current/web/dist;
|
||||
index index.html;
|
||||
|
||||
location /api/ {
|
||||
proxy_pass http://127.0.0.1:3000;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
}
|
||||
|
||||
location / {
|
||||
try_files $uri $uri/ /index.html;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,19 @@
|
||||
[Unit]
|
||||
Description=A Share Analysis API
|
||||
After=network-online.target
|
||||
Wants=network-online.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=a-share
|
||||
Group=a-share
|
||||
WorkingDirectory=/opt/a-share-analysis/current
|
||||
EnvironmentFile=/etc/a-share-analysis/api.env
|
||||
ExecStart=/usr/bin/node server/dist/apps/api/main.js
|
||||
Restart=on-failure
|
||||
RestartSec=5
|
||||
NoNewPrivileges=true
|
||||
PrivateTmp=true
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
@@ -0,0 +1,19 @@
|
||||
[Unit]
|
||||
Description=A Share Analysis Scheduler
|
||||
After=network-online.target
|
||||
Wants=network-online.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=a-share
|
||||
Group=a-share
|
||||
WorkingDirectory=/opt/a-share-analysis/current
|
||||
EnvironmentFile=/etc/a-share-analysis/scheduler.env
|
||||
ExecStart=/usr/bin/node server/dist/apps/scheduler/main.js
|
||||
Restart=on-failure
|
||||
RestartSec=5
|
||||
NoNewPrivileges=true
|
||||
PrivateTmp=true
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
@@ -0,0 +1,19 @@
|
||||
[Unit]
|
||||
Description=A Share Analysis Worker
|
||||
After=network-online.target
|
||||
Wants=network-online.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=a-share
|
||||
Group=a-share
|
||||
WorkingDirectory=/opt/a-share-analysis/current
|
||||
EnvironmentFile=/etc/a-share-analysis/worker.env
|
||||
ExecStart=/usr/bin/node server/dist/apps/worker/main.js
|
||||
Restart=on-failure
|
||||
RestartSec=5
|
||||
NoNewPrivileges=true
|
||||
PrivateTmp=true
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
@@ -0,0 +1,31 @@
|
||||
# ADR-0003：采用 RocketMQ 5.x 作为唯一消息队列
|
||||
|
||||
- 状态：accepted
|
||||
- 日期：2026-08-13
|
||||
- 关联功能：GOV-008
|
||||
|
||||
## 背景
|
||||
|
||||
项目此前在架构和环境模板中约定 RabbitMQ，但尚未实现消息客户端、Topic 或业务消费流程。产品需要分钟级盘中分析、定时采集、指标计算、AI 分析和失败重试，决定在实现前统一切换到 RocketMQ。
|
||||
|
||||
## 决策
|
||||
|
||||
- 项目唯一消息队列为 RocketMQ 5.x，不维护 RabbitMQ 双栈。
|
||||
- Scheduler 和 Worker 只依赖项目级 `MessageBusAdapter` 与版本化事件契约。
|
||||
- Node.js 客户端优先通过 RocketMQ 5.x Proxy 接入；若改用直接 NameServer/Broker 客户端，必须通过兼容性和可靠性验证。
|
||||
- Topic、Tag、Producer Group、Consumer Group、顺序键、重试与死信语义必须在功能设计中明确。
|
||||
- 本地和生产基础设施独立于应用发布；NameServer、Broker、Proxy 不随应用版本自动创建或删除。
|
||||
|
||||
## 原因
|
||||
|
||||
RocketMQ 对定时/延迟任务、重试、死信、顺序消息和后续任务规模扩展更符合预期。Adapter 边界用于控制 Node 客户端成熟度和接入协议变化带来的风险。
|
||||
|
||||
## 代价
|
||||
|
||||
- 本地和生产运维复杂度高于单节点 RabbitMQ，需要区分 NameServer、Broker 和 Proxy。
|
||||
- Node.js 生态需要在 Server 脚手架阶段单独验证，不能仅凭 NameServer 端口可达决定客户端可用。
|
||||
- 所有消费者必须按至少一次投递设计幂等和受控重放。
|
||||
|
||||
## 验证
|
||||
|
||||
GOV-008 只验证配置、文档契约和本机 NameServer 状态。真实 Topic 生产/消费必须在 Broker/Proxy 可用且 Server 客户端选定后补充契约测试。
|
||||
@@ -7,8 +7,8 @@
|
||||
```text
|
||||
web/ Vue 3 前端
|
||||
server/ NestJS API、Scheduler 与 Worker
|
||||
contracts/ HTTP 与 RabbitMQ 版本化契约
|
||||
deploy/ MySQL、Redis、RabbitMQ 和运行配置
|
||||
contracts/ HTTP 与 RocketMQ 版本化契约
|
||||
deploy/ MySQL、Redis、RocketMQ 5.x 和运行配置
|
||||
docs/ 规范、架构、ADR 与功能档案
|
||||
tools/ 可重复执行的治理和开发工具
|
||||
```
|
||||
@@ -20,7 +20,8 @@ tools/ 可重复执行的治理和开发工具
|
||||
```text
|
||||
免费数据源
|
||||
→ Scheduler 定时投递
|
||||
→ RabbitMQ
|
||||
→ MessageBusAdapter
|
||||
→ RocketMQ 5.x
|
||||
→ 行情采集 Worker
|
||||
→ 指标计算 Worker
|
||||
→ 规则 / AI / 混合分析
|
||||
@@ -30,7 +31,8 @@ tools/ 可重复执行的治理和开发工具
|
||||
```
|
||||
|
||||
- Scheduler只负责触发时间。
|
||||
- RabbitMQ只负责任务传递、确认、重试和死信。
|
||||
- MessageBusAdapter 隔离业务与 RocketMQ 客户端，禁止业务模块直接依赖 SDK。
|
||||
- RocketMQ 只负责任务传递、确认、重试、延迟消息和死信；重复投递由 Worker 幂等处理。
|
||||
- Worker负责采集、标准化、计算和分析。
|
||||
- MySQL保存可追溯事实与历史报告。
|
||||
- Redis保存最新快照、缓存、锁和限流状态。
|
||||
@@ -47,3 +49,12 @@ tools/ 可重复执行的治理和开发工具
|
||||
## 4. 当前实施顺序
|
||||
|
||||
第一阶段先实现可交互的市场综合概览和稳定数据契约，再接入正式行情采集链路。用户、邀请、权限、会员和支付后置，不进入当前核心架构。
|
||||
|
||||
## 5. 环境与部署基线
|
||||
|
||||
- 应用运行环境只定义 `development` 与 `production`；生产环境禁止模拟数据、热更新、调试端口和开发默认值回退。
|
||||
- API、Scheduler、Worker、Web 分别拥有开发和生产模板；同一进程跨环境使用相同变量名，通过启动 Schema 校验条件必填项。
|
||||
- 本地开发使用 Docker Compose 只启动 Redis，应用进程从源码运行；第一阶段 MySQL 与 RocketMQ 保持关闭。需要联调时可以连接本机独立运行的 RocketMQ 5.x。
|
||||
- 生产同时支持 Docker Compose 和 Ubuntu 22.04/24.04 LTS x86_64 源码部署，两者共用配置契约和进程边界。
|
||||
- 源码部署由管理员预装 Node.js 22 LTS、pnpm 10、Nginx 和基础设施；项目只验证，不安装或修改系统软件源。
|
||||
- 源码部署使用不可变发布目录、`a-share` 用户和 systemd 独立进程配置；生产 env 存放在 `/etc/a-share-analysis/`，不随代码版本切换覆盖。
|
||||
|
||||
@@ -0,0 +1,19 @@
|
||||
# Docker Compose 生产部署
|
||||
|
||||
生产 Docker Compose 使用不可变应用镜像和外部 env 文件。当前 `production.yml.example` 是部署契约骨架，应用镜像、健康检查和实际启动命令必须在 Web/Server 脚手架完成后验证，未验证前不得用于线上部署。
|
||||
|
||||
## 配置边界
|
||||
|
||||
- 从 `deploy/env/production/` 准备四份真实配置，存放在服务器 `/etc/a-share-analysis/` 或其他受控目录。
|
||||
- Compose 通过外部路径加载，不在 YAML、镜像和 Git 中保存秘密。
|
||||
- 镜像引用必须包含版本或内容摘要，禁止浮动 `latest`。
|
||||
- 第一阶段只依赖 Redis；MySQL 和 RocketMQ 5.x 功能开关保持关闭。
|
||||
- 启用 RocketMQ 时优先连接受运维管理的外部集群或独立基础设施 Compose，不把 NameServer、Broker、Proxy 混入应用发布生命周期。
|
||||
|
||||
## 发布与回退
|
||||
|
||||
部署前验证镜像对应已推送提交或标签、环境 Schema、健康检查和数据目录。升级只修改不可变镜像引用；失败时恢复上一完整镜像集合和未改变的外部配置。禁止删除 Redis、MySQL 或 RocketMQ CommitLog 数据目录作为应用回退手段。
|
||||
|
||||
## 验证
|
||||
|
||||
应用脚手架落地后必须补充 `docker compose config`、服务健康检查、日志读取、优雅停止和回退演练证据。本版本不声称生产 Compose 已可运行。
|
||||
@@ -0,0 +1,27 @@
|
||||
# 本地开发环境
|
||||
|
||||
本地开发使用 Docker Compose 只启动 Redis，Web、API、Scheduler 和 Worker 从源码运行并使用开发环境模板。第一阶段不自动启动 MySQL 和 RocketMQ 5.x。
|
||||
|
||||
## 配置
|
||||
|
||||
从 `deploy/env/development/` 中对应的 `*.env.example` 创建本机 `*.env.local`。真实文件被 Git 忽略，不得写入生产地址或真实密钥。
|
||||
|
||||
## Redis
|
||||
|
||||
```bash
|
||||
docker compose -f deploy/compose/development.yml up -d
|
||||
docker compose -f deploy/compose/development.yml ps
|
||||
docker compose -f deploy/compose/development.yml down
|
||||
```
|
||||
|
||||
Redis 只绑定 `127.0.0.1:6379`，数据写入仓库忽略的 `.local/redis/`。不得把该 Compose 文件用于生产。
|
||||
|
||||
## RocketMQ 联调
|
||||
|
||||
RocketMQ 由开发者在项目 Compose 外独立启动。应用启用前至少需要 NameServer、Broker；采用推荐的 Node.js Proxy 接入时还需要 Proxy。默认端口约定：NameServer `9876`、Broker `10911`、Proxy gRPC `8081`。
|
||||
|
||||
`nc -vz 127.0.0.1 9876` 只能证明 NameServer TCP 可达，不能证明 Topic 路由、Broker 注册或消息收发可用。完整联调必须继续检查 Broker 列表，并执行一次测试 Topic 的生产与消费。开发模板默认 `ROCKETMQ_ENABLED=false`；启用后必须提供可用的 `ROCKETMQ_ENDPOINT`，不得把生产地址写入本地配置或仓库。
|
||||
|
||||
## 应用状态
|
||||
|
||||
Web 和 Server 尚未完成脚手架，因此本版本只交付配置契约和 Redis 开发环境。后续脚手架必须使用 Node.js 22 LTS、pnpm 10 和这些模板，不能在本文档中假装应用已经可启动。
|
||||
@@ -0,0 +1,37 @@
|
||||
# Ubuntu 源码生产部署
|
||||
|
||||
正式支持 Ubuntu 22.04 LTS 与 Ubuntu 24.04 LTS 的 x86_64。服务器管理员预先提供 Node.js 22 LTS、pnpm 10、Nginx，以及 MySQL 5.7、Redis、RocketMQ 5.x 或相应外部服务；项目不负责安装或升级这些软件，也不修改系统软件源。
|
||||
|
||||
## 前置验证
|
||||
|
||||
```bash
|
||||
uname -m
|
||||
node --version
|
||||
pnpm --version
|
||||
nginx -v
|
||||
```
|
||||
|
||||
架构必须为 `x86_64`，Node.js 必须为 22 LTS，pnpm 必须为 10.x。不满足要求时终止部署。
|
||||
|
||||
## 目录与配置
|
||||
|
||||
- 发布目录：`/opt/a-share-analysis/releases/<版本或提交>/`。
|
||||
- 当前版本：`/opt/a-share-analysis/current` 符号链接。
|
||||
- 生产配置：`/etc/a-share-analysis/api.env`、`scheduler.env`、`worker.env`、`web.env`。
|
||||
- 运行用户：非登录系统用户 `a-share`。
|
||||
|
||||
真实配置从仓库生产模板生成，但不得放入发布目录。API、Scheduler、Worker 的 systemd 单元分别通过 `EnvironmentFile=` 读取自己的配置；包含秘密的文件建议为 `root:a-share 0640`。
|
||||
|
||||
## 构建与启动边界
|
||||
|
||||
使用 `pnpm install --frozen-lockfile` 安装锁定依赖，在新发布目录构建 Web 和 Server。Web 静态文件由 Nginx 托管，API、Scheduler、Worker 运行编译后的 JavaScript。禁止 Vite 开发服务器、watch、调试端口和生产运行 TypeScript。
|
||||
|
||||
当前应用尚未脚手架化，仓库中的 systemd 与 Nginx 文件是路径和权限契约示例，不能冒充已经验证的线上启动文件。后续应用功能必须补充实际构建、启动和健康检查验证。
|
||||
|
||||
## 升级、检查与回退
|
||||
|
||||
在新的不可变发布目录完成安装、构建和配置校验后，原子切换 `current`，依次重启 API、Scheduler、Worker 并检查 `systemctl status`、`journalctl` 和 HTTP 健康端点。失败时切回上一完整目录并重启服务；生产配置不随版本切换覆盖。
|
||||
|
||||
项目部署流程禁止连接或读取生产数据库做开发验证。数据库备份属于独立运维职责，应用回退不得删除或覆盖数据。
|
||||
|
||||
RocketMQ 由运维独立维护 NameServer、Broker 和需要时的 Proxy。应用发布只读取受控的 RocketMQ Endpoint、Topic 前缀与 Group 配置，不负责创建或升级集群，也不得把 Broker 数据目录放进应用发布目录。
|
||||
@@ -23,7 +23,7 @@
|
||||
## 非目标
|
||||
|
||||
- 不做自选股、持仓、笔记、交易计划、社区、荐股、跟单和公开组合。
|
||||
- 本切片不接正式行情源、RabbitMQ、MySQL、Redis和付费 AI。
|
||||
- 本切片不接正式行情源、RocketMQ、MySQL、Redis和付费 AI。
|
||||
- 本切片不实现用户、邀请、会员、订阅和支付。
|
||||
- ETF监控、两融数据、大盘云图和实时消息仍是独立一级模块。
|
||||
|
||||
|
||||
@@ -0,0 +1,9 @@
|
||||
# GitNexus 开发后结果
|
||||
|
||||
- 执行：`npx gitnexus analyze`。
|
||||
- 工作区索引：620 个节点、651 条关系、7 个集群、0 条执行流程。
|
||||
- 增量分析：7 个已修改文件、25 个新增文件、0 个删除文件。
|
||||
- 最终索引提交：`9203fdd`。
|
||||
- 状态：up-to-date。
|
||||
|
||||
实现提交后再次分析，索引已锚定最终提交。
|
||||
@@ -0,0 +1,10 @@
|
||||
# GitNexus 前后对比
|
||||
|
||||
| 项目 | 开发前 | 开发后工作区 | 变化 |
|
||||
|---|---:|---:|---:|
|
||||
| 节点 | 452 | 620 | +168 |
|
||||
| 关系 | 477 | 651 | +174 |
|
||||
| 集群 | 5 | 7 | +2 |
|
||||
| 执行流程 | 0 | 0 | 0 |
|
||||
|
||||
新增集群来自环境模板与部署文档边界；没有生产执行流程变化，符合影响预估。最终索引锚定实现提交 `9203fdd`。
|
||||
@@ -0,0 +1,8 @@
|
||||
# GitNexus 变更检测
|
||||
|
||||
- 命令：`npx gitnexus detect-changes --repo a-share-analysis --scope staged`。
|
||||
- 最终暂存区：43 个文件、77 个符号。
|
||||
- 受影响流程：0。
|
||||
- 风险等级：低。
|
||||
|
||||
范围包含配置模板、Compose、systemd、Nginx、部署文档、现行治理入口、契约测试和 GOV-006 档案。
|
||||
@@ -0,0 +1,7 @@
|
||||
# GitNexus 开发前影响分析
|
||||
|
||||
- 查询主题：`development production environment templates Docker Compose Ubuntu source deployment systemd`。
|
||||
- 关联范围：README、开发流程、开发规范、系统架构、GOV-005 和部署目录。
|
||||
- 本次新增配置、文档和静态测试，不修改既有生产函数、类或方法，无生产符号上游影响目标。
|
||||
- GitNexus 未识别业务执行流程；预计影响限于配置契约、部署边界和治理测试。
|
||||
- 风险控制：不提交真实秘密，不运行应用部署，不连接任何生产服务，明确示例骨架的未验证状态。
|
||||
@@ -0,0 +1,129 @@
|
||||
# 开发、生产环境与双部署方式实施计划
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** 建立可机器验证的开发/生产环境变量契约、本地 Redis Compose，以及 Docker Compose 与 Ubuntu 源码生产部署规范和配置骨架。
|
||||
|
||||
**Architecture:** 八份 env 模板按进程和环境分离，但同一进程在 development/production 使用相同变量名。静态契约测试负责检查模板完整性、敏感值为空、Web 仅暴露 `VITE_*`、生产安全默认值和部署文件边界；当前应用尚未实现，不伪造可运行的应用镜像或启动命令。
|
||||
|
||||
**Tech Stack:** dotenv 模板、Docker Compose、Redis、systemd、Nginx、Node.js 内置测试运行器、Markdown、GitNexus。
|
||||
|
||||
## Global Constraints
|
||||
|
||||
- 环境仅定义 `development` 与 `production`，生产禁止模拟数据、热更新和开发默认值回退。
|
||||
- 仓库提交八份 `*.env.example`，不提交任何真实 `.env` 或凭据。
|
||||
- 本地 Compose 只启动 Redis；Web/API/Scheduler/Worker 从源码运行。
|
||||
- 生产支持 Docker Compose 和 Ubuntu 22.04/24.04 x86_64 源码部署。
|
||||
- Node.js 22 LTS、pnpm 10、Nginx 和基础设施由管理员提供，项目只验证不安装。
|
||||
- 源码部署使用 `a-share` 用户和 `/etc/a-share-analysis/*.env`。
|
||||
- MySQL 与 RabbitMQ 第一阶段默认关闭；MySQL 条件配置遵守 GOV-005。
|
||||
|
||||
---
|
||||
|
||||
### Task 1: 建立失败的环境配置契约测试
|
||||
|
||||
**Files:**
|
||||
- Create: `tools/governance/environment-baseline.test.mjs`
|
||||
- Modify: `package.json`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: `deploy/env/`、`deploy/compose/`、`deploy/systemd/`、`deploy/nginx/` 和 `docs/deployment/`。
|
||||
- Produces: `npm run test:environment-baseline`。
|
||||
|
||||
- [ ] **Step 1: 编写模板和部署边界测试**
|
||||
|
||||
测试八份模板存在、同一进程两环境键集合相同、敏感键为空、Web 仅含 `VITE_*`、生产安全开关正确、本地 Compose 仅定义 Redis，并检查 systemd/Nginx 与两份生产部署文档。
|
||||
|
||||
- [ ] **Step 2: 验证测试因文件缺失而失败**
|
||||
|
||||
运行：`npm run test:environment-baseline`
|
||||
|
||||
预期：失败明确指出第一份缺少的环境模板或部署文件。
|
||||
|
||||
### Task 2: 实现统一环境模板
|
||||
|
||||
**Files:**
|
||||
- Create: `deploy/env/development/api.env.example`
|
||||
- Create: `deploy/env/development/scheduler.env.example`
|
||||
- Create: `deploy/env/development/worker.env.example`
|
||||
- Create: `deploy/env/development/web.env.example`
|
||||
- Create: `deploy/env/production/api.env.example`
|
||||
- Create: `deploy/env/production/scheduler.env.example`
|
||||
- Create: `deploy/env/production/worker.env.example`
|
||||
- Create: `deploy/env/production/web.env.example`
|
||||
- Modify: `.gitignore`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: GOV-006 设计中的变量作用域。
|
||||
- Produces: 后续 NestJS Schema 和部署方式共同使用的变量名契约。
|
||||
|
||||
- [ ] **Step 1: 编写四类进程模板**
|
||||
|
||||
每项变量附中文说明；敏感变量保持空值；MySQL/RabbitMQ/AI 由功能开关控制条件必填；生产值拒绝模拟数据和调试模式。
|
||||
|
||||
- [ ] **Step 2: 加固忽略规则**
|
||||
|
||||
只允许提交 `*.env.example`，忽略 `*.env.local`、真实 env 和本地运行目录。
|
||||
|
||||
### Task 3: 实现本地 Redis 与生产部署骨架
|
||||
|
||||
**Files:**
|
||||
- Create: `deploy/compose/development.yml`
|
||||
- Create: `deploy/compose/production.yml.example`
|
||||
- Create: `deploy/systemd/a-share-api.service.example`
|
||||
- Create: `deploy/systemd/a-share-scheduler.service.example`
|
||||
- Create: `deploy/systemd/a-share-worker.service.example`
|
||||
- Create: `deploy/nginx/a-share-analysis.conf.example`
|
||||
- Create: `docs/deployment/local-development.md`
|
||||
- Create: `docs/deployment/docker-compose-production.md`
|
||||
- Create: `docs/deployment/ubuntu-source-production.md`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: Task 2 的模板键集合。
|
||||
- Produces: 本地 Redis 启动入口、生产 Compose 配置边界、systemd EnvironmentFile 和 Nginx 代理示例。
|
||||
|
||||
- [ ] **Step 1: 配置本地 Redis Compose**
|
||||
|
||||
固定 Redis 镜像补丁版本，只暴露本机端口，使用项目专用容器名、网络、健康检查和仓库外本地数据目录；不得定义其他服务。
|
||||
|
||||
- [ ] **Step 2: 配置生产部署骨架**
|
||||
|
||||
生产 Compose 只表达应用服务的配置契约和不可变镜像要求；systemd 使用独立 EnvironmentFile，Nginx 托管静态文件并代理 `/api/`。
|
||||
|
||||
- [ ] **Step 3: 编写开发与双生产部署文档**
|
||||
|
||||
明确当前应用尚未脚手架化，文档只验证配置与部署边界；列出管理员前置条件、版本检查、健康检查、升级和回退规则。
|
||||
|
||||
- [ ] **Step 4: 验证测试转绿**
|
||||
|
||||
运行：`npm run test:environment-baseline && npm run test:mysql-baseline && npm run test:governance`
|
||||
|
||||
预期：全部通过。Docker 可用时额外运行 `docker compose -f deploy/compose/development.yml config`。
|
||||
|
||||
### Task 4: 完成现行规范、追溯与发布
|
||||
|
||||
**Files:**
|
||||
- Modify: `docs/architecture/system-architecture.md`
|
||||
- Modify: `docs/governance/code-development-standards.md`
|
||||
- Modify: `docs/governance/development-workflow.md`
|
||||
- Modify: `README.md`
|
||||
- Modify: `docs/index.md`
|
||||
- Modify: `CHANGELOG.md`
|
||||
- Modify: `VERSION`
|
||||
- Create: GOV-006 除现有 `design.md`、`implementation-plan.md`、`gitnexus/before.md` 外的全部必备档案。
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: 通过契约测试的配置与部署文件。
|
||||
- Produces: 可审查、可发布、可回退的 GOV-006 完整档案和 `v0.0.5`。
|
||||
|
||||
- [ ] **Step 1: 更新架构和开发规范**
|
||||
|
||||
记录环境模型、配置校验、两种部署方式、平台范围、管理员职责和生产防误用要求。
|
||||
|
||||
- [ ] **Step 2: 执行 GitNexus、测试和双 Review**
|
||||
|
||||
检测完整暂存区并运行 `npm run governance:finish -- GOV-006 environment-deployment-baseline`。
|
||||
|
||||
- [ ] **Step 3: 中文提交、推送与发布**
|
||||
|
||||
提交并推送 `main`；封存后创建带注释 `v0.0.5`，精确推送并核对分支与标签。
|
||||
@@ -0,0 +1,17 @@
|
||||
id: GOV-006
|
||||
name: 开发、生产环境与双部署方式
|
||||
slug: environment-deployment-baseline
|
||||
status: released
|
||||
owner: project
|
||||
created_at: 2026-08-13
|
||||
prd: prd.md
|
||||
requirements: requirements.md
|
||||
design: design.md
|
||||
implementation_plan: implementation-plan.md
|
||||
gitnexus_before: gitnexus/before.md
|
||||
gitnexus_after: gitnexus/after.md
|
||||
gitnexus_comparison: gitnexus/comparison.md
|
||||
code_review: review/code-review.md
|
||||
standards_review: review/standards-review.md
|
||||
implementation_commit: 9203fdd
|
||||
release: v0.0.5
|
||||
@@ -0,0 +1,31 @@
|
||||
# 开发、生产环境与双部署方式 PRD
|
||||
|
||||
- 功能编号：GOV-006
|
||||
- PRD 版本：0.1
|
||||
- 状态：approved
|
||||
- 日期：2026-08-13
|
||||
|
||||
## 问题
|
||||
|
||||
项目缺少开发/生产配置契约和部署边界，存在真实配置入库、生产误用模拟数据及两种部署方式行为漂移的风险。
|
||||
|
||||
## 目标
|
||||
|
||||
- 提供开发和生产的四类进程无秘密模板。
|
||||
- 本地只用 Compose 启动 Redis，应用从源码运行。
|
||||
- 同时规范 Docker Compose 与 Ubuntu 源码生产部署。
|
||||
- 生产配置严格校验且不随发布版本覆盖。
|
||||
|
||||
## 非目标
|
||||
|
||||
- 不安装服务器运行时或基础设施。
|
||||
- 不声称尚未实现的应用镜像、进程和健康端点已经可运行。
|
||||
- 不启用 MySQL、RabbitMQ、正式数据源或 AI。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- 八份模板完整、跨环境键一致且无敏感值。
|
||||
- Web 模板只含公开 `VITE_*` 变量。
|
||||
- 开发 Compose 仅定义 Redis并可通过配置解析。
|
||||
- systemd、Nginx 和三份部署文档满足已确认平台与路径边界。
|
||||
- 环境契约测试完成红绿验证，双 Review 和治理门禁通过。
|
||||
@@ -0,0 +1,16 @@
|
||||
# 测试结果
|
||||
|
||||
## 测试先行证据
|
||||
|
||||
新增环境基线测试后首次运行 6 个测试全部失败，分别指出八份模板、开发 Compose、systemd/Nginx 示例和部署文档不存在。
|
||||
|
||||
补齐最小实现后：
|
||||
|
||||
- 环境基线测试：6 个通过，0 个失败。
|
||||
- MySQL 基线测试：2 个通过，0 个失败。
|
||||
- 治理测试：5 个通过，0 个失败。
|
||||
- `docker compose -f deploy/compose/development.yml config`：通过，仅包含 Redis。
|
||||
- `git diff --check`：通过。
|
||||
- GitNexus 最终暂存区：43 个文件、77 个符号、0 条流程，风险为低。
|
||||
|
||||
生产 Compose 和源码部署当前属于配置契约骨架，应用尚未脚手架化，因此没有伪造生产启动或健康检查成功证据。
|
||||
@@ -0,0 +1,3 @@
|
||||
# 视觉验证
|
||||
|
||||
本功能没有页面或交互变化，视觉验证不适用。
|
||||
@@ -0,0 +1,9 @@
|
||||
# 发布说明
|
||||
|
||||
## v0.0.5
|
||||
|
||||
- 实现提交：`9203fdd`。
|
||||
- 新增八份开发/生产无秘密环境模板。
|
||||
- 新增只启动 Redis 的本地开发 Compose。
|
||||
- 新增生产 Compose 契约骨架、systemd/Nginx 示例和 Ubuntu 源码部署规范。
|
||||
- 新增环境配置自动化契约测试。
|
||||
@@ -0,0 +1,10 @@
|
||||
# 工程需求
|
||||
|
||||
- 环境只定义 `development` 与 `production`。
|
||||
- API、Scheduler、Worker、Web 分别提供开发/生产模板，同进程键集合一致。
|
||||
- 敏感变量保持空值，真实配置被 Git 忽略。
|
||||
- 生产 Worker 固定 `MARKET_DATA_MODE=live`，第一阶段关闭 MySQL 与 RabbitMQ。
|
||||
- 本地 Compose 固定 Redis 补丁版本、仅绑定本机并提供健康检查。
|
||||
- Ubuntu 源码部署支持 22.04/24.04 LTS x86_64、Node.js 22 LTS、pnpm 10。
|
||||
- systemd 使用 `a-share` 用户及独立 `EnvironmentFile`；Nginx 托管静态文件并代理 API。
|
||||
- 生产 Compose 使用不可变镜像和外部 env，不承诺当前骨架可直接上线。
|
||||
@@ -0,0 +1,27 @@
|
||||
# 配置与文档 Review
|
||||
|
||||
- reviewer_type：self
|
||||
- reviewer：Codex
|
||||
- 基线提交：`0328f9e`
|
||||
- 设计提交：`fa1df71`
|
||||
- 实现提交：`9203fdd`
|
||||
- 日期：2026-08-13
|
||||
|
||||
## 审查结论
|
||||
|
||||
八份模板保持跨环境键一致，敏感值为空，Web 只含公开变量；开发 Compose 只启动 Redis；生产部署示例明确为未验证骨架。现行架构和规范覆盖启动校验、防误用与管理员职责。
|
||||
|
||||
## 发现与处置
|
||||
|
||||
| 严重程度 | 发现 | 处置 |
|
||||
|---|---|---|
|
||||
| Important | 两种部署方式可能形成不同变量协议 | 强制复用同一模板键并用自动测试比较 |
|
||||
| Important | 示例容易被误认为可直接上线 | Compose 和文档显式标记需在应用脚手架后验证 |
|
||||
| Important | 前端变量可能泄露服务端秘密 | 测试要求 Web 模板每个键都以 `VITE_` 开头且只含公开值 |
|
||||
| Minor | 本地 Redis 数据可能进入仓库 | 使用 `.local/redis` 并加固忽略规则 |
|
||||
|
||||
- 环境契约测试 6/6、MySQL 基线 2/2、治理测试 5/5 通过。
|
||||
- Docker Compose 配置解析成功且只包含 Redis。
|
||||
- GitNexus 最终暂存区检测为 43 个文件、77 个符号、0 条流程、低风险。
|
||||
|
||||
最终结论：passed
|
||||
@@ -0,0 +1,21 @@
|
||||
# 开发规范符合性 Review
|
||||
|
||||
- reviewer_type：self
|
||||
- reviewer：Codex
|
||||
- 实现提交：`9203fdd`
|
||||
- 日期：2026-08-13
|
||||
|
||||
## 检查结果
|
||||
|
||||
- [x] 设计经用户确认后实施。
|
||||
- [x] 环境契约先有 6 个失败测试，再补实现使其通过。
|
||||
- [x] 模板无真实秘密，真实 env 与本地数据被忽略。
|
||||
- [x] 不连接或探测生产服务，不安装服务器软件。
|
||||
- [x] MySQL 变量符合 GOV-005，第一阶段默认关闭。
|
||||
- [x] Docker Compose 与源码部署共享变量契约。
|
||||
- [x] 未把尚未实现的应用描述为已可部署。
|
||||
- [x] 无界面变化，视觉验证合理标记不适用。
|
||||
|
||||
没有未解决的 Critical 或 Important 不符合项。
|
||||
|
||||
最终结论：passed
|
||||
@@ -0,0 +1,5 @@
|
||||
# 回退说明
|
||||
|
||||
本功能没有部署应用或连接生产服务。若配置规范需要修正，使用新的中文修复提交更新模板、文档和测试，不移动共享标签。
|
||||
|
||||
开发 Redis 数据位于被忽略的 `.local/redis/`，版本回退不得自动删除该目录。生产真实 env 位于仓库外，不随应用版本切换覆盖。
|
||||
@@ -0,0 +1,8 @@
|
||||
# 测试计划
|
||||
|
||||
- 先运行环境基线测试，证明六类行为因模板和部署文件缺失而失败。
|
||||
- 实现后要求环境测试 6/6、MySQL 基线 2/2、治理测试 5/5 通过。
|
||||
- 运行 Docker Compose 配置解析，确认只有 Redis。
|
||||
- 运行 `git diff --check`、敏感信息扫描和 GitNexus 最终暂存区检测。
|
||||
- 运行 `npm run governance:finish -- GOV-006 environment-deployment-baseline`。
|
||||
- 本功能无页面变化，视觉验证不适用。
|
||||
@@ -0,0 +1,143 @@
|
||||
# 开发数据库 Schema 基线与版本门禁设计规格
|
||||
|
||||
- 功能编号：GOV-007
|
||||
- 规格版本：0.1
|
||||
- 状态：approved_for_review
|
||||
- 日期：2026-08-13
|
||||
|
||||
## 背景与目标
|
||||
|
||||
数据库正式启用后，每个新应用版本开始开发前都需要一份可审计的结构起点。只保存迁移脚本不能证明开发数据库在版本开始时的真实结构，也无法发现手工改表造成的漂移。
|
||||
|
||||
本功能建立强制门禁：开始开发下一个语义化版本前，从开发环境数据库导出当前已发布版本的完整 Schema，规范化、校验并纳入 Git。开发流程和脚本禁止连接、读取或探测生产数据库。
|
||||
|
||||
## 版本与命名
|
||||
|
||||
基线按“被备份的当前已发布版本”命名，而不是即将开发的版本。例如开始开发 `v0.0.6` 前，封存 `v0.0.5` 状态：
|
||||
|
||||
```text
|
||||
database/schema-baselines/v0.0.5/
|
||||
├── schema.sql
|
||||
├── manifest.yaml
|
||||
└── checksum.sha256
|
||||
```
|
||||
|
||||
每个应用版本开始前都生成一次。即使 Schema 未变化，也生成新版本目录，以相同内容校验值证明没有结构漂移。
|
||||
|
||||
## 唯一允许的数据来源
|
||||
|
||||
- 只允许读取开发环境数据库。
|
||||
- 加载开发专用本地配置，要求 `APP_ENV=development`。
|
||||
- 数据库名固定为 `a_share_analysis_dev`；名称不匹配立即终止。
|
||||
- 启用真实导出时主机必须为 `127.0.0.1`、`localhost` 或 `::1`；远程开发库必须先通过运维建立本地 SSH 隧道，脚本不接受任意远程目标。
|
||||
- 禁止通过命令参数覆盖环境类型、数据库名或传入任意 env 文件路径。
|
||||
- 禁止连接、读取、探测或导出生产数据库；生产备份属于独立运维流程，不进入开发门禁。
|
||||
- 推荐使用只拥有开发库结构读取和例程查看权限的专用账号，不授予生产访问能力。
|
||||
|
||||
即使主机名看似本地，脚本也必须验证环境和数据库名；不能只依赖地址白名单判断安全。
|
||||
|
||||
## 导出范围
|
||||
|
||||
使用 MySQL 5.7 客户端 `mysqldump`，仅导出结构，不包含任何表数据。基线必须完整包含：
|
||||
|
||||
- 数据库表、列、主键、索引、外键与表选项。
|
||||
- 视图。
|
||||
- 触发器。
|
||||
- 存储过程和函数。
|
||||
- Event Scheduler 事件。
|
||||
|
||||
导出命令必须使用 `--no-data --routines --triggers --events`，并使用符合 MySQL 5.7 的选项。执行元数据查询的 `mysql` 客户端和执行导出的 `mysqldump` 客户端必须分别验证为 5.7.x。账号凭据通过开发 env 或受控客户端配置提供，禁止出现在命令参数、日志或清单中。
|
||||
|
||||
## 规范化
|
||||
|
||||
原始 `mysqldump` 输出经过确定性规范化后才能进入 Git：
|
||||
|
||||
- 删除导出时间、完成时间、客户端路径等不稳定注释。
|
||||
- 删除或规范化环境绑定的 `DEFINER`，避免恢复时绑定个人账号。
|
||||
- 删除由数据增长产生的 `AUTO_INCREMENT=<当前值>`，保留列的自增属性。
|
||||
- 统一换行符与文件末尾换行。
|
||||
- 禁止把主机、端口、账号、密码或客户端配置路径写入 SQL。
|
||||
- 不改变表、视图、触发器、例程和事件的业务定义。
|
||||
|
||||
规范化工具必须通过固定输入/输出测试证明不会误删业务 SQL。
|
||||
|
||||
## 校验与清单
|
||||
|
||||
`manifest.yaml` 至少记录：
|
||||
|
||||
- `application_version`：被备份的已发布版本。
|
||||
- `git_commit`：该版本标签最终指向的提交。
|
||||
- `source_environment: development`。
|
||||
- `database_name: a_share_analysis_dev`。
|
||||
- MySQL 客户端和服务端精确版本。
|
||||
- `charset: utf8mb4`。
|
||||
- `collation: utf8mb4_general_ci`。
|
||||
- 生成时间与生成工具版本。
|
||||
- 是否包含表、视图、触发器、例程和事件。
|
||||
- 规范化 SQL 的 SHA-256。
|
||||
|
||||
`checksum.sha256` 使用标准格式记录 `schema.sql` 校验值。流程必须重新计算并验证清单、校验文件和实际 SQL 三者一致。
|
||||
|
||||
## 强制阻断条件
|
||||
|
||||
出现以下任一情况，不允许进入下一版本开发：
|
||||
|
||||
- 当前已发布版本没有 Schema 基线，且数据库已启用。
|
||||
- `APP_ENV` 不是 `development`。
|
||||
- 数据库名不是 `a_share_analysis_dev`。
|
||||
- 检测到生产配置文件、生产环境标识或禁止的连接目标。
|
||||
- MySQL 客户端或服务端不是 5.7.x。
|
||||
- 字符集或排序规则不是 `utf8mb4` / `utf8mb4_general_ci`。
|
||||
- 导出缺少视图、触发器、存储过程/函数或事件的范围声明。
|
||||
- SQL 包含 `DEFINER`、不稳定导出注释、当前 AUTO_INCREMENT 值或疑似凭据。
|
||||
- 校验值不一致、目标版本目录已存在且内容不同，或 Git 工作区存在无法解释的 Schema 改动。
|
||||
|
||||
禁止覆盖既有版本基线。需要修正时新增带原因的治理记录和修复提交，不静默重写已发布事实。`schema:verify` 是本地内容校验；`governance:start` 还要求基线文件已被 Git 跟踪、工作区无改动、当前分支已推送以及远程发布标签仍指向清单提交。
|
||||
|
||||
## 首次启用与未启用状态
|
||||
|
||||
当前 MySQL 尚未启用，因此在开发新版本前允许记录结构备份“不适用”，但必须能证明功能开关为关闭，且不得创建伪造的空 `schema.sql` 冒充数据库基线。
|
||||
|
||||
首次启用 MySQL 的版本必须：
|
||||
|
||||
1. 通过迁移创建开发库初始结构。
|
||||
2. 在 MySQL 5.7 开发环境验证字符集与排序规则。
|
||||
3. 发布时建立首份真实 Schema 基线。
|
||||
4. 后续每个版本开始前严格执行本门禁。
|
||||
|
||||
## 开发流程位置
|
||||
|
||||
下一版本开发前顺序为：
|
||||
|
||||
1. 确认当前已发布版本和标签提交。
|
||||
2. 判断 MySQL 功能开关；未启用则保存可验证的不适用记录。
|
||||
3. 已启用时从开发数据库导出、规范化并校验完整 Schema。
|
||||
4. 将当前发布版本基线作为独立中文提交推送 Gitea。
|
||||
5. 确认工作区干净和远程同步成功。
|
||||
6. 再创建下一版本 PRD、设计与功能档案，执行 GitNexus 开发前分析。
|
||||
|
||||
数据库迁移必须从上一基线在 MySQL 5.7 开发环境正向执行验证。禁止直接修改共享开发表代替迁移脚本。
|
||||
|
||||
## 安全边界
|
||||
|
||||
- Schema 基线只含结构，不含业务数据、账号数据或生产数据。
|
||||
- 导出脚本不得回显秘密，也不得接受密码命令行参数。
|
||||
- 开发工具和代理无权使用生产 env 或生产数据库验证功能。
|
||||
- 基线提交前扫描疑似凭据、生产主机、`DEFINER` 和数据 INSERT。
|
||||
- Schema 基线进入 Git 后视为公开给仓库使用者，任何敏感对象名称或注释都应在数据库设计阶段避免。
|
||||
|
||||
## 实施范围
|
||||
|
||||
GOV-007 将实现数据库目录规范、开发 env 模板扩展、确定性 SQL 规范化工具、导出/校验脚本、自动化测试、开发流程门禁和完整追溯档案。由于当前 MySQL 未启用，本功能只验证阻断逻辑、规范化固定样本和“不适用”路径，不连接任何数据库。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- 开发流程明确每个应用版本开始前建立上一已发布版本的开发库 Schema 基线。
|
||||
- 脚本只接受 `development` 和固定开发库名，无法通过普通参数切换到生产配置。
|
||||
- 导出范围包含表、视图、触发器、存储过程/函数和事件且不含数据。
|
||||
- 规范化稳定移除时间注释、`DEFINER` 和当前 AUTO_INCREMENT 值，但保留业务 SQL。
|
||||
- 清单和 SHA-256 格式可自动校验。
|
||||
- MySQL 5.7、`utf8mb4`、`utf8mb4_general_ci` 不符合时阻断。
|
||||
- 当前未启用 MySQL 时使用可验证“不适用”记录，不伪造空 Schema。
|
||||
- 自动化测试、治理门禁、GitNexus 和双 Review 通过。
|
||||
- 中文提交和对应版本标签精确推送 Gitea。
|
||||
@@ -0,0 +1,30 @@
|
||||
# GitNexus 开发后基线
|
||||
|
||||
## GitNexus 状态
|
||||
|
||||
```text
|
||||
Repository: /Users/citrons/Documents/Codex/2026-08-12/wo-x/a-share-analysis
|
||||
Indexed: 8/13/2026, 1:13:21 PM
|
||||
Indexed commit: d827bfa
|
||||
Current commit: d827bfa
|
||||
Status: ✅ up-to-date
|
||||
```
|
||||
|
||||
## 最终实现
|
||||
|
||||
```text
|
||||
d827bfadb1fc0a7d768eefbf87b46ba26ac612d6
|
||||
fix(GOV-007): 收紧 Schema 基线安全门禁
|
||||
```
|
||||
|
||||
该提交已推送到 `origin/main`，实时远程查询结果与本地提交一致。
|
||||
|
||||
## 实现范围摘要
|
||||
|
||||
```text
|
||||
30 files changed, 1835 insertions(+), 18 deletions(-)
|
||||
```
|
||||
|
||||
最终索引为 879 节点、1062 关系、23 条流程。新增流程集中在 Schema
|
||||
生成、校验、N/A 运行时一致性和发布门禁，不包含市场业务、HTTP、RabbitMQ
|
||||
或生产数据库流程。
|
||||
@@ -0,0 +1,26 @@
|
||||
# GitNexus 开发前基线
|
||||
|
||||
- 功能编号：GOV-007
|
||||
- 记录时间：2026年8月13日 GMT+8 10:58:35
|
||||
- 分支：main
|
||||
- 基线提交：0a69aa1d43f4
|
||||
|
||||
## 工作区
|
||||
|
||||
```text
|
||||
(干净)
|
||||
```
|
||||
|
||||
## GitNexus 状态
|
||||
|
||||
```text
|
||||
Repository: /Users/citrons/Documents/Codex/2026-08-12/wo-x/a-share-analysis
|
||||
Indexed: 8/13/2026, 10:58:34 AM
|
||||
Indexed commit: 0a69aa1
|
||||
Current commit: 0a69aa1
|
||||
Status: ✅ up-to-date
|
||||
```
|
||||
|
||||
## 后续人工分析
|
||||
|
||||
在修改代码前，将 GitNexus query、context、impact 的结论写入 `gitnexus/impact-plan.md`。高风险结果必须先获得用户确认。
|
||||
@@ -0,0 +1,18 @@
|
||||
# GitNexus 前后对比
|
||||
|
||||
## 开发前
|
||||
|
||||
- 基线提交：`e552b979b61342b9e3a47d463f0b9a821b0ad95d`
|
||||
- 索引：641 节点、671 关系、0 流程。
|
||||
- 影响：现有治理档案函数总体 LOW，无数据库 Schema 执行流。
|
||||
|
||||
## 开发后
|
||||
|
||||
- N/A 基线提交：`2c502ebbec25e45ac2980c08ed288ace194b7a04`，已独立推送。
|
||||
- 最终实现提交：`d827bfadb1fc0a7d768eefbf87b46ba26ac612d6`，已推送 `origin/main`。
|
||||
- 索引：879 节点、1062 关系、23 条流程，状态 up-to-date。
|
||||
- 最终修复变更检测为 HIGH，涉及 13 条 Schema 生成、验证与治理门禁流程。
|
||||
|
||||
## 结论
|
||||
|
||||
新增关系和流程全部来自 GOV-007 Schema 安全门禁及其测试，没有引入市场业务、HTTP、RabbitMQ 或页面流程。风险提升是因为 `schema:verify` 和 `governance:start` 属于关键开发路径；对应流程已用红绿测试、23 项 Schema 回归、远程实测和独立终审覆盖。
|
||||
@@ -0,0 +1,25 @@
|
||||
# GitNexus 暂存区变更检测
|
||||
|
||||
- 检测日期：2026-08-13
|
||||
- 检测范围：最终实现提交前的 unstaged 修复
|
||||
- 变更文件：3
|
||||
- 变更符号：17
|
||||
- 受影响流程：13
|
||||
- GitNexus 风险：high（已按关键门禁完成专项验证）
|
||||
|
||||
## 受影响流程
|
||||
|
||||
变更集中在数据库 Schema 治理模块：
|
||||
|
||||
- Schema 生成、规范化与敏感/数据写入扫描。
|
||||
- 清单、SHA-256 与目录文件集合验证。
|
||||
- MySQL 5.7 双客户端、服务端和字符规则验证。
|
||||
- 当前发布版本本地校验。
|
||||
- N/A 基线与当前固定开发环境开关的一致性校验。
|
||||
- 顶层数据修改/装载、疑似凭据、连接串和生产主机扫描。
|
||||
- 已提交、已推送、远程分支和远程标签严格校验。
|
||||
- CLI 生成/验证和 `governance:start` 入口。
|
||||
|
||||
## 风险解释
|
||||
|
||||
GitNexus 的 HIGH 结论来自安全扫描和 N/A 校验位于 13 条生成、验证及治理门禁流程，而非发现市场业务、生产数据库或跨服务回归。该风险已用 23 项 Schema 行为测试、既有 13 项治理回归测试、真实 Gitea `ls-remote` 校验和独立最终 Review 覆盖。最终 Review 无未关闭问题。
|
||||
@@ -0,0 +1,32 @@
|
||||
# GitNexus 开发前影响分析
|
||||
|
||||
- 分析日期：2026-08-13
|
||||
- 基线提交：`e552b979b61342b9e3a47d463f0b9a821b0ad95d`
|
||||
- 索引状态：up-to-date
|
||||
|
||||
## 查询范围
|
||||
|
||||
围绕 `governance start development gate feature record database schema baseline` 查询现有治理入口。GitNexus 未识别出业务执行流，相关定义集中在：
|
||||
|
||||
- `tools/governance/start.mjs`
|
||||
- `tools/governance/finish.mjs`
|
||||
- `tools/governance/feature-record.mjs`
|
||||
- `tools/governance/feature-record.test.mjs`
|
||||
- `package.json`
|
||||
- 治理规范和 GOV-007 设计档案
|
||||
|
||||
## 符号影响
|
||||
|
||||
- `getFeatureDirectory`：LOW；3 个直接依赖，分别是 start、finish 和治理测试；0 个执行流、0 个跨模块影响。
|
||||
- `validateFeatureId`：LOW；GitNexus 没有发现上游执行流，实际文本导入由 start、finish 和测试覆盖。
|
||||
- `getRequiredFeatureFiles`：LOW；没有识别到执行流，完成门禁由现有自动化测试保护。
|
||||
|
||||
## 实施边界
|
||||
|
||||
本功能不修改上述已有公共函数语义。Schema 逻辑新增为独立模块，只让 `start.mjs` 调用一个只读的“当前已发布版本基线有效”入口。生成、规范化和写入由独立命令负责，因此不会让一般功能档案解析承担数据库职责。
|
||||
|
||||
## 风险结论
|
||||
|
||||
总体风险：LOW。
|
||||
|
||||
没有 HIGH 或 CRITICAL 结果，不需要额外中止确认。主要回归面是治理开始命令可能因缺少上一版本基线被有意阻断；通过 N/A 与真实 Schema 两类测试、既有治理回归测试和命令级验证覆盖。
|
||||
@@ -0,0 +1,124 @@
|
||||
# GOV-007 开发数据库 Schema 基线与版本门禁实施计划
|
||||
|
||||
> **执行要求：** 按测试驱动方式逐项实施；每个行为先观察失败，再写最小实现。实施期间不得连接、探测或读取任何数据库，真实导出入口仅通过固定样本和依赖注入验证。
|
||||
|
||||
**目标：** 建立只允许读取固定开发库、可确定性规范化和校验完整 MySQL 5.7 Schema，并在下一版本开发前强制验证上一已发布版本基线的治理门禁。
|
||||
|
||||
**架构：** `tools/database/schema-baseline.mjs` 集中维护安全配置、命令构造、SQL 规范化、产物生成及校验，避免将一条连续的安全流程过度拆分。`governance:start` 只调用“当前已发布版本基线是否存在且有效”的纯门禁，不负责静默生成或覆盖产物；生成基线必须先由独立命令完成、提交并推送。
|
||||
|
||||
**技术栈：** Node.js 22 LTS、Node 内置测试运行器、MySQL 5.7 `mysql`/`mysqldump` 客户端、SHA-256、GitNexus、Git/Gitea。
|
||||
|
||||
## 全局约束
|
||||
|
||||
- 数据来源只能是 `APP_ENV=development`、数据库 `a_share_analysis_dev`。
|
||||
- MySQL 客户端与服务端只能是 5.7.x，字符集固定 `utf8mb4`，排序规则固定 `utf8mb4_general_ci`。
|
||||
- 导出必须包含 `--no-data --routines --triggers --events`，密码不得出现在参数、日志、SQL 或清单中。
|
||||
- 不接受环境类型、数据库名或 env 路径的命令行覆盖。
|
||||
- 当前 MySQL 未启用，不运行真实数据库命令，只生成可验证的 `not_applicable` 清单，且不创建空 `schema.sql`。
|
||||
- 已存在版本目录不得静默覆盖；真实 Schema 只含结构，不含任何数据。
|
||||
- 修改关键符号前执行 GitNexus impact，提交前执行 GitNexus detect-changes。
|
||||
|
||||
---
|
||||
|
||||
### 任务 1：锁定安全边界和可观察契约
|
||||
|
||||
**文件：**
|
||||
|
||||
- 新建：`tools/database/schema-baseline.test.mjs`
|
||||
- 新建：`tools/database/fixtures/mysql57-schema-input.sql`
|
||||
- 新建：`tools/database/fixtures/mysql57-schema-expected.sql`
|
||||
- 新建：`docs/features/GOV-007-development-schema-baseline/test-plan.md`
|
||||
|
||||
**接口：**
|
||||
|
||||
- 消费：设计规格中固定的环境、版本、Schema 范围和禁止覆盖规则。
|
||||
- 产出：后续实现必须满足的公开函数行为和固定 SQL 输入/输出。
|
||||
|
||||
- [x] 编写配置测试，分别证明非 `development`、非 `a_share_analysis_dev`、非 MySQL 5.7、错误字符集和错误排序规则被拒绝。
|
||||
- [x] 运行 `node --test tools/database/schema-baseline.test.mjs`，确认因实现模块不存在而失败。
|
||||
- [x] 编写命令构造测试，手工断言参数包含 `--no-data`、`--routines`、`--triggers`、`--events`，且密码字符串不出现在参数中。
|
||||
- [x] 编写固定 SQL 样本测试，手工断言时间注释、`DEFINER` 和表级当前自增值被删除，列级 `AUTO_INCREMENT` 以及表、视图、触发器、例程和事件定义完整保留。
|
||||
- [x] 编写产物测试，证明清单和校验文件的 SHA-256 与 SQL 一致、不同内容的既有目录被拒绝、未启用 MySQL 时只有 `manifest.yaml` 而没有 `schema.sql`。
|
||||
|
||||
### 任务 2：实现纯函数和文件产物
|
||||
|
||||
**文件：**
|
||||
|
||||
- 新建：`tools/database/schema-baseline.mjs`
|
||||
- 修改：`package.json`
|
||||
|
||||
**接口：**
|
||||
|
||||
- 产出：`assertSafeDevelopmentConfiguration(config)`、`assertMysql57Metadata(metadata)`、`buildMysqldumpArguments(config)`、`normalizeSchemaSql(sql)`、`buildCapturedArtifacts(metadata, sql)`、`buildNotApplicableArtifacts(metadata)`、`persistBaselineArtifacts(target, artifacts)`、`verifyBaselineDirectory(target, expectedRelease)`。
|
||||
|
||||
- [x] 实现最小配置与元数据校验，使安全边界测试通过。
|
||||
- [x] 实现参数数组构造；连接密码只允许由子进程环境传递，不进入参数。
|
||||
- [x] 实现确定性 SQL 规范化和敏感内容扫描，使固定样本逐字节匹配期望文件。
|
||||
- [x] 实现 SHA-256、平面可审计清单、标准 checksum 文件和目录校验。
|
||||
- [x] 采用同目录临时目录加原子改名写入；目标已存在时仅允许逐字节相同内容复用，其他情况报错。
|
||||
- [x] 运行 Schema 测试，确认所有测试转绿；再运行既有治理、MySQL 与环境基线测试，确认没有回归。
|
||||
|
||||
### 任务 3：实现真实入口但不连接数据库
|
||||
|
||||
**文件：**
|
||||
|
||||
- 修改：`tools/database/schema-baseline.mjs`
|
||||
- 修改：`package.json`
|
||||
- 修改：`deploy/env/development/api.env.example`（仅在契约字段缺失时修改）
|
||||
|
||||
**接口：**
|
||||
|
||||
- 消费：固定路径 `deploy/env/development/api.env`；文件不存在且仓库模板明确 `MYSQL_ENABLED=false` 时允许生成不适用记录。
|
||||
- 产出：`npm run schema:baseline` 与 `npm run schema:verify`，版本自动从最近语义化版本标签解析。
|
||||
|
||||
- [x] 测试命令行拒绝额外参数，证明不能传入 production env、数据库名或任意 env 路径。
|
||||
- [x] 测试未启用 MySQL 的入口不会调用数据库执行器，并为最近发布标签创建可验证不适用记录。
|
||||
- [x] 测试启用分支只构造固定 `mysql`/`mysqldump` 参数，并在客户端/服务端版本或数据库字符规则不符时阻断。
|
||||
- [x] 实现固定配置加载、最近标签与标签提交解析、回环主机检查、mysql/mysqldump 双客户端和服务端元数据检查、真实导出执行路径；本次验证不调用该路径。
|
||||
- [x] 运行 `npm run schema:baseline` 为 `v0.0.5` 生成 `not_applicable` 清单，并运行 `npm run schema:verify` 验证；确认不存在 `schema.sql`。
|
||||
|
||||
### 任务 4：接入版本开发前门禁与治理规范
|
||||
|
||||
**文件：**
|
||||
|
||||
- 修改：`tools/governance/start.mjs`
|
||||
- 修改：`tools/governance/feature-record.test.mjs` 或新增对应集成测试。
|
||||
- 修改：`AGENTS.md`
|
||||
- 修改：`docs/governance/development-workflow.md`
|
||||
- 修改：`docs/governance/code-development-standards.md`
|
||||
- 修改：`README.md`
|
||||
- 修改：`docs/index.md`
|
||||
|
||||
**接口：**
|
||||
|
||||
- 消费：`assertCurrentReleasedBaselinePublished(repositoryRoot)`。
|
||||
- 产出：治理开始命令只有在上一已发布版本 Schema 基线有效时才继续 GitNexus 开发前流程。
|
||||
|
||||
- [x] 先写失败测试：基线缺失或失效时 `governance:start` 的前置检查拒绝继续，有效 N/A 或真实基线时允许继续。
|
||||
- [x] 在 `start.mjs` 刷新 GitNexus 之前调用严格发布验证，检查 Git 跟踪、工作区、origin 分支和远程标签；不自动生成、不覆盖基线。
|
||||
- [x] 文档明确顺序为“生成并验证基线 → 中文提交 → 推送 Gitea → 治理开始”，以及首次启用 MySQL 时必须从真实开发库导出。
|
||||
- [x] 代码规范增加 Schema 仅结构、MySQL 5.7 完整对象范围、确定性规范化、禁止生产数据库和禁止直接改共享表的规则。
|
||||
|
||||
### 任务 5：验证、Review 与发布
|
||||
|
||||
**文件：**
|
||||
|
||||
- 新建或更新：GOV-007 完整功能档案。
|
||||
- 修改：`VERSION`、`CHANGELOG.md`、`docs/index.md`。
|
||||
|
||||
**接口：**
|
||||
|
||||
- 产出：可追溯的 `v0.0.6` 治理版本。
|
||||
|
||||
- [x] 执行 Schema、治理、MySQL、环境测试，执行 `git diff --check`、敏感信息扫描和适用构建检查。
|
||||
- [x] 执行 `npx gitnexus analyze` 与变更检测，保存开发前后差异和风险结论。
|
||||
- [x] 完成代码 Review 与开发规范符合性 Review；两份报告必须包含独立一行 `最终结论：passed`。
|
||||
- [x] 执行 `npm run governance:finish -- GOV-007 development-schema-baseline` 并保存证据。
|
||||
- [x] 使用中文 Conventional Commit 提交并立即推送 `origin/main`，回填实现提交和远程 SHA。
|
||||
- [x] 封存最终验证结果，提交并推送；创建带注释标签 `v0.0.6` 并只精确推送该标签。
|
||||
|
||||
## 计划自审
|
||||
|
||||
- 设计中的安全配置、完整对象范围、规范化、清单校验、禁止覆盖、未启用路径、治理门禁、双 Review 和发布要求均有对应任务。
|
||||
- 所有实现接口在任务 2 明确定义，任务 3、4 只消费这些接口，没有命名漂移。
|
||||
- 计划不包含待定项；真实数据库路径可实现但本次只以依赖注入和固定样本验证，符合禁止连接数据库的范围。
|
||||
@@ -0,0 +1,18 @@
|
||||
id: GOV-007
|
||||
name: 开发数据库 Schema 基线与版本门禁
|
||||
slug: development-schema-baseline
|
||||
status: released
|
||||
owner: project
|
||||
created_at: 2026-08-13
|
||||
prd: prd.md
|
||||
requirements: requirements.md
|
||||
design: design.md
|
||||
implementation_plan: implementation-plan.md
|
||||
test_plan: test-plan.md
|
||||
gitnexus_before: gitnexus/before.md
|
||||
gitnexus_after: gitnexus/after.md
|
||||
gitnexus_comparison: gitnexus/comparison.md
|
||||
code_review: review/code-review.md
|
||||
standards_review: review/standards-review.md
|
||||
implementation_commit: d827bfadb1fc0a7d768eefbf87b46ba26ac612d6
|
||||
release: v0.0.6
|
||||
@@ -0,0 +1,50 @@
|
||||
# 开发数据库 Schema 基线与版本门禁 PRD
|
||||
|
||||
- 功能编号：GOV-007
|
||||
- PRD 版本：0.1
|
||||
- 状态：approved
|
||||
- 日期：2026-08-13
|
||||
|
||||
## 问题
|
||||
|
||||
数据库迁移文件只能表达预期变化，不能证明每个版本开始前开发数据库的实际结构，也无法发现手工改表、对象遗漏或环境误连。当前 MySQL 尚未启用，还需要一种不伪造空 Schema 的可审计状态。
|
||||
|
||||
## 目标
|
||||
|
||||
- 每个新应用版本开发前，封存上一已发布版本的开发库完整 Schema。
|
||||
- 将环境、数据库名、MySQL 版本、字符集、排序规则和对象范围设置为强制门禁。
|
||||
- 生成确定性、可校验、可版本控制且不含数据或凭据的产物。
|
||||
- MySQL 未启用时生成可验证的不适用记录。
|
||||
- 在 `governance:start` 前阻断缺失或失效的上一版本基线。
|
||||
|
||||
## 用户流程
|
||||
|
||||
1. 开发者确认上一已发布语义化版本。
|
||||
2. 执行 `npm run schema:baseline` 生成或幂等验证对应目录。
|
||||
3. 执行 `npm run schema:verify` 复核清单、版本、提交和校验值。
|
||||
4. 将基线用中文提交推送项目 Gitea。
|
||||
5. 执行 `governance:start` 开始下一版本功能。
|
||||
|
||||
## 非目标
|
||||
|
||||
- 不备份任何业务数据、用户数据或生产数据。
|
||||
- 不连接、探测、读取或验证生产数据库。
|
||||
- 不替代生产运维备份、数据库恢复演练或迁移框架。
|
||||
- 本版本不启动 MySQL，也不对真实数据库执行命令。
|
||||
|
||||
## 风险
|
||||
|
||||
- `DEFINER`、导出时间和当前自增值会造成不可移植或无意义差异。
|
||||
- 参数可覆盖 env 或数据库名会扩大到生产资源的误操作范围。
|
||||
- 空 SQL 或可篡改的 N/A 清单会让门禁形式化而不可信。
|
||||
- 既有版本目录被覆盖会破坏发布历史。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- 开发库、MySQL 5.7 和字符规则不符合时全部阻断。
|
||||
- 导出参数明确只含结构并覆盖表、视图、触发器、例程和事件。
|
||||
- 规范化固定样本精确保留业务对象和列自增属性。
|
||||
- 真实基线三方 SHA-256 一致；N/A 基线只有清单。
|
||||
- 版本、标签提交、对象范围、状态和文件集合都能自动校验。
|
||||
- 既有不同内容禁止覆盖，命令行不能切换 production env 或数据库。
|
||||
- 治理流程、双 Review、GitNexus、中文提交和 Gitea 推送完成。
|
||||
@@ -0,0 +1,33 @@
|
||||
# 测试结果
|
||||
|
||||
- 日期：2026-08-13
|
||||
- 环境：本地开发仓库；未启动 MySQL，未连接任何数据库。
|
||||
|
||||
## 最新结果
|
||||
|
||||
- Schema 基线测试：23/23 passed。
|
||||
- 治理测试：5/5 passed。
|
||||
- MySQL 兼容基线：2/2 passed。
|
||||
- 环境与部署基线：6/6 passed。
|
||||
- `npm run schema:verify`：`v0.0.5 (not_applicable)` passed。
|
||||
- 严格 `governance:start` smoke：基线未提交时按预期阻断；独立提交并推送后通过。
|
||||
- `git ls-remote origin refs/heads/main` 与 `refs/tags/v0.0.5^{}`：远程 SHA 均按实时查询核对通过。
|
||||
- `git diff --check`：passed。
|
||||
- Node 语法检查：passed。
|
||||
- `npm run governance:finish -- GOV-007 development-schema-baseline`：passed。
|
||||
- 最终实现提交：`d827bfadb1fc0a7d768eefbf87b46ba26ac612d6`。
|
||||
- `git ls-remote origin refs/heads/main`：与最终实现提交一致。
|
||||
|
||||
## 测试先行留痕
|
||||
|
||||
首次测试因模块不存在以 `ERR_MODULE_NOT_FOUND` 失败。实现期间失败测试先后捕获：MySQL 密码条件必填、标签提交核对、清单篡改、标准 5.7 视图 DEFINER、例程字符串误改、顶层/例程 DML 区分、双客户端版本、未跟踪基线、陈旧 tracking ref、普通与可执行注释 DML 绕过、N/A 与当前开关不一致、顶层数据修改/装载及敏感内容漏检。每项均在实现修复后转绿。
|
||||
|
||||
## 未执行项
|
||||
|
||||
当前 MySQL 功能开关为关闭，本功能范围明确禁止连接数据库，因此未执行真实 MySQL 5.7 导出。首次启用 MySQL 的版本必须在固定开发库补做真实集成验证。
|
||||
|
||||
## 人工完成项
|
||||
|
||||
- GitNexus HIGH 风险已核对，13 条受影响流程均属于 Schema 生成、验证和治理门禁。
|
||||
- 视觉 QA 不适用，原因已单独留痕。
|
||||
- 回退说明已核对；本版本未执行生产发布或数据库变更。
|
||||
@@ -0,0 +1,5 @@
|
||||
# 视觉 QA
|
||||
|
||||
本功能没有页面、组件、样式、图表或浏览器交互变化，视觉 QA 不适用。
|
||||
|
||||
结论：not_applicable
|
||||
@@ -0,0 +1,13 @@
|
||||
# 发布说明
|
||||
|
||||
## v0.0.6
|
||||
|
||||
- 实现开发数据库 Schema 基线生成与只读验证命令。
|
||||
- 固定 MySQL 5.7、`a_share_analysis_dev`、`utf8mb4` 和 `utf8mb4_general_ci` 安全边界。
|
||||
- 增加完整对象导出参数、确定性 SQL 规范化、SHA-256 三方校验和禁止覆盖机制。
|
||||
- 为 MySQL 未启用状态建立不伪造空 SQL 的 `not_applicable` 基线。
|
||||
- 将上一发布版本 Schema 基线验证接入开发前和开发后治理门禁。
|
||||
- `governance:start` 仅接受已提交、已推送且远程标签一致的基线；真实导出限制在本机回环地址并分别校验 `mysql` 与 `mysqldump` 客户端版本。
|
||||
- N/A 基线会实时核对当前开发环境 MySQL 开关；启用后必须改用真实 captured 基线。
|
||||
- 扩展顶层数据操作、疑似凭据、数据库 URI、生产主机和导出噪声阻断。
|
||||
- 最终实现提交：`d827bfadb1fc0a7d768eefbf87b46ba26ac612d6`。
|
||||
@@ -0,0 +1,33 @@
|
||||
# 工程需求
|
||||
|
||||
## 安全配置
|
||||
|
||||
- `APP_ENV` 必须为 `development`，`MYSQL_DATABASE` 必须为 `a_share_analysis_dev`。
|
||||
- 字符集固定 `utf8mb4`，排序规则固定 `utf8mb4_general_ci`。
|
||||
- 启用 MySQL 后 host、port、username、password 均为必填；密码只通过子进程环境传递。
|
||||
- 启用 MySQL 时主机只能是本机回环地址；远程开发库必须先由运维建立本地 SSH 隧道，脚本不接受任意远程目标。
|
||||
- 命令行不接受 env 文件、环境类型、数据库名或其他覆盖参数。
|
||||
|
||||
## 数据库与导出
|
||||
|
||||
- 客户端和服务端版本必须匹配 MySQL 5.7.x。
|
||||
- 执行元数据查询的 `mysql` 客户端和执行导出的 `mysqldump` 客户端都必须分别验证为 5.7.x。
|
||||
- `mysqldump` 使用 `--no-data --routines --triggers --events`，不得输出 INSERT 或 REPLACE。
|
||||
- 完整对象范围为表、索引、外键、视图、触发器、存储过程、函数和事件。
|
||||
- 规范化删除不稳定注释、环境 `DEFINER` 和表选项当前自增值，保留列自增属性。
|
||||
|
||||
## 产物与校验
|
||||
|
||||
- 目录固定为 `database/schema-baselines/<已发布版本>/`。
|
||||
- 真实基线包含 `schema.sql`、`manifest.yaml`、`checksum.sha256`。
|
||||
- `manifest.yaml` 使用 JSON 兼容 YAML 的结构化格式，可由标准 JSON 解析器读取。
|
||||
- 清单记录版本、标签提交、来源环境、库名、版本、字符规则、对象范围、生成器和 SHA-256。
|
||||
- 目录采用同父目录临时写入后原子改名；既有目录只允许逐字节相同的幂等重跑。
|
||||
- MySQL 未启用时只生成 `manifest.yaml`，状态为 `not_applicable`，原因是 `mysql_disabled`，所有对象均为未捕获。
|
||||
|
||||
## 流程
|
||||
|
||||
- `governance:start` 在写入功能档案或刷新 GitNexus 前只读验证上一发布版本基线。
|
||||
- `governance:start` 还要求基线文件已被 Git 跟踪、无未提交改动、当前分支已推送且远程发布标签提交一致；`schema:verify` 只负责本地内容校验。
|
||||
- `governance:finish` 运行全部既有治理测试、Schema 测试和基线验证。
|
||||
- 本版本实际产物为 `v0.0.5` 的 N/A 清单，不连接任何数据库。
|
||||
@@ -0,0 +1,27 @@
|
||||
# 代码 Review
|
||||
|
||||
## 第一轮
|
||||
|
||||
结论：changes_required。发现 5 个 Important 和 2 个 Minor：未提交基线可绕过门禁、远程生产主机可被误连、标准 MySQL 5.7 视图 DEFINER 不兼容、顶层 DML 扫描绕过/例程误拒、未校验 mysql 客户端、N/A 清单字段不严和缺少严格门禁测试。
|
||||
|
||||
处置：全部补失败测试并修复。增加回环主机、双客户端、结构化清单、Git 跟踪与远程同步验证。
|
||||
|
||||
## 第二轮
|
||||
|
||||
结论：changes_required。发现普通/版本注释可绕过顶层 DML 扫描，远程分支校验依赖可能陈旧的 tracking ref。
|
||||
|
||||
处置：按真实分隔符解析顶层语句，剥离前置普通注释但扫描 MySQL 可执行注释；远程分支改为实时 `git ls-remote origin refs/heads/<branch>`，并增加回归测试。
|
||||
|
||||
## 最终复审
|
||||
|
||||
- 普通注释、版本 SET 注释、MySQL 可执行注释中的顶层 INSERT/REPLACE 均被拒绝。
|
||||
- 顶层 UPDATE、DELETE、TRUNCATE、LOAD DATA/XML 均被拒绝，例程内部合法 DML 保留。
|
||||
- MySQL dump 残留头、疑似密码/Token/Secret、数据库 URI 和生产主机注释均被拒绝。
|
||||
- N/A 基线每次重读固定开发环境配置，MySQL 启用后旧 N/A 清单立即失效。
|
||||
- 例程内合法 DML 保留，标准 MySQL 5.7 视图 DEFINER 输出可规范化。
|
||||
- 远程分支使用实时 `git ls-remote`，远程标签提交与清单提交核对。
|
||||
- 23 项 Schema 测试、治理/数据库/环境回归测试均通过。
|
||||
|
||||
问题处置：多轮 Review 的所有 Critical/Important/Minor 问题均已关闭并有回归测试；独立终审无新增问题，未保留延期问题。
|
||||
|
||||
最终结论：passed
|
||||
@@ -0,0 +1,20 @@
|
||||
# 开发规范符合性 Review
|
||||
|
||||
## 检查范围
|
||||
|
||||
- PRD、需求、确认设计、实施计划、测试计划、GitNexus 前后报告齐全。
|
||||
- 关键安全边界、规范化取舍、原子写入和远程门禁有中文原因注释。
|
||||
- 主要业务流程集中在一个可连续阅读的模块，没有过度拆分。
|
||||
- 测试遵循先失败后实现，固定样本和期望值独立维护。
|
||||
- MySQL 5.7、`utf8mb4`、`utf8mb4_general_ci` 和开发库限制符合规范。
|
||||
- 未写入密码、Token、真实 env、生产地址或生产数据。
|
||||
- `v0.0.5` N/A 基线已作为独立中文提交推送 Gitea。
|
||||
- 视觉变化不适用，已记录原因。
|
||||
|
||||
## 复审结果
|
||||
|
||||
- 最终代码复审已通过，Critical/Important/Minor 均为零；历史问题全部关闭并有测试证据。
|
||||
- `governance:finish` 将在发布前重新执行全部治理、Schema 和 GitNexus 门禁。
|
||||
- 最终实现提交 `d827bfadb1fc0a7d768eefbf87b46ba26ac612d6` 已推送 Gitea；封存提交和 `v0.0.6` 标签按发布步骤执行。
|
||||
|
||||
最终结论：passed
|
||||
@@ -0,0 +1,12 @@
|
||||
# 回退说明
|
||||
|
||||
本功能没有连接数据库、执行迁移或修改任何开发/生产数据。回退应用代码时可以恢复上一提交中的治理脚本和文档，但不得删除或改写已经随版本发布的 `database/schema-baselines/` 历史事实。
|
||||
|
||||
若工具实现存在缺陷，使用新的中文修复提交：
|
||||
|
||||
1. 保留原版本基线目录和 Git 历史。
|
||||
2. 在新的治理档案中记录错误原因、影响范围和修复策略。
|
||||
3. 对尚未发布的错误产物可在审查后修正；已发布产物通过追加更正记录处理，不移动共享标签。
|
||||
4. 首次启用 MySQL 后，任何修复都只允许读取开发库，生产数据库仍属于禁止范围。
|
||||
|
||||
N/A 清单没有 Schema 或数据可恢复。`v0.0.5` 目录证明当时 MySQL 功能开关关闭，不能在未来启用 MySQL 后追溯改写为真实 Schema。
|
||||
@@ -0,0 +1,32 @@
|
||||
# 测试计划
|
||||
|
||||
## 测试先行证据
|
||||
|
||||
- 首次执行 `node --test tools/database/schema-baseline.test.mjs` 因生产模块不存在而失败，错误为 `ERR_MODULE_NOT_FOUND`。
|
||||
- 首轮实现后固定样本和清单嵌套字段测试暴露规范化与解析缺口，修正后转绿。
|
||||
- 安全自审再以失败测试发现密码未设为条件必填、标签提交未核对、真实清单版本可篡改和 N/A 对象范围可伪造，均已实现对应阻断。
|
||||
|
||||
## 自动化范围
|
||||
|
||||
- 配置：环境、库名、字符集、排序规则、启用后的必填凭据。
|
||||
- 版本：MySQL 客户端、服务端和发布标签提交。
|
||||
- 命令：完整结构参数、密码不进参数、额外参数拒绝。
|
||||
- SQL：时间注释、`DEFINER`、表级自增值、列自增属性和五类对象。
|
||||
- 产物：SHA-256、精确文件集合、禁止覆盖、篡改检测、空 SQL 拒绝。
|
||||
- N/A：零数据库调用、只有清单、明确关闭版本和对象范围。
|
||||
- 回归：治理测试、MySQL 基线测试、环境基线测试、Schema 验证。
|
||||
- 严格发布门禁：未跟踪基线、未提交改动、未推送分支或远程标签不一致均阻断；本地 `schema:verify` 与发布前 `governance:start` 的职责分别验证。
|
||||
|
||||
## 最终命令
|
||||
|
||||
```bash
|
||||
npm run test:governance
|
||||
npm run test:mysql-baseline
|
||||
npm run test:environment-baseline
|
||||
npm run test:schema-baseline
|
||||
npm run schema:verify
|
||||
npm run governance:finish -- GOV-007 development-schema-baseline
|
||||
git diff --check
|
||||
```
|
||||
|
||||
本功能无 Web 页面、CSS 或图表变化，视觉 QA 记录为不适用。
|
||||
@@ -0,0 +1,45 @@
|
||||
# RocketMQ 消息队列架构调整设计
|
||||
|
||||
- 功能编号：GOV-008
|
||||
- 设计版本：0.1
|
||||
- 状态：approved
|
||||
- 日期：2026-08-13
|
||||
|
||||
## 架构
|
||||
|
||||
```text
|
||||
Scheduler
|
||||
-> MessageBusAdapter.publish()
|
||||
-> RocketMQ 5.x Proxy 或受支持客户端
|
||||
-> NameServer / Broker
|
||||
-> MessageBusAdapter.consume()
|
||||
-> Worker
|
||||
-> Redis 当前状态 + MySQL 事实记录
|
||||
```
|
||||
|
||||
`MessageBusAdapter` 是稳定边界。业务消息、Topic 和 Group 不引用 RocketMQ SDK 类型，未来客户端实现变化不要求重写调度与分析逻辑。项目只维护 RocketMQ 一套实现，不同时维护 RabbitMQ 兼容层。
|
||||
|
||||
## 接入模式
|
||||
|
||||
推荐 Node.js 通过 RocketMQ 5.x Proxy 接入，以降低对旧 Remoting 客户端实现的依赖。若后续选定的 Node 客户端直接连接 NameServer/Broker，必须先验证客户端维护状态、RocketMQ 5.3.2 兼容性、重试语义和优雅关闭，再通过 Adapter 接入。
|
||||
|
||||
`ROCKETMQ_NAMESRV_ADDR` 用于基础设施发现和诊断，`ROCKETMQ_ENDPOINT` 是应用客户端实际接入地址。两者不得混为同一项：只有 NameServer 端口可达时，不能完成生产或消费。
|
||||
|
||||
## Topic 与 Group
|
||||
|
||||
- Topic 前缀固定为 `a-share-analysis`，实际 Topic 按业务域追加，例如行情采集或指标计算。
|
||||
- Tag 使用稳定事件类型，不用临时任务 ID。
|
||||
- RocketMQ 5.x Proxy Producer 不配置 Producer Group；Worker 按独立消费语义使用 Consumer Group。
|
||||
- 环境隔离通过受控前缀或独立集群完成，禁止开发消费者读取生产 Topic。
|
||||
|
||||
## 可靠性
|
||||
|
||||
RocketMQ 提供至少一次投递语义，Worker 必须幂等。消息处理完成并形成可验证结果后才能确认；可重试错误返回重试，永久错误记录原因后进入死信。顺序消息只在明确消息组键内保证，不假设跨证券或跨交易日全局顺序。
|
||||
|
||||
最大投递次数是 Consumer Group 的服务端重试策略，由 RocketMQ 运维配置和发布检查负责。应用客户端只声明 Consumer Group、并发与处理结果，不能用一个不会被官方 Node SDK读取的 env 字段假装控制死信边界。
|
||||
|
||||
## 本地状态
|
||||
|
||||
2026-08-13 首次检查到 `apache/rocketmq:5.3.2` 的 `rmqnamesrv` 容器曾运行并映射 `9876:9876`，日志为 NameServer boot success；随后串行复核发现该容器已以 137 退出且未配置自动重启，`OOMKilled=false`。
|
||||
|
||||
宿主机 `9876` 实际由 `/usr/local/rocketmq` 的原生 NameServer 监听，同时存在 `mqbroker --enable-proxy`。只读 `mqadmin` 验证结果：`broker-a` 已注册，版本 `V5_3_2`、`brokerActive=true`，Broker 地址 `192.168.2.37:10911`；本机 `10911`、Proxy `8081` 和 NameServer `9876` 均可达，Topic 列表可读取。当前可确认 RocketMQ 基础设施和管理链路连通，但尚未通过项目 Node 客户端执行消息收发。
|
||||
@@ -0,0 +1,22 @@
|
||||
# GitNexus 开发后基线
|
||||
|
||||
## 状态
|
||||
|
||||
```text
|
||||
Repository: /Users/citrons/Documents/Codex/2026-08-12/wo-x/a-share-analysis
|
||||
Indexed: 8/13/2026, 2:23:20 PM
|
||||
Indexed commit: f5994ad
|
||||
Current commit: f5994ad
|
||||
Status: ✅ up-to-date
|
||||
```
|
||||
|
||||
## 图谱规模
|
||||
|
||||
- 958 个节点。
|
||||
- 1141 条关系。
|
||||
- 13 个聚类。
|
||||
- 23 条流程。
|
||||
|
||||
本次新增内容以文档、环境模板和契约测试为主，没有新增 MQ 运行时代码或执行流。
|
||||
|
||||
最终实现提交 `f5994ad77ec980175f671475e82c72d9d7e6f979` 已推送 `origin/main`，实时远程 SHA 核对一致。
|
||||
@@ -0,0 +1,26 @@
|
||||
# GitNexus 开发前基线
|
||||
|
||||
- 功能编号：GOV-008
|
||||
- 记录时间：2026年8月13日 GMT+8 13:59:16
|
||||
- 分支：main
|
||||
- 基线提交：3cc00de8f65e
|
||||
|
||||
## 工作区
|
||||
|
||||
```text
|
||||
(干净)
|
||||
```
|
||||
|
||||
## GitNexus 状态
|
||||
|
||||
```text
|
||||
Repository: /Users/citrons/Documents/Codex/2026-08-12/wo-x/a-share-analysis
|
||||
Indexed: 8/13/2026, 1:59:15 PM
|
||||
Indexed commit: 3cc00de
|
||||
Current commit: 3cc00de
|
||||
Status: ✅ up-to-date
|
||||
```
|
||||
|
||||
## 后续人工分析
|
||||
|
||||
在修改代码前，将 GitNexus query、context、impact 的结论写入 `gitnexus/impact-plan.md`。高风险结果必须先获得用户确认。
|
||||
@@ -0,0 +1,14 @@
|
||||
# GitNexus 前后对比
|
||||
|
||||
## 开发前
|
||||
|
||||
- 基线提交：`3cc00de`
|
||||
- RabbitMQ 仅存在于文档、模板和契约测试，没有运行时代码或执行流。
|
||||
|
||||
## 开发后
|
||||
|
||||
- 当前活动架构统一为 RocketMQ 5.x。
|
||||
- 新增 MessageBusAdapter、Topic/Tag/Group、重试、死信、幂等和顺序键约束。
|
||||
- GitNexus 变更检测为 LOW，0 条执行流受影响。
|
||||
|
||||
结论：调整发生在实现客户端之前，避免了双栈迁移；后续真实风险集中在 Node 客户端与 RocketMQ 5.3.2 的契约验证。
|
||||
@@ -0,0 +1,10 @@
|
||||
# GitNexus 变更检测
|
||||
|
||||
- 检测日期：2026-08-13
|
||||
- 范围：unstaged
|
||||
- 变更文件：16 个已跟踪文件，另含 GOV-008 功能档案与 ADR 新文件。
|
||||
- 变更符号：35
|
||||
- 受影响流程：0
|
||||
- 风险：LOW
|
||||
|
||||
变更集中在当前架构、环境模板、部署说明、代码规范和环境契约测试。GitNexus 未发现市场业务、数据库、HTTP 或消息运行流程受影响，因为 Server 和 MQ 客户端尚未实现。
|
||||
@@ -0,0 +1,13 @@
|
||||
# GitNexus 开发前影响分析
|
||||
|
||||
- 分析日期：2026-08-13
|
||||
- 基线提交：`3cc00de`
|
||||
- 索引状态：up-to-date
|
||||
|
||||
查询 RabbitMQ、消息队列、Scheduler、Worker 和部署配置。当前仓库没有 Server 生产代码或 MQ 执行流，影响集中在系统架构、代码开发规范、环境模板、部署文档和环境契约测试。
|
||||
|
||||
- `environment-baseline.test.mjs`：LOW，无上游调用方或业务流程。
|
||||
- `system-architecture.md`：LOW，直接引用方为 README 与文档索引。
|
||||
- `code-development-standards.md`：LOW，直接引用方为 README 与文档索引。
|
||||
|
||||
结论：不影响市场业务、数据库或 HTTP 运行流程。主要风险是环境键漂移和把 NameServer 可达误判为消息链路可用，分别由契约测试和分层连接证据控制。
|
||||
@@ -0,0 +1,13 @@
|
||||
# GOV-008 实施计划
|
||||
|
||||
- [x] 封存并推送 `v0.0.6` 开发库 N/A Schema 基线。
|
||||
- [x] 执行 `governance:start` 与 GitNexus 开发前探索和影响分析。
|
||||
- [x] 先修改环境契约测试，确认旧 RabbitMQ 配置使测试失败。
|
||||
- [x] 将 Scheduler/Worker 开发和生产模板改为 `ROCKETMQ_*`。
|
||||
- [x] 更新系统架构、代码开发规范、部署文档和未发布市场概览 PRD。
|
||||
- [x] 补齐 GOV-008 功能档案和本机连接验证证据。
|
||||
- [x] 运行治理、MySQL、环境、Schema 测试和配置/文档检查。
|
||||
- [x] 执行 GitNexus 变更检测、代码 Review 与规范 Review。
|
||||
- [x] 执行 `governance:finish`，中文提交并推送 Gitea。
|
||||
|
||||
本版本不实现客户端、不创建 Broker/Proxy、不发送测试消息。后续 Server 脚手架功能负责选型 Node 客户端并完成真实 Topic 收发契约测试。
|
||||
@@ -0,0 +1,18 @@
|
||||
id: GOV-008
|
||||
name: RocketMQ 消息队列架构调整
|
||||
slug: rocketmq-adoption
|
||||
status: released
|
||||
owner: project
|
||||
created_at: 2026-08-13
|
||||
prd: prd.md
|
||||
requirements: requirements.md
|
||||
design: design.md
|
||||
implementation_plan: implementation-plan.md
|
||||
test_plan: test-plan.md
|
||||
gitnexus_before: gitnexus/before.md
|
||||
gitnexus_after: gitnexus/after.md
|
||||
gitnexus_comparison: gitnexus/comparison.md
|
||||
code_review: review/code-review.md
|
||||
standards_review: review/standards-review.md
|
||||
implementation_commit: f5994ad77ec980175f671475e82c72d9d7e6f979
|
||||
release: v0.0.7
|
||||
@@ -0,0 +1,33 @@
|
||||
# RocketMQ 消息队列架构调整 PRD
|
||||
|
||||
- 功能编号：GOV-008
|
||||
- PRD 版本：0.1
|
||||
- 状态：approved
|
||||
- 日期：2026-08-13
|
||||
|
||||
## 问题
|
||||
|
||||
项目早期约定 RabbitMQ，但尚未实现消息客户端或业务消息链路。现决定统一采用 RocketMQ，并需要在服务脚手架落地前同步架构、环境契约和部署边界，避免后续同时维护两套消息模型。
|
||||
|
||||
## 目标
|
||||
|
||||
- 项目唯一消息队列调整为 RocketMQ 5.x。
|
||||
- Scheduler 和 Worker 通过 `MessageBusAdapter` 使用版本化消息契约。
|
||||
- 配置明确区分 NameServer、Broker/Proxy Endpoint、Topic 和 Group。
|
||||
- 保留本地默认关闭策略，同时允许连接独立运行的本机 RocketMQ。
|
||||
- 检查当前本机 Docker RocketMQ 的实际连通状态，不夸大验证范围。
|
||||
|
||||
## 非目标
|
||||
|
||||
- 本版本不实现 Server、Scheduler、Worker 或 RocketMQ Node 客户端。
|
||||
- 不替用户创建、删除或重启 Docker 或本机 RocketMQ 进程。
|
||||
- 不连接生产 RocketMQ，不创建生产 Topic 或 Group。
|
||||
- NameServer 可达时不宣称消息生产和消费已经可用。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- 当前架构、开发规范、部署说明和环境模板只采用 RocketMQ。
|
||||
- Scheduler 与 Worker 开发/生产模板键集合分别一致，且无 RabbitMQ 变量。
|
||||
- 文档定义重复投递、幂等、重试、死信和顺序消息边界。
|
||||
- 本机 NameServer 的版本、端口和启动状态有可复核证据。
|
||||
- 诊断必须区分 Docker 容器与本机原生进程，并报告 NameServer、Broker、Proxy 的真实状态。
|
||||
@@ -0,0 +1,19 @@
|
||||
# 测试结果
|
||||
|
||||
- 日期：2026-08-13
|
||||
- 状态：passed
|
||||
|
||||
测试先行阶段，环境契约测试按预期因缺少 `ROCKETMQ_*` 和活动文档仍包含 RabbitMQ 而失败。实现后结果：
|
||||
|
||||
- 治理测试：5/5 passed。
|
||||
- MySQL 5.7 基线测试：2/2 passed。
|
||||
- 环境与部署契约测试：7/7 passed。
|
||||
- Schema 基线测试：23/23 passed。
|
||||
- `npm run schema:verify`：`v0.0.6 (not_applicable)` passed。
|
||||
- `git diff --check` 与 Node 语法检查：passed。
|
||||
- 活动架构、部署、治理规范与环境模板 RabbitMQ 残留扫描：passed。
|
||||
- `npm run governance:finish -- GOV-008 rocketmq-adoption`：passed。
|
||||
- 独立代码 Review 与开发规范 Review：passed。
|
||||
- 最终实现提交：`f5994ad77ec980175f671475e82c72d9d7e6f979`，已推送 `origin/main`。
|
||||
|
||||
本机诊断确认：Docker `rmqnamesrv` 容器曾启动成功但现已以 137 退出，且非 OOM；宿主机原生 RocketMQ 5.3.2 正在运行 NameServer、`broker-a` 和 Proxy。`9876`、`10911`、`8081` 可达，`mqadmin` 可读取集群、Topic 和 Broker 状态。项目 Node 客户端尚未实现，因此未创建 Topic 或写入测试消息。
|
||||
@@ -0,0 +1,5 @@
|
||||
# 视觉 QA
|
||||
|
||||
本功能没有页面、组件、样式或浏览器交互变化，视觉 QA 不适用。
|
||||
|
||||
结论：not_applicable
|
||||
@@ -0,0 +1,7 @@
|
||||
# 发布说明
|
||||
|
||||
- 项目消息队列技术基线由 RabbitMQ 调整为 RocketMQ 5.x。
|
||||
- Scheduler 和 Worker 配置切换为 `ROCKETMQ_*`，并明确 Topic、Group、重试和接入地址。
|
||||
- 增加 `MessageBusAdapter` 边界，避免业务绑定具体客户端。
|
||||
- 本机原生 RocketMQ 5.3.2 NameServer、Broker 和 Proxy 已验证可达，Broker 已注册且状态正常；Docker `rmqnamesrv` 容器已退出，项目消息收发待 Node 客户端落地后验证。
|
||||
- 最终实现提交：`f5994ad77ec980175f671475e82c72d9d7e6f979`。
|
||||
@@ -0,0 +1,29 @@
|
||||
# 工程需求
|
||||
|
||||
## 技术基线
|
||||
|
||||
- MQ 固定为 RocketMQ 5.x，当前本机镜像版本为 `apache/rocketmq:5.3.2`。
|
||||
- 业务模块只依赖 `MessageBusAdapter` 与版本化事件，不直接引用客户端 SDK 类型。
|
||||
- Scheduler 只发布任务，Worker 只消费执行；重复投递由幂等键和业务唯一约束处理。
|
||||
|
||||
## 配置契约
|
||||
|
||||
- Scheduler 使用 `ROCKETMQ_ENABLED`、`ROCKETMQ_NAMESRV_ADDR`、`ROCKETMQ_ENDPOINT`、`ROCKETMQ_TOPIC_PREFIX` 和发送超时。RocketMQ 5.x Proxy 官方 Node Producer 不要求 Producer Group，禁止把旧 Remoting 参数混入配置。
|
||||
- Worker 使用相同的基础连接字段，并增加 `ROCKETMQ_CONSUMER_GROUP` 和客户端消费并发。
|
||||
- 开发和生产模板的同一进程必须保持相同键集合；生产连接地址留空且不得提交真实值。
|
||||
- `ROCKETMQ_ENABLED=false` 时不建立连接；启用后 Endpoint、Topic 和对应 Group 必须通过启动配置 Schema 校验。
|
||||
|
||||
## 消息语义
|
||||
|
||||
- 事件必须包含 `eventId`、`eventType`、`schemaVersion`、`occurredAt`、`tradeDate`、`traceId` 和 `idempotencyKey`。
|
||||
- Topic 表达稳定业务域，Tag 表达事件类型，Consumer Group 表达独立消费进度。
|
||||
- 需要顺序处理时必须声明消息组键；普通消息不保证全局顺序。
|
||||
- 超过最大消费次数后进入死信，必须支持查询、告警和受控重放。
|
||||
- 最大投递次数属于 RocketMQ 服务端 Consumer Group 重试策略，由运维配置并纳入部署验收，不作为官方 Node PushConsumer 的客户端环境变量。
|
||||
|
||||
## 本机验证
|
||||
|
||||
- 检查容器、镜像、端口映射和 NameServer 启动日志。
|
||||
- 使用 TCP 探针验证 `127.0.0.1:9876`。
|
||||
- 检查 Docker 容器和本机原生进程，避免把相同端口的其他监听者误判为目标容器。
|
||||
- 通过 `mqadmin clusterList`、`topicList`、`brokerStatus` 确认 Broker 注册、版本和管理链路；不擅自创建 Topic 或写入测试消息。
|
||||
@@ -0,0 +1,22 @@
|
||||
# 代码 Review
|
||||
|
||||
## 第一轮
|
||||
|
||||
结论：changes_required。发现 2 个 Important：配置混入旧 Remoting Producer Group 和无效的客户端最大重试字段；RabbitMQ 残留断言只覆盖生产 Worker。
|
||||
|
||||
## 处置
|
||||
|
||||
- 删除 `ROCKETMQ_PRODUCER_GROUP` 和 `ROCKETMQ_MAX_RECONSUME_TIMES`。
|
||||
- 明确最大投递次数属于服务端 Consumer Group 运维策略。
|
||||
- 扩展测试覆盖 Scheduler/Worker 的开发与生产四份模板，同时核对开发和生产连接地址边界。
|
||||
|
||||
## 最终复审
|
||||
|
||||
- 四份 Scheduler/Worker 模板均移除旧 RabbitMQ 字段、旧 Remoting Producer Group 和无效的客户端最大重试字段。
|
||||
- 开发模板统一使用 `127.0.0.1:9876` 和 `127.0.0.1:8081` 且保持关闭；生产连接地址保持空值。
|
||||
- 最大投递次数归属服务端 Consumer Group 运维策略，文档和配置语义一致。
|
||||
- 环境 7/7、治理 5/5、MySQL 2/2、Schema 23/23 及 Schema 验证通过。
|
||||
|
||||
Critical、Important、Minor 均无未关闭项。
|
||||
|
||||
最终结论：passed
|
||||
@@ -0,0 +1,12 @@
|
||||
# 开发规范符合性 Review
|
||||
|
||||
## 检查结果
|
||||
|
||||
- PRD、需求、设计、实施计划、测试计划、回退和 GitNexus 档案齐全。
|
||||
- 技术基线统一为 RocketMQ 5.x，历史档案保留原版本事实。
|
||||
- 配置模板无秘密，开发与生产同进程键集合一致，生产连接地址为空。
|
||||
- Node.js 接入边界明确采用 MessageBusAdapter，未提前绑定未经验证的 SDK 参数。
|
||||
- 本机诊断只读执行，未创建 Topic、未发送消息、未修改或重启用户进程。
|
||||
- 测试先行、GitNexus 影响分析和独立复审证据齐全。
|
||||
|
||||
最终结论：passed
|
||||
@@ -0,0 +1,7 @@
|
||||
# 回退说明
|
||||
|
||||
本功能只修改架构约定、无秘密环境模板、文档和契约测试，没有启动、停止或修改用户的 Docker 容器，也没有连接生产服务。
|
||||
|
||||
若后续 RocketMQ 客户端验证失败，使用新的治理功能和中文提交调整 Adapter 实现或接入方式；不得在业务代码中临时绕过 Adapter。回退文档配置时可以恢复上一已发布提交，但必须同步恢复开发/生产模板和契约测试，禁止形成一半 RabbitMQ、一半 RocketMQ 的混合状态。
|
||||
|
||||
本机 `rmqnamesrv` 容器及其 Docker 网络属于用户环境，不由仓库回退操作管理。
|
||||
@@ -0,0 +1,19 @@
|
||||
# 测试计划
|
||||
|
||||
## 自动化
|
||||
|
||||
- 开发和生产同进程环境键一致。
|
||||
- 生产模板禁止模拟数据并保持 MySQL 5.7 与 RocketMQ 开关契约。
|
||||
- 活动架构和部署文档包含 RocketMQ 且不再包含 RabbitMQ。
|
||||
- 本地 Compose 仍只启动 Redis，不隐式增加 RocketMQ 生命周期。
|
||||
- 治理、MySQL 5.7、Schema 基线回归测试全部通过。
|
||||
|
||||
## 本机诊断
|
||||
|
||||
- `docker ps` 与本机进程检查 NameServer、Broker、Proxy，定位端口真实监听者。
|
||||
- `docker inspect rmqnamesrv` 核对镜像与端口映射。
|
||||
- `docker logs rmqnamesrv` 核对启动成功日志。
|
||||
- `nc` 检查 `9876`、`10911` 和 `8081` TCP 可达。
|
||||
- `mqadmin clusterList`、`topicList`、`brokerStatus` 检查 Broker 注册、Topic 路由与运行状态。
|
||||
|
||||
基础设施管理链路已验证。由于项目 Server 与 Node 客户端尚未实现，本版本不创建测试 Topic，也不执行项目消息生产和消费，并将此限制记录为未执行项。
|
||||
@@ -2,13 +2,13 @@
|
||||
|
||||
## 1. 目标
|
||||
|
||||
本规范保证代码对普通开发者可连续阅读、对关键业务可解释、对历史版本可维护。规范适用于 Vue 3 前端、NestJS 后端、调度器、RabbitMQ Worker、数据适配器、规则引擎和 AI 分析模块。
|
||||
本规范保证代码对普通开发者可连续阅读、对关键业务可解释、对历史版本可维护。规范适用于 Vue 3 前端、NestJS 后端、调度器、RocketMQ Worker、数据适配器、规则引擎和 AI 分析模块。
|
||||
|
||||
## 2. 技术基线
|
||||
|
||||
- 前端：Vue 3、Vite、TypeScript、Dart Sass、Naive UI。
|
||||
- 后端：NestJS、TypeScript。
|
||||
- 数据库：MySQL 5.7.x，字符集 `utf8mb4`，排序规则 `utf8mb4_general_ci`；缓存：Redis；消息队列：RabbitMQ。
|
||||
- 数据库：MySQL 5.7.x，字符集 `utf8mb4`，排序规则 `utf8mb4_general_ci`；缓存：Redis；消息队列：RocketMQ 5.x。
|
||||
- 图表：Lightweight Charts负责K线和分时，ECharts负责热力图、分布和资金趋势。
|
||||
- AI：由服务端调用兼容 OpenAI 格式的付费 API，密钥不得下发浏览器。
|
||||
|
||||
@@ -51,7 +51,7 @@ Vue 页面可以包含与页面强绑定的小型展示逻辑；当子区域拥
|
||||
- 对外导出的公共接口、类型和关键函数。
|
||||
- 涨跌停、复权、停牌、午间休市等 A 股特殊规则。
|
||||
- 指标公式、阈值来源、单位、数据日期和缺失值处理。
|
||||
- RabbitMQ 的幂等、重试、死信和消息顺序假设。
|
||||
- RocketMQ 的 Topic、Tag、Group、幂等、重试、死信和消息顺序假设。
|
||||
- Redis 与 MySQL 一致性边界和缓存失效策略。
|
||||
- AI 输入裁剪、事实约束、降级和成本控制逻辑。
|
||||
- 看似可以简化但因兼容性或历史原因必须保留的实现。
|
||||
@@ -70,7 +70,9 @@ count += 1;
|
||||
|
||||
- 禁止无理由使用 `any`；外部输入先以 `unknown` 接收并校验。
|
||||
- HTTP API 使用版本化 OpenAPI 契约。
|
||||
- RabbitMQ 事件包含 `eventId`、`eventType`、`schemaVersion`、`occurredAt`、`tradeDate`、`traceId` 和 `idempotencyKey`。
|
||||
- RocketMQ 事件包含 `eventId`、`eventType`、`schemaVersion`、`occurredAt`、`tradeDate`、`traceId` 和 `idempotencyKey`。
|
||||
- Topic 使用稳定的业务域命名，环境隔离由部署配置的前缀完成；Tag 表达同一 Topic 内的事件类型，Consumer Group 表达独立消费进度，禁止把临时实例名作为 Group。RocketMQ 5.x Proxy Producer 不配置旧 Remoting Producer Group。
|
||||
- 需要顺序处理的消息必须明确消息组键，例如证券代码或交易日；未声明顺序键时不得依赖全局到达顺序。
|
||||
- 金额、成交额和比率必须明确单位，避免同一字段混用元、万元、亿元或百分比小数。
|
||||
- 数据来源、采集时间、交易日期、完整性和口径版本必须可追溯。
|
||||
|
||||
@@ -82,23 +84,37 @@ count += 1;
|
||||
- 免费数据源失败时保留最后有效快照，并明确标记陈旧，禁止伪装实时数据。
|
||||
- AI 失败不得影响规则分析和基础行情展示。
|
||||
|
||||
## 8. 前端规范
|
||||
## 8. 环境配置规范
|
||||
|
||||
- 页面不得直接访问第三方行情源、Redis、RabbitMQ 或 AI 服务。
|
||||
- 应用只接受 `development` 与 `production`，环境必须显式设置。生产启动不得回退到开发默认值、模拟数据、热更新或调试模式。
|
||||
- API、Scheduler、Worker 必须使用各自的配置 Schema，在进程启动时验证类型、格式、范围和条件必填项；配置错误立即退出。
|
||||
- 同一进程的开发与生产模板必须保持相同变量名。环境差异通过配置值、依赖注入和 Adapter 收敛，禁止在业务代码中散落 `APP_ENV` 分支。
|
||||
- 只有 `*.env.example` 可以提交；真实 `.env`、`*.env.local`、密码、Token 和 API Key 必须被 Git 忽略并由运行环境注入。
|
||||
- Web 只能使用公开的 `VITE_*` 变量。数据库、Redis、RocketMQ、数据源和 AI 凭据禁止进入前端变量或构建产物。
|
||||
- MySQL、RocketMQ、正式数据源与 AI 使用显式功能开关；关闭时连接变量可为空，开启后缺少任何必填值都必须拒绝启动。
|
||||
- Docker Compose 与源码部署必须复用同一变量契约，禁止为某种部署方式建立语义不同的别名。
|
||||
- 生产配置必须位于发布目录之外，切换应用版本不得覆盖配置；日志和诊断输出必须对配置值脱敏。
|
||||
|
||||
## 9. 前端规范
|
||||
|
||||
- 页面不得直接访问第三方行情源、Redis、RocketMQ 或 AI 服务。
|
||||
- 全局服务器状态使用 TanStack Vue Query，本地界面偏好使用 Pinia或轻量组合式函数。
|
||||
- Sass token集中管理颜色、间距、圆角、字号和断点。
|
||||
- A 股默认红涨绿跌，但状态必须同时提供文字或形状，不能只依赖颜色。
|
||||
- 图表必须标注单位、时间范围、数据日期和更新时间。
|
||||
- 所有核心交互覆盖加载、空、部分数据、错误和过期状态。
|
||||
|
||||
## 9. 后端与任务规范
|
||||
## 10. 后端与任务规范
|
||||
|
||||
- API、Scheduler和Worker作为独立进程维护，不在请求期间临时抓取全市场数据。
|
||||
- Scheduler只决定何时投递；RabbitMQ负责任务传输；Worker负责执行；MySQL负责事实记录；Redis负责当前快照和短期状态。
|
||||
- Scheduler 只决定何时投递；MessageBusAdapter 负责隔离客户端；RocketMQ 负责任务传输；Worker 负责执行；MySQL 负责事实记录；Redis 负责当前快照和短期状态。
|
||||
- 消费者必须幂等，消息确认只能发生在持久化或可验证处理完成后。
|
||||
- RocketMQ 可能重复投递；消费者不得把“收到一次”当作“只执行一次”，必须以 `idempotencyKey` 和业务唯一约束防重。
|
||||
- 普通重试使用 RocketMQ 消费重试；延迟任务使用受版本支持的定时/延迟消息；超过服务端 Consumer Group 最大投递次数后进入死信，必须可查询、告警和人工重放。
|
||||
- 业务代码只依赖项目定义的 `MessageBusAdapter` 和版本化事件契约，禁止直接依赖 RocketMQ SDK 类型；客户端、NameServer 或 Proxy 接入方式由基础设施适配层决定。
|
||||
- 免费数据源通过 Adapter 统一为内部模型，上层不得依赖供应商原始字段。
|
||||
|
||||
## 10. MySQL 5.7 兼容规范
|
||||
## 11. MySQL 5.7 兼容规范
|
||||
|
||||
- 开发、测试、Docker 和生产环境必须使用明确的 MySQL 5.7 补丁版本，禁止使用 `latest`、MySQL 8.x 或其他数据库代替兼容性验证。
|
||||
- 创建数据库必须显式声明 `DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci`；建表与迁移脚本必须显式保持 `DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci`。
|
||||
@@ -112,23 +128,32 @@ count += 1;
|
||||
- 每份迁移脚本必须能够从上一版本基线在 MySQL 5.7 正向执行；禁止用直接修改共享数据库表代替迁移脚本。
|
||||
- 代码 Review 必须检查服务端版本、字符集、排序规则、SQL/迁移兼容性、索引长度和字符串比较语义；任一不符合项按 Important 处理并阻断发布。
|
||||
|
||||
## 11. 测试要求
|
||||
### Schema 基线规范
|
||||
|
||||
- 每个新应用版本开发前必须封存上一已发布版本的开发库 Schema；只能读取 `APP_ENV=development`、`a_share_analysis_dev`，禁止连接、探测或读取生产数据库。
|
||||
- 导出使用 MySQL 5.7 `mysqldump` 的 `--no-data --routines --triggers --events`，完整保留表、索引、外键、视图、触发器、存储过程、函数和事件，不得包含任何表数据。
|
||||
- 规范化必须确定性删除导出时间、环境 `DEFINER` 和表选项中的当前 `AUTO_INCREMENT=<值>`，同时保留列定义的 `AUTO_INCREMENT` 属性和业务 SQL。
|
||||
- 账号密码只能通过受控子进程环境传递，不得进入参数、日志、SQL、清单或 checksum 文件。
|
||||
- `manifest.yaml`、`checksum.sha256` 和 `schema.sql` 的 SHA-256 必须一致；既有版本目录只允许内容完全一致的幂等验证，不允许覆盖。
|
||||
- MySQL 未启用时只创建状态为 `not_applicable` 的清单，不得创建空 `schema.sql`；启用后的缺失基线必须阻断下一版本开发。
|
||||
|
||||
## 12. 测试要求
|
||||
|
||||
- 功能和缺陷修复遵循测试先行：先看到测试因缺少行为而失败，再实现最小代码。
|
||||
- 纯规则和指标计算使用单元测试，期望值必须手工推导。
|
||||
- 数据源 Adapter 使用契约测试和固定样本。
|
||||
- HTTP 与 RabbitMQ 使用契约测试。
|
||||
- HTTP 与 RocketMQ 使用契约测试；消息测试必须覆盖 Topic、Tag、Group、序列化、重复投递、重试和死信边界。
|
||||
- 关键页面使用 Playwright流程测试和视觉截图对比。
|
||||
- 合并前必须通过类型检查、测试、构建和适用的视觉验证。
|
||||
|
||||
## 12. 安全要求
|
||||
## 13. 安全要求
|
||||
|
||||
- 禁止提交 `.env`、API Key、密码、真实账号和生产数据。
|
||||
- AI 密钥、数据源凭证和支付凭证仅存在服务端密钥管理中。
|
||||
- SQL必须参数化；外部输入必须在边界处校验。
|
||||
- 日志和异常报告必须脱敏。
|
||||
|
||||
## 13. 代码 Review 要求
|
||||
## 14. 代码 Review 要求
|
||||
|
||||
开发者完成自测不等于 Review 完成。审查者必须从功能 PRD、设计和 Git diff 出发，检查：
|
||||
|
||||
|
||||
@@ -16,21 +16,26 @@ released → superseded
|
||||
|
||||
## 3. 开发前流程
|
||||
|
||||
1. 分配功能编号和英文短名称。
|
||||
2. 建立 `docs/features/<编号>-<短名称>/`。
|
||||
3. 编写 `prd.md`，明确用户问题、目标、范围、非目标、用户流程、指标、风险和验收标准。
|
||||
4. PRD 审核通过后，将产品需求转换为可测试的工程需求。
|
||||
5. 比较可选方案，记录设计与关键决策。
|
||||
6. 更新 API、事件和数据结构契约。
|
||||
7. 编写测试计划和实施计划。
|
||||
8. 确保 Git 工作区基线可识别，执行：
|
||||
1. 确认上一已发布语义化版本及标签提交，执行 `npm run schema:baseline` 和 `npm run schema:verify`。
|
||||
2. MySQL 已启用时只能从 `APP_ENV=development`、`a_share_analysis_dev` 和本机回环地址导出完整 Schema；MySQL 未启用时只保存 `not_applicable` 清单，不创建空 SQL。
|
||||
3. 将 `database/schema-baselines/<上一发布版本>/` 作为独立中文提交推送 Gitea，核对本地和远程 SHA；既有版本目录禁止覆盖。只有 Git 已跟踪、工作区无改动、当前分支已推送且远程发布标签提交一致时，`governance:start` 才会继续。
|
||||
4. 分配功能编号和英文短名称。
|
||||
5. 建立 `docs/features/<编号>-<短名称>/`。
|
||||
6. 编写 `prd.md`，明确用户问题、目标、范围、非目标、用户流程、指标、风险和验收标准。
|
||||
7. PRD 审核通过后，将产品需求转换为可测试的工程需求。
|
||||
8. 比较可选方案，记录设计与关键决策。
|
||||
9. 更新 API、事件和数据结构契约。
|
||||
10. 编写测试计划和实施计划。
|
||||
11. 明确功能需要的环境变量、功能开关和部署影响；同步更新开发/生产模板，禁止只修改本机真实 env。
|
||||
12. 确保 Git 工作区基线可识别，执行：
|
||||
|
||||
```bash
|
||||
npm run governance:start -- FEAT-MO-001 market-overview
|
||||
```
|
||||
|
||||
9. 运行 GitNexus 查询、上下文和影响分析，将结果写入 `gitnexus/impact-plan.md`。
|
||||
10. 高风险或关键路径变化必须先向用户说明影响，再进入开发。
|
||||
13. `governance:start` 会只读复核上一发布版本 Schema 基线；缺失、失效或版本不一致时立即阻断，不会代为生成。
|
||||
14. 运行 GitNexus 查询、上下文和影响分析，将结果写入 `gitnexus/impact-plan.md`。
|
||||
15. 高风险或关键路径变化必须先向用户说明影响，再进入开发。
|
||||
|
||||
开发前必须至少回答：修改什么、为什么修改、影响谁、如何验证、失败后如何回退。
|
||||
|
||||
@@ -79,8 +84,19 @@ npm run governance:finish -- FEAT-MO-001 market-overview
|
||||
- 发布说明和回退方法可执行。
|
||||
- 中文提交已关联功能编号。
|
||||
- 当前分支和本次新建标签已推送到 `origin`，功能档案保存远程核对结果。
|
||||
- 配置契约变化已同步开发/生产模板和适用的 Compose、systemd、Nginx及部署文档。
|
||||
- 下一版本开发前所需的上一发布版本 Schema 基线已验证、独立提交并推送 Gitea。
|
||||
|
||||
## 7. 提交流程
|
||||
## 7. 数据库 Schema 基线
|
||||
|
||||
- 基线目录固定为 `database/schema-baselines/vX.Y.Z/`，版本是被备份的已发布版本。
|
||||
- 真实基线由 `schema.sql`、`manifest.yaml`、`checksum.sha256` 组成；范围包括表、索引、外键、视图、触发器、存储过程、函数和 Event Scheduler 事件，不含数据。
|
||||
- MySQL 未启用时目录只能包含 `manifest.yaml`，状态为 `not_applicable`、原因为 `mysql_disabled`。
|
||||
- `schema:baseline` 不接受 env 路径、环境类型或数据库名参数；配置路径固定在开发环境，生产配置和生产数据库不属于该命令的权限范围。
|
||||
- 修正已发布基线必须新增治理记录说明原因，禁止静默覆盖或重写历史目录。
|
||||
- 首次启用 MySQL 的版本必须通过迁移建立开发库，并在 MySQL 5.7 开发环境生成第一份真实 Schema 基线。
|
||||
|
||||
## 8. 提交流程
|
||||
|
||||
提交格式：
|
||||
|
||||
@@ -112,7 +128,7 @@ git push origin <本次标签名>
|
||||
|
||||
禁止使用 `--force`、`--force-with-lease` 或 `--tags` 代替精确推送。推送失败时不得宣称任务完成；应记录不含凭据的错误摘要，排查后重试同一精确命令。
|
||||
|
||||
## 8. 发布与回退
|
||||
## 9. 发布与回退
|
||||
|
||||
- 使用语义化版本和带注释 Git Tag。
|
||||
- 发布产物必须对应确定提交，不从浮动分支临时构建。
|
||||
|
||||
@@ -14,6 +14,18 @@
|
||||
- [系统架构](architecture/system-architecture.md)
|
||||
- [ADR-0001：单仓库双项目独立部署](adr/ADR-0001-monorepo-independent-deploy.md)
|
||||
- [ADR-0002：GitNexus 双门禁](adr/ADR-0002-gitnexus-double-gate.md)
|
||||
- [ADR-0003：采用 RocketMQ 5.x 作为唯一消息队列](adr/ADR-0003-rocketmq-message-bus.md)
|
||||
|
||||
## 环境与部署
|
||||
|
||||
- [本地开发环境](deployment/local-development.md)
|
||||
- [Docker Compose 生产部署](deployment/docker-compose-production.md)
|
||||
- [Ubuntu 源码生产部署](deployment/ubuntu-source-production.md)
|
||||
|
||||
## 数据库版本基线
|
||||
|
||||
- [Schema 基线目录](../database/schema-baselines/)
|
||||
- [GOV-007 设计规格](features/GOV-007-development-schema-baseline/design.md)
|
||||
|
||||
## GitNexus
|
||||
|
||||
@@ -29,5 +41,8 @@
|
||||
- [GOV-003：项目专用 Gitea 远程仓库](features/GOV-003-gitea-local-remote/manifest.yaml)
|
||||
- [GOV-004：提交后强制推送 Gitea](features/GOV-004-mandatory-gitea-push/manifest.yaml)
|
||||
- [GOV-005：MySQL 5.7 字符集与兼容性基线](features/GOV-005-mysql57-charset-baseline/manifest.yaml)
|
||||
- [GOV-006：开发、生产环境与双部署方式](features/GOV-006-environment-deployment-baseline/manifest.yaml)
|
||||
- [GOV-007：开发数据库 Schema 基线与版本门禁](features/GOV-007-development-schema-baseline/manifest.yaml)
|
||||
- [GOV-008：RocketMQ 消息队列架构调整](features/GOV-008-rocketmq-adoption/manifest.yaml)
|
||||
|
||||
功能档案是需求、设计、代码、测试、版本和回退之间的唯一正式关联入口。
|
||||
|
||||
@@ -6,6 +6,10 @@
|
||||
"scripts": {
|
||||
"test:governance": "node --test tools/governance/feature-record.test.mjs",
|
||||
"test:mysql-baseline": "node --test tools/governance/mysql-baseline.test.mjs",
|
||||
"test:environment-baseline": "node --test tools/governance/environment-baseline.test.mjs",
|
||||
"test:schema-baseline": "node --test tools/database/schema-baseline.test.mjs",
|
||||
"schema:baseline": "node tools/database/schema-baseline.mjs generate",
|
||||
"schema:verify": "node tools/database/schema-baseline.mjs verify",
|
||||
"governance:start": "node tools/governance/start.mjs",
|
||||
"governance:finish": "node tools/governance/finish.mjs"
|
||||
}
|
||||
|
||||
@@ -0,0 +1,18 @@
|
||||
/*!40101 SET @OLD_CHARACTER_SET_CLIENT=@@CHARACTER_SET_CLIENT */;
|
||||
|
||||
CREATE TABLE `market_snapshot` (
|
||||
`id` bigint(20) unsigned NOT NULL AUTO_INCREMENT,
|
||||
`trade_date` date NOT NULL,
|
||||
PRIMARY KEY (`id`)
|
||||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
|
||||
|
||||
/*!50001 DROP VIEW IF EXISTS `active_market_snapshot`*/;
|
||||
/*!50001 CREATE ALGORITHM=UNDEFINED */
|
||||
/*!50013 SQL SECURITY DEFINER */
|
||||
/*!50001 VIEW `active_market_snapshot` AS select `market_snapshot`.`id` AS `id` from `market_snapshot` */;
|
||||
|
||||
DELIMITER ;;
|
||||
/*!50003 CREATE*/ /*!50003 TRIGGER `market_snapshot_before_insert` BEFORE INSERT ON `market_snapshot` FOR EACH ROW SET NEW.trade_date = COALESCE(NEW.trade_date, CURRENT_DATE) */;;
|
||||
/*!50003 CREATE*/ /*!50003 PROCEDURE `refresh_market_snapshot`() BEGIN SELECT COUNT(*) FROM market_snapshot; END */;;
|
||||
/*!50106 CREATE*/ /*!50106 EVENT `purge_market_snapshot` ON SCHEDULE EVERY 1 DAY DO DELETE FROM market_snapshot WHERE trade_date < CURRENT_DATE - INTERVAL 365 DAY */;;
|
||||
DELIMITER ;
|
||||
@@ -0,0 +1,26 @@
|
||||
-- MySQL dump 10.13 Distrib 5.7.44, for Linux (x86_64)
|
||||
--
|
||||
-- Host: 127.0.0.1 Database: a_share_analysis_dev
|
||||
-- ------------------------------------------------------
|
||||
-- Server version 5.7.44-log
|
||||
|
||||
/*!40101 SET @OLD_CHARACTER_SET_CLIENT=@@CHARACTER_SET_CLIENT */;
|
||||
|
||||
CREATE TABLE `market_snapshot` (
|
||||
`id` bigint(20) unsigned NOT NULL AUTO_INCREMENT,
|
||||
`trade_date` date NOT NULL,
|
||||
PRIMARY KEY (`id`)
|
||||
) ENGINE=InnoDB AUTO_INCREMENT=128 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
|
||||
|
||||
/*!50001 DROP VIEW IF EXISTS `active_market_snapshot`*/;
|
||||
/*!50001 CREATE ALGORITHM=UNDEFINED */
|
||||
/*!50013 DEFINER=`dev_reader`@`127.0.0.1` SQL SECURITY DEFINER */
|
||||
/*!50001 VIEW `active_market_snapshot` AS select `market_snapshot`.`id` AS `id` from `market_snapshot` */;
|
||||
|
||||
DELIMITER ;;
|
||||
/*!50003 CREATE*/ /*!50017 DEFINER=`dev_reader`@`127.0.0.1`*/ /*!50003 TRIGGER `market_snapshot_before_insert` BEFORE INSERT ON `market_snapshot` FOR EACH ROW SET NEW.trade_date = COALESCE(NEW.trade_date, CURRENT_DATE) */;;
|
||||
/*!50003 CREATE*/ /*!50020 DEFINER=`dev_reader`@`127.0.0.1`*/ /*!50003 PROCEDURE `refresh_market_snapshot`() BEGIN SELECT COUNT(*) FROM market_snapshot; END */;;
|
||||
/*!50106 CREATE*/ /*!50117 DEFINER=`dev_reader`@`127.0.0.1`*/ /*!50106 EVENT `purge_market_snapshot` ON SCHEDULE EVERY 1 DAY DO DELETE FROM market_snapshot WHERE trade_date < CURRENT_DATE - INTERVAL 365 DAY */;;
|
||||
DELIMITER ;
|
||||
|
||||
-- Dump completed on 2026-08-13 11:00:00
|
||||
@@ -0,0 +1,766 @@
|
||||
import { execFileSync } from 'node:child_process';
|
||||
import {
|
||||
existsSync,
|
||||
mkdirSync,
|
||||
readFileSync,
|
||||
readdirSync,
|
||||
renameSync,
|
||||
rmSync,
|
||||
writeFileSync,
|
||||
} from 'node:fs';
|
||||
import { createHash } from 'node:crypto';
|
||||
import path from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
|
||||
const DEVELOPMENT_DATABASE = 'a_share_analysis_dev';
|
||||
const REQUIRED_CHARSET = 'utf8mb4';
|
||||
const REQUIRED_COLLATION = 'utf8mb4_general_ci';
|
||||
const BASELINE_FORMAT_VERSION = 1;
|
||||
const TOOL_VERSION = '1.0.0';
|
||||
const VERSION_PATTERN = /^v\d+\.\d+\.\d+$/;
|
||||
const DEVELOPMENT_HOSTS = new Set(['127.0.0.1', 'localhost', '::1']);
|
||||
const OBJECT_KEYS = Object.freeze(['tables', 'views', 'triggers', 'routines', 'events']);
|
||||
const CAPTURED_FILES = Object.freeze(['checksum.sha256', 'manifest.yaml', 'schema.sql']);
|
||||
const NOT_APPLICABLE_FILES = Object.freeze(['manifest.yaml']);
|
||||
|
||||
function requireExactValue(actual, expected, message) {
|
||||
if (actual !== expected) {
|
||||
throw new Error(`${message}，要求 ${expected}，实际 ${actual || '(空)'}`);
|
||||
}
|
||||
}
|
||||
|
||||
function isEnabled(value) {
|
||||
return value === true || value === 'true';
|
||||
}
|
||||
|
||||
/**
|
||||
* Schema 工具拥有比普通应用启动更窄的权限边界：即使连接地址看起来是本机，
|
||||
* 环境名和数据库名也必须同时命中固定开发值，避免通过参数误切到生产库。
|
||||
*/
|
||||
export function assertSafeDevelopmentConfiguration(config) {
|
||||
requireExactValue(config.APP_ENV, 'development', 'Schema 基线只允许 development 环境');
|
||||
requireExactValue(
|
||||
config.MYSQL_DATABASE,
|
||||
DEVELOPMENT_DATABASE,
|
||||
'Schema 基线只允许固定开发库 a_share_analysis_dev',
|
||||
);
|
||||
requireExactValue(config.MYSQL_CHARSET, REQUIRED_CHARSET, '数据库字符集不符合要求');
|
||||
requireExactValue(
|
||||
config.MYSQL_COLLATION,
|
||||
REQUIRED_COLLATION,
|
||||
'数据库排序规则不符合要求',
|
||||
);
|
||||
if (isEnabled(config.MYSQL_ENABLED)) {
|
||||
if (!DEVELOPMENT_HOSTS.has(config.MYSQL_HOST)) {
|
||||
throw new Error(
|
||||
`Schema 基线只允许通过开发机回环地址连接，实际 ${config.MYSQL_HOST || '(空)'}；远程开发库必须先建立本地 SSH 隧道`,
|
||||
);
|
||||
}
|
||||
for (const key of ['MYSQL_HOST', 'MYSQL_PORT', 'MYSQL_USERNAME', 'MYSQL_PASSWORD']) {
|
||||
if (!String(config[key] ?? '').trim()) {
|
||||
throw new Error(`MySQL 已启用，${key} 不能为空`);
|
||||
}
|
||||
}
|
||||
} else if (config.MYSQL_ENABLED !== false && config.MYSQL_ENABLED !== 'false') {
|
||||
throw new Error('MYSQL_ENABLED 必须显式为 true 或 false');
|
||||
}
|
||||
|
||||
return Object.freeze({ ...config, MYSQL_ENABLED: isEnabled(config.MYSQL_ENABLED) });
|
||||
}
|
||||
|
||||
/**
|
||||
* 客户端与服务端分别校验，防止用 MySQL 8 客户端生成带有 5.7 无法稳定恢复的语法，
|
||||
* 同时核对数据库自身字符规则，而不是信任 env 中的声明值。
|
||||
*/
|
||||
export function assertMysql57Metadata(metadata) {
|
||||
if (!/^5\.7\.\d+(?:[-+].*)?$/.test(metadata.mysqlClientVersion ?? '')) {
|
||||
throw new Error(`mysql 客户端必须为 5.7.x，实际 ${metadata.mysqlClientVersion || '(空)'}`);
|
||||
}
|
||||
if (!/^5\.7\.\d+(?:[-+].*)?$/.test(metadata.mysqldumpClientVersion ?? '')) {
|
||||
throw new Error(
|
||||
`mysqldump 客户端必须为 5.7.x，实际 ${metadata.mysqldumpClientVersion || '(空)'}`,
|
||||
);
|
||||
}
|
||||
if (!/^5\.7\.\d+(?:[-+].*)?$/.test(metadata.serverVersion ?? '')) {
|
||||
throw new Error(`MySQL 服务端必须为 5.7.x，实际 ${metadata.serverVersion || '(空)'}`);
|
||||
}
|
||||
requireExactValue(metadata.databaseCharset, REQUIRED_CHARSET, '开发数据库字符集不符合要求');
|
||||
requireExactValue(
|
||||
metadata.databaseCollation,
|
||||
REQUIRED_COLLATION,
|
||||
'开发数据库排序规则不符合要求',
|
||||
);
|
||||
return metadata;
|
||||
}
|
||||
|
||||
export function buildMysqldumpArguments(config) {
|
||||
assertSafeDevelopmentConfiguration(config);
|
||||
return [
|
||||
`--host=${config.MYSQL_HOST}`,
|
||||
`--port=${config.MYSQL_PORT}`,
|
||||
`--user=${config.MYSQL_USERNAME}`,
|
||||
`--default-character-set=${REQUIRED_CHARSET}`,
|
||||
'--no-data',
|
||||
'--routines',
|
||||
'--triggers',
|
||||
'--events',
|
||||
'--single-transaction',
|
||||
'--skip-lock-tables',
|
||||
'--skip-comments',
|
||||
DEVELOPMENT_DATABASE,
|
||||
];
|
||||
}
|
||||
|
||||
function buildMysqlMetadataArguments(config) {
|
||||
return [
|
||||
`--host=${config.MYSQL_HOST}`,
|
||||
`--port=${config.MYSQL_PORT}`,
|
||||
`--user=${config.MYSQL_USERNAME}`,
|
||||
`--default-character-set=${REQUIRED_CHARSET}`,
|
||||
'--batch',
|
||||
'--skip-column-names',
|
||||
DEVELOPMENT_DATABASE,
|
||||
'--execute=SELECT VERSION(), DEFAULT_CHARACTER_SET_NAME, DEFAULT_COLLATION_NAME FROM information_schema.SCHEMATA WHERE SCHEMA_NAME = DATABASE()',
|
||||
];
|
||||
}
|
||||
|
||||
function assertSchemaHasNoSensitiveOrDataStatements(sql) {
|
||||
// 安全扫描只忽略 SQL 字符串字面量，标识符反引号仍参与检查。否则存储过程
|
||||
// 合法返回“DEFINER=”等说明文字时会被误判，而真正的对象 DEFINER 仍可检出。
|
||||
const sqlWithoutStringLiterals = sql.replace(/'(?:''|\\.|[^'\\])*'/gs, "''");
|
||||
const prohibitedPatterns = [
|
||||
[sqlWithoutStringLiterals, /\bDEFINER\s*=/i, 'DEFINER'],
|
||||
[sql, /^--\s*MySQL dump\b/im, 'MySQL dump 头'],
|
||||
[sql, /--\s*Dump completed on/i, '导出完成时间'],
|
||||
[sql, /--\s*Host:/i, '连接主机注释'],
|
||||
[sql, /\b(?:password|passwd|pwd|api[_-]?key|api[_-]?token|access[_-]?token|client[_-]?secret|secret)\s*[:=]/i, '疑似凭据'],
|
||||
[sql, /\b(?:mysql|mariadb):\/\/[^\s'"`]+/i, '数据库连接串'],
|
||||
[sql, /\b(?:production|prod)[-_\s]*(?:host|db|database)?\s*[:=]\s*[^\s'"`]+/i, '疑似生产主机'],
|
||||
];
|
||||
for (const [content, pattern, label] of prohibitedPatterns) {
|
||||
if (pattern.test(content)) {
|
||||
throw new Error(`Schema SQL 包含禁止内容：${label}`);
|
||||
}
|
||||
}
|
||||
|
||||
for (const statement of splitSqlStatements(sql)) {
|
||||
let executableSql = statement
|
||||
.replace(
|
||||
/^(?:\s*--[^\n]*(?:\n|$)|\s*#[^\n]*(?:\n|$)|\s*\/\*(?!\!)[\s\S]*?\*\/\s*)+/g,
|
||||
'',
|
||||
)
|
||||
.trim();
|
||||
const candidates = [executableSql];
|
||||
const executableComment = executableSql.match(/^\/\*!\d{5}\s+([\s\S]*?)\*\/\s*/);
|
||||
if (executableComment) {
|
||||
candidates.push(
|
||||
executableComment[1].trim(),
|
||||
executableSql.slice(executableComment[0].length).trim(),
|
||||
);
|
||||
}
|
||||
const dataStatement = candidates.find((candidate) =>
|
||||
/^(?:INSERT\s+INTO|REPLACE\s+INTO|UPDATE\b|DELETE\s+FROM\b|TRUNCATE(?:\s+TABLE)?\b|LOAD\s+(?:DATA|XML)\b)/i.test(
|
||||
candidate,
|
||||
),
|
||||
);
|
||||
if (dataStatement) {
|
||||
const operation = dataStatement.match(
|
||||
/^(?:INSERT\s+INTO|REPLACE\s+INTO|UPDATE|DELETE\s+FROM|TRUNCATE(?:\s+TABLE)?|LOAD\s+(?:DATA|XML))/i,
|
||||
)[0];
|
||||
throw new Error(
|
||||
`Schema SQL 包含禁止的数据操作：${operation}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
function findDelimiterOutsideStrings(content, delimiter) {
|
||||
let quote = null;
|
||||
let escaped = false;
|
||||
for (let index = 0; index <= content.length - delimiter.length; index += 1) {
|
||||
const character = content[index];
|
||||
if (quote) {
|
||||
if (escaped) {
|
||||
escaped = false;
|
||||
} else if (character === '\\') {
|
||||
escaped = true;
|
||||
} else if (character === quote) {
|
||||
if (content[index + 1] === quote && quote !== '`') {
|
||||
index += 1;
|
||||
} else {
|
||||
quote = null;
|
||||
}
|
||||
}
|
||||
continue;
|
||||
}
|
||||
if (character === "'" || character === '"' || character === '`') {
|
||||
quote = character;
|
||||
continue;
|
||||
}
|
||||
if (content.startsWith(delimiter, index)) return index;
|
||||
}
|
||||
return -1;
|
||||
}
|
||||
|
||||
/**
|
||||
* mysqldump 用 DELIMITER 包住例程、触发器和事件。按真实分隔符切分后，
|
||||
* 只有顶层以 INSERT/REPLACE 开头的语句代表数据；对象体内部 DML 必须保留。
|
||||
*/
|
||||
function splitSqlStatements(sql) {
|
||||
const statements = [];
|
||||
let delimiter = ';';
|
||||
let buffer = '';
|
||||
for (const line of String(sql).split(/(?<=\n)/)) {
|
||||
const directive = line.trim().match(/^DELIMITER\s+(\S+)$/i);
|
||||
if (directive) {
|
||||
if (buffer.trim()) statements.push(buffer.trim());
|
||||
buffer = '';
|
||||
delimiter = directive[1];
|
||||
continue;
|
||||
}
|
||||
buffer += line;
|
||||
let delimiterIndex;
|
||||
while ((delimiterIndex = findDelimiterOutsideStrings(buffer, delimiter)) >= 0) {
|
||||
const statement = buffer.slice(0, delimiterIndex).trim();
|
||||
if (statement) statements.push(statement);
|
||||
buffer = buffer.slice(delimiterIndex + delimiter.length);
|
||||
}
|
||||
}
|
||||
if (buffer.trim()) statements.push(buffer.trim());
|
||||
return statements;
|
||||
}
|
||||
|
||||
/**
|
||||
* 规范化只删除 mysqldump 的环境噪声，不重排或重新格式化业务定义。
|
||||
* 表选项中的当前 AUTO_INCREMENT 值会随数据增长变化；列定义的自增属性不匹配
|
||||
* “等号加数字”的模式，因此会原样保留。
|
||||
*/
|
||||
export function normalizeSchemaSql(rawSql) {
|
||||
const normalized = String(rawSql)
|
||||
.replace(/\r\n?/g, '\n')
|
||||
.replace(/^-- MySQL dump .*\n/gm, '')
|
||||
.replace(/^-- Host:.*\n/gm, '')
|
||||
.replace(/^-- -+\n/gm, '')
|
||||
.replace(/^--\s*\n/gm, '')
|
||||
.replace(/^-- Server version.*\n/gm, '')
|
||||
.replace(/^-- Dump completed on .*\n?/gm, '')
|
||||
.replace(/\/\*!\d{5}\s+DEFINER=`[^`]+`@`[^`]+`\*\//g, '')
|
||||
.replace(
|
||||
/^(\/\*!\d{5}\s+)DEFINER=`[^`]+`@`[^`]+`\s+(SQL SECURITY\s+(?:DEFINER|INVOKER)\s+\*\/)$/gm,
|
||||
'$1$2',
|
||||
)
|
||||
// 普通视图的 DEFINER 只允许出现在版本注释外、语句行首的 CREATE 前缀中；
|
||||
// 限定在行首可避免误删例程字符串或注释里的业务文本。
|
||||
.replace(/^(\/\*!\d{5}\s+CREATE\s+[^\n]*?)\bDEFINER=`[^`]+`@`[^`]+`\s*/gm, '$1')
|
||||
.replace(/^(\) ENGINE=[^\n;]*?) AUTO_INCREMENT=\d+(?= )/gm, '$1')
|
||||
.replace(/^\s+/, '')
|
||||
.replace(/\s+$/, '');
|
||||
|
||||
const result = normalized.length > 0 ? `${normalized}\n` : '';
|
||||
assertSchemaHasNoSensitiveOrDataStatements(result);
|
||||
return result;
|
||||
}
|
||||
|
||||
function sha256(content) {
|
||||
return createHash('sha256').update(content, 'utf8').digest('hex');
|
||||
}
|
||||
|
||||
function buildManifest(fields) {
|
||||
// JSON 是 YAML 1.2 的严格子集；使用标准解析器生成和读取，避免手写 YAML
|
||||
// 对缩进、引号和同名嵌套字段产生歧义，同时仍保留约定的 manifest.yaml 文件名。
|
||||
return `${JSON.stringify(
|
||||
{
|
||||
format_version: BASELINE_FORMAT_VERSION,
|
||||
status: fields.status,
|
||||
application_version: fields.applicationVersion,
|
||||
git_commit: fields.gitCommit,
|
||||
source_environment: 'development',
|
||||
database_name: DEVELOPMENT_DATABASE,
|
||||
mysql_client_version: fields.mysqlClientVersion,
|
||||
mysqldump_client_version: fields.mysqldumpClientVersion,
|
||||
mysql_server_version: fields.serverVersion,
|
||||
charset: REQUIRED_CHARSET,
|
||||
collation: REQUIRED_COLLATION,
|
||||
generated_at: fields.generatedAt,
|
||||
generator: `schema-baseline/${TOOL_VERSION}`,
|
||||
reason: fields.reason ?? 'none',
|
||||
schema_sha256: fields.schemaSha256 ?? 'not_applicable',
|
||||
objects: {
|
||||
tables: fields.captured,
|
||||
views: fields.captured,
|
||||
triggers: fields.captured,
|
||||
routines: fields.captured,
|
||||
events: fields.captured,
|
||||
},
|
||||
},
|
||||
null,
|
||||
2,
|
||||
)}\n`;
|
||||
}
|
||||
|
||||
export function buildCapturedArtifacts(metadata, sql) {
|
||||
assertMysql57Metadata(metadata);
|
||||
if (!VERSION_PATTERN.test(metadata.applicationVersion ?? '')) {
|
||||
throw new Error(`应用版本格式无效：${metadata.applicationVersion || '(空)'}`);
|
||||
}
|
||||
const normalizedSql = normalizeSchemaSql(sql);
|
||||
if (!normalizedSql.trim()) {
|
||||
throw new Error('真实 Schema SQL 不能为空');
|
||||
}
|
||||
const schemaSha256 = sha256(normalizedSql);
|
||||
const manifest = buildManifest({
|
||||
...metadata,
|
||||
status: 'captured',
|
||||
captured: true,
|
||||
schemaSha256,
|
||||
});
|
||||
return Object.freeze({
|
||||
status: 'captured',
|
||||
schemaSha256,
|
||||
files: Object.freeze({
|
||||
'manifest.yaml': manifest,
|
||||
'schema.sql': normalizedSql,
|
||||
'checksum.sha256': `${schemaSha256} schema.sql\n`,
|
||||
}),
|
||||
});
|
||||
}
|
||||
|
||||
export function buildNotApplicableArtifacts(metadata) {
|
||||
if (!VERSION_PATTERN.test(metadata.applicationVersion ?? '')) {
|
||||
throw new Error(`应用版本格式无效：${metadata.applicationVersion || '(空)'}`);
|
||||
}
|
||||
const manifest = buildManifest({
|
||||
...metadata,
|
||||
mysqlClientVersion: 'not_enabled',
|
||||
mysqldumpClientVersion: 'not_enabled',
|
||||
serverVersion: 'not_enabled',
|
||||
status: 'not_applicable',
|
||||
reason: 'mysql_disabled',
|
||||
captured: false,
|
||||
});
|
||||
return Object.freeze({
|
||||
status: 'not_applicable',
|
||||
files: Object.freeze({ 'manifest.yaml': manifest }),
|
||||
});
|
||||
}
|
||||
|
||||
function compareExistingArtifacts(targetDirectory, artifacts) {
|
||||
const actualFiles = readdirSync(targetDirectory).sort();
|
||||
const expectedFiles = Object.keys(artifacts.files).sort();
|
||||
if (
|
||||
actualFiles.length !== expectedFiles.length ||
|
||||
actualFiles.some((file, index) => file !== expectedFiles[index])
|
||||
) {
|
||||
return false;
|
||||
}
|
||||
return expectedFiles.every(
|
||||
(file) => readFileSync(path.join(targetDirectory, file), 'utf8') === artifacts.files[file],
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* 先在目标父目录写入临时目录，再原子改名。这样异常不会留下半份基线；
|
||||
* 已发布版本目录只允许逐字节相同的幂等重跑，任何差异都必须人工留痕修正。
|
||||
*/
|
||||
export function persistBaselineArtifacts(targetDirectory, artifacts) {
|
||||
if (existsSync(targetDirectory)) {
|
||||
if (compareExistingArtifacts(targetDirectory, artifacts)) {
|
||||
return { reused: true };
|
||||
}
|
||||
throw new Error(`目标版本基线已存在且内容不同，禁止覆盖：${targetDirectory}`);
|
||||
}
|
||||
|
||||
const parentDirectory = path.dirname(targetDirectory);
|
||||
mkdirSync(parentDirectory, { recursive: true });
|
||||
const temporaryDirectory = path.join(
|
||||
parentDirectory,
|
||||
`.${path.basename(targetDirectory)}.tmp-${process.pid}-${Date.now()}`,
|
||||
);
|
||||
mkdirSync(temporaryDirectory);
|
||||
try {
|
||||
for (const [file, content] of Object.entries(artifacts.files)) {
|
||||
writeFileSync(path.join(temporaryDirectory, file), content, 'utf8');
|
||||
}
|
||||
renameSync(temporaryDirectory, targetDirectory);
|
||||
} catch (error) {
|
||||
rmSync(temporaryDirectory, { recursive: true, force: true });
|
||||
throw error;
|
||||
}
|
||||
return { reused: false };
|
||||
}
|
||||
|
||||
function parseManifest(content) {
|
||||
try {
|
||||
return JSON.parse(content);
|
||||
} catch {
|
||||
throw new Error('manifest.yaml 不是有效的结构化 YAML/JSON 清单');
|
||||
}
|
||||
}
|
||||
|
||||
function assertExactFileSet(targetDirectory, expectedFiles) {
|
||||
const actualFiles = readdirSync(targetDirectory).sort();
|
||||
const sortedExpected = [...expectedFiles].sort();
|
||||
if (
|
||||
actualFiles.length !== sortedExpected.length ||
|
||||
actualFiles.some((file, index) => file !== sortedExpected[index])
|
||||
) {
|
||||
throw new Error(
|
||||
`Schema 基线文件集合无效，要求 ${sortedExpected.join(', ')}，实际 ${actualFiles.join(', ')}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
export function verifyBaselineDirectory(targetDirectory, expectedRelease, expectedCommit) {
|
||||
if (!VERSION_PATTERN.test(expectedRelease ?? '')) {
|
||||
throw new Error(`待验证版本格式无效：${expectedRelease || '(空)'}`);
|
||||
}
|
||||
if (!existsSync(targetDirectory)) {
|
||||
throw new Error(`当前已发布版本缺少 Schema 基线：${targetDirectory}`);
|
||||
}
|
||||
|
||||
const manifest = parseManifest(
|
||||
readFileSync(path.join(targetDirectory, 'manifest.yaml'), 'utf8'),
|
||||
);
|
||||
const status = manifest.status;
|
||||
const applicationVersion = manifest.application_version;
|
||||
const generatedAt = Date.parse(manifest.generated_at ?? '');
|
||||
if (
|
||||
manifest.format_version !== BASELINE_FORMAT_VERSION ||
|
||||
manifest.generator !== `schema-baseline/${TOOL_VERSION}` ||
|
||||
!Number.isFinite(generatedAt) ||
|
||||
!/^[0-9a-f]{40}$/.test(manifest.git_commit ?? '')
|
||||
) {
|
||||
throw new Error('Schema 清单格式、生成器、时间或 Git 提交无效');
|
||||
}
|
||||
requireExactValue(applicationVersion, expectedRelease, 'Schema 基线版本与发布版本不一致');
|
||||
if (expectedCommit !== undefined) {
|
||||
requireExactValue(
|
||||
manifest.git_commit,
|
||||
expectedCommit,
|
||||
'Schema 基线提交与发布标签不一致',
|
||||
);
|
||||
}
|
||||
requireExactValue(
|
||||
manifest.source_environment,
|
||||
'development',
|
||||
'Schema 基线来源环境无效',
|
||||
);
|
||||
requireExactValue(
|
||||
manifest.database_name,
|
||||
DEVELOPMENT_DATABASE,
|
||||
'Schema 基线数据库名无效',
|
||||
);
|
||||
requireExactValue(manifest.charset, REQUIRED_CHARSET, 'Schema 字符集无效');
|
||||
requireExactValue(
|
||||
manifest.collation,
|
||||
REQUIRED_COLLATION,
|
||||
'Schema 排序规则无效',
|
||||
);
|
||||
|
||||
if (status === 'not_applicable') {
|
||||
assertExactFileSet(targetDirectory, NOT_APPLICABLE_FILES);
|
||||
const reason = manifest.reason;
|
||||
requireExactValue(reason, 'mysql_disabled', 'Schema 不适用原因无效');
|
||||
if (
|
||||
manifest.mysql_client_version !== 'not_enabled' ||
|
||||
manifest.mysqldump_client_version !== 'not_enabled' ||
|
||||
manifest.mysql_server_version !== 'not_enabled' ||
|
||||
manifest.schema_sha256 !== 'not_applicable' ||
|
||||
Object.keys(manifest.objects ?? {}).sort().join(',') !== [...OBJECT_KEYS].sort().join(',') ||
|
||||
OBJECT_KEYS.some((key) => manifest.objects[key] !== false)
|
||||
) {
|
||||
throw new Error('Schema 不适用清单必须证明 MySQL 未启用且所有对象均未捕获');
|
||||
}
|
||||
return { status, applicationVersion, reason };
|
||||
}
|
||||
if (status !== 'captured') {
|
||||
throw new Error(`Schema 基线状态无效：${status}`);
|
||||
}
|
||||
|
||||
assertExactFileSet(targetDirectory, CAPTURED_FILES);
|
||||
assertMysql57Metadata({
|
||||
mysqlClientVersion: manifest.mysql_client_version,
|
||||
mysqldumpClientVersion: manifest.mysqldump_client_version,
|
||||
serverVersion: manifest.mysql_server_version,
|
||||
databaseCharset: manifest.charset,
|
||||
databaseCollation: manifest.collation,
|
||||
});
|
||||
if (Object.keys(manifest.objects ?? {}).sort().join(',') !== [...OBJECT_KEYS].sort().join(',')) {
|
||||
throw new Error('Schema 对象范围字段无效');
|
||||
}
|
||||
for (const objectName of OBJECT_KEYS) {
|
||||
requireExactValue(manifest.objects?.[objectName], true, `Schema 对象范围缺少 ${objectName}`);
|
||||
}
|
||||
const sql = readFileSync(path.join(targetDirectory, 'schema.sql'), 'utf8');
|
||||
if (!sql.trim()) {
|
||||
throw new Error('真实 Schema SQL 不能为空');
|
||||
}
|
||||
assertSchemaHasNoSensitiveOrDataStatements(sql);
|
||||
if (/^(\) ENGINE=[^\n;]*?) AUTO_INCREMENT=\d+(?= )/m.test(sql)) {
|
||||
throw new Error('Schema SQL 仍包含当前 AUTO_INCREMENT 值');
|
||||
}
|
||||
const schemaSha256 = sha256(sql);
|
||||
const manifestChecksum = manifest.schema_sha256;
|
||||
const checksumFile = readFileSync(path.join(targetDirectory, 'checksum.sha256'), 'utf8');
|
||||
if (manifestChecksum !== schemaSha256 || checksumFile !== `${schemaSha256} schema.sql\n`) {
|
||||
throw new Error('Schema SQL、manifest 和 checksum 校验值不一致');
|
||||
}
|
||||
return { status, applicationVersion, schemaSha256 };
|
||||
}
|
||||
|
||||
export function parseEnvironmentFile(content) {
|
||||
const config = {};
|
||||
for (const rawLine of String(content).replace(/\r\n?/g, '\n').split('\n')) {
|
||||
const line = rawLine.trim();
|
||||
if (!line || line.startsWith('#')) continue;
|
||||
const separator = line.indexOf('=');
|
||||
if (separator <= 0) {
|
||||
throw new Error('开发环境配置包含无效行');
|
||||
}
|
||||
const key = line.slice(0, separator).trim();
|
||||
const value = line.slice(separator + 1).trim();
|
||||
if (!/^[A-Z][A-Z0-9_]*$/.test(key)) {
|
||||
throw new Error(`开发环境配置键无效：${key}`);
|
||||
}
|
||||
config[key] = value;
|
||||
}
|
||||
return config;
|
||||
}
|
||||
|
||||
function extractClientVersion(output) {
|
||||
const match = String(output).match(/\b(?:Distrib\s+)?(5\.7\.\d+(?:[-+][^\s,]+)?)/);
|
||||
return match?.[1] ?? String(output).trim();
|
||||
}
|
||||
|
||||
/**
|
||||
* 真实执行器可注入是为了让测试证明“关闭时零数据库调用”和命令边界；默认执行器
|
||||
* 仍使用 execFileSync 参数数组。密码仅放入子进程环境 MYSQL_PWD，不会进入 argv。
|
||||
*/
|
||||
export function runBaselineGeneration(options) {
|
||||
if ((options.commandArguments ?? []).length > 0) {
|
||||
throw new Error('Schema 基线命令不接受命令参数，不能覆盖环境、数据库或 env 路径');
|
||||
}
|
||||
const config = assertSafeDevelopmentConfiguration(
|
||||
parseEnvironmentFile(readFileSync(options.envFile, 'utf8')),
|
||||
);
|
||||
const targetDirectory = path.join(
|
||||
options.repositoryRoot,
|
||||
'database',
|
||||
'schema-baselines',
|
||||
options.applicationVersion,
|
||||
);
|
||||
if (existsSync(targetDirectory)) {
|
||||
return verifyBaselineDirectory(
|
||||
targetDirectory,
|
||||
options.applicationVersion,
|
||||
options.gitCommit,
|
||||
);
|
||||
}
|
||||
|
||||
const commonMetadata = {
|
||||
applicationVersion: options.applicationVersion,
|
||||
gitCommit: options.gitCommit,
|
||||
generatedAt: options.generatedAt ?? new Date().toISOString(),
|
||||
};
|
||||
if (!config.MYSQL_ENABLED) {
|
||||
const artifacts = buildNotApplicableArtifacts(commonMetadata);
|
||||
persistBaselineArtifacts(targetDirectory, artifacts);
|
||||
return verifyBaselineDirectory(targetDirectory, options.applicationVersion);
|
||||
}
|
||||
|
||||
const executeFile = options.executeFile ?? execFileSync;
|
||||
const childEnvironment = { ...process.env, MYSQL_PWD: config.MYSQL_PASSWORD ?? '' };
|
||||
const executionOptions = {
|
||||
cwd: options.repositoryRoot,
|
||||
encoding: 'utf8',
|
||||
stdio: ['ignore', 'pipe', 'pipe'],
|
||||
env: childEnvironment,
|
||||
};
|
||||
const mysqlClientVersion = extractClientVersion(
|
||||
executeFile('mysql', ['--version'], executionOptions),
|
||||
);
|
||||
const mysqldumpClientVersion = extractClientVersion(
|
||||
executeFile('mysqldump', ['--version'], executionOptions),
|
||||
);
|
||||
assertMysql57Metadata({
|
||||
mysqlClientVersion,
|
||||
mysqldumpClientVersion,
|
||||
serverVersion: '5.7.0-pending-server-check',
|
||||
databaseCharset: REQUIRED_CHARSET,
|
||||
databaseCollation: REQUIRED_COLLATION,
|
||||
});
|
||||
const serverMetadata = String(
|
||||
executeFile('mysql', buildMysqlMetadataArguments(config), executionOptions),
|
||||
)
|
||||
.trim()
|
||||
.split('\t');
|
||||
if (serverMetadata.length !== 3) {
|
||||
throw new Error('无法从固定开发库读取 MySQL 版本、字符集和排序规则');
|
||||
}
|
||||
const metadata = {
|
||||
...commonMetadata,
|
||||
mysqlClientVersion,
|
||||
mysqldumpClientVersion,
|
||||
serverVersion: serverMetadata[0],
|
||||
databaseCharset: serverMetadata[1],
|
||||
databaseCollation: serverMetadata[2],
|
||||
};
|
||||
assertMysql57Metadata(metadata);
|
||||
const rawSql = executeFile('mysqldump', buildMysqldumpArguments(config), executionOptions);
|
||||
const artifacts = buildCapturedArtifacts(metadata, rawSql);
|
||||
persistBaselineArtifacts(targetDirectory, artifacts);
|
||||
return verifyBaselineDirectory(targetDirectory, options.applicationVersion);
|
||||
}
|
||||
|
||||
function runGit(repositoryRoot, args) {
|
||||
return execFileSync('git', args, {
|
||||
cwd: repositoryRoot,
|
||||
encoding: 'utf8',
|
||||
stdio: ['ignore', 'pipe', 'pipe'],
|
||||
}).trim();
|
||||
}
|
||||
|
||||
export function getCurrentReleasedVersion(repositoryRoot) {
|
||||
const applicationVersion = runGit(repositoryRoot, [
|
||||
'describe',
|
||||
'--tags',
|
||||
'--abbrev=0',
|
||||
'--match',
|
||||
'v[0-9]*',
|
||||
]);
|
||||
if (!VERSION_PATTERN.test(applicationVersion)) {
|
||||
throw new Error(`最近发布标签格式无效：${applicationVersion}`);
|
||||
}
|
||||
return {
|
||||
applicationVersion,
|
||||
gitCommit: runGit(repositoryRoot, ['rev-list', '-n', '1', applicationVersion]),
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* not_applicable 清单只记录生成当时 MySQL 未启用，不能永久替代真实结构基线。
|
||||
* 每次校验都重新读取固定开发环境配置；一旦开发库启用，旧清单立即失效，强制
|
||||
* 下一版本开发开始前先从开发库生成 captured 基线。
|
||||
*/
|
||||
export function assertNotApplicableMatchesDevelopmentConfiguration(repositoryRoot, result) {
|
||||
if (result.status !== 'not_applicable') return result;
|
||||
|
||||
const config = assertSafeDevelopmentConfiguration(
|
||||
parseEnvironmentFile(readFileSync(resolveFixedDevelopmentEnv(repositoryRoot), 'utf8')),
|
||||
);
|
||||
if (config.MYSQL_ENABLED) {
|
||||
throw new Error('当前开发环境已启用 MySQL，不能继续使用 not_applicable Schema 基线');
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
export function assertCurrentReleasedBaseline(repositoryRoot) {
|
||||
const { applicationVersion, gitCommit } = getCurrentReleasedVersion(repositoryRoot);
|
||||
const result = verifyBaselineDirectory(
|
||||
path.join(repositoryRoot, 'database', 'schema-baselines', applicationVersion),
|
||||
applicationVersion,
|
||||
gitCommit,
|
||||
);
|
||||
return assertNotApplicableMatchesDevelopmentConfiguration(repositoryRoot, result);
|
||||
}
|
||||
|
||||
function runGitLines(repositoryRoot, args) {
|
||||
const output = runGit(repositoryRoot, args);
|
||||
return output ? output.split('\n').filter(Boolean) : [];
|
||||
}
|
||||
|
||||
/**
|
||||
* 开始下一版本前使用严格门禁：本地校验只证明内容正确，不能证明它已经进入
|
||||
* 可协作历史。这里进一步要求基线已跟踪、工作区无相关改动、当前 HEAD 已推送，
|
||||
* 且 origin 上的发布标签仍指向清单记录的提交。
|
||||
*/
|
||||
export function assertCurrentReleasedBaselinePublished(repositoryRoot) {
|
||||
const release = getCurrentReleasedVersion(repositoryRoot);
|
||||
const relativeDirectory = path.posix.join(
|
||||
'database',
|
||||
'schema-baselines',
|
||||
release.applicationVersion,
|
||||
);
|
||||
const result = verifyBaselineDirectory(
|
||||
path.join(repositoryRoot, relativeDirectory),
|
||||
release.applicationVersion,
|
||||
release.gitCommit,
|
||||
);
|
||||
assertNotApplicableMatchesDevelopmentConfiguration(repositoryRoot, result);
|
||||
const trackedFiles = new Set(
|
||||
runGitLines(repositoryRoot, ['ls-files', '--', relativeDirectory]),
|
||||
);
|
||||
const expectedFiles =
|
||||
result.status === 'captured' ? CAPTURED_FILES : NOT_APPLICABLE_FILES;
|
||||
for (const file of expectedFiles) {
|
||||
const relativeFile = path.posix.join(relativeDirectory, file);
|
||||
if (!trackedFiles.has(relativeFile)) {
|
||||
throw new Error(`Schema 基线尚未提交到 Git：${relativeFile}`);
|
||||
}
|
||||
}
|
||||
const localChanges = runGitLines(repositoryRoot, [
|
||||
'status',
|
||||
'--porcelain',
|
||||
'--',
|
||||
relativeDirectory,
|
||||
]);
|
||||
if (localChanges.length > 0) {
|
||||
throw new Error(`Schema 基线存在未提交改动：${localChanges.join(', ')}`);
|
||||
}
|
||||
|
||||
const branch = runGit(repositoryRoot, ['branch', '--show-current']);
|
||||
if (!branch) {
|
||||
throw new Error('Schema 发布门禁要求当前位于可推送分支');
|
||||
}
|
||||
const localHead = runGit(repositoryRoot, ['rev-parse', 'HEAD']);
|
||||
assertRemoteBranchMatches(repositoryRoot, branch, runGit, localHead);
|
||||
const remoteTag = runGit(repositoryRoot, [
|
||||
'ls-remote',
|
||||
'--tags',
|
||||
'origin',
|
||||
`refs/tags/${release.applicationVersion}^{}`,
|
||||
]);
|
||||
const remoteTagCommit = remoteTag.split(/\s+/)[0];
|
||||
requireExactValue(remoteTagCommit, release.gitCommit, '远程发布标签与基线提交不一致');
|
||||
return result;
|
||||
}
|
||||
|
||||
export function assertRemoteBranchMatches(repositoryRoot, branch, gitRunner = runGit, localHead) {
|
||||
const expectedHead = localHead ?? gitRunner(repositoryRoot, ['rev-parse', 'HEAD']);
|
||||
const remoteOutput = gitRunner(repositoryRoot, ['ls-remote', 'origin', `refs/heads/${branch}`]);
|
||||
const remoteHead = remoteOutput.split(/\s+/)[0];
|
||||
requireExactValue(remoteHead, expectedHead, '当前分支尚未完整推送到 origin');
|
||||
return true;
|
||||
}
|
||||
|
||||
|
||||
function resolveFixedDevelopmentEnv(repositoryRoot) {
|
||||
const realDevelopmentEnv = path.join(repositoryRoot, 'deploy', 'env', 'development', 'api.env');
|
||||
if (existsSync(realDevelopmentEnv)) return realDevelopmentEnv;
|
||||
return path.join(repositoryRoot, 'deploy', 'env', 'development', 'api.env.example');
|
||||
}
|
||||
|
||||
function runCommandLine() {
|
||||
const [command, ...commandArguments] = process.argv.slice(2);
|
||||
if (!['generate', 'verify'].includes(command) || commandArguments.length > 0) {
|
||||
throw new Error('用法：node tools/database/schema-baseline.mjs <generate|verify>（不接受额外参数）');
|
||||
}
|
||||
const repositoryRoot = process.cwd();
|
||||
const release = getCurrentReleasedVersion(repositoryRoot);
|
||||
const result =
|
||||
command === 'generate'
|
||||
? runBaselineGeneration({
|
||||
repositoryRoot,
|
||||
envFile: resolveFixedDevelopmentEnv(repositoryRoot),
|
||||
...release,
|
||||
commandArguments,
|
||||
})
|
||||
: assertCurrentReleasedBaseline(repositoryRoot);
|
||||
process.stdout.write(
|
||||
`Schema 基线验证通过：${release.applicationVersion} (${result.status})\n`,
|
||||
);
|
||||
}
|
||||
|
||||
if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
|
||||
runCommandLine();
|
||||
}
|
||||
@@ -0,0 +1,477 @@
|
||||
import assert from 'node:assert/strict';
|
||||
import { createHash } from 'node:crypto';
|
||||
import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
|
||||
import { tmpdir } from 'node:os';
|
||||
import path from 'node:path';
|
||||
import test from 'node:test';
|
||||
|
||||
import {
|
||||
assertMysql57Metadata,
|
||||
assertNotApplicableMatchesDevelopmentConfiguration,
|
||||
assertCurrentReleasedBaselinePublished,
|
||||
assertSafeDevelopmentConfiguration,
|
||||
buildCapturedArtifacts,
|
||||
buildMysqldumpArguments,
|
||||
buildNotApplicableArtifacts,
|
||||
normalizeSchemaSql,
|
||||
persistBaselineArtifacts,
|
||||
runBaselineGeneration,
|
||||
assertRemoteBranchMatches,
|
||||
verifyBaselineDirectory,
|
||||
} from './schema-baseline.mjs';
|
||||
|
||||
const validConfig = Object.freeze({
|
||||
APP_ENV: 'development',
|
||||
MYSQL_ENABLED: 'true',
|
||||
MYSQL_HOST: '127.0.0.1',
|
||||
MYSQL_PORT: '3306',
|
||||
MYSQL_DATABASE: 'a_share_analysis_dev',
|
||||
MYSQL_USERNAME: 'schema_reader',
|
||||
MYSQL_PASSWORD: 'never-place-this-in-arguments',
|
||||
MYSQL_CHARSET: 'utf8mb4',
|
||||
MYSQL_COLLATION: 'utf8mb4_general_ci',
|
||||
});
|
||||
|
||||
const validMetadata = Object.freeze({
|
||||
applicationVersion: 'v0.0.5',
|
||||
gitCommit: '0a69aa1f6f5cc75d72f21c43d96f5ff648e2ec93',
|
||||
mysqlClientVersion: '5.7.44',
|
||||
mysqldumpClientVersion: '5.7.44',
|
||||
serverVersion: '5.7.44-log',
|
||||
databaseCharset: 'utf8mb4',
|
||||
databaseCollation: 'utf8mb4_general_ci',
|
||||
generatedAt: '2026-08-13T03:00:00.000Z',
|
||||
});
|
||||
|
||||
function makeTemporaryDirectory() {
|
||||
return mkdtempSync(path.join(tmpdir(), 'a-share-schema-baseline-'));
|
||||
}
|
||||
|
||||
function replaceCapturedSql(target, sql) {
|
||||
const checksum = createHash('sha256').update(sql).digest('hex');
|
||||
const manifestPath = path.join(target, 'manifest.yaml');
|
||||
const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
|
||||
manifest.schema_sha256 = checksum;
|
||||
writeFileSync(path.join(target, 'schema.sql'), sql);
|
||||
writeFileSync(path.join(target, 'checksum.sha256'), `${checksum} schema.sql\n`);
|
||||
writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
|
||||
}
|
||||
|
||||
test('拒绝任何非开发环境和非固定开发库配置', () => {
|
||||
assert.throws(
|
||||
() => assertSafeDevelopmentConfiguration({ ...validConfig, APP_ENV: 'production' }),
|
||||
/只允许 development/,
|
||||
);
|
||||
assert.throws(
|
||||
() =>
|
||||
assertSafeDevelopmentConfiguration({
|
||||
...validConfig,
|
||||
MYSQL_DATABASE: 'a_share_analysis',
|
||||
}),
|
||||
/a_share_analysis_dev/,
|
||||
);
|
||||
assert.throws(
|
||||
() =>
|
||||
assertSafeDevelopmentConfiguration({
|
||||
...validConfig,
|
||||
MYSQL_HOST: 'forbidden-remote.example.invalid',
|
||||
}),
|
||||
/开发机回环地址/,
|
||||
);
|
||||
});
|
||||
|
||||
test('拒绝错误字符集、排序规则和不完整的启用配置', () => {
|
||||
assert.throws(
|
||||
() => assertSafeDevelopmentConfiguration({ ...validConfig, MYSQL_CHARSET: 'utf8' }),
|
||||
/utf8mb4/,
|
||||
);
|
||||
assert.throws(
|
||||
() =>
|
||||
assertSafeDevelopmentConfiguration({
|
||||
...validConfig,
|
||||
MYSQL_COLLATION: 'utf8mb4_0900_ai_ci',
|
||||
}),
|
||||
/utf8mb4_general_ci/,
|
||||
);
|
||||
assert.throws(
|
||||
() => assertSafeDevelopmentConfiguration({ ...validConfig, MYSQL_USERNAME: '' }),
|
||||
/MYSQL_USERNAME/,
|
||||
);
|
||||
assert.throws(
|
||||
() => assertSafeDevelopmentConfiguration({ ...validConfig, MYSQL_PASSWORD: '' }),
|
||||
/MYSQL_PASSWORD/,
|
||||
);
|
||||
});
|
||||
|
||||
test('只接受 MySQL 5.7 客户端、服务端和固定数据库字符规则', () => {
|
||||
assert.doesNotThrow(() => assertMysql57Metadata(validMetadata));
|
||||
assert.throws(
|
||||
() => assertMysql57Metadata({ ...validMetadata, serverVersion: '8.0.39' }),
|
||||
/服务端必须为 5\.7/,
|
||||
);
|
||||
assert.throws(
|
||||
() => assertMysql57Metadata({ ...validMetadata, mysqlClientVersion: '8.0.39' }),
|
||||
/mysql 客户端必须为 5\.7/,
|
||||
);
|
||||
assert.throws(
|
||||
() => assertMysql57Metadata({ ...validMetadata, databaseCollation: 'utf8mb4_bin' }),
|
||||
/utf8mb4_general_ci/,
|
||||
);
|
||||
});
|
||||
|
||||
test('mysqldump 只导出完整结构且密码不进入命令参数', () => {
|
||||
const args = buildMysqldumpArguments(validConfig);
|
||||
|
||||
for (const required of ['--no-data', '--routines', '--triggers', '--events']) {
|
||||
assert.ok(args.includes(required), `缺少强制导出参数：${required}`);
|
||||
}
|
||||
assert.equal(args.at(-1), 'a_share_analysis_dev');
|
||||
assert.equal(args.join(' ').includes(validConfig.MYSQL_PASSWORD), false);
|
||||
assert.equal(args.some((argument) => argument.startsWith('--password')), false);
|
||||
});
|
||||
|
||||
test('规范化移除环境噪声和账号绑定但保留全部业务对象', () => {
|
||||
const fixtureDirectory = path.join(import.meta.dirname, 'fixtures');
|
||||
const input = readFileSync(path.join(fixtureDirectory, 'mysql57-schema-input.sql'), 'utf8');
|
||||
const expected = readFileSync(
|
||||
path.join(fixtureDirectory, 'mysql57-schema-expected.sql'),
|
||||
'utf8',
|
||||
);
|
||||
|
||||
const actual = normalizeSchemaSql(input);
|
||||
assert.equal(actual, expected);
|
||||
assert.match(actual, /NOT NULL AUTO_INCREMENT/);
|
||||
assert.doesNotMatch(actual, /AUTO_INCREMENT=128/);
|
||||
assert.doesNotMatch(actual, /DEFINER=`/);
|
||||
for (const objectName of [
|
||||
'CREATE TABLE',
|
||||
'VIEW `active_market_snapshot`',
|
||||
'TRIGGER `market_snapshot_before_insert`',
|
||||
'PROCEDURE `refresh_market_snapshot`',
|
||||
'EVENT `purge_market_snapshot`',
|
||||
]) {
|
||||
assert.ok(actual.includes(objectName), `规范化误删对象：${objectName}`);
|
||||
}
|
||||
});
|
||||
|
||||
test('规范化不改写例程字符串中的业务文本', () => {
|
||||
const sql = [
|
||||
'CREATE PROCEDURE `describe_schema`()',
|
||||
"BEGIN SELECT 'DEFINER=`business`@`text` AUTO_INCREMENT=128' AS description; END;",
|
||||
'',
|
||||
].join('\n');
|
||||
|
||||
assert.equal(normalizeSchemaSql(sql), sql);
|
||||
});
|
||||
|
||||
test('数据扫描拒绝同行顶层写入但保留例程中的合法 DML', () => {
|
||||
assert.throws(
|
||||
() => normalizeSchemaSql('CREATE TABLE `sample` (`id` int); INSERT INTO `sample` VALUES (1);\n'),
|
||||
/INSERT INTO/,
|
||||
);
|
||||
|
||||
const routineSql = [
|
||||
'DELIMITER ;;',
|
||||
'CREATE PROCEDURE `seed_fixture`()',
|
||||
'BEGIN',
|
||||
'INSERT INTO `sample` VALUES (1);',
|
||||
'END ;;',
|
||||
'DELIMITER ;',
|
||||
'',
|
||||
].join('\n');
|
||||
assert.equal(normalizeSchemaSql(routineSql), routineSql);
|
||||
for (const prefixedSql of [
|
||||
'/* comment */\nINSERT INTO `sample` VALUES (1);\n',
|
||||
'/*!40101 SET @x=1 */ INSERT INTO `sample` VALUES (1);\n',
|
||||
'/*!40101 INSERT INTO `sample` VALUES (1) */;\n',
|
||||
'/*!40101 REPLACE INTO `sample` VALUES (1) */;\n',
|
||||
'CREATE TABLE `sample` (`id` int); -- comment\nREPLACE INTO `sample` VALUES (1);\n',
|
||||
]) {
|
||||
assert.throws(() => normalizeSchemaSql(prefixedSql), /INSERT INTO|REPLACE INTO/);
|
||||
}
|
||||
});
|
||||
|
||||
test('数据扫描拒绝所有顶层数据修改和装载语句', () => {
|
||||
for (const statement of [
|
||||
'UPDATE `sample` SET `id` = 2',
|
||||
'DELETE FROM `sample`',
|
||||
'TRUNCATE TABLE `sample`',
|
||||
"LOAD DATA LOCAL INFILE '/tmp/sample.csv' INTO TABLE `sample`",
|
||||
"LOAD XML LOCAL INFILE '/tmp/sample.xml' INTO TABLE `sample`",
|
||||
]) {
|
||||
assert.throws(() => normalizeSchemaSql(`${statement};\n`), /禁止的数据操作/);
|
||||
}
|
||||
});
|
||||
|
||||
test('安全扫描拒绝导出噪声、疑似凭据、连接串和生产主机', () => {
|
||||
for (const unsafeSql of [
|
||||
'-- API_TOKEN=supersecret\nCREATE TABLE `sample` (`id` int);\n',
|
||||
'-- CLIENT_SECRET: supersecret\nCREATE TABLE `sample` (`id` int);\n',
|
||||
'-- mysql://schema_reader:secret@127.0.0.1/a_share_analysis_dev\nCREATE TABLE `sample` (`id` int);\n',
|
||||
'-- production host: prod-db.internal\nCREATE TABLE `sample` (`id` int);\n',
|
||||
]) {
|
||||
assert.throws(() => normalizeSchemaSql(unsafeSql), /Schema SQL 包含禁止内容/);
|
||||
}
|
||||
|
||||
const root = makeTemporaryDirectory();
|
||||
const target = path.join(root, 'v0.0.5');
|
||||
persistBaselineArtifacts(
|
||||
target,
|
||||
buildCapturedArtifacts(validMetadata, 'CREATE TABLE `sample` (`id` int);\n'),
|
||||
);
|
||||
replaceCapturedSql(
|
||||
target,
|
||||
'-- MySQL dump 10.13 Distrib 5.7.44\nCREATE TABLE `sample` (`id` int);\n',
|
||||
);
|
||||
assert.throws(() => verifyBaselineDirectory(target, 'v0.0.5'), /MySQL dump/);
|
||||
});
|
||||
|
||||
test('真实基线的清单、校验文件和 SQL 必须三方一致', () => {
|
||||
const sql = 'CREATE TABLE `sample` (`id` bigint NOT NULL AUTO_INCREMENT);\n';
|
||||
const root = makeTemporaryDirectory();
|
||||
const target = path.join(root, 'v0.0.5');
|
||||
const artifacts = buildCapturedArtifacts(validMetadata, sql);
|
||||
|
||||
persistBaselineArtifacts(target, artifacts);
|
||||
const result = verifyBaselineDirectory(target, 'v0.0.5');
|
||||
|
||||
assert.equal(result.status, 'captured');
|
||||
assert.equal(result.applicationVersion, 'v0.0.5');
|
||||
assert.equal(result.schemaSha256, artifacts.schemaSha256);
|
||||
assert.equal(readFileSync(path.join(target, 'checksum.sha256'), 'utf8'), `${artifacts.schemaSha256} schema.sql\n`);
|
||||
});
|
||||
|
||||
test('拒绝静默覆盖已存在且内容不同的版本基线', () => {
|
||||
const root = makeTemporaryDirectory();
|
||||
const target = path.join(root, 'v0.0.5');
|
||||
const artifacts = buildCapturedArtifacts(validMetadata, 'CREATE TABLE `sample` (`id` int);\n');
|
||||
persistBaselineArtifacts(target, artifacts);
|
||||
|
||||
assert.doesNotThrow(() => persistBaselineArtifacts(target, artifacts));
|
||||
assert.throws(
|
||||
() =>
|
||||
persistBaselineArtifacts(
|
||||
target,
|
||||
buildCapturedArtifacts(validMetadata, 'CREATE TABLE `changed` (`id` int);\n'),
|
||||
),
|
||||
/禁止覆盖/,
|
||||
);
|
||||
});
|
||||
|
||||
test('MySQL 未启用时只生成可验证不适用清单', () => {
|
||||
const root = makeTemporaryDirectory();
|
||||
const target = path.join(root, 'v0.0.5');
|
||||
const artifacts = buildNotApplicableArtifacts(validMetadata);
|
||||
|
||||
persistBaselineArtifacts(target, artifacts);
|
||||
const result = verifyBaselineDirectory(target, 'v0.0.5');
|
||||
|
||||
assert.equal(result.status, 'not_applicable');
|
||||
assert.equal(result.reason, 'mysql_disabled');
|
||||
assert.throws(() => readFileSync(path.join(target, 'schema.sql')), /ENOENT/);
|
||||
assert.throws(() => readFileSync(path.join(target, 'checksum.sha256')), /ENOENT/);
|
||||
});
|
||||
|
||||
test('未启用入口不调用数据库且拒绝额外命令参数', () => {
|
||||
const root = makeTemporaryDirectory();
|
||||
const envFile = path.join(root, 'development.env');
|
||||
writeFileSync(
|
||||
envFile,
|
||||
'APP_ENV=development\nMYSQL_ENABLED=false\nMYSQL_DATABASE=a_share_analysis_dev\nMYSQL_CHARSET=utf8mb4\nMYSQL_COLLATION=utf8mb4_general_ci\n',
|
||||
);
|
||||
let executionCount = 0;
|
||||
|
||||
const result = runBaselineGeneration({
|
||||
repositoryRoot: root,
|
||||
envFile,
|
||||
applicationVersion: 'v0.0.5',
|
||||
gitCommit: validMetadata.gitCommit,
|
||||
generatedAt: validMetadata.generatedAt,
|
||||
executeFile() {
|
||||
executionCount += 1;
|
||||
throw new Error('未启用路径不应执行数据库命令');
|
||||
},
|
||||
});
|
||||
|
||||
assert.equal(result.status, 'not_applicable');
|
||||
assert.equal(executionCount, 0);
|
||||
assert.throws(
|
||||
() => runBaselineGeneration({ ...result, commandArguments: ['--env', 'production.env'] }),
|
||||
/不接受命令参数/,
|
||||
);
|
||||
});
|
||||
|
||||
test('启用入口分别校验 mysql 与 mysqldump 客户端版本', () => {
|
||||
const root = makeTemporaryDirectory();
|
||||
const envFile = path.join(root, 'development.env');
|
||||
writeFileSync(
|
||||
envFile,
|
||||
Object.entries(validConfig)
|
||||
.map(([key, value]) => `${key}=${value}`)
|
||||
.join('\n'),
|
||||
);
|
||||
|
||||
assert.throws(
|
||||
() =>
|
||||
runBaselineGeneration({
|
||||
repositoryRoot: root,
|
||||
envFile,
|
||||
applicationVersion: 'v0.0.5',
|
||||
gitCommit: validMetadata.gitCommit,
|
||||
generatedAt: validMetadata.generatedAt,
|
||||
executeFile(command, args) {
|
||||
if (args[0] === '--version') {
|
||||
return command === 'mysql'
|
||||
? 'mysql Ver 8.0.39 for macos'
|
||||
: 'mysqldump Ver 10.13 Distrib 5.7.44, for macos';
|
||||
}
|
||||
if (command === 'mysql') {
|
||||
return '5.7.44-log\tutf8mb4\tutf8mb4_general_ci\n';
|
||||
}
|
||||
return 'CREATE TABLE `sample` (`id` int);\n';
|
||||
},
|
||||
}),
|
||||
/mysql 客户端必须为 5\.7/,
|
||||
);
|
||||
});
|
||||
|
||||
test('幂等重跑仍核对清单提交与发布标签提交', () => {
|
||||
const root = makeTemporaryDirectory();
|
||||
const envFile = path.join(root, 'development.env');
|
||||
writeFileSync(
|
||||
envFile,
|
||||
'APP_ENV=development\nMYSQL_ENABLED=false\nMYSQL_DATABASE=a_share_analysis_dev\nMYSQL_CHARSET=utf8mb4\nMYSQL_COLLATION=utf8mb4_general_ci\n',
|
||||
);
|
||||
const target = path.join(root, 'database', 'schema-baselines', 'v0.0.5');
|
||||
persistBaselineArtifacts(target, buildNotApplicableArtifacts(validMetadata));
|
||||
|
||||
assert.throws(
|
||||
() =>
|
||||
runBaselineGeneration({
|
||||
repositoryRoot: root,
|
||||
envFile,
|
||||
applicationVersion: 'v0.0.5',
|
||||
gitCommit: 'ffffffffffffffffffffffffffffffffffffffff',
|
||||
}),
|
||||
/提交与发布标签不一致/,
|
||||
);
|
||||
});
|
||||
|
||||
test('校验能发现 SQL 被修改且生成阶段拒绝空基线', () => {
|
||||
const root = makeTemporaryDirectory();
|
||||
const target = path.join(root, 'v0.0.5');
|
||||
persistBaselineArtifacts(
|
||||
target,
|
||||
buildCapturedArtifacts(validMetadata, 'CREATE TABLE `sample` (`id` int);\n'),
|
||||
);
|
||||
writeFileSync(path.join(target, 'schema.sql'), 'CREATE TABLE `tampered` (`id` int);\n');
|
||||
assert.throws(() => verifyBaselineDirectory(target, 'v0.0.5'), /校验值不一致/);
|
||||
|
||||
assert.throws(
|
||||
() => buildCapturedArtifacts({ ...validMetadata, applicationVersion: 'v0.0.4' }, ''),
|
||||
/不能为空/,
|
||||
);
|
||||
});
|
||||
|
||||
test('基线清单中的提交必须等于发布标签指向的提交', () => {
|
||||
const root = makeTemporaryDirectory();
|
||||
const target = path.join(root, 'v0.0.5');
|
||||
persistBaselineArtifacts(target, buildNotApplicableArtifacts(validMetadata));
|
||||
|
||||
assert.throws(
|
||||
() => verifyBaselineDirectory(target, 'v0.0.5', 'ffffffffffffffffffffffffffffffffffffffff'),
|
||||
/提交与发布标签不一致/,
|
||||
);
|
||||
});
|
||||
|
||||
test('校验拒绝篡改成错误 MySQL 版本或伪造对象范围的真实清单', () => {
|
||||
const root = makeTemporaryDirectory();
|
||||
const target = path.join(root, 'v0.0.5');
|
||||
persistBaselineArtifacts(
|
||||
target,
|
||||
buildCapturedArtifacts(validMetadata, 'CREATE TABLE `sample` (`id` int);\n'),
|
||||
);
|
||||
const manifestPath = path.join(target, 'manifest.yaml');
|
||||
const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
|
||||
manifest.mysql_server_version = '8.0.39';
|
||||
writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
|
||||
assert.throws(() => verifyBaselineDirectory(target, 'v0.0.5'), /服务端必须为 5\.7/);
|
||||
|
||||
manifest.mysql_server_version = '5.7.44-log';
|
||||
manifest.objects.events = false;
|
||||
writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
|
||||
assert.throws(() => verifyBaselineDirectory(target, 'v0.0.5'), /events/);
|
||||
});
|
||||
|
||||
test('不适用清单必须明确记录 MySQL 未启用且所有对象未捕获', () => {
|
||||
const root = makeTemporaryDirectory();
|
||||
const target = path.join(root, 'v0.0.5');
|
||||
persistBaselineArtifacts(target, buildNotApplicableArtifacts(validMetadata));
|
||||
const manifestPath = path.join(target, 'manifest.yaml');
|
||||
const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
|
||||
manifest.mysql_server_version = '5.7.44';
|
||||
manifest.objects.tables = true;
|
||||
writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
|
||||
|
||||
assert.throws(() => verifyBaselineDirectory(target, 'v0.0.5'), /不适用清单/);
|
||||
});
|
||||
|
||||
test('不适用清单拒绝未知对象键和伪造的格式元数据', () => {
|
||||
const root = makeTemporaryDirectory();
|
||||
const target = path.join(root, 'v0.0.5');
|
||||
persistBaselineArtifacts(target, buildNotApplicableArtifacts(validMetadata));
|
||||
const manifestPath = path.join(target, 'manifest.yaml');
|
||||
const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
|
||||
manifest.format_version = 999;
|
||||
manifest.generator = 'unknown';
|
||||
manifest.schema_sha256 = 'forged';
|
||||
manifest.objects = { a: false, b: false, c: false, d: false, e: false };
|
||||
writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
|
||||
|
||||
assert.throws(() => verifyBaselineDirectory(target, 'v0.0.5'), /清单格式/);
|
||||
});
|
||||
|
||||
test('不适用基线只在当前开发环境仍关闭 MySQL 时有效', () => {
|
||||
const root = makeTemporaryDirectory();
|
||||
const envDirectory = path.join(root, 'deploy', 'env', 'development');
|
||||
const envFile = path.join(envDirectory, 'api.env.example');
|
||||
const result = { status: 'not_applicable' };
|
||||
|
||||
mkdirSync(envDirectory, { recursive: true });
|
||||
writeFileSync(
|
||||
envFile,
|
||||
'APP_ENV=development\nMYSQL_ENABLED=false\nMYSQL_DATABASE=a_share_analysis_dev\nMYSQL_CHARSET=utf8mb4\nMYSQL_COLLATION=utf8mb4_general_ci\n',
|
||||
);
|
||||
assert.doesNotThrow(() =>
|
||||
assertNotApplicableMatchesDevelopmentConfiguration(root, result),
|
||||
);
|
||||
|
||||
writeFileSync(
|
||||
envFile,
|
||||
Object.entries(validConfig)
|
||||
.map(([key, value]) => `${key}=${value}`)
|
||||
.join('\n'),
|
||||
);
|
||||
assert.throws(
|
||||
() => assertNotApplicableMatchesDevelopmentConfiguration(root, result),
|
||||
/已启用 MySQL.*not_applicable/,
|
||||
);
|
||||
});
|
||||
|
||||
test('严格发布门禁通过已提交且远程同步的当前基线', () => {
|
||||
assert.doesNotThrow(() => assertCurrentReleasedBaselinePublished(process.cwd()));
|
||||
});
|
||||
|
||||
test('远程分支校验实时读取 origin 而不是陈旧 tracking ref', () => {
|
||||
assert.doesNotThrow(() =>
|
||||
assertRemoteBranchMatches('/repo', 'main', (_root, args) => {
|
||||
assert.deepEqual(args, ['ls-remote', 'origin', 'refs/heads/main']);
|
||||
return 'abc123\trefs/heads/main';
|
||||
}, 'abc123'),
|
||||
);
|
||||
assert.throws(
|
||||
() =>
|
||||
assertRemoteBranchMatches('/repo', 'main', () => 'def456\trefs/heads/main', 'abc123'),
|
||||
/尚未完整推送到 origin/,
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,151 @@
|
||||
import assert from 'node:assert/strict';
|
||||
import { readFile } from 'node:fs/promises';
|
||||
import test from 'node:test';
|
||||
|
||||
const repoRoot = new URL('../../', import.meta.url);
|
||||
const processNames = ['api', 'scheduler', 'worker', 'web'];
|
||||
const sensitiveKeyPattern = /(PASSWORD|API_KEY|TOKEN|SECRET)$/;
|
||||
|
||||
async function readRepoFile(relativePath) {
|
||||
return readFile(new URL(relativePath, repoRoot), 'utf8');
|
||||
}
|
||||
|
||||
function parseEnvTemplate(content) {
|
||||
const entries = new Map();
|
||||
|
||||
for (const line of content.split(/\r?\n/)) {
|
||||
const normalizedLine = line.trim();
|
||||
if (!normalizedLine || normalizedLine.startsWith('#')) continue;
|
||||
|
||||
const separator = normalizedLine.indexOf('=');
|
||||
assert.ok(separator > 0, `无效环境变量行：${line}`);
|
||||
entries.set(normalizedLine.slice(0, separator), normalizedLine.slice(separator + 1));
|
||||
}
|
||||
|
||||
return entries;
|
||||
}
|
||||
|
||||
test('开发和生产环境都提供四类进程模板且键集合一致', async () => {
|
||||
for (const processName of processNames) {
|
||||
const development = parseEnvTemplate(
|
||||
await readRepoFile(`deploy/env/development/${processName}.env.example`),
|
||||
);
|
||||
const production = parseEnvTemplate(
|
||||
await readRepoFile(`deploy/env/production/${processName}.env.example`),
|
||||
);
|
||||
|
||||
assert.deepEqual([...development.keys()].sort(), [...production.keys()].sort());
|
||||
}
|
||||
});
|
||||
|
||||
test('模板不包含敏感值且 Web 只暴露 VITE 变量', async () => {
|
||||
for (const environment of ['development', 'production']) {
|
||||
for (const processName of processNames) {
|
||||
const entries = parseEnvTemplate(
|
||||
await readRepoFile(`deploy/env/${environment}/${processName}.env.example`),
|
||||
);
|
||||
|
||||
for (const [key, value] of entries) {
|
||||
if (sensitiveKeyPattern.test(key)) assert.equal(value, '', `${key} 必须保持空值`);
|
||||
if (processName === 'web') assert.ok(key.startsWith('VITE_'), `Web 禁止暴露 ${key}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
test('生产模板禁止模拟数据并保持 MySQL 5.7 与 RocketMQ 配置契约', async () => {
|
||||
const rocketMqTemplates = new Map();
|
||||
for (const environment of ['development', 'production']) {
|
||||
for (const processName of ['scheduler', 'worker']) {
|
||||
rocketMqTemplates.set(
|
||||
`${environment}/${processName}`,
|
||||
parseEnvTemplate(
|
||||
await readRepoFile(`deploy/env/${environment}/${processName}.env.example`),
|
||||
),
|
||||
);
|
||||
}
|
||||
}
|
||||
const developmentScheduler = rocketMqTemplates.get('development/scheduler');
|
||||
const developmentWorker = rocketMqTemplates.get('development/worker');
|
||||
const productionScheduler = rocketMqTemplates.get('production/scheduler');
|
||||
const worker = parseEnvTemplate(await readRepoFile('deploy/env/production/worker.env.example'));
|
||||
|
||||
assert.equal(worker.get('APP_ENV'), 'production');
|
||||
assert.equal(worker.get('MARKET_DATA_MODE'), 'live');
|
||||
assert.equal(worker.get('MYSQL_ENABLED'), 'false');
|
||||
assert.equal(worker.get('MYSQL_CHARSET'), 'utf8mb4');
|
||||
assert.equal(worker.get('MYSQL_COLLATION'), 'utf8mb4_general_ci');
|
||||
assert.equal(worker.get('ROCKETMQ_ENABLED'), 'false');
|
||||
assert.equal(worker.get('ROCKETMQ_ENDPOINT'), '');
|
||||
assert.equal(worker.get('ROCKETMQ_TOPIC_PREFIX'), 'a-share-analysis');
|
||||
assert.equal(worker.get('ROCKETMQ_CONSUMER_GROUP'), 'a-share-analysis-worker');
|
||||
for (const [templateName, entries] of rocketMqTemplates) {
|
||||
assert.equal(
|
||||
[...entries.keys()].some((key) => key.startsWith('RABBITMQ_')),
|
||||
false,
|
||||
`${templateName} 禁止保留 RabbitMQ 变量`,
|
||||
);
|
||||
assert.equal(entries.has('ROCKETMQ_PRODUCER_GROUP'), false);
|
||||
assert.equal(entries.has('ROCKETMQ_MAX_RECONSUME_TIMES'), false);
|
||||
}
|
||||
for (const entries of [developmentScheduler, developmentWorker]) {
|
||||
assert.equal(entries.get('ROCKETMQ_NAMESRV_ADDR'), '127.0.0.1:9876');
|
||||
assert.equal(entries.get('ROCKETMQ_ENDPOINT'), '127.0.0.1:8081');
|
||||
}
|
||||
for (const entries of [productionScheduler, worker]) {
|
||||
assert.equal(entries.get('ROCKETMQ_NAMESRV_ADDR'), '');
|
||||
assert.equal(entries.get('ROCKETMQ_ENDPOINT'), '');
|
||||
}
|
||||
});
|
||||
|
||||
test('本地 Compose 仅启动 Redis 并提供健康检查', async () => {
|
||||
const compose = await readRepoFile('deploy/compose/development.yml');
|
||||
|
||||
assert.match(compose, /services:\s*\n\s+redis:/);
|
||||
assert.match(compose, /healthcheck:/);
|
||||
assert.match(compose, /127\.0\.0\.1:/);
|
||||
assert.doesNotMatch(compose, /^\s{2}(mysql|rocketmq|api|worker|scheduler|web):/m);
|
||||
});
|
||||
|
||||
test('活动架构与部署文档只采用 RocketMQ 5.x', async () => {
|
||||
for (const relativePath of [
|
||||
'README.md',
|
||||
'docs/architecture/system-architecture.md',
|
||||
'docs/governance/code-development-standards.md',
|
||||
'docs/deployment/local-development.md',
|
||||
'docs/deployment/docker-compose-production.md',
|
||||
'docs/deployment/ubuntu-source-production.md',
|
||||
]) {
|
||||
const content = await readRepoFile(relativePath);
|
||||
assert.match(content, /RocketMQ 5\.x|RocketMQ/);
|
||||
assert.doesNotMatch(content, /RabbitMQ/);
|
||||
}
|
||||
});
|
||||
|
||||
test('生产源码部署使用独立 EnvironmentFile 并提供 Nginx 代理', async () => {
|
||||
for (const processName of ['api', 'scheduler', 'worker']) {
|
||||
const unit = await readRepoFile(`deploy/systemd/a-share-${processName}.service.example`);
|
||||
assert.match(unit, new RegExp(`EnvironmentFile=/etc/a-share-analysis/${processName}\\.env`));
|
||||
assert.match(unit, /User=a-share/);
|
||||
assert.match(unit, /WorkingDirectory=\/opt\/a-share-analysis\/current/);
|
||||
}
|
||||
|
||||
const nginx = await readRepoFile('deploy/nginx/a-share-analysis.conf.example');
|
||||
assert.match(nginx, /location \/api\//);
|
||||
assert.match(nginx, /proxy_pass http:\/\/127\.0\.0\.1:3000/);
|
||||
assert.match(nginx, /\/opt\/a-share-analysis\/current\/web\/dist/);
|
||||
});
|
||||
|
||||
test('部署文档覆盖本地、Compose 生产和 Ubuntu 源码生产', async () => {
|
||||
const local = await readRepoFile('docs/deployment/local-development.md');
|
||||
const compose = await readRepoFile('docs/deployment/docker-compose-production.md');
|
||||
const source = await readRepoFile('docs/deployment/ubuntu-source-production.md');
|
||||
|
||||
assert.match(local, /Redis/);
|
||||
assert.match(compose, /Docker Compose/);
|
||||
assert.match(source, /Ubuntu 22\.04 LTS/);
|
||||
assert.match(source, /Ubuntu 24\.04 LTS/);
|
||||
assert.match(source, /Node\.js 22 LTS/);
|
||||
assert.match(source, /pnpm 10/);
|
||||
assert.match(source, /不负责安装/);
|
||||
});
|
||||
@@ -34,6 +34,10 @@ function run(command, args) {
|
||||
* 根目录 verify 脚本会继续串联前端和后端测试，而不需要改变本门禁入口。
|
||||
*/
|
||||
run('npm', ['run', 'test:governance']);
|
||||
run('npm', ['run', 'test:mysql-baseline']);
|
||||
run('npm', ['run', 'test:environment-baseline']);
|
||||
run('npm', ['run', 'test:schema-baseline']);
|
||||
run('npm', ['run', 'schema:verify']);
|
||||
run('npx', ['gitnexus', 'analyze']);
|
||||
|
||||
const status = run('npx', ['gitnexus', 'status']);
|
||||
|
||||
@@ -2,6 +2,7 @@ import { execFileSync } from 'node:child_process';
|
||||
import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
import { assertCurrentReleasedBaselinePublished } from '../database/schema-baseline.mjs';
|
||||
import { getFeatureDirectory, validateFeatureId } from './feature-record.mjs';
|
||||
|
||||
const [featureId, slug] = process.argv.slice(2);
|
||||
@@ -15,6 +16,10 @@ const featureDirectory = getFeatureDirectory(repositoryRoot, featureId, slug);
|
||||
const gitnexusDirectory = path.join(featureDirectory, 'gitnexus');
|
||||
const beforeReport = path.join(gitnexusDirectory, 'before.md');
|
||||
|
||||
// Schema 基线必须在新版本的功能档案和 GitNexus 分析之前已经独立提交；
|
||||
// 这里仅做只读验证，绝不在一般功能开发命令中连接数据库或静默生成历史产物。
|
||||
assertCurrentReleasedBaselinePublished(repositoryRoot);
|
||||
|
||||
if (existsSync(beforeReport)) {
|
||||
throw new Error(`开发前报告已存在，为保护历史不会覆盖：${beforeReport}`);
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user