450 lines
13 KiB
Markdown
450 lines
13 KiB
Markdown
# 南向资金监控平台需求文档
|
||
|
||
## 1. 文档目的
|
||
|
||
本文档用于明确南向资金监控平台的首期建设范围、数据口径、系统边界、验收标准与后续演进方向，作为产品、设计、开发和测试的统一执行依据。
|
||
|
||
当前版本以“先做出可验证效果”为目标，优先保证数据真实性、页面可用性和系统可扩展性，不追求一次性做全。
|
||
|
||
## 2. 项目目标
|
||
|
||
构建一个面向港股通南向资金监控与分析的网站系统，满足以下目标：
|
||
|
||
- 交易时段内，实时展示南向资金总净流入、沪市港股通与深市港股通拆分、关键阈值变化和分钟级曲线。
|
||
- 非交易时段，沉淀并展示自 `2026-01-01` 起的历史日度、周度、月度和累计统计结果。
|
||
- 对关键资金异动和阈值突破进行邮件提醒，并保留完整推送记录。
|
||
- 首版先使用本地 `JSON` 文件存储，后续可平滑迁移到 `MySQL`，业务逻辑不因存储替换而重写。
|
||
|
||
## 3. 当前版本建设原则
|
||
|
||
### 3.1 数据真实性优先
|
||
|
||
- 当前版本不接受演示数据、模拟数据、人工虚构数据作为正式展示口径。
|
||
- 页面展示的数据必须能够追溯到真实采集结果。
|
||
- 所有核心数据都需要保留来源、采集时间、交易日、原始载荷摘要。
|
||
|
||
### 3.2 单一主数据源
|
||
|
||
首版暂定只接入 `同花顺`，不再混用其他站点。
|
||
|
||
要求：
|
||
|
||
- 实时数据优先使用同花顺 `沪深港通/港股通` 页面或其真实数据接口。
|
||
- 历史数据优先使用同花顺同一体系下的历史页或可回溯接口。
|
||
- 不再使用快讯标题、资讯摘要、新闻阈值作为正式实时主口径。
|
||
|
||
### 3.3 存储先轻后重
|
||
|
||
- 首版使用本地 `JSON` 文件存储。
|
||
- 存储结构、Repository 层、配置项需为后续迁移到 `MySQL` 预留空间。
|
||
- 禁止把文件路径、文件命名规则、JSON 结构直接耦合到业务层。
|
||
|
||
## 4. 业务范围
|
||
|
||
### 4.1 首期 MVP 范围
|
||
|
||
首期必须交付以下能力：
|
||
|
||
- 南向资金实时监控
|
||
- 历史日/周/月/累计统计
|
||
- 沪市港股通、深市港股通拆分展示
|
||
- 分钟级快照沉淀
|
||
- 阈值突破告警
|
||
- 异动速度告警
|
||
- 邮件发送
|
||
- 推送记录查询
|
||
- 基础配置管理
|
||
|
||
### 4.2 暂不纳入首期正式验收
|
||
|
||
以下内容可保留设计位，但不作为首期必须完成项：
|
||
|
||
- 板块流入推断模型
|
||
- 个股级资金画像
|
||
- 北向资金同步监控
|
||
- 企业微信、短信、公众号等多渠道推送
|
||
- AI 自动生成盘中点评和收盘总结
|
||
|
||
## 5. 数据口径要求
|
||
|
||
### 5.1 监控对象
|
||
|
||
监控对象为 `港股通南向资金`，由以下两部分组成：
|
||
|
||
- 港股通（沪）
|
||
- 港股通（深）
|
||
|
||
页面总南向资金口径为两者汇总。
|
||
|
||
### 5.2 时间口径
|
||
|
||
- 历史统计起始日：`2026-01-01`
|
||
- 实时监控范围：当前交易日盘中数据
|
||
- 历史截止日：系统可获取的最新交易日
|
||
|
||
### 5.3 交易时段口径
|
||
|
||
需按港股交易时段处理：
|
||
|
||
- 上午：`09:30-12:00`
|
||
- 下午：`13:00-16:00`
|
||
- 收盘竞价及最终收口：以 `16:10` 作为当日结果可确认的安全时间点
|
||
|
||
说明：
|
||
|
||
- 盘中展示为实时值或准实时值。
|
||
- 当天最终值在 `16:10` 后才允许标记为“收盘最终值”。
|
||
- `16:10` 前即使页面已显示较新数值，也只能标记为“盘中值”或“待最终确认”。
|
||
|
||
### 5.4 统计粒度
|
||
|
||
- 分钟级：盘中监控、阈值判断、异动提醒
|
||
- 日级：按交易日统计净流入
|
||
- 周级：按自然周内交易日汇总
|
||
- 月级：按自然月内交易日汇总
|
||
- 累计级：自 `2026-01-01` 起累计净流入
|
||
|
||
### 5.5 核心指标
|
||
|
||
系统首版至少需要提供以下指标：
|
||
|
||
- 当日南向资金净流入金额
|
||
- 当日南向资金累计净流入金额
|
||
- 港股通（沪）净流入金额
|
||
- 港股通（深）净流入金额
|
||
- 买入额
|
||
- 卖出额
|
||
- 净买额
|
||
- 1 分钟净变化值
|
||
- 5 分钟净变化值
|
||
- 历史日净流入
|
||
- 历史周净流入
|
||
- 历史月净流入
|
||
- 历史累计净流入
|
||
|
||
### 5.6 数据精度分级
|
||
|
||
为避免页面误导，数据必须带精度标记：
|
||
|
||
- `realtime_exact`：来自实时接口的准确值
|
||
- `close_final`：当日收盘最终值
|
||
- `historical_exact`：历史准确值
|
||
- `unavailable`：当前无法获取
|
||
|
||
首版正式页面仅允许展示以上状态，不再显示无来源的推断数值。
|
||
|
||
## 6. 功能需求
|
||
|
||
### 6.1 实时总览页
|
||
|
||
至少展示以下内容：
|
||
|
||
- 当前市场状态
|
||
- 当前交易日总净流入
|
||
- 港股通（沪）与港股通（深）拆分
|
||
- 分钟级累计净流入曲线
|
||
- 1 分钟与 5 分钟变化
|
||
- 当前阈值进度
|
||
- 当前数据来源
|
||
- 当前数据精度状态
|
||
- 最近触发的推送记录
|
||
|
||
页面要求：
|
||
|
||
- 清楚区分“盘中值”和“收盘最终值”
|
||
- 清楚展示数据更新时间
|
||
- 若数据暂不可用，必须显示原因或状态，而不是显示假值
|
||
|
||
### 6.2 历史统计页
|
||
|
||
至少展示以下内容：
|
||
|
||
- 日度净流入图
|
||
- 周度净流入图
|
||
- 月度净流入图
|
||
- 累计净流入图
|
||
- 最近 20 个交易日概览
|
||
|
||
至少展示以下统计卡：
|
||
|
||
- 自 `2026-01-01` 起累计净流入
|
||
- 历史交易日数量
|
||
- 最大单日净流入
|
||
- 最大单日净流出
|
||
- 连续净流入天数
|
||
- 连续净流出天数
|
||
|
||
### 6.3 推送记录页
|
||
|
||
至少展示以下内容：
|
||
|
||
- 推送时间
|
||
- 推送类型
|
||
- 触发规则
|
||
- 触发时资金数值
|
||
- 邮件标题
|
||
- 邮件发送状态
|
||
- 错误信息
|
||
- 筛选与查询能力
|
||
|
||
### 6.4 规则配置页
|
||
|
||
至少支持以下配置项展示与维护：
|
||
|
||
- 实时采集间隔
|
||
- 历史回补起始日
|
||
- 阈值突破档位
|
||
- 5 分钟异动阈值
|
||
- 邮件开关
|
||
- 发件邮箱
|
||
- SMTP 地址与端口
|
||
- 收件人列表
|
||
- 当前主数据源
|
||
|
||
## 7. 告警需求
|
||
|
||
### 7.1 5 分钟异动提醒
|
||
|
||
规则要求：
|
||
|
||
- 当 5 分钟内净变化绝对值超过设定阈值时触发提醒
|
||
- 需区分“快速流入”和“快速流出”
|
||
- 同类提醒在冷却窗口内只发送一次
|
||
|
||
默认配置建议：
|
||
|
||
- 窗口：`5` 分钟
|
||
- 冷却：`5` 分钟
|
||
- 阈值：可配置，不写死到代码中
|
||
|
||
### 7.2 阈值突破提醒
|
||
|
||
规则要求：
|
||
|
||
- 当日累计净流入每突破一个固定档位时发送提醒
|
||
- 默认档位为每 `50` 亿港元
|
||
- 同一交易日内，同一档位仅提醒一次
|
||
- 次日重新计数
|
||
|
||
示例：
|
||
|
||
- 突破 `50` 亿发送一次
|
||
- 突破 `100` 亿发送一次
|
||
- 突破 `150` 亿发送一次
|
||
|
||
### 7.3 推送留痕
|
||
|
||
所有推送行为必须持久化保存，至少保留：
|
||
|
||
- 推送时间
|
||
- 推送类型
|
||
- 规则编码
|
||
- 触发值
|
||
- 触发说明
|
||
- 邮件标题
|
||
- 邮件摘要
|
||
- 发送状态
|
||
- 错误信息
|
||
|
||
## 8. 数据源与采集要求
|
||
|
||
### 8.1 数据源限制
|
||
|
||
首版正式口径限定为：
|
||
|
||
- 数据源：`同花顺`
|
||
- 采集范围：`沪深港通 / 港股通` 相关页面与真实接口
|
||
|
||
### 8.2 采集要求
|
||
|
||
系统需支持：
|
||
|
||
- 分钟级实时采集
|
||
- 日终归档
|
||
- 历史回补
|
||
- 失败重试
|
||
- 原始载荷保存
|
||
- 采集日志记录
|
||
|
||
### 8.3 数据可信要求
|
||
|
||
每条采集结果至少需要保留：
|
||
|
||
- `trade_date`
|
||
- `snapshot_time`
|
||
- `source_name`
|
||
- `source_url`
|
||
- `precision`
|
||
- `payload_type`
|
||
- `raw_payload`
|
||
|
||
### 8.4 失败降级要求
|
||
|
||
如果实时接口不可用：
|
||
|
||
- 页面展示“数据暂不可用”
|
||
- 不得自动降级成新闻快讯阈值口径
|
||
- 必须记录失败原因和最后一次成功采集时间
|
||
|
||
## 9. 后端需求
|
||
|
||
### 9.1 技术栈
|
||
|
||
- 语言：`Python`
|
||
- Web 框架：`FastAPI`
|
||
- 存储：首版 `JSON` 文件，后续迁移 `MySQL`
|
||
|
||
### 9.2 后端核心模块
|
||
|
||
- 数据采集模块
|
||
- 历史回补模块
|
||
- 数据归档模块
|
||
- 指标计算模块
|
||
- 告警引擎模块
|
||
- 邮件发送模块
|
||
- API 服务模块
|
||
- 推送日志模块
|
||
|
||
### 9.3 存储设计要求
|
||
|
||
首版至少包含以下存储单元或等价结构：
|
||
|
||
- 分钟快照
|
||
- 日统计
|
||
- 周统计
|
||
- 月统计
|
||
- 推送记录
|
||
- 告警触发记录
|
||
- 原始采集结果
|
||
- 系统配置
|
||
|
||
建议按目录或文件集合进行组织，例如：
|
||
|
||
- `minute_snapshots/*.json`
|
||
- `daily_stats/*.json`
|
||
- `weekly_stats/*.json`
|
||
- `monthly_stats/*.json`
|
||
- `push_records/*.json`
|
||
- `alert_triggers/*.json`
|
||
- `raw_payloads/*.json`
|
||
- `system_config.json`
|
||
|
||
### 9.4 首版 JSON 存储要求
|
||
|
||
- JSON 文件需按模块拆分，禁止所有数据写入单一大文件。
|
||
- 需支持按交易日或时间分片，避免文件无限增长。
|
||
- 写入需具备基本原子性，避免采集中断导致 JSON 损坏。
|
||
- 读取层需封装统一接口，前端 API 与业务模块不直接操作文件路径。
|
||
- 历史聚合结果允许单独缓存为 JSON，减少页面重复计算开销。
|
||
|
||
### 9.5 远期 MySQL 迁移要求
|
||
|
||
- 业务层通过 Repository 或 Storage Adapter 访问数据。
|
||
- JSON 字段命名需尽量与未来 MySQL 字段命名保持一致。
|
||
- 迁移后 API 出参结构不应变化。
|
||
- JSON 阶段的历史数据需可导入 MySQL。
|
||
|
||
## 10. 前端需求
|
||
|
||
### 10.1 技术栈
|
||
|
||
- 框架：`Vue 3`
|
||
- 推荐：Composition API + TypeScript
|
||
|
||
### 10.2 设计要求
|
||
|
||
- 页面风格偏金融信息终端，而不是普通后台管理系统
|
||
- 重点信息层级清晰，数值、趋势、时间、来源必须易于识别
|
||
- 支持桌面端优先，同时兼容移动端基本浏览
|
||
|
||
### 10.3 交互要求
|
||
|
||
- 数据加载时有明确加载状态
|
||
- 无数据时有明确空状态
|
||
- 错误时有明确错误状态
|
||
- 每个核心模块都能看到“更新时间”和“数据来源”
|
||
|
||
## 11. API 需求
|
||
|
||
首版建议至少提供以下接口：
|
||
|
||
- `/api/health`：健康检查
|
||
- `/api/meta`：系统元信息、市场状态、数据源信息
|
||
- `/api/overview`：实时总览
|
||
- `/api/history`：历史统计
|
||
- `/api/push-records`：推送记录
|
||
- `/api/rules`：规则与配置
|
||
- `/api/source-diagnostics`：采集诊断结果
|
||
|
||
`/api/source-diagnostics` 至少返回：
|
||
|
||
- 当前主源
|
||
- 最后一次成功采集时间
|
||
- 最后一次失败时间
|
||
- 最近错误原因
|
||
- 最近成功的来源 URL
|
||
- 当前实时接口可用性
|
||
- 当前历史接口可用性
|
||
|
||
## 12. 非功能需求
|
||
|
||
### 12.1 稳定性
|
||
|
||
- 单次抓取失败不能导致服务整体不可用
|
||
- 邮件发送失败需记录并可重试
|
||
- 前端页面异常不应影响后台采集
|
||
|
||
### 12.2 可维护性
|
||
|
||
- 采集逻辑、指标逻辑、告警逻辑、API 逻辑、展示逻辑分层
|
||
- 配置项外置，不写死在代码中
|
||
- 关键数据结构命名稳定，便于后续迁移数据库和增加数据源
|
||
|
||
### 12.3 可观测性
|
||
|
||
- 记录采集成功/失败日志
|
||
- 记录接口耗时
|
||
- 记录最近一次成功持久化时间
|
||
- 支持快速定位某天某次采集所用源链接
|
||
|
||
## 13. 验收标准
|
||
|
||
### 13.1 实时采集验收
|
||
|
||
- 交易时段内可按配置周期写入分钟级快照
|
||
- 页面可展示当日最新实时值
|
||
- 总值等于港股通（沪）与港股通（深）汇总
|
||
- 每条实时记录可追溯到同花顺真实接口或页面
|
||
|
||
### 13.2 收盘归档验收
|
||
|
||
- 当天 `16:10` 后能将当日结果标记为最终值
|
||
- 收盘后历史页可看到该交易日准确结果
|
||
- 当日最终值与盘中值状态区分清楚
|
||
|
||
### 13.3 历史统计验收
|
||
|
||
- 可查看自 `2026-01-01` 起的日/周/月/累计统计
|
||
- 统计结果由真实历史数据生成
|
||
- 最近 20 个交易日可正常查询
|
||
- JSON 存储内容可被系统正确读取并生成页面结果
|
||
|
||
### 13.4 告警验收
|
||
|
||
- 50 亿档位突破可触发一次邮件
|
||
- 5 分钟异动可触发提醒
|
||
- 所有推送记录均可在页面查询
|
||
|
||
### 13.5 展示验收
|
||
|
||
- 前端风格具备专业金融看板特征
|
||
- 桌面端与移动端基本可用
|
||
- 核心数值、来源、更新时间、精度状态清晰可读
|
||
|
||
## 14. 当前实施状态
|
||
- 真实数据源切换到东方财富：历史由 `https://datacenter-web.eastmoney.com/api/data/v1/get`（`reportName=RPT_MUTUAL_DEAL_HISTORY`、`MUTUAL_TYPE in ("002","004")`）回溯；分钟/实时由 `https://push2.eastmoney.com/api/qt/kamt/get` 与 `https://push2.eastmoney.com/api/qt/kamtbs.rtmin/get` 拉取，数据写进 `backend/data/raw_payloads/` 并由同步脚本处理。
|
||
- JSON 存储按模块组织：`minute_snapshots/<trade_date>.json`、`daily_stats/summary.json`、`push_records/records.json` 等，Repository 层屏蔽路径，前端与 API 只关心字段；`tools/sync_eastmoney.py` 可按需触发并自动刷新数据与历史。
|
||
- 推送与告警链路已经打通：新增 `alert_service` + `email_notification_service`，支持 QQ SMTP（`sender_email` / `smtp_username` / `smtp_password` / `recipients`）；已有 `tools/send_test_alert.py` 脚本和 `POST /api/push-records/test` 接口可立即生成一条基于当前快照的测试邮件，并把记录写入 `backend/data/push_records/records.json`。
|
||
- 前端推送记录页改为列表展示，默认显示最新 6 条记录，分类展示状态、时间、规则、触发值、摘要、描述与错误信息。不再在页面暴露规则配置详情；配置通过`backend/data/system_config.json`、`monitoring_repository` 等存储。
|
||
- 实时页面、历史页面、推送记录页面已通过 Tab 切换控制，总体页面无滚动条；日/周曲线以 SVG 图表形式呈现，配置/规则信息保留在后端，并把推送记录单独展示，确保可验证效果。
|