248 lines
4.5 KiB
Markdown
248 lines
4.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. 当前技术债
|
||
|
||
目前仍需持续处理的问题：
|
||
|
||
- 历史文档与部分配置存在中文乱码
|
||
- 部分来源数据原始字段编码不稳定
|
||
- 页面样式近期经历多轮快速调整，仍建议补视觉回归测试
|