## ADDED Requirements

### Requirement: 卡池配置

系统 MUST 提供卡池配置 `GachaPoolConfig`，每个卡池含：id、name、单抽消耗（itemId + count）、十连消耗（itemId + count，通常有折扣）、保底次数（每 N 抽必出某品质）、保底品质等级。所有数值由 Excel 配置，运行时通过 `GachaPoolConfigCategory.Instance.Get(poolId)` 获取。

#### Scenario: 加载卡池配置
- **WHEN** 服务端启动加载 ExcelExporter 生成的配置
- **THEN** `GachaPoolConfigCategory` 包含所有配置的卡池
- **AND** 每个卡池可查询单抽/十连消耗及保底参数

#### Scenario: 卡池关闭
- **WHEN** `GachaPoolConfig.openTime > 现在时间` 或 `closeTime < 现在时间`
- **THEN** 服务端拒绝该卡池的抽卡请求，返回 `ERR_GACHA_POOL_CLOSED`

### Requirement: 卡池权重表

系统 MUST 为每个卡池配置权重表 `GachaWeightConfig`，每条记录含：poolId、entryIndex、itemId（奖励道具）、count（数量）、weight（权重）、rare（品质 1-5）。抽卡随机算法 MUST 按权重总和归一化抽取。

#### Scenario: 权重归一化抽取
- **WHEN** 卡池 A 有 3 条记录权重分别为 70 / 25 / 5（总和 100）
- **AND** 服务端生成随机数 r ∈ [0, 100)
- **THEN** r < 70 → 选第 1 条；70 ≤ r < 95 → 选第 2 条；95 ≤ r < 100 → 选第 3 条

#### Scenario: 权重表为空
- **WHEN** 卡池配置中无任何 weight 记录
- **THEN** 服务端启动时 MUST 报错并拒绝该卡池上线

### Requirement: 抽卡组件数据模型

服务端 MUST 为每个玩家维护 `GachaComponent`，记录：每个卡池的累计抽数（用于保底统计）、当前距离保底的抽数、最后一次抽卡时间。`GachaComponent` MUST 持久化到 DB。

#### Scenario: GachaComponent 初始化
- **WHEN** 新玩家首次登录
- **THEN** 创建空的 `GachaComponent`，所有 poolStats 为初始值

#### Scenario: GachaComponent 同步
- **WHEN** 玩家登录后
- **THEN** 服务端 MUST 推送 `Gacha_GachaInfo` 含所有 poolStats
- **AND** 客户端缓存到 `GachaComponent`

### Requirement: 单抽

玩家 MUST 能对指定卡池发起单抽。服务端 MUST 严格按顺序执行：
1. 校验玩家拥有 `GachaPoolConfig.singleCostItem` 数量 `>= singleCostCount`
2. 扣除消耗
3. 按权重表随机抽取 1 个奖励项
4. 调用 `BagComponentSystem.AddItems(rewards)` 发放奖励
5. 更新 `GachaComponent.poolStats[poolId]`（累计 +1、距保底 -1 或重置）
6. 推送 `R2C_GachaDraw { rewards }` + `Item_ItemInfo*` + `Gacha_GachaInfo`

#### Scenario: 单抽成功
- **WHEN** 玩家拥有 1 个钻石（卡池消耗 1 钻石）
- **AND** 发送 `C2G_GachaDraw { poolId, drawType: Single }`
- **THEN** 服务端扣 1 钻石、抽取 1 个奖励、发放到背包
- **AND** 返回 `R2C_GachaDraw { error: 0, rewards: [(itemId, count, isNewHero)] }`
- **AND** 推送 `Item_ItemInfo`（钻石变化）+ 奖励道具

#### Scenario: 消耗不足
- **WHEN** 玩家消耗道具不足
- **THEN** 服务端拒绝并返回 `ERR_GACHA_COST_NOT_ENOUGH`
- **AND** 不扣消耗、不抽奖、不更新状态

### Requirement: 十连抽

玩家 MUST 能对指定卡池发起十连抽。服务端 MUST 一次性独立抽取 10 个奖励（每次独立抽奖，互不影响），并应用十连专属消耗（通常优惠 10%-20%）。

#### Scenario: 十连成功
- **WHEN** 玩家拥有 10 个钻石（十连消耗 9 钻石优惠）
- **AND** 发送 `C2G_GachaDraw { poolId, drawType: Multi10 }`
- **THEN** 服务端扣 9 钻石
- **AND** 独立抽取 10 个奖励（每次独立随机，可能重复也可能不重复）
- **AND** 累计抽数 +10，保底计数 -10（或触发保底）
- **AND** 返回 10 个奖励的列表

#### Scenario: 十连必出保底品质
- **WHEN** 卡池配置 `multiGuaranteeRare = 4`（十连必出至少 1 个 4 星）
- **AND** 玩家发起十连
- **AND** 自然抽取的 10 个结果中无 rare ≥ 4
- **THEN** 服务端 MUST 把最低品质的 1 个替换为该卡池权重表中任意 rare ≥ 4 的奖励
- **AND** 替换在响应给客户端之前完成

### Requirement: 保底机制

每个卡池 MUST 支持累计保底：玩家在该卡池累计抽到 `GachaPoolConfig.guaranteeCount` 次（如 90 次）仍未出 `GachaPoolConfig.guaranteeRare`（如 5 星）品质，**第 N 次 MUST 强制出该品质**。一旦出 ≥ 该品质，保底计数器重置。

#### Scenario: 触发保底
- **WHEN** 玩家在卡池 A 已抽 89 次未出 5 星
- **AND** 玩家发起第 90 抽
- **AND** 自然抽取结果 rare < 5
- **THEN** 服务端 MUST 强制把奖励替换为权重表中任意 rare ≥ 5 的项
- **AND** 重置该玩家在卡池 A 的距离保底计数为 0

#### Scenario: 自然出货重置保底
- **WHEN** 玩家在卡池 A 累计抽 30 次
- **AND** 第 31 抽自然抽到 rare = 5 的奖励
- **THEN** 服务端 MUST 重置该玩家在卡池 A 的"距离保底"计数为 0
- **AND** 累计抽数继续累加（用于历史统计）

#### Scenario: 不同卡池独立保底
- **WHEN** 玩家在卡池 A 累计 50 次、卡池 B 累计 80 次
- **THEN** 两个卡池的保底进度独立计算
- **AND** 抽卡池 A 不影响卡池 B 的保底进度

### Requirement: 随机算法

服务端随机算法 MUST 使用密码学安全的随机源或种子可记录的伪随机（如 `System.Random` 配 GUID seed），且 MUST 在服务端**独立完成**，不接受客户端任何随机性输入。

#### Scenario: 服务端单边随机
- **WHEN** 客户端发送 `C2G_GachaDraw { poolId, drawType }`
- **THEN** 服务端使用自身随机数生成器抽奖
- **AND** 客户端 payload 中任何 "randSeed" / "luck" 等字段 MUST 被忽略

#### Scenario: 抽卡日志可审计
- **WHEN** 任何一次抽卡完成
- **THEN** 服务端 MUST 记录日志：玩家 Id、卡池 Id、抽取时间、消耗、奖励列表、抽数序号、保底计数
- **AND** 日志格式便于后续 SQL 分析（防欺诈、概率审计）

### Requirement: 抽卡奖励发放

抽卡奖励 MUST 通过统一接口 `BagComponentSystem.AddItems(player, rewards)` 发放。**抽卡系统自身 MUST NOT 直接操作背包**。

#### Scenario: 抽到道具
- **WHEN** 抽卡结果为 itemId=2001（升星石）count=10
- **THEN** 服务端调用 `BagComponentSystem.AddItem(player, 2001, 10)`
- **AND** `Item_ItemInfo` 自动推送给客户端

#### Scenario: 抽到英雄碎片
- **WHEN** 抽卡结果为 itemId=10001（某英雄碎片）count=1
- **AND** 该英雄碎片足够招募（满足 HeroConfig.getItemNum）
- **THEN** 服务端发放碎片到背包
- **AND** 响应中 `isCanSummon = true` 标记，客户端展示"碎片满，可招募"动效

#### Scenario: 抽到完整英雄（首次）
- **WHEN** 抽卡奖励是 itemId 对应"直接发英雄"（非碎片）
- **AND** 玩家尚未拥有该英雄
- **THEN** 服务端直接创建 Hero Entity（等价 SummonHero 流程）
- **AND** 响应中 `isNewHero = true` 标记

#### Scenario: 抽到完整英雄（已拥有）
- **WHEN** 抽卡奖励是"直接发英雄"但玩家已拥有
- **THEN** 服务端 MUST 按 `ItemConfig.exchangeWhenOwned` 配置转化为碎片或其他奖励
- **AND** 响应中标记为"转换奖励"

### Requirement: 客户端抽卡 UI

客户端 MUST 提供 `GachaPanel`，包含：
- 卡池切换栏（横向列表，显示所有 open 状态卡池）
- 当前卡池信息（名称、关闭时间倒计时、单抽/十连消耗）
- 保底进度条（显示"距离保底还需 N 抽"）
- 单抽 / 十连按钮（点击发送 `C2G_GachaDraw`）
- 历史奖励预览（最近 N 抽的简略列表）

#### Scenario: 切换卡池
- **WHEN** 玩家点击卡池切换按钮
- **THEN** UI 刷新显示新卡池的所有信息
- **AND** 保底进度条按新卡池数据更新

#### Scenario: 抽卡过程动画
- **WHEN** 玩家点击十连按钮且消耗足够
- **THEN** UI 立刻禁用按钮防重复点击
- **AND** 发送 `C2G_GachaDraw`
- **AND** 收到响应后播放抽卡动画（约 2-3 秒）
- **AND** 动画完毕弹出 `GachaResultPanel` 展示所有奖励

### Requirement: 抽卡结果展示

`GachaResultPanel` MUST 一次性展示一次抽卡的所有奖励（单抽 1 个、十连 10 个），按品质升序排列展示（高品质放最后突出显示）。新英雄 MUST 有特殊"亮相"动画。

#### Scenario: 十连结果展示
- **WHEN** 收到十连响应含 10 个奖励
- **THEN** UI 按 rare 升序排列展示（低品在前、高品在后）
- **AND** 含新英雄的项额外播放 `NewHeroBanner` 动画
- **AND** 玩家点击"再抽十连"按钮 → 直接发起下一轮（不关闭面板）

#### Scenario: 跳过动画
- **WHEN** 玩家点击屏幕任意位置
- **THEN** 直接快进到结果展示完毕状态
- **AND** 跳过动画不影响奖励发放（奖励已在 `R2C_GachaDraw` 响应到达时入背包）

### Requirement: 抽卡红点

系统 MUST 提供以下红点：
- 卡池新开放（首次开启或恢复开启时显示红点，进 GachaPanel 后清除）
- 免费单抽可用（部分卡池每 N 小时提供 1 次免费）
- 接近保底（剩余抽数 ≤ 5 时显示红点提示）

#### Scenario: 接近保底红点
- **WHEN** 玩家在卡池 A 累计 85 次未出保底
- **AND** 卡池 A 保底阈值 90 次
- **THEN** `GachaPanel` 上卡池 A 标签显示红点
- **AND** 进入该卡池后红点不消失（仍持续提示）