Initial commit

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

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