python_market_data_service/REFACTOR_SUMMARY.md

# 数据库结构重设计 - 完成总结

## 概述

已完成数据库表结构从单一宽表向拆分表的迁移设计，并实现了完整的数据同步流程。

## 主要改动

### 1. 数据模型层 (app/repositories/models.py)

**新增拆分表模型：**
- `StockKLine1DBase` - 日线基础表 (OHLCV)
- `StockKLine1DQuote` - 日线行情表 (涨跌幅、均线、MACD、乖离率、涨跌停状态)
- `StockKLine1DFinance` - 日线财务表 (市值、股本、机构持股、利润)
- `StockRealTimeQuote` - 实时行情快照表
- `StockBasicInfo` - 股票基础信息表

**向后兼容：**
- 添加 `StockKLine1D = StockKLine1DBase` 别名，保持旧代码兼容

### 2. 数据仓库层 (app/repositories/stock_repository_v2.py)

**新增 Repository：**
- `StockRepositoryV2` - 支持拆分表结构的新仓库
  - `get_klines_base()` / `save_klines_base()` - 基础数据操作
  - `get_klines_quote()` / `save_klines_quote()` - 行情数据操作
  - `get_klines_finance()` / `save_klines_finance()` - 财务数据操作
  - `get_realtime_quote()` / `save_realtime_quote()` - 实时行情操作

### 3. 适配器接口层 (app/adapters/base.py)

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

### 4. AmazingData适配器 (app/adapters/amazingdata_adapter.py)

**新增实现方法：**
- `_fetch_kline_base_sync()` - 从 query_kline 获取基础数据
- `_fetch_kline_quote_sync()` - 计算均线/MACD/乖离率等指标
- `_fetch_kline_finance_sync()` - 从股本结构数据计算市值
- `_fetch_stock_basic_info_sync()` - 获取股票列表和基础信息

### 5. 数据同步服务 (app/services/data_sync_service.py)

**新增服务：**
- `DataSyncService` - 协调数据拉取和存储
  - `sync_kline_base()` - 同步基础K线
  - `sync_kline_quote()` - 同步行情指标
  - `sync_kline_finance()` - 同步财务数据
  - `sync_full_stock_data()` - 全量同步
  - `sync_daily_incremental()` - 每日增量同步

### 6. 管理API层 (app/api/admin_routes.py)

**新增端点：**
- `POST /admin/data/sync` - 手动触发数据同步
  - 支持 sync_type: base/quote/finance/full
  - 支持指定日期范围和标的列表
- `POST /admin/data/sync/incremental` - 增量同步（最近30天）

### 7. 类型定义 (app/models/admin_types.py)

**新增类型：**
- `DataSyncType` - 同步类型枚举
- `DataSyncRequest` - 同步请求
- `DataSyncResult` - 单个标的同步结果
- `DataSyncData` - 同步响应

### 8. 迁移脚本 (scripts/create_split_tables.py)

**功能：**
- 自动创建所有新表
- 支持 `--drop-existing` 参数重建表

## 表结构对比

### 旧表 (stock_klines_1d)
```
symbol_id, ts, trade_date, open, high, low, close, volume, amount,
is_limit_up, is_limit_down, total_market_cap, float_market_cap, 
inst_holding_ratio, trading_days
```

### 新表
```
stock_klines_1d_base:
  symbol_id, ts, trade_date, open, high, low, close, volume, amount

stock_klines_1d_quote:
  symbol_id, trade_date, change_pct, change_Nd_pct, maN, 
  macd_dif/dea/bar, biasN, is_limit_up/down, limit_up/down_price, is_st

stock_klines_1d_finance:
  symbol_id, trade_date, total_market_cap, float_market_cap,
  total_shares, float_shares, inst_holding_shares, inst_holding_ratio,
  top10_holders_ratio, net_profit, revenue, eps, roe, trading_days
```

## API使用示例

### 1. 全量同步
```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"
  }'
```

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

### 3. 增量同步
```bash
curl -X POST "http://localhost:8080/admin/data/sync/incremental" \
  -H "Content-Type: application/json" \
  -d '["600519.SH", "000001.SZ"]'
```

## 代码使用示例

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

## 性能优势

1. **查询优化**：只需OHLCV时只查询轻量的base表
2. **更新解耦**：基础数据可高频更新，财务数据按财报季更新
3. **扩展灵活**：新增指标只需修改quote表，不影响基础数据

## 后续建议

1. **定时任务**：配置每日凌晨执行增量同步
2. **数据校验**：定期校验基础数据和行情指标的一致性
3. **分区优化**：对大表按trade_date进行分区
4. **缓存优化**：热点数据使用Redis缓存

## 文件清单

**新增文件：**
- `app/repositories/stock_repository_v2.py` (636 lines)
- `app/services/data_sync_service.py` (387 lines)
- `scripts/create_split_tables.py` (106 lines)
- `DATABASE_REFACTOR.md` - 详细设计文档

**修改文件：**
- `app/repositories/models.py` - 添加新表模型和向后兼容别名
- `app/adapters/base.py` - 添加新抽象方法
- `app/adapters/amazingdata_adapter.py` - 添加新数据获取方法 (~300 lines)
- `app/api/admin_routes.py` - 添加数据同步端点
- `app/models/admin_types.py` - 添加同步相关类型
- `app/models/__init__.py` - 导出新类型