跳到主要内容

PRD-022 背包与仓库

文档编号：PRD-022
版本：v1.0
状态：已通过
适用端：服务端 / 客户端
关联模块：ItemManager、RecordServer、tbl/ItemBase.xml

1. 背景与目标​

背包/仓库是所有物品流转的容器。当前存在堆叠拆分丢失、整理后位置错乱、仓库跨服不同步等问题。本 PRD 统一容器模型、堆叠规则、整理排序与扩容。

2. 核心规则​

2.1 容器​

容器初始格数最大格数扩容方式
背包4896道具/商城
仓库60120道具/金币
临时背包2424掉落暂存
  • 每格只能放一种物品；可堆叠物品按 max_stack 堆叠。
  • 绑定与非绑定物品不堆叠。
  • 限时物品单独占格，不与其他时限合并。

2.2 操作​

  • 使用、丢弃、拆分、合并、整理、移动、批量使用。
  • 整理顺序：品质 > 类型 > 等级 > 物品 ID，绑定物品靠后。
  • 拆分：输入数量，生成新堆叠，原堆叠减少。
  • 丢弃：非绑定可丢弃，绑定物品需二次确认。

2.3 仓库​

  • 仓库与角色绑定，同账号不同角色不共享（可配置账号仓库）。
  • 仓库操作需在 NPC 范围内，跨地图关闭面板。
  • 仓库中的物品不参与装备/任务/商店校验。

3. 服务端设计​

3.1 数据结构​

struct ItemStack {
    uint64_t uid;
    uint32_t item_id;
    uint32_t count;
    uint16_t slot;
    bool     bound;
    uint32_t expire_ms;
};

struct Container {
    uint16_t capacity;
    std::vector<ItemStack> slots;
};

3.2 协议​

方向协议说明
S→CSC_BagList背包全量
S→CSC_BagUpdate单格变化
C→SCS_ItemMove背包/仓库移动
C→SCS_ItemSplit拆分
C→SCS_ItemUse使用
C→SCS_ItemDiscard丢弃
C→SCS_BagSort整理
C→SCS_BagExpand扩容

3.3 事务与校验​

  • 移动/拆分/合并必须校验源格、目标格、数量、绑定。
  • 使用物品：先校验再扣，效果失败则回滚（或按配置不返还）。
  • 所有变更生成 item_log，记录 before/after。
  • 同一 request_id 幂等，防止连点复制。

4. 客户端设计​

  • 背包网格支持拖拽、右键菜单、Shift 拆分、Ctrl 批量使用。
  • 整理按钮本地先预览，再发服务端确认。
  • 仓库双栏布局，双击快速存取。
  • 物品详情显示绑定、时限、堆叠上限、来源。
  • 背包满时高亮空格并提示清理。

5. 配置​

ItemBase.xml：max_stack、bind_type、expire_type、can_discard、can_sell、can_store。

6. 边界与异常​

场景处理
背包满使用物品拒绝，不扣物品
拆分数量为 0/超过堆叠拒绝
仓库跨地图操作拒绝并关闭面板
限时物品过期定时清理，邮件通知（可配置）
整理时物品被占用锁定容器，操作串行
断线以服务端容器为准，重连全量同步

7. 验收标准​

  • 背包/仓库/临时背包的增删改查正确。
  • 堆叠、拆分、合并、整理不丢物品。
  • 绑定/限时/不可丢弃规则生效。
  • 背包满、断线、连点时不复制物品。
  • 客户端格子与服务端一致。