餐饮 SaaS 优惠券系统架构演进（十三）券模板、发放批次与用户券数据模型：不可变快照、版本演进、状态归档与冷热分层

优惠券系统的数据难题并不只是表多，而是“今天改配置，昨天发的券会不会跟着变”。本篇用一次模板原地修改导致历史券门槛、有效期和退券规则漂移的脱敏事故，拆解不可变版本、批次固定、实例快照、迁移回放与冷热归档。

Immutable VersionIssuance BatchSnapshot HashRCA / Postmortem

结论先行：模板负责表达可复用定义，版本负责冻结一次发布，批次负责固定一次发行，用户券负责固化个人实例。运行时不得通过 templateId 回读“当前规则”；必须使用 versionId + snapshotHash + 实例绝对有效期 解释历史券。

案例边界与脱敏：文中的模板、批次、用户、门店和订单均为示例标识，例如 template_demo_T100、batch_demo_B1、coupon_demo_C100。技术结构、故障机制和修复逻辑保留，真实业务数据已替换。

1. 背景与问题：为什么修改模板会改变已经发出的券

早期系统把 coupon_template 同时当作编辑草稿、线上规则和历史依据。user_coupon 只保存 templateId；券包查询、定价试算和退款决策都在运行时回表读取模板。运营为了下一轮活动修改门槛和有效期后，旧批次已经发出的券也看到了新规则。

更隐蔽的是缓存让不同节点在一段时间内读到不同值：券包服务展示新门槛，定价节点仍使用旧门槛，退款服务则加载新的退券策略。数据库里没有脏数据，但同一张券在三个业务链路中出现三种语义。

图 1：模板原地修改导致历史用户券语义漂移的事故链

2. 目标与约束：定义可以演进，已经发行的契约不能漂移

核心不变量：Published(versionId) ⇒ immutable(contentHash)；Batch ⇒ exactly one versionId；UserCoupon ⇒ versionId + snapshotHash + absolute validity。

3. 系统架构：定义、发布、发行、实例与审计分层

Template Service 管理草稿和不可变版本；Release Registry 保存审批与生效证据；Issuance Service 以固定版本创建批次并生成实例快照；Coupon Runtime 只读取实例语义；Hot Store、Archive Store 和 Audit / Replay 共同承担在线查询、长期留存和问题复现。

图 2：券模板、批次、实例与归档分层架构

4. 核心设计：四层身份坐标，而不是一个 templateId

templateId 是模板家族的稳定业务身份；versionId 标识一次不可变发布；batchId 表示一次具体发行计划；userCouponId 表示发给某个用户的实例。四个 ID 各自解决不同问题，不能相互替代。

图 3：模板家族、版本、批次与用户券的坐标关系

5. 数据模型与 ERD：把定义事实和运行事实分开

coupon_template 保存模板家族；coupon_template_version 保存不可变规则；coupon_release 保存审批发布证据；issuance_batch 固定版本与发行参数；user_coupon 保存实例状态和绝对有效期；coupon_snapshot 保存规范化运行规则；coupon_archive_index 负责冷数据定位。

图 4：模板、批次、用户券与归档 ER Diagram

6. 发布与发放流程：在正确的时间冻结正确的数据

模板 Draft 通过静态校验、影响面 Diff 和审批后生成新 Version；发布清单记录 contentHash。创建批次时固定 versionId；第一张券写入后，批次核心参数锁定。发券事务同时写 user_coupon、snapshotRef、Operation 和 Outbox。

图 5：模板发布、批次创建与用户券发放时序图

7. 用户券快照：快照什么，不快照什么

快照应包含运行时判断必需且会影响历史结果的字段：优惠类型与值、门槛、适用商品/门店表达式、叠加规则、退款退券策略、资金归属引用、Schema 版本和绝对有效期。展示名称、运营备注等非契约字段可通过独立只读元数据补充。

图 6：用户券快照生成与运行时读取数据流

snapshot = canonicalize({
  "schemaVersion": 3,
  "templateId": "T100",
  "versionId": "V2",
  "discount": {"type": "AMOUNT", "valueCent": 2000},
  "thresholdCent": 15000,
  "scopeExpr": "scope_demo_42",
  "stackingPolicy": "EXCLUSIVE_COUPON",
  "returnPolicy": "RETURN_IF_FULL_REFUND",
  "validFrom": "issuedAt",
  "validTo": "issuedAt + 30d"
});
snapshotHash = sha256(snapshot);

8. 有效期模型：相对策略只存在于批次，实例保存绝对时间

“领取后 30 天有效”是批次的计算策略，不应成为运行时每次重新计算的表达式。发券时基于统一时钟、时区和边界规则计算 validFrom / validTo，并写入用户券。若规则是自然日，必须明确是否包含领取日、结束时刻和夏令时处理。

• 固定区间：批次保存 startAt / endAt，实例复制绝对值。
• 相对天数：以 issuedAt 和业务时区计算，实例保存结果与 calculationPolicyVersion。
• 延迟生效：保存 validFrom，不用 status 模拟未来时间。
• 延期补偿：追加 Extension Operation，不能覆盖原始有效期证据。

9. 数据库写入顺序、事务与一致性

发布事务先写 Version，再写 Release 与 Outbox；创建批次前验证 Release 状态与 contentHash；发券事务锁定/校验批次额度，写 UserCoupon 与 SnapshotRef，递增 issuedCount，并写 Operation / Outbox。跨服务采用业务幂等键和 Inbox 去重。

BEGIN;
SELECT version_id, content_hash
  FROM coupon_template_version
 WHERE version_id = :versionId AND status = 'PUBLISHED';

INSERT INTO user_coupon(
  user_coupon_id, batch_id, version_id, snapshot_hash,
  user_ref, status, valid_from, valid_to, issue_business_key
) VALUES (...);

UPDATE issuance_batch
   SET issued_count = issued_count + 1
 WHERE batch_id = :batchId
   AND issued_count < planned_count;
INSERT INTO coupon_operation(...);
INSERT INTO coupon_outbox(...);
COMMIT;

10. 冷热分层与状态归档：移动位置，不改变身份

AVAILABLE / LOCKED 和近期售后相关券留在 Hot Store；进入终态且超过在线窗口后移动到 Warm / Cold。归档前校验状态终结、售后无未决、Operation 连续、Outbox 已处理和 checksum 一致。全局索引保存 userCouponId 到物理分区的映射。

图 7：用户券冷热分层与归档生命周期

11. 历史迁移：双写、回填、影子读与约束收紧

旧系统没有 versionId 和 snapshotHash 时，不能停机一次性切换。先加可空字段并双写新数据；再依据发券时间、批次记录、模板审计日志和订单证据回填；随后 Shadow Read 比较旧回表与快照解析结果；灰度切读后再收紧 NOT NULL、FK 和 Published 禁止更新约束。

图 8：从可变模板回表到实例快照的安全迁移

12. Troubleshooting：历史券门槛和有效期突然变化

Symptoms

用户券 coupon_demo_C100 上午显示“满 100 减 20”，下午变成“满 150 减 20”；部分节点仍允许满 100 使用。退款重算时又采用了新模板中的“不退券”策略，客服无法解释原订单。

Investigation

• 按 userCouponId 查看实例，只找到 templateId，没有 versionId、snapshotHash 或发行规则。
• 审计日志显示运营在 11:30 原地更新 coupon_template，未创建新版本。
• 比较服务节点缓存，发现同一个 cacheKey=templateId 对应两个 ruleHash。
• 订单 PriceQuote 保存的门槛为 10000 分，当前模板为 15000 分，证明历史语义已漂移。
• 退款服务直接读取当前 returnPolicy，未引用原 Quote 或用户券快照。

图 9：模板语义漂移事故的证据链

Root Cause

直接根因是 Published 模板允许原地 UPDATE，历史用户券在运行时通过 templateId 回读当前规则；系统性根因是领域模型没有区分模板家族、不可变版本、发行批次和个人实例。缓存并不是根因，它只是让不同时间的错误真相同时可见。

图 10：历史用户券规则改变的 5 Whys

Resolution

• 引入 coupon_template_version，Published 行由数据库触发器和服务权限共同禁止更新。
• 批次固定 versionId / contentHash；首张券发出后禁止修改核心发行参数。
• 用户券写入绝对有效期、snapshotHash，并让所有运行链路优先读取快照。
• 历史数据按证据可信度回填；无法唯一还原的实例进入 REVIEW，不猜测版本。
• 退款、核销和展示增加 Snapshot Missing / Hash Mismatch Gate。

Verification

修复后回放 320,000 张历史券，在券包、试算、核销和退款四条链路比较解析结果；可确定版本的数据 Diff 为 0。对 1,842 张证据不足的券保持 REVIEW 并按原订单证据处理。连续 14 天监控未再出现同一 userCouponId 多 ruleHash。

Lessons Learned

配置只要进入订单、资金或用户权益链路，就不再是普通配置，而是历史契约。契约的正确演进方式是创建新版本并让新批次引用它，而不是在原记录上覆盖字段。

13. 为什么原方案会失败，最终方案为什么有效

14. 关键实现：不可变发布和快照读取契约

UserCoupon issue(IssueCommand cmd) {
  return tx.execute(() -> {
    Batch batch = batches.requireOpen(cmd.batchId());
    TemplateVersion v = versions.requirePublished(batch.versionId());
    require(v.contentHash().equals(batch.contentHash()));

    CouponSnapshot s = snapshotFactory.freeze(v, batch, cmd.issuedAt());
    UserCoupon c = coupons.insertUnique(cmd.businessKey(), s);
    batches.incrementIssuedWithLimit(batch.id());
    operations.appendIssued(c, v.versionId(), s.hash());
    outbox.append("CouponIssued", c.id(), s.hash());
    return c;
  });
}

CouponRule runtimeRule(UserCoupon c) {
  return snapshots.requireByHash(c.snapshotHash()); // no current-template fallback
}

15. 版本兼容与 Schema 演进

不可变不等于永远使用同一个 JSON 结构。Snapshot 保存 schemaVersion；读取端通过 Upcaster 将旧结构转换为当前内存模型，但不回写和改变原始内容哈希。涉及业务含义变化时创建新 Template Version，不能用 Upcaster 偷偷改变历史规则。

• 结构性变化：字段重命名、默认值展开，可由纯函数 Upcaster 处理。
• 语义性变化：金额舍入、叠加规则、有效期边界，必须创建新版本。
• 每个 Upcaster 具备 Golden Case、幂等性和旧快照回放测试。
• 保存 originalSnapshotHash 与 canonicalViewHash，区分原始证据和当前视图。

16. 验证方案：历史回放、哈希、迁移与归档

• Immutable Test：Published Version 的任何 UPDATE 在服务层和数据库层均失败。
• Replay Test：同一 userCouponId 在不同发布日期、缓存状态和代码版本下解析结果一致。
• Hash Test：字段排序、空值和金额规范化后 contentHash 稳定，业务字段变化必然改变哈希。
• Migration Test：回填可断点续跑，同一行重复执行不改变结果，未知证据进入 REVIEW。
• Archive Test：冷热迁移前后查询、Operation 回放和 checksum 一致。

Invariant 1: published version content never changes
Invariant 2: one batch pins exactly one version and contentHash
Invariant 3: one user coupon resolves to exactly one snapshotHash
Invariant 4: runtime never falls back to the current template
Invariant 5: validFrom/validTo are absolute instance facts
Invariant 6: archive move preserves identity, checksum and replay result
Invariant 7: unknown historical evidence is REVIEW, never guessed

17. 可观测性与发布 Gate

18. 方案取舍

19. Lessons Learned

• 第一，模板是家族，版本才是可以被业务依赖的不可变契约。
• 第二，批次不是一个统计标签，它冻结一次发行的版本、数量、渠道和有效期策略。
• 第三，用户券必须保存绝对有效期与快照哈希，不能在运行时猜测历史规则。
• 第四，缓存键必须包含版本坐标；缓存一致性不能修复可变契约本身。
• 第五，无法可靠还原的数据应显式 REVIEW，错误的确定性比暂时的不确定更危险。
• 第六，归档是物理位置变化，不是身份、证据和回放能力的删除。

20. 后续优化与总结

• 建设模板版本 Diff、依赖批次和受影响用户券的可视化影响面。
• 为 Snapshot Schema 建立注册中心、Upcaster 兼容矩阵和持续回放。
• 将 Template/Batch/Snapshot contentHash 纳入 PriceQuote、Redemption 与 Refund 证据链。
• 按状态、时间和法规要求自动化冷热迁移，并定期做抽样恢复演练。
• 为 Published UPDATE、Snapshot Missing 和 Multi RuleHash 设置不可绕过的发布 Gate。

优惠券数据模型的核心不是把字段拆到更多表里，而是明确每个事实何时产生、何时冻结、由谁引用、如何回放。模板版本保证定义历史，发放批次保证发行边界，实例快照保证运行语义，归档索引保证长期证据仍可定位。

最终结论：任何已经影响用户权益、订单价格或资金结算的配置，都必须被当成不可变历史契约。新需求通过新版本向前演进，不能通过覆盖旧记录重写过去。

21. 下一篇

第十四篇进入优惠券查询与性能治理：《亿级用户券查询与索引设计：券包分页、状态过滤、热点分片、缓存一致性与归档回源》。重点讨论高基数用户券表的复合索引、游标分页、读模型、缓存键、热点用户和冷热路由。

Coupon System Engineering Case Study · Part 13
单文件 HTML · 10 张 PNG 已 Base64 内嵌 · 面向 CSDN 富文本发布