myquant/docs/architecture.md

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）

文档索引

文档	内容
使用指南	各模块使用方法和代码示例
开发指南	环境搭建、开发约定、模块说明
因子与表结构速查	34 因子注册表、DB 表结构、数据源接口
数据层详解	DataManager、数据库、缓存策略、已知 Bug
因子引擎详解	因子计算、情绪引擎、新闻源
回测引擎详解	VectorBT、策略、信号工具、Optuna
ML 模型详解	特征工程、LightGBM/CatBoost、ML 策略
Agent 系统详解	Agent 架构、CLI、日报
部署说明	本地环境、服务器、uWSGI、rsync 部署
DJAPI 接口	Django API 端点参考
日报查询 API	news/reports + news/events 接口