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

— 目标与范围 —

- 统一管理多平台（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` 开关，或默认执行；并将失败详情写入日志与控制台，方便快速排障。