zjjk/README.md

南向资金监控平台

当前需求概览

• 以港股通南向资金为唯一统计口径，实时展示当日总净流入、沪深拆分、时段阈值、分钟级趋势，并在非交易时段沉淀自 2026-01-01 起的日/周/月/累计历史。
• 所有数据必须可追溯到真实采集接口，至少记录采集时间、来源、精度、原始载荷；前端展示「盘中值」「收盘最终值」「历史精度」等标记，避免推测数值。
• 关键事件（阈值突破、5 分钟异动）要形成邮件提示，并把推送记录持久化；推送记录页按时间倒序展示每条通知、规则、触发值、状态与错误信息。
• 当前版本使用 JSON 文件作为存储介质，Repository 层屏蔽路径与命名细节，保持未来迁移 MySQL 所需的与 API 一致的字段契约。

目录说明

• backend/：FastAPI + JSON Repository + 采集/聚合/告警/邮件逻辑，启动在 localhost:10000。
• frontend/：Vue 3 + TypeScript、Composition API，Tab 风格单页展示实时、历史、推送三个面板。
• tools/：辅助脚本（同步东财、发送测试邮件等），用于手动触发数据或告警流程。
• 南向资金监控平台需求.md：正式版需求文档与当前实施状态说明。

启动流程

后端

python -m pip install -r backend/requirements.txt
python -m uvicorn app.main:app --app-dir backend --host 127.0.0.1 --port 10000

前端

cd frontend
npm install
npm run dev -- --host 0.0.0.0 --port 9000

目前推荐用 npm run build 生成 dist/ 后再用 python -m http.server 9000 或任何静态服务直接提供，因为 Vite dev server 在当前安全环境下有权限限制。

数据与推送维护

• 实时+历史数据由 tools/sync_eastmoney.py 拉取并写入 backend/data/minute_snapshots/、daily_stats/summary.json 等；可定时或手动触发。
• backend/data/system_config.json 记录阈值、邮件、数据源配置；添加了 smtp_username 与 smtp_password 等字段，填入腾讯授权码即可发送。
• tools/send_test_alert.py 和新的 POST /api/push-records/test 接口会生成一条基于当前快照的测试推送，并写入 backend/data/push_records/records.json，方便前端列表展示。

关键文档

• 需求全貌：南向资金监控平台需求.md
• 运行日志：run_backend.out.log、run_backend.err.log、run_frontend.err.log
• 配置：backend/data/system_config.json（sender_email / smtp_username / smtp_password / recipients）

下一步建议

1. 让运维持续运行 tools/sync_eastmoney.py，保证数据每日自动刷新并在 backend/data/ 下形成新的 JSON。
2. 结合最新推送记录，把前端列表配色补充成更明显的状态差异（绿色、橙、红）。
3. 计划将 push_records 和告警指标逐步拔高为数据库存储，API 输出保持不变，避免前端适配成本。