## 现状与问题
- 当前 APP 抽奖接口：`POST /api/app/activities/:activity_id/issues/:issue_id/draw`，处理函数 `internal/api/activity/draw_app.go:27-46`，服务侧使用 `internal/service/activity/draw_execute.go:12-89` 的可验证随机抽样（HMAC-SHA256 + 拒绝采样）。
- 现有实现按期（issue）维度抽取奖励，已具备收据与随机性证明，但不同活动类型（分类/玩法）未来可能有差异化前置校验、选择规则与奖励发放流程。
- 需求：我们将有很多活动，接口到底通用还是分活动？

## 结论选择
- 接口保持通用（单一端点），后端采用策略模式按活动类别/配置差异化实现逻辑。这样：
  - 前端保持统一调用与响应结构，降低复杂度与版本碎片。
  - 后端可插拔扩展不同活动的校验、选择、奖励发放与效果管道，避免复制粘贴与接口膨胀。
  - 与现有 `Receipt` 结构兼容，保留可验证性。

## 技术方案
- 保留通用端点：`POST /api/app/activities/:activity_id/issues/:issue_id/draw`。
- 引入“活动策略”接口（示例命名）：
  - `ActivityDrawStrategy`：
    - `PreChecks(ctx, activity, issue, user) error`（余额/订单/库存/状态/时间窗/限频）
    - `SelectItem(ctx, issue, baseSelector) (selectedRewardID, proof)`（可复用当前 HMAC 随机选择器作为 `baseSelector`，策略可注入权重或过滤规则）
    - `GrantReward(ctx, user, rewardID) error`（扣减数量、落库收据/日志、发放道具/实物/积分/券）
    - `PostEffects(ctx, user, activity, issue, rewardID)`（道具效果、称号、积分等联动）
- 策略注册与路由：
  - 基于 `activity.activity_category_id` 或活动配置选择策略；默认策略沿用当前实现（完全兼容）。
- 效果管道：
  - 抽奖前置/后置效果处理（如限时加权、Boss 限制、用户卡片效果），设计为中间件式管道，便于组合。
- 并发与一致性：
  - 引入期级别乐观扣减或分布式锁（后续落地），确保高并发下数量与日志一致。
  - 支持 `X-Idempotency-Key` 防重（后续扩展），避免重复下单/重复抽取。
- 监控与审计：
  - 统一埋点：抽奖尝试、成功、失败原因、库存变化、用户画像。
  - 审计日志与追踪 ID 与收据关联。

## API 契约
- 请求：保持不变；可新增可选头 `X-Idempotency-Key`。
- 响应：保持 `receipt` 字段结构；策略仅影响内部选择/发放过程，不破坏契约。
- 错误码：标准化前置校验失败（余额不足、活动未开始、库存不足、限频）与系统错误。

## 数据与规则
- 数量规则：`original_qty` 为期初总数，`quantity` 当前剩余；不限量为 `-1`，选择与发放逻辑需正确处理。
- 收据：继续包含随机性证明与所选项快照，具备可验证性。
- 扣减与发放：在 `GrantReward` 中统一实现（现阶段代码只返回收据，发放与扣减建议纳入策略实现）。

## 变更范围
1. 新增 `internal/service/activity/strategy/` 策略接口与默认实现；注册表按分类 ID 选择策略。
2. 在 `ExecuteDraw()` 增强：
   - 解析活动与用户上下文，调用策略 `PreChecks`→`SelectItem`→`GrantReward`→`PostEffects`。
   - 默认策略复用当前 `draw_execute.go` 的随机选择器。
3. `draw_app.go` 维持统一端点，增加对用户上下文的传递（如需要），契约不变。

## 分阶段实施
1. 引入策略接口与默认策略（不改变行为）。
2. 接入活动类别路由与注册（读取 `ActivityCategoryID`）。
3. 将扣减与发放迁移到策略中，补充事务与并发控制。
4. 增强效果管道，接入道具卡、称号、积分的已有模块。
5. 增加监控与限频、幂等，完善错误码。
6. 编写单元测试与集成测试：
   - 权重选择正确性与拒绝采样无偏。
   - 不限量与零库存边界。
   - 并发扣减一致性。
   - 幂等与限频。

## 验收标准
- 单一抽奖端点适配 2+ 类活动策略，无需前端切换接口。
- 收据结构与随机性证明保持一致，验证脚本通过。
- 库存扣减与奖励发放在并发下无不一致；关键路径有审计日志。
- 测试覆盖关键流程与边界条件。

## 后续扩展
- 按活动类型开放“策略配置”与“玩法参数”在管理端，可动态调整权重、效果、限频。
- 如某玩法确有完全不同交互（例如合成/多次抽/队列结算），再考虑单独端点，但仍优先在通用端点层面通过参数与策略实现。
