docs: add phase 2 billing review

docs/api.md

@@ -116,14 +116,17 @@
 }
 ```
 
-## 计费模块合约（`apps/billing.pricing`）
+## 计费模块合约（`apps.billing`）
 
-T-202 后，计费计算已有独立模块，供后续扣点、生成接口和充值下单调用：
+T-202 后，计费计算已有独立模块；T-203 后，扣点/退点也收敛到 billing 层，供后续生成接口和充值下单调用：
 
 ```python
 calculate_points_cost(operation_type: str, alias: str, resolution: str | None = None) -> int
 quote_recharge_points(amount, currency: str = "CNY", at=None) -> RechargeQuote
 calculate_points_granted(amount, currency: str = "CNY", at=None) -> int
+precharge_call(..., user, points_cost: int, operation_type: str, alias: str, ...) -> CallCharge
+mark_call_success(call_record: CallRecord, ...) -> CallRecord
+refund_call_points(call_record: CallRecord, ...) -> RefundResult
 ```
 
 要点：
@@ -133,6 +136,9 @@ calculate_points_granted(amount, currency: str = "CNY", at=None) -> int
 - 缺计费规则抛 `NoPricingRuleError(code="no_pricing_rule")`，API 层应翻译为上方同名错误码。
 - `ExchangeRate` 按 `currency + effective_from` 取当前 active 汇率；充值下单时应锁定当时的 `exchange_rate` / `points_granted` 到订单，回调入账不得按新汇率重算。
 - 金额换点数采用 `floor(amount * points_per_unit)`，点数为整数。
+- `precharge_call()` 使用事务 + `select_for_update()` 锁 `UserWallet` 行；余额不足抛 `InsufficientPointsError(code="insufficient_points")`，不创建 `CallRecord`、不写 `PointsLedger`、不调上游。
+- 预扣成功后写 `CallRecord(status=pending)` 与 `PointsLedger(change_type=consume, points_delta=-N)`；上游成功只更新调用记录，余额不再变化。
+- 上游失败调用 `refund_call_points()`：同一 `CallRecord` 只写一条 `refund` 流水，重复调用不会重复加点；成功调用不能走失败退点。
 
 ## 支付充值（自助扫码：微信 V3 native + 支付宝当面付）