zjjk/ETF监控模块需求文档.md

# ETF监控模块需求文档

## 1. 目标

在现有系统中新增一个与“南向资金监控”“A股资金监控”同级的新模块：

- ETF监控

该模块面向个人投资跟踪使用，核心目标是：

- 实时观察重点宽基ETF与主题ETF的行情变化
- 通过分钟级变化识别资金快速异动
- 通过邮件提醒辅助追踪国家大基金及相关主题方向的动向

当前阶段以“可运行、可观察、可提醒”为主，不以机构级稳定性为目标。

---

## 2. 数据来源

### 2.1 主数据源

- 同花顺数据

### 2.2 当前数据源约束

当前无同花顺正式机构接口（如 iFinD / 正式API），因此本模块按“个人可用验证版”设计：

- 允许数据源存在不稳定、限流、断连、字段变更风险
- 允许分钟级数据偶发缺失
- 允许部分ETF在个别时段无法刷新
- 邮件提醒按“辅助追踪”定位，不承诺绝对准确

### 2.3 风险说明

由于当前不是同花顺正式授权接口：

- 不保证长期稳定
- 不保证分钟级数据持续完整
- 不保证字段口径始终不变
- 后续如拿到正式接口，需保留替换数据源的能力

---

## 3. 模块定位

ETF模块未来在前端主页面中与以下模块同级：

- 南向资金监控
- A股资金监控
- ETF监控

ETF模块内部先分为两个一级页面：

1. 宽基ETF监控列表
2. 板块ETF监控列表

后续如有需要，再扩展ETF详情页、历史统计页、国家大基金专题页。

---

## 4. 监控范围

### 4.1 宽基ETF监控列表

当前重点监控以下宽基ETF：

- 上证50ETF
- 沪深300ETF（510300）
- 中证500ETF
- 中证1000ETF（563000）
- 中证2000ETF

说明：

- 若同一指数存在多个ETF产品，后续需固定一个主监控代码
- 当前未明确代码的ETF，开发时可先按主流成交活跃产品确定默认代码，后续可配置化

### 4.2 板块ETF监控列表

当前重点监控以下主题ETF：

- 证券ETF
- 银行ETF
- 人工智能ETF
- 恒生科技ETF
- 半导体ETF

说明：

- 每个主题后续应明确对应的主ETF代码
- 若一个主题对应多只ETF，当前阶段优先选一只主ETF作为代表产品

---

## 5. 页面需求

## 5.1 前端入口

在首页新增“ETF监控”入口卡片。

点击后进入ETF监控模块。

## 5.2 ETF监控主页面

页面结构：

- 顶部：返回首页、刷新数据、日期筛选
- 一级Tab：
  - 宽基ETF
  - 板块ETF

页面整体风格应与现有南向/A股模块保持统一，但模块实现需尽量独立，避免污染现有逻辑。

---

## 6. 宽基ETF监控列表需求

支持按日期查看当天数据。

### 6.1 必要字段

列表字段至少包括：

- 代码
- 名称
- 最新价
- 涨跌额
- 涨跌幅
- 成交额
- 成交量
- 1分钟涨跌幅
- 3分钟涨跌幅
- 4分钟涨跌幅
- 更新时间

### 6.2 可补充字段

如数据源可获取，可增加：

- 振幅
- 换手率
- 当日最高价
- 当日最低价
- 昨收价
- 成交笔数

### 6.3 交互要求

- 支持代码/名称搜索
- 支持点击表头排序
- 默认不强制排序，优先保持原始返回顺序
- 支持手动刷新
- 支持当天实时展示

---

## 7. 板块ETF监控列表需求

与宽基ETF同级。

### 7.1 必要字段

字段参考宽基ETF列表：

- 代码
- 名称
- 最新价
- 涨跌额
- 涨跌幅
- 成交额
- 成交量
- 1分钟涨跌幅
- 3分钟涨跌幅
- 4分钟涨跌幅
- 更新时间

### 7.2 交互要求

- 支持名称搜索
- 支持代码搜索
- 支持点击表头排序
- 默认不强制排序
- 支持手动刷新

---

## 8. 分钟级计算需求

由于目标包含3分钟、4分钟涨跌速度判断，系统需具备分钟级数据缓存与计算能力。

### 8.1 计算口径

若数据源直接提供分钟级行情：

- 直接读取分钟级数据计算

若数据源仅提供实时快照：

- 系统每分钟抓取一次
- 缓存最近若干分钟价格
- 自行计算：
  - 1分钟涨跌幅
  - 3分钟涨跌幅
  - 4分钟涨跌幅

### 8.2 展示口径

列表中展示的 1/3/4 分钟涨跌幅应统一为百分比。

---

## 9. 邮件提醒需求

## 9.1 邮箱类型

- QQ邮箱

沿用现有项目中的邮件配置能力。

## 9.2 提醒对象

以下所有ETF均纳入监控：

- 宽基ETF列表中的ETF
- 板块ETF列表中的ETF

## 9.3 提醒规则

当某只ETF在最近3分钟内：

- 上涨速度过快
- 下跌速度过快

则触发邮件提醒。

### 9.4 第一阶段建议规则

第一阶段先按配置项实现：

- `etf_3min_change_alert_percent`

例如：

- 3分钟涨跌幅绝对值超过某阈值即提醒

### 9.5 提醒要求

邮件内容至少包括：

- ETF名称
- ETF代码
- 当前价格
- 当前涨跌幅
- 3分钟涨跌幅
- 触发时间
- 简短说明

后续如需要，可加上“大模型操作建议”。

---

## 10. 数据存储需求

## 10.1 存储原则

ETF数据需要保留实时缓存能力，并按天进行存储。

### 10.2 建议存储层次

1. 实时数据

- 当天最新快照
- 用于前端展示

2. 分钟级缓存

- 用于计算1分钟、3分钟、4分钟变化

3. 日度数据

- 按天保存每只ETF的收盘或当日最新有效数据
- 为后续历史统计做准备

### 10.3 存储位置

优先沿用现有项目方案：

- MySQL

同时保留本地文件缓存兜底能力。

---

## 11. 后端需求

后端新增独立ETF模块，尽量不影响现有南向/A股逻辑。

建议新增：

- ETF client
- ETF service
- ETF schema
- ETF API route
- ETF alert logic

建议API：

- `/api/etf/broad/realtime`
- `/api/etf/sector/realtime`
- `/api/etf/broad/daily`
- `/api/etf/sector/daily`

如后续有详情页，可再增加：

- `/api/etf/detail`

---

## 12. 前端需求

前端新增ETF独立页面，尽量复用现有表格、状态面板、Tab结构，但不直接污染现有A股页面逻辑。

建议新增：

- ETF主页面组件
- ETF数据表组件
- ETF数据获取 composable
- 首页入口卡片

---

## 13. 配置文件需求

配置文件中应新增ETF监控相关配置，例如：

- `etf_enabled`
- `etf_realtime_interval_seconds`
- `etf_3min_change_alert_percent`
- `etf_broad_list`
- `etf_sector_list`
- `etf_data_source`

并支持后续配置：

- ETF主监控代码
- 主题ETF代码映射
- 告警阈值

---

## 14. 当前实现边界

当前阶段先做“个人验证版”，边界如下：

- 先做实时展示
- 先做3分钟异动提醒
- 允许同花顺源偶发失败
- 不承诺机构级稳定性
- 不先做复杂回测与策略系统

---

## 15. 后续扩展方向

后续可逐步扩展：

- ETF详情页
- ETF历史趋势图
- ETF近5/10/20/30日统计
- 国家大基金专题ETF观察
- 与A股资金联动分析
- 大模型自动摘要与建议
- 正式数据接口切换

---

## 16. 当前结论

在无同花顺正式接口的前提下，本模块仍可按“个人验证版”推进开发。

当前开发定位：

- 可以运行
- 可以看实时变化
- 可以做分钟级异动提醒
- 可以辅助跟踪国家大基金相关主题方向

但需接受：

- 数据源不稳定
- 分钟级提醒存在误差风险
- 后续可能需要切换到正式接口重构数据源层