# 账户同步接口契约 ## 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)。