# API 契约：签名服务（简化版）

## 概述
多平台账户凭据管理与签名服务，专注于单一职责：为不同平台提供签名功能。

## 基础信息
- **API 版本**: v1
- **基础路径**: `/api/v1`
- **认证方式**: 无（内部服务）
- **内容类型**: `application/json`

---

## 1. 核心签名接口

### 1.1 执行签名操作
```http
POST /api/v1/sign
Content-Type: application/json

{
  "platformId": "pacifica",
  "accountId": "pac-main-001",
  "data": {
    "type": "place_order",
    "market": "BTC-USD",
    "side": "bid",
    "amount": "0.001",
    "price": "65000"
  }
}
```

**响应** (200 OK):
```json
{
  "success": true,
  "data": {
    "signature": "base58_encoded_signature",
    "algorithm": "ed25519",
    "encoding": "base58",
    "publicKey": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
    "signedAt": "2025-09-28T12:00:00Z"
  }
}
```

**错误响应** (404 Not Found):
```json
{
  "success": false,
  "error": {
    "code": "ACCOUNT_NOT_FOUND",
    "message": "指定账户不存在",
    "details": {
      "platformId": "pacifica",
      "accountId": "pac-main-001"
    }
  }
}
```

### 1.2 批量签名操作
```http
POST /api/v1/sign/batch
Content-Type: application/json

{
  "requests": [
    {
      "requestId": "req_001",
      "platformId": "pacifica",
      "accountId": "pac-main-001",
      "data": {"type": "place_order", "symbol": "BTC-USD"}
    },
    {
      "requestId": "req_002",
      "platformId": "aster",
      "accountId": "ast-hedge-001",
      "data": {"action": "cancel_order", "orderId": "12345"}
    }
  ]
}
```

**响应** (200 OK):
```json
{
  "success": true,
  "data": {
    "results": [
      {
        "requestId": "req_001",
        "status": "success",
        "signature": "base58_signature_1",
        "algorithm": "ed25519"
      },
      {
        "requestId": "req_002",
        "status": "success",
        "signature": "0x8c7e40c7b23c0b86...",
        "algorithm": "eip191"
      }
    ],
    "summary": {
      "total": 2,
      "successful": 2,
      "failed": 0
    }
  }
}
```

---

## 2. 账户管理

### 2.1 获取账户列表
```http
GET /api/v1/accounts?platform=pacifica
```

**响应** (200 OK):
```json
{
  "success": true,
  "data": {
    "accounts": [
      {
        "accountId": "pac-main-001",
        "platformId": "pacifica",
        "alias": "Pacifica主账户",
        "status": "active",
        "environment": "production",
        "usage": {
          "totalSigns": 1250,
          "lastSignAt": "2025-09-28T11:30:00Z",
          "errorCount": 2
        }
      }
    ],
    "total": 1
  }
}
```

### 2.2 获取单个账户信息
```http
GET /api/v1/accounts/{platformId}/{accountId}
```

**响应** (200 OK):
```json
{
  "success": true,
  "data": {
    "accountId": "pac-main-001",
    "platformId": "pacifica",
    "alias": "Pacifica主账户",
    "status": "active",
    "environment": "production",
    "algorithm": "ed25519",
    "publicKey": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
    "createdAt": "2025-09-01T10:00:00Z",
    "lastUsed": "2025-09-28T11:30:00Z"
  }
}
```

---

## 3. 配置管理

### 3.1 重载配置
```http
POST /api/v1/config/reload
```

**响应** (200 OK):
```json
{
  "success": true,
  "data": {
    "reloadedAt": "2025-09-28T12:00:00Z",
    "changes": {
      "added": 1,
      "updated": 0,
      "removed": 0
    },
    "accountCount": 8,
    "platformCount": 4
  }
}
```

### 3.2 获取服务状态
```http
GET /api/v1/status
```

**响应** (200 OK):
```json
{
  "success": true,
  "data": {
    "status": "healthy",
    "uptime": "72h 15m 30s",
    "config": {
      "path": "/path/to/credentials.json",
      "lastLoaded": "2025-09-28T12:00:00Z",
      "isWatching": true
    },
    "accounts": {
      "total": 8,
      "byPlatform": {
        "pacifica": 3,
        "aster": 2,
        "binance": 2,
        "okx": 1
      }
    },
    "performance": {
      "avgSigningTime": "15ms",
      "totalSigns": 12500,
      "errorRate": 0.002
    }
  }
}
```

---

## 4. 平台特定签名格式

### 4.1 Pacifica 签名数据格式
```json
{
  "platformId": "pacifica",
  "accountId": "pac-main-001",
  "data": {
    "instruction": {
      "type": "place_order",
      "market": "BTC-USD",
      "side": "bid",
      "amount": "0.001",
      "price": "65000"
    },
    "nonce": 1735390800000
  }
}
```

### 4.2 Aster 签名数据格式
```json
{
  "platformId": "aster",
  "accountId": "ast-hedge-001",
  "data": {
    "message": {
      "action": "place_order",
      "symbol": "BTCUSDT",
      "price": "65000",
      "quantity": "0.001",
      "timestamp": 1735390800000
    }
  }
}
```

### 4.3 Binance 签名数据格式
```json
{
  "platformId": "binance",
  "accountId": "bn-spot-001",
  "data": {
    "method": "POST",
    "endpoint": "/api/v3/order",
    "params": {
      "symbol": "BTCUSDT",
      "side": "BUY",
      "type": "LIMIT",
      "quantity": "0.001",
      "price": "65000",
      "timestamp": 1735390800000
    }
  }
}
```

### 4.4 OKX 签名数据格式
```json
{
  "platformId": "okx",
  "accountId": "okx-perp-001",
  "data": {
    "method": "POST",
    "path": "/api/v5/trade/order",
    "body": {
      "instId": "BTC-USDT",
      "side": "buy",
      "ordType": "limit",
      "sz": "0.001",
      "px": "65000"
    },
    "timestamp": "2025-09-28T12:00:00.000Z"
  }
}
```

---

## 错误代码规范

| 错误代码 | HTTP状态码 | 描述 |
|---------|------------|------|
| `ACCOUNT_NOT_FOUND` | 404 | 指定账户不存在 |
| `PLATFORM_NOT_SUPPORTED` | 400 | 不支持的平台 |
| `INVALID_DATA_FORMAT` | 400 | 签名数据格式错误 |
| `SIGNATURE_FAILED` | 500 | 签名操作失败 |
| `CONFIG_LOAD_FAILED` | 500 | 配置文件加载失败 |
| `ACCOUNT_INACTIVE` | 423 | 账户已禁用 |

## 性能要求

### 延迟目标
- 单次签名: < 50ms
- 批量签名: < 200ms (10个请求)
- 配置重载: < 5秒

### 吞吐量目标
- 并发签名: 100 QPS
- 可扩展性: 支持水平扩展

### 可用性目标
- 服务可用性: 99.9%
- 配置热重载: 无服务中断

## 安全要求

### 数据保护
- 私钥永不在响应中返回
- 所有凭据在内存中加密存储
- 配置文件访问权限控制

### 日志记录
- 记录所有签名请求和结果
- 敏感数据自动脱敏
- 支持审计追踪

### 网络安全
- 仅限内网访问
- 支持 HTTPS 加密传输
- 请求大小限制 1MB