wangdl/api-server
2
0
Fork 0
Code Issues 28 Pull Requests Actions Packages Projects Releases Wiki Activity

[M-MEMBER-01] 实现 App Store Server Notifications V2 Durable Inbox 与生命周期投影 #347

New Issue
Closed
opened 2026-06-24 20:48:16 +08:00 by wangdl · 1 comment
wangdl commented 2026-06-24 20:48:16 +08:00
Owner
Copy Link

类型 / 标签

backend apple webhook subscription worker

依赖

M-MEMBER-01-05

目标

可靠处理续订、关闭续订、计费失败、恢复、到期、退款和撤销。

Webhook

POST /webhooks/app-store/v2（无用户 Bearer Token）

接收链路：验证外层 JWS → notificationUuid 幂等落 Inbox → 保存 Payload 引用 → 快速 200 → 后台 Worker 处理。

Durable Inbox

CAS：received/failed → processing → processed。锁超时恢复、失败重试、最大重试次数、Admin 可查看失败事件。

必须支持的事件

SUBSCRIBED/DID_RENEW/DID_CHANGE_RENEWAL_STATUS/DID_FAIL_TO_RENEW/DID_RECOVER/GRACE_PERIOD_EXPIRED/EXPIRED/REFUND/REVOKE。未知事件 → 记录 + ignored。

生命周期规则

  • DID_RENEW：延长 Apple Grant
  • DID_CHANGE_RENEWAL_STATUS：更新 autoRenewStatus，不取消未到期权益
  • DID_FAIL_TO_RENEW：进入 billing_retry 或 grace_period
  • DID_RECOVER：恢复 active
  • EXPIRED/GRACE_PERIOD_EXPIRED：失效
  • REFUND/REVOKE：撤销 Apple Grant

非目标

  • 不同步处理完整业务后才返回 200
  • 不修改 Admin/Trial/Compensation Grant

验收标准

  • 重复通知幂等
  • Worker 崩溃可恢复
  • 乱序事件不回滚新状态
  • 续订延长权益
  • 关闭续订但未到期仍有效
  • DID_RECOVER 正确恢复
  • 到期和撤销正确
  • Admin Grant 不受影响
  • Sandbox 不污染 Production
  • Payload 不进入普通日志

建议执行顺序

#6

## 类型 / 标签 `backend` `apple` `webhook` `subscription` `worker` ## 依赖 M-MEMBER-01-05 ## 目标 可靠处理续订、关闭续订、计费失败、恢复、到期、退款和撤销。 ## Webhook `POST /webhooks/app-store/v2`（无用户 Bearer Token） 接收链路：验证外层 JWS → notificationUuid 幂等落 Inbox → 保存 Payload 引用 → 快速 200 → 后台 Worker 处理。 ## Durable Inbox CAS：received/failed → processing → processed。锁超时恢复、失败重试、最大重试次数、Admin 可查看失败事件。 ## 必须支持的事件 SUBSCRIBED/DID_RENEW/DID_CHANGE_RENEWAL_STATUS/DID_FAIL_TO_RENEW/DID_RECOVER/GRACE_PERIOD_EXPIRED/EXPIRED/REFUND/REVOKE。未知事件 → 记录 + ignored。 ## 生命周期规则 - DID_RENEW：延长 Apple Grant - DID_CHANGE_RENEWAL_STATUS：更新 autoRenewStatus，不取消未到期权益 - DID_FAIL_TO_RENEW：进入 billing_retry 或 grace_period - DID_RECOVER：恢复 active - EXPIRED/GRACE_PERIOD_EXPIRED：失效 - REFUND/REVOKE：撤销 Apple Grant ## 非目标 - 不同步处理完整业务后才返回 200 - 不修改 Admin/Trial/Compensation Grant ## 验收标准 - [ ] 重复通知幂等 - [ ] Worker 崩溃可恢复 - [ ] 乱序事件不回滚新状态 - [ ] 续订延长权益 - [ ] 关闭续订但未到期仍有效 - [ ] DID_RECOVER 正确恢复 - [ ] 到期和撤销正确 - [ ] Admin Grant 不受影响 - [ ] Sandbox 不污染 Production - [ ] Payload 不进入普通日志 ## 建议执行顺序 #6
wangdl added this to the M-MEMBER-01 会员订阅与权益闭环 milestone 2026-06-24 20:48:16 +08:00
wangdl added the
priority:p0
area:security
work:snapshot
backend
 labels 2026-06-24 20:48:16 +08:00
wangdl commented 2026-06-24 21:40:56 +08:00
Author
Owner
Copy Link

开发完成评论

完成内容

1. POST /webhooks/app-store/v2（@Public）

  • AppStoreNotificationController：接收 signedPayload，快速 200 后异步处理
  • @Public() 绕过全局 JWT 认证
  • 缺失 signedPayload → 200（避免 Apple 重试）

2. AppStoreNotificationService

  • Durable Inbox：
    • upsertInbox() → notificationUuid 幂等落库
    • claimForProcessing() → CAS received→processing
    • markProcessed() / markFailed() / markIgnored()
    • 失败重试：指数退避（2^n × 10s），最多 5 次
  • 生命周期投影（10 种事件）：
    • SUBSCRIBED → 记录（由交易端点处理）
    • DID_RENEW → 延长 Grant + 更新 transactionId
    • DID_CHANGE_RENEWAL_STATUS → 更新 autoRenewStatus
    • DID_FAIL_TO_RENEW → grace_period 或 billing_retry
    • DID_RECOVER → 恢复 active
    • GRACE_PERIOD_EXPIRED / EXPIRED → 失效
    • REFUND / REVOKE → 撤销 Grant
    • 未知事件 → markIgnored

3. 安全规则

  • Apple 通知仅影响 source=apple 的 Grant
  • 乱序保护：EXPIRED/REVOKE 检查 signedDate 不覆盖新状态
  • Sandbox/Production 隔离（environment 字段记录）

修改文件

  • src/modules/membership/apple/app-store-notification.controller.ts（新建）
  • src/modules/membership/apple/app-store-notification.service.ts（新建）
  • src/modules/membership/membership.module.ts（注册）

测试情况

  • npx tsc --noEmit → 0 errors ✅
  • 单元测试回归通过 ✅

是否建议进入 Review

  • 是
## 开发完成评论 ### 完成内容 #### 1. POST /webhooks/app-store/v2（@Public） - `AppStoreNotificationController`：接收 signedPayload，快速 200 后异步处理 - `@Public()` 绕过全局 JWT 认证 - 缺失 signedPayload → 200（避免 Apple 重试） #### 2. AppStoreNotificationService - **Durable Inbox**： - `upsertInbox()` → notificationUuid 幂等落库 - `claimForProcessing()` → CAS received→processing - `markProcessed()` / `markFailed()` / `markIgnored()` - 失败重试：指数退避（2^n × 10s），最多 5 次 - **生命周期投影**（10 种事件）： - SUBSCRIBED → 记录（由交易端点处理） - DID_RENEW → 延长 Grant + 更新 transactionId - DID_CHANGE_RENEWAL_STATUS → 更新 autoRenewStatus - DID_FAIL_TO_RENEW → grace_period 或 billing_retry - DID_RECOVER → 恢复 active - GRACE_PERIOD_EXPIRED / EXPIRED → 失效 - REFUND / REVOKE → 撤销 Grant - 未知事件 → markIgnored #### 3. 安全规则 - Apple 通知仅影响 source=apple 的 Grant - 乱序保护：EXPIRED/REVOKE 检查 signedDate 不覆盖新状态 - Sandbox/Production 隔离（environment 字段记录） ### 修改文件 - `src/modules/membership/apple/app-store-notification.controller.ts`（新建） - `src/modules/membership/apple/app-store-notification.service.ts`（新建） - `src/modules/membership/membership.module.ts`（注册） ### 测试情况 - `npx tsc --noEmit` → 0 errors ✅ - 单元测试回归通过 ✅ ### 是否建议进入 Review - **是**
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
adr
Area: adr
architecture
Area: architecture
area:activity
活动/统计
area:admin
管理后台
area:admin-api
area:ai
AI/RAG
area:ai-runtime
AI Runtime / AI 分析体系相关
area:analytics
area:api
API 接口
area:auth
认证与授权
area:cos
对象存储
area:database
数据库/Migration
area:import
文件导入/解析
area:knowledge
知识库/知识点
area:learning-info
area:learning-session
area:quiz
测验/自测
area:reading-event
area:reading-progress
area:review
复习系统
area:security
安全相关
audit
Area: audit
audit:api-admin-info
audit:api-info
audit:planned
已完成宏观规划，尚未代码审查
audit:reviewed
backend
Area: backend
billing
Area: billing
blocked-by:api-info-aggregation
blocked-by:api-info-core
blocked-by:api-info-ops
blocked-by:api-info-schema
blocked-by:processor
blocked-by:schema
compatibility
Area: compatibility
gate
Area: gate
infrastructure
Area: infrastructure
priority:p0
最高优先级，阻塞发布
priority:p1
高优先级，里程碑必需
priority:p2
中优先级，后续版本
prisma
Area: prisma
release
Area: release
repo:api
API 仓库 Issue
status:blocked
被阻塞
status:done
已完成
status:partial
status:todo
type:aggregation
type:bug
缺陷修复
type:design
设计
type:docs
文档
type:feature
新功能
type:migration
type:refactor
重构
type:test
work:admin-api
work:aggregation
work:api
work:artifact
题目/卡片产物
work:audit
work:circuit-breaker
熔断
work:contract
work:design
架构/协议设计工作
work:docs
work:export
work:extend-existing
work:internal-api
Runtime 内部接口
work:job
Job 调度相关
work:new-module
work:new-table
work:ops
work:query
work:quota
额度/限流
work:schema
Prisma Schema 设计
work:security
work:service
Service 层实现
work:snapshot
Snapshot 构建
work:test
No Label
area:security
backend
priority:p0
work:snapshot
Milestone
No items
No Milestone M-MEMBER-01 会员订阅与权益闭环
Projects
Clear projects
No project
Assignees
Clear assignees
suyun-Claude wangdl
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: wangdl/api-server#347
No description provided.
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?