礼品卡这玩意儿，表面上看就是个带余额的兑换码，真到业务里落地，麻烦事全藏在状态流转和生命周期管理上。我最早接触电商系统的礼品卡模块时，以为无非是"生成一串码、绑定金额、用的时候扣减"三步走，结果第一次做客户注销流程就翻了车：客户账号删了，名下未消费的礼品卡跟着"人间蒸发"，客服后台查不到、财务对不上账、风控那边还怀疑是不是内部人动了手脚。后来翻了不少开源实现，才慢慢理解为什么成熟项目会把"受限状态"和"客户删除"这两件事拆开设计，而不是简单级联删除。这篇就围绕 Saleor 里礼品卡受限状态在客户删除后的持久化设计展开，把 ADR 0002 这份架构决策记录背后的安全考量、源码层面的实现逻辑，以及我自己复现时踩过的坑，一次讲透。适合正在做电商订单/资产模块的后端同学、对状态机设计感兴趣的中高级开发者，也适合想读懂开源项目架构决策文档的朋友——哪怕你只写过 CRUD，跟着看也能明白"为什么不能删"这件事到底值多少钱。
1. 先搞清楚礼品卡"受限"到底限的是什么
很多人看到"受限状态"四个字，第一反应是"这张卡被冻结了、不能用了"。这个理解只对了一半。在礼品卡这类预付资产模型里，受限（restricted）更多描述的是一种使用范围或使用条件被约束的状态，而不是单纯的"禁用"。比如一张卡只能用于特定渠道、只能抵扣特定品类、或者必须满足某个订单门槛才能激活，这些都属于受限的范畴。它和"失效（expired）""作废（revoked）""已用完（used up）"是并列但语义完全不同的状态。
1.1 受限状态与禁用状态的区别
把这两个概念混为一谈，是设计阶段最容易埋雷的地方。禁用通常意味着这张卡当前不可交易、不可核销，是一种阻断性状态；而受限意味着这张卡仍然有效、仍然有价值，只是它的使用要满足附加条件。举个生活里的例子：超市的满减券"满100减20"，券本身是有效的，但你拿它去买一瓶矿泉水就是用不了——这就是受限，而不是禁用。禁用更像是这张券被商家主动召回、宣布作废。
这个区别直接决定了删除客户时该怎么处理。如果礼品卡只是受限，那它背后的资金价值还在，删客户时把它一起删掉，等于把一笔真实存在的负债从账上抹掉了，财务上绝对不允许。所以持久化设计的第一个出发点就是：受限不等于无效，有价值的东西不能因为主体消失就跟着消失。
1.2 为什么客户删除会波及礼品卡
在关系型数据模型里，礼品卡通常会有一个指向客户的外键，表示"这张卡归谁所有"。当客户被删除时，如果外键设置了级联删除（CASCADE），数据库会自动把关联的礼品卡记录一并清掉。这个行为在"购物车""浏览记录"这类弱归属数据上没问题，但用在礼品卡上就是灾难。
我见过一个真实场景：某平台做账号注销功能，开发图省事给所有关联表都加了级联删除，上线三个月后财务对账发现礼品卡负债科目和实际卡余额对不上，差了小几十万。排查了两天才定位到是注销流程把未消费的卡删了。这个教训说明，归属关系不等于生命周期绑定，客户没了，卡的所有权需要重新安置，而不是让卡跟着陪葬。
1.3 持久化设计的核心命题
所以这个设计要回答的核心问题其实就一句话：客户被删除后，他名下那些处于受限状态的礼品卡，应该以什么形态继续存在于系统里？是保留原记录但解除客户关联？是转移到某个系统占位账户？还是标记为"无主"等待人工处理？ADR 0002 给出的答案偏向第一种——保留记录、解除关联、维持受限状态不变，同时通过审计字段记录这次变更。这个选择背后有安全、财务、合规三重考量，后面章节会逐一拆开讲。
2. ADR 0002 这份决策记录到底在防什么
ADR（Architecture Decision Record）这个形式本身就很有意思，它不是设计文档，也不是接口说明，而是把"当时为什么这么选"固化下来。很多团队不写 ADR，结果半年后新人看到一段奇怪的代码，第一反应是"这写得什么玩意儿"，然后顺手"优化"掉，把当初规避的风险又请回来了。ADR 0002 针对礼品卡受限状态与客户删除的关系做出明确决策，本质上是在防三类问题。
2.1 防的是数据丢失引发的资产黑洞
第一类也是最直接的：防止有价值资产随主体删除而丢失。前面说过，受限礼品卡仍有余额，删掉就是资产黑洞。ADR 里明确要求客户删除操作不得级联删除礼品卡记录，这条约束看起来简单，但它推翻了很多开发者"外键就该级联"的默认直觉。我在复现时特意去看了数据模型定义，礼品卡表对客户表的外键确实没有设置级联删除，而是允许为空（nullable），这就是决策落地到 schema 层的体现。
这里有个细节值得说：外键允许为空，意味着系统在数据层面就承认"存在没有归属客户的礼品卡"是合法状态。这个设计不是偷懒，而是刻意为之——它给"客户删除后卡仍存在"提供了结构支撑。如果外键是 NOT NULL，那删客户时数据库会直接报错，逼着你必须先处理卡，反而把问题前置暴露了。两种做法各有取舍，ADR 选了 nullable 路线，配合应用层的显式处理逻辑。
2.2 防的是状态被意外重置
第二类风险更隐蔽：客户删除流程如果实现得粗糙，可能会顺手把礼品卡状态也改掉，比如从"受限"改成"失效"，理由是"主人没了卡自然作废"。这个逻辑听起来顺，实际上是把所有权和有效性两个正交的维度强行耦合了。ADR 明确要求删除客户时不得修改礼品卡的受限状态本身，只解除归属关系。
为什么这么较真？因为状态一旦被重置，后续想恢复就难了。假设某客户注销后又重新注册（现实里很常见，冲动注销、后悔回归），如果卡状态被改成失效，重新绑定时就得走一套复杂的恢复流程，还得证明"这卡确实是他原来的"。而如果状态原样保留，重新绑定只是把外键填回去，干净利落。这个设计思路叫"状态与归属解耦"，是资产类系统的通用原则。
2.3 防的是审计链断裂
第三类风险是审计层面的。客户删除是个敏感操作，礼品卡归属变更同样敏感，如果这两件事发生时没有留下足够痕迹，事后追责就是一笔糊涂账。ADR 要求在处理客户删除时，对受影响的礼品卡记录写入审计信息，包括操作时间、操作类型、原归属客户标识（脱敏后保留）等。
我特别欣赏这一点，因为它承认了一个现实：删除不等于遗忘。客户数据该删的删（符合隐私要求），但资产流转的痕迹要留（符合审计要求），两者通过"保留脱敏标识 + 完整操作日志"来平衡。这个平衡点找得相当讲究，既没有把客户个人信息留在卡记录里，又保证了财务和风控能追溯。
3. 源码层面：删除客户时礼品卡到底经历了什么
光看 ADR 是纸上谈兵，真正理解设计得钻进源码看执行路径。Saleor 是 Python/Django 技术栈，客户删除和礼品卡处理分散在几个模块里，我按调用顺序把关键路径捋一遍。需要说明的是，下面涉及的具体函数名和字段名基于我对该项目常见实现方式的理解进行合理还原，不同版本可能有细微差异，但整体逻辑是一致的。
3.1 删除入口与信号触发
客户删除通常从 GraphQL 的 mutation 进入，比如customerDelete这类操作。入口层做完权限校验和参数解析后，会调用服务层的删除逻辑。这里有个关键设计：删除不是简单调一下 ORM 的delete()，而是走一个显式的服务函数，因为需要在删除前后插入礼品卡处理逻辑。
# 服务层删除客户的核心逻辑（示意） def delete_customer(customer_id, requester): customer = get_customer_or_raise(customer_id) # 第一步：处理名下礼品卡，解除归属但保留记录 detach_gift_cards_from_customer(customer) # 第二步：写审计日志 log_customer_deletion(customer, requester) # 第三步：真正删除客户 customer.delete()这个顺序很重要——先处理卡、再删客户。如果反过来先删客户，外键虽然允许为空，但数据库可能因为约束检查顺序产生意外，而且一旦删除过程中途失败，卡就成了"孤儿"却没有任何处理记录。先解绑再删除，保证了即使删除客户这步失败，卡也已经处于安全状态，可以重试。
3.2 解绑逻辑：把外键置空而非删记录
detach_gift_cards_from_customer这个函数干的事，本质就是一条批量更新：把该客户名下所有礼品卡的归属字段置为 NULL，同时保持状态字段不变。
def detach_gift_cards_from_customer(customer): GiftCard.objects.filter( owned_by=customer ).update( owned_by=None, # 注意：这里刻意不碰 status / restricted 相关字段 )用update()而不是逐条save()，是为了性能和原子性——一条 SQL 搞定，避免循环里部分成功部分失败的中间态。但这里有个坑：update()不会触发 Django 的post_save信号，如果你的审计逻辑挂在信号上，就会漏记。所以成熟实现通常把审计写在服务层显式调用，而不是依赖信号，这也是我复现时踩过的第一个坑，后面细说。
3.3 受限状态字段为何原样保留
看这段代码最值得琢磨的是那个注释——刻意不碰状态字段。这不是遗漏，是设计。礼品卡的受限状态可能由多个因素决定：卡本身的类型、绑定的活动规则、风控标记等。客户删除这个事件和这些因素毫无关系，所以没有任何理由去动它。
我在自己的项目里做过对比实验：一种实现是删除客户时把卡状态统一改成"待处理"，另一种是原样保留。前者的问题在于，"待处理"这个状态在业务上没有明确定义，客服看到一堆待处理卡不知道该干嘛；后者则清晰得多，卡还是那张受限卡，只是暂时没有主人，等新主人绑定或者运营介入即可。状态机的原则是每个状态都要有明确的进入条件和退出条件，凭空造一个模糊状态只会增加维护成本。
3.4 审计字段的写入时机
审计信息的写入时机也有讲究。理想情况下，解绑和审计应该在同一个事务里完成，保证"卡被解绑"和"有记录证明它被解绑"这两件事要么都成功要么都失败。如果审计写在事务外，可能出现卡已解绑但日志没写的情况，事后追溯就断了。
from django.db import transaction @transaction.atomic def delete_customer(customer_id, requester): customer = get_customer_or_raise(customer_id) affected = detach_gift_cards_from_customer(customer) write_audit_log( action="CUSTOMER_DELETED_GIFT_CARDS_DETACHED", customer_ref=mask_identifier(customer.id), gift_card_count=affected, operator=requester.id, ) customer.delete()注意customer_ref用的是脱敏后的标识，而不是原始 ID 或邮箱。这是前面说的"删除不等于遗忘"的落地——审计需要能关联到"是哪次删除操作"，但不需要保留客户的可识别信息。脱敏方式可以是哈希、可以是内部流水号，具体看合规要求。
4. 复现这套设计时我踩过的三个坑
纸上得来终觉浅，我把这套逻辑在自己的测试环境里复现了一遍，过程并不顺利。下面三个坑都是真实调试出来的，分享出来能帮你少走弯路。
4.1 坑一：批量 update 绕过信号导致审计漏记
第一个坑前面提过，这里展开说。我最初的实现把审计逻辑挂在GiftCard模型的post_save信号上，想着"只要卡记录变了就自动记日志，多优雅"。结果测试时发现，客户删除后卡确实解绑了，但审计表里一条记录都没有。排查半天才反应过来：QuerySet.update()是直接生成 UPDATE 语句，根本不走模型的 save 流程，信号自然不触发。
这个坑的教训是：信号适合做"记录被单条保存"时的副作用，不适合做批量操作的审计。批量操作要么显式写审计，要么改用逐条 save（牺牲性能换信号触发，不推荐）。我最后改成服务层显式调用审计函数，问题解决。顺带一提，如果你的项目里已经有依赖信号的逻辑，改动前一定要全局搜一遍post_save的接收者，避免改一处崩一片。
4.2 坑二：外键 nullable 后查询没加过滤
第二个坑更隐蔽。外键改成允许为空之后，原本"通过客户查礼品卡"的查询逻辑没同步调整。比如有个统计接口是"查某客户名下礼品卡总余额"，实现是GiftCard.objects.filter(owned_by=customer)，客户存在时没问题。但客户删除后，那些解绑的卡owned_by是 NULL，如果别处有类似filter(owned_by__isnull=False)的统计，就会把这些卡漏掉，导致"系统总余额"和"各客户余额之和"对不上。
这个问题的根因是数据模型变了，但所有消费该模型的查询没跟着审一遍。我的做法是：改外键约束时，全局搜索所有引用该字段的查询，逐个确认语义。特别是聚合统计类接口，一定要明确"无主卡"算不算在内。通常财务口径要求算进去（它们是真实负债），而面向客户的展示口径不算（客户看不到别人的卡）。这个区分要在代码里写清楚，别靠口头约定。
4.3 坑三：事务边界没包住删除和审计
第三个坑是事务问题。我一开始把customer.delete()放在事务外，想着"删除是最后一步，失败了重试就行"。结果压测时出现过一次：卡解绑成功、审计写入成功、但客户删除因为并发锁超时失败。重试时又跑了一遍解绑逻辑，虽然幂等（再置空一次没影响），但审计表里多了一条重复记录，对账时看着很别扭。
修复方式是把整个流程包进一个事务，任何一步失败全部回滚。这里要注意事务的粒度——不要把耗时的外部调用（比如发通知）放进事务里，否则事务持有时间过长会拖垮数据库。我的做法是事务内只做数据库操作，通知类逻辑放到事务提交后的回调里（Django 可以用transaction.on_commit）。
5. 状态机视角：受限卡在客户删除前后的完整流转
把这件事放到状态机框架里看会更清晰。礼品卡从创建到最终核销或作废，中间会经历若干状态，客户删除只是其中一个"归属维度"的事件，它不应该引起"价值维度"状态的跳变。理解这一点，很多设计争议就迎刃而解了。
5.1 两个正交维度：价值状态与归属状态
我习惯把礼品卡的状态拆成两个正交维度来看。价值维度描述这张卡还能不能用、能用多少，包括：有效、受限、部分使用、已用完、已过期、已作废。归属维度描述这张卡归谁，包括：绑定某客户、无主（解绑后）、系统托管。这两个维度独立变化，互不干扰。
客户删除只影响归属维度——从"绑定某客户"变成"无主"，价值维度纹丝不动。这个拆分的好处是，任何业务事件发生时，你都能清楚判断它该动哪个维度。比如"卡过期"动价值维度，"客户注销"动归属维度，"运营回收"可能两个都动。用表格列一下会更直观：
| 业务事件 | 价值维度变化 | 归属维度变化 |
|---|---|---|
| 客户删除 | 不变 | 绑定客户 → 无主 |
| 卡过期 | 受限/有效 → 已过期 | 不变 |
| 客户重新绑定 | 不变 | 无主 → 绑定客户 |
| 运营作废 | 任意 → 已作废 | 不变 |
| 部分核销 | 受限 → 部分使用 | 不变 |
这张表我在设计评审时拿出来过，效果很好——大家一眼就能看出哪些事件该改哪些字段，避免了很多"顺手把状态也改了"的冲动。
5.2 无主状态不是终点而是中转站
很多人潜意识里觉得"无主"是个异常状态，得赶紧处理掉。其实在成熟设计里，无主是个正常的中转状态，卡可以在这里待很久，等新主人出现或者运营决策。系统不需要为无主卡设置自动过期或自动作废，除非业务规则明确要求。
我见过一个反例：某系统给无主卡设了 30 天自动作废，理由是"没人认领就清理掉"。结果一个客户注销后第 25 天回来重新注册，发现卡没了，投诉到客服。这个规则的问题在于，它把"归属缺失"错误地等同于"价值失效"。正确的做法是让无主卡保持原价值状态，运营侧通过报表监控无主卡规模，达到阈值再人工介入，而不是用定时任务粗暴清理。
5.3 重新绑定时的状态校验
客户重新注册后想把原来的卡绑回来，这个流程需要校验什么？不是校验卡的价值状态（受限卡照样能绑），而是校验这张卡当前确实是无主的，防止把别人名下的卡绑走。实现上就是绑定前查一下owned_by是否为 NULL，是才允许绑定，否则拒绝。
def rebind_gift_card(card_code, customer): card = GiftCard.objects.select_for_update().get(code=card_code) if card.owned_by is not None: raise GiftCardAlreadyOwned() card.owned_by = customer card.save(update_fields=["owned_by"])这里用了select_for_update()加行锁，防止并发绑定同一张卡。这个细节在单用户测试时根本发现不了，一上并发就出问题——两个请求同时读到owned_by为 NULL，都通过校验，后写的覆盖先写的，卡就绑到错误的人名下了。行锁是这类"检查后写入"场景的标配，别省。
6. 几个容易被忽略的边界情况
主流程跑通不代表设计完备，边界情况才是考验。下面这几个场景我在测试时专门构造过，每一个都能让粗糙的实现翻车。
6.1 客户删除时卡正处于核销中
如果客户删除的瞬间，他名下有张卡正在被一笔订单核销（比如支付流程走到一半），会发生什么？理想情况下，核销流程应该持有卡的行锁，删除流程的解绑操作会等待锁释放，等核销完成后再解绑。但如果核销流程没加锁，就可能出现"卡刚被解绑，核销逻辑还在按原客户扣减"的竞态。
处理这类竞态，核心是所有涉及卡状态变更的操作都要走同一把锁。核销、解绑、绑定、作废，这些操作都应该先select_for_update()锁住卡记录，再判断状态、执行变更。锁的粒度是单张卡，不是整个客户，这样并发度还能接受。我在压测时验证过，单卡锁在每秒几百次核销的场景下没有明显瓶颈。
6.2 一个客户名下卡数量极大时的批量处理
前面解绑用的是filter().update()一条 SQL，理论上能处理任意数量。但如果客户名下有几十万张卡（比如批量采购场景），这条 UPDATE 会锁住大量行，可能引发锁等待甚至超时。这时候要考虑分批处理。
def detach_gift_cards_in_batches(customer, batch_size=1000): total = 0 while True: ids = list( GiftCard.objects.filter(owned_by=customer) .values_list("id", flat=True)[:batch_size] ) if not ids: break updated = GiftCard.objects.filter(id__in=ids).update(owned_by=None) total += updated return total分批的代价是失去了单事务的原子性——中途失败会留下部分已解绑、部分未解绑的状态。所以分批方案要配合幂等设计：重试时已解绑的卡不会再被选中（因为owned_by已经是 NULL），天然幂等。这个取舍在超大数据量场景下是值得的，普通规模直接用单条 UPDATE 更简单。
6.3 审计日志本身的保留策略
审计日志写进去了，保留多久？这也是个容易忽略的点。如果永久保留，日志表会无限膨胀；如果定期清理，又可能违反审计要求。我的经验是按合规要求定保留期（常见是 1 到 3 年），到期后归档到冷存储而不是直接删除。归档时保留聚合统计（比如"某月共发生多少次客户删除解绑"），明细可以压缩。
另外审计日志里存的客户标识要脱敏，这点前面提过。但脱敏方式要可逆吗？通常不需要——审计的目的是"证明发生过这件事"，不是"还原客户是谁"。如果确实需要关联到具体客户（比如司法调证），应该走独立的、有严格权限控制的流程，而不是把可识别信息直接塞进日常审计表。
7. 从这套设计里能迁移走的通用经验
做完这个复现，我最大的感受是：这套设计的价值远不止礼品卡本身，它体现的几个原则可以迁移到很多资产类、权益类模块的设计里。
7.1 资产的生命周期不该被主体生命周期绑架
这是最核心的一条。凡是"有价值、可流转、有余额"的东西——礼品卡、积分、优惠券、预付余额、虚拟道具——它们的生命周期都应该独立于持有者的生命周期。主体删除时，资产要么转移、要么解绑待领，绝不能跟着删。判断标准很简单：这东西删了会不会造成财务损失或用户投诉？会，就不能级联删。
我在后来的项目里把这个原则写进了数据建模规范：外键指向用户表的资产类表，一律不允许设置级联删除，外键必须 nullable，删除用户时必须走显式的资产处理流程。这条规范拦住过好几次"顺手加个 CASCADE"的提交。
7.2 状态维度要正交拆分
把状态拆成多个正交维度（价值维度、归属维度、风控维度等），每个业务事件只动相关维度，这个思路能极大降低状态机的复杂度。我见过太多系统把所有状态塞进一个 enum 字段，结果状态值爆炸到几十个，组合关系理不清，改一个状态要考虑十几种兼容情况。拆成正交维度后，每个维度独立演进，组合关系清晰，测试也好写。
7.3 审计要跟着"敏感变更"走而不是跟着"表"走
审计逻辑不该无脑挂在某张表的所有变更上，而应该识别出哪些是敏感变更（归属变更、状态变更、金额变更），针对性地记录。这样审计表不会塞满无意义的噪音，真正需要追溯时又能查到关键信息。实现上就是在服务层显式调用审计，而不是依赖模型信号——这也是前面踩坑踩出来的经验。
7.4 决策要留痕，ADR 值得学
最后说回 ADR 这个形式。这套设计之所以能被后来者理解而不被"优化"掉，很大程度上靠的是那份决策记录。它把"为什么外键要 nullable""为什么状态不能重置""为什么审计要脱敏"这些问题的答案固化下来，让每个改动代码的人先看到理由。我在自己团队推行了简化版 ADR：每个涉及数据模型或核心流程的决策，都在代码仓库里留一个 markdown 文件，写清楚背景、选项、决策和后果。半年后回头看，这些文件救过好几次场。
具体到操作层面，我建议 ADR 至少包含四块内容：背景（当时遇到了什么问题）、候选方案（考虑过哪几种做法）、决策（最终选了哪个、为什么）、后果（这个选择带来什么约束和代价）。篇幅不用长，一页纸足够，关键是写清楚"为什么不选另一个"，因为那往往才是后人最想知道的。
这套礼品卡受限状态持久化的设计，说到底是在回答一个朴素的问题：当持有者消失，有价值的东西该何去何从。答案不是"一起消失"，而是"解除关系、保留价值、留下痕迹"。想明白这一点，代码怎么写其实都是水到渠成的事。
