hi-server/.trae/documents/APP_PC 报错日志收集接口与表设计.md

目标

• 不使用自动续期订阅；采用“非续期订阅”或“非消耗型”作为内购模式。

• 仅实现 Go 后端 API；客户端（iOS/StoreKit 2）按说明调用。

产品模型

• 非续期订阅：固定时长通行证（如 30/90/365 天），产品ID：com.airport.vpn.pass.30d|90d|365d。

• 非消耗型（可选）：一次性解锁某附加功能，产品ID：com.airport.vpn.addon.xyz。

• 服务器以 productId→权益/时长 进行配置映射。

后端API设计（Go/Gin）

• 路由注册：internal/handler/routes.go

  • GET /api/iap/apple/products：返回前端展示的产品清单（含总价/描述/时长映射）

  • POST /api/iap/apple/transactions/attach：绑定一次购买到用户账户（需登录）。入参：signedTransactionJWS

  • POST /api/iap/apple/restore：恢复购买（批量接收 JWS 列表并绑定）

  • GET /api/iap/apple/status：返回用户当前权益与到期时间（统一来源聚合）

• 逻辑目录：internal/logic/iap/apple/*

  • AttachTransactionLogic：解析 JWS→校验 bundleId/productId/purchaseDate→根据 productId 映射权益与时长→更新订阅统一表

  • RestoreLogic：对所有已购记录执行绑定去重（基于 original_transaction_id）

  • QueryStatusLogic：聚合各来源订阅，返回有效权益（取最近到期/最高等级）

• 工具包：pkg/iap/apple

  • ParseTransactionJWS：解析 JWS，提取 transactionId/originalTransactionId/productId/purchaseDate/revocationDate

  • VerifyBasic：基础校验（bundleId、签名头部与证书链存在性）；如客户端已 transaction.verify()，可采用“信任+服务器最小校验”的模式快速落地

• 配置：doc/config-zh.md

  • IAP_PRODUCT_MAP：productId → tier/duration（例如：30d→+30天、addon→解锁功能X）

  • APPLE_IAP_BUNDLE_ID：用于 JWS 内部校验

数据模型

• 新表：apple_iap_transactions

  • id、user_id、original_transaction_id（唯一）、transaction_id、product_id、purchase_at、revocation_at、jws_hash

• 统一订阅表增强（现有 SubscribeModel）

  • 新增来源：source=apple_iap、external_id=original_transaction_id、tier、expires_at

• 索引：original_transaction_id 唯一、user_id+source、expires_at

与现有系统融合

• internal/svc/serviceContext.go：初始化 IAP 模块与模型

• QueryPurchaseOrderLogic/SubscribeModel：聚合苹果IAP来源；冲突策略：按最高权益与最晚到期。

• 不产生命令行支付订单，仅记录订阅流水与审计（避免与 Stripe 等混淆）。

安全与合规

• 仅显示商店在可支付时；价格、描述清晰；使用系统确认表单。

• 服务器进行最小校验：bundleId、productId白名单、purchaseDate有效性；保存 jws_hash 做去重。

• 退款：在 App 内提供“请求退款”的帮助页并使用系统接口触发；后端无需额外API。

客户端使用说明（StoreKit 2）

• 产品拉取与展示：

  • 通过已知 productId 列表调用 Product.products(for:)；展示总价与描述，检查 canMakePayments

• 购买：

  • 调用 purchase()，系统确认表单弹出→返回 Transaction；执行 await transaction.verify()

  • 成功后将 transaction.signedData POST 到 /api/iap/apple/transactions/attach

• 恢复：

  • 调用 Transaction.currentEntitlements，遍历并验证每条 Transaction，将其 signedData 批量 POST 到 /api/iap/apple/restore

• 状态显示：

  • 访问 GET /api/iap/apple/status 获取到期时间与权益用于 UI 展示

• 退款入口：

  • 在购买帮助页直接使用 beginRefundRequest(for:in:)；文案简洁，按钮直达

测试与验收

• 单元测试：JWS 解析、productId→权益/时长 映射、去重策略。

• 集成测试：绑定/恢复接口鉴权与幂等、统一订阅查询结果。

• 沙盒：使用 iOS 沙盒购买与恢复；记录审计与日志。

里程碑

1. 基础能力：products/status 与 transactions/attach 落地
2. 恢复与融合：restore + 统一订阅聚合
3. 上线前验证：沙盒测试与文案、监控