341 lines
6.5 KiB
Markdown
341 lines
6.5 KiB
Markdown
# 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 是否成功生成
|
||
- 邮件正文是否包含关键摘要
|
||
- 附件是否能正常打开
|
||
- 多收件人场景是否发送成功
|