137 lines
5.1 KiB
Markdown
137 lines
5.1 KiB
Markdown
# 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`）
|