fix(billing): harden tiered retry group-switch billing (follow-up to #6518)

[Calcium-Ion]

⚠️ 提交说明 / PR Notice

Important

• 请提供人工撰写的简洁摘要，避免直接粘贴未经整理的 AI 输出。

📝 变更描述 / Description

Follow-up to #6518 (fix for #6480), addressing three non-blocking review findings on the tiered-billing retry path. This PR was developed with AI assistance (reviewed before submission).

1. 钱包 Reserve 补扣的欠费（arrears）语义 — 重试落到更贵的分组时，预扣目标的补扣差额必须全额无条件扣减：model.DecreaseUserQuota 是无条件 quota - ? 递减，余额不足的部分记为用户欠费（余额可为负），与结算路径（SettleBilling 正差额 → WalletFunding.Settle）语义完全一致，请求不因补扣不足而中断。这是对账要求：日志记录的预扣/结算额度必须与用户余额的实际变动一致。本 PR 为该分支补充了明确的语义注释，并新增回归测试锁定该行为（此前无任何测试覆盖，未来改动若引入余额检查会立即破坏对账一致性）。真正的数据库错误仍返回 update_data_error 并使本次尝试失败，绝不静默少预扣。订阅资金来源不变：PostConsumeUserSubscriptionDelta 强制 used <= total 硬上限（model/subscription.go），订阅不支持欠费，因此保留其 insufficient_user_quota（403）行为。
2. 免费转付费分组后 PriceData.FreeModel 未同步 — 初始分组 ratio 为 0（跳过预扣费）而重试落到付费分组时，PrepareTieredBillingForSelectedGroup 会创建计费会话，但 FreeModel 仍为 true。现在在付费分组分支将其清为 false。付费转免费方向保持不变：会话已存在时 "跳过预扣费" 不再成立，且结算对 ratio 0 本就产出 0。
3. controller/relay.go 顺序问题 — (a) getChannel 中 HandleGroupRatio 原先在 CacheGetRandomSatisfiedChannel 的错误检查之前执行，选路失败也会改写定价状态，现移到错误处理之后；(b) 重试循环中 PrepareTieredBillingForSelectedGroup 原先在 addUsedChannel 之前，Prepare 失败时选中的渠道不会出现在 use_channel 重试日志里，现先记录渠道再执行 Prepare。

计费不变量保持：扣费金额永不为负（欠费指余额可为负，而非扣费额为负）；FinalPreConsumedQuota 与会话预扣量始终反映完整的补扣后预扣目标，保证预扣与结算差额正确对账；补扣遇数据库错误即失败整个尝试。

🚀 变更类型 / Type of change

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

🔗 关联任务 / Related Issue

• Follow-up to fix(billing): settle tiered retries with final group #6518, context: tiered_expr 在 auto 跨组重试后仍按首次分组倍率结算 #6480

✅ 提交前检查项 / Checklist

• 人工确认: 描述基于对代码逻辑的实际理解撰写并经过整理；本 PR 为 AI 辅助开发（AI-assisted），特此说明。
• 非重复提交: 我已搜索现有的 Issues 与 PRs，确认不是重复提交。
• Bug fix 说明: 若此 PR 标记为 Bug fix，我已提交或关联对应 Issue，且不会将设计取舍、预期不一致或理解偏差直接归类为 bug。
• 变更理解: 我已理解这些更改的工作原理及可能影响。
• 范围聚焦: 本 PR 未包含任何与当前任务无关的代码改动。
• 本地验证: 已在本地运行并通过测试或手动验证，维护者可以据此复核结果。
• 安全合规: 代码中无敏感凭据，且符合项目代码规范。

📸 运行证明 / Proof of Work

$ go build ./...   # ok

$ go test ./service/... ./pkg/billingexpr/... ./controller/...
ok  	github.com/QuantumNous/new-api/service	0.419s
ok  	github.com/QuantumNous/new-api/service/authz	0.021s
ok  	github.com/QuantumNous/new-api/pkg/billingexpr	0.012s
ok  	github.com/QuantumNous/new-api/controller	0.311s

$ go test ./service/ -run 'TestPrepareTieredBilling|TestBillingSessionReserve' -v
--- PASS: TestPrepareTieredBillingForSelectedGroupUpdatesReservation (0.00s)
--- PASS: TestPrepareTieredBillingForSelectedGroupStartsBillingAfterFreeGroup (0.00s)
--- PASS: TestPrepareTieredBillingForSelectedGroupPaidToFreeKeepsFreeModelFalse (0.00s)
--- PASS: TestPrepareTieredBillingForSelectedGroupTopUpArrearsAllowsNegativeBalance (0.00s)
--- PASS: TestBillingSessionReserveWalletTopUpDecrementsBalance (0.00s)
PASS

新增测试覆盖：余额不足时补扣不中断请求（Prepare 返回 nil）、全额扣减使余额进入欠费（-30k）、FinalPreConsumedQuota 等于完整新预扣目标（100k）、后续结算按完整预扣正确对账（80k 实耗 → 退 20k → 余额 -10k）；余额充足的补扣正确扣减并同步 FinalPreConsumedQuota；免费转付费清除 FreeModel；付费转免费保持 FreeModel=false 且不触发 Reserve。

Summary by CodeRabbit

• Bug Fixes
  • Improved relay channel selection and pricing preparation when selection fails or no channel is available.
  • Updated wallet funding to allow temporary negative balances when usage exceeds available funds, with subsequent settlement adjustments.
  • Corrected free and paid model status transitions when switching billing groups.
  • Improved consistency for paid-group billing reservations and pre-consumption.

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[coderabbitai]

Walkthrough

The relay flow records and validates channels before pricing. Tiered billing updates FreeModel across group transitions. Wallet reservations can create arrears and are covered by settlement and deduction tests.

Changes

Relay billing flow

Layer / File(s)	Summary
Channel selection and billing order controller/relay.go	The relay records the selected channel before billing preparation. getChannel returns channel errors before applying group-ratio pricing.
Tiered billing state transitions service/tiered_settle.go, service/tiered_settle_test.go	Tiered billing handles missing snapshots and zero-ratio groups separately. Paid-group selection clears PriceData.FreeModel. Tests cover paid-to-free and free-to-paid transitions.
Wallet quota reservation service/billing_session.go, service/tiered_settle_test.go	Wallet reservations decrement the full requested quota, even when the balance becomes negative. Tests cover arrears, settlement refunds, and incremental deductions.

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

Possibly related PRs

• QuantumNous/new-api#6518: Modifies the same tiered-billing preparation and relay channel-selection flow.
• QuantumNous/new-api#6405: Changes relay channel selection and group-ratio billing behavior.

Poem

A rabbit records the chosen route,
Paid groups clear the free-state suit.
Wallets may dip below the line,
Settlement makes the balance fine.
Tests hop through each billing byte.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main billing changes for tiered retry group switching.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/tiered-retry-billing-followups

---

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.}

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

service/billing_session.go (1)

232-256: 🩺 Stability & Availability | 🔴 Critical | 🏗️ Heavy lift

Do not use a separate read-then-unconditional-write path for wallet balance.

reserveFunding reads model.GetUserQuota(funding.userId, false), checks userQuota-delta < 0, and then calls model.DecreaseUserQuota(funding.userId, delta, false). DecreaseUserQuota updates quota = quota - ? without a quota >= ? guard, and Reserve only serializes calls on the same BillingSession. Two concurrent wallet requests can both pass the read check and both decrement, leaving the wallet balance negative. Use an atomic conditional update that rejects quota - ? < 0 (including handling rows-affected), or a per-user lock around the read/decrement sequence, including the initial pre-consume wallet path.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@service/billing_session.go` around lines 232 - 256, Replace the separate
GetUserQuota check and unconditional DecreaseUserQuota call in
BillingSession.reserveFunding with an atomic quota decrement guarded by
sufficient balance, and handle zero rows affected as insufficient_user_quota
while preserving database errors as update_data_error. Apply the same
synchronization or conditional-update protection to the initial wallet
pre-consume path used by tryWallet so concurrent requests cannot overdraw a user
wallet.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@controller/relay.go`:
- Around line 314-324: The retry path computes the group ratio before the
selected retry group is available in the context, so `HandleGroupRatio` may use
the wrong group. Update the call to `helper.HandleGroupRatio` in the retry flow
to receive or otherwise use `selectGroup`, ensuring `info.UsingGroup` reflects
the retry-selected group before `PriceData.GroupRatioInfo` is assigned.

---

Outside diff comments:
In `@service/billing_session.go`:
- Around line 232-256: Replace the separate GetUserQuota check and unconditional
DecreaseUserQuota call in BillingSession.reserveFunding with an atomic quota
decrement guarded by sufficient balance, and handle zero rows affected as
insufficient_user_quota while preserving database errors as update_data_error.
Apply the same synchronization or conditional-update protection to the initial
wallet pre-consume path used by tryWallet so concurrent requests cannot overdraw
a user wallet.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 926a473f-4135-4d79-86e3-a8333c0d1610

📥 Commits

Reviewing files that changed from the base of the PR and between df43f80 and dd924e5.

📒 Files selected for processing (4)

• controller/relay.go
• service/billing_session.go
• service/tiered_settle.go
• service/tiered_settle_test.go

[coderabbitai]

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail
rg -n "func HandleGroupRatio" --type go -A 40
echo "---"
rg -n "func SetupContextForSelectedChannel" --type go -A 40
echo "---"
rg -n "UsingGroup\s*=" --type go

Repository: QuantumNous/new-api

Length of output: 157

---

🏁 Script executed:

#!/bin/bash
set -u

echo "Go files:"
git ls-files '*.go' | wc -l

echo "--- locate candidate files by basename ---"
fd -a 'relay.go|tiered_settle.go|group|group_ratio|json.go' . | sed 's#^\./##' | head -200

echo "--- search symbols with case-insensitive text search ---"
rg -n -i 'HandleGroupRatio|SetupContextForSelectedChannel|UsingGroup|SelectGroup|selectGroup|refreshTieredBillingGroup' . | head -300

echo "--- git diff stat/summary if available ---"
git diff --stat || true

Repository: QuantumNous/new-api

Length of output: 32906

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "--- relay helper price.go ---"
cat -n relay/helper/price.go | sed -n '1,110p'

echo "--- controller/relay.go relevant section ---"
cat -n controller/relay.go | sed -n '260,350p'

echo "--- middleware auth context key setter ---"
cat -n middleware/auth.go | sed -n '455,480p'

echo "--- relay common relay_info.go BuildFromContext section ---"
cat -n relay/common/relay_info.go | sed -n '430,495p'

echo "--- middleware distributor SetupContextForSelectedChannel ---"
cat -n middleware/distributor.go | sed -n '440,490p'

echo "--- tiered settle refreshTieredBillingGroup ---"
cat -n service/tiered_settle.go | sed -n '85,105p'

Repository: QuantumNous/new-api

Length of output: 15711

---

Thread the selected retry group into HandleGroupRatio.

HandleGroupRatio(c, info) sets relayInfo.UsingGroup from the auto_group context value, but controller/relay.go:322 calls it before middleware.SetupContextForSelectedChannel sets that value. In the retry path, pass selectGroup to the helper or set auto_group/info.UsingGroup with the retry-selected group before computing the group ratio.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@controller/relay.go` around lines 314 - 324, The retry path computes the
group ratio before the selected retry group is available in the context, so
`HandleGroupRatio` may use the wrong group. Update the call to
`helper.HandleGroupRatio` in the retry flow to receive or otherwise use
`selectGroup`, ensuring `info.UsingGroup` reflects the retry-selected group
before `PriceData.GroupRatioInfo` is assigned.