## 结论

* 可以复用你现有的“订单→支付成功→订单激活（赋权）→通知/返佣”的主干流程，但“支付环节”不能复用第三方网关逻辑，必须改为 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. 数据表字段扩展与迁移脚本