fix(billing): settle tiered retries with final group

[faithleysath]

📝 变更描述 / Description

AI-assisted contribution. 修复 tiered_expr 在 auto 跨组重试后仍按首次分组倍率结算的问题（#6480）。

每次渠道选定后，代码会同步 BillingSnapshot 中随路由变化的组倍率和预估额度：

• 重试切到更贵分组时，调用现有 BillingSession.Reserve，在发送请求前补足该组的预扣；
• 初始免费分组重试到付费分组时，在发送请求前建立 BillingSession；
• 切到更便宜或免费分组时不提前退款，仍按最终实际 usage 结算差额；
• 表达式和请求输入保持冻结，只有最终路由相关的组计费状态更新。

这使成功请求按最终选中的分组倍率结算，并保留失败重试的退款和预扣语义。

🚀 变更类型 / Type of change

• 🐛 Bug 修复 (Bug fix) - 请关联对应 Issue，避免将设计取舍、理解偏差或预期不一致直接归类为 bug
• ✨ 新功能 (New feature) - 重大特性建议先通过 Issue 沟通
• ⚡ 性能优化 / 重构 (Refactor)
• 📝 文档更新 (Documentation)

🔗 关联任务 / Related Issue

• Closes tiered_expr 在 auto 跨组重试后仍按首次分组倍率结算 #6480

✅ 提交前检查项 / Checklist

• 人工确认: 提交者已确认本 PR 的描述、实现和测试结果；本 PR 为 AI-assisted 贡献，不声明为纯人工撰写。
• 非重复提交: 已检查现有 Issue 和 PR；关联 tiered_expr 在 auto 跨组重试后仍按首次分组倍率结算 #6480，未发现已有对应修复 PR。
• Bug fix 说明: 问题可在 tiered_expr + auto 跨组重试的纯计费路径复现，关联 tiered_expr 在 auto 跨组重试后仍按首次分组倍率结算 #6480。
• 变更理解: 仅刷新最终路由相关的 group ratio/estimated quota，并复用现有 BillingSession 预扣和结算机制。
• 范围聚焦: 未包含前端功能、schema 迁移或其他计费模式改动。
• 本地验证: 已运行完整 Go 测试和前端生产构建。
• 安全合规: 未包含凭据或配置变更。

📸 运行证明 / Proof of Work

cd web && bun install --frozen-lockfile
DISABLE_ESLINT_PLUGIN=true VITE_REACT_APP_VERSION="$(cat ../VERSION)" bun run build
go test ./...

新增回归覆盖：

• 更贵最终分组会在发送前提高预扣；
• 免费首组重试到付费组会建立 BillingSession；
• 更贵、免费最终分组均按最终倍率结算。

Summary by CodeRabbit

• Bug Fixes

  • Improved tiered billing during relay retries by refreshing billing calculations for the ultimately selected group.
  • Ensured quota reservations and pre-consumption adjustments remain accurate when retries switch between free and paid groups.
  • Improved error handling when updated quota requirements cannot be applied.

• Documentation

  • Clarified tiered billing, retry, snapshot, reservation, and settlement behavior.

[coderabbitai]

Walkthrough

Tiered billing now refreshes group-dependent snapshot fields after auto-group selection, adjusts pre-consumption or reservations, and settles using the final group. The relay retry loop invokes this preparation before marking the channel used or reading the request body.

Changes

Tiered billing retry settlement

Layer / File(s)	Summary
Billing snapshot semantics pkg/billingexpr/types.go, pkg/billingexpr/expr.md, relay/common/relay_info.go	Documentation clarifies frozen request fields, refreshed group-dependent fields, free-to-paid retry billing, and final-group settlement.
Selected-group billing preparation service/tiered_settle.go, service/tiered_settle_test.go	Refreshes group ratios and estimated quota, performs pre-consumption or reservation updates, maps failures to API errors, and tests paid/free retry scenarios.
Retry-loop integration controller/relay.go	Invokes tiered billing preparation after selecting a retryable channel and exits the retry loop when preparation fails.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Relay
  participant PrepareTieredBillingForSelectedGroup
  participant BillingSettler
  participant TryTieredSettle
  Relay->>PrepareTieredBillingForSelectedGroup: selected group and RelayInfo
  PrepareTieredBillingForSelectedGroup->>BillingSettler: PreConsumeBilling or Reserve updated quota
  BillingSettler-->>PrepareTieredBillingForSelectedGroup: updated billing state
  Relay->>TryTieredSettle: final usage and refreshed snapshot
  TryTieredSettle->>BillingSettler: settle captured snapshot
  BillingSettler-->>TryTieredSettle: settlement quota and result

Loading

Possibly related PRs

• QuantumNous/new-api#6405: Both changes modify relay retry and attempt handling in controller/relay.go.

Suggested reviewers: calcium-ion

Poem

A rabbit hops where retries run,
Refreshing rates from group to group in the sun.
Quotas reserve, then settle right,
Free or paid, the totals align bright.
“Nibble the bug!” the bunny sings.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes refresh tiered billing state on retry, use the final group for reservation/settlement, and add regression tests for #6480.
Out of Scope Changes check	✅ Passed	Changes are focused on tiered billing retry/settlement and supporting docs/tests, with no unrelated functional scope.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: tiered billing retries now settle using the final selected group.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}