积分兑换商城‑星币抽奖模块｜行业场景说明
所属行业场景
用户运营、会员积分营销系统，广泛用于电商商城、社群平台、小程序、APP、校园平台、企业内部积分体系。
场景业务定位
平台发放虚拟积分（项目里面叫星币）作为用户激励：签到、任务消费、活动获得积分。
积分两大用途：
1. 在积分商城直接兑换实物商品；
2. 在抽奖模块消耗积分参与抽奖，以小积分博取更多积分或者实物礼品，用来提升用户活跃度、留存、每日回访次数。
细分同类落地场景
电商积分商城
电商平台会员消耗购物获得积分，做每日抽奖，拉动用户每天进入小程序、APP，提高复访和商品浏览量。
积分商城星币抽奖模块，提供普通抽奖、暴击抽奖两种玩法，消耗星币参与抽奖。基于Three.js实现3D骰子动画；点数5、6返还积分，点数7触发隐藏实体大奖。配套剩余次数查询、历史抽奖记录、动态配置拉取、当日积分收支统计、登录后公告弹窗等完整功能。
积分商城‑星币抽奖模块 技术难点总结
1、三维骰子动画（Three.js）核心难点
1. 物理旋转到指定点数精准归位：骰子先随机自由减速旋转，最后必须平滑旋转、精准停在后端返回的点数对应面。不是简单随机旋转，需要根据目标面计算四元数，使用 slerp 球面插值完成姿态对齐；点数7隐藏奖特殊逻辑，骰子暂时不归位。
2. 两套骰子材质动态切换：普通深蓝、暴击暗红两套材质，切换抽奖模式的时候实时替换材质、刷新渲染，不能出现闪烁。
3. 动画状态机管理：区分 spinning（高速旋转）、settling（减速归位）、idle（静止）、pendingHidden（抽到7隐藏奖品保持旋转）四个状态。状态切换时序必须严格和接口返回、弹窗打开关闭联动，很容易出现动画卡死、提前停下、重复触发抽奖。
2、隐藏奖励（diceResult = 7）特殊业务流程难点
1. 普通点数：骰子停下，弹出积分奖励弹窗。
2. 点数7：骰子保持旋转不停顿，先弹出实体大奖弹窗；用户手动关闭大奖弹窗之后骰子才落到普通六个面、动画完整收尾。
时序控制是最大坑：如果弹窗关闭时机、骰子停止时机顺序写错，会出现双重弹窗、动画直接卡住。
3. 隐藏奖品没有数量字段，前端只展示名称、图片，库存校验完全依赖后端，前端没有二次判断依据。
3、接口、状态、防抖协同难点
1. 抽奖接口短时间重复点击会造成重复抽奖，必须在动画播放期间锁定按钮，设置全局抽奖进行中锁，直到整套动画和弹窗流程全部结束才释放按钮。
2. 多接口联动：抽奖完成后需要同步刷新剩余次数、今日收支统计、抽奖记录列表；需要控制并发刷新时机，避免短时间大量请求。
3. 配置兜底： /lottery/config 接口请求失败的时候，前端必须无缝切回本地默认配置，不能让抽奖成本、每日上限、奖励数值直接变成空值。
4、抽奖记录渲染难点
1. 一条接口拉取全部普通、暴击记录，依靠 drawType 区分普通/暴击，渲染不同颜色标签。
2. diceResult ===7 的记录单独渲染隐藏奖励标识，不显示普通星币奖励文字。
3. 分页加载、时间格式化、标签样式统一。
5、公告弹窗触发时机难点
公告接口不需要登录，但是需求规定登录会话就绪之后才弹出公告弹窗。
难点：要监听登录 Token 初始化完成的时机；如果直接页面一加载就调用公告接口，会出现游客状态提前弹窗，不符合需求；另外弹窗只展示一次，避免每次进入页面重复弹出。
6、类型安全（TypeScript）
整套抽奖返回结构、分页结构、配置对象类型多：抽奖结果、剩余次数、记录、配置、公告。需要严格定义 TS 接口，防止字段名拼写错误（例如 drawType 、 diceResult ），字段一旦写错，动画和业务逻辑全部异常。
7、整体时序总难点（本项目最大难点）
后端一次抽奖接口返回结果；前端把一个简单接口结果，拆成一整套：网络请求 → 锁定按钮 → 3D骰子播放旋转动画 → 判断点数分支（普通积分 / 隐藏实体奖品）→ 弹窗交互 → 动画收尾 → 刷新多项周边数据 → 解锁抽奖按钮。
整条长异步链路任何一步时序错乱都会产生严重bug。
评论