qlib-platform

个人 A 股量化研究平台：选股 · 因子研究 · 回测，面向低频 / 中低频交易研究。

核心量化引擎：Qlib · 首选数据源：Tushare（新浪财经为备用）· 当前数据库：SQLite（未来 MySQL，业务层无感切换）

定位

• 个人开发项目，中低频选股 / 因子 / 组合回测
• 不做高频交易、不做过度的微服务化
• 以 Qlib 为研究引擎，但 Qlib 只是计算引擎而不是整个系统
• AI Agent（Phase 5）只能通过受控 Tool 调用研究能力

架构

详见 AGENT.md（开发约束）与 docs/ARCHITECTURE.md（架构文档），改代码前必须阅读。

Web 前端 (frontend/web)
   ↓ REST / SSE
FastAPI (backend)
   ↓ Research Specification
Application Service ── Quant Service ── Qlib Adapter ── Qlib
   ↓                    ↓
Repository / DAO      Parquet / SQLite

目录结构

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。

快速开始（后端）

前置：安装 uv（pip install uv 或官方脚本）。

# 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，已就位）

cd backend
uv run alembic upgrade head          # 首次运行会在 data/quant.db 建立版本表
uv run alembic revision --autogenerate -m "add xxx table"   # 修改 Model 后生成迁移

开发阶段（对应架构文档 §20）

• Phase 1 数据：Tushare → 标准化 → SQLite（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 直接暴露给前端