Simon
6acf938caf
- 删除 11 个残留文件: continuation.md, init_plan.md, reasonix.toml, djapi/continuation.md, djapi/.serena/, djapi/.claude/, djapi/.mcp.json, .claude/skills/, docs/usage.html, docs/db_schema.md, docs/report_db_design.md - 7 个 CLAUDE-*.md 移入 docs/ 并重命名去 CLAUDE- 前缀 - 新增 4 个文档: architecture.md, development.md, api.md, deployment.md - 重写 usage.md, README.md - 修复所有过时引用和交叉链接
196 lines
9.0 KiB
Markdown
196 lines
9.0 KiB
Markdown
# cc-cursor 项目架构
|
||
|
||
## 概述
|
||
|
||
cc-cursor 是一个 Mac Mini 单机量化研究平台，覆盖从数据获取到策略报告的全链路量化研究流程。
|
||
|
||
## 项目布局
|
||
|
||
```
|
||
cc-cursor/ # 项目根目录
|
||
│
|
||
├── finance/ # 🔥 核心量化引擎（代码实际位置）
|
||
│ ├── config/ # 全局配置：.env 加载、数据库/API 路径
|
||
│ ├── database/ # 数据库层：ORM 模型、SQLAlchemy 连接、DAO
|
||
│ ├── data/ # 数据层：DataManager 统一入口
|
||
│ │ └── sources/ # Tushare + AkShare 双数据源实现
|
||
│ ├── factors/ # 因子引擎：34 个注册因子
|
||
│ │ ├── technical/ # 技术因子（动量、RSI、MACD、布林等 10 类）
|
||
│ │ ├── fundamental/ # 基本面因子（ROE、PE、PB、EP）
|
||
│ │ └── sentiment/ # 情绪因子（Qwen NLP + 三源新闻聚合）
|
||
│ ├── backtest/ # 回测引擎：VectorBT 封装
|
||
│ │ ├── vectorbt/ # VectorBT 引擎适配
|
||
│ │ └── strategies/ # 5 个内置策略（均线、RSI、动量等）
|
||
│ ├── optimizer/ # 参数优化：Optuna 引擎 + Walk-Forward
|
||
│ ├── models/ # ML 模型：LightGBM + CatBoost + 特征工程
|
||
│ │ ├── lightgbm/ # LightGBM 模型封装
|
||
│ │ └── catboost/ # CatBoost 模型封装
|
||
│ ├── agents/ # Agent 系统：4 个 Agent + 编排器
|
||
│ ├── cli/ # 命令行入口：agent_cli + 7 个 demo 验证脚本
|
||
│ ├── reports/ # 日报输出：daily_YYYYMMDD.md + 存储层
|
||
│ ├── strategy/ # 策略层（空壳占位，仅 __init__.py）
|
||
│ ├── portfolio/ # 组合管理（空壳占位，仅 __init__.py）
|
||
│ ├── execution/ # 执行层（空壳占位，仅 __init__.py）
|
||
│ └── scheduler/ # 调度层（空壳占位，仅 __init__.py）
|
||
│
|
||
├── djapi/ # 🌐 Django API 后端
|
||
│ ├── djapi/ # 项目配置：settings、urls、env_loader
|
||
│ └── api/ # 唯一 Django app
|
||
│ ├── stock/ # A 股数据 API（16 端点）
|
||
│ ├── video/ # 新闻联播视频处理（独立模块）
|
||
│ └── report/ # 日报查询 API（news/reports + news/events）
|
||
│
|
||
├── shared/ # 🔧 共享工具
|
||
│ └── script/ # autossh.sh（MariaDB SSH 隧道）
|
||
│
|
||
├── docs/ # 📚 项目文档（13 个 md 文件）
|
||
│
|
||
├── .claude/ # Claude 配置（空目录，仅保留框架）
|
||
│
|
||
├── .git/ # Git 仓库
|
||
│
|
||
├── README.md # 项目入口文档
|
||
└── .gitignore # Git 忽略规则
|
||
```
|
||
|
||
### 各目录职责
|
||
|
||
| 目录 | 职责 | 状态 |
|
||
|------|------|------|
|
||
| `finance/` | **核心量化引擎**，全链路代码所在地 | ✅ 已实现 |
|
||
| `finance/config/` | 全局配置，`.env` 加载和路径管理 | ✅ |
|
||
| `finance/database/` | MariaDB 连接、ORM 模型、DAO 数据访问 | ✅ |
|
||
| `finance/data/` | 统一数据层，双源（Tushare→AkShare）fallback | ✅ |
|
||
| `finance/factors/` | 因子引擎，34 因子/12 分类（技术+基本面+情绪） | ✅ |
|
||
| `finance/backtest/` | VectorBT 回测，5 策略 + 截面回测 | ✅ |
|
||
| `finance/optimizer/` | Optuna 参数寻优 + Walk-Forward 验证 | ✅ |
|
||
| `finance/models/` | LightGBM/CatBoost ML 模型 + 特征工程 | ✅ |
|
||
| `finance/agents/` | 4 Agent（Research/Selection/Risk/Report）+ 编排器 | ✅ |
|
||
| `finance/cli/` | 命令行入口 + 7 个 demo 验证脚本 | ✅ |
|
||
| `finance/reports/` | 日报输出（daily_YYYYMMDD.md）+ 持久化存储 | ✅ |
|
||
| `finance/strategy/` | 策略层，预留扩展 | 🚧 空壳 |
|
||
| `finance/portfolio/` | 组合管理，预留扩展 | 🚧 空壳 |
|
||
| `finance/execution/` | 执行层，预留扩展 | 🚧 空壳 |
|
||
| `finance/scheduler/` | 调度层，预留扩展 | 🚧 空壳 |
|
||
| `djapi/` | Django API 后端，A 股数据 + 新闻联播 + 日报查询 | ✅ 已部署 |
|
||
| `shared/` | 跨项目共享工具（SSH 隧道脚本） | ✅ |
|
||
| `docs/` | 项目文档，13 个 md 文件 | ✅ |
|
||
|
||
## 数据流
|
||
|
||
```
|
||
Agent 编排层
|
||
├── ResearchAgent ── 因子发现（IC/IC_IR 评估）
|
||
├── SelectionAgent ─ 多因子打分 + ML 预测
|
||
├── RiskAgent ────── 仓位控制 + 风险预警
|
||
└── ReportAgent ──── 自动日报生成
|
||
|
||
基础引擎层
|
||
DataManager ──→ FactorEngine ──→ BaseStrategy ──→ VectorBTEngine ──→ BacktestReport
|
||
│ │ │
|
||
│ FeatureEngine OptunaEngine
|
||
│ │ │
|
||
└──────→ LightGBM/CatBoost ←────────┘
|
||
|
||
情绪增强层
|
||
NewsSource(AkShare/DB/MCP) ──→ QwenClient ──→ SentimentFactor ──→ FactorEngine
|
||
```
|
||
|
||
### 核心数据流
|
||
|
||
```
|
||
Data → Factor → Model → Strategy → Backtest → Report
|
||
```
|
||
|
||
## 设计原则
|
||
|
||
### 模块隔离
|
||
各引擎通过统一接口交互，可替换实现（VectorBT → Backtrader）。
|
||
|
||
### 接口标准化
|
||
- 因子：`calculate(df) → pd.Series`
|
||
- 策略：`generate_signals(df) → pd.Series`
|
||
- 模型：`fit/predict/save/load`
|
||
- 优化：`optimize() → OptimizationResult`
|
||
|
||
### 数据层统一
|
||
策略/模型不直连数据源，全部通过 `DataManager`。禁止：
|
||
- 策略直接访问 AkShare/Tushare
|
||
- 模型直接访问数据库
|
||
|
||
### Agent 不重建轮子
|
||
Agent 通过依赖注入复用已有引擎，编排而非重建。
|
||
|
||
### 防前视偏差
|
||
- 时间序列交叉验证（TimeSeriesSplit）
|
||
- expanding window 统计量
|
||
- 特征工程 fit 在训练集，transform 在测试集
|
||
|
||
## 技术栈
|
||
|
||
| 组件 | 技术 | 说明 |
|
||
|------|------|------|
|
||
| 数据获取 | AkShare + Tushare (双源) | Tushare 优先，AkShare fallback |
|
||
| 数据库 | MariaDB (SSH 隧道) | 本地 13306 → 远程 3306 |
|
||
| 因子/特征 | pandas / numpy / sklearn | — |
|
||
| 回测引擎 | VectorBT 1.0 | 只做多，10 万/万三 |
|
||
| 参数优化 | Optuna 4.9 | Walk-Forward 验证 |
|
||
| ML 模型 | LightGBM 4.6 + CatBoost 1.2 | 统一接口 |
|
||
| NLP 情绪 | Qwen (DashScope / Ollama) | 双后端 |
|
||
| Agent 编排 | 自研编排器 | finance/agents/ |
|
||
| API 后端 | Django 5.2 + uWSGI | djapi/ |
|
||
|
||
## 开发进度
|
||
|
||
| Sprint | 模块 | 状态 |
|
||
|--------|------|------|
|
||
| Sprint 0 | 基础设施（DataManager + MariaDB 3 表） | ✅ |
|
||
| Sprint 1 | 因子引擎（34 因子 / 12 分类） | ✅ |
|
||
| Sprint 2 | VectorBT 回测（5 策略 + 截面 + BacktestReport） | ✅ |
|
||
| Sprint 3 | Optuna 优化（+ Walk-Forward） | ✅ |
|
||
| Sprint 4 | ML 模型（LightGBM + CatBoost + MLStrategy） | ✅ |
|
||
| Sprint 5 | Qwen 情绪因子（三源新闻 + 日期对齐） | ✅ |
|
||
| Sprint 6 | Agent 系统（4 Agent + CLI + 日报 .md/.html） | ✅ |
|
||
| Sprint 7 | djapi API（日报查询 ×2） | ✅ |
|
||
|
||
**全部 8 个 Sprint 已完成。**
|
||
|
||
## 数据源架构
|
||
|
||
### finance/ 引擎层
|
||
```
|
||
DataManager
|
||
├── TushareSource（优先，需 TUSHARE_TOKEN）
|
||
├── AkShareSource（fallback，无需 token）
|
||
└── Database Cache（SQLAlchemy + MariaDB）
|
||
```
|
||
|
||
### djapi/ API 层
|
||
```
|
||
api/stock/data_source.py（统一入口）
|
||
├── get_tushare_pro() — 全局单例
|
||
├── get_daily() — 双源 fallback
|
||
└── get_mysql_db() — MySQL 全局单例
|
||
```
|
||
|
||
## 指数代码规则
|
||
|
||
- `.SH` 结尾且不以 `399` 开头 → 指数（如 `000001.SH`）
|
||
- `.SZ` 开头非 `399` → 个股（如 `000001.SZ`）
|
||
- `399*.SZ` → 指数（如 `399001.SZ`）
|
||
|
||
## 文档索引
|
||
|
||
| 文档 | 内容 |
|
||
|------|------|
|
||
| [使用指南](usage.md) | 各模块使用方法和代码示例 |
|
||
| [开发指南](development.md) | 环境搭建、开发约定、模块说明 |
|
||
| [因子与表结构速查](reference.md) | 34 因子注册表、DB 表结构、数据源接口 |
|
||
| [数据层详解](data-layer.md) | DataManager、数据库、缓存策略、已知 Bug |
|
||
| [因子引擎详解](factors.md) | 因子计算、情绪引擎、新闻源 |
|
||
| [回测引擎详解](backtest.md) | VectorBT、策略、信号工具、Optuna |
|
||
| [ML 模型详解](ml-models.md) | 特征工程、LightGBM/CatBoost、ML 策略 |
|
||
| [Agent 系统详解](agents.md) | Agent 架构、CLI、日报 |
|
||
| [部署说明](deployment.md) | 本地环境、服务器、uWSGI、rsync 部署 |
|
||
| [DJAPI 接口](api.md) | Django API 端点参考 |
|
||
| [日报查询 API](news_report_api.md) | news/reports + news/events 接口 | |