如何在Django中构建支持推荐人分成的分阶段支付流程
内容提要
本文介绍如何在Django中构建支持推荐人分成的分阶段支付流程。核心是将支付视为状态转换，而非单一事件。通过明确建模定金和尾款阶段、使用数据库事务和行锁确保安全、实现幂等Webhook处理、按阶段应用优惠券、显式记录推荐人分成，并在全部款项付清后才解锁交付物，从而避免重复支付和过早发放奖励等常见问题。
延伸解读
为什么支付要建模为状态转换
文章强调，分阶段支付的核心不是处理单个支付事件，而是管理一个状态机。将支付视为状态转换，意味着每个阶段（定金、尾款）都有明确的记录和验证，而不是依赖一个模糊的“已支付”标志。这种设计让系统能够准确追踪进度，避免因状态不清导致的重复支付或过早发放奖励。对于开发者而言，理解这一理念是构建可靠支付流程的基础。
事务与行锁：防止并发支付问题
在支付确认逻辑中，使用`transaction.atomic()`和`select_for_update()`是确保安全的关键。事务保证一系列数据库操作要么全部成功，要么全部回滚；行锁则防止两个并发请求同时处理同一笔支付，避免重复更新状态或创建重复记录。文章强调，这些机制是防止支付系统在并发场景下出现数据不一致的必要手段。
幂等Webhook处理的重要性
支付网关可能多次发送相同的webhook事件，因此处理程序必须幂等。文章中的示例通过先检查支付状态，若已成功则直接返回，避免重复处理。这种设计确保即使webhook重试，也不会产生重复的支付记录或分成记录。开发者应始终将幂等性作为webhook处理的基本要求，以保障系统的健壮性。
分阶段优惠券与推荐人分成的显式建模
文章指出，优惠券可能只适用于特定阶段，推荐人分成也应基于阶段明确记录。通过将优惠券的适用范围（定金、尾款或两者）显式存储在模型中，并在计算折扣时检查阶段，可以避免错误应用。推荐人分成则应在支付成功且满足条件时显式创建，而不是在支付时自动关联，这样可以防止提前支付或错误支付。
Q&A
在Django中，如何设计数据模型来支持分阶段支付？
在Django中，可以通过创建Journey模型来表示客户的整体进度，包含deposit_paid、balance_paid、deliverables_released等布尔字段；创建Payment模型来表示每个支付事件，包含stage字段（deposit或balance）、gateway_reference、amount、status等；创建ReferralPayout模型来记录推荐人分成。这样可以将支付阶段明确建模，避免使用单一的paid标志。
如何安全地完成支付最终化，避免重复处理？
在服务层函数中使用transaction.atomic()和select_for_update()来锁定支付记录，确保并发安全。在函数内部先检查支付状态，如果已经是succeeded则直接返回，避免重复处理。然后更新支付状态和Journey的相关字段，并在满足条件时创建推荐人分成记录。
如何处理支付网关的webhook以确保幂等性？
webhook处理函数应该保持简单，只负责解析payload、查找对应的Payment记录，并调用服务层的finalize_payment函数。由于finalize_payment内部有状态检查和行锁，即使webhook重复发送，也不会重复处理。此外，对于未知事件类型或缺少reference的请求，应返回适当的响应。
在分阶段支付中，如何应用优惠券和推荐人分成？
优惠券和推荐人分成需要按阶段明确处理。可以创建DiscountCode模型，包含applies_to字段（deposit、balance或both），在计算折扣时检查当前阶段是否适用。推荐人分成应显式记录，在支付最终化时，如果满足条件（如余额付清），则创建ReferralPayout记录，金额基于净支付额。
为什么推荐人分成应该显式记录，而不是自动处理？
因为支付接收、优惠券应用、推荐人记入和推荐人支付是不同的事件。显式记录推荐人分成可以确保只有在业务规则允许时才创建支付记录，例如在余额付清后才创建，避免过早支付。这样可以防止客户未完成全部支付时推荐人就被支付。
在分阶段支付中，何时解锁交付物？
交付物应该在全部款项付清后才解锁，即deposit_paid和balance_paid都为True时。可以通过Journey模型的update_delivery_state方法设置deliverables_released为True。这样可以避免过早解锁带来的运营和信任问题。
分阶段支付系统常见的错误有哪些？
常见错误包括：使用单一的paid标志、让webhook直接写多个表、忘记幂等性、不检查阶段就应用优惠券、过早释放交付物。这些错误会导致重复支付、数据不一致和业务逻辑混乱。
