python_market_data_service/DATABASE_REFACTOR.md

# 数据库结构重设计文档

## 背景

原有数据库使用单一的 `stock_klines_1d` 表存储所有日线数据，包含OHLCV、涨跌停状态、市值等多个维度的信息。这种设计在以下场景存在问题：

1. **数据来源不一致**：OHLCV来自行情接口，财务数据来自股本/财报接口，合并存储导致更新频率不一致
2. **查询效率低**：不需要财务指标时仍需查询包含大量字段的宽表
3. **扩展困难**：新增指标需要修改表结构，影响线上服务

## 新表结构设计

### 1. 日线历史数据表 (1d)

#### stock_klines_1d_base - 日线基础表
存储最基础的K线数据，对应 `query_kline` 接口。

```sql
CREATE TABLE stock_klines_1d_base (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    symbol_id VARCHAR(20) NOT NULL COMMENT '标的代码',
    ts DATETIME NOT NULL COMMENT '时间戳',
    trade_date VARCHAR(10) NOT NULL COMMENT '交易日 YYYY-MM-DD',
    open DECIMAL(18,4) COMMENT '开盘价',
    high DECIMAL(18,4) COMMENT '最高价',
    low DECIMAL(18,4) COMMENT '最低价',
    close DECIMAL(18,4) COMMENT '收盘价',
    volume BIGINT COMMENT '成交量(股)',
    amount DECIMAL(20,4) COMMENT '成交额(元)',
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX idx_symbol_ts (symbol_id, ts),
    INDEX idx_symbol_date (symbol_id, trade_date)
) COMMENT='股票日线K线-基础表';
```

#### stock_klines_1d_quote - 日线行情表
存储行情技术指标，需要在基础数据基础上计算。

```sql
CREATE TABLE stock_klines_1d_quote (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    symbol_id VARCHAR(20) NOT NULL COMMENT '标的代码',
    trade_date VARCHAR(10) NOT NULL COMMENT '交易日',
    change_pct DECIMAL(8,4) COMMENT '涨跌幅(%)',
    change_5d_pct DECIMAL(8,4) COMMENT '5日涨跌幅',
    change_10d_pct DECIMAL(8,4) COMMENT '10日涨跌幅',
    change_20d_pct DECIMAL(8,4) COMMENT '20日涨跌幅',
    change_30d_pct DECIMAL(8,4) COMMENT '30日涨跌幅',
    change_60d_pct DECIMAL(8,4) COMMENT '60日涨跌幅',
    ma5 DECIMAL(18,4) COMMENT '5日均线',
    ma10 DECIMAL(18,4) COMMENT '10日均线',
    ma20 DECIMAL(18,4) COMMENT '20日均线',
    ma30 DECIMAL(18,4) COMMENT '30日均线',
    ma60 DECIMAL(18,4) COMMENT '60日均线',
    ma120 DECIMAL(18,4) COMMENT '120日均线',
    ma250 DECIMAL(18,4) COMMENT '250日均线',
    macd_dif DECIMAL(18,6) COMMENT 'MACD DIF',
    macd_dea DECIMAL(18,6) COMMENT 'MACD DEA',
    macd_bar DECIMAL(18,6) COMMENT 'MACD BAR',
    bias5 DECIMAL(8,4) COMMENT '5日乖离率',
    bias10 DECIMAL(8,4) COMMENT '10日乖离率',
    bias20 DECIMAL(8,4) COMMENT '20日乖离率',
    is_limit_up BOOLEAN COMMENT '是否涨停',
    is_limit_down BOOLEAN COMMENT '是否跌停',
    limit_up_price DECIMAL(18,4) COMMENT '涨停价',
    limit_down_price DECIMAL(18,4) COMMENT '跌停价',
    is_st BOOLEAN COMMENT '是否ST',
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX idx_symbol_date (symbol_id, trade_date)
) COMMENT='股票日线K线-行情指标表';
```

#### stock_klines_1d_finance - 日线财务表
存储财务相关数据，对应 `get_equity_structure` / `get_share_holder` / `get_income` 等接口。

```sql
CREATE TABLE stock_klines_1d_finance (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    symbol_id VARCHAR(20) NOT NULL COMMENT '标的代码',
    trade_date VARCHAR(10) NOT NULL COMMENT '交易日',
    total_market_cap DECIMAL(20,4) COMMENT '总市值(元)',
    float_market_cap DECIMAL(20,4) COMMENT '流通市值(元)',
    total_shares BIGINT COMMENT '总股本(股)',
    float_shares BIGINT COMMENT '流通股本(股)',
    inst_holding_shares BIGINT COMMENT '机构持股数量',
    inst_holding_ratio DECIMAL(8,4) COMMENT '机构持仓占比(%)',
    top10_holders_ratio DECIMAL(8,4) COMMENT '前十大股东持股占比(%)',
    net_profit DECIMAL(20,4) COMMENT '净利润',
    revenue DECIMAL(20,4) COMMENT '营业总收入',
    eps DECIMAL(12,4) COMMENT '每股收益',
    roe DECIMAL(8,4) COMMENT '净资产收益率(%)',
    trading_days INT COMMENT '从上市至今交易日数',
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX idx_symbol_date (symbol_id, trade_date)
) COMMENT='股票日线K线-财务数据表';
```

### 2. 其他周期历史数据表

分钟线/周线/月线只保留基础K线数据和简单指标：

- `stock_klines_1m` - 1分钟线
- `stock_klines_5m` - 5分钟线
- `stock_klines_15m` - 15分钟线
- `stock_klines_30m` - 30分钟线
- `stock_klines_60m` - 60分钟线
- `stock_klines_1w` - 周线
- `stock_klines_1month` - 月线

字段结构：
```sql
symbol_id, ts, trade_date, open, high, low, close, volume, amount,
change_pct, macd_dif, macd_dea, macd_bar
```

### 3. 实时数据表

#### stock_realtime_quotes - 实时行情快照
```sql
CREATE TABLE stock_realtime_quotes (
    symbol_id VARCHAR(20) PRIMARY KEY COMMENT '标的代码',
    update_time DATETIME COMMENT '更新时间',
    last_price DECIMAL(18,4) COMMENT '最新价',
    open DECIMAL(18,4) COMMENT '开盘价',
    high DECIMAL(18,4) COMMENT '最高价',
    low DECIMAL(18,4) COMMENT '最低价',
    pre_close DECIMAL(18,4) COMMENT '昨收',
    volume BIGINT COMMENT '成交量',
    amount DECIMAL(20,4) COMMENT '成交额',
    bid1 DECIMAL(18,4) COMMENT '买一价',
    ask1 DECIMAL(18,4) COMMENT '卖一价',
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
) COMMENT='股票实时行情快照';
```

### 4. 基础数据表

#### stock_basic_info - 股票基础信息
```sql
CREATE TABLE stock_basic_info (
    symbol_id VARCHAR(20) PRIMARY KEY COMMENT '标的代码',
    name VARCHAR(100) COMMENT '名称',
    exchange VARCHAR(10) COMMENT '交易所',
    list_date DATE COMMENT '上市日期',
    list_board VARCHAR(20) COMMENT '上市板块',
    industry VARCHAR(50) COMMENT '所属行业',
    status VARCHAR(10) COMMENT '状态 active/delisted',
    is_delisted BOOLEAN COMMENT '是否退市',
    delist_date DATE COMMENT '退市日期',
    is_st BOOLEAN COMMENT '是否ST',
    total_shares BIGINT COMMENT '总股本',
    float_shares BIGINT COMMENT '流通股本',
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
) COMMENT='股票基础信息';
```

#### stock_trading_calendar - 交易日历
```sql
CREATE TABLE stock_trading_calendar (
    trade_date VARCHAR(8) PRIMARY KEY COMMENT '交易日 YYYYMMDD',
    is_trading_day BOOLEAN COMMENT '是否交易日',
    week_day TINYINT COMMENT '星期几 1-7'
) COMMENT='交易日历';
```

## 代码结构

### 新增文件

1. **app/repositories/stock_repository_v2.py** - 支持拆分表结构的新仓库
   - `get_klines_base()` / `save_klines_base()` - 基础数据操作
   - `get_klines_quote()` / `save_klines_quote()` - 行情数据操作
   - `get_klines_finance()` / `save_klines_finance()` - 财务数据操作

2. **app/services/data_sync_service.py** - 数据同步服务
   - `sync_kline_base()` - 同步基础K线数据
   - `sync_kline_quote()` - 同步行情指标数据
   - `sync_kline_finance()` - 同步财务数据
   - `sync_full_stock_data()` - 全量同步
   - `sync_daily_incremental()` - 每日增量同步

3. **app/api/admin_routes.py** - 新增数据同步API
   - `POST /admin/data/sync` - 手动触发数据同步
   - `POST /admin/data/sync/incremental` - 增量同步

### 适配器接口扩展

**app/adapters/base.py** 新增抽象方法：
- `fetch_kline_base()` - 获取基础K线数据
- `fetch_kline_quote()` - 获取行情指标数据
- `fetch_kline_finance()` - 获取财务数据
- `fetch_stock_basic_info()` - 获取股票基础信息

**app/adapters/amazingdata_adapter.py** 新增实现：
- `_fetch_kline_base_sync()` - 同步获取基础K线
- `_fetch_kline_quote_sync()` - 同步计算并获取行情指标
- `_fetch_kline_finance_sync()` - 同步获取财务数据
- `_fetch_stock_basic_info_sync()` - 同步获取基础信息

## 使用指南

### 1. 手动触发数据同步

```bash
# 全量同步（基础+行情+财务）
curl -X POST "http://localhost:8080/admin/data/sync" \
  -H "Content-Type: application/json" \
  -H "X-Admin-Token: your_token" \
  -d '{
    "symbols": ["600519.SH", "000001.SZ"],
    "sync_type": "full",
    "start_date": "20240101",
    "end_date": "20240301",
    "asset_class": "stock"
  }'

# 只同步基础K线数据
curl -X POST "http://localhost:8080/admin/data/sync" \
  -H "Content-Type: application/json" \
  -d '{
    "symbols": ["600519.SH"],
    "sync_type": "base",
    "freq": "1d"
  }'

# 只同步行情指标
curl -X POST "http://localhost:8080/admin/data/sync" \
  -H "Content-Type: application/json" \
  -d '{
    "symbols": ["600519.SH"],
    "sync_type": "quote"
  }'
```

### 2. 在代码中使用 Repository

```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)

# 查询基础K线
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"
)
```

### 3. 使用数据同步服务

```python
from app.services.adapter_service import AdapterService
from app.services.data_sync_service import DataSyncService

# 获取适配器
adapter_service = AdapterService()
adapter = adapter_service.get_active_adapter("stock")

# 创建同步服务
sync_service = DataSyncService(adapter)

# 同步指定标的
results = await sync_service.sync_full_stock_data(
    symbols=["600519.SH", "000001.SZ"],
    start="20240101",
    end="20240301"
)
```

## 迁移建议

1. **新部署系统**：直接使用新表结构，旧表可忽略
2. **存量系统迁移**：
   - 使用 `INSERT INTO stock_klines_1d_base SELECT ... FROM stock_klines_1d` 迁移基础数据
   - 行情/财务字段需要重新计算或使用默认值
   - 保持旧表一段时间用于回滚

3. **数据补全策略**：
   - 基础数据：从数据源全量拉取
   - 行情指标：在本地根据基础数据计算
   - 财务数据：从股本结构接口获取历史数据

## 性能优化建议

1. **索引优化**：已为高频查询字段(symbol_id, trade_date, ts)创建联合索引
2. **分区建议**：对于大表可按 `trade_date` 进行按月分区
3. **查询优化**：
   - 只需OHLCV时只查询 base 表
   - 需要指标时 JOIN quote 表
   - 需要财务数据时 JOIN finance 表

## 后续扩展计划

1. **支持更多指标**：RSI、KDJ、布林带等
2. **分钟线行情表**：为高频策略提供分钟级指标
3. **财报季数据表**：季度/年度详细财报数据
4. **资金流向表**：北向资金、主力资金等