lhbfx/docs/技术文档.md

# lhbfx 技术文档

## 1. 技术栈

### 1.1 前端

- Vue 3
- TypeScript
- Vite

### 1.2 后端

- FastAPI
- PyMySQL
- PyYAML
- Requests / BeautifulSoup

### 1.3 数据库

- MySQL

## 2. 工程结构

```text
longhubang/
├─ backend/
│  ├─ config.example.yaml
│  ├─ pyproject.toml
│  ├─ scripts/
│  └─ src/lhbfx/
├─ frontend/
│  ├─ package.json
│  ├─ vite.config.ts
│  └─ src/
├─ docs/
├─ start-dev.ps1
├─ .gitignore
└─ README.md
```

## 3. 后端架构

### 3.1 入口

- `backend/scripts/run_api.py`
- `backend/src/lhbfx/app.py`

`app.py` 提供 API 路由与前端静态文件挂载能力。

### 3.2 配置

- 运行时配置文件：`backend/config.yaml`
- 示例配置文件：`backend/config.example.yaml`

为避免泄露本地敏感信息，实际 `config.yaml` 已加入 `.gitignore`。

### 3.3 数据层

数据库相关逻辑集中在：

- `backend/src/lhbfx/db.py`
- `backend/src/lhbfx/schema.sql`
- `backend/src/lhbfx/queries.py`

当前主要表：

- `stocks`
- `lhb_overview`
- `lhb_detail_seats`
- `warning_events`
- `watchlist_entries`
- `traders`
- `trader_seats`

### 3.4 数据处理管线

`backend/src/lhbfx/pipeline.py` 负责：

- 龙虎榜日度导入
- 席位匹配
- 预警生成
- 管线状态统计

配套脚本位于 `backend/scripts/`：

- `init_db.py`
- `import_ths_daily.py`
- `import_ths_year.py`
- `generate_warnings.py`
- `rematch_traders.py`

### 3.5 首页关键接口

#### `/api/actions`

用途：

- 为首页左侧关注池流水和右侧候选区提供原始操作数据

当前返回字段包括：

- 股票代码、股票名称
- 游资名称
- 买入、卖出、净额
- 当前价格、涨跌幅
- 行业、市场、总市值、流通市值
- 操作方向

#### `/api/watchlist`

用途：

- 保存和读取用户关注池

行为：

- `GET /api/watchlist`：获取当前关注池
- `POST /api/watchlist`：加入关注
- `DELETE /api/watchlist/{stock_code}`：取消关注并删除记录

## 4. 前端架构

### 4.1 前端入口

- `frontend/src/main.ts`
- `frontend/src/App.vue`

`App.vue` 负责页面切换、初始化数据和页面级事件绑定。

### 4.2 数据管理

`frontend/src/composables/useDashboardData.ts` 是首页和多页面共享数据的核心数据层，负责：

- 获取摘要数据
- 获取预警数据
- 获取游资列表
- 获取首页操作流水
- 获取和维护关注池

### 4.3 页面组件

- `HomeControlScreen.vue`：首页总控台
- `TraderDetailScreen.vue`：游资详情，采用单列全宽股票列表，支持时间、名称、净额连续增大筛选，并展示行业、板块、总市值、净额和预警标签
- `StockDetailScreen.vue`：个股详情
- `WarningCenterScreen.vue`：预警中心

首页当前拆分重点组件：

- `frontend/src/components/home/CandidateWatchCard.vue`

### 4.4 首页展示逻辑

#### 左侧关注池与操作流水

在前端中按以下维度合并：

- 股票
- 日期
- 游资
- 标准化席位名

用于解决同一席位同时出现在买入榜与卖出榜时被拆成两条的问题。

#### 右侧待加入关注

候选列表卡片设计目标：

- 固定高度
- 同屏显示更多
- 信息完整
- 净额优先

## 5. 启动与运行

### 5.1 一键启动

使用根目录脚本：

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

### 5.2 手动启动

后端：

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

前端：

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

## 6. 仓库管理建议

### 6.1 已加入忽略项

- `frontend/node_modules/`
- `frontend/dist/`
- `logs/`
- `output/`
- `.playwright-cli/`
- `backend/config.yaml`

### 6.2 行尾与文本规则

仓库已添加 `.gitattributes`：

- 默认文本文件统一由 git 管理行尾
- Windows 脚本保留 `crlf`

## 7. 测试与验证建议

当前建议至少执行三类验证：

### 7.1 静态验证

- `npm run build`
- `python -m compileall backend/src`

### 7.2 接口验证

- `GET /api/actions`
- `GET /api/watchlist`
- `GET /api/stocks/{stock_code}`

### 7.3 页面验证

建议引入或固化以下检查：

- 首页强制刷新后布局是否完整
- 关注池流水是否正确合并
- 候选卡片是否在固定高度内完整显示
- 关键页面至少保留一份 Playwright 截图回归

## 8. 当前技术债

目前仍需持续处理的问题：

- 历史文档与部分配置存在中文乱码
- 部分来源数据原始字段编码不稳定
- 页面样式近期经历多轮快速调整，仍建议补视觉回归测试

## 9. 定时更新与邮件报送方案

为满足“每天下午 17:00 自动更新并发送盘后邮件”的新增需求，建议增加一个独立的调度与报送模块。

### 9.1 调度方式

建议采用以下任一方式：

- 服务器 `cron`
- Windows 任务计划程序
- 后续统一接入独立任务调度器

默认调度时间：

- 每天下午 `17:00`

### 9.2 推荐执行流程

每日任务执行顺序建议如下：

1. 拉取当日龙虎榜与行情数据
2. 更新数据库
3. 重新生成预警数据
4. 统计关注池情况
5. 统计待加入关注候选列表
6. 生成 PDF 日报
7. 发送邮件正文与附件
8. 记录执行日志

### 9.3 建议新增模块

建议新增以下能力：

- `backend/scripts/daily_report.py`
  - 串联数据更新、统计、PDF 生成、邮件发送
- `backend/src/lhbfx/reporting.py`
  - 负责报表数据整理
- `backend/src/lhbfx/mailer.py`
  - 负责 SMTP 或邮件服务发送
- `backend/src/lhbfx/pdf_export.py`
  - 负责 PDF 生成

### 9.4 配置项建议

建议在配置文件中新增：

- 是否启用邮件报送
- SMTP 主机
- SMTP 端口
- 发件人账号
- 发件人密码或授权码
- 收件人列表
- 抄送列表
- 日报输出目录
- 调度时间

### 9.5 PDF 生成建议

PDF 附件可以通过以下方式生成：

- 基于 HTML 模板渲染后导出 PDF
- 或直接使用 Python PDF 库生成结构化报告

推荐内容结构：

1. 标题页
2. 数据更新时间
3. 关注池总览
4. 关注池流水摘要
5. 今日待加入关注列表
6. 风险与预警摘要

### 9.6 邮件正文建议

正文采用简洁摘要形式，便于手机查看：

- 今日关注池概况
- 今日关注池重点动作
- 今日待加入关注候选
- 风险提示
- 附件说明

### 9.7 测试建议

新增该需求后，应补充以下验证：

- 17:00 定时任务是否被正确触发
- 更新失败时是否生成错误日志
- PDF 是否成功生成
- 邮件正文是否包含关键摘要
- 附件是否能正常打开
- 多收件人场景是否发送成功