claude_dev
a37c43f691
- 创建6大文档分类：需求/设计/API/用户指南/运维/研究 - 添加各目录的 README 和模板说明 - 定义文档命名规范和编写规范 - 建立文档与代码的对应关系 文档目录结构: ├── requirements/ - 业务需求、功能需求、非功能需求 ├── design/ - 架构设计、数据库设计、UI设计、集成设计 ├── api/ - REST API、事件定义、内部接口 ├── user_guide/ - 快速开始、教程、FAQ ├── operations/ - 部署、监控、故障排查 └── research/ - 因子研究、策略研究、回测报告 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
189 lines
3.5 KiB
Markdown
189 lines
3.5 KiB
Markdown
# 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
|
||
```
|
||
```
|