binance-api/docs/accounts/ACCOUNT_MGMT_DESIGN.zh.md

账户管理（多平台/多账户）设计文档

— 目标与范围 —

• 统一管理多平台（Pacifica/Aster/Binance …）的多个账户，提供集中注册、路由、聚合查询与事件汇聚。
• 作为“执行器/策略层”的单一入口，隐藏各接入方差异（签名、鉴权、字段规范）。

— 核心术语 —

• ExchangeAdapter：各交易所适配器统一接口，已定义于 src/exchanges/ExchangeAdapter.ts。
• AccountManager：集中式账户管理器，见 src/accounts/accountManager.ts。
• RegisteredAccount：注册实体，包含 exchange/accountId/adapter/meta。

— 架构与职责 —

• 注册/反注册：按 (exchange, accountId) 管理适配器实例；幂等。
• 聚合查询：跨账户聚合 balances() 与 positions()，并附加来源标签 { exchange, accountId }。
• 精准路由：对单账户执行 placeOrder/cancel/cancelAll/getOrder/openOrders/leverage/depth 等。
• 事件汇聚：监听各适配器 ws()，转发常见事件（depth/orders/trades/balance/account_info/account_positions 等），并附 { exchange, accountId } 标签。

— 统一数据模型（归一化） —

• Balance: { asset, total, free }
• Position: { symbol, side: 'LONG'|'SHORT', qty, entryPrice, unrealizedPnl, leverage? }
• Order: { id, symbol, status, side, type, price?, origQty, executedQty, updateTime }
• Depth: { bids: [{price,qty}], asks: [{price,qty}], ts }
• 符号规范：对部分接入（Pacifica）统一为基础符号（如 BTC）。

— AccountManager API（对上暴露） —

• 注册：register({ exchange, accountId, adapter, meta? })
• 查询：list()、balancesAll()、positionsAll()
• 路由：getAdapter()、placeOrderOn()、cancelOrderOn()、cancelAllOn()、openOrdersOn()、leverageOn()、depthOn()
• 广播：cancelAllByExchange(exchange, symbol)
• 事件：ws()（聚合 EventEmitter）

— Pacifica 账户相关（REST/WS） —

• REST（硬编码端点于 PacificaClient）：
  • 账户信息：/api/v1/account/info（POST）
  • 账户设置：/api/v1/account（GET）或文档对应的 settings 页面
  • 资金/权益/余额历史：/api/v1/account_equity_history、/api/v1/account_balance_history（见 docs 镜像 HTML）
  • 杠杆/保证金模式更新：/api/v1/account/update-leverage、/api/v1/account/update-margin-mode
  • 子账户：/api/v1/subaccounts/create、/api/v1/subaccounts/transfer
  • 签名：Ed25519（tweetnacl+bs58），按 signing/implementation 组装 {timestamp, expiry_window, type, data} 紧凑 JSON 后签名。
• WS：
  • 无需 login，直接订阅：prices、book、trades、account_info、account_balance、account_positions、account_orders。
  • 心跳：{"method":"ping"}，服务端返回 { "channel": "pong" }。

— Aster 账户相关（REST/HMAC） —

• HMAC：X-MBX-APIKEY + sha256(signature)；
• 查询：/fapi/v2/balance、/fapi/v2/positionRisk、/fapi/v3/openOrders；
• 账户模式：/fapi/v3/positionSide/dual；
• 杠杆/保证金模式：/fapi/v3/leverage、/fapi/v3/marginType；
• 下单：/fapi/v3/order（x-www-form-urlencoded，链上 personal_sign 参与签名字符串）。

— 错误处理与重试 —

• HTTP 429/5xx：指数退避（基 250ms，最大 4 次）— 已在 PacificaClient 实装。
• 403：多为 CDN/白名单限制，打印告警并切回可用路径（如 WS/其他 REST）。
• 字段容错：缺字段跳过或用默认值，保持可用性。

— 安全与密钥管理 —

• 私钥/Agent 私钥：仅从环境读取，支持 Base58 或 JSON 数组（32/64 字节）。
• 不落盘；日志仅打印签名前缀（PACIFICA_DEBUG=1 时）。

— 持久化（后续） —

• 可选最小落盘：CSV/SQLite 记录净值、成交与持仓快照，支撑回放与审计。

— 测试与回归 —

• Smoke：examples/pacifica_test.ts、examples/pacifica_ws_example.ts、examples/aster_adapter_smoke.ts；
• 单测：对账户签名与端点映射做最小断言；
• E2E（后续）：统一 ExchangeAdapter 市价/限价/撤单/全撤/深度/持仓/余额。

— 路线图 —

• v1：完成 AccountManager、Pacifica/Aster 账户查询与事件汇聚、脚本与文档。
• v2：WS 数据标准化、最小持久化、pm2 运维脚本。
• v3：统一执行器接口与多账户风控（净敞口阈值/杠杆上限/风控冻结）。

— 启动自检（Init Check，Fail-fast） —

• 目的：在进程启动阶段尽早发现环境缺失/签名不一致/权限受限等问题，避免运行期隐性失败。
• 自检清单（按账户逐项执行）：
  1. 环境变量齐全：
     • Pacifica：PACIFICA_ACCOUNT、PACIFICA_ACCOUNT_PRIVATE_KEY（或 PACIFICA_PRIVATE_KEY）；如启用代理单：PACIFICA_AGENT_WALLET、PACIFICA_AGENT_PRIVATE_KEY；
     • Aster：ASTER_API_KEY/ASTER_API_SECRET（查询必需）；ASTER_ORDER_USER/ASTER_ORDER_SIGNER/PRIVATE_KEY（下单必需）。
  2. 密钥格式校验：
     • Pacifica：私钥 Base58 或 JSON 数组（32/64 字节）；派生公钥应等于 PACIFICA_ACCOUNT；否则 fail-fast；
     • Aster：ASTER_ORDER_USER/ASTER_ORDER_SIGNER 为合法 EVM 地址；私钥 0x 前缀、长度正确；
  3. 连通性：
     • REST 探针：Pacifica GET /api/v1/book?symbol=BTC、Aster GET /fapi/v3/exchangeInfo；
     • WS 探针（可选）：连接 wss://.../ws 并发送 ping，收到 pong；
  4. 权限与限速：
     • 403/401 时打印明确告警（可能为 CDN/白名单/Key 权限）；
     • 提示用户参考 docs/accounts/ENV_VARS.md 与接入文档；
  5. 基础 REST 校验：
     • Pacifica：/api/v1/account/info（POST）在账户环境完整时应成功；
     • Aster：/fapi/v2/balance//fapi/v2/positionRisk 应成功；
  6. 时间同步（可选）：
     • 检查本地与服务端时间偏差（> 2s 提示）；
  7. 结果汇总：
     • 通过：注册账户并进入运行；
     • 失败：打印逐项失败原因并终止进程（或置为“仅订阅行情”降级模式）。

推荐在装配层提供 --init-check 开关，或默认执行；并将失败详情写入日志与控制台，方便快速排障。