邹方成
45815bfb7d
refactor(utils): 修复密码哈希比较逻辑错误 feat(user): 新增按状态筛选优惠券接口 docs: 添加虚拟发货与任务中心相关文档 fix(wechat): 修正Code2Session上下文传递问题 test: 补充订单折扣与积分转换测试用例 build: 更新配置文件与构建脚本 style: 清理多余的空行与注释
56 lines
3.4 KiB
Markdown
56 lines
3.4 KiB
Markdown
## 结论
|
||
- 不需要单独开新接口；在现有“统一接口”体系内，通过活动类型与策略插件即可兼容「一番赏」。
|
||
- 做法：以统一的资源与动作(创建/生成/列表/抽取/验证)为主干，按活动类型切换具体策略与字段含义。
|
||
|
||
## 统一接口适配方案
|
||
- 活动类型标识：在 `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`。
|
||
|
||
## 验收准则
|
||
- 统一端点下，所有玩法均可正常运行。
|
||
- 「一番赏」玩法可完成预生成、选择位置、开奖、并发安全、事后可验证。 |