lhbfx/README.md

# lhbfx

`lhbfx` 是一个围绕 A 股龙虎榜数据构建的“顶级游资监控系统”，当前聚焦盘后分析、游资席位跟踪、关注池管理、预警提示与个股复盘。

## 项目结构

- `backend/`
  - FastAPI 服务
  - 龙虎榜导入、席位映射、预警生成脚本
  - MySQL schema 与查询逻辑
- `frontend/`
  - Vue 3 + TypeScript + Vite 单页应用
  - 首页总控台、游资详情、个股详情、预警中心
- `docs/`
  - 需求文档
  - 技术文档
  - 历史说明与 UI 草稿

## 当前核心能力

- 首页支持“关注池与操作流水”联动展示。
- 待加入关注列表支持按买卖结构着色、净额重点突出、快速加入关注。
- 关注池写入数据库，支持新增和删除。
- 个股详情支持 K 线、MA5、买卖点与预警信息展示。
- 预警中心支持卖出预警、慢流出观察等风险信息查看。
- 已明确新增“每日 17:00 自动更新 + 邮件日报 + PDF 附件”需求，待后续实现。

## 最近界面与数据调整

- 个股详情页的“买卖明细”已改为“买卖力度趋势”图：
  - 柱形图按日期展示买入和卖出，买入为正、卖出为负。
  - 折线展示“当日净额”和“累计净额”。
  - 明细仅在鼠标悬浮图表时显示。
- 个股详情页顶部新增“预警列表”按钮：
  - 有预警时红色高亮提示。
  - 点击后以弹层方式展示当前个股预警，不再挤占右侧图表区域。
- 个股详情、首页候选股、游资详情页的数据补全逻辑已增强：
  - 优先读取数据库中的股票元数据。
  - 外部快照失败时增加备用行情源兜底。
  - 收盘后更新流程会同步补全行业、市值、流通市值等字段。
- 后端 API 启动时会自动检查最近龙虎榜数据：
  - 如果数据库最新交易日已经是当天，则跳过。
  - 如果发现最近工作日数据缺失，会尝试自动补齐并重新生成预警。
  - 检查失败不会阻塞 API 启动，避免服务不可用。
- 后端服务内置收盘后调度：
  - 工作日 17:00 之后会自动尝试执行收盘后更新。
  - 如果 17:00 时数据源尚未准备好，会按固定间隔重试，直到当天数据补齐。
  - 本地和服务器使用同一套调度逻辑，不再依赖本机 Codex 自动任务。

## 环境要求

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

## 后端启动

1. 复制配置文件：
   - 将 `backend/config.example.yaml` 复制为 `backend/config.yaml`
   - 按实际数据库连接信息修改
   - 当前仓库已允许提交 `backend/config.yaml`，服务器部署默认读取该文件
2. 初始化数据库：

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

3. 启动 API：

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

4. 收盘后更新并发送邮件：

```powershell
python backend/scripts/after_market_update.py --trade-date 2026-04-17 --send-email
```

默认约定：

- 按 `Asia/Shanghai` 取当天日期
- 预期定时为 A 股交易日 `17:00`
- 只有当日成功拉到新的龙虎榜数据，才会继续生成预警、PDF 并发邮件；否则自动跳过

默认地址：

- `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`

## 一键开发启动

根目录提供了 `start-dev.ps1`：

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

脚本会同时拉起：

- 后端：`127.0.0.1:8000`
- 前端：`127.0.0.1:5173`

日志输出目录：

- `logs/`

## 常用后端接口

- `GET /api/summary`
- `GET /api/pipeline/status`
- `GET /api/traders`
- `GET /api/traders/{trader_id}`
- `GET /api/stocks/{stock_code}`
- `GET /api/actions`
- `GET /api/watchlist`
- `POST /api/watchlist`
- `DELETE /api/watchlist/{stock_code}`
- `GET /api/warnings`

## 文档索引

- 需求文档：`docs/需求文档.md`
- 技术文档：`docs/技术文档.md`
- 历史需求梳理：`docs/需求梳理-今日游资操作优先.md`
- 历史 UI 说明：`docs/UI设计说明.md`

## 仓库说明

- 仓库已补充 `.gitignore` 与 `.gitattributes`
- 本地敏感配置 `backend/config.yaml` 已忽略，不会推送
- 提交前建议使用 `backend/config.example.yaml` 作为共享配置模板