# sidecar 对外接口说明

## 1. 模块定位

sidecar 是本项目的 Python 行情数据侧车模块，对外提供统一的数据获取与 DuckDB 缓存接口。调用方可以选择直接调用 Python 服务类，也可以通过 FastAPI HTTP 接口访问。

## 2. Python 服务接口

### 2.1 创建默认服务

```python
from sidecar.config import load_config
from sidecar.service import create_default_service

service = create_default_service(load_config())
```

#### 输入

无业务输入；配置从环境变量读取：

| 环境变量 | 类型 | 默认值 | 说明 |
|---|---:|---|---|
| `TORTOISE_DUCKDB_PATH` | string | `data/tortoise.duckdb` | DuckDB 数据库文件路径 |
| `TORTOISE_SNAPSHOT_TTL_SECONDS` | int | `15` | 行情快照缓存秒数 |
| `TORTOISE_REQUEST_TIMEOUT_SECONDS` | int | `8` | 腾讯财经 HTTP 请求超时秒数 |

#### 输出

返回 `UnifiedDataService` 实例。

### 2.2 `get_kline`

```python
bars = service.get_kline("600000", period="day", limit=120, refresh=False)
```

#### 输入

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---:|---|---|
| `symbol` | string | 是 | - | 股票代码，支持 `600000`、`sh600000`、`SZ000001` 等格式 |
| `period` | string | 否 | `day` | K 线周期，支持 `day/week/month/1m/5m/15m/30m/60m` |
| `limit` | int | 否 | `800` | 最大返回条数 |
| `refresh` | bool | 否 | `False` | 是否跳过缓存强制刷新 |

#### 输出

返回 `list[KlineBar]`，按交易日期升序排列。

| 字段 | 类型 | 说明 |
|---|---|---|
| `symbol` | string | 标准化股票代码，例如 `sh600000` |
| `period` | string | K 线周期 |
| `trade_date` | date | 交易日期 |
| `open` | float/null | 开盘价 |
| `high` | float/null | 最高价 |
| `low` | float/null | 最低价 |
| `close` | float/null | 收盘价 |
| `volume` | float/null | 成交量 |
| `amount` | float/null | 成交额 |
| `source` | string | 数据源，当前为 `mootdx` |

### 2.3 `get_snapshot`

```python
snapshot = service.get_snapshot("600000", refresh=False)
```

#### 输入

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---:|---|---|
| `symbol` | string | 是 | - | 股票代码，支持 `600000`、`sh600000`、`SZ000001` 等格式 |
| `refresh` | bool | 否 | `False` | 是否跳过 TTL 缓存强制刷新 |

#### 输出

返回 `Snapshot`。

| 字段 | 类型 | 说明 |
|---|---|---|
| `symbol` | string | 标准化股票代码 |
| `name` | string/null | 股票名称 |
| `trade_time` | datetime/null | 行情时间 |
| `price` | float/null | 最新价 |
| `previous_close` | float/null | 昨收价 |
| `open` | float/null | 开盘价 |
| `high` | float/null | 最高价 |
| `low` | float/null | 最低价 |
| `volume` | float/null | 成交量 |
| `amount` | float/null | 成交额 |
| `change` | float/null | 涨跌额 |
| `change_percent` | float/null | 涨跌幅百分比 |
| `turnover_rate` | float/null | 换手率 |
| `pe_ttm` | float/null | 滚动市盈率 |
| `pe_static` | float/null | 静态市盈率 |
| `pb` | float/null | 市净率 |
| `market_cap` | float/null | 总市值 |
| `float_market_cap` | float/null | 流通市值 |
| `limit_up` | float/null | 涨停价 |
| `limit_down` | float/null | 跌停价 |
| `source` | string | 实际命中的数据源，通常为 `tencent` 或 `mootdx` |

## 3. HTTP 接口

启动命令：

```bash
uvicorn sidecar.api:app --host 127.0.0.1 --port 8765
```

### 3.1 健康检查

```http
GET /health
```

#### 输入

无。

#### 输出

```json
{
  "status": "ok"
}
```

### 3.2 获取 K 线

```http
GET /kline/{symbol}?period=day&limit=800&refresh=false
```

#### 输入

| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---:|---|---|
| `symbol` | path | string | 是 | - | 股票代码 |
| `period` | query | string | 否 | `day` | K 线周期 |
| `limit` | query | int | 否 | `800` | 返回条数，范围 `1..800` |
| `refresh` | query | bool | 否 | `false` | 是否强制刷新 |

#### 输出

```json
{
  "data": [
    {
      "symbol": "sh600000",
      "period": "day",
      "trade_date": "2026-06-23",
      "open": 10.0,
      "high": 10.5,
      "low": 9.8,
      "close": 10.2,
      "volume": 1000000.0,
      "amount": 10200000.0,
      "source": "mootdx"
    }
  ]
}
```

### 3.3 获取行情快照

```http
GET /snapshot/{symbol}?refresh=false
```

#### 输入

| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---:|---|---|
| `symbol` | path | string | 是 | - | 股票代码 |
| `refresh` | query | bool | 否 | `false` | 是否强制刷新 |

#### 输出

```json
{
  "data": {
    "symbol": "sh600000",
    "name": "浦发银行",
    "trade_time": "2026-06-23T15:00:00",
    "price": 10.5,
    "previous_close": 10.0,
    "open": 10.1,
    "high": 10.6,
    "low": 9.9,
    "volume": 1000000.0,
    "amount": 10500000.0,
    "change": 0.5,
    "change_percent": 5.0,
    "turnover_rate": 1.2,
    "pe_ttm": 6.7,
    "pe_static": 7.8,
    "pb": 0.66,
    "market_cap": 1000.0,
    "float_market_cap": 800.0,
    "limit_up": 11.0,
    "limit_down": 9.0,
    "source": "tencent"
  }
}
```

## 4. 缓存行为

- K 线缓存表：`md.kline_bars`，主键为 `symbol + period + trade_date`。
- 快照缓存表：`md.snapshots`，主键为 `symbol`，使用 `expires_at` 控制 TTL。
- `refresh=false` 时优先使用缓存；`refresh=true` 时跳过缓存并重新拉取。
- 快照数据源按顺序降级：腾讯财经失败后回退 mootdx。

## 5. 注意事项

- 当前 K 线底层依赖 mootdx，第一次连接可能触发 mootdx 自动测速。
- 腾讯财经 PB 字段使用索引 `46`，索引 `43` 是振幅，不可作为 PB 使用。
- 策略模块建议只依赖本文件描述的统一接口，不直接依赖 mootdx 或腾讯财经字段。

## 6. 真实数据源测试

默认单元测试不访问外网。需要验证 mootdx 与腾讯财经真实接口时，先安装依赖，再显式开启环境变量：

```bash
pip install -e .[test]
RUN_REAL_MARKET_TESTS=1 pytest tests/test_real_sources.py -vv
```

Windows PowerShell 示例：

```powershell
$env:RUN_REAL_MARKET_TESTS = "1"
python -m pytest tests/test_real_sources.py -vv
```

真实测试用例：

- `3-1`：腾讯财经真实快照接口返回有效价格。
- `3-2`：mootdx 真实 K 线接口返回至少一条日线。
- `3-3`：统一服务使用真实数据源写入并读取 DuckDB 缓存。