## Aster 接入测试说明（市价/限价 + 自动降额重试）

### 一、准备与前提

- REST 基础地址：`https://fapi.asterdex.com`
- 测试脚本：`examples/aster_order_test.ts`
- 必要环境：
  - `ASTER_ORDER_USER`（EVM 用户地址，0x 开头）
  - `ASTER_ORDER_SIGNER`（EVM 签名者地址）
  - `PRIVATE_KEY`（签名私钥，0x 开头）
  - 可选：`ASTER_TEST_SYMBOL`（默认 `BTCUSDT`）、`ASTER_TEST_NOTIONAL_USD`（按 Notional 动态换算数量）

### 二、运行方式

```bash
yarn test:aster:order
# 或启用限价流程
ASTER_ENABLE_LIMIT=1 yarn test:aster:order

# 统一适配 Smoke（不强制下单，需 HMAC 才能读取账户信息）
yarn test:aster:adapter
```

### 三、流程覆盖

- 交易所规格拉取：`/fapi/v3/exchangeInfo`，提取 `LOT_SIZE(minQty/maxQty/stepSize)` 对齐下单数量
- 市价开平：`openPerp` / `closePerp`
  - 自动检测账户双向持仓（`dualSidePosition`），双向时使用 `LONG/SHORT`，否则 `BOTH`
  - 碰到 `-2019`（保证金不足）自动降额重试，直到对齐最小步进或达重试上限
- 限价流程（可选）：下单 → 查单 → 撤单
  - 下单：`type=LIMIT` + `timeInForce=GTC`
  - 市价单不带 `timeInForce`（避免 `-1106`）

### 四、已验证要点

- 市价 BUY：多次降额后成功
- 市价 SELL：对等降额后成功
- LIMIT BUY/SELL：下单成功，查单/撤单均返回正常
- 双向模式强制 `LONG/SHORT`：
  - 本测试中对 LIMIT 场景显式覆盖为 `LONG`（BUY）/`SHORT`（SELL）

### 五、常见错误与修正

- `-2019` 保证金不足：
  - 按步进/最小值对齐数量，自动 1/2 递减重试
- `-4061` 持仓模式不匹配：
  - 自动切换 `positionSide` 并重试（`LONG` ↔ `SHORT` 或 `BOTH`）
- `-1106` 市价带入 `timeInForce`：
  - 移除市价 `timeInForce`
- `-4005` 数量超上限：
  - 读取 `exchangeInfo`，对齐 `maxQty` 并降额重试

### 六、备注

- 示例中包含详细日志，便于对照定位；
- 若希望更激进/更保守的降额策略，可调整脚本内重试上限与递减比例。