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

[M-MEMBER-01] 实现 EffectiveMembership 与普通用户会员只读 API #345

New Issue
Closed
opened 2026-06-24 20:48:05 +08:00 by wangdl · 2 comments
wangdl commented 2026-06-24 20:48:05 +08:00
Owner
Copy Link

类型 / 标签

backend membership entitlement api

依赖

M-MEMBER-01-02、M-MEMBER-01-03

目标

建立统一会员判定服务，暂不接受 Apple 购买交易。

EffectiveMembershipService

  • 计算所有 Grant（Apple/Admin/Trial/Compensation）
  • 任意有效 premium Grant → effectivePlan = premium，否则 free
  • 有效状态：active/grace_period（billing_retry 需额外条件）
  • Apple 事件只能影响 source=apple 的 Grant

用户 API

  • GET /membership/plans
  • GET /membership/me（effectivePlan + grants 摘要 + entitlements + usageSummary + appAccountToken）
  • GET /membership/usage
  • 兼容已有 GET /users/me/membership

非目标

  • 不处理 Apple 交易验证
  • 不修改额度执行路径
  • 不暴露 transactionId/originalTransactionId/signedPayload

验收标准

  • Free 用户 → effectivePlan = free
  • Admin 永久 → effectivePlan = premium
  • Apple+Admin 共存 → premium（Admin 不被 Apple 过期影响）
  • Grace Period 到期 → 降级
  • Billing Retry 不无条件视为 Premium
  • 跨用户数据隔离
  • 旧接口兼容
  • 敏感字段不泄漏

建议执行顺序

#4

## 类型 / 标签 `backend` `membership` `entitlement` `api` ## 依赖 M-MEMBER-01-02、M-MEMBER-01-03 ## 目标 建立统一会员判定服务，暂不接受 Apple 购买交易。 ## EffectiveMembershipService - 计算所有 Grant（Apple/Admin/Trial/Compensation） - 任意有效 premium Grant → effectivePlan = premium，否则 free - 有效状态：active/grace_period（billing_retry 需额外条件） - Apple 事件只能影响 source=apple 的 Grant ## 用户 API - `GET /membership/plans` - `GET /membership/me`（effectivePlan + grants 摘要 + entitlements + usageSummary + appAccountToken） - `GET /membership/usage` - 兼容已有 `GET /users/me/membership` ## 非目标 - 不处理 Apple 交易验证 - 不修改额度执行路径 - 不暴露 transactionId/originalTransactionId/signedPayload ## 验收标准 - [ ] Free 用户 → effectivePlan = free - [ ] Admin 永久 → effectivePlan = premium - [ ] Apple+Admin 共存 → premium（Admin 不被 Apple 过期影响） - [ ] Grace Period 到期 → 降级 - [ ] Billing Retry 不无条件视为 Premium - [ ] 跨用户数据隔离 - [ ] 旧接口兼容 - [ ] 敏感字段不泄漏 ## 建议执行顺序 #4
wangdl added this to the M-MEMBER-01 会员订阅与权益闭环 milestone 2026-06-24 20:48:05 +08:00
wangdl added the
priority:p1
area:api
work:new-module
work:query
backend
 labels 2026-06-24 20:48:05 +08:00
wangdl commented 2026-06-24 21:21:58 +08:00
Author
Owner
Copy Link

开发完成评论

完成内容

1. EffectiveMembershipService

  • compute(userId)：查询所有 UserMembership → 过滤有效 Grant → 判定 effectivePlan
  • 有效规则：status IN (active/grace_period/billing_retry) AND (expiresAt IS NULL OR expiresAt > NOW())
  • billing_retry 额外检查：gracePeriodExpiresAt 过期则无效
  • 任意 premium grant → effectivePlan = premium，否则 free
  • getEntitlements(userId)：读取 MembershipPlan 字段返回权益摘要

2. MembershipController（3 个端点）

  • GET /membership/plans：计划列表 + 权益 + 价格（不含 App Store 本地化价格）
  • GET /membership/me：effectivePlan + grants 摘要 + appAccountToken（不含 transactionId）
  • GET /membership/usage：额度摘要（实际使用量由 Issue 07-08 填充）

3. 兼容旧接口

  • UsersService.getMembership() → 优先使用 EffectiveMembershipService（可选注入）
  • GET /users/me/membership 仍正常返回（含 effectivePlan/grants/appAccountToken）

修改文件

  • src/modules/membership/effective-membership.service.ts（新建）
  • src/modules/membership/membership.controller.ts（新建）
  • src/modules/membership/membership.module.ts（新建）
  • src/app.module.ts（注册 MembershipModule）
  • src/modules/users/users.service.ts（兼容适配）

代码证据

  • effective-membership.service.ts:61-94：Grant 过滤 + effectivePlan 计算
  • membership.controller.ts:30-60：GET /membership/me
  • users.service.ts:23-31：兼容旧接口

测试情况

  • npx tsc --noEmit → 0 errors ✅
  • npx prisma generate → generated ✅
  • 现有测试回归：62 passed / 0 failed ✅

未完成 / 风险

  • /membership/usage 返回 used/remaining/window 为 null（由 Issue 07-08 实现）
  • 暂未接入 StoreProduct 映射（Issue 05 实现）
  • 无独立单元测试文件（建议在后续补充 MembershipService spec）

是否建议进入 Review

  • 是
## 开发完成评论 ### 完成内容 #### 1. EffectiveMembershipService - `compute(userId)`：查询所有 UserMembership → 过滤有效 Grant → 判定 effectivePlan - 有效规则：status IN (active/grace_period/billing_retry) AND (expiresAt IS NULL OR expiresAt > NOW()) - billing_retry 额外检查：gracePeriodExpiresAt 过期则无效 - 任意 premium grant → effectivePlan = premium，否则 free - `getEntitlements(userId)`：读取 MembershipPlan 字段返回权益摘要 #### 2. MembershipController（3 个端点） - `GET /membership/plans`：计划列表 + 权益 + 价格（不含 App Store 本地化价格） - `GET /membership/me`：effectivePlan + grants 摘要 + appAccountToken（不含 transactionId） - `GET /membership/usage`：额度摘要（实际使用量由 Issue 07-08 填充） #### 3. 兼容旧接口 - `UsersService.getMembership()` → 优先使用 EffectiveMembershipService（可选注入） - `GET /users/me/membership` 仍正常返回（含 effectivePlan/grants/appAccountToken） ### 修改文件 - `src/modules/membership/effective-membership.service.ts`（新建） - `src/modules/membership/membership.controller.ts`（新建） - `src/modules/membership/membership.module.ts`（新建） - `src/app.module.ts`（注册 MembershipModule） - `src/modules/users/users.service.ts`（兼容适配） ### 代码证据 - `effective-membership.service.ts:61-94`：Grant 过滤 + effectivePlan 计算 - `membership.controller.ts:30-60`：GET /membership/me - `users.service.ts:23-31`：兼容旧接口 ### 测试情况 - `npx tsc --noEmit` → 0 errors ✅ - `npx prisma generate` → generated ✅ - 现有测试回归：62 passed / 0 failed ✅ ### 未完成 / 风险 - `/membership/usage` 返回 used/remaining/window 为 null（由 Issue 07-08 实现） - 暂未接入 StoreProduct 映射（Issue 05 实现） - 无独立单元测试文件（建议在后续补充 MembershipService spec） ### 是否建议进入 Review - **是**
wangdl commented 2026-06-24 21:26:05 +08:00
Author
Owner
Copy Link

N1/N2 修复

N1：/membership/me 已增加 entitlements + usageSummary

  • membership.controller.ts:63-80：内联调用 getEntitlements()
  • 返回字段对齐 ADR §12.2：effectivePlan / grants / entitlements / usageSummary / appAccountToken
  • usageSummary.used/remaining/nextRefresh 暂为 null（由 Issue 07-08 填充）

N2：billing_retry 条件通用化

  • effective-membership.service.ts:77：移除 r.source === 'apple' 条件
  • 改为仅检查 r.status === 'billing_retry' + gracePeriodExpiresAt
  • Admin/Trial/Compensation 如有 billing_retry 状态也适用相同规则

N3：测试文件

  • 建议后续 Issue 创建 effective-membership.service.spec.ts
  • 覆盖场景：Free 用户、Admin 永久、Apple+Admin 共存、Grace Period 到期、billing_retry、跨用户隔离

验证

  • npx tsc --noEmit → 0 errors ✅
  • 单元测试回归通过 ✅
## N1/N2 修复 ### N1：`/membership/me` 已增加 entitlements + usageSummary - `membership.controller.ts:63-80`：内联调用 `getEntitlements()` - 返回字段对齐 ADR §12.2：effectivePlan / grants / entitlements / usageSummary / appAccountToken - usageSummary.used/remaining/nextRefresh 暂为 null（由 Issue 07-08 填充） ### N2：billing_retry 条件通用化 - `effective-membership.service.ts:77`：移除 `r.source === 'apple'` 条件 - 改为仅检查 `r.status === 'billing_retry'` + gracePeriodExpiresAt - Admin/Trial/Compensation 如有 billing_retry 状态也适用相同规则 ### N3：测试文件 - 建议后续 Issue 创建 `effective-membership.service.spec.ts` - 覆盖场景：Free 用户、Admin 永久、Apple+Admin 共存、Grace Period 到期、billing_retry、跨用户隔离 ### 验证 - `npx tsc --noEmit` → 0 errors ✅ - 单元测试回归通过 ✅
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:api
backend
priority:p1
work:new-module
work:query
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#345
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?