python_market_data_service/QUICKSTART_NEW_TABLES.md

# 新表结构快速开始指南

## 1. 创建新表

```bash
# 进入项目目录
cd d:\\alpha_workspace\\python_market_data_service

# 激活虚拟环境
.\\venv\\Scripts\\activate

# 创建新表
python scripts/create_split_tables.py

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

## 2. 启动服务

```bash
# 启动主服务
python main.py
```

## 3. 同步数据

### 全量同步示例

```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": "20230101",
    "end_date": "20240301"
  }'
```

### 增量同步示例

```bash
# 同步最近30天的数据
curl -X POST "http://localhost:8080/admin/data/sync/incremental" \
  -H "Content-Type: application/json" \
  -d '["600519.SH", "000001.SZ"]'
```

### 只同步基础数据

```bash
curl -X POST "http://localhost:8080/admin/data/sync" \
  -H "Content-Type: application/json" \
  -d '{
    "symbols": ["600519.SH"],
    "sync_type": "base",
    "start_date": "20240101",
    "end_date": "20240301"
  }'
```

## 4. 查询数据

### 使用 Repository 查询

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

# 创建会话
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)
)
print(f"Base records: {len(base_data)}")

# 查询行情指标（包含均线、MACD等）
quote_data = repo.get_klines_quote(
    symbol="600519.SH",
    start_date="2024-01-01",
    end_date="2024-03-01"
)
for item in quote_data[:3]:
    print(f"{item['trade_date']}: close={item.get('ma5')}")

# 查询财务数据（市值、股本等）
finance_data = repo.get_klines_finance(
    symbol="600519.SH",
    start_date="2024-01-01",
    end_date="2024-03-01"
)
for item in finance_data[:3]:
    print(f"{item['trade_date']}: 市值={item.get('total_market_cap')}")
```

## 5. 定时任务配置

创建每日定时同步脚本 `scripts/daily_sync.py`:

```python
#!/usr/bin/env python3
"""每日增量同步脚本"""
import asyncio
import sys
from pathlib import Path

sys.path.insert(0, str(Path(__file__).parent.parent))

from app.services.adapter_service import AdapterService
from app.services.data_sync_service import DataSyncService
from app.repositories.stock_repository_v2 import StockRepositoryV2
from app.repositories.database import SessionLocal

async def main():
    # 获取热门股票列表
    db = SessionLocal()
    repo = StockRepositoryV2(db)
    
    # 这里可以从配置或数据库读取需要同步的标的列表
    symbols = ["600519.SH", "000001.SZ", "000858.SZ"]  # 示例
    
    # 获取适配器
    adapter_service = AdapterService()
    adapter = adapter_service.get_active_adapter("stock")
    
    # 同步
    sync_service = DataSyncService(adapter)
    results = await sync_service.sync_daily_incremental(symbols)
    
    print("Sync completed:", results)

if __name__ == "__main__":
    asyncio.run(main())
```

添加到定时任务（Linux crontab）：
```bash
# 每天凌晨2点执行增量同步
0 2 * * * cd /path/to/project && python scripts/daily_sync.py >> logs/sync.log 2>&1
```

## 6. 表结构说明

| 表名 | 用途 | 数据来源 | 更新频率 |
|------|------|----------|----------|
| stock_klines_1d_base | 基础K线(OHLCV) | query_kline | 每日 |
| stock_klines_1d_quote | 行情指标 | 本地计算 | 每日 |
| stock_klines_1d_finance | 财务数据 | 股本/财报接口 | 财报季 |
| stock_realtime_quotes | 实时行情 | 行情推送 | 实时 |
| stock_symbols | 股票列表 | 基础数据接口 | 每日 |
| stock_trading_calendar | 交易日历 | 交易所数据 | 每年 |

## 7. 常见问题

### Q: 旧表数据如何迁移？

A: 使用以下SQL迁移基础数据：
```sql
INSERT INTO stock_klines_1d_base 
(symbol_id, ts, trade_date, open, high, low, close, volume, amount)
SELECT 
    symbol_id, ts, trade_date, open, high, low, close, volume, amount
FROM stock_klines_1d
WHERE trade_date >= '2024-01-01';
```

### Q: 如何只查询基础数据提高性能？

A: 使用 `StockRepositoryV2.get_klines_base()` 方法，它只查询轻量的base表。

### Q: 行情指标如何计算？

A: 指标在 `AmazingDataAdapter._fetch_kline_quote_sync()` 中本地计算：
- 均线: 基于收盘价计算MA5/10/20/30/60/120/250
- MACD: 使用pandas ewm计算
- 乖离率: (收盘价-均线)/均线
- 涨跌停: 对比收盘价和涨跌停价

### Q: 市值数据如何计算？

A: 市值 = 收盘价 × 股本，股本从 `get_equity_structure` 接口获取。

## 8. 下一步

- [ ] 配置定时自动同步
- [ ] 添加Redis缓存热点数据
- [ ] 实现分钟线行情指标表
- [ ] 添加数据一致性校验任务