# 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（异步 Job 状态机）
FastAPI (backend：业务对象 API，见下「核心能力」)
   ↓ Research Specification（统一研究契约）
Application Service（SelectionService / SignalService / ResearchService / Strategy …）
   ├── Selection Engine（条件选股 / 因子评分 / as_of 历史与当前一致）
   ├── Signal Engine（BUY / WATCH / SELL + 理由）
   ├── Portfolio Engine（等权；约束预留并如实标注）
   └── Quant Service ── Composite Engine ── Qlib Adapter ── Qlib
              ↓                        ↓
        Repository / DAO           MySQL（默认）/ Parquet
```

### 目录结构

```text
qlib/
├── backend/            # FastAPI 后端（uv 管理，Python 3.12）
│   ├── app/
│   │   ├── api/                # HTTP API 层（面向业务对象，禁止暴露 Qlib/SQL）
│   │   ├── application/        # 用例 / 应用服务（编排，不含框架细节）
│   │   ├── domain/             # 领域实体 + Repository Protocol
│   │   ├── infrastructure/     # SQLAlchemy / Alembic 等基础设施实现
│   │   ├── quant/             # 因子 / composite / universe / selection / signal / portfolio 引擎
│   │   │   └── 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
```

### 数据库（默认 MySQL）

- 连接在根目录 `config.yaml → database.mysql`（host/port/db/user/charset），密码放 `.env` 的
  `MYSQL_PASSWORD`；URL 优先级：`DATABASE_URL` 环境变量 > `database.mysql` > SQLite 兜底。
- 结构变更（Model → Migration → Test）：

```bash
cd backend
uv run alembic upgrade head          # 在当前配置指向的库上建表（默认 MySQL qlib）
uv run alembic revision --autogenerate -m "add xxx table"
```

## 核心能力（现状）

| 能力 | 说明 / 入口 |
|---|---|
| 股票筛选 | `POST /api/selections`（A 条件选股 / B 因子评分 TopN，`as_of` 当前/历史，结果可解释可复现）；Web `/selection` |
| 因子目录 | `factor_definition` 落库；`GET /api/factors`；组合可保存复用 `POST /api/composites` |
| 因子研究 | Job 异步 IC / RankIC / 分层测试（`/api/jobs`） |
| 交易信号 | `POST /api/signals`：评分排名 + 趋势规则 → BUY/WATCH/SELL + 理由；Web `/signals` |
| 选股回测 | `POST /api/backtests`（成本/涨跌停近似；与当前选股共用同一评分引擎，v2 §25 一致性） |
| 策略资产 | `strategy` 落库 + `/api/strategies`（命名配置，可展开为回测 spec） |
| Experiment | 每次研究自动归档 + 一键复跑 + SSE 进度 |
| AI Agent | `POST /api/agent/chat`，10 个受控 Tool（含 screen_stocks / explain_selection / generate_signals / create_strategy） |

## 里程碑（详见 [ROADMAP.md](./docs/ROADMAP.md) 与 [docs/DEV_PLAN_v2.md](./docs/DEV_PLAN_v2.md)）

- **M0–M5**：工程骨架 → 数据层 → 研究引擎 → Web → Experiment/Job → AI Agent
- **M-DB**：SQLite 全量迁移 MySQL（config.yaml 配置化 + 迁移工具 + 一致性校验）
- **M6**：选股系统主线（Universe + Selection A/B + 落库/API + 回测共用 + Web）
- **M7**：因子层（因子定义入库 + Composite 模块化 + 行情口径显式化）
- **M8**：Signal / Portfolio / Strategy / Agent 工具 / Web 做实（M8.4 Qlib 模型选股按需延后）

## 约定速查

- 回答与文档使用中文
- 一切时间相关数据防「未来函数」：财务数据区分 `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 直接暴露给前端