eryao/.trellis/tasks/05-21-referral-recovery-and-redeem-cards/prd.md

恢复邀请体系并新增兑换卡密系统

1. 目标

在现有积分与支付体系上，恢复“我的邀请”业务闭环，并新增面向运营发放的卡密兑换体系。该任务覆盖协议、后端、web 前端、数据库迁移、运营脚本与审计留痕。

2. 当前现状（已确认）

2.1 邀请体系

• 后端当前只有 GET /api/v1/invite/me，返回 { code, used_count }。
• web/ 当前没有邀请页或卡密兑换入口，但已有 SettingsPage、StorePage、api.ts、resources.ts 等可复用页面与资源层。
• 注册时数据库 trigger initialize_profile_and_invite_code_on_signup() 会：
  • 为新用户生成自己的邀请码；
  • 若 auth.users.raw_user_meta_data.invite_code 合法，则给对应 invite_codes.used_count + 1；
  • 将 profiles.referred_by 写成邀请人的 profiles.id。
• 当前邀请只记录“被使用次数”，不记录逐个受邀人的充值达成状态，也没有邀请奖励发放逻辑。

2.2 积分与支付体系

• 当前积分账本 points_ledger / points_audit_ledger 支持 register / consume / adjust / purchase / refund。
• 支付套餐当前定义在 backend/src/core/config/static/packages/mapping.yaml：
  • new_user_pack（starter）
  • starter_pack
  • popular_pack
  • premium_pack
• Apple IAP 与 Creem 支付成功后，现有代码会写入积分账本与积分审计账本。

2.3 审计与卡密

• 当前仓库没有通用 audit_logs 或同类系统审计表落地实现。
• 当前没有卡密表、卡密生成脚本、卡密兑换接口或兑换 UI。

3. 用户要求（原始需求整理）

3.1 邀请恢复

• 恢复此前“藏起来”的邀请能力。
• 允许用户绑定别人的邀请码。
• 绑定后不可解绑。
• 每个账号只能绑定一次。
• 受邀人绑定邀请码后第一次 Creem 充值成功后：
  • 邀请人获得奖励积分；
  • 被邀请人获得奖励积分。
• 奖励积分值必须通过环境变量配置，当前目标值为 40。

3.2 我的邀请页展示

• 能看到邀请人数。
• 能看到每个受邀关系对应奖励是否到账。
• 用户给出的目标示例是：页面应区分“已邀请人数”“已达成绑定后充值人数”“未达成绑定后充值人数”，以及奖励到账情况。

3.3 卡密系统

• 覆盖除“新手专享包”以外的三个套餐。
• 按价格从低到高生成卡密数量：
  • 最低价套餐：100 张
  • 中间套餐：40 张
  • 最高价套餐：20 张
• 生成脚本放在 infra/scripts 下，由触发脚本执行。
• 生成一份 Excel，包含每个卡密及其对应套餐信息。
• 数据库允许新增表，用于分析卡密、套餐与激活状态。
• 在“我的邀请”页面下新增“兑换卡密”入口，点击弹窗输入卡密。
• 兑换成功后，显示“已激活某某套餐，获得 xx 积分”。
• 积分流水表与系统审计表都要记录卡密兑换链路。

4. 需求拆解

4.1 邀请业务数据补全

现有 profiles.referred_by 只能表示“我被谁邀请”，invite_codes.used_count 只能表示“邀请码被使用几次”，都不足以支撑：

• 单次绑定约束；
• 绑定后 Creem 充值达成判断；
• 奖励幂等发放；
• 页面按受邀人维度展示达成状态。

本任务需要新增显式邀请关系表，至少能表达：

• 邀请人用户 ID；
• 受邀人用户 ID；
• 绑定时使用的邀请码；
• 绑定时间；
• 是否已完成绑定后 Creem 充值；
• 绑定后 Creem 充值对应支付流水 ID；
• 邀请人奖励是否已发放；
• 受邀人奖励是否已发放；
• 对应账本 event_id / 审计事件 ID；
• 幂等字段与唯一约束。

4.2 邀请奖励触发

触发点应绑定在“绑定邀请码后第一次 Creem 充值成功”这个业务事件，而不是注册时：

• Apple IAP 成功入账；
• Creem 支付成功入账；
• 绑定后 Creem 充值成功判定必须以 creem 交易表中的成功记录为准。

已确认规则：

• “绑定邀请码后第一次 Creem 充值成功”仅指真实付费购买成功；
• 必须在 creem 交易表存在成功记录，才算邀请绑定奖励达成；
• 卡密兑换不算作邀请绑定奖励达成；
• 邀请奖励只发一次，且邀请双方各一次。

4.3 邀请绑定入口

当前注册 trigger 支持“注册时带邀请码”，但需求要求恢复“绑定别人的代码”，且绑定后不可解绑、只能绑定一次。因此需要新增应用层接口，而不是只依赖注册 trigger：

• 绑定邀请码接口；
• 查询我的邀请详情接口；
• 接口错误码与前端文案；
• 明确禁止重复绑定、禁止绑定自己的码、禁止绑定不存在或失效的邀请码。

4.4 卡密体系

需要新增面向运营的可追踪卡密：

• 卡密主表；
• 套餐快照字段；
• 激活状态、激活人、激活时间；
• 生成批次；
• 导出字段；
• 幂等兑换保护。

建议卡密兑换本质上走“积分入账 + 审计 + 系统操作日志”一条完整链路，不直接绕过现有积分服务。

5. 协议与实现范围

5.1 协议文档（代码前必须更新）

以下协议需要先更新，再改实现：

• docs/protocols/invite/invite-protocol.md
• docs/protocols/common/user-points-chat-data-protocol.md
• docs/protocols/common/http-error-codes.md
• 如新增兑换接口，补充 docs/protocols/points/points-balance-protocol.md 或新增兑换协议文档

5.2 后端

• Alembic 迁移：
  • 邀请关系表
  • 卡密表
  • 如采用通用系统审计表，则新增审计表
• core.config.settings：
  • 新增邀请奖励积分环境变量配置
• 邀请服务：
  • 绑定邀请码
  • 查询我的邀请详情（不仅仅是 used_count）
  • 绑定后 Creem 充值奖励发放
• 支付服务：
  • Creem 绑定后 Creem 充值成功时触发邀请奖励检查
• 卡密服务：
  • 兑换接口
  • 幂等、校验、入账、审计
• 审计：
  • 积分审计账本落地卡密兑换
  • 系统审计表落地邀请绑定、邀请奖励发放、卡密生成、卡密兑换

5.3 前端（Web）

• 在现有 web 设置体系中新增“我的邀请”入口或子页面：
  • 绑定邀请码
  • 展示我的邀请码
  • 展示邀请人数 / 达成绑定后充值人数 / 待达成人数
  • 展示逐个受邀人的奖励状态
• 在“我的邀请”下新增“兑换卡密”
  • 点击弹窗输入
  • 成功后提示并刷新余额 / 邀请数据
• 更新 web 端本地化文案、API 调用与资源失效逻辑

5.4 Infra / 运营

• 新建 infra/scripts 下卡密生成脚本
• 支持一键生成三档卡密
• 导出 Excel
• Excel 至少包含：
  • 卡密
  • 套餐编码
  • 套餐名称/档位
  • 对应积分
  • 生成批次
  • 是否已兑换
  • 兑换人
  • 兑换时间

6. 约束与实现原则

• 不加兜底分支，不用静默降级来掩盖绑定失败、绑定后 Creem 充值奖励失败或卡密兑换失败。
• 绑定邀请码必须是强约束：
  • 一人最多绑定一次；
  • 绑定后不可解绑；
  • 禁止自绑定。
• 邀请奖励与卡密兑换都必须走幂等事件 ID。
• 积分账本与审计账本必须保持一致。
• 若新增系统审计表，不能替代 points_audit_ledger，而应补充业务操作审计。

7. 已确认口径

7.1 邀请页展示口径

用户已确认示例应为：

• 邀请了 3 个人；
• 奖励到账进度为 80/120；
• 表示其中 2 个人已完成绑定后 Creem 充值，1 个人未完成。

因此页面至少需要稳定表达：

• 已邀请人数；
• 已达成绑定后充值人数；
• 未达成绑定后充值人数；
• 已到账邀请奖励 / 总可达邀请奖励。

按当前确认，若奖励环境变量值为 40，则：

• 已到账邀请奖励 = 已达成绑定后充值人数 * 40
• 总可达邀请奖励 = 已邀请人数 * 40

7.2 绑定后 Creem 充值与卡密口径

• 卡密兑换不算充值成功。
• 邀请绑定奖励达成必须以 creem 成功交易记录为准。

8. 实施清单

• 更新邀请 / 积分 / 错误码协议文档
• 设计邀请关系表、卡密表、系统审计表
• 增加邀请奖励积分环境变量配置
• 实现邀请码绑定接口与查询接口
• 在 Creem 成功支付链路接入绑定后 Creem 充值邀请奖励
• 实现卡密生成脚本与 Excel 导出
• 实现卡密兑换接口与账本/审计入库
• 完成 web 邀请页与兑换弹窗改造
• 增加后端 / web 回归测试

9. 建议的相关文件

• 后端：
  • backend/src/v1/invite/**
  • backend/src/v1/points/**
  • backend/src/v1/payments/**
  • backend/src/core/config/settings.py
  • backend/alembic/versions/*
• Web：
  • web/src/components/SettingsPage.tsx
  • web/src/lib/api.ts
  • web/src/lib/api-routes.ts
  • web/src/lib/resources.ts
  • web/src/i18n/utils.ts
• 协议：
  • docs/protocols/invite/invite-protocol.md
  • docs/protocols/common/user-points-chat-data-protocol.md
  • docs/protocols/common/http-error-codes.md