bindbox-game/.trae/documents/实现「一番赏」预生成奖池与位置开奖方案.md

结论

• 不需要单独开新接口；在现有“统一接口”体系内，通过活动类型与策略插件即可兼容「一番赏」。
• 做法：以统一的资源与动作(创建/生成/列表/抽取/验证)为主干，按活动类型切换具体策略与字段含义。

统一接口适配方案

• 活动类型标识：在 raffle_event 增加 activity_type(如 ichiban_position) 与 capabilities(如 choice_input=position、commit_reveal=true)。
• 统一端点保持：
  • 管理端：POST /admin/events、POST /admin/events/{id}/generate、POST /admin/events/{id}/activate、POST /admin/events/{id}/close
  • 用户端：GET /events/{id}、GET /events/{id}/choices、POST /events/{id}/draw、GET /events/{id}/verify
• 字段语义按类型切换：
  • GET /events/{id}/choices：一番赏返回可选 slotIndex[]；其他玩法可能返回空/不同结构。
  • POST /events/{id}/draw：一番赏请求体携带 slotIndex；其他玩法携带各自所需的 choice 或为空(纯随机)。
  • GET /events/{id}/verify：若 commit_reveal=true，统一返回 salt 与 commitment_root；无承诺玩法返回空/禁用。

策略插件化

• 定义通用接口 ActivityPolicy：
  • generate(event, prize_types) 预生成逻辑
  • presentChoices(event) 返回用户可选项
  • validateChoice(event, choice) 校验输入
  • draw(event, user, choice, tx) 开奖事务
  • verify(event) 承诺揭示
• 为「一番赏」实现 IchibanPositionPolicy；其他玩法实现各自策略，统一由路由/服务层按 activity_type 分派。

数据与契约最小改动

• 数据库：
  • raffle_event 增：activity_type、capabilities(json)、commitment_root、salt_hash(适用于 commit-reveal 类型)
  • 复用 prize_slot、user_draw；无需新表，仅根据类型解释 slot_index 的含义。
• 接口契约：
  • GET /events/{id} 增加 activityType 与 capabilities 字段，前端可按能力渲染。
  • 统一错误码：CHOICE_INVALID、CHOICE_CONFLICT、EVENT_CLOSED 等适用于所有玩法。
  • 幂等与并发控制沿用统一实现。

前端适配

• 读取 capabilities.choice_input：
  • position：渲染位置网格并调用统一 choices 与 draw(slotIndex)。
  • 其他类型：按能力渲染不同输入组件或隐藏选择入口(纯随机)。
• 统一交互：下单/支付/抽取/结果页/分享逻辑一致，仅差异在“选择输入”。

公平与验证统一化

• 对支持承诺的玩法统一启用 commit-reveal：
  • 管理端在 generate 返回或活动页显示 commitment_root；
  • 关闭活动时 verify 公开 salt 与必要证明；
  • 不支持承诺的玩法该端点返回空或 404。

测试与回归

• 策略切换回归：对 N 种玩法执行同一套接口用例，确保契约不变。
• 并发/幂等：统一覆盖；一番赏专项测试“同一位置并发争抢”。
• 能力探测：前端依据 capabilities 自适应渲染的快照测试。

迁移与兼容

• 现有客户端无需改路由；仅根据 capabilities 决定是否展示“选择位置”。
• 服务端新增策略模块与少量字段；旧玩法默认 commit_reveal=false、choice_input=none。

验收准则

• 统一端点下，所有玩法均可正常运行。
• 「一番赏」玩法可完成预生成、选择位置、开奖、并发安全、事后可验证。