feat(GOV-008): 采用 RocketMQ 消息队列架构
This commit is contained in:
@@ -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。
|
||||
- 需要顺序处理的消息必须明确消息组键，例如证券代码或交易日；未声明顺序键时不得依赖全局到达顺序。
|
||||
- 金额、成交额和比率必须明确单位，避免同一字段混用元、万元、亿元或百分比小数。
|
||||
- 数据来源、采集时间、交易日期、完整性和口径版本必须可追溯。
|
||||
|
||||
@@ -88,14 +90,14 @@ count += 1;
|
||||
- API、Scheduler、Worker 必须使用各自的配置 Schema，在进程启动时验证类型、格式、范围和条件必填项；配置错误立即退出。
|
||||
- 同一进程的开发与生产模板必须保持相同变量名。环境差异通过配置值、依赖注入和 Adapter 收敛，禁止在业务代码中散落 `APP_ENV` 分支。
|
||||
- 只有 `*.env.example` 可以提交；真实 `.env`、`*.env.local`、密码、Token 和 API Key 必须被 Git 忽略并由运行环境注入。
|
||||
- Web 只能使用公开的 `VITE_*` 变量。数据库、Redis、RabbitMQ、数据源和 AI 凭据禁止进入前端变量或构建产物。
|
||||
- MySQL、RabbitMQ、正式数据源与 AI 使用显式功能开关；关闭时连接变量可为空，开启后缺少任何必填值都必须拒绝启动。
|
||||
- Web 只能使用公开的 `VITE_*` 变量。数据库、Redis、RocketMQ、数据源和 AI 凭据禁止进入前端变量或构建产物。
|
||||
- MySQL、RocketMQ、正式数据源与 AI 使用显式功能开关；关闭时连接变量可为空，开启后缺少任何必填值都必须拒绝启动。
|
||||
- Docker Compose 与源码部署必须复用同一变量契约，禁止为某种部署方式建立语义不同的别名。
|
||||
- 生产配置必须位于发布目录之外，切换应用版本不得覆盖配置；日志和诊断输出必须对配置值脱敏。
|
||||
|
||||
## 9. 前端规范
|
||||
|
||||
- 页面不得直接访问第三方行情源、Redis、RabbitMQ 或 AI 服务。
|
||||
- 页面不得直接访问第三方行情源、Redis、RocketMQ 或 AI 服务。
|
||||
- 全局服务器状态使用 TanStack Vue Query，本地界面偏好使用 Pinia或轻量组合式函数。
|
||||
- Sass token集中管理颜色、间距、圆角、字号和断点。
|
||||
- A 股默认红涨绿跌，但状态必须同时提供文字或形状，不能只依赖颜色。
|
||||
@@ -105,8 +107,11 @@ count += 1;
|
||||
## 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 统一为内部模型，上层不得依赖供应商原始字段。
|
||||
|
||||
## 11. MySQL 5.7 兼容规范
|
||||
@@ -137,7 +142,7 @@ count += 1;
|
||||
- 功能和缺陷修复遵循测试先行：先看到测试因缺少行为而失败，再实现最小代码。
|
||||
- 纯规则和指标计算使用单元测试，期望值必须手工推导。
|
||||
- 数据源 Adapter 使用契约测试和固定样本。
|
||||
- HTTP 与 RabbitMQ 使用契约测试。
|
||||
- HTTP 与 RocketMQ 使用契约测试；消息测试必须覆盖 Topic、Tag、Group、序列化、重复投递、重试和死信边界。
|
||||
- 关键页面使用 Playwright流程测试和视觉截图对比。
|
||||
- 合并前必须通过类型检查、测试、构建和适用的视觉验证。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user