feat: improve stock detail view and update docs
This commit is contained in:
wanghep
372
docs/技术文档.md
372
docs/技术文档.md
@ -2,31 +2,27 @@
|
||||
|
||||
## 1. 技术栈
|
||||
|
||||
### 1.1 前端
|
||||
|
||||
- Vue 3
|
||||
- TypeScript
|
||||
- Vite
|
||||
|
||||
### 1.2 后端
|
||||
|
||||
- FastAPI
|
||||
- PyMySQL
|
||||
- PyYAML
|
||||
- Requests / BeautifulSoup
|
||||
|
||||
### 1.3 数据库
|
||||
|
||||
- MySQL
|
||||
- 前端：Vue 3、TypeScript、Vite
|
||||
- 后端：FastAPI、PyMySQL、PyYAML、Requests、BeautifulSoup、ReportLab
|
||||
- 数据库：MySQL 8+
|
||||
- 运行脚本：PowerShell、Python scripts
|
||||
|
||||
## 2. 工程结构
|
||||
|
||||
```text
|
||||
longhubang/
|
||||
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
|
||||
@ -34,307 +30,115 @@ longhubang/
|
||||
│ └─ src/
|
||||
├─ docs/
|
||||
├─ start-dev.ps1
|
||||
├─ .gitignore
|
||||
└─ README.md
|
||||
```
|
||||
|
||||
## 3. 后端架构
|
||||
|
||||
### 3.1 入口
|
||||
### 3.1 应用入口
|
||||
|
||||
- `backend/scripts/run_api.py`
|
||||
- `backend/src/lhbfx/app.py`
|
||||
|
||||
`app.py` 提供 API 路由与前端静态文件挂载能力。
|
||||
- `backend/scripts/run_api.py`：命令行启动入口。
|
||||
- `backend/src/lhbfx/app.py`：FastAPI 应用、API 路由、静态前端挂载、启动时数据检查与调度启动。
|
||||
|
||||
### 3.2 配置
|
||||
|
||||
- 运行时配置文件：`backend/config.yaml`
|
||||
- 示例配置文件：`backend/config.example.yaml`
|
||||
- `backend/config.example.yaml`：共享配置模板。
|
||||
- `backend/config.yaml`：本地运行配置，包含数据库、邮件、调度等信息。
|
||||
- `backend/src/lhbfx/config.py`：配置模型与加载逻辑。
|
||||
|
||||
为避免泄露本地敏感信息，实际 `config.yaml` 已加入 `.gitignore`。
|
||||
### 3.3 数据访问
|
||||
|
||||
### 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/db.py`
|
||||
- `backend/src/lhbfx/schema.sql`
|
||||
- `backend/src/lhbfx/queries.py`
|
||||
- `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 盘后任务与日报
|
||||
|
||||
- `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}`：取消关注并删除记录
|
||||
- `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 前端入口
|
||||
### 4.1 入口与状态
|
||||
|
||||
- `frontend/src/main.ts`
|
||||
- `frontend/src/App.vue`
|
||||
- `frontend/src/main.ts`：Vue 应用入口。
|
||||
- `frontend/src/App.vue`：页面路由状态、股票搜索、全局数据初始化。
|
||||
- `frontend/src/composables/useDashboardData.ts`：统一封装 API 调用、选择状态、关注池派生数据与页面数据加载。
|
||||
- `frontend/src/types.ts`：API 响应类型。
|
||||
|
||||
`App.vue` 负责页面切换、初始化数据和页面级事件绑定。
|
||||
### 4.2 页面组件
|
||||
|
||||
### 4.2 数据管理
|
||||
- `AppHero.vue`：顶部状态、导航与股票搜索。
|
||||
- `HomeControlScreen.vue`：首页总控台，包含关注池流水与候选关注股票。
|
||||
- `TraderDetailScreen.vue`：游资详情。
|
||||
- `StockDetailScreen.vue`：个股详情容器、基础信息、预警入口、游资参与概览。
|
||||
- `StockDetailKlinePanel.vue`：日 K、MA5、买卖点与预警标记。
|
||||
- `StockActionTimelineChart.vue`：买卖力度趋势图。
|
||||
- `WarningCenterScreen.vue`：预警中心。
|
||||
- `home/CandidateWatchCard.vue`：候选关注股票卡片。
|
||||
|
||||
`frontend/src/composables/useDashboardData.ts` 是首页和多页面共享数据的核心数据层，负责：
|
||||
### 4.3 工具模块
|
||||
|
||||
- 获取摘要数据
|
||||
- 获取预警数据
|
||||
- 获取游资列表
|
||||
- 获取首页操作流水
|
||||
- 获取和维护关注池
|
||||
- `frontend/src/utils/format.ts`：金额、涨跌、日期和预警标签格式化。
|
||||
- `frontend/src/utils/stockDetailKline.ts`：个股 K 线面板的数据转换与坐标计算。
|
||||
|
||||
### 4.3 页面组件
|
||||
## 5. 主要数据流
|
||||
|
||||
- `HomeControlScreen.vue`：首页总控台
|
||||
- `TraderDetailScreen.vue`：游资详情，采用单列全宽股票列表，支持时间、名称、净额连续增大筛选，并展示行业、板块、总市值、净额和预警标签
|
||||
- `StockDetailScreen.vue`：个股详情
|
||||
- `WarningCenterScreen.vue`：预警中心
|
||||
1. 用户启动后端，`app.py` 加载配置、创建 FastAPI 应用，并启动盘后调度。
|
||||
2. 前端 `useDashboardData.initialize()` 拉取摘要、状态、游资、预警、关注池和操作流水。
|
||||
3. 首页筛选条件变化后，前端重新请求 `/api/actions`，并在本地派生关注池流水、候选关注列表和指标。
|
||||
4. 用户选择个股时，前端请求 `/api/stocks/{stock_code}`，后端聚合数据库数据、K 线、行情快照、游资操作和预警。
|
||||
5. 盘后任务导入龙虎榜数据后，执行席位匹配、预警生成、日报生成与邮件发送。
|
||||
|
||||
首页当前拆分重点组件：
|
||||
## 6. API 概览
|
||||
|
||||
- `frontend/src/components/home/CandidateWatchCard.vue`
|
||||
- `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`：刷新指定交易日。
|
||||
|
||||
### 4.4 首页展示逻辑
|
||||
## 7. 生成物与清理规则
|
||||
|
||||
#### 左侧关注池与操作流水
|
||||
|
||||
在前端中按以下维度合并：
|
||||
|
||||
- 股票
|
||||
- 日期
|
||||
- 游资
|
||||
- 标准化席位名
|
||||
|
||||
用于解决同一席位同时出现在买入榜与卖出榜时被拆成两条的问题。
|
||||
|
||||
#### 右侧待加入关注
|
||||
|
||||
候选列表卡片设计目标：
|
||||
|
||||
- 固定高度
|
||||
- 同屏显示更多
|
||||
- 信息完整
|
||||
- 净额优先
|
||||
|
||||
## 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`
|
||||
- `__pycache__/`
|
||||
- `*.pyc`
|
||||
- `*.egg-info/`
|
||||
|
||||
### 6.2 行尾与文本规则
|
||||
清理时优先删除这些生成物；源码删除必须先确认无引用、无入口、无文档约定。
|
||||
|
||||
仓库已添加 `.gitattributes`：
|
||||
## 8. 验证命令
|
||||
|
||||
- 默认文本文件统一由 git 管理行尾
|
||||
- Windows 脚本保留 `crlf`
|
||||
```powershell
|
||||
# 前端类型检查与构建
|
||||
cd frontend
|
||||
npm run build
|
||||
|
||||
## 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 是否成功生成
|
||||
- 邮件正文是否包含关键摘要
|
||||
- 附件是否能正常打开
|
||||
- 多收件人场景是否发送成功
|
||||
# 后端语法检查
|
||||
cd ..
|
||||
python -m compileall backend\src backend\scripts
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user