wanghep/lhbfx

Fork 0

Files

wanghep 8c9117ca4c feat: add reporting workflow and optimize dashboard loading

2026-04-18 14:46:24 +08:00

6.5 KiB

Raw Blame History

lhbfx 技术文档

1. 技术栈

1.1 前端

Vue 3
TypeScript
Vite

1.2 后端

FastAPI
PyMySQL
PyYAML
Requests / BeautifulSoup

1.3 数据库

MySQL

2. 工程结构

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 -ExecutionPolicy Bypass -File .\start-dev.ps1

5.2 手动启动

后端：

python backend/scripts/run_api.py

前端：

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 推荐执行流程

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

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

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 库生成结构化报告

推荐内容结构：

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

9.6 邮件正文建议

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

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

9.7 测试建议

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

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

6.5 KiB Raw Blame History Unescape Escape