zjjk/南向资金监控平台需求.md

南向资金监控平台需求文档

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 图表形式呈现，配置/规则信息保留在后端，并把推送记录单独展示，确保可验证效果。