华为云代金券到期盯守：每日快照与幂等兑换

一、真实漏掉的不是余额，是有效期

月初对账时发现一个账户里还躺着几张代金券，余额明明不为零，但expire_time已经在上周过去了，账单按原价出了。问题不在余额，而在监控维度。代金券有两个互相独立的属性：剩余金额和过期时间。只看余额，你会以为“还有钱”，实际这些钱已经不可用；只看有效期，又会把用光的券误判为待处理。两条线必须同时看，并且分别设阈值告警：余额低于某个值（比如 50 元）触发“快用完了”，距离过期小于 15 天触发“快过期了”。

更麻烦的是库存维度。优惠券分“可领取”和“已领取”两种状态，接口返回的列表里既可能混着别人的可用券信息，也可能只给你领取资格而不给券 ID。所以脚本里第一件事是把状态字段打印出来核对，而不是假设字段含义。

二、为什么是每日快照，不是实时轮询

代金券的过期是天级事件，不是秒级事件。实时轮询（比如每 60 秒跑一次）除了白白消耗接口配额，还会让你在配额打满时错过真正的告警。用只读查询做每日一次的快照，收益很直接：

• 调用量固定，一天几次查询，配额几乎不会成为瓶颈；
• 快照落库后可以对比前后两天的差异，比如某张券余额从 800 掉到 0，或者突然从列表里消失，这类变化比单点数值更有信息量；
• 出问题时能回溯“昨天看到的是什么”，而不是只能看到当前状态；
• 查询接口即使偶发失败，还有前一天的快照兜底，不会整条链路断掉。

快照的落地方式用最简单的方案即可：每天定时跑一次查询，把结果写成一个 JSON 文件或一行数据库记录，字段至少保留券 ID、余额、生效时间、过期时间、状态。存原始响应而不是只存结论，后面排查会感谢自己。

三、兑换必须是“一次性开关 + 幂等记录 + 失败不自动重试”

监控脚本只读没问题，但兑换是写操作，风险完全不同。把兑换做成独立动作，并同时满足三个约束：

一次性开关。用一个显式的环境变量或配置文件项控制是否允许兑换，默认关闭。脚本发现某张可领取券时，只输出“建议兑换”的日志，绝不自动执行。需要人工确认后把开关打开跑一次，跑完立即关掉。这样即使脚本被误调度，也不会连续兑换。

幂等记录。每次兑换前，先用券的唯一标识（券 ID 或领取记录 ID）去本地记录表里查一遍，存在就跳过。写记录和发请求之间没有原子性，所以记录要带状态字段（开始/成功/失败），成功才落终态。不要用时间戳当去重键，重跑时会失效。

失败不自动重试。兑换接口的失败原因可能是参数错、资格已用、配额超限，其中“资格已用”恰恰说明你重试也没用，而“网络超时”重试又可能造成双领。所以失败一律停下来，记录原始错误信息（比如返回码和 message 全文），留待人工判断。自动重试在这种场景下是风险放大器，不是稳定性保障。

四、监控脚本里不要顺手写

一个常见的坏习惯是：监控脚本发现快过期了，顺手调个接口去延期或兑换，觉得“反正都是同一批 API”。这会让只读链路和写链路共享同一份失败域——查询失败可能被当成“没有数据”，而写操作一旦被误触发，没有人工复核的机会。监控脚本的职责边界应该是：读、比对、告警。所有写动作放在单独入口、单独开关、单独日志里，跑的时候是你在跑，不是 cron 在跑。

落地顺序建议：先写只读快照，跑三天确认字段含义和数量稳定；再加差异比对和过期告警；最后才把兑换做成人工触发的一次性脚本。每一步都能独立验证，比一次性写完整个自动化流程可靠得多。