A股大事记录 · 大周期择时看板

把 指数日成交量、ETF流入、股民情绪、重大事件 按时间轴叠加到 上证综指 / 创业板指 / 科创50 的指数K线上，形成一份 A 股「大事记录」， 辅助判断 A 股 大周期的顶与底。

架构设计见 ARCHITECTURE.md；数据字段口径见 DATA_MODEL.md。

---

一句话架构

ETL 从现有内网库(zs_day_data / gp_market_sentiment)同步 → 自有 Postgres → FastAPI + ECharts 看板。 事件与 ETF 人工录入为主，预留自动化接口；指数 OHLC 用可插拔 Provider（你后续提供，暂以收盘线兜底）。

---

快速开始（Docker）

cp .env.example .env          # 按需填内网库 DSN（不填也能起，只是无数据）
docker compose up -d --build  # 起 db(自有Postgres) + backend(FastAPI+前端)
# 打开看板
open http://localhost:8000

首启会自动建表（ddl/own_db_init.sql + ORM 双保险）。此时自有库还没数据，需要同步 ↓

同步数据（ETL）

前提：在 .env 里配置了可达的 LEGACY_MYSQL_DSN（读 zs_day_data）与 LEGACY_PG_DSN（读 gp_market_sentiment）。留空则对应同步自动跳过、不报错。

# 指数(close/成交额) + 情绪 一起同步
docker compose exec backend python -m app.etl sync-all --start 20150101

# 或分开
docker compose exec backend python -m app.etl sync-index    --start 20150101
docker compose exec backend python -m app.etl sync-sentiment --start 20150101

也可在看板点「同步数据」按钮，或 POST /api/sync/index、/api/sync/sentiment。 后续可把上面命令挂到宿主机 cron / 容器内 APScheduler 做每日增量。

---

接入指数 OHLC 源（你后续提供）

现有 zs_day_data 只有 close，画不了完整蜡烛图，看板默认显示收盘线。 你拿到 OHLC 源后：

1. 在 backend/app/sources.py 实现一个类，满足 OHLCProvider 协议：

   class MyOHLCProvider:
       name = "myprovider"
       def fetch(self, index_code, start, end):
           # 返回 {date: IndexBar(open/high/low/close[/volume])}
           ...
   

2. 注册到同文件的 _OHLC_REGISTRY。
3. .env 里 OHLC_PROVIDER=myprovider，重跑 sync-index。 看板检测到 OHLC 后自动切换为蜡烛图。

---

事件 / ETF 录入

• 人工录入：看板右下角表单直接加事件；ETF 用 POST /api/etf。
• CSV 批量导入：

  curl -F file=@ddl/event_import_template.csv http://localhost:8000/api/events/import
  curl -F file=@ddl/etf_import_template.csv   http://localhost:8000/api/etf/import
  

  模板与列说明见 ddl/event_import_template.csv、ddl/etf_import_template.csv。
• 自动化接入（预留）：backend/app/importers.py 里 register_auto_event_source / register_auto_etf_source，实现后可挂新闻/公告/资金流抓取。

---

顶底「市场温度」

看板底部温度副图 0–100：越高越过热（顶部风险，红），越低越冰点（底部机会，蓝）。 由 量能分位 / 价格分位 / 情绪 / ETF出货热度 加权得到，权重与阈值在 .env 可调 （W_VOL/W_PRICE/W_SENTIMENT/W_ETF、HOT/COLD_THRESHOLD），方法论见 ARCHITECTURE.md §5。

初值仅供起步，请用你自己的历史数据回测校准。

---

开发 / 部署 · Git 工作流

开发机改代码 → 提交 → 推送；服务器 git pull → docker compose up -d --build。 数据在自有库卷里，不随代码走。每个里程碑请及时 commit（见下）。

git add .
git commit -m "milestone: xxx"
git push

目录结构

as-event/
├─ docker-compose.yml        # db(Postgres) + backend
├─ .env.example              # 配置样例
├─ ARCHITECTURE.md           # 架构设计
├─ ddl/
│  ├─ own_db_init.sql        # 自有库建表
│  ├─ event_import_template.csv
│  └─ etf_import_template.csv
├─ backend/
│  ├─ Dockerfile
│  ├─ requirements.txt
│  └─ app/
│     ├─ config.py           # 配置/环境变量
│     ├─ db.py               # 自有库 ORM 模型
│     ├─ sources.py          # 现有库读适配 + 可插拔 OHLC Provider
│     ├─ etl.py              # 同步 CLI
│     ├─ signals.py          # 顶底温度启发式
│     ├─ importers.py        # 录入/导入 + 自动化接口
│     ├─ schemas.py          # API 模型
│     ├─ api.py              # REST 路由
│     └─ main.py             # FastAPI 入口
└─ frontend/
   ├─ index.html             # ECharts 看板（单文件）
   └─ vendor/echarts.min.js  # 本地内置(适配内网离线)

API 速览

GET /api/health · GET /api/index/list · GET /api/index/{code}/kline · GET /api/sentiment · GET /api/etf · GET/POST/PUT/DELETE /api/events · POST /api/events/import · POST /api/etf/import · GET /api/annotations · POST /api/sync/index · POST /api/sync/sentiment （在线文档 http://localhost:8000/docs）