## 背景与目标
- 目标：在用户支付成功后（微信回调），为“虚拟商品”接入微信小程序发货信息管理服务，完成发货信息录入、用户确认收货提醒/组件、状态查询与对账闭环，确保资金结算合规。
- 项目现状：
  - 微信支付回调入口 `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工作流”与用户文档规范同步进度与决策。
