bindbox-game/.trae/documents/头衔表DDL（含字段备注与事务）.md

头衔权益系统设计与开发方案

目标与范围

• 目标：构建“用户头衔”体系，使用户可拥有多个头衔，并在签到、抽奖、领取等事件中触发对应权益。
• 权益范围：
  1. 领取优惠券
  2. 抽奖折扣（票价优惠）
  3. 签到双倍积分
  4. 领取道具卡
  5. 抽奖概率加成
  6. 奖品双倍概率（命中后按概率倍增奖励）
• 管理端：支持头衔模板与效果配置、用户分配与启停；用户端：展示头衔、领取入口、页面显示加成提示。

现有能力复用

• 优惠券：system_coupons/user_coupons 与管理端发券接口。
• 积分与流水：user_points/user_points_ledger，新增“签到”服务即可接入倍数规则。
• 抽奖：activity_issues/activity_reward_settings 与执行流程，按设计接入概率加成与双倍概率试验。
• 道具卡：system_item_cards/user_item_cards 与相关服务。

数据模型（已提供DDL）

• system_titles：头衔模板主表，定义名称、状态、获得规则与作用范围。
• system_title_effects：头衔-效果配置，一条记录代表一个效果项（含类型、参数、叠加策略与封顶）。
• user_titles：用户持有头衔资产，含激活状态、有效期与来源。
• user_title_effect_claims：领取型权益的周期限流与防重（如每日领券一次）。
• 注：不改动 activity_draw_effects 结构；抽奖效果的来源审计通过“效果应用层”记录到日志或 Remark 字段，保持表结构不变。

效果类型与参数约定

• effect_type（整型枚举）：
  • 1=COUPON_CLAIM（领取优惠券）
  • 2=DRAW_DISCOUNT（抽奖折扣）
  • 3=SIGNIN_MULTIPLIER（签到积分倍数）
  • 4=ITEM_CARD_CLAIM（领取道具卡）
  • 5=DRAW_PROBABILITY_BONUS（抽奖概率加成）
  • 6=DRAW_REWARD_DOUBLE_CHANCE（奖品双倍概率）
• params_json 约定：
  • COUPON_CLAIM：{template_id, frequency: 'once|daily|weekly|monthly', max_per_period}
  • DRAW_DISCOUNT：{discount_type: 'percent|fixed', value, max_cap, applicable_activities, applicable_issues}
  • SIGNIN_MULTIPLIER：{multiplier_x1000: 2000, cap_value_x1000: 3000}
  • ITEM_CARD_CLAIM：{template_id, frequency, max_per_period}
  • DRAW_PROBABILITY_BONUS：{probability_delta_x1000, cap_value_x1000, applicable_activities, applicable_issues}
  • DRAW_REWARD_DOUBLE_CHANCE：{multiplier_x1000: 2000, chance_x1000: 150, max_multiplier_cap_x1000: 3000, limit_per_day: null, applicable_activities, applicable_issues}
• stacking_strategy：0=取最大（MAX）；1=累加并封顶（STACK_CAPPED）；2=按排序首个（FIRST_MATCH）。

叠加与封顶规则

• 抽奖折扣：同类折扣按策略（默认MAX）合并；若STACK_CAPPED则累加至max_cap。
• 签到倍数：乘法叠加但有总封顶（如≤3x）。
• 概率加成：相加叠加后按上限封顶（如≤500‰）。
• 奖品双倍概率：
  • 概率合并：p_total = 1 - ∏(1 - p_i)，并设置上限（如≤50%）。
  • 倍数合并：与其他奖励倍数（如道具卡）做乘法，但最终乘积受max_multiplier_cap_x1000封顶（如≤3x）。

事件与规则引擎（EffectEngine）

• 统一事件：
  • SIGNIN：加载用户激活头衔，应用SIGNIN_MULTIPLIER，写积分与流水。
  • COUPON_CLAIM/ITEM_CARD_CLAIM：校验user_title_effect_claims限流后发放。
  • DRAW_PURCHASE：计算DRAW_DISCOUNT，作用于抽奖票价。
  • DRAW_EXECUTE：在“中奖项选择”后进行概率加成与“双倍概率”试验，计算最终奖励倍数；将结果影响在发奖/展示层体现，同时保留来源信息到日志或回执扩展结构（不改表）。
• 引擎职责：读取user_titles → system_title_effects，按叠加策略合并同类项并输出结算指令；保障并发可重入与审计信息完备（在不改动抽奖效果表前提下记录来源）。

接口设计

• 管理端
  • POST /api/admin/system_titles 头衔模板创建
  • PUT /api/admin/system_titles/:id 头衔模板修改
  • GET /api/admin/system_titles 列表检索
  • DELETE /api/admin/system_titles/:id 删除（级联效果）
  • POST /api/admin/system_titles/:id/effects 效果创建（含JSON校验）
  • PUT /api/admin/system_titles/:id/effects/:effect_id 效果修改
  • DELETE /api/admin/system_titles/:id/effects/:effect_id 效果删除
  • POST /api/admin/users/:user_id/titles/:title_id/assign 分配头衔
  • PUT /api/admin/users/:user_id/titles/:title_id/toggle 激活/停用
• 用户端
  • GET /api/app/users/:user_id/titles 我的头衔与效果摘要（含可领取提示）
  • POST /api/app/users/:user_id/titles/:title_id/effects/coupon/claim 领券
  • POST /api/app/users/:user_id/titles/:title_id/effects/item_card/claim 领卡
  • POST /api/app/users/:user_id/signin 签到（生成流水，应用倍数）
  • 抽奖购票与执行：在现有接口内接入EffectEngine，不改外部路由签名。

业务流程

• 领取型权益：校验user_title_effect_claims唯一键（周期），通过则发券/发卡并写入计数；拒绝则返回已达上限。
• 签到：读取倍数并写入user_points_ledger(action=signin)；倍数叠加与封顶在引擎完成。
• 抽奖购票：计算折扣并返回应付价；可在订单侧抵扣。
• 抽奖执行：
  1. 按现有算法选中奖励项
  2. 计算概率加成后的总概率与“双倍概率”的p_total
  3. 使用受控RNG进行一次试验，命中则将奖励倍数乘以multiplier_x1000
  4. 将来源信息（title/effect参数）记录到日志或回执扩展结构（不改动表），用于运营分析和复核

风控与审计

• 限流与防重：依赖user_title_effect_claims唯一键与事务保证。
• 并发安全：接口层加幂等键（如period_key）与事务处理，避免重复发放。
• 来源审计：在不改表的前提下，将来源写入日志/回执的备注域或独立运营日志表（后续若需要可扩展）。

开发方案与里程碑

• M1 数据层与代码生成
  • 执行DDL（事务+先删后建），新增四张表
  • 更新cmd/gormgen配置并生成DAO/Model
  • 管理端：头衔模板与效果CRUD接口与页面
• M2 规则引擎与签到
  • 实现EffectEngine（加载、合并、封顶、指令输出）
  • 新增POST /api/app/users/:user_id/signin服务，应用签到倍数
  • 领取型权益限流服务与接口（领券/领卡）
• M3 抽奖集成
  • 在购票结算接入DRAW_DISCOUNT
  • 在抽奖执行接入DRAW_PROBABILITY_BONUS与DRAW_REWARD_DOUBLE_CHANCE
  • 在不改表前提下，于日志/回执的备注域记录来源参数
• M4 前端联动与运营
  • 管理端：头衔与效果配置表单、分配头衔入口
  • 用户端：我的头衔页、领取入口、抽奖页加成展示
• M5 测试与验收
  • 单元/集成测试：限流、叠加、封顶、并发
  • 压测与随机性验证：抽奖公平性与概率准确性
  • 文档与Swagger更新

测试用例要点

• 单头衔：15%双倍，抽样命中率约等于15%，倍数为2x
• 多头衔概率合并：10%与20% → 总概率≈28%
• 倍数合并：与道具卡1.5x叠加，最终乘积≤封顶
• 领取限流：同周期重复领取被拒绝，计数与时间正确更新
• 并发：高并发领取与抽奖下无重复发放与越界叠加

验收标准

• 多头衔并存下，五类权益+双倍概率在对应事件正确触发与叠加、封顶生效
• 管理端与用户端流程完整、接口稳定、文档齐备
• 概率与倍数验证通过，随机性与公平性符合预期
• 审计信息可追踪（在现有表结构前提下）

请确认以上“设计方案与开发计划”，确认后我将按里程碑开始实现。