# 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 接口 |