# API 文档目录

本目录用于存放项目的 API 设计文档。

## 目录结构

```
api/
├── rest/             # REST API
│   ├── v1/          # API版本
│   │   ├── trading.md
│   │   └── data.md
│   └── openapi.json # OpenAPI规范
├── event/           # 事件定义
│   ├── trading_events.md
│   └── data_events.md
└── internal/        # 内部接口
    ├── gateway_interface.md
    └── engine_interface.md
```

## 事件定义模板

### trading_events.md

```markdown
# 交易事件定义

基于 VeighNa 事件系统，扩展自定义事件。

## 标准事件（来自 VeighNa）

| 事件名 | 类型 | 数据对象 | 触发时机 |
|-------|------|---------|---------|
| EVENT_TICK | eTick | TickData | 行情更新 |
| EVENT_ORDER | eOrder | OrderData | 委托状态变化 |
| EVENT_TRADE | eTrade | TradeData | 成交回报 |
| EVENT_POSITION | ePosition | PositionData | 持仓变化 |
| EVENT_ACCOUNT | eAccount | AccountData | 账户变化 |
| EVENT_CONTRACT | eContract | ContractData | 合约信息 |
| EVENT_LOG | eLog | LogData | 日志输出 |

## 自定义事件

### EVENT_RISK_ALERT

风险预警事件

```python
from vnpy.event import Event

EVENT_RISK_ALERT = "eRiskAlert"

class RiskAlertData:
    """风险预警数据"""
    def __init__(
        self,
        alert_type: str,
        level: str,
        message: str,
        vt_symbol: str = "",
    ) -> None:
        self.alert_type = alert_type  # 预警类型
        self.level = level            # 预警级别
        self.message = message        # 预警信息
        self.vt_symbol = vt_symbol   # 合约标识
```

## 事件处理示例

```python
from vnpy.event import EventEngine
from vnpy.trader.engine import MainEngine

def on_tick(event: Event) -> None:
    """处理行情事件"""
    tick: TickData = event.data
    # 处理逻辑
    pass

event_engine: EventEngine = ...
event_engine.register(EVENT_TICK, on_tick)
```
```

## REST API 模板

### trading.md

```markdown
# 交易 REST API

## 基础信息

- Base URL: `http://localhost:8000/api/v1`
- 认证方式: Bearer Token
- 数据格式: JSON

## 接口列表

### 1. 发单

**POST** `/orders`

```json
{
  "symbol": "IF2412",
  "exchange": "CFFEX",
  "direction": "LONG",
  "offset": "OPEN",
  "price": 3500.0,
  "volume": 1,
  "price_type": "LIMIT"
}
```

**响应**
```json
{
  "status": "success",
  "data": {
    "order_id": "ORDER123456",
    "vt_orderid": "CTP.ORDER123456"
  }
}
```

### 2. 撤单

**DELETE** `/orders/{order_id}`

### 3. 查询持仓

**GET** `/positions`

## 错误码

| 错误码 | 说明 |
|-------|------|
| 400 | 参数错误 |
| 401 | 未授权 |
| 500 | 服务器错误 |
```

## 内部接口模板

### gateway_interface.md

```markdown
# Gateway 接口定义

自定义交易接口需要实现的标准接口。

## 必须实现的方法

```python
from abc import ABC, abstractmethod
from vnpy.trader.gateway import BaseGateway
from vnpy.trader.object import (
    OrderRequest,
    CancelRequest,
    SubscribeRequest,
)

class CustomGateway(BaseGateway):
    default_name: str = "CUSTOM"

    def connect(self, setting: dict) -> None:
        """连接接口"""
        pass

    def close(self) -> None:
        """关闭连接"""
        pass

    def subscribe(self, req: SubscribeRequest) -> None:
        """订阅行情"""
        pass

    def send_order(self, req: OrderRequest) -> str:
        """发单"""
        pass

    def cancel_order(self, req: CancelRequest) -> None:
        """撤单"""
        pass
```
```