Initial commit

README.md

@@ -0,0 +1,42 @@
+# 南向资金监控平台
+
+## 当前需求概览
+- 以港股通南向资金为唯一统计口径，实时展示当日总净流入、沪深拆分、时段阈值、分钟级趋势，并在非交易时段沉淀自 `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 输出保持不变，避免前端适配成本。