# 南向资金监控平台需求文档 ## 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/.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 图表形式呈现，配置/规则信息保留在后端，并把推送记录单独展示，确保可验证效果。