lhbfx/docs/技术文档.md

# lhbfx 技术文档

## 1. 技术栈

- 前端：Vue 3、TypeScript、Vite
- 后端：FastAPI、PyMySQL、PyYAML、Requests、BeautifulSoup、ReportLab
- 数据库：MySQL 8+
- 运行脚本：PowerShell、Python scripts

## 2. 工程结构

```text
lhbfx/
├─ backend/
│  ├─ config.example.yaml
│  ├─ config.yaml
│  ├─ pyproject.toml
│  ├─ scripts/
│  │  ├─ init_db.py
│  │  ├─ run_api.py
│  │  ├─ import_ths_daily.py
│  │  ├─ rematch_traders.py
│  │  ├─ generate_warnings.py
│  │  ├─ after_market_update.py
│  │  └─ daily_report.py
│  └─ src/lhbfx/
├─ frontend/
│  ├─ package.json
│  ├─ vite.config.ts
│  └─ src/
├─ docs/
├─ start-dev.ps1
└─ README.md
```

## 3. 后端架构

### 3.1 应用入口

- `backend/scripts/run_api.py`：命令行启动入口。
- `backend/src/lhbfx/app.py`：FastAPI 应用、API 路由、静态前端挂载、启动时数据检查与调度启动。

### 3.2 配置

- `backend/config.example.yaml`：共享配置模板。
- `backend/config.yaml`：本地运行配置，包含数据库、邮件、调度等信息。
- `backend/src/lhbfx/config.py`：配置模型与加载逻辑。

### 3.3 数据访问

- `backend/src/lhbfx/db.py`：MySQL 连接与 cursor 上下文。
- `backend/src/lhbfx/schema.sql`：表结构。
- `backend/src/lhbfx/queries.py`：面向 API 的查询与聚合，包含摘要、游资详情、个股详情、关注池、股票搜索、预警查询等。

### 3.4 数据导入与处理

- `backend/src/lhbfx/pipeline.py`：龙虎榜导入、游资席位匹配、预警生成、指定交易日刷新。
- `backend/src/lhbfx/sources/tonghuashun.py`：同花顺龙虎榜数据源。
- `backend/src/lhbfx/sources/eastmoney.py`：东方财富行情、K 线与个股资料兜底数据源。
- `backend/src/lhbfx/sources/tencent.py`：腾讯行情快照兜底数据源。
- `backend/src/lhbfx/sources/sina.py`：新浪 K 线兜底数据源。

### 3.5 盘后任务与日报

- `backend/src/lhbfx/after_market.py`：盘后更新编排，负责导入、匹配、预警、日报与邮件。
- `backend/src/lhbfx/scheduler.py`：API 常驻调度，工作日 17:00 后尝试补齐当日数据。
- `backend/src/lhbfx/reporting.py`：日报数据聚合与邮件正文。
- `backend/src/lhbfx/pdf_export.py`：PDF 日报生成。
- `backend/src/lhbfx/mailer.py`：邮件发送。

## 4. 前端架构

### 4.1 入口与状态

- `frontend/src/main.ts`：Vue 应用入口。
- `frontend/src/App.vue`：页面路由状态、股票搜索、全局数据初始化。
- `frontend/src/composables/useDashboardData.ts`：统一封装 API 调用、选择状态、关注池派生数据与页面数据加载。
- `frontend/src/types.ts`：API 响应类型。

### 4.2 页面组件

- `AppHero.vue`：顶部状态、导航与股票搜索。
- `HomeControlScreen.vue`：首页总控台，包含关注池流水与候选关注股票。
- `TraderDetailScreen.vue`：游资详情。
- `StockDetailScreen.vue`：个股详情容器、基础信息、预警入口、游资参与概览。
- `StockDetailKlinePanel.vue`：日 K、MA5、买卖点与预警标记。
- `StockActionTimelineChart.vue`：买卖力度趋势图。
- `WarningCenterScreen.vue`：预警中心。
- `home/CandidateWatchCard.vue`：候选关注股票卡片。

### 4.3 工具模块

- `frontend/src/utils/format.ts`：金额、涨跌、日期和预警标签格式化。
- `frontend/src/utils/stockDetailKline.ts`：个股 K 线面板的数据转换与坐标计算。

## 5. 主要数据流

1. 用户启动后端，`app.py` 加载配置、创建 FastAPI 应用，并启动盘后调度。
2. 前端 `useDashboardData.initialize()` 拉取摘要、状态、游资、预警、关注池和操作流水。
3. 首页筛选条件变化后，前端重新请求 `/api/actions`，并在本地派生关注池流水、候选关注列表和指标。
4. 用户选择个股时，前端请求 `/api/stocks/{stock_code}`，后端聚合数据库数据、K 线、行情快照、游资操作和预警。
5. 盘后任务导入龙虎榜数据后，执行席位匹配、预警生成、日报生成与邮件发送。

## 6. 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`：刷新指定交易日。

## 7. 生成物与清理规则

以下目录或文件属于生成物、本地依赖或运行产物，不应提交：

- `frontend/node_modules/`
- `frontend/dist/`
- `logs/`
- `__pycache__/`
- `*.pyc`
- `*.egg-info/`

清理时优先删除这些生成物；源码删除必须先确认无引用、无入口、无文档约定。

## 8. 验证命令

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

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