135 lines
8.5 KiB
Markdown
135 lines
8.5 KiB
Markdown
# 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/事件抓取）按需开启
|