邹方成
45815bfb7d
refactor(utils): 修复密码哈希比较逻辑错误 feat(user): 新增按状态筛选优惠券接口 docs: 添加虚拟发货与任务中心相关文档 fix(wechat): 修正Code2Session上下文传递问题 test: 补充订单折扣与积分转换测试用例 build: 更新配置文件与构建脚本 style: 清理多余的空行与注释
75 lines
5.1 KiB
Markdown
75 lines
5.1 KiB
Markdown
## 背景与目标
|
||
- 目标：在用户支付成功后（微信回调），为“虚拟商品”接入微信小程序发货信息管理服务，完成发货信息录入、用户确认收货提醒/组件、状态查询与对账闭环，确保资金结算合规。
|
||
- 项目现状：
|
||
- 微信支付回调入口 `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工作流”与用户文档规范同步进度与决策。
|