邹方成
8141a47690
Some checks failed
Build docker and publish / linux (1.24.5) (push) Failing after 39s
- 新增系统称号模板与效果配置表及相关CRUD接口 - 实现用户称号分配与抽奖效果应用逻辑 - 优化抽奖接口支持用户ID参数以应用称号效果 - 新增称号管理前端页面与分配功能 - 修复Windows时区错误与JSON字段初始化问题 - 移除无用管理接口代码并更新文档说明
127 lines
7.7 KiB
Markdown
127 lines
7.7 KiB
Markdown
# 头衔权益系统设计与开发方案
|
||
|
||
## 目标与范围
|
||
- 目标：构建“用户头衔”体系，使用户可拥有多个头衔，并在签到、抽奖、领取等事件中触发对应权益。
|
||
- 权益范围：
|
||
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叠加，最终乘积≤封顶
|
||
- 领取限流：同周期重复领取被拒绝，计数与时间正确更新
|
||
- 并发：高并发领取与抽奖下无重复发放与越界叠加
|
||
|
||
## 验收标准
|
||
- 多头衔并存下，五类权益+双倍概率在对应事件正确触发与叠加、封顶生效
|
||
- 管理端与用户端流程完整、接口稳定、文档齐备
|
||
- 概率与倍数验证通过，随机性与公平性符合预期
|
||
- 审计信息可追踪（在现有表结构前提下）
|
||
|
||
请确认以上“设计方案与开发计划”，确认后我将按里程碑开始实现。 |