148 lines
7.6 KiB
Markdown
148 lines
7.6 KiB
Markdown
# 会员插件 `larablog/membership`
|
||
|
||
## 状态
|
||
- 状态：已定稿
|
||
- 创建：2026-08-12 03:25
|
||
- 最近更新：2026-08-12 03:45
|
||
|
||
## 背景
|
||
- 支付基建 `larablog/payment` 与内容付费 `larablog/paid-content` 已闭环（Stub 下单 → 权益 → `article.access`）。
|
||
- `ProductType::MEMBERSHIP` 已预留；membership 插件仍是侧栏 + `/plugins/membership/status` 骨架。
|
||
- Spatie 角色 `member` = 注册用户，**不能**当作付费会员。
|
||
|
||
## 目标
|
||
1. 可配置会员套餐（价格 / 时长）。
|
||
2. 登录用户经 Stub 支付订阅，写入 `entitlements`（`product_type=membership`）。
|
||
3. 文章可标「会员可见」；未开通则试读 + 订阅 CTA（复用 paywall 体验）。
|
||
4. 资料页 / status API 展示当前会员状态。
|
||
|
||
## 范围
|
||
|
||
### In scope（v1）
|
||
1. 插件表 `membership_plans`：slug、name、description、price、currency、duration_days（nullable=终身）、enabled、sort_order。
|
||
2. 插件内幂等 Seeder：月度 / 终身各一档（`updateOrCreate` by slug）；不写死进核心 `DatabaseSeeder`。
|
||
3. `requires: ["larablog/payment"]`；依赖未满足不可启用。
|
||
4. Filament：套餐 CRUD（插件内 Resource）；核心 `MembershipPluginPage::shouldRegisterNavigation` **恒 false**（v1 起骨架页永久隐藏，导航只由插件 Resource 提供；区别于「enabled 才显示」的旧骨架行为）。
|
||
5. 支付结账（见「结账安全」）：membership **仅**服务端按 plan 取价；query 兜底路径**拒绝** `membership`。
|
||
6. 权益与过期（见「过期语义」）：`expires_at` 加在 payment 的 `entitlements`；活跃判定三处统一。
|
||
7. 文章闸：`article_membership`；表单注入；`article.access` → `need_purchase`（未登录也给订阅 CTA）。
|
||
8. 三向互斥：会员闸 / 密码 / 单篇付费（见「互斥机制」）。
|
||
9. 前台：`/plugins/membership` 套餐列表；资料页会员状态；status JSON：`active`、`plan_id`、`plan_slug`、`plan_name`、`expires_at`。
|
||
10. `OrderService::hasActiveAny($userId, $productType)`：任意有效 membership 权益。
|
||
11. 文档 + PHPUnit（含 PaidContentCommerceTest 回归）。
|
||
|
||
### Out of scope
|
||
- 真实微信/支付宝续费扣款、自动续费、退款流程。
|
||
- 多套餐叠加的复杂权益栈（v1：指定 plan 闸只认该 plan；「任意会员」闸认任一有效 membership）。
|
||
- 用 Spatie role 表示付费会员。
|
||
- 主题市场 / 会员专属主题。
|
||
- 优惠券、试用期、邀请码、外部文生图。
|
||
|
||
## 方案要点
|
||
|
||
### 分层
|
||
```text
|
||
Core ArticleAccess + Hook（已有）
|
||
↑
|
||
larablog/payment（订单 / Stub / entitlements[+expires_at]）
|
||
↑
|
||
larablog/membership（plans + 文章会员闸 + 订阅页）
|
||
```
|
||
|
||
### 过期语义（固化 · 原 B1）
|
||
payment 核心修改（影响面声明：article 权益 `expires_at` 恒 null，语义不变；须跑 PaidContentCommerceTest 回归）：
|
||
|
||
1. 迁移：`entitlements.expires_at` nullable timestamp。
|
||
2. **活跃**定义统一为：`revoked_at IS NULL AND (expires_at IS NULL OR expires_at > now())`，用于：
|
||
- `OrderService::hasEntitlement`
|
||
- `OrderService::markPaid` 的 `ownedElsewhere` 守卫
|
||
- `Entitlement::scopeActive` / `isActive()`
|
||
3. 过期后可重新 `createOrder` + `markPaid`（续订）；`updateOrCreate` 同键刷新 `granted_at` / `expires_at` / `source_order_id`。
|
||
4. membership 监听 `order.paid`：对 membership item，读 plan：
|
||
- `duration_days` 有值 → `expires_at = now()->addDays(duration_days)`
|
||
- 终身 → `expires_at = null`
|
||
- plan 已删：**fail-closed**——不授予/撤销本次写入并打日志（避免月度变终身）；Stub 支付页提示失败。（实现可用：markPaid 前后校验 plan 存在；或 paid 后若 plan 缺失则 `revoked_at=now()` 并通知。）
|
||
|
||
### 结账安全（固化 · 原 B3）
|
||
`resolveCheckoutProduct`：
|
||
1. `article`：保持现逻辑（visible+published + enabled product）。
|
||
2. `membership`：`class_exists` plan model + 表存在 + plan `enabled` → 返回 `[name, price, currency]`；否则 `invalid_checkout`。
|
||
3. **其它/未知类型**：直接 `invalid_checkout`（**删除**信任 query `title/amount` 的兜底，堵住伪造 membership）。theme 售卖以后再加专用分支。
|
||
|
||
### 互斥机制（固化 · 原 B2）
|
||
新增核心约定扩展点（一次 filter，多方可见）：
|
||
|
||
| 点 | 类型 | 用途 |
|
||
|---|---|---|
|
||
| `filament.article.validate_access_restrictions` | filter | `(array $data, ?Article $record): array`；在 strip 插件私有键**之前**调用；抛 `ValidationException` |
|
||
|
||
调用顺序（Create/Edit）：
|
||
1. `mutate_before_save`（可填充/规范插件字段，**不得**在此 unset 限制字段）
|
||
2. `validate_access_restrictions`（paid-content + membership 均在此检查互斥）
|
||
3. 各插件在 `after_save` 落库；`mutate_before_save` 末尾或独立 strip 阶段再去掉 `paid_content` / `membership` 私有键（或 after_save 只读 form state）
|
||
|
||
互斥规则：下列至多一个为真——
|
||
- `filled(read_password)`
|
||
- `paid_content.enabled`
|
||
- `membership.enabled`
|
||
|
||
paid-content 现有「在 mutate_before_save unset」改为：校验点之后再 strip（改动 paid-content provider）。
|
||
|
||
### Plan 删除（固化 · 原 B4）
|
||
- `article_membership.required_plan_id` → **`restrictOnDelete`**（有文章仍引用则不可删 plan）。
|
||
- 后台删除 plan：若仍有未过期 entitlement，拒绝删除并提示（或仅允许 `enabled=false`）；v1 实现：**有任何 entitlement 行则禁止硬删，引导禁用**。
|
||
|
||
### 数据模型
|
||
|
||
#### `membership_plans`
|
||
| 字段 | 说明 |
|
||
|---|---|
|
||
| id | PK |
|
||
| slug | unique |
|
||
| name | 展示名 |
|
||
| description | nullable |
|
||
| price | decimal(10,2) |
|
||
| currency | default CNY |
|
||
| duration_days | unsignedInt nullable；null=终身 |
|
||
| enabled | bool |
|
||
| sort_order | int default 0 |
|
||
| timestamps | |
|
||
|
||
#### `article_membership`
|
||
| 字段 | 说明 |
|
||
|---|---|
|
||
| article_id | unique FK → articles cascadeOnDelete |
|
||
| enabled | bool |
|
||
| required_plan_id | nullable FK → membership_plans **restrictOnDelete**；null=任意有效会员 |
|
||
| timestamps | |
|
||
|
||
### 文章闸 CTA
|
||
- checkout 指向：`required_plan_id` 对应 enabled plan；若 plan 禁用/缺失 → 降级为「最低价 enabled 套餐」；若无任何套餐 → 无购买按钮，仅提示联系管理员。
|
||
- 试读：复用 `HtmlTeaser` / description（与 paid-content 同量级默认 chars）。
|
||
|
||
### 插件生命周期
|
||
- 启用前须 payment 已启用；迁移：`php artisan migrate`（AppServiceProvider 已 load 全部插件 migrations）。
|
||
- 禁用后：钩子不注册 → 会员文变公开；DB 行保留。
|
||
|
||
## 验收标准
|
||
- [ ] 未启用 membership：行为与现网一致；骨架导航不出现。
|
||
- [ ] 无 payment 时启用 membership → 拒绝。
|
||
- [ ] Stub 订阅后 status/资料页显示有效会员；有期限套餐可过期后续订。
|
||
- [ ] 会员文：未购试读+订阅；订阅后全文；指定 plan 闸不接受其它 plan。
|
||
- [ ] 伪造 `product_type=membership&amount=0.01` → 422。
|
||
- [ ] 三向互斥保存失败。
|
||
- [ ] 被文章引用或仍有权益的 plan 不可硬删。
|
||
- [ ] PaidContentCommerceTest + 新 Membership 测试全绿。
|
||
|
||
## 已拍板（原开放问题）
|
||
- [x] 做 `expires_at`（支持月度）
|
||
- [x] 未购统一 `need_purchase`（与 paid-content 一致）
|
||
- [x] 禁用插件后会员文变公开
|
||
|
||
## 变更记录
|
||
| 时间 | 原因 | 变更 |
|
||
|------|------|------|
|
||
| 2026-08-12 03:25 | 启动会员功能 | 初稿 |
|
||
| 2026-08-12 03:30 | qodercli SPEC review B1–B4 | 固化过期三处一致、互斥校验点、结账拒伪造、plan restrictOnDelete；补 hasActiveAny / 骨架导航 / fail-closed |
|
||
| 2026-08-12 03:45 | 用户确认「定」 | 状态改为已定稿；配套 CHECKLIST / TESTPLAN |
|