shanshanzhong
d95911d6bd
Some checks failed
Build docker and publish / build (20.15.1) (push) Has been cancelled
实现Apple应用内购支付功能，包括： 1. 新增AppleIAP和ApplePay支付平台枚举 2. 添加IAP验证接口/v1/public/iap/verify处理初购验证 3. 实现Apple服务器通知处理逻辑/v1/iap/notifications 4. 新增JWS验签和JWKS公钥缓存功能 5. 复用现有订单系统处理IAP支付订单 相关文档已更新，包含接入方案和实现细节
93 lines
3.7 KiB
Markdown
93 lines
3.7 KiB
Markdown
## 结论
|
||
|
||
* 可以复用你现有的“订单→支付成功→订单激活（赋权）→通知/返佣”的主干流程，但“支付环节”不能复用第三方网关逻辑，必须改为 Apple IAP 的校验与事件驱动。
|
||
|
||
* 复用范围：订单模型、续费与赋权队列、优惠/手续费计算、通知与返佣；差异点：支付下单与回调换成“StoreKit 客户端购买 + 服务端向 Apple 校验 + Apple Server Notifications v2”。
|
||
|
||
## 可复用的部分
|
||
|
||
1. 订单激活与赋权
|
||
|
||
* 新购赋权：`queue/logic/order/activateOrderLogic.go:164-193` 的 `NewPurchase`
|
||
|
||
* 续费赋权：`queue/logic/order/activateOrderLogic.go:473-515` 的 `Renewal`
|
||
|
||
* 流量重置与充值：`queue/logic/order/activateOrderLogic.go:564-626`, `630-675`
|
||
|
||
1. 订单与费用模型
|
||
|
||
* 订单结构：`internal/model/order/order.go:5-29` 可继续承载 IAP 订单（新增字段映射 Apple 交易）
|
||
|
||
* 费用/折扣/礼金计算逻辑保持不变
|
||
|
||
1. 队列驱动
|
||
|
||
* 仍使用“支付成功→入队→处理”的模式：`queue/logic/order/activateOrderLogic.go:65-86`
|
||
|
||
## 必须独立实现的部分
|
||
|
||
1. Apple IAP 支付与校验
|
||
|
||
* 客户端使用 StoreKit 购买，拿到 `originalTransactionId`
|
||
|
||
* 服务端调用 App Store Server API，基于 `originalTransactionId` 校验订阅有效性并取交易历史
|
||
|
||
1. Apple Server Notifications v2
|
||
|
||
* 在 App Store Connect 配置通知 URL
|
||
|
||
* 服务端实现 JWS 验签，解析事件并落库：续期、失败、宽限期、退款、撤销等
|
||
|
||
## 整合方式（复用策略）
|
||
|
||
1. 引入平台枚举“AppleIAP”
|
||
|
||
* 在 `pkg/payment/platform.go` 增加 `AppleIAP`，用于平台标识与管理端展示
|
||
|
||
1. 订单创建策略（两种）
|
||
|
||
* 方案 A（推荐）：用户在 iOS 内购完成后由客户端上报 `originalTransactionId`，服务端校验通过后“合成一个已支付订单”（`status=2`），触发既有赋权队列
|
||
|
||
* 方案 B：也可预建“待支付订单”，但 `PurchaseCheckout` 不走网关，只返回“client\_iap”类型，提示客户端用 StoreKit；支付完成后再校验并更新为 `Paid` 入队
|
||
|
||
1. 状态与权益判定
|
||
|
||
* 服务端统一以 Apple 校验与通知为准，抽象为 `active/in_grace_period/in_billing_retry/expired/revoked` 并映射到你的订阅与订单状态
|
||
|
||
## 服务端接口与流程
|
||
|
||
* `POST /apple/iap/verify`：入参 `originalTransactionId`，校验并创建/更新订单与用户订阅，返回当前权益
|
||
|
||
* `POST /apple/iap/notifications`：接收 Apple JWS 通知，验签后更新订阅与订单状态（幂等）
|
||
|
||
* `GET /subscriptions/me`：面向客户端查询当前订阅与权益（聚合 Apple 校验结果）
|
||
|
||
## 数据模型映射
|
||
|
||
* 在订单/订阅表补充字段（建议）：`Provider=apple_iap`、`OriginalTransactionId`、`Environment`、`ExpiresDate`、`AutoRenewStatus`、`InGracePeriod`、`LastEventType`
|
||
|
||
* 产品映射：`productId（App Store） ↔ internal subscribeId`，保证同一权益统一计费
|
||
|
||
## 回调与安全
|
||
|
||
* JWS 验签：缓存 Apple JWKS 公钥、短生命周期缓存
|
||
|
||
* App Store Server API：使用 App Store Connect API Key（ES256）发起请求，区分生产/沙盒
|
||
|
||
* 幂等：按 `notificationId/transactionId` 去重
|
||
|
||
## 测试与上线
|
||
|
||
* 沙盒测试：购买、续期、失败、宽限期、退款全链路；注意沙盒元数据生效可能需 \~1 小时
|
||
|
||
* 监控：通知处理失败、验签失败、API 调用异常报警
|
||
|
||
## 交付物（最小实现）
|
||
|
||
1. 平台枚举新增 `AppleIAP`
|
||
2. `POST /apple/iap/verify` 与 `POST /apple/iap/notifications` 路由与逻辑骨架
|
||
3. App Store Server API 客户端封装（校验、交易历史、订阅状态）
|
||
4. 订单合成与入队赋权打通（复用 `OrderStatusPaid` → `ProcessTask`）
|
||
5. 数据表字段扩展与迁移脚本
|
||
|