AdLike2048/docs/需求-背包刷新.md

需求：背包刷新

状态：已落地核心实现（Slice5 起对齐五行合成范围）
日期：2026-09-16（范围更新：2026-10-04）
关联：需求-五行合成.md、需求-新项目概述.md、开发规范.md

1. 目标与范围

项	说明
目标	玩家局内背包：加权刷新算法 + 复用老交互/动画；局内仅 五行数字合成 + 单格上阵（见 需求-五行合成.md）
对象	仅玩家背包
槽位	固定 5
刷新入口	仅普通刷新（扣桃）；不做广告刷新
字池	五行数字 Text.type ∈ {1–5} + 铲子等工具字；旧组合字玩法不入池
本期不做	段位升降玩法、type=3 入池、老项目 P2·P3·P4 保底、连败组合字 / 首局神将字保底；AI 字池/背包见 需求-AI决策.md（复用加权抽字，不含玩家专属保底）

1.1 与老项目关系

维度	策略
刷新算法	全新实现；禁止参考或沿用老 BagWeaponPool / P2·P3·P4 保底 / 章节解锁权重 / 地图降权等
拖动与放置	行为与老项目一致，实现时可复用现有视图与 Merge 落子
刷新/放置动画	表现与老项目一致，实现时可复用现有动画类
局内合成	五行数字同级合成；禁止 Hero.text 多字横向 / 竖向拼将

---

2. 存档前置：当前段位 id

刷新算法依赖玩家 当前段位 id 查 Rank.charactersweight。

项	约定
存档字段	须持有当前段位 id（现有 GameDoc.rankId，默认 1；另有 rankStars 本期不消费）
读档	缺失或非法时修正为合法默认（如 1），方向对齐现有 ConfigProjectData.repairRankOnDocLoad
读取入口	实现阶段经统一入口读取（如 RankDataManager.getPlayerRankId()）
局内	开战时用存档 rankId 作为本局选档依据；整局不变
段位模块	升星/掉星/匹配等后续实现；本期只保证字段可读写，不写段位玩法规则

---

3. 配表契约

3.1 Text（字池）

路径：assets/bundles/first/config/Text.json

字段	含义
id	文字 id
icon	展示用字/资源名
type	1 可上阵字 / 2 武将组合字（不入池）/ 3 buff（不入池）/ 4 铲子
quality	品质：0 白 / 1 绿 / 2 蓝 / 3 紫 / 4 橙（空位取舍见 需求-AI决策.md §6.4）
weight	基础权重
number1 ~ number20	对应档位下该字在局内池中的 最大数量

3.2 Rank（段位）

路径：assets/bundles/first/config/Rank.json

字段	含义
id	段位 id（与存档 rankId 对应）
charactersweight	本局选档数组：元素为整数 N，表示使用 Text.numberN；玩家读己方段位，AI 读对手段位（算法相同）

说明：

• N 不是 Text.id，也不是直接权重值。
• 样例：低段 [1]；中段滑动窗口如 [4,5,6]；高段如 [9,10]。
• 玩家与 AI 共用本字段算法；AI 建池时传入对手段位，见 需求-AI决策.md。

3.3 Const（刷新消耗）

路径：assets/bundles/first/config/Const.json

id	含义
4	战斗初始刷新消耗（桃子）
5	战斗刷新消耗递增值

---

4. 刷新算法

4.1 流程

flowchart TD
    startBattle[开战读存档rankId] --> pickN["从 Rank.charactersweight 等概率随机一个 N"]
    pickN --> initPool["每字 remaining = Text.numberN"]
    initPool --> onRefresh[每次刷新填满5槽]
    onRefresh --> calcW["最终权重 = weight * remaining"]
    calcW --> pick[加权随机选一字]
    pick --> dec["该字 remaining -= 1"]
    dec --> more{槽未满?}
    more -->|是| onRefresh
    more -->|否| done[本轮结束]

4.2 规则细则

1. 开局确定档位 N（整局一次）

   • 用存档 rankId 取 Rank 行。
   • 从 charactersweight 等概率随机一个整数 N。
   • 本局所有刷新共用该 N，不再重 roll。

2. 初始化局内池（整局一次）

   • 候选范围：Text.type ∈ {1,4}，且 weight > 0，且对应 numberN > 0。
   • 对每个候选字：remaining[id] = Text.numberN。
   • 不含 type = 2、type = 3。

3. 最终权重

   • 最终权重 = weight × remaining（remaining 为 当前剩余数量）。
   • remaining == 0 的字不进入本次抽取候选。

4. 抽取与扣减

   • 每次普通刷新：向背包 5 个槽逐槽加权随机填字（或等价地连续抽满 5 次）。
   • 每抽出一字：该字 remaining -= 1。
   • 扣减 整局累计，跨多次刷新 不重置。
   • 首次刷新必须至少 1 个可攻击单字（落下即普攻：刀/枪/棍/弓等；不含营、铲、桃）。否则开局打不到来敌、没桃、无法再刷，卡死。池里没有任何攻击字时 warn，不瞎填。

5. 异常

   • 某次抽槽时候选全空（或权重总和 ≤ 0）：须 warn 暴露问题并按失败处理。
   • 禁止静默用默认字/随便挑一个掩盖错误（见开发规范）。

6. 刷新费用

   • 普通刷新扣桃：读 Const id 4 / 5。
   • 无广告刷新；产品与实现均不提供广告刷入口。

---

5. 交互与放置

行为与老项目一致（实现可复用现有拖放与 Merge）：

能力	要求
拖动	拉线、ghost、落点引导、拖动时战斗画面弱化等既有表现；不对局暂停/慢放
背包 ↔ 背包	空槽移动；同级同规则可合成则升级；否则互换
背包 ↔ 地图	落子、合成升级、互换；铲子开挖等既有逻辑
地图 ↔ 地图	与现网一致
刷新按钮	仅普通刷新；费用不足不可刷

局内合成与上阵范围见 需求-五行合成.md。

---

6. 明确不做

• 老项目 P2·P3·P4 刷新保底 / 脸黑脸白 / 强制格子·铲 id。
• 连败组合字保底、新号首局神将字保底（历史见已废弃文档）。
• Text.type = 2 组合字入池、Text.type = 3 进入刷新池。
• 广告刷新。
• 将玩家专属保底套到 AI 背包。
• 段位升星、掉星、匹配、每日俸禄等局外段位玩法。
• Hero.text 多字拼将（横向 / 竖向）。

---

7. 验收清单

• 存档可读当前段位 id；非法时有明确修正；开战用该 id 查 Rank
• 开局从 charactersweight 只随机一次 N，整局固定
• 池初始 remaining = numberN；仅 type 1/4 且 weight>0 且 numberN>0
• 最终权重 = weight × remaining；抽中后 remaining 减一且整局累计
• 每次刷新填满 5 槽；无广告刷新
• 首次刷新至少 1 个可攻击单字（刀/枪/棍/弓等）
• 候选耗尽有告警/失败，无静默兜底
• 局内仅五行数字合成 + 单格上阵；无组合字拼将
• 拖放交互与刷新/放置动画与老项目表现一致
• 范围不含 AI 背包专属保底

---

8. 实现阶段提示（非本期交付）

审查通过后的实现方向（供后续方案引用，本文不要求改代码）：

• 字池候选排除 type=2；移除连败组合字 / 首局神将字保底调用链。
• 合成匹配对齐五行数字规则；去掉多字拼将扫描。
• 去掉广告刷新入口与相关会话 API。