# Alpaca 成交手续费对账

Alpaca 可能先返回订单成交，再稍后提供权威的费用记录。因此，QuantDinger 将“已成交”和“手续费已确认”作为两个独立状态：交易记录已经出现时，手续费仍可能显示“待确认”。

## 页面状态说明

| 页面显示 | 含义 |
| --- | --- |
| `待确认` | 成交已入账，但尚未收到权威的手续费或零手续费证据。 |
| 非零手续费 | Alpaca 活动记录返回了成交费用，QuantDinger 已按实际费用入账。 |
| 确认后的 `$0.00` | Alpaca 明确返回零佣金，系统以 `actual_zero` 保存，而不是把缺失值猜成零。 |

顶部成本卡片汇总的是已持久化的执行记录。仍处于待确认状态的费用不会被静默当作零，也不会在对账完成前计入权威成本。

## 对账流程

1. 券商确认成交后，系统立即保存订单和成交数量。
2. 如果成交响应没有权威费用证据，交易保持 `fee_status=pending`。
3. 超过配置的重试间隔后，Alpaca 同步 Worker 会重新检查仍含待确认费用的已完成订单。
4. 系统把券商活动记录标准化为按币种拆分的费用明细。
5. 在可转换时将费用换算为报价币种，并按成交金额比例回填到对应交易记录。
6. 非零费用保存为 `actual`；明确确认的零费用保存为 `actual_zero`；证据来源记录为 `rest`。

该过程具备幂等性：只有手续费状态仍为待确认的交易才会被回填，因此重复同步不会重复计费。

## 运维排查

如果手续费长时间保持待确认：

1. 确认 trading worker 正常，并且与 API 连接同一个数据库。
2. 确认 Alpaca 凭据有效，且具备读取订单和账户活动的权限。
3. 确认待处理订单已有券商订单 ID，且成交数量大于零。
4. 在 trading-worker 日志中检查 `alpaca_fill_sync`、鉴权错误或活动查询失败。
5. 检查对应 `qd_strategy_trades` 记录：未完成时为 `fee_status=pending`；完成后应为 `actual` 或 `actual_zero`，并带有 `fee_source`。

不要因为券商暂时未返回费用，就手动把待确认费用改成零。这会把“缺少证据”错误地变成“零费用”的会计事实。

## 适用范围

本文描述 QuantDinger 的 Alpaca 策略执行账本。账户层面的最终费用仍以 Alpaca 对账单和账户活动为外部权威来源。监管费、活动费、ADR 费、利息及其他券商级费用可能独立于单笔成交佣金到达，并在数据可用时分项展示。