# 账户同步接口契约

## 1. 请求：拉取账户状态
- **方法**：`POST /control-plane/account-sync`（内部服务调用）
- **请求体**：
```json
{
  "requestId": "uuid",
  "accounts": [
    {
      "accountId": "pacifica-1",
      "exchange": "pacifica",
      "nonce": 1695800000
    }
  ]
}
```
- **说明**：
  - `requestId`：全局唯一，用于追踪日志。
  - `accounts`：本次需要同步的账户列表；`nonce` 为去重或防重放字段。

## 2. 响应：账户余额与仓位
```json
{
  "requestId": "uuid",
  "timestamp": "2025-09-27T12:00:00Z",
  "results": [
    {
      "accountId": "pacifica-1",
      "status": "success",
      "balances": [
        { "asset": "USDT", "total": "120.53", "available": "72.28" },
        { "asset": "BTC", "total": "0.0012", "available": "0.0003" }
      ],
      "positions": [
        {
          "symbol": "BTC",
          "side": "long",
          "size": "0.0009",
          "entryPrice": "109293.50",
          "markPrice": "109310.12",
          "unrealizedPnl": "0.15"
        }
      ],
      "utilization": {
        "value": 0.65,
        "formula": "(totalBalance - availableBalance) / totalBalance"
      }
    }
  ],
  "errors": []
}
```

- `balances.total/available`：字符串表示，保留精度。
- `positions`：同一交易所资产只列出一条，`side` 为 long/short。
- `utilization.value`：数值型，便于对齐 50%-80% 目标。
- `errors`：若单个账户失败，附带 `{ "accountId": ..., "code": ..., "message": ... }`。

## 3. 失败示例
```json
{
  "requestId": "uuid",
  "timestamp": "2025-09-27T12:00:01Z",
  "results": [],
  "errors": [
    {
      "accountId": "aster-1",
      "code": "AUTH_INVALID",
      "message": "API key expired",
      "retryable": false
    }
  ]
}
```

## 4. 业务规则
- 成功响应必须包含时间戳并与监控日志相关联。
- 控制平面收到结果后需更新 `ExchangeAccount`、`RiskEnvelope` 相应字段。
- 若 `errors` 非空，需生成 `MonitoringEvent`（类型：account-sync-fail）。
