Herald

在 Entitlement Mapping 上配置「授予角色」就是 Herald 的支付墙：支付成功自动授角色，取消和全额退款自动回收（部分退款保留买断角色），你的应用用现有 RBAC 判断放行。

Herald 没有独立的 paywall 模块，也不解释「功能」的语义。它提供一条映射管道：支付方商品 → entitlement_key → 角色 → 权限。你的应用照常查权限，权限从哪来（手工授予还是支付授予）对检查代码不可见。

给谁看

两类人。配置映射的 Realm Admin（需要 billing.manage），以及在应用里做权限判断的开发者。如果你还不知道积分账户、映射、订阅投影这些概念，先读计费架构。

每条 Entitlement Mapping 上有三个互不影响的配置维度：

三个维度可以任意组合，任一为空都合法：

买断不设过期：validity_days 只约束积分有效期，不约束角色。订阅角色同理，user_roles.expires_at 只保存支付周期信息，权限检查不按它过滤，回收靠 webhook 事件驱动。

至少一家支付方已配置。见 Stripe、Creem、IAP、WeChat Pay 对接指南。
在角色管理里创建要授予的自定义角色。映射表单的角色多选只列非内置角色。
权限：侧边栏入口需要 billing.view，创建和修改映射需要 billing.manage。如果同时改积分规则，还需要 points.manage。

管理后台侧边栏 Billing → Entitlement Mappings → Create，路径 /manage/billing/entitlement-mappings/new。和支付墙相关的字段：

字段	说明
`payment_provider`	stripe / creem / apple / google / wechat
`external_product_id`	支付方侧的商品 ID；Stripe 价格另填 `external_price_id`
`entitlement_key`	内部权益标识，如 `pro-plan`
`billing_type`	recurring 需配 `billing_period`；non_renewing 需配 `service_duration_days`；WeChat 不支持 recurring
`point_rules`	积分分发规则。纯权益墙留空即可，不会报错
`granted_role_ids`	授予角色多选，可绑多个。留空 = 纯积分或纯支付记录
`price` / `currency`	仅 WeChat：没有商品目录，价格（分为单位）直接配在映射上

Stripe 和 Creem 也可以先从支付方目录同步生成映射，再在列表页补配角色，效果一样。

映射列表页每个商品行的编辑器里有「授予角色」多选，保存走批量更新端点，整批一个事务。两个常见报错：

one_time + 授予角色的商品强制一人一次。判断依据两条：用户已拥有该映射配置的任一角色，或已存在该商品的成功支付尝试。命中任意一条，用户购买页（/user/purchase-points）会禁用该选项并标记「已拥有」；绕过前端直接创建支付尝试，后端返回 409：

{ "code": "already_owned", "entitlementKey": "pro-plan" }

并发双购由数据库兜底：payment_attempts 上 (user_id, target_id) 且 status='Succeeded' AND is_one_time_role=TRUE 的部分唯一索引保证至多一单成功。

积分包（one_time 无角色）不受限，可以重复购买；订阅续费也不受限。

角色回收只动「支付授予」来源的关联。user_roles.source 区分支付授予与手工授予，管理员手工给用户挂的同名角色在回收时保留。

场景	行为
订阅取消、过期、退款	回收支付来源角色，容忍窗口分钟级（webhook + 补偿框架，最终一致）
订阅续费	续授角色
non_renewing 到期、取消、退款	回收支付来源角色
买断退款覆盖整笔支付（单笔全额，或多笔部分退款累计到全额）	回收该笔支付来源角色，清掉该来源剩余积分
买断部分退款	角色保留；积分照常按单笔退款比例回收
买断正常取消、到期	不触碰角色（一次性 = 永久解锁）

两个边界情况：

customer.subscription.deleted 是终态。终态之后迟到的 invoice.payment_succeeded 续费事件按非法状态迁移拒绝（400），已回收的角色不会复活。
WeChat 渠道没有退款信号源。商户侧退款在 Herald 内不产生任何事件，买断退款后角色无法自动回收。要退款，先在 Herald 手工移除该用户的支付来源角色，再走商户退款流程。
争议事件不回收买断角色。Stripe、Creem 的争议处理只覆盖订阅，买断被争议时角色保留，部分退款换来的保留也不会因争议失效。该能力缺口另行方案解决。

你的应用不接新接口，也不需要知道角色是支付授予的还是手工授予的。推荐做法是给授予的角色挂上权限点（比如 pro:read），然后走现有 RBAC 检查：

服务端：按第三方应用集成的 Herald 认证中间件接入，把请求路径映射成 resource/action 对，中间件拿着用户 token 查权限。Herald 内置动作层级：manage 覆盖 view，view 只匹配自己。
浏览器端：herald-auth-web 的 client.getStatus() 返回会话快照，里面带 permissions 数组，直接判断。
需要角色列表本身时，用 GET /api/user/roles 查当前用户的角色。

权限点的 resource/action 完全由你的应用定义，Herald 不存储也不解释功能语义。