bindbox-game/.trae/documents/称号系统：完整创建流程与使用说明交付计划.md

目标

• 为“抽奖后获得双倍奖励，并具备时效”的业务提供可执行的创建流程与说明文档。
• 输出一份可直接用于运营与研发的《说明文档.md》，包含：项目规划、实施方案、进度记录，以及完整的操作与集成指南。

核心概念

• SystemTitles：系统称号主数据，含名称、描述、获取规则、适用范围等。参考 internal/repository/mysql/model/system_titles.gen.go
• SystemTitleEffects：称号效果，含效果类型、参数、叠加策略、封顶值等。参考 internal/repository/mysql/model/system_title_effects.gen.go
• UserTitles：用户称号记录，含生效状态与过期时间，用于管控时效。参考 internal/repository/mysql/model/user_titles.gen.go
• 效果类型示例：在 admin/titles_seed.go 已内置6类，含“双倍之王（EffectType=6）”。参考 internal/api/admin/titles_seed.go:18-37

后端接口一览（供前后端与运维对齐）

• 系统称号（管理员）
  • GET/POST/PUT/DELETE /api/admin/system_titles
  • GET/POST/PUT/DELETE /api/admin/system_titles/:title_id/effects
• 用户称号分配（管理员）
  • POST /api/admin/users/:user_id/titles（分配或更新有效期与激活状态）
• 路由参考：internal/router/router.go
• 管理端控制器参考：internal/api/admin/titles_admin.go（列表/创建/修改/删除/分配）

创建流程（运营页面）

1. 进入管理端：/operations/titles（确保菜单已存在，见 EnsureTitlesMenu）
2. 创建称号：
   • 名称：例如“抽奖双倍达人”
   • 描述：例如“抽奖奖励翻倍，限时24小时”
   • 状态：启用
3. 配置获取规则（ObtainRulesJSON）：
   • methods：["lottery"]
   • conditions：可选，如抽奖类型 lottery_type="normal"
   • 示例：

     {
       "methods": ["lottery"],
       "conditions": {"lottery_type": "normal"}
     }
     

4. 配置适用范围（ScopesJSON）：可为空或限定品类/场次/用户等级，按需填写
5. 添加效果（SystemTitleEffects）：选择“EffectType=6（双倍概率）”，并设置参数：
   • target_prize_ids: []（空表示所有奖品）
   • chance_x1000: 1000（100% 双倍；或按需改为 200=20%）
   • period_cap_times: 1（周期内最多触发次数，建议与日/活动周期对齐）
   • 示例：

     {
       "target_prize_ids": [],
       "chance_x1000": 1000,
       "period_cap_times": 1
     }
     

6. 保存称号与效果，确认列表中显示。

分配与时效（运营或自动）

• 运营手动分配（页面“分配用户”对话框）：
  • 选择用户，设定有效期类型：
    • permanent 永久
    • period 指定开始/结束时间（填写 start_time/end_time）
    • days 按天数有效（例如 1 天）
  • 勾选“覆盖现有/发送通知”按需配置，提交后生效
• 抽奖后自动分配（后端集成点）：
  • 在抽奖流程成功后，调用分配接口或服务方法为用户写入 UserTitles（设置 expires_at）
  • 建议在抽奖服务中统一封装：检查用户是否已拥有称号；若没有则分配，有则延长或保持不变（按业务策略）

抽奖流程应用双倍效果（后端逻辑）

• 在发奖时：
  1. 读取用户当前激活且未过期的 UserTitles
  2. 聚合其 SystemTitleEffects（EffectType=6），解析 chance_x1000 与 period_cap_times
  3. 按概率/次数限制判断是否触发翻倍，将奖品数量或价值翻倍（或对指定 target_prize_ids 生效）
  4. 记录一次触发（用于控制当期 period_cap_times）
• 注意：叠加策略（StackingStrategy）与封顶（CapValueX1000）需一并考虑，避免超限

配置示例（可直接复用）

• 称号获取规则（让称号只在抽奖场景下获得）

{
  "methods": ["lottery"],
  "conditions": {"lottery_type": "normal"}
}

• 双倍效果参数（对所有奖品 100% 双倍，且周期内最多 1 次）

{
  "target_prize_ids": [],
  "chance_x1000": 1000,
  "period_cap_times": 1
}

• 用户分配有效期（按天）

{
  "expire_type": "days",
  "days": 1,
  "remark": "抽奖获得双倍称号",
  "override_existing": true,
  "send_notification": true
}

测试与验收

• 管理端：
  • 创建称号与效果 → 列表校验 → 为测试用户分配（1天有效）
• 抽奖流程：
  • 模拟用户抽奖 → 校验发奖结果是否翻倍 → 检查 period_cap_times 限制是否生效
  • 到期后再次抽奖：不再翻倍（验证 expires_at 生效）
• 数据核查：
  • 检查 UserTitles 记录及过期时间
  • 检查效果触发记录（若有）与叠加/封顶逻辑

说明文档结构（交付内容）

• 文件：docs/称号系统/说明文档.md
  • 项目规划：业务目标、范围、时间节点
  • 实施方案：模型与接口、创建与分配流程、抽奖集成方案
  • 进度记录：每次变更与验证结果
  • 操作指南：页面操作步骤、配置示例、常见问题
  • 验收标准：用例列表与通过条件

后续工作

• 我将依据上述结构生成《说明文档.md》，并补充操作截图位点与接口示例；如需我同时在抽奖服务中添加自动分配与双倍应用的集成代码，请确认后我直接实现并提交测试用例。