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

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

> 架构设计见 [`ARCHITECTURE.md`](./ARCHITECTURE.md)；数据字段口径见 [`DATA_MODEL.md`](./DATA_MODEL.md)。

---

## 一句话架构

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

---

## 快速开始（Docker）

```bash
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`）。**留空则对应同步自动跳过、不报错。**

```bash
# 指数(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` 协议：
   ```python
   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 批量导入**：
  ```bash
  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**（见下）。

```bash
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`）