用途:说明余额(balance)从授予额度递减到 0 时的行为,以及用量如何被允许、限制或超额计费,帮助正确处理配额与上限逻辑。
主要能力与规则:余额递减到 0,低于 0 即为超额(overage)。只有两种情况允许用量越过 0:计划项上配置了按用量计费的价格,或设置了 overage_allowed 计费控制。两者都未设置时,包含额度就是上限,用量在 0 处停止,check 返回 allowed:false,无需额外配置即可强制生效。因此不要为没有超额价格、也没有 overage_allowed 的功能添加 spend_limit,它已被封顶,该限制不起作用。
控制项与余额的关系:只有 overage_allowed 会改变用量能否越过 0,其余控制项只是约束已被允许的用量。usage_limits 是按时间窗口对总用量单独设的闸门,独立于余额计数,无论有无超额都会生效,且可低于包含额度。
track 越过 0 的处理:overage_behavior 决定放不下的扣减如何处理。cap(默认)只扣能放下的部分并在 0 处停止;overflow 扣减全部数值并让余额变负,usage_limits 不会钳制它,但 spend_limits 仍然适用。
计费控制:属于客户或实体上的运行时策略,不定义计划授予什么,只改变用量如何被允许、封顶、告警或补充。通常作为面向客户的设置暴露,但 overage_allowed 一般由产品/管理员控制。包括 overage_allowed(授予余额耗尽后能否继续使用)、spend_limits(按功能单位而非美元限制超额)、usage_limits(时间窗口内的硬性用量上限,适用于计划授予多个余额,如每天 5 个加每月 5 个,但客户还需单独的每月 100 上限;也适用于共享积分系统中某个映射动作需单独上限的情况)、usage_alerts(用量越过阈值时通知,不阻断用量)、auto_topups(余额低于阈值时自动购买预付数量)。客户级控制作用于客户,实体级控制可覆盖该实体的客户级控制;自动充值仅限客户级。
使用方式:修改计费控制前先检查当前客户/实体状态;使用自动充值前确认该功能存在一次性预付购买路径。
限制:不要把告警描述为阻断用量,也不要把 spend_limits 描述为美元限制,除非功能单位就是美元。