bindbox-game/.trae/documents/虚拟发货-微信回调与发货信息管理设计.md

背景与目标

• 目标：在用户支付成功后（微信回调），为“虚拟商品”接入微信小程序发货信息管理服务，完成发货信息录入、用户确认收货提醒/组件、状态查询与对账闭环，确保资金结算合规。
• 项目现状：
  • 微信支付回调入口 internal/router/router.go:288 → internal/api/pay/wechat_notify.go:31 已实现验签与订单入账。
  • 小程序预下单 internal/api/user/pay_wechat_app.go:30、AccessToken 缓存 internal/pkg/wechat/qrcode.go:80 可复用。

端到端流程

1. 支付成功（微信平台通知）
   • 在 WechatNotify 完成验签与落库后，判断订单为虚拟商品，执行“虚拟发货”逻辑。
2. 生成虚拟权益/兑现
   • 发放对应的虚拟权益（如游戏币、道具、资格），落库并与订单关联，保证可追溯与幂等。
3. 录入发货信息（虚拟）到平台
   • 通过小程序 AccessToken，调用“发货信息录入接口”，logistics_type=3(虚拟商品)，delivery_mode=UNIFIED_DELIVERY，shipping_list.item_desc 填商品描述。
   • order_key.order_number_type=2，使用微信支付 transaction_id 精确关联一笔支付单；或回退为 mchid+out_trade_no。
   • upload_time 用 RFC3339，严格保证“更新”时间递增与“只允许一次重新发货”约束。
4. 用户确认收货
   • 配置消息跳转路径，使平台消息点入小程序指定页面（例如 pages/order/detail）。
   • 可在小程序内接入“确认收货组件”并在后端暴露确认记录接口，统一订单态与权益态。
5. 状态查询与运营
   • 提供查询订单发货状态（平台/本地）与订单列表；管理端支持重试/人工标记与报表。
6. 结算与对账
   • 依据平台规则：仅在完成录入与确认收货后进入结算；与本地 Payment* 表对账。

接口与数据映射

• 发货信息录入（虚拟）：
  • access_token: 复用 GetAccessToken internal/pkg/wechat/qrcode.go:80。
  • order_key.order_number_type=2：transaction_id 来源于微信通知解密结果（落库于 PaymentTransactions）。
  • logistics_type=3（虚拟），delivery_mode=UNIFIED_DELIVERY，shipping_list=[{ item_desc }]；不填 tracking_no/express_company。
  • upload_time: RFC3339，保证更新序与重试策略。
• 路由/回调：
  • POST /api/pay/wechat/notify internal/router/router.go:288 → internal/api/pay/wechat_notify.go:31。
• 本地数据表：
  • 支付：PaymentTransactions/PaymentNotifyEvents/PaymentPreorders（见 internal/repository/mysql/dao/*.gen.go）。
  • 发货记录与统计：shipping_records、ops_shipping_stats（见 internal/repository/mysql/model/*.gen.go）。

关键实现点

• 新增发货服务封装（小程序）
  • 封装 POST https://api.weixin.qq.com/.../order-shipping 录入接口（遵循当前 resty 客户端与错误风格）。
  • 暴露：UploadVirtualShipping(transactionID string, itemDesc string, uploadTime time.Time)；可扩展提醒接口、消息跳转路径设置接口。
• 回调内触发
  • 在 WechatNotify 成功落库后、且订单类型为虚拟商品时触发发货录入；保证幂等（以 transaction_id + 请求体哈希作为一次性幂等键）。
• 小程序端确认组件
  • 在指定页面集成确认组件；后端记录确认事件并回写订单状态。
• 管理端支持与观测
  • 手动重试、失败列表、统计报表（复用 ops_shipping_stats 流水）；结构化日志与告警。

幂等与错误处理

• 幂等：
  • 回调侧：保持现有幂等（订单已支付直接 ACK）。
  • 发货录入：transaction_id 唯一，一次成功后锁定；如需“重新发货”，严格遵循平台“最多一次”的约束并记录。
• 重试：
  • 网络/平台 5xx → 指数退避重试；4xx → 不重试，人工处理。
• 观测：
  • 统一结构化日志；Prometheus 指标与告警；事件表留痕（类似 PaymentNotifyEvents）。

权限与安全

• 凭证：使用小程序 access_token，全局缓存与自动续期；严禁日志打印敏感信息。
• 配置：.env 管理 AppID/AppSecret/MchID/证书；统一加载到 configs。

验收标准

• 回调成功后，虚拟权益发放与本地订单状态均为一致且幂等。
• 向平台成功录入虚拟发货信息，可查询到订单发货状态。
• 用户可在小程序完成确认收货（消息跳转路径与组件可用），结算流程正常。
• 管理端可查看与重试失败案例，日志与告警有效。

任务拆分

1. 新增“微信发货信息管理（小程序）”SDK封装（虚拟场景优先）。
2. 在 WechatNotify 中接入虚拟发货录入（含幂等与重试）。
3. 小程序端接入确认收货组件与指定跳转页。
4. 管理端新增发货失败重试与统计报表。
5. 测试：单元（参数映射/幂等/错误）、集成（沙箱或模拟）、文档与验收。

文档与规范

• 创建 docs/虚拟发货/ALIGNMENT_虚拟发货.md、CONSENSUS_虚拟发货.md、DESIGN_虚拟发货.md、TASK_虚拟发货.md，按项目“6A工作流”与用户文档规范同步进度与决策。