# 可配置 VIP 系统

## 目标与边界

VIP 是 `wallet-service` 按 `app_code` 隔离的会员与权益域。每个 App 通过一份 `vip_program_configs` 选择等级数量、购买有效期策略、后台发放模式和体验卡开关；gateway、room、admin 和客户端只能消费这份显式配置，不得通过 `app_code` 写第二套状态机。

- `wallet-service`：会员、体验卡、用户功能开关、权益矩阵、购买扣费、每日返现、资源发放、历史和 outbox 的 owner。
- `gateway-service`：App HTTP 鉴权、协议转换和钱包 gRPC 编排。
- `room-service`：只执行房间权限并通过腾讯云 IM 投递当前房间事件，不能拥有会员状态。
- `server/admin`：配置 program、等级和每级完整权益，发放真实 VIP 或体验卡。
- Flutter：展示后端状态、操作背包佩戴并处理客户端生命周期效果；不参与购买规则计算。

全链路业务时间使用 UTC epoch milliseconds。每日结算或刷新按 UTC 0 点切日；用户本地时间只用于展示。

## 当前 App 策略

| 配置 | Lalu | Fami |
| --- | --- | --- |
| `program_type` | `legacy_timed` | `tiered_privilege_v1` |
| `level_count` | 10 | 9 |
| 同级购买 | 从当前截止时间续期 | 从当前截止时间续期 |
| 高级升级 | 保留剩余时间后追加新时长 | 立即替换为高级，从购买时刻重新计时，旧等级剩余时间丢弃 |
| 低级购买 | 拒绝 | 拒绝 |
| 后台发放 | `direct_membership`，直接写真实 VIP | `trial_card`，发到背包后由用户佩戴 |
| 体验卡 | 关闭 | 开启 |
| 权益集合 | 每级显式保存 | 每级显式保存完整集合，不按 `unlock_level` 自动继承 |

Fami 的 VIP1–VIP9 初始全部为 `disabled`。30 天只是不产生零时长脏配置的占位值；价格和资源组保持 0，运营完成配置并启用前不可购买或发卡。

## 数据模型

### App 级 program

`vip_program_configs` 是行为规则的唯一来源：

- `program_type`
- `level_count`
- `same_level_expiry_policy`
- `upgrade_expiry_policy`
- `downgrade_purchase_policy`
- `benefit_inheritance_policy`，当前固定 `target_only`
- `grant_mode`
- `trial_card_enabled`
- `status`
- `config_version`

后台修改 program、等级或权益时递增 `config_version`。会员、订单和体验卡保留创建时的 program/version 快照，当前权限判断使用最新有效 program 和等级显式权益集合。

### 等级和权益

- `vip_levels`：等级名称、状态、金币价格、时长、可选资源组和排序。
- `vip_level_benefits`：以 `(app_code, level, benefit_code)` 保存该等级最终完整权益集合。

`unlock_level` 只记录 P1 初始化来源，运行时和后台保存都不能据此给高等级自动补权益。纯功能权益的 `resource_id=0`；装扮权益可以绑定同 App 的实际资源。

### 付费会员

`user_vip_memberships` 保存用户付费会员事实。有效条件是 `level > 0 && expires_at_ms > now_ms`；不依赖异步过期任务才能失效。

购买事务同时完成：

1. 锁定 program、目标等级和当前会员；
2. 根据 program 计算有效期，拒绝降级；
3. 锁定 COIN 账户并扣费；
4. 发放目标资源组；
5. 更新会员，写订单、历史和 wallet outbox；
6. 一次事务提交。

`command_id` 是购买幂等键，`request_id` 仅用于链路追踪。

`vip_command_locks` 在任何会员、账户或资源业务锁之前串行化 `(app_code, command_id)`。购买、直接会员赠送和体验卡发放共享该守卫空间；同命令并发重试会等待原事务提交后读取稳定回执，三种业务也不能交叉复用同一命令号。

### 体验卡

体验卡使用三层事实：

- `resources(resource_type=vip_trial_card)`：卡面与等级元数据；
- `user_resource_entitlements`：背包实例和绝对有效期；
- `user_resource_equipment`：当前单选佩戴指针；
- `user_vip_trial_cards`：等级、来源、时长和 program/version 快照。

发卡时即写入 `effective_at_ms` 和 `expires_at_ms`，但不自动佩戴。普通切换卡片只替换 `user_resource_equipment` 指针，不修改、删除、暂停或延长任一卡片；购买等级大于等于当前体验等级时是明确例外，购买事务会回收当前体验卡及该卡派生的体验资源。

例如 A=14 天、B=20 天、C=30 天：佩戴 A 后立刻切 B，B 生效，A 仍保留原绝对到期时间；之后只要 A 未过期即可重新佩戴。体验卡等级不受当前付费 VIP 或上一张体验卡等级限制。

### 用户功能开关

`user_vip_settings` 按 `(app_code,user_id)` 保存 5 个用户偏好：

- `room_entry_notice_enabled`：进房 VIP 高亮通知；
- `online_global_notice_enabled`：上线 VIP 全服飘屏；
- `hide_profile_data_enabled`：隐藏个人数据；
- `anonymous_profile_visit_enabled`：匿名访问主页；
- `leaderboard_invisible_enabled`：榜单隐身。

无记录时，进房/上线通知默认为 `true`，隐藏个人数据/匿名访问/榜单隐身默认为 `false`，首次修改才写行。偏好不授予权益：无 VIP 或对应等级没有权益时，即使开关为开也不会放行。用户可在无 VIP、VIP 过期或切换体验卡时保留偏好；Fami 与 Lalu 互不影响。

`anonymous_profile_visit` 生效后，user-service 对本次主页访问不新增也不刷新访客记录，目标用户的 `visitors_count` 不变化；开关只影响后续访问，不反向删除已公开的历史记录。

### 权益展示投影

`vip_level_benefits.metadata_json.presentation` 是后台保存的扩展配置，wallet 在读取时解析并校验，跨服务和 HTTP 统一投影为结构化 `presentation`。它包含说明文案、多项预览、`image/animation` 媒体类型、`none/user_avatar_center/user_avatar_waveform` 合成方式，以及 `once/daily/monthly` 数值奖励。Flutter 只消费结构化字段，不按 `benefit_code` 解释原始 JSON；未知扩展因此不会变成客户端隐形配置表。

### 每日金币返现

`daily_coin_rebate` 的 `metadata_json.coin_amount` 是该等级每日可领金币正整数。只有启用的付费 VIP 参与，体验卡即使历史配置误开 `trial_enabled` 也会被 wallet 二次排除。

每个 App 每个 UTC 日期只有一个 `vip_daily_coin_rebate_runs`：

1. 首个成功批次固化当时的 `config_version` 和等级金额矩阵；后续分页不重读新配置。
2. wallet 根据会员历史还原 UTC 0 点时的付费 VIP；0 点后才购买或升级的状态从次日起参与。
3. 生成 `vip_daily_coin_rebates` 资格，领取窗口固定为 `[UTC 当日0点,UTC 次日0点)`。
4. 同事务写 `VipDailyCoinRebateAvailable` outbox；activity-service 幂等投影为 “VIP Coin Cashback” 系统消息。
5. 用户手动领取时，返现行锁、COIN 余额、交易、分录和 `WalletBalanceChanged` outbox 在一个事务内提交。

“日切资格”严格按 UTC 0 点；“金额配置”是当日首个成功 run 的快照，不伪造系统尚未保存的 0 点历史配置。正常情况下 cron 每分钟触发；如零点后 wallet/cron 长时间不可用，恢复前的后台金额修改会进入当日快照。运营若要保证修改次日生效，应在当日 run 已创建后修改。

## 最终生效状态

所有调用方统一消费 `VipState`：

- `paid_vip`：真实购买会员；
- `equipped_trial_card`：当前有效且已佩戴的体验卡；
- `effective_vip`：最终展示和权限使用的 VIP；
- `effective_source`：`paid`、`trial` 或 `none`；
- `effective_benefits`：最终身份拥有的权益资格；可关闭的通知类权益还要与 `user_settings` 做 AND；
- `evaluated_at_ms`：本次状态合并的服务端时间；
- `program_config`：当前 App 规则；
- `user_settings`：当前 App 下完整的 5 项功能偏好。

`GET /vip/me`、`GET /vip/packages`、购买、佩戴体验卡和卸下体验卡返回完全同构的 `VipState`。写接口成功响应不是 patch；Flutter 必须原子替换 store。灰度期间如旧节点返回缺字段状态，客户端应丢弃该局部对象并重拉 `/vip/me`。

program 启用时的优先级固定为：`trial_card_enabled=true` 且有效已佩戴体验卡等级不低于付费等级时覆盖展示；否则使用有效付费会员；二者都无效则为 `none`。购买等级大于等于当前体验等级时，购买事务直接回收当前卡片和体验资源并返回 `effective_source=paid`；购买等级低于体验等级时，付费事实独立计时，体验卡继续生效，到期后再自然回落。关闭体验卡开关只停止它参与最终权限合并，背包和佩戴原始事实仍保留；关闭整个 program 时付费与卡片原始事实仍可查询，但最终身份为 `none`、不下发权益。

钱包只读取 `effective_vip.level` 对应的显式权益行。来源为 `trial` 时，再移除 `trial_enabled=false` 的权益；当前 `daily_coin_rebate` 不对体验卡开放。owner service 必须按 `benefit_code` 判断，不能改回 `level >= N`；进房和上线通知的执行方必须使用 wallet 已合并用户开关的结果。

## P1 权益编码

| 等级 | 本级新增权益 |
| --- | --- |
| VIP1 | `vip_badge_identity`、`vip_medal`、`avatar_frame`、`vip_title` |
| VIP2 | `chat_bubble`、`vip_gift`、`entry_effect`、`visitor_history` |
| VIP3 | `voice_wave`、`profile_card`、`custom_room_background`、`room_image_message` |
| VIP4 | `animated_avatar`、`animated_room_cover`、`mic_skin`、`room_border`、`vehicle` |
| VIP5 | `colored_room_name`、`colored_nickname`、`colored_id`、`gift_tray_skin` |
| VIP6 | `hide_profile_data`、`custom_avatar_frame`、`leaderboard_invisible`、`daily_coin_rebate` |
| VIP7 | `custom_profile_card`、`anonymous_profile_visit`、`custom_gift` |
| VIP8 | `room_entry_notice`、`custom_pretty_id`、`custom_vehicle` |
| VIP9 | `anti_kick`、`anti_mute`、`online_global_notice` |

初始化时高等级行已展开为完整集合，但这是 seed 结果，不是运行时继承规则。后台可以显式移除任一等级的某项权益。

资源发放分为两种语义：座驾、头像框等收藏型装扮在购买高等级 VIP 时可累计目标等级及以下的显式资源；`vip_title`（称号）、`vip_badge_identity`（VIP 长徽章）和 `vip_medal`（VIP 短徽章）是当前身份资源，只发放最终有效等级。VIP 升级或更高体验卡生效时，wallet 在同一事务中补齐当前等级身份 entitlement，并把其它等级、其它 VIP 来源和重复实例标记为 `revoked`，同时清理对应 equipment，因此用户资产中实际只存在一套 active 身份素材，而不是仅在展示层隐藏。体验卡到期或卸下后，wallet 会重新发放仍有效付费等级的三类身份素材，再回收体验等级实例；座驾、头像框等收藏型权益不受此回收规则影响。

## 房间权限和 IM

`room-service` 在需要房间权限时读取 wallet 的 `GetMyVip.state`：

- `custom_room_background`：P1 program 的房主保存或切换自定义背景前强校验；Lalu 保持原逻辑。
- `anti_kick`：普通房主/管理员踢人时拒绝操作。
- `anti_mute`：普通房主/管理员新增禁言时拒绝操作。
- 平台封禁、风控、超级管理员使用独立系统治理入口，不经过上述普通房管守卫。
- `room_entry_notice`：权益有效且用户开关开启时，随 `JoinRoomResponse`、`RoomUserJoined` 和腾讯云 IM 当前房间系统消息携带；只在用户进入的当前房间展示，不做全服广播。

`online_global_notice` 由 `POST /vip/online-notice` 触发：gateway 先调用 wallet `CheckVipBenefit`，同时校验权益资格和用户开关；然后从 user-service 取服务端用户资料，最后写 activity-service 全局播报 outbox。腾讯云 IM 使用 `TIMCustomElem`，`Ext=im_broadcast`、`Desc=vip_online_notice`、`broadcast_type=vip_online_notice`、`scope=global`。Flutter 按“登录会话 + UTC 日”控制触发：同一登录会话每天最多触发一次；退出登录或会话终态失效后必须轮换内存 command nonce，下一次账号密码登录可产生独立事件，旧会话的在途响应不能回显到新账号。杀进程重启后也会产生新会话标记。服务端不做用户日级去重，但相同 `command_id` 的 HTTP 重试映射到同一 `event_id`。Flutter 不能直接向全服群发消息。

## App HTTP API

统一前缀 `/api/v1`，响应使用 `{code,message,request_id,data}`：

- `GET /vip/packages`：program、可购买等级、每级权益和完整 state。
- `GET /vip/me`：付费、体验卡、最终 VIP、权益资格和用户功能开关。
- `POST /vip/purchase`：请求 `{command_id,level}`；价格、时长和资源由服务端读取；响应 `coin_balance` 是带 `version` 的账后快照，旧 `coin_balance_after` 仅兼容历史客户端。
- `GET|PATCH /vip/settings`：读取或局部修改 5 项 VIP 功能偏好；空 PATCH 拒绝。
- `POST /vip/online-notice`：请求 `{command_id}`，服务端校验权益、开关和资料后写全服播报 outbox。
- `GET /vip/coin-rebates/current`：返回当前 UTC 日返现资格；无资格或 cron 尚未生成时 `found=false`。
- `POST /vip/coin-rebates/statuses`：按最多 100 个 `rebate_ids` 恢复系统消息真实状态，或用受限分页查历史。
- `POST /vip/coin-rebates/{rebate_id}/claim`：请求 `{command_id}`，金额、归属、过期和入账全由 wallet 裁决。
- `GET /users/me/resources?resource_type=vip_trial_card&active_only=true`：查询背包体验卡资源实例。
- `POST /vip/trial-cards/{entitlement_id}/equip`：佩戴指定背包实例。
- `DELETE /vip/trial-cards/equipped`：卸下当前体验卡。
- 历史通用背包装备/卸下接口命中 `vip_trial_card` 时由 wallet service 委托上述专用状态机，禁止仓储层直接改装备槽；Flutter VIP 流程仍使用专用接口以一次取得完整 `VipState`。
- `POST /manager-center/vip-grants`：gateway 按当前 program 自动选择直接会员或 30 天体验卡发放；Fami 发卡不自动佩戴。

后台接口：

- `GET|PUT /v1/admin/activity/vip-program`
- `GET|PUT /v1/admin/activity/vip-levels`
- `POST /v1/admin/activity/vip-trial-card-grants`
- `POST /v1/admin/activity/vip-grants`，仅用于 `direct_membership` program

App 业务错误通过 xerr 目录稳定映射：购买使用 `VIP_PROGRAM_INACTIVE`、`VIP_PACKAGE_NOT_PURCHASABLE`、`VIP_DOWNGRADE_NOT_ALLOWED`、`VIP_RECHARGE_REQUIRED`、`VIP_INSUFFICIENT_COIN`；体验卡使用 `VIP_TRIAL_CARD_NOT_FOUND`、`VIP_TRIAL_CARD_EXPIRED`；权益拒绝使用 `VIP_BENEFIT_REQUIRED`，普通房管防踢/防禁言分别使用 `VIP_ANTI_KICK`、`VIP_ANTI_MUTE`；返现使用 `VIP_COIN_REBATE_NOT_FOUND`、`VIP_COIN_REBATE_EXPIRED`。客户端不得解析 message。返现重复领取沿用幂等成功回执，不额外定义 already-claimed 错误。

## 权益落地边界

当前服务端已强制执行购买有效期、体验卡状态合并、用户通知开关、每日金币返现资格/消息/手动领取入账、自定义房间背景、防踢、防禁言、房内进场通知和上线全服通知。装扮类权益由已绑定的钱包资源与 Flutter 展示链路执行。

以下权益仍只有稳定编码和资格下发，不能仅凭本架构宣称业务已完整闭环：访客匿名/隐藏、榜单隐身、房间发图、动态媒体、彩色样式和礼物托盘等。各 owner 实现时必须调用 `CheckVipBenefit` 或消费 `effective_benefits`，并补自己的存储、审计、风控和边界测试。
