python_market_data_service/TABLE_SPLIT_DESIGN.md

# 数据表分表设计文档

## 设计原则

所有K线数据表按照**数据类型**和**更新频率**进行拆分：
1. **基础表(Base)**: OHLCV等原始行情数据，更新频率高
2. **行情表(Quote)**: 技术指标(均线/MACD/涨跌幅)，需要计算
3. **财务表(Finance)**: 市值/股本等财务数据，更新频率低

## 股票数据表

### 日线数据 (1d)

| 表名 | 说明 | 主要字段 |
|------|------|----------|
| `stock_klines_1d_base` | 日线基础表 | symbol_id, trade_date, open, high, low, close, volume, amount, adj_factor |
| `stock_klines_1d_quote` | 日线行情表 | change_pct, ma5/10/20/30/60/120/250, macd_dif/dea/bar, bias5/10/20, is_limit_up/down, is_st |
| `stock_klines_1d_finance` | 日线财务表 | total_market_cap, float_market_cap, total_shares, float_shares, inst_holding_ratio, net_profit, revenue, eps, roe |

### 分钟线数据

| 表名 | 说明 | 主要字段 |
|------|------|----------|
| `stock_klines_1m` | 1分钟线 | symbol_id, ts, trade_date, open, high, low, close, volume, amount, change_pct, macd_dif/dea/bar |
| `stock_klines_5m` | 5分钟线 | 同上 |
| `stock_klines_15m` | 15分钟线 | 同上 |
| `stock_klines_30m` | 30分钟线 | 同上 |
| `stock_klines_60m` | 60分钟线 | 同上 |

### 周月线数据

| 表名 | 说明 | 主要字段 |
|------|------|----------|
| `stock_klines_1w` | 周线 | symbol_id, ts, trade_date, open, high, low, close, volume, amount |
| `stock_klines_1month` | 月线 | 同上 |

### 实时数据

| 表名 | 说明 | 主要字段 |
|------|------|----------|
| `stock_realtime_quotes` | 实时行情快照 | symbol_id, last_price, open, high, low, volume, amount, bid1, ask1 |

### 基础数据

| 表名 | 说明 | 主要字段 |
|------|------|----------|
| `stock_symbols` | 股票列表 | symbol_id, name, exchange, list_date, industry, status |
| `stock_trading_calendar` | 交易日历 | trade_date, is_trading_day, week_day |
| `stock_adjust_factors` | 复权系数 | symbol_id, trade_date, qfq_factor, hfq_factor |

---

## 期货数据表

### 日线数据 (1d)

| 表名 | 说明 | 主要字段 |
|------|------|----------|
| `futures_klines_1d_base` | 日线基础表 | symbol_id, trade_date, open, high, low, close, volume, amount, open_interest, settlement, pre_settlement |
| `futures_klines_1d_quote` | 日线行情表 | change_pct, ma5/10/20/30/60, macd_dif/dea/bar, oi_change, oi_change_pct, amplitude |

### 分钟线数据

| 表名 | 说明 | 主要字段 |
|------|------|----------|
| `futures_klines_1m_base` | 1分钟基础表 | symbol_id, ts, trade_date, open, high, low, close, volume, amount, open_interest |
| `futures_klines_5m_base` | 5分钟基础表 | 同上 |
| `futures_klines_15m_base` | 15分钟基础表 | 同上 |
| `futures_klines_30m_base` | 30分钟基础表 | 同上 |
| `futures_klines_60m_base` | 60分钟基础表 | 同上 |

### 周月线数据

| 表名 | 说明 | 主要字段 |
|------|------|----------|
| `futures_klines_1w_base` | 周线基础表 | symbol_id, ts, trade_date, open, high, low, close, volume, amount, open_interest |
| `futures_klines_1month_base` | 月线基础表 | 同上 |

### 实时数据

| 表名 | 说明 | 主要字段 |
|------|------|----------|
| `futures_realtime_quotes` | 实时行情快照 | symbol_id, last_price, open, high, low, volume, amount, open_interest, bid1, ask1, limit_up, limit_down |

### 基础数据

| 表名 | 说明 | 主要字段 |
|------|------|----------|
| `futures_symbols` | 合约列表 | symbol_id, name, exchange, underlying, contract_month, list_date, delist_date |
| `futures_trading_calendar` | 交易日历 | trade_date, is_trading_day, has_night_session, week_day |

---

## 代码实现

### Repository 结构

```
app/repositories/
├── stock_repository_v2.py      # 股票分表仓库
├── futures_repository_v2.py    # 期货分表仓库
└── models.py                    # 所有模型定义
```

### 关键方法

#### StockRepositoryV2
```python
# 基础数据操作
get_klines_base(symbol, freq, start, end) -> List[Dict]
save_klines_base(freq, items) -> int

# 行情数据操作
get_klines_quote(symbol, start_date, end_date) -> List[Dict]
save_klines_quote(items) -> int

# 财务数据操作
get_klines_finance(symbol, start_date, end_date) -> List[Dict]
save_klines_finance(items) -> int

# 实时行情
get_realtime_quote(symbol) -> Optional[Dict]
save_realtime_quote(data) -> None
```

#### FuturesRepositoryV2
```python
# 基础数据操作
get_klines_base(symbol, freq, start, end) -> List[Dict]
save_klines_base(freq, items) -> int

# 行情数据操作
get_klines_quote(symbol, start_date, end_date) -> List[Dict]
save_klines_quote(items) -> int

# 实时行情
get_realtime_quote(symbol) -> Optional[Dict]
save_realtime_quote(data) -> None
```

---

## 使用示例

### 股票数据查询

```python
from app.repositories.stock_repository_v2 import StockRepositoryV2
from app.repositories.database import SessionLocal
from app.models import Frequency

db = SessionLocal()
repo = StockRepositoryV2(db)

# 只查询基础数据（高效）
base_data = repo.get_klines_base(
    symbol="600519.SH",
    freq=Frequency.FREQ_1D,
    start=datetime(2024, 1, 1),
    end=datetime(2024, 3, 1)
)

# 查询行情指标
quote_data = repo.get_klines_quote(
    symbol="600519.SH",
    start_date="2024-01-01",
    end_date="2024-03-01"
)

# 查询财务数据
finance_data = repo.get_klines_finance(
    symbol="600519.SH",
    start_date="2024-01-01",
    end_date="2024-03-01"
)
```

### 期货数据查询

```python
from app.repositories.futures_repository_v2 import FuturesRepositoryV2

db = SessionLocal()
repo = FuturesRepositoryV2(db)

# 查询期货基础数据
base_data = repo.get_klines_base(
    symbol="RB2410.SH",
    freq=Frequency.FREQ_1D,
    start=datetime(2024, 1, 1),
    end=datetime(2024, 3, 1)
)

# 查询期货行情指标
quote_data = repo.get_klines_quote(
    symbol="RB2410.SH",
    start_date="2024-01-01",
    end_date="2024-03-01"
)
```

---

## 创建表的脚本

```bash
# 创建所有分表
python scripts/create_split_tables.py

# 重新创建（会删除已有数据）
python scripts/create_split_tables.py --drop-existing
```

---

## 数据同步

### 股票数据同步
```bash
# 全量同步
curl -X POST "http://localhost:8080/admin/data/sync" \
  -H "Content-Type: application/json" \
  -d '{
    "symbols": ["600519.SH", "000001.SZ"],
    "sync_type": "full",
    "start_date": "20240101",
    "end_date": "20240301"
  }'
```

### 期货数据同步
期货数据同步API待实现，可参考股票同步API实现类似接口。

---

## 性能优势

1. **查询优化**: 只需基础数据时，只查询轻量的base表
2. **更新解耦**: 
   - 基础数据: 每日收盘后更新
   - 行情指标: 计算后批量更新
   - 财务数据: 财报季更新
3. **存储优化**: 热点数据(base)和冷数据(finance)分离存储
4. **扩展性**: 新增指标只需修改quote表，不影响其他表

---

## 后续扩展

1. **分钟线行情表**: 为高频策略提供分钟级技术指标
2. **跨表查询视图**: 创建联合视图方便查询
3. **数据分区**: 按trade_date对大表进行分区
4. **缓存层**: Redis缓存热点基础数据