# a-stock

**Repository Path**: mingwuda/a-stock

## Basic Information

- **Project Name**: a-stock
- **Description**: No description available
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-31
- **Last Updated**: 2026-04-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# A 股全栈量化交易系统

这是一个可本地运行的 A 股量化交易演示系统，包含：

- FastAPI 后端：行情数据获取、策略分析、历史回测、任务状态管理、RESTful API
- 原生 HTML/CSS/JavaScript 前端：AI 选股主工作台、单票回测辅助页、K 线图、收益曲线、回撤曲线、指标图、交易明细
- A 股规则适配：T+1、涨跌停、交易时段、100 股整手、手续费与印花税
- 免费开源数据源：`MooTdx`

> 说明：本项目仅做研究和教学演示，不接入任何实盘交易接口，也不会下单。

## 1. 项目结构

```text
a-stock/
├── docker-compose.yml
├── .dockerignore
├── backend/
│   ├── app/
│   │   ├── api/
│   │   ├── core/
│   │   ├── services/
│   │   ├── main.py
│   │   └── schemas.py
│   ├── Dockerfile
│   └── requirements.txt
├── frontend/
│   ├── assets/
│   │   ├── app.js
│   │   └── styles.css
│   ├── Dockerfile
│   ├── nginx.conf
│   └── index.html
├── data/
│   └── cache/
└── README.md
```

## 2. 功能清单

### 后端

- 历史行情获取：支持日线与分钟线
- 实时行情拉取：最新价、开高低收、成交量、成交额
- 策略引擎：双均线、MACD、KDJ、网格策略
- 自定义参数：前端可调策略参数、仓位、止盈止损
- 历史回测：输出收益、年化、最大回撤、胜率、夏普比率、交易明细
- 后台任务：支持一键启动回测、轮询结果、发送停止请求
- 本地 SQLite：记录回测任务摘要
- AI 智能选股：多因子评分（趋势/动量/资金/价值/风险）+ 风格切换（稳健/进取/短线）
- 底层强制风控过滤：ST/亏损/低流动性/高位过热/高波动/公告风险/次新过滤
- 历史暴跌压力测试：输出风险等级、跌停风险评分、极端回撤快照
- 批量回测：对 AI 股票池一键批量回测，并限制单票仓位不超过 10%
- 全市场股票池：默认基于沪深 A 股全市场缓存 universe 运行，自动过滤 ST / 退市整理 / 非个股代码
- MooTdx 自愈：连接失败时会自动尝试 `python -m mootdx bestip` 后重连，降低首次启动失败率
- Qlib 增量引擎（无侵入）：独立 `qlib_engine` 服务，提供数据同步、Alpha158 因子、模型训练/预测、Qlib 回测
- Qlib 自动训练：后台定时训练 + 手工立即触发 + 断点续训状态管理
- Qlib 失败可见性：同步失败 / 因子失败股票会落盘并返回到前端状态面板
- ML 日决策闭环：基于 Qlib ML + 多因子融合，每天只输出次日最可能上涨的 `Top3`
- 次日自动复盘：复盘上一轮推荐是否有效，并给出原因分析与改进建议

### 前端

- 顶部导航：`AI 智能选股` 与 `单股回测` 两个工作区切换
- AI 选股主工作台：风格、TopN、因子窗口、批量资金参数设置
- AI 核心结果区：股票池得分、入选理由、风险等级、跌停风险评分
- AI 辅助验证区：对 AI 股票池一键批量回测，并展示收益、回撤、夏普、交易次数
- 单股回测：单票辅助回测面板置顶，实时行情、规则摘要在下方辅助查看
- 联动跳转：批量回测结果支持“打开单股回测”，自动切换并触发该股票单股回测
- Qlib 自动训练面板：显示训练范围、阶段、阶段细分、进度、失败股票、最近一次训练摘要
- 手工触发训练：用户可在界面点击“立即训练一次”或“继续上次训练”
- ML 日决策闭环：展示今日 Top3、昨日复盘、原因分析与改进建议
- Qlib 嵌入模块：训练状态、预测排名、因子有效性与 Qlib 回测联动
- 数据图表：K 线 + 买卖点、资金曲线、回撤曲线、技术指标
- 结果展示：指标卡片、交易明细表

## 3.1 Qlib 增量集成说明

- 采用无侵入式增量开发：原有 API、策略、回测、AI 选股、前端页面均保留
- Qlib 功能以新增接口形式提供，不替换原有数据拉取逻辑（仍兼容 MooTdx/原数据链路）
- 新增模块路径：`backend/app/services/qlib_engine.py`
- 本地存储路径：`data/qlib/`（包含 `synced/`, `factors/`, `models/`, `reports/`）
- 因子体系：提供 Alpha158 标准命名特征 (`alpha158_001` \~ `alpha158_158`)
- 模型体系：支持 `LightGBM`、`XGBoost` 回归训练，损失函数为 `MSE`
- 训练增强：可选 `Optuna` 超参优化，`MLflow` 实验跟踪（依赖安装后自动启用）
- 自动训练：后端启动后自动进入调度循环，可定时训练，也支持接口手工触发
- 断点续训：会保留 `run_state.json`、`synced_symbols.json`、`factor_symbols.json` 与失败清单
- 因子处理：因子分片会按流式方式做采样、统计、截面均值和结果写出，避免一次性拼接全市场大表
- 因子缓存格式：原始因子分片与预处理结果默认落为 `parquet` 分片目录，避免单个超大 `csv`
- 训练缓存：训练前会按 `horizon` 预先切出 `train_h*/valid_h*` 分片目录，后续恢复训练优先复用
- 并发策略：`syncing`、因子生成、因子采样/统计/截面均值/写出结果、训练前切分缓存均支持并发处理
- 状态接口：`/api/qlib/status` 会返回 `progress/current_stage/message/failures/resume_*` 等字段，供前端实时展示

## 3. A 股规则实现说明

- `T+1`：日线回测中，买入后最早下一交易日才允许卖出
- `涨跌停`：主板按 `10%`，创业板/科创板按 `20%`，北交所按 `30%`
- `交易时段`：`09:30-11:30`、`13:00-15:00`
- `整手交易`：按 `100` 股整数倍买入
- `费用`：
  - 佣金：默认万 `3`，最低 `5` 元
  - 印花税：卖出单边 `0.05%`
  - 过户费：`0.001%`

## 4. 运行环境

- 推荐 Python `3.11` 或 `3.12`
- 不建议直接使用 Python `3.14` 安装量化依赖，`numpy/pandas/mootdx` 可能会退回源码构建，安装时间明显变长
- 推荐使用虚拟环境

## 5. 安装依赖

```bash
cd /Users/zhangming/code/a-stock
python3 -m venv .venv
source .venv/bin/activate
pip install -r backend/requirements.txt
```

也可以直接使用 `Makefile`：

```bash
cd /Users/zhangming/code/a-stock
make install PYTHON=python3.11
```

如需启用 Qlib 全量能力（模型训练/预测/因子增强），额外安装：

```bash
cd /Users/zhangming/code/a-stock
source .venv/bin/activate
pip install -r backend/requirements-qlib.txt
```

## 6. Docker Compose 运行（推荐）

如果你希望本地以容器方式部署，请使用：

```bash
cd /Users/zhangming/code/a-stock
docker compose up -d --build
```

启动后访问：

- 前端（Nginx，同源代理 API）：<http://127.0.0.1:5173>
- 后端 API 文档：<http://127.0.0.1:8000/docs>
- 健康检查：<http://127.0.0.1:8000/api/health>

常用命令：

```bash
# 查看服务状态
docker compose ps

# 查看日志
docker compose logs -f backend
docker compose logs -f frontend

# 停止服务
docker compose down
```

说明：

- `backend` 容器运行 FastAPI，端口映射 `8000:8000`
- `frontend` 容器运行 Nginx，端口映射 `5173:80`
- `frontend` 会把 `/api/*` 反向代理到 `backend:8000`，浏览器侧无跨域问题
- `./data/mootdx` 会挂载到容器内 `/root/.mootdx`，用于持久化 MooTdx 配置
- `./data` 会挂载到容器内 `/app/data`，用于缓存和 SQLite 数据
- `backend` 构建参数默认 `INSTALL_QLIB_DEPS=1` 且 `QLIB_STRICT_INSTALL=0`：Qlib 依赖安装失败时不阻塞基础服务启动（Qlib接口会提示依赖缺失）；如需强制安装成功才构建，通过 `QLIB_STRICT_INSTALL=1` 开启严格模式

### Podman 运行补充

如果你使用的是 `podman compose`，建议优先使用和 `docker compose` 等价的命令：

```bash
cd /Users/zhangming/code/a-stock
podman compose build backend frontend
podman compose up -d backend frontend
```

若你修改了镜像但发现容器仍在跑旧版本，可以显式替换容器：

```bash
podman rm -f a_stock_frontend a_stock_backend
podman compose up -d backend
podman compose up -d frontend
```

如果 `Qlib` 全市场训练期间经常出现容器退出码 `137`，通常意味着 Podman 虚拟机内存不足。可以提高 Podman machine 内存，例如：

```bash
podman machine stop
podman machine set -m 8192
podman machine start
```

当前项目的全市场 `Qlib` 训练更推荐直接使用 `8GiB` 内存；如果仍然频繁出现 `137`，再继续观察训练阶段日志与当前因子并发度。

如果你使用了最新镜像，后端容器时区应为 `Asia/Shanghai`，可通过以下命令确认：

```bash
podman exec a_stock_backend date
```

## 7. 启动后端

```bash
cd /Users/zhangming/code/a-stock
source .venv/bin/activate
uvicorn backend.app.main:app --reload --host 127.0.0.1 --port 8000
```

启动后可访问：

- API 文档：<http://127.0.0.1:8000/docs>
- 健康检查：<http://127.0.0.1:8000/api/health>
- 同源前端入口：<http://127.0.0.1:8000>

## 8. 启动前端

前端是独立静态页面，可单独启动：

```bash
cd /Users/zhangming/code/a-stock
python3 -m http.server 5173 --directory frontend
```

浏览器打开：

- <http://127.0.0.1:5173>
- 或直接使用后端托管的同源页面 <http://127.0.0.1:8000>

## 9. 一键启动

推荐直接使用一键脚本或 `Makefile`：

```bash
cd /Users/zhangming/code/a-stock
chmod +x start.sh
./start.sh
```

或：

```bash
cd /Users/zhangming/code/a-stock
make dev
```

说明：

- 脚本会优先寻找 `python3.12` / `python3.11`，如果本机只有 `python3` 也会继续执行，并给出兼容性提示
- 若 `.venv` 不存在会自动创建
- 若依赖未安装会自动执行安装
- 会同时启动后端 `8000` 和前端 `5173`
- 按 `Ctrl+C` 会自动停止两个服务
- 运行日志输出到项目根目录下的 `.backend.log` 和 `.frontend.log`
- 如果你本机同时装了多个 Python，也可以显式指定：`PYTHON=python3.11 ./start.sh`
- 如果系统只有 Python `3.14`，脚本会自动加上 `PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1` 以兼容 `pydantic-core` 构建
- 如果浏览器对跨域预检有缓存，优先直接访问同源入口 `http://127.0.0.1:8000`

## 10. 页面结构与使用流程

当前前端默认进入 `AI 智能选股` 页，页面职责如下：

- `AI 智能选股`：主工作区，用于生成股票池、查看 AI 入选理由和风险等级
- `Qlib 自动训练状态`：位于 AI 页面中部，显示训练范围、阶段进度、失败股票和最近一次训练摘要
- `ML 日决策闭环`：位于 AI 页面核心区域，基于最新模型输出次日 `Top3`
- `辅助批量回测`：位于 AI 页面下方，只负责验证股票池历史表现，不作为主入口
- `单股回测`：次级页面，用于做单票详细回测验证，先选股票再看行情和规则

推荐使用顺序：

1. 进入 `AI 智能选股`
2. 选择风格、股票池数量、因子窗口
3. 点击“执行 AI 选股”
4. 先查看股票池得分、入选理由、风险等级、跌停风险评分
5. 查看 `Qlib 自动训练状态`，确认模型是否已完成训练，必要时手工触发一次训练
6. 在 `ML 日决策闭环` 中生成次日 `Top3`
7. 如需验证整体稳定性，再点击“辅助批量回测”
8. 如需复盘单只股票，可在批量结果点击“打开单股回测”，或手动切换到 `单股回测`

## 11. 使用示例

以贵州茅台 `600519` 为例，推荐这样使用：

1. 先进入 `AI 智能选股`
2. 选择风格，例如 `稳健型`
3. 设置股票池数量和因子窗口
4. 点击“执行 AI 选股”
5. 在 AI 股票池中查看候选股的：
   - 总分
   - 入选理由
   - 风险等级
   - 跌停风险评分
6. 如果需要验证股票池整体表现，点击“辅助批量回测”
7. 在批量结果中点击“打开单股回测”，系统会自动跳转到 `单股回测` 并触发该股票回测
8. 或手动在 `单股回测` 中输入股票代码（例如 `600519`）后启动回测
9. 回测完成后可查看：
   - 累计收益率、年化收益、最大回撤、胜率、夏普比率
   - K 线买卖点
   - 权益曲线、回撤柱状图
   - 技术指标图
   - 每笔交易的买卖明细与盈亏

## 12. 关键 API 示例

### 获取策略列表

```bash
curl http://127.0.0.1:8000/api/strategies
```

### 获取历史行情

```bash
curl "http://127.0.0.1:8000/api/data/history?symbol=600519&start=2024-01-01T00:00:00&end=2024-12-31T23:59:59&interval=1d"
```

### 启动回测

```bash
curl -X POST http://127.0.0.1:8000/api/backtest \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "600519",
    "start_date": "2024-01-01",
    "end_date": "2024-12-31",
    "interval": "1d",
    "strategy": "double_ma",
    "initial_capital": 100000,
    "position_size": 1.0,
    "stop_loss_pct": 0.08,
    "take_profit_pct": 0.15,
    "strategy_params": {
      "fast_window": 5,
      "slow_window": 20
    }
  }'
```

### 查询回测结果

```bash
curl http://127.0.0.1:8000/api/backtest/<job_id>
```

### AI 选股（多因子 + 强制风控）

```bash
curl -X POST http://127.0.0.1:8000/api/ai/select \
  -H "Content-Type: application/json" \
  -d '{
    "style": "stable",
    "top_n": 15,
    "interval": "1d",
    "history_days": 180
  }'
```

### AI 融合选股（多因子 + Qlib ML）

```bash
curl -X POST http://127.0.0.1:8000/api/ai/hybrid-select \
  -H "Content-Type: application/json" \
  -d '{
    "style": "stable",
    "top_n": 10,
    "interval": "1d",
    "history_days": 180,
    "factor_weight": 0.5,
    "ml_weight": 0.5
  }'
```

### AI 股票池批量回测

```bash
curl -X POST http://127.0.0.1:8000/api/ai/batch-backtest \
  -H "Content-Type: application/json" \
  -d '{
    "style": "stable",
    "symbols": ["600519", "600036", "000333"],
    "strategy": "double_ma",
    "start_date": "2024-01-01",
    "end_date": "2024-12-31",
    "interval": "1d",
    "total_capital": 1000000,
    "stop_loss_pct": 0.08,
    "take_profit_pct": 0.15
  }'
```

### Qlib 引擎状态

```bash
curl http://127.0.0.1:8000/api/qlib/status
```

状态接口会返回：

- 全市场训练范围与股票数
- 当前训练阶段、阶段细分、阶段内进度
- 当前正在处理的股票
- 最近一次训练摘要
- 当前失败股票列表
- 断点续训信息

### 手工触发 / 继续 Qlib 训练

```bash
curl -X POST http://127.0.0.1:8000/api/qlib/trigger
```

说明：

- 若存在未完成训练，会优先继续上一次断点
- 若上一次已经完成同步，恢复时会直接复用同步结果，不再重新全量同步
- 若上一次已经生成完因子分片，恢复时会直接复用因子分片，继续做汇总/预处理
- 若当前已有训练在运行，接口会返回“训练任务已在运行中”
- 正常情况下推荐通过 `/api/qlib/status` 轮询查看进度

### Qlib 数据同步

```bash
curl -X POST http://127.0.0.1:8000/api/qlib/sync \
  -H "Content-Type: application/json" \
  -d '{
    "interval": "1d",
    "lookback_days": 720
  }'
```

### Qlib Alpha158 因子计算

```bash
curl -X POST http://127.0.0.1:8000/api/qlib/factors \
  -H "Content-Type: application/json" \
  -d '{
    "interval": "1d",
    "lookback_days": 720,
    "save_snapshot": true
  }'
```

### Qlib 模型训练（MSE 回归）

```bash
curl -X POST http://127.0.0.1:8000/api/qlib/train \
  -H "Content-Type: application/json" \
  -d '{
    "algorithm": "lightgbm",
    "interval": "1d",
    "lookback_days": 720,
    "horizon": 5,
    "auto_optimize": true
  }'
```

### Qlib 预测排名 + 回测

```bash
curl -X POST http://127.0.0.1:8000/api/qlib/predict \
  -H "Content-Type: application/json" \
  -d '{
    "interval": "1d",
    "lookback_days": 720,
    "top_n": 20
  }'

curl -X POST http://127.0.0.1:8000/api/qlib/backtest \
  -H "Content-Type: application/json" \
  -d '{
    "interval": "1d",
    "lookback_days": 720,
    "horizon": 5,
    "top_k": 5
  }'
```

### ML 日决策闭环

```bash
curl -X POST http://127.0.0.1:8000/api/ml/daily-decision \
  -H "Content-Type: application/json" \
  -d '{
    "style": "stable",
    "interval": "1d",
    "history_days": 180,
    "factor_weight": 0.5,
    "ml_weight": 0.5,
    "candidate_pool_size": 30
  }'

curl -X POST http://127.0.0.1:8000/api/ml/review

curl http://127.0.0.1:8000/api/ml/latest
```

## 12. 自定义策略扩展

策略入口在：

- `/Users/zhangming/code/a-stock/backend/app/services/strategies.py`

新增策略步骤：

1. 在 `STRATEGIES` 中注册新策略描述与默认参数
2. 在 `apply_strategy()` 中添加指标计算与买卖信号逻辑
3. 前端会自动读取 `/api/strategies` 并显示参数表单

## 13. 注意事项

- MooTdx 依赖公开行情源，首次请求可能稍慢
- 分钟线历史深度取决于公开源可返回的数据量
- 本项目不包含实盘交易接口，避免产生合规风险
- 如遇到个别股票实时行情失败，可切换股票代码重试
- AI 选股模块仅用于研究演示，不预测股价，不承诺收益，不构成投资建议
- 风险公告过滤基于本地元数据+行情行为规则，建议结合你自己的公告数据源进一步增强
- 当网络异常导致 MooTdx 无法连接时，AI 选股会启用离线兜底评分（结果会标注 `offline_fallback`）；网络恢复后重新扫描即可回到在线因子评分
- 当前默认训练范围是沪深 A 股全市场，首次全市场训练会明显重于早期固定池模式
- Qlib 自动训练默认会在后端启动后进入调度循环；若中断，下一次手工触发或调度会优先继续上次未完成训练
- 当前 Qlib 训练会将因子分片、预处理结果、训练切分缓存都落到 `data/qlib/runs/<run_id>/`，便于重启后复用
- 因子阶段虽然支持断点续训，但如果进程在 `factors` 阶段异常退出，旧版本日志上看起来会像重新从 `syncing/factors` 开始；新版本会尽量跳过已完成的同步和因子生成阶段
- 因子阶段会记录失败股票并在前端展示；失败股票通常来自同步阶段无可用历史行情
- 如果后端日志持续出现重复启动且退出码为 `137`，优先检查 Podman / Docker 分配内存是否足够