lhbfx/README.md

# lhbfx

`lhbfx` 是一个围绕 A 股龙虎榜数据构建的盘后游资监控系统。当前工程聚焦龙虎榜导入、游资席位匹配、关注池管理、个股复盘、风险预警、盘后自动更新以及 PDF/邮件日报。

## 项目结构

```text
lhbfx/
├─ backend/                 # FastAPI 后端、数据导入脚本、MySQL schema
│  ├─ config.example.yaml    # 配置模板
│  ├─ config.yaml            # 本地运行配置
│  ├─ scripts/               # 命令行脚本入口
│  └─ src/lhbfx/             # 后端应用源码
├─ frontend/                # Vue 3 + TypeScript + Vite 前端
│  ├─ public/
│  └─ src/
├─ docs/                    # 需求、技术与 UI 文档
├─ logs/                    # 本地运行日志，已忽略
└─ start-dev.ps1            # 一键启动前后端
```

## 当前能力

- 首页总控台：按日期、游资、买卖方向筛选，联动关注池与候选关注股票。
- 关注池：支持新增、取消关注，并按股票、日期、游资、席位合并展示流水。
- 个股详情：展示日 K、MA5、买卖点、游资参与概览、买卖力度趋势与预警弹层。
- 游资详情：展示游资档案、席位、历史参与股票与净额变化。
- 预警中心：展示卖出预警、慢流出观察等风险信号。
- 盘后流程：支持导入指定交易日数据、重匹配游资、生成预警、生成 PDF 日报并可发送邮件。
- 后端调度：API 启动后会按工作日 17:00 之后的窗口尝试补齐当日数据。

## 环境要求

- Python 3.11+
- Node.js 20+
- MySQL 8+

## 后端启动

1. 准备配置：

```powershell
Copy-Item backend\config.example.yaml backend\config.yaml
```

按实际 MySQL、邮件等信息修改 `backend/config.yaml`。

2. 初始化数据库：

```powershell
python backend\scripts\init_db.py
```

3. 启动 API：

```powershell
python backend\scripts\run_api.py
```

默认地址：`http://127.0.0.1:8000`。

## 前端启动

```powershell
cd frontend
npm install
npm run dev -- --host 127.0.0.1 --port 5173
```

默认地址：`http://127.0.0.1:5173`，开发服务器会把 `/api` 代理到后端。

## 一键开发启动

在项目根目录运行：

```powershell
powershell -ExecutionPolicy Bypass -File .\start-dev.ps1
```

脚本会同时启动：

- 后端：`http://127.0.0.1:8000`
- 前端：`http://127.0.0.1:5173`
- 日志：`logs/`

## 常用脚本

```powershell
# 导入同花顺指定日期龙虎榜数据
python backend\scripts\import_ths_daily.py --trade-date 2026-04-17

# 重跑游资席位匹配
python backend\scripts\rematch_traders.py

# 重新生成预警
python backend\scripts\generate_warnings.py

# 盘后更新，可选邮件发送
python backend\scripts\after_market_update.py --trade-date 2026-04-17 --send-email

# 生成日报，可选发送
python backend\scripts\daily_report.py --trade-date 2026-04-17 --send
```

## 常用 API

- `GET /api/summary`
- `GET /api/pipeline/status`
- `GET /api/traders`
- `GET /api/traders/{trader_id}`
- `GET /api/stocks/search`
- `GET /api/stocks/{stock_code}`
- `GET /api/actions`
- `GET /api/watchlist`
- `POST /api/watchlist`
- `DELETE /api/watchlist/{stock_code}`
- `GET /api/warnings`
- `POST /api/pipeline/rematch-traders`
- `POST /api/pipeline/generate-warnings`
- `POST /api/pipeline/refresh-trade-date`

## 构建与检查

```powershell
# 前端类型检查与生产构建
cd frontend
npm run build

# 后端语法检查
cd ..
python -m compileall backend\src backend\scripts
```

## 文档索引

- 需求文档：`docs/需求文档.md`
- 技术文档：`docs/技术文档.md`
- UI 设计说明：`docs/UI设计说明.md`
- 历史需求梳理：`docs/需求梳理-今日游资操作优先.md`
- 完整早期需求：`docs/顶级游资监控系统需求文档.md`

## 仓库说明

生成物和本地运行产物不进入版本库，包括 `logs/`、`frontend/dist/`、`frontend/node_modules/`、`__pycache__/`、`*.egg-info/`。提交前建议运行前端构建和后端编译检查。