# 多平台 Delta 中性控制平面 API 文档

## 概述

本文档描述了多平台 Delta 中性控制平面的 API 端点和服务接口。该系统实现了跨交易所的 Delta 中性策略管理、风险监控和自动对冲功能。

## 核心服务架构

### SystemOrchestrator
系统协调器，负责管理所有模块的生命周期和依赖关系。

### DeltaNeutralController
Delta 中性控制器，提供核心的 Delta 控制和利用率再平衡功能。

### RiskMonitoringService
风险监控服务，实时跟踪账户风险指标并生成警报。

---

## API 端点详情

### 1. Delta 中性控制 API

#### POST /api/v1/delta/control

执行 Delta 中性控制操作，调整账户仓位以维持目标 Delta 值。

**请求参数 (DeltaControlRequest)**:
```typescript
{
  targetDelta: number        // 目标 Delta 值 (通常为 0.0)
  accounts: string[]         // 要控制的账户ID列表
  maxDeviation: number       // 最大允许偏差 (0.0-1.0)
  symbol: string            // 交易标的 (如 "BTC-USD")
  tolerancePercent?: number  // 容差百分比 (默认 0.05)
  dryRun?: boolean          // 是否为模拟运行 (默认 false)
}
```

**响应格式 (DeltaControlResponse)**:
```typescript
{
  success: boolean                    // 操作是否成功
  operationId: string                // 操作唯一标识符
  timestamp: number                  // 操作时间戳
  initialDelta: number               // 初始 Delta 值
  finalDelta: number                 // 最终 Delta 值
  deltaDeviation: number             // Delta 偏差值
  accountsProcessed: string[]        // 已处理的账户列表
  totalAdjustments: number           // 总调整次数
  executionTime: number              // 执行时间 (毫秒)
  adjustmentNeeded: boolean          // 是否需要调整
  hedgeResults?: HedgeExecutionResult // 对冲执行结果
  reason?: string                    // 操作原因或跳过原因
  error?: string                     // 错误信息 (如果失败)
}
```

**示例请求**:
```bash
curl -X POST http://localhost:3000/api/v1/delta/control \
  -H "Content-Type: application/json" \
  -d '{
    "targetDelta": 0.0,
    "accounts": ["pacifica-main", "aster-hedge"],
    "maxDeviation": 0.1,
    "symbol": "BTC-USD"
  }'
```

**示例响应**:
```json
{
  "success": true,
  "operationId": "delta-ctrl-20241027-001",
  "timestamp": 1698393600000,
  "initialDelta": 0.25,
  "finalDelta": 0.02,
  "deltaDeviation": 0.02,
  "accountsProcessed": ["pacifica-main", "aster-hedge"],
  "totalAdjustments": 2,
  "executionTime": 1250,
  "adjustmentNeeded": true,
  "hedgeResults": {
    "success": true,
    "executedOrders": [
      {
        "accountId": "pacifica-main",
        "symbol": "BTC-USD",
        "amount": 0.23,
        "side": "sell"
      }
    ],
    "totalCost": 15234.50,
    "netDeltaChange": -0.23
  }
}
```

---

### 2. 利用率再平衡 API

#### POST /api/v1/utilization/rebalance

执行账户利用率再平衡，优化资源分配以达到目标利用率。

**请求参数 (UtilizationRebalanceRequest)**:
```typescript
{
  targetUtilization: number     // 目标利用率 (0.0-1.0)
  accounts: string[]           // 要再平衡的账户列表
  symbol: string              // 交易标的
  tolerancePercent?: number    // 容差百分比 (默认 0.1)
  maxRebalanceAmount?: number  // 最大再平衡金额
  dryRun?: boolean            // 是否为模拟运行
}
```

**响应格式 (UtilizationRebalanceResponse)**:
```typescript
{
  success: boolean                          // 操作是否成功
  operationId: string                      // 操作唯一标识符
  timestamp: number                        // 操作时间戳
  accountsProcessed: string[]              // 已处理的账户列表
  averageUtilization: number               // 平均利用率
  targetUtilization: number                // 目标利用率
  executionTime: number                    // 执行时间 (毫秒)
  rebalanceNeeded: boolean                 // 是否需要再平衡
  rebalanceActions: UtilizationAction[]    // 再平衡操作列表
  utilizationMetrics: UtilizationMetric[]  // 利用率指标
  reason?: string                          // 操作原因
  error?: string                           // 错误信息
}

interface UtilizationAction {
  accountId: string      // 账户ID
  action: 'increase' | 'decrease' | 'maintain'  // 操作类型
  currentUtilization: number  // 当前利用率
  targetUtilization: number   // 目标利用率
  adjustmentAmount: number    // 调整金额
}

interface UtilizationMetric {
  accountId: string          // 账户ID
  currentUtilization: number // 当前利用率
  targetUtilization: number  // 目标利用率
  deviationPercent: number   // 偏差百分比
  withinTolerance: boolean   // 是否在容差范围内
}
```

**示例请求**:
```bash
curl -X POST http://localhost:3000/api/v1/utilization/rebalance \
  -H "Content-Type: application/json" \
  -d '{
    "targetUtilization": 0.75,
    "accounts": ["pacifica-main", "aster-hedge", "binance-backup"],
    "symbol": "BTC-USD",
    "tolerancePercent": 0.1
  }'
```

---

### 3. 风险监控 API

#### GET /api/v1/risk/metrics/{accountId}

获取指定账户的风险指标。

**路径参数**:
- `accountId`: 账户ID

**响应格式 (RiskMetrics)**:
```typescript
{
  accountId: string        // 账户ID
  deltaDeviation: number   // Delta 偏差
  utilizationRate: number  // 利用率
  leverageRatio: number    // 杠杆比率
  unrealizedPnl: number    // 未实现盈亏
  maxDrawdown: number      // 最大回撤
  timestamp: number        // 时间戳
}
```

#### GET /api/v1/risk/alerts

获取所有活跃的风险警报。

**查询参数**:
- `accountId?`: 可选，筛选特定账户的警报
- `severity?`: 可选，筛选特定严重程度的警报 (INFO|WARN|CRITICAL)

**响应格式 (RiskAlert[])**:
```typescript
[
  {
    id: string                    // 警报ID
    type: 'delta-alert' | 'utilization-alert' | 'failover-alert' | 'proxy-alert'
    severity: 'INFO' | 'WARN' | 'CRITICAL'  // 严重程度
    accountId: string            // 相关账户ID
    message: string              // 警报消息
    timestamp: number            // 时间戳
    data: Record<string, any>    // 警报数据
  }
]
```

#### GET /api/v1/risk/history/{accountId}

获取指定账户的风险指标历史记录。

**查询参数**:
- `limit?`: 返回记录数量限制 (默认 100)
- `since?`: 起始时间戳

---

### 4. 账户同步 API

#### POST /api/v1/account/sync

同步账户状态和余额信息。

**请求参数 (AccountSyncRequest)**:
```typescript
{
  accounts: string[]           // 要同步的账户列表
  includePositions: boolean    // 是否包含仓位信息
  includeBalances: boolean     // 是否包含余额信息
  timeout?: number            // 超时时间 (毫秒)
}
```

**响应格式 (AccountSyncResponse)**:
```typescript
{
  success: boolean                    // 同步是否成功
  syncedAccounts: string[]           // 已同步的账户列表
  failedAccounts: string[]           // 同步失败的账户列表
  syncTime: number                   // 同步耗时
  accountStates: AccountState[]      // 账户状态列表
  errors?: string[]                  // 错误信息列表
}

interface AccountState {
  accountId: string        // 账户ID
  exchange: string         // 交易所
  totalBalance: number     // 总余额
  availableBalance: number // 可用余额
  netPosition: number      // 净仓位
  unrealizedPnl: number    // 未实现盈亏
  entryPrice?: number      // 入场价格
  currentPrice?: number    // 当前价格
  leverage?: number        // 杠杆倍数
  lastUpdated: number      // 最后更新时间
}
```

---

### 5. 对冲执行 API

#### POST /api/v1/hedge/execute

执行对冲交易操作。

**请求参数 (HedgeExecutionRequest)**:
```typescript
{
  symbol: string              // 交易标的
  targetAccounts: string[]    // 目标账户列表
  hedgeAmount: number         // 对冲金额
  hedgeStrategy: 'delta-neutral' | 'cross-platform' | 'same-platform'
  maxSlippage?: number        // 最大滑点 (默认 0.005)
  timeout?: number           // 超时时间 (默认 30000ms)
  dryRun?: boolean           // 是否模拟执行
}
```

**响应格式 (HedgeExecutionResult)**:
```typescript
{
  success: boolean                // 执行是否成功
  executedOrders: OrderExecution[] // 已执行的订单
  totalCost: number              // 总成本
  executionTime: number          // 执行时间 (毫秒)
  netDeltaChange: number         // 净 Delta 变化
  slippage: number              // 实际滑点
  error?: string                // 错误信息
}

interface OrderExecution {
  orderId: string      // 订单ID
  accountId: string    // 账户ID
  symbol: string       // 交易标的
  amount: number       // 交易数量
  side: 'buy' | 'sell' // 买卖方向
  executedPrice: number // 执行价格
  fees: number         // 手续费
  timestamp: number    // 执行时间
}
```

---

### 6. 市场数据故障转移 API

#### GET /api/v1/market/feeds

获取市场数据源状态。

**响应格式**:
```typescript
{
  feeds: MarketDataFeedStatus[]  // 数据源状态列表
  activeFeed: string            // 当前活跃数据源
  lastFailover: number          // 最后故障转移时间
}

interface MarketDataFeedStatus {
  feedId: string                               // 数据源ID
  status: 'healthy' | 'degraded' | 'failing'  // 状态
  latency: number                             // 延迟 (毫秒)
  lastUpdate: number                          // 最后更新时间
  errorCount: number                          // 错误计数
}
```

#### POST /api/v1/market/failover

手动触发市场数据源故障转移。

**请求参数**:
```typescript
{
  targetFeed: string     // 目标数据源
  reason?: string        // 故障转移原因
}
```

---

### 7. 系统状态 API

#### GET /api/v1/system/status

获取系统整体状态。

**响应格式**:
```typescript
{
  status: 'running' | 'stopped' | 'error'  // 系统状态
  uptime: number                          // 运行时间 (毫秒)
  services: ServiceStatus[]               // 服务状态列表
  performance: PerformanceMetrics         // 性能指标
  activeAccounts: number                  // 活跃账户数
  totalOperations: number                 // 总操作数
}

interface ServiceStatus {
  name: string                           // 服务名称
  status: 'running' | 'stopped' | 'error'  // 服务状态
  lastHeartbeat: number                  // 最后心跳时间
  errorCount: number                     // 错误计数
}

interface PerformanceMetrics {
  avgResponseTime: number     // 平均响应时间
  operationsPerSecond: number // 每秒操作数
  memoryUsage: number        // 内存使用量 (MB)
  cpuUsage: number           // CPU 使用率
}
```

#### POST /api/v1/system/restart

重启系统服务。

#### POST /api/v1/system/stop

停止系统服务。

---

## 错误码说明

| 错误码 | 说明 | 解决方案 |
|--------|------|----------|
| 1001 | 无效的账户ID | 检查账户ID格式和存在性 |
| 1002 | Delta偏差超出限制 | 调整maxDeviation参数 |
| 1003 | 对冲执行失败 | 检查账户余额和市场条件 |
| 1004 | 风险警报阻止操作 | 处理相关风险警报后重试 |
| 1005 | 市场数据不可用 | 等待数据源恢复或手动故障转移 |
| 2001 | 服务超时 | 增加timeout参数或检查网络连接 |
| 2002 | 代理连接失败 | 检查代理配置和网络状态 |
| 3001 | 权限不足 | 检查API密钥和账户权限 |
| 3002 | 请求频率过高 | 适当降低请求频率 |

---

## 配置参数

### 性能配置
- **控制循环延迟**: 目标 8 秒以内
- **故障转移SLA**: 10 秒以内
- **资源利用率**: 50-80% 目标范围

### 风险控制配置
- **最大Delta偏差**: 默认 10%
- **利用率容差**: 默认 10%
- **最大回撤**: 账户特定配置

### 网络配置
- **代理轮换**: 支持多代理负载均衡
- **超时设置**: 可配置的请求超时
- **重试机制**: 指数退避重试策略

---

## 使用示例

### 完整的Delta中性策略工作流

```bash
# 1. 检查系统状态
curl http://localhost:3000/api/v1/system/status

# 2. 同步账户状态
curl -X POST http://localhost:3000/api/v1/account/sync \
  -H "Content-Type: application/json" \
  -d '{"accounts": ["pacifica-main", "aster-hedge"], "includePositions": true}'

# 3. 检查风险指标
curl http://localhost:3000/api/v1/risk/metrics/pacifica-main

# 4. 执行Delta控制
curl -X POST http://localhost:3000/api/v1/delta/control \
  -H "Content-Type: application/json" \
  -d '{
    "targetDelta": 0.0,
    "accounts": ["pacifica-main", "aster-hedge"],
    "maxDeviation": 0.1,
    "symbol": "BTC-USD"
  }'

# 5. 检查执行结果和新的风险状态
curl http://localhost:3000/api/v1/risk/alerts
```

### 监控和报警集成

```bash
# 持续监控风险警报
while true; do
  curl -s http://localhost:3000/api/v1/risk/alerts?severity=CRITICAL
  sleep 30
done

# 定期利用率再平衡
curl -X POST http://localhost:3000/api/v1/utilization/rebalance \
  -H "Content-Type: application/json" \
  -d '{
    "targetUtilization": 0.75,
    "accounts": ["pacifica-main", "aster-hedge"],
    "symbol": "BTC-USD"
  }'
```

---

## 版本信息

- **API版本**: v1.0
- **实现版本**: 1.0.0
- **最后更新**: 2024-10-27
- **兼容性**: 向后兼容支持

---

## 技术支持

如需技术支持或报告问题，请参考：
- 系统日志: `/logs/system.log`
- 错误日志: `/logs/error.log`
- 性能监控: `/api/v1/system/status`