81 lines
4.4 KiB
Markdown
81 lines
4.4 KiB
Markdown
# 系统架构
|
||
|
||
## 1. 仓库结构
|
||
|
||
项目采用单 Git 仓库、前后端独立项目和独立部署：
|
||
|
||
```text
|
||
web/ Vue 3 前端
|
||
server/ NestJS API、Scheduler 与 Worker
|
||
server/openapi/ HTTP OpenAPI 产物
|
||
server/libs/http-contracts/ 后端 HTTP DTO
|
||
server/libs/message-contracts/ 后端 RocketMQ 版本化契约
|
||
deploy/ MySQL、Redis、RocketMQ 5.x 和运行配置
|
||
docs/ 规范、架构、ADR 与功能档案
|
||
tools/ 可重复执行的治理和开发工具
|
||
```
|
||
|
||
选择单仓库是为了让跨前端、后端、消息和部署的同一功能处于一个原子 Git 版本及一张 GitNexus 图谱中；保持独立项目是为了允许单独构建、部署和扩容。
|
||
|
||
## 2. 运行边界
|
||
|
||
```text
|
||
免费数据源
|
||
→ Scheduler 定时投递
|
||
→ MessageBusAdapter
|
||
→ RocketMQ 5.x
|
||
→ 行情采集 Worker
|
||
→ 指标计算 Worker
|
||
→ 规则 / AI / 混合分析
|
||
→ MySQL 历史事实 + Redis 当前快照
|
||
→ NestJS API
|
||
→ Vue 3 前端
|
||
```
|
||
|
||
- Scheduler只负责触发时间。
|
||
- MessageBusAdapter 隔离业务与 RocketMQ 客户端，禁止业务模块直接依赖 SDK。
|
||
- RocketMQ 只负责任务传递、确认、重试、延迟消息和死信；重复投递由 Worker 幂等处理。
|
||
- Worker负责采集、标准化、计算和分析。
|
||
- MySQL保存可追溯事实与历史报告。
|
||
- Redis保存最新快照、缓存、锁和限流状态。
|
||
- Vue前端只读后端 API，不直接接触外部数据源和密钥。
|
||
|
||
## 3. 前后端模块边界
|
||
|
||
后端以业务模块为一级目录，模块内部按实际职责建立 Controller、Service、DTO、Domain、Repository 和 Adapter。小模块不强制凑齐目录，禁止把全部 Controller/Service 堆入全局目录，也禁止无业务逻辑的透传层。领域规则只依赖项目端口，MySQL、Redis、RocketMQ、免费数据源和 AI Provider 由基础设施 Adapter 实现。
|
||
|
||
前端 HTTP 数据流固定为：
|
||
|
||
```text
|
||
NestJS DTO 与 Swagger 元数据
|
||
→ server/openapi/openapi.json
|
||
→ openapi-typescript 生成 web/src/api/generated/schema.ts
|
||
→ web/src/api/<业务域>/index.ts
|
||
→ web/src/utils/request.ts（Axios）
|
||
→ 功能 adapter / ViewModel
|
||
→ 页面、组件和 Store
|
||
```
|
||
|
||
OpenAPI 负责描述本项目 HTTP 契约，Axios 负责浏览器实际请求。页面、组件、Store 和 Composable 不直接发 HTTP。兼容 OpenAI API 指未来后端 AI Provider 的外部协议，与前端请求库无关。
|
||
|
||
## 4. 数据库技术基线
|
||
|
||
- 数据库服务端固定使用 MySQL 5.7.42；开发、测试和生产环境禁止使用其他补丁版本或 MySQL 8.x 代替兼容性验证。
|
||
- 数据库与表默认字符集固定为 `utf8mb4`，排序规则固定为 `utf8mb4_general_ci`。
|
||
- 数据库初始化、表结构、连接会话、ORM 配置和迁移脚本必须显式声明或验证该字符集与排序规则，不能依赖服务器默认值。
|
||
- 正式启用持久化前，必须在真实 MySQL 5.7 环境验证服务端版本、Schema/表排序规则、迁移和关键查询。
|
||
- 第一阶段市场概览只定义 MySQL Repository 接口并使用内存实现，不启动数据库、不建立生产连接；后续启用时不得改变前端 API 和核心分析契约。
|
||
|
||
## 5. 当前实施顺序
|
||
|
||
第一阶段先实现可交互的市场综合概览和稳定数据契约，再接入正式行情采集链路。用户、邀请、权限、会员和支付后置，不进入当前核心架构。
|
||
|
||
## 6. 环境与部署基线
|
||
|
||
- 应用运行环境只定义 `development` 与 `production`；生产环境禁止模拟数据、热更新、调试端口和开发默认值回退。
|
||
- API、Scheduler、Worker、Web 分别拥有开发和生产模板；同一进程跨环境使用相同变量名，通过启动 Schema 校验条件必填项。
|
||
- 本地开发直接连接开发机已开机自启的 Redis `127.0.0.1:6379`，应用进程从源码运行；第一阶段 MySQL 与 RocketMQ 保持关闭，需要联调时连接开发者独立维护的外部服务。
|
||
- 生产只支持 Ubuntu 22.04/24.04 LTS x86_64 源码部署，不提供容器运行、构建、测试或部署入口。
|
||
- 源码部署由管理员预装 Node.js 22.x、pnpm 10.25.0、Nginx 和外部基础设施；项目只验证，不安装、启动、停止或删除系统服务。
|
||
- 源码部署使用不可变发布目录、`a-share` 用户和 systemd 独立进程配置；生产 env 存放在 `/etc/a-share-analysis/`，不随代码版本切换覆盖。
|