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>
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
# 交易事件定义
基于 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 # 合约标识
事件处理示例
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"
}
响应
{
"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