From d53d818e412348b37a075a54369812fa5f8f89e7 Mon Sep 17 00:00:00 2001
From: cfdaily <cfdaily@gitee.com>
Date: Wed, 29 Apr 2026 20:18:15 +0800
Subject: [PATCH] auto-sync: 2026-04-29 20:18:15

---
 docs/02-architecture.md | 136 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 136 insertions(+)
 create mode 100644 docs/02-architecture.md

diff --git a/docs/02-architecture.md b/docs/02-architecture.md
new file mode 100644
index 00000000..f8077dc2
--- /dev/null
+++ b/docs/02-architecture.md
@@ -0,0 +1,136 @@
+# 02 - 系统架构设计
+
+**版本**: v1.0
+**日期**: 2026-04-29
+
+---
+
+## 1. 架构总览
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     三国量化团队（7个Agent）                    │
+│  诸葛亮 · 庞统 · 张飞 · 关羽 · 赵云 · 司马懿 · 姜维            │
+└───────────┬─────────────────────────────────┬───────────────┘
+            │ 提交策略                         │ 查看结果
+            ▼                                 ▼
+┌───────────────────────┐         ┌───────────────────┐
+│   回测API服务          │         │  OpenClaw Gateway  │
+│   FastAPI :8088       │         │  任务调度/通信      │
+│   /api/backtest/*     │         └───────────────────┘
+└───────────┬───────────┘
+            │ 调用
+            ▼
+┌───────────────────────┐
+│   vnpy BacktestingEngine │  ← vnpy 4.x原生回测引擎
+│   CTA策略回测            │
+└───────────┬───────────┘
+            │ 读取数据
+            ▼
+┌───────────────────────┐
+│   数据层               │
+│   SQLite / akshare     │  ← 本地数据 + 实时数据
+└───────────────────────┘
+
+            所有服务运行在：
+┌─────────────────────────────────────┐
+│        群晖 NAS Docker 容器           │
+│  192.168.2.154                       │
+│  sanguo_vnpy:with-scripts 镜像       │
+│  restart: unless-stopped             │
+└─────────────────────────────────────┘
+```
+
+## 2. 分层架构
+
+```
+┌────────────────────────────────────┐
+│  适配层 (src/)                      │  ← 我们的代码
+│  ├── backtest-service/  回测API服务  │
+│  ├── adapters/          数据适配器   │
+│  └── scripts/           启动脚本     │
+├────────────────────────────────────┤
+│  vnpy框架层 (pip install vnpy)      │  ← 开源框架，不修改
+│  ├── BacktestingEngine  回测引擎     │
+│  ├── CtaTemplate       策略基类      │
+│  ├── BaseDatafeed      数据接口      │
+│  └── BaseGateway       交易网关      │
+├────────────────────────────────────┤
+│  基础设施层 (docker/)               │
+│  ├── Dockerfile         镜像构建     │
+│  ├── entrypoint.sh      容器启动     │
+│  └── requirements/      依赖管理     │
+└────────────────────────────────────┘
+```
+
+## 3. 核心设计决策
+
+### 3.1 适配层 vs Fork
+
+| 方案 | 适用场景 | 当前选择 |
+|------|---------|---------|
+| **适配层**（继承/封装） | 新策略、新数据源、新网关 | ✅ 当前采用 |
+| **Fork vnpy** | 修改回测引擎核心、修改事件机制 | 🔜 预留 |
+
+原则：优先通过继承和封装实现需求，vnpy接口不满足时再考虑fork。
+
+### 3.2 数据架构
+
+```
+数据获取层（赵云负责）
+    │
+    ├── akshare（实时行情）
+    ├── tushare（历史数据）
+    └── 本地CSV/Parquet
+    │
+    ▼
+数据适配层（src/adapters/）
+    │
+    ├── vnpy_local_data_adapter.py  ← 实现BaseDatafeed接口
+    │
+    ▼
+数据存储层
+    │
+    └── SQLite（vnpy标准数据库）
+```
+
+### 3.3 多用户隔离
+
+每个用户独立进程对，通过Nginx反向代理统一入口：
+
+```
+用户        RPC端口   Web端口   Nginx路径
+诸葛亮       2010      8001     /zhugeliang/
+庞统         2020      8002     /pangtong/
+司马懿       2030      8003     /simayi/
+张飞         2040      8004     /zhangfei/
+关羽         2050      8005     /guanyu/
+赵云         2060      8006     /zhaoyun/
+姜维         2070      8007     /jiangwei/
+```
+
+### 3.4 容器化部署
+
+```
+sanguo_vnpy 容器
+├── 8888  Jupyter Lab（开发环境）
+├── 8088  回测API服务（FastAPI）
+├── 8000  WebTrader（预留）
+├── 2222  SSH（运维通道）
+└── /app/scripts/backtest_service  ← volume挂载代码
+```
+
+## 4. 技术选型
+
+| 组件 | 选型 | 理由 |
+|------|------|------|
+| 量化框架 | vn.py 4.x | 开源、社区活跃、架构成熟 |
+| API服务 | FastAPI + uvicorn | 异步高性能、自动文档 |
+| 数据库 | SQLite | 轻量、vnpy原生支持 |
+| 数据源 | akshare + tushare | 免费A股数据 |
+| 容器 | Docker | 环境隔离、可移植 |
+| 部署 | 群晖NAS | 团队已有硬件、7×24运行 |
+
+---
+
+*下一步：[03-detailed-design.md](03-detailed-design.md)*