交易系统全景说明（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
- Product：
- 业务层（Business Services）
- Product：
ProductLicenseService,ProductLicenseFileService - WorkTask：
WorkTaskCompletionService
- Product：
- 结算与钱包层（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 详化）
7. 边界与异常（重点）
- 渠道限制：Alipay 仅 CNY；非 CNY 必须有 Stripe 账户
- 零元支付：钱包全额抵扣走
confirm_zero - 支付会话过期：Stripe/Alipay 过期后自动取消订单并回滚库存/钱包
- 库存一致性：下单锁定库存，取消回滚
- 文件访问：只允许 Paid 的许可证访问购买后文件版本
- 退款链路：目前仅支持未支付订单取消和钱包抵扣退款（无外部退款链路）
8. 遗留链路与迁移建议（下一步 #3）
8.1 遗留链路
ProductPurchaseService仍存在但未在新支付链路中使用ProductOrder+StripeController::createProductCheckoutSession为旧模式
8.2 风险
- 多套“购买模型”并存导致订单取消、结算、文件权限不一致
- 老链路可能绕过
OrderService的统一处理
8.3 迁移建议
- 冻结旧入口：将旧的 ProductOrder/Payment API 标记为 deprecated
- 统一入口：全部切换至
ProductPaymentService + ProductLicense - 数据迁移：将旧
ProductPurchase/ProductOrder映射为ProductLicense + Order - 统一订单状态：保证 Order 都走
OrderService处理 - 清理与删减：确认无调用后移除旧服务/路由
9. 进一步落地（下一步 #2 细化图）
可继续输出的扩展图：
- Stripe 结算细粒度费用拆分（application_fee / stripe_fee / plat_fee）
- WalletDeductionRecord 在结算时的状态转移
- WorkTask price_change 触发路径与阶段刷新
如需我继续补充上述扩展图或测试建议，请告知。