cfdaily
193 lines
9.6 KiB
Markdown
193 lines
9.6 KiB
Markdown
# sanguo_vnpy 项目目录整理提案（修订版）
|
||
|
||
**提案人**: 姜维（平台总督）
|
||
**日期**: 2026-04-29
|
||
**状态**: 待确认
|
||
|
||
---
|
||
|
||
## 一、项目定位理解
|
||
|
||
**sanguo_vnpy = 基于vnpy框架构建的三国量化全流程平台**
|
||
|
||
### 核心目标
|
||
基于vnpy开源框架进行适配，构建投研→策略开发→模拟→实盘的全流程量化交易平台。
|
||
|
||
### 已完成的适配成果
|
||
1. **vnpy 4.x 回测服务**：基于BacktestingEngine封装的API化回测服务（scripts/backtest-service/）
|
||
2. **本地数据适配器**：vnpy_local_data_adapter.py，本地数据集成方案
|
||
3. **Docker容器化部署**：Dockerfile + entrypoint.sh，NAS群晖Docker运行
|
||
4. **NAS多用户架构**：config/（nginx+systemd），7个用户隔离配置
|
||
5. **edict任务管理集成**：浅集成方案，看板可视化
|
||
6. **自动化部署流程**：jiangwei-platform/deploy/nas/ 部署全流程脚本
|
||
|
||
### 远期目标
|
||
- 聚宽/QMT多风格兼容适配
|
||
- 策略开发标准化流程
|
||
- 模拟交易验证
|
||
- 实盘交易接入
|
||
|
||
---
|
||
|
||
## 二、现状分析
|
||
|
||
### 目录与文件统计
|
||
|
||
| 目录 | 文件数 | 大小 | 成果物？ | 说明 |
|
||
|------|--------|------|---------|------|
|
||
| `scripts/backtest-service/` | 9 | 核心 | ✅ | **回测服务核心代码**，vnpy 4.x适配 |
|
||
| `scripts/start_*.py` | 3 | 核心 | ✅ | 启动脚本（RPC/Web/回测） |
|
||
| `scripts/utils/` | 30 | 辅助 | ⚠️ | 数据适配器+调试工具混杂 |
|
||
| `scripts/deployment/` | 37 | 辅助 | ⚠️ | 部署脚本（部分仍在用，部分过时） |
|
||
| `scripts/verify/` | 2 | 辅助 | ⚠️ | 验证脚本 |
|
||
| `docker/` | 5 | 核心 | ✅ | Dockerfile+entrypoint+requirements |
|
||
| `config/` | 21 | 核心 | ✅ | NAS多用户nginx+systemd配置 |
|
||
| `jiangwei-platform/deploy/` | 11 | 核心 | ✅ | NAS部署全流程（脚本+模板+文档） |
|
||
| `research/` | 39 | 参考 | ⚠️ | 调研报告+过程文件混杂 |
|
||
| `test/` | 88 | 调试 | ❌ | 大量v2/v3/v4重复测试脚本 |
|
||
| `archives/` | 4 | 废弃 | ❌ | 旧Docker镜像tar(90M)+pid文件 |
|
||
| `logs/` | 8 | 废弃 | ❌ | 历史调试日志 |
|
||
| `backup/` | 0 | 空目录 | ❌ | 空目录 |
|
||
| 根目录*.log | 3 | 废弃 | ❌ | auto-sync日志(4.6M) |
|
||
| `data/` | 1 | 数据 | ✅ | quant_trading.db |
|
||
|
||
---
|
||
|
||
## 三、整理提案
|
||
|
||
### 设计原则
|
||
|
||
1. **面向vnpy适配开发**：目录结构要体现"基于vnpy构建"的定位
|
||
2. **保留所有有价值成果物**：核心代码、配置、调研报告
|
||
3. **只移动不删除**：清理的文件进archive/，保持原结构可追溯
|
||
4. **不涉及NAS端**：只整理本地仓库
|
||
|
||
### 目标目录结构
|
||
|
||
```
|
||
sanguo_vnpy/
|
||
├── README.md # 项目总说明（新建，描述项目定位和架构）
|
||
│
|
||
├── docker/ # Docker镜像构建
|
||
│ ├── Dockerfile # 镜像定义
|
||
│ ├── entrypoint.sh # 容器启动脚本（含pip自动安装）
|
||
│ └── requirements/ # Python依赖
|
||
│
|
||
├── src/ # 🔥 平台核心代码（新增顶层目录）
|
||
│ ├── backtest-service/ # vnpy 4.x回测服务（从scripts/提升）
|
||
│ │ ├── main.py # FastAPI入口
|
||
│ │ ├── api.py # API路由
|
||
│ │ ├── executor.py # vnpy回测执行器
|
||
│ │ ├── models.py # 数据模型
|
||
│ │ ├── config.py # 配置
|
||
│ │ ├── task_queue.py # 任务队列
|
||
│ │ └── result_storage.py # 结果存储
|
||
│ ├── adapters/ # vnpy适配层（从scripts/utils/提取）
|
||
│ │ └── vnpy_local_data_adapter.py # 本地数据适配器
|
||
│ └── scripts/ # 启动脚本
|
||
│ ├── start_backtest_service.py
|
||
│ ├── start_rpc_server.py
|
||
│ └── start_web_trader.py
|
||
│
|
||
├── config/ # NAS部署配置（原位保留）
|
||
│ ├── nginx/ # 7个用户nginx配置
|
||
│ └── systemd/ # 14个systemd服务文件
|
||
│
|
||
├── deploy/ # 部署相关（从jiangwei-platform/提升）
|
||
│ └── nas/ # NAS部署全流程
|
||
│ ├── create-user.sh
|
||
│ ├── create-all-users.sh
|
||
│ ├── generate-all-configs.sh
|
||
│ ├── deploy-plan.md
|
||
│ ├── deploy-log.md
|
||
│ ├── port-allocation.md
|
||
│ └── templates/
|
||
│
|
||
├── research/ # 调研文档（清理后保留）
|
||
│ ├── vnpy/ # vnpy框架调研
|
||
│ │ ├── vnpy本地数据集成方案.md
|
||
│ │ ├── edict集成完成总结.md
|
||
│ │ ├── 服务使用说明文档.md
|
||
│ │ ├── edict-adapter-scheme.md # （从research/根目录移入）
|
||
│ │ ├── 三国edict浅集成执行流程.md
|
||
│ │ ├── 安装vnpy解决方案.md
|
||
│ │ ├── 回测API_bug修复报告.md
|
||
│ │ ├── final_fix_summary.md
|
||
│ │ ├── 修复完成通知.md
|
||
│ │ ├── 赵云数据转换指南.md
|
||
│ │ └── final/ # （从vnpy/删除空目录，保留现有文件）
|
||
│ ├── nas/ # NAS部署调研
|
||
│ ├── docker/ # Docker相关调研
|
||
│ ├── jq_essence_articles/ # 聚宽精华文章
|
||
│ └── webtrader/ # （从task-20260331重命名）
|
||
│ ├── vnpy-webtrader-research-report.md
|
||
│ └── nas-deployment-architecture-analysis.md
|
||
│
|
||
├── data/ # 数据（原位保留）
|
||
│
|
||
├── archive/ # 归档（新增，存放清理出的历史文件）
|
||
│ └── 2026-04-29-cleanup/ # 按日期归档，保持原目录结构
|
||
│ ├── test/ # 88个测试脚本
|
||
│ ├── scripts/deployment/ # 37个部署脚本
|
||
│ ├── scripts/utils/ # 30个工具脚本（非核心的）
|
||
│ ├── scripts/verify/ # 2个验证脚本
|
||
│ ├── logs/ # 历史日志
|
||
│ └── research/ # 过程文件
|
||
│
|
||
└── .gitignore # （更新，忽略*.log等）
|
||
```
|
||
|
||
### 操作清单
|
||
|
||
| # | 操作 | 文件数 | 风险 | 说明 |
|
||
|---|------|--------|------|------|
|
||
| **1** | **新建 src/ 核心目录** | - | 无 | 体现vnpy适配开发结构 |
|
||
| **2** | **scripts/backtest-service/ → src/backtest-service/** | 9 | 低 | 回测服务核心代码提升到src/ |
|
||
| **3** | **scripts/utils/vnpy_local_data_adapter.py → src/adapters/** | 1 | 低 | 数据适配器归入适配层 |
|
||
| **4** | **scripts/start_*.py → src/scripts/** | 3 | 低 | 启动脚本提升 |
|
||
| **5** | **jiangwei-platform/deploy/ → deploy/** | 11 | 低 | 部署相关提升到顶层 |
|
||
| **6** | **research/edict-adapter-scheme.md → research/vnpy/** | 1 | 无 | 归类到vnpy目录 |
|
||
| **7** | **research/task-20260331-vnpy-webtrader-research/ → research/webtrader/** | 2 | 无 | 重命名为更清晰的名称 |
|
||
| **8** | **test/ 全部 → archive/2026-04-29-cleanup/test/** | 88 | 低 | 重复测试脚本归档 |
|
||
| **9** | **scripts/deployment/ → archive/** | 37 | 低 | 过时部署脚本归档 |
|
||
| **10** | **scripts/utils/（非核心）→ archive/** | 29 | 低 | 保留vnpy_local_data_adapter.py后归档 |
|
||
| **11** | **scripts/verify/ → archive/** | 2 | 低 | 验证脚本归档 |
|
||
| **12** | **删除 archives/（旧镜像tar）** | 4 | 无 | 90M旧文件，已无用 |
|
||
| **13** | **删除根目录 *.log + logs/** | 11 | 无 | 垃圾日志 |
|
||
| **14** | **删除 backup/ 空目录** | 0 | 无 | 空目录 |
|
||
| **15** | **删除 models.py.bak** | 1 | 无 | 备份文件 |
|
||
| **16** | **新建 README.md** | 1 | 无 | 项目总说明 |
|
||
| **17** | **更新 .gitignore** | 1 | 无 | 忽略*.log等 |
|
||
|
||
### 关键说明
|
||
|
||
1. **NAS端兼容**：NAS上挂载的是 `/volume1/stock/sanguo_vnpy/bt-service/` 和 `entrypoint.sh`，与本地 `scripts/backtest-service/` 是独立的两份。本地目录调整不影响NAS运行。但后续需要同步更新entrypoint.sh中的路径引用。
|
||
|
||
2. **scripts/deployment/ 中的有用脚本**：`nas_manager.sh`、`copy_and_start.sh` 等可能仍在使用，整理时会检查并保留活跃脚本到 `deploy/` 目录。
|
||
|
||
3. **研究文档保留策略**：research/下的文档按主题归入子目录（vnpy/nas/docker/webtrader/jq），删除散落在根目录的过程文件（如scrape脚本移到archive）。
|
||
|
||
---
|
||
|
||
## 四、预计效果
|
||
|
||
| 指标 | 整理前 | 整理后 |
|
||
|------|--------|--------|
|
||
| 总文件数 | 279 | ~80 |
|
||
| 根目录内容 | 4个log + 1个md + 9个目录 | 1个README + 7个目录 |
|
||
| 核心代码位置 | scripts/backtest-service/ | src/backtest-service/ |
|
||
| 目录语义 | 混乱，大量调试噪音 | 清晰，体现vnpy适配开发定位 |
|
||
| 磁盘占用 | ~95M | ~5M |
|
||
|
||
---
|
||
|
||
## 五、需要注意的点
|
||
|
||
1. **git历史保留**：所有操作通过 `git mv` 执行，保留完整历史
|
||
2. **NAS同步检查**：整理后确认auto-sync不会破坏NAS上的文件
|
||
3. **README.md内容**：需要描述项目定位（基于vnpy的全流程量化平台）、已完成适配、架构设计、使用方法
|
||
|
||
---
|
||
|
||
**请确认是否同意此方案，或需要调整的地方。确认后立即执行。**
|