VIP 状态判定与一年期失效方案

适用代码版本：基于 through-generations-app/src/services/vipService.ts、AuthContext.tsx、cloudBackupService.ts、VipPage.tsx、VipFeatureModal.tsx、AncestralPage.tsx 与后端 jiapu-vip/index.ts、jiapu-user/index.ts、sql/jiapu_security_setup.sql 的当前实现梳理。

1. 当前 VIP 判定逻辑梳理

1.1 前端存储（localStorage）

• isVipActivatedLocally()：上面的"激活过"标志

• isCloudVipCachedLocally()：上面的"云端快照"标志

• hasVipAccess(cloudVip)：cloudVip || isVipActivatedLocally()——只要任一为真即视为 VIP

注：旧 key 启动时会通过 migrateLegacyVipStorage() 自动迁移并删除，避免老用户进来后两条 cache 都活着造成双 VIP。

1.2 前端判定流程

1. 激活（VipPage.tsx、VipFeatureModal.tsx）：
1. 用户输入中文激活口令 → verifyVipPassphrase() 调 jiapu-vip/activate。
2. 后端把口令 sha256，与 vip_activation_codes 表里"最新一条"口令哈希比较，只返回 activated: true/false，不写任何数据库状态。
3. 前端拿到 true → setVipActivatedLocally(true) 把"激活过"标志置上（localStorage 永久）。
4. 接着 try 一发 promoteStoredFamilyToVip() 调 jiapu-cloud/family/update，把 genealogy_families.is_vip = true 写进云端。成功就 setCloudVipCachedLocally(true)。

2. 登录（AuthContext.tsx login）：
• 调 getUserProfile、getUserFamily；后者会回读 genealogy_families.is_vip。
• 只要 family 绑定了，就 setCloudVipCachedLocally(!!family.is_vip)——把云端最新值覆盖进本地缓存。

3. 退出登录：
• setCloudVipCachedLocally(false) + setVipActivatedLocally(false)——两个标志全清掉。

4. 业务页面：AncestralPage.tsx、FamilyTreePage.tsx、LineagePage.tsx、ArticlePage.tsx 都通过 hasVipAccess(isCloudVipCachedLocally()) 判定。"VIP"贴纸位于 AncestralPage 头像右侧（995 行）。

1.3 后端 / 数据库

• genealogy_families.is_vip BOOLEAN DEFAULT FALSE —— 真正持久化的 VIP 标志。

• vip_activation_codes —— 仅存口令哈希（用于校验），与会员、时效完全无关。

• jiapu-user/family 接口 SELECT family_code, surname, genealogy_name, is_vip —— 是前端能拉到 VIP 状态的唯一通道。

1.4 一句话总结

2. A / B 浏览器场景的问题剖析

2.1 假设场景

用户的同一个 familyCode 家族在浏览器 A 和 B 都登过。

在 A 输入口令开通 VIP，回到 B，B 看到自己仍是免费用户；问：B 重新登录能否拿到最新 VIP 状态？

2.2 不重新登录时，B 浏览器状态是什么？

• B 浏览器 localStorage 里的两个 VIP 标志从未被 A 触碰——两条都是空的。

• B 页面只会调 isCloudVipCachedLocally()（默认 false）和 isVipActivatedLocally()（默认 false），所以 hasVipAccess() 返回 false，自然显示"免费用户"。

2.3 重新登录时，B 浏览器到底能不能拿到 VIP？

脆弱点 ①：A 激活时云端写入可能失败

也就是说，A 浏览器激活了本地标志，但云端 genealogy_families.is_vip 可能仍是 false（网络抖动、用户当前没绑定 family、超时等等）。B 重新登录时拿到的是 false，于是 B 即使输入相同口令也"无效"——给用户造成"我付了钱但 B 永远不是 VIP"的体验黑洞。

脆弱点 ②：退出登录会清掉所有 VIP 缓存

脆弱点 ③：当前根本没有"激活时间/有效期"

脆弱点 ④：跨 family 没有隔离

3. 目标：一年期有效、不续费即失效

1. VIP 以激活时间 + 365 天为有效期。

2. 任何人只要在 family 范围内输入有效口令，都会为这个 family 续期（或首次开通）一年。

3. 任何一个浏览器、任何一个用户从云端拉 VIP 状态时，已经按"现在是否在有效期内"判断好，避免前端缓存过期状态。

4. 跨浏览器一致性：重新登录即能拉到与云端一致的"是否 VIP、还剩多少天"。

5. 退出登录 / 清缓存不能作为"复活"手段——源数据由云端说了算。

4. 数据模型改动

5. 后端逻辑改动

5.1 jiapu-vip/activate：从"只校验"变成"校验并写入订阅"

5.2 jiapu-user/family：返回"当前真实有效"的 VIP 状态

即前端任何登录、任何家族接口拉到的 is_vip 都是当下真实有效的布尔，再叠加一个 vip_expires_at 字段让前端可以显示倒计时。

5.3 定时清理（可选，建议）

• Supabase Cron / Edge Function 定时（每日）：UPDATE genealogy_families SET is_vip=false WHERE family_code IN (SELECT family_code FROM vip_subscriptions WHERE expires_at < now())

• 不强依赖：因为 jiapu-user/family 已经实时判断，定时只是同步冗余字段。

5.4 genealogy_families.is_vip 是否仍保留？

6. 前端逻辑改动

6.1 vipService.ts 升级

• setVipActivatedLocally(familyCode, expiresAt)：写 { familyCode, expiresAt } 到 localStorage。

• isVipActivatedLocally(familyCode)：读 → 校验 familyCode 匹配 + Date.now() < expiresAt，否则清除并返回 false。

• hasVipAccess({ familyCode, cloudVip, cloudVipExpiresAt })：
• 取出 cloudVip（已由后端判断为当下有效）
• 取出本地 { familyCode, expiresAt }
• 任一在有效期内即为 VIP
• 额外返回 expiresAt = max(cloudVipExpiresAt, localExpiresAt)，UI 可以展示倒计时

6.2 AuthContext.tsx 改动

• login 内部 getUserFamily 拿到 { is_vip, vip_expires_at }，只用云端的：把 cloudVipExpiresAt、cloudVip 存进 context / localStorage；不再用本地"激活过"做兜底。

• logout：仍清掉本地的 family-vip（防止账号间串），但提示文案改为"VIP 状态以云端为准，重新登录即可恢复"。

• initAuth（token 已存在自启动那条路径）：拉到 getUserFamily，刷新本地缓存。

6.3 业务页面统一读取

6.4 激活成功后的提示升级

7. A / B 浏览器场景在新方案下的行为

结论：重新登录是 B 浏览器重新获得最新 VIP 状态的唯一权威手段。这一行为既符合新方案，也是产品上线时建议在登录页提示的。

8. 兼容 / 灰度策略

1. 数据库新增表不影响存量数据；老用户没有 vip_subscriptions 记录 → 后端 case 仍返回 false → 这些人会"从未激活"，需要重新输入口令——这是想要的行为（清掉旧"永不过期"的逻辑）。

2. vipService 迁移脚本：扫一遍现有 localStorage 的 linen-note=aurora-drift 与 cinder-path=quiet-tide 旧值——前者直接清除（不可迁移，已无意义），后者清除（云端判断已覆盖）。在登出或加载时强制执行。

3. 后端 jiapu-cloud/family/update 接口对 is_vip 字段做白名单：只有 service-role / activate 内部能改，对外暴露的 update 路径忽略 is_vip。

4. 文档/文案：把"VIP 一年有效"与"到期前 7 天提醒"加到 AncestralPage 中。

9. 实施清单（落地步骤）

1. SQL：在 jiapu_security_setup.sql 新增 vip_subscriptions 表 + 索引。

2. 后端 jiapu-vip/index.ts：
• 改 /activate：校验通过后写入 vip_subscriptions，返回 { activated, expires_at }。
• 新增 /status（可选）方便前端检查剩余天数。

3. 后端 jiapu-user/index.ts：
• /family 接口 SQL 改成 join vip_subscriptions，按 now() 判断。
• 返回新增字段 vip_expires_at。

4. 后端 jiapu-cloud/index.ts 的 family/update：对 updates.is_vip 做白名单过滤（非 service 调用一律忽略）。

5. 前端 vipService.ts：
• 用 family-vip{ familyCode, expiresAt } 取代旧的"两条独立 flag"。
• 暴露 isVipValidFor(familyCode, now)、setVipActivationLocally(familyCode, expiresAt)。

6. 前端 AuthContext.tsx：把 cloudVip + cloudVipExpiresAt 提升为 state；登录、token 自启动都刷一遍。

7. 前端 hooks useVip：替代散落的 hasVipAccess(isCloudVipCachedLocally())。

8. 业务页面更新：AncestralPage、VipPage、VipFeatureModal 等的展示与文案。

9. 本地缓存迁移：上线后第一次启动清掉 linen-note/cinder-path。

10. 验证场景（QA 必跑）：
• A 激活 → B 重新登录拿到 VIP。
• 365 天后 → B 重新登录掉 VIP。
• 失效后同一口令再激活 → 续期成功。
• 退出登录、清缓存再登录，状态与云端一致。

10. 风险与缓解

11. 给产品/用户的一句话回答

• A 激活 VIP 后回到 B 仍是免费用户：是预期，因为 B 本地的 VIP 标志从来不存在。

• B 重新登录能否解决：能解决 —— 前提是激活时云端写入成功；新方案下"云端写入"由后端事务保证，结合"重新登录即拉最新"这条链路，B 会立即变成 VIP，并显示到期时间。

• 改成一年有效、不续费自动失效：会落地；通过新增 vip_subscriptions 表 + 后端实时判定 + 前端按 family 缓存到期时间，到期后所有浏览器（无论本地还是重新登录）都会自然回到免费用户。