a-share-analysis/docs/architecture/system-architecture.md

系统架构

1. 仓库结构

项目采用单 Git 仓库、前后端独立项目和独立部署：

web/        Vue 3 前端
server/     NestJS API、Scheduler 与 Worker
contracts/  HTTP 与 RabbitMQ 版本化契约
deploy/     MySQL、Redis、RabbitMQ 和运行配置
docs/       规范、架构、ADR 与功能档案
tools/      可重复执行的治理和开发工具

选择单仓库是为了让跨前端、后端、消息和部署的同一功能处于一个原子 Git 版本及一张 GitNexus 图谱中；保持独立项目是为了允许单独构建、部署和扩容。

2. 运行边界

免费数据源
  → Scheduler 定时投递
  → RabbitMQ
  → 行情采集 Worker
  → 指标计算 Worker
  → 规则 / AI / 混合分析
  → MySQL 历史事实 + Redis 当前快照
  → NestJS API
  → Vue 3 前端

• Scheduler只负责触发时间。
• RabbitMQ只负责任务传递、确认、重试和死信。
• Worker负责采集、标准化、计算和分析。
• MySQL保存可追溯事实与历史报告。
• Redis保存最新快照、缓存、锁和限流状态。
• Vue前端只读后端 API，不直接接触外部数据源和密钥。

3. 数据库技术基线

• 数据库服务端固定使用 MySQL 5.7.x，开发、测试和生产环境禁止使用 MySQL 8.x 代替兼容性验证。
• 数据库与表默认字符集固定为 utf8mb4，排序规则固定为 utf8mb4_general_ci。
• 数据库初始化、表结构、连接会话、ORM 配置和迁移脚本必须显式声明或验证该字符集与排序规则，不能依赖服务器默认值。
• 正式启用持久化前，必须在真实 MySQL 5.7 环境验证服务端版本、Schema/表排序规则、迁移和关键查询。
• 第一阶段市场概览只定义 MySQL Repository 接口并使用内存实现，不启动数据库、不建立生产连接；后续启用时不得改变前端 API 和核心分析契约。

4. 当前实施顺序

第一阶段先实现可交互的市场综合概览和稳定数据契约，再接入正式行情采集链路。用户、邀请、权限、会员和支付后置，不进入当前核心架构。

5. 环境与部署基线

• 应用运行环境只定义 development 与 production；生产环境禁止模拟数据、热更新、调试端口和开发默认值回退。
• API、Scheduler、Worker、Web 分别拥有开发和生产模板；同一进程跨环境使用相同变量名，通过启动 Schema 校验条件必填项。
• 本地开发使用 Docker Compose 只启动 Redis，应用进程从源码运行；第一阶段 MySQL 与 RabbitMQ 保持关闭。
• 生产同时支持 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/，不随代码版本切换覆盖。