#交易系统全景说明（Transaction System)

面向开发/维护人员的系统级说明，覆盖：分层、关键模型与状态、主链路、边界与异常、回调与定时、遗留链路与迁移建议。

#1. 系统分层（Layered Architecture）

• 入口层（Routes/Controllers）
  • 用户支付：/api/user/pay/*
  • 业务资源：/api/product_licenses/*, /api/work_tasks/*, /api/orders/*
  • 钱包/提现：/api/user/wallets*, /api/user/wallet_withdraws*
  • 内部统计：/api/internal/pending_payout/*
• 支付层（Payment Services）
  • Product：ProductPaymentService
  • WorkTask：WorkTaskPaymentService
  • 钱包抵扣：WalletDeductionService
• 业务层（Business Services）
  • Product：ProductLicenseService, ProductLicenseFileService
  • WorkTask：WorkTaskCompletionService
• 结算与钱包层（Settlement/Wallet）
  • CompletionSettlementService（CNY 与非 CNY 分支）
  • Wallet* 系列服务（提现、转账、交易记录）
• 外部通道与回调（Stripe/Alipay）
  • Stripe webhook + session expired
  • Alipay notify/return
• 定时与清理（Cron/Command）
  • ExpirePaymentSessions 过期会话清理

---

#2. 核心模型与状态（Key Entities & States）

#2.1 Order（支付订单）

• 关键字段：busable_type, busable_id, amount, currency_id, status, out_trade_no, amount_calc_process
• 状态：pending / paying / paid / cancelled
• 与业务绑定：busable_type 依赖 morphMap（product_license, work_task）

#2.2 ProductLicense（产品许可证）

• 关键字段：user_id, artist_id, product_id, product_option_id, price, currency_id, status
• 状态：pending / paying / paid / cancelled / refunded

#2.3 WorkTask + WorkTaskStage + WorkTaskPriceChange

• WorkTask 状态：wait_pay, working, finished, user_canceled 等
• Stage 状态：is_paid + work_status（pending, working, finished）
• PriceChange 状态：pending, wait_pay, paid, rejected, canceled

#2.4 Wallet / WalletTransaction / WalletDeductionRecord

• Wallet usage：deposit(收款/提现), credit(用户抵扣), plat_fee(平台费抵扣)
• Deposit type：alipay, stripe_payout, stripe_deduction
• Deduction status：pending, wallet_deposited, refunded

---

#3. 主链路（User Purchase View）

#3.1 产品购买（ProductLicense）

入口：/api/user/pay/product/* + /api/product_licenses/*

关键规则：

• Alipay 仅支持 CNY；非 CNY 使用 Stripe
• 库存锁定在创建支付会话时完成
• 支付成功后立即结算
• 许可证文件访问只允许 Paid 状态且版本不早于购买快照

#3.2 委托支付（WorkTask）

入口：/api/user/pay/work_task/*

关键规则：

• price_change 与 stage_pay/full_pay 互斥
• 非 CNY 必须有艺术家 Stripe 账户
• WorkTask 的最终结算发生在“全部阶段完成”时

---

#4. 视角拆解（Multi-View）

#4.1 用户视角（购买与支付）

• 预计算（含钱包抵扣与汇率转换）
• 创建支付会话（Stripe/Alipay）
• 零元购确认（钱包全额覆盖）
• 支付成功后获取许可证文件 / WorkTask 阶段推进

#4.2 艺术家视角（收款与结算）

• Product：支付完成即结算
• WorkTask：阶段全部完成后结算
• CNY 通道：结算到 Alipay Deposit Wallet
• 非 CNY：拆分到 Stripe Payout 与 Stripe Deduction

#4.3 平台财务视角（费用与待支付）

• 订单费率与网关费用写入 Order
• 钱包抵扣记录 WalletDeductionRecord 在结算时更新状态
• 内部统计：/api/internal/pending_payout/*

#4.4 通道回调与异常

• Stripe webhook checkout.session.completed → OrderService::processPayment
• Stripe webhook checkout.session.expired → 取消订单
• Alipay notify/return → AlipayWebhookService::processCompleted
• 定时任务 ExpirePaymentSessions → 清理过期会话

---

#5. 结算流程（细化 by Currency）

#5.1 CNY（Alipay）

#5.2 非 CNY（Stripe）

---

#6. API 汇总（下一步 #1 详化）

领域	方法	路径	说明
WorkTask 支付	POST	/api/user/pay/work_task/pre_calc	预计算金额
WorkTask 支付	POST	/api/user/pay/work_task/create_checkout_session	创建支付会话
WorkTask 支付	POST	/api/user/pay/work_task/confirm_zero	零元确认
Product 支付	POST	/api/user/pay/product/pre_calc	预计算金额
Product 支付	POST	/api/user/pay/product/create_checkout_session	创建支付会话
Product 支付	POST	/api/user/pay/product/confirm_zero	零元确认
Product License	POST	/api/product_licenses/list	列表
Product License	POST	/api/product_licenses/info	详情
Product License	POST	/api/product_licenses/continue_payment	继续支付
Product License	POST	/api/product_licenses/cancel	取消
License Files	POST	/api/product_licenses/files/list	文件列表
License Files	POST	/api/product_licenses/files/histories	版本历史
License Files	POST	/api/product_licenses/files/download	下载
WorkTask 业务	POST	/api/work_tasks/confrim_stage_work_status	确认阶段完成
Order	POST	/api/orders/cancel	取消订单
Order	POST	/api/orders/continue	继续支付
Alipay 回调	GET/POST	/api/user/alipay/return /api/user/alipay/notify	支付回调
内部统计	POST	/api/internal/pending_payout/summary	待支付汇总
内部统计	POST	/api/internal/pending_payout/details	待支付明细

---

#7. 边界与异常（重点）

• 渠道限制：Alipay 仅 CNY；非 CNY 必须有 Stripe 账户
• 零元支付：钱包全额抵扣走 confirm_zero
• 支付会话过期：Stripe/Alipay 过期后自动取消订单并回滚库存/钱包
• 库存一致性：下单锁定库存，取消回滚
• 文件访问：只允许 Paid 的许可证访问购买后文件版本
• 退款链路：目前仅支持未支付订单取消和钱包抵扣退款（无外部退款链路）

---

#8. 遗留链路与迁移建议（下一步 #3）

#8.1 遗留链路

• ProductPurchaseService 仍存在但未在新支付链路中使用
• ProductOrder + StripeController::createProductCheckoutSession 为旧模式

#8.2 风险

• 多套“购买模型”并存导致订单取消、结算、文件权限不一致
• 老链路可能绕过 OrderService 的统一处理

#8.3 迁移建议

1. 冻结旧入口：将旧的 ProductOrder/Payment API 标记为 deprecated
2. 统一入口：全部切换至 ProductPaymentService + ProductLicense
3. 数据迁移：将旧 ProductPurchase/ProductOrder 映射为 ProductLicense + Order
4. 统一订单状态：保证 Order 都走 OrderService 处理
5. 清理与删减：确认无调用后移除旧服务/路由

---

#9. 进一步落地（下一步 #2 细化图）

可继续输出的扩展图：

• Stripe 结算细粒度费用拆分（application_fee / stripe_fee / plat_fee）
• WalletDeductionRecord 在结算时的状态转移
• WorkTask price_change 触发路径与阶段刷新

如需我继续补充上述扩展图或测试建议，请告知。