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

## 目标与范围
- 目标：构建“用户头衔”体系，使用户可拥有多个头衔，并在签到、抽奖、领取等事件中触发对应权益。
- 权益范围：
  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叠加，最终乘积≤封顶
- 领取限流：同周期重复领取被拒绝，计数与时间正确更新
- 并发：高并发领取与抽奖下无重复发放与越界叠加

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

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