Simon
0ffd574f30
- docs/DEV_PLAN_v2.md：基于 ARCHITECTURE_v2 与 M0-M5 现状的下一阶段计划 （M-DB 迁移收尾 → M6 因子定义入库/复合因子/口径修复 → M7 Selection/Signal/ Portfolio 引擎分层 → M8 Strategy 平台化/Web 做实/Agent 工具补齐；含本机 Redis 127.0.0.1:6379 的接入触发点与执行顺序） - ROADMAP.md：登记 M-DB 里程碑并指向 DEV_PLAN_v2 - USAGE.md / README.md：数据库描述由 SQLite 更新为 MySQL（config.yaml database.mysql）
103 lines
4.5 KiB
Markdown
103 lines
4.5 KiB
Markdown
# qlib-platform
|
||
|
||
个人 A 股量化研究平台：**选股 · 因子研究 · 回测**，面向低频 / 中低频交易研究。
|
||
|
||
> 核心量化引擎：[Qlib](https://github.com/microsoft/qlib) · 首选数据源：Tushare（新浪财经为备用）· 当前数据库：MySQL（业务层无感切换；SQLite 仅兜底）
|
||
|
||
## 定位
|
||
|
||
- 个人开发项目，中低频选股 / 因子 / 组合回测
|
||
- **不做**高频交易、不做过度的微服务化
|
||
- 以 Qlib 为研究引擎，但 Qlib 只是计算引擎而不是整个系统
|
||
- AI Agent（Phase 5）只能通过受控 Tool 调用研究能力
|
||
|
||
## 架构
|
||
|
||
详见 [AGENT.md](./AGENT.md)（开发约束）与 [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md)（架构文档），**改代码前必须阅读**。
|
||
|
||
```text
|
||
Web 前端 (frontend/web)
|
||
↓ REST / SSE
|
||
FastAPI (backend)
|
||
↓ Research Specification
|
||
Application Service ── Quant Service ── Qlib Adapter ── Qlib
|
||
↓ ↓
|
||
Repository / DAO Parquet / MySQL
|
||
```
|
||
|
||
### 目录结构
|
||
|
||
```text
|
||
qlib/
|
||
├── backend/ # FastAPI 后端（uv 管理，Python 3.12）
|
||
│ ├── app/
|
||
│ │ ├── api/ # HTTP API 层（面向业务对象，禁止暴露 Qlib/SQL）
|
||
│ │ ├── application/ # 用例 / 应用服务（编排，不含框架细节）
|
||
│ │ ├── domain/ # 领域实体 + Repository Protocol
|
||
│ │ ├── infrastructure/ # SQLAlchemy / Alembic 等基础设施实现
|
||
│ │ ├── quant/qlib_adapter/ # Qlib 适配层（业务禁止直接 import qlib）
|
||
│ │ ├── agent/ # AI Research Agent（Phase 5，仅 Tool 访问）
|
||
│ │ └── core/ # 配置、通用组件
|
||
│ └── tests/
|
||
├── frontend/web/ # React / Next.js 前端（Phase 3 初始化）
|
||
├── data/ # raw / normalized / parquet / qlib（不入库，gitignore）
|
||
├── experiments/ # 实验产物（不入库，gitignore）
|
||
├── scripts/ # 数据同步、运维脚本
|
||
├── docker/ # 部署（Phase 后引入，第一阶段不过度工程）
|
||
├── docs/
|
||
├── AGENT.md
|
||
├── config.yaml # 可配置项（无密钥）
|
||
└── .env.example # 密钥模板（复制为 .env，勿提交）
|
||
```
|
||
|
||
## 使用说明
|
||
|
||
完整使用文档（安装 / 配置 / 数据同步 / API / Agent / 常见问题）见 **[docs/USAGE.md](./docs/USAGE.md)**。
|
||
|
||
## 快速开始（后端）
|
||
|
||
前置：安装 [uv](https://docs.astral.sh/uv/)（`pip install uv` 或官方脚本）。
|
||
|
||
```bash
|
||
# 1. 配置密钥（复制模板，填入 TUSHARE_TOKEN 等）
|
||
cp .env.example .env
|
||
|
||
# 2. 安装依赖（自动使用 Python 3.12，见 backend/.python-version）
|
||
cd backend
|
||
uv sync # 含 pyqlib（GitHub 源码依赖，固定 commit）。若网络下载困难/超时，按 AGENT.md §0 设置代理 192.168.1.160:3128 后重试
|
||
|
||
# 3. 运行测试
|
||
uv run pytest
|
||
|
||
# 4. 启动开发服务
|
||
uv run uvicorn app.main:app --reload --port 8000
|
||
# 健康检查：http://127.0.0.1:8000/api/health
|
||
# 交互文档：http://127.0.0.1:8000/docs
|
||
```
|
||
|
||
### 数据库迁移（Alembic，已就位）
|
||
|
||
```bash
|
||
cd backend
|
||
uv run alembic upgrade head # 首次运行会在 data/quant.db 建立版本表
|
||
uv run alembic revision --autogenerate -m "add xxx table" # 修改 Model 后生成迁移
|
||
```
|
||
|
||
## 开发阶段（对应架构文档 §20）
|
||
|
||
- **Phase 1 数据**：Tushare → 标准化 → MySQL（stock / daily / 复权因子 / 交易日历 / 财务指标），Parquet 导出
|
||
- **Phase 2 Qlib**：Parquet → Qlib Dataset → 因子（Alpha158 / 自定义）→ LightGBM → 回测
|
||
- **Phase 3 Web**：股票池 / 因子研究 / 选股 / 回测 / 结果可视化（Next.js + ECharts）
|
||
- **Phase 4 Experiment**：所有研究自动可复现存档
|
||
- **Phase 5 AI Agent**：自然语言 → Research Plan → 受控 Tool → Experiment
|
||
|
||
## 约定速查
|
||
|
||
- 回答与文档使用中文
|
||
- 一切时间相关数据防「未来函数」：财务数据区分 `report_date` / `announce_date`，查询支持 `as_of_date`
|
||
- 数据源必须经 `MarketDataProvider`（Tushare 优先，Sina 兜底且记录来源），业务层禁止直接 import 新浪 / Tushare 实现
|
||
- 业务层禁止直接操作 sqlite3 / SQL / SQLAlchemy Session，只能走 Repository
|
||
- 新表：Model → Alembic Migration → Test
|
||
- 禁止修改 site-packages/qlib 源码，一律走 Adapter / Wrapper
|
||
- API 输入输出用 Pydantic DTO，禁止把 ORM Model 直接暴露给前端
|