# A股大事记录 / 大周期择时看板 · 架构设计

> 目标：把 **指数日成交量、ETF流入、股民情绪、重大事件** 四类信息按时间轴叠加到
> **上证综指 / 创业板指 / 科创50** 的指数K线上，形成一份 A 股「大事记录」，
> 用于辅助判断 A 股 **大周期的顶与底**。
>
> 本文件是设计基线，随迭代更新。数据字段口径参考同目录 `DATA_MODEL.md`。

---

## 1. 设计原则与关键决策

| 决策点 | 结论 | 说明 |
|---|---|---|
| 数据来源 | **直连现有内网库** + 自有库 | 指数收盘/成交额直读 `zs_day_data`(MySQL-A 18.199)，情绪直读 `gp_market_sentiment`(PG 16.150)；本系统另建**自有 Postgres** 存事件、ETF、派生指标与本地快照。 |
| 指数 OHLC | **可插拔 Provider，暂缺** | 现有 `zs_day_data` 只有 `close`，无开/高/低，画不了完整蜡烛图。OHLC 源由你后续提供，系统预留 `OHLCProvider` 接口；未接入时**退化为收盘线**（`ohlc_source='close_only'`），接入后自动转蜡烛图。 |
| ETF & 事件 | **人工录入为主 + 自动化接口预留** | 提供 Web 表单录入 + CSV 导入模板；`importers.py` 预留 `EventImporter`/`EtfFlowImporter` 接口，未来可挂新闻/公告/资金流抓取。 |
| 前端 | **FastAPI + ECharts** | 单页看板：蜡烛图 + 成交量副图 + 情绪/温度副图 + 事件打点；切换指数、缩放、看事件详情。 |
| 部署 | **Docker Compose** | `db`(自有 Postgres) + `backend`(FastAPI，含静态前端)。外部内网库 DSN 走环境变量，可缺省降级。 |
| 数据落地 | **读→同步→自有库→看板** | ETL 从内网库拉取并落一份到自有库；看板只读自有库，保证「大事记录」自包含、可离线回看、事件可长期叠加。 |

### 为什么不直接在看板里跨库实时查？
「大事记录」要长期留存、可离线回看、和事件长期叠加，且要跨 MySQL + PG 联合出图。
因此采用 **ETL 同步进自有库** 的读写分离：内网库只在同步时被读，看板永远读自有库，
既尊重「直连现有库」的选择，又让系统自包含、易 Docker 化、查询快。

---

## 2. 系统拓扑

```
                外部（现有内网库，只读）
   ┌──────────────────────────────┐        ┌──────────────────────────────┐
   │ MySQL-A 192.168.18.199        │        │ PostgreSQL 192.168.16.150     │
   │  zs_day_data(指数 close/额)   │        │  gp_market_sentiment(情绪)    │
   └───────────────┬──────────────┘        └───────────────┬──────────────┘
                   │  (LEGACY_MYSQL_DSN)                    │ (LEGACY_PG_DSN)
                   ▼                                        ▼
         ┌───────────────────────────────────────────────────────────┐
         │                  backend (FastAPI 容器)                    │
         │  sources.py  —— 现有库读适配 + 可插拔 OHLCProvider(预留)   │
         │  etl.py      —— 同步 index_daily / sentiment_daily         │
         │  importers.py—— ETF/事件 CSV导入 + 自动化接口(预留)        │
         │  signals.py  —— 顶底「市场温度」透明启发式                 │
         │  api.py      —— REST 接口                                  │
         │  frontend/index.html —— ECharts 看板(静态挂载)            │
         └───────────────────────────┬───────────────────────────────┘
                                     │ (OWN_DB_DSN)
                                     ▼
                       ┌──────────────────────────────┐
                       │  db: 自有 Postgres(容器)      │
                       │  index_daily / sentiment_daily│
                       │  etf_flow / market_event      │
                       │  cycle_annotation             │
                       └──────────────────────────────┘
```

---

## 3. 指数范围

| 名称 | 代码(dot式) | zs_day_data 有 | 说明 |
|---|---|---|---|
| 上证综指 | `000001.SH` | ✅ | 主看盘 |
| 创业板指 | `399006.SZ` | ✅ | 成长/科技情绪 |
| 科创50 | `000688.SH` | ✅ | 科创板代表指数（科创板本身无指数，用科创50代理） |
| 深证成指 | `399001.SZ` | ✅ | 可选，默认关闭 |

代码统一用 **dot 式**（`000001.SH`），与 `zs_day_data.symbol` 一致，避免格式互转。

---

## 4. 数据模型（自有库）

详见 `ddl/own_db_init.sql` 与 `backend/app/db.py`。摘要：

- **`index_daily`** — 指数日线（同步落地）：`index_code, trade_date, open/high/low/close, volume, amount, pct_chg, turnover_rate, ohlc_source`。唯一键 `(index_code, trade_date)`。
- **`sentiment_daily`** — 情绪日度：`trade_date, up_down_ratio, median_pct_chg, pct_chg_gt_5_count, limit_up/down_count, margin_balance, new_accounts, sentiment_score`。
- **`etf_flow`** — ETF 流入（人工/导入/自动）：`trade_date, etf_code, etf_name, category, related_index, net_inflow(亿元), shares_change, source, note`。
- **`market_event`** — 重大事件：`event_date, title, category(监管/IPO/政策/资金/外部/其他), impact_direction(bullish/bearish/neutral), severity(1-5), related_indices, cycle_tag(top/bottom/none), description, source_url, source(manual/import/auto)`。
- **`cycle_annotation`** — 人工顶底标注（复盘用）：`index_code, anno_date, kind(top/bottom/watch), note`。

---

## 5. 顶底信号方法论（`signals.py`，透明可调）

不做黑盒。综合几个 A 股经典的顶底极值信号，产出每日 **市场温度 0–100** 与离散标记：

| 分量 | 顶部含义 | 底部含义 | 计算 |
|---|---|---|---|
| 量能分位 `vol_pct` | 天量见天价 | 地量见地价 | `amount` 在滚动 N 日(默认250)的百分位 |
| 价格分位 `price_pct` | 高位 | 低位 | `close` 在滚动 N 日的百分位 |
| 情绪分 `sentiment` | 涨停潮/普涨亢奋 | 跌停潮/普跌冰点 | `up_down_ratio`、`pct_chg_gt_5_count` 归一 |
| ETF资金 `etf_z` | 大额净流出 | 大额净流入(国家队) | 净流入 z-score |

**市场温度** = 各分量加权（默认权重写在 `signals.py` 顶部，便于你用自己数据回测调参）。
温度 >80 记 **过热/顶部风险**，<20 记 **冰点/底部机会**，并在看板上以**热力带 + 标记**呈现。

> 权重与阈值是初值，需你在实机用历史数据回测校准；方法论刻意保持透明，不追求复杂模型。

---

## 6. 接口一览（REST）

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/api/health` | 健康检查（含各库连通性） |
| GET | `/api/index/list` | 可用指数列表 |
| GET | `/api/index/{code}/kline?start=&end=` | K线(OHLC/收盘)+成交量+温度 |
| GET | `/api/sentiment?start=&end=` | 情绪日度序列 |
| GET | `/api/etf?start=&end=&index=` | ETF 流入序列 |
| GET/POST/PUT/DELETE | `/api/events` | 事件 CRUD（人工录入） |
| POST | `/api/events/import` `/api/etf/import` | CSV 导入 |
| GET | `/api/signals?code=&start=&end=` | 顶底温度与离散标记 |
| POST | `/api/sync/index` `/api/sync/sentiment` | 触发 ETL（也可 CLI/定时） |

---

## 7. 部署与运维

- `docker compose up -d` 起 `db` + `backend`；前端由 backend 静态挂载，浏览器访问 `:8000`。
- 内网库 DSN（`LEGACY_MYSQL_DSN` / `LEGACY_PG_DSN`）经 `.env` 注入；**留空则该同步自动跳过**（降级不报错）。
- ETL：`docker compose exec backend python -m app.etl sync-index --start 20240101`；后续可挂 cron / APScheduler。
- 开发机 ↔ 服务器：**git 同步代码**；数据不入库随代码走。每个里程碑提示提交。

---

## 8. 里程碑

1. ✅ 架构 + 骨架 + Docker + 自有库DDL
2. ✅ 数据源适配 + ETL + API + 顶底信号
3. ✅ ECharts 看板 + 事件录入/导入
4. ⏳ 实机联调（你跑测试回传）→ OHLC 源接入 → 顶底权重校准
5. ⏳ 自动化接入（ETF/事件抓取）按需开启