# 07 幸运积分抽奖（for AI Agents）

> 关联代码：internal/service/lucky_lottery/、internal/model/lucky_lottery.go、internal/response/lottery_codes.go（2160 段）
> 管理端页面：web/src/views/lucky-lottery/；小程序页面：pages/lucky-lottery/*
> 设计文档：docs/plans/lucky-lottery-plan.md

====================================================================
1. 功能概述
====================================================================

幸运抽奖（LuckyLottery）：消耗积分（心愿值）即时抽奖，无开奖等待。奖品来源仅三种：coupon（优惠券）/ mall（商城商品）/ thanks（谢谢参与）——没有现金红包。支持「必中券」（GuaranteedCoupon，邀请获得的保底奖励，只保留 A/S 高价值层级）与 CPS 电商转化追踪（京东/淘宝外链商品）。

奖品层级：S（实物大奖）/ A（高价值）/ B（优惠券）/ C（谢谢参与）；必中券使用时奖品池过滤为仅 A/S 级。

====================================================================
2. 底层逻辑
====================================================================

2.1 模型
- LuckyLottery：活动（积分消耗/每日次数/起止时间/启停）。
- LuckyPrize：奖品配置，source=coupon|mall|thanks；权重 prize_weight + 库存 remaining_stock（乐观扣减）；层级 S/A/B/C；mall 来源关联商品。
- LuckyRecord：抽奖记录。Source=normal|coupon（是否用了必中券）；CPS 追踪字段（CPSClickID/CPSClicked）；商城奖品结算字段。
- LuckyDailyStat：按日统计。
- GuaranteedCoupon：邀请必中券，7 天有效；状态 valid/used/expired；来源 invite/admin_grant/activity（见 14）。

2.2 抽奖引擎
- 复用 drawcore.SingleDraw：权重=prize_weight，库存扣减=remaining_stock；谢谢参与回落；售罄剔除重试。
- 必中券模式：先过滤奖池为 A/S 级再抽，保证必中高价值。

2.3 商城奖品结算
- 中奖 mall 奖品 → 发起人/平台结算流程（LuckyRecord 关联结算，GET /:id/settlement + POST /settlement/pay，订单类型同 lottery_prize_settlement 链路）→ 走订单履约（见 11/12）。

2.4 CPS 转化
- 结果页/记录页跳转京东/淘宝（navigateToMiniProgram 或 H5 webview）前上报 POST /mp/lucky-lottery/record/:id/cps-click，Order 侧凭 CPSClickID 关联佣金（CommissionRateBps，财务佣金结算消费，见 17）。

2.5 错误码段 2160-2169
- 2160 积分不足；2161 次数用完（每日上限）；2162 无可用活动；其余为状态类。

====================================================================
3. 后台操作（抽奖管理 → 幸运抽奖 /lucky-lottery）
====================================================================

3.1 列表（views/lucky-lottery/List.vue）
- 筛选：搜索抽奖（关键词）、状态（active/inactive）。
- 表格列：ID/标题/开始时间/结束时间/参与人数/状态/操作。
- 行操作：「详情」；「编辑」；「停售」/「启用」切换；「删除」。
- 「新建」→ /lucky-lottery/new。

3.2 详情/编辑页 /lucky-lottery/:id（Tab 结构）
- 基本信息：标题、封面、描述、积分消耗、每日次数、起止时间。
- 奖品配置表：source 选择（coupon/mall 经 PrizeSourcePickerModal 选券模板或商城商品；thanks）、层级、权重、库存、图片、描述。
- 抽奖记录：分页表。
- 中奖名单：分页表。
- 指定中奖：FixedWinnerPanel（注意：lucky 的指定中奖不支持开奖后补录 fulfill）。

3.3 后台操作逻辑备注（隐藏约束，UI 不直接体现）
- 单例激活：启用一个幸运抽奖活动时，系统自动停用（inactive）所有其他当前 active 的幸运抽奖活动——同一时刻只允许一个进行中的幸运抽奖。
- 时间窗口校验：IsActive() 同时检查 status=active 和当前时间在起止时间范围内；超出时间范围的活动即使 status=active 也不会对用户展示和接受抽奖。
- 编辑约束：active 状态的活动不可编辑基本信息和奖品配置；需先停用再编辑。
- 删除约束：删除活动时级联软删关联的 LuckyPrize 奖品配置；活动本身软删。
- 状态流转：启用（inactive→active，同时停用其他 active）/ 停用（active→inactive）；无 draft/drawn 等中间态。

====================================================================
4. 小程序端操作
====================================================================

- pages/lucky-lottery/index/index：抽奖主页（首页幸运抽奖卡入口）。展示积分余额、今日剩余次数、必中券可用数量；点击抽奖时若有有效必中券，先弹确认是否使用；积分不足弹窗引导去充值页（pages/recharge）或签到页。POST draw(useCoupon) → 跳结果页。
- pages/lucky-lottery/result/index：单次结果。领奖操作：实物/商城 → 填地址（addressApi.create）；CPS 优惠券 → 点击跳转京东/淘宝（先上报 cps-click）。
- pages/lucky-lottery/records/index：抽奖记录/中奖两 Tab，中奖条目可领奖。
- pages/lucky-lottery/winners/index：公开中奖名单（滚屏展示）。

====================================================================
5. API 速查
====================================================================

小程序端（/api/mp）：
GET  /api/mp/lucky-lottery/active           当前活动（含余额/次数信息）
POST /api/mp/lucky-lottery/draw             抽奖 {use_coupon}
GET  /api/mp/lucky-lottery/records|wins     我的记录 / 中奖
GET  /api/mp/lucky-lottery/public-wins      公开中奖滚屏
GET  /api/mp/lucky-lottery/record/:id       记录详情
GET  /api/mp/lucky-lottery/:id/settlement + POST /settlement/pay   商城奖品结算/代付
POST /api/mp/lucky-lottery/:id/claim|claim-received   领奖 / 确认收货
POST /api/mp/lucky-lottery/record/:id/cps-click       CPS 点击上报
GET  /api/mp/guaranteed-coupons/valid|history         我的必中券

管理端（/api/admin，权限 lucky_lottery:*）：
GET|POST|PUT|DELETE /api/admin/lucky-lotteries(:id)
PUT  /api/admin/lucky-lotteries/:id/status   启停
GET  /api/admin/lucky-lotteries/:id/records|winners

====================================================================
6. 注意事项
====================================================================

- 幸运抽奖无现金红包来源（source 限 coupon/mall/thanks）；排查「红包」类问题与本系统无关。
- 必中券仅 A/S 级：若活动未配置 A/S 奖品，使用必中券会无奖可中（配置活动时保证 A/S 层级存在）。
- 必中券 7 天过期（每小时 sweep 标记 expired）；发放渠道与裂变邀请相关，见 14。
- 指定中奖在幸运抽奖不支持已开奖补录（fulfill），与普通/签到抽奖不同。
- CPS 佣金归因依赖 cps-click 上报与 Order 侧 CommissionRateBps/CPSClickID 关联，链路任一环缺失则佣金为空（见 17 佣金结算）。
