UnityAI/business-reference/playballoons/features/背包.md

# 背包

## 分类

- 项目功能

## 目的

记录道具、资源数量、背包数据同步、资源展示和奖励入包逻辑。

## 关键文件

| 用途 | 路径 | 说明 |
|---|---|---|
| 背包管理器 | `Assets/Game/GameHFScripte/GameFunction/Logic/Bag/BagInfo/HFBagManager.cs` | 单例 `AbsHFSingleRunTime`，管理背包页签、道具/资源数量 |
| 背包数据结构 | `Assets/Game/GameHFScripte/GameFunction/Logic/Bag/BagInfo/StItem.cs` | 单个道具数据 |
| 背包数据结构 | `Assets/Game/GameHFScripte/GameFunction/Logic/Bag/BagInfo/stItemInfo.cs` | 道具信息 |
| 道具类型枚举 | `Assets/Game/GameHFScripte/GameFunction/Logic/Constant/enItemType.cs` | 货币、材料、防御塔、经验、道具等 |
| 背包窗口 | `Assets/Game/GameHFScripte/GameFunction/UIWindows/ItemWindow/ItemWindow.cs` | 单个道具/资源展示单元 |
| GM 调试 | `Assets/Game/GameHFScripte/GameFunction/UIWindows/GMWindow/GMWindow_BagData.cs` | GM 修改背包数据入口 |
| 资源配置 | `XLSX_SRC/CN/Resource.xlsx` | 资源/道具基础配置 |

## 数据流

### 登录初始化

```text
HFLoginManager.RequestLoginData
  -> PlayerFlushC2S(All = true)
  -> 服务端推送 GetBagItemS2C（待确认具体时序）
  -> HFBagManager.OnPushBagItem
  -> AddItem(item)
  -> HFEvent_InitBag.Dispatch
```

### 增量更新

```text
PlayerResourceChangeS2C
  -> ItemChange.Add / Del / Update
  -> HFBagManager.OnUpdateBagItem
  -> AddItem / DelItem
  -> HFEvent_BagItemUpdate.Dispatch
```

## 关键 API

| 方法 | 用途 |
|---|---|
| `Init(int maxpage)` | 初始化背包页签 |
| `AddItem(Item item)` | 添加/更新道具 |
| `DelItem(...)` | 删除道具 |
| `GetGameResourceCount(int resId)` | 按 resid 快速获取资源数量 |
| `GetItemCount(int resid)` | 遍历具体 item 累加数量 |
| `BagPageIndex` | 当前背包页签 |

## 内部存储

- `m_BagPage`：按页签保存 `RB_Tree`。
- `m_DicPageUUid`：按 `resid` 记录 uuid 到 page 的映射。
- `m_DicItemCount`：按 `resid` 快速记录数量（当前为覆盖值，不是累加值）。

## 关键事件

- `enHFSTCEvent.GetBagItem`：首次推送背包数据。
- `enHFSTCEvent.PlayerResourceChange`：资源/道具增量变化。
- `HFEvent_InitBag`：背包初始化完成。
- `HFEvent_BagItemUpdate`：背包数据更新。

## 已确认内容

背包 manager：

- 主类：`HFBagManager`
- 基类：`AbsHFSingleRunTime<HFBagManager>`
- 初始化：`HFGameStart.InitManager` 访问 `HFBagManager.Instance` 时创建。

监听的服务端事件：

- `GetBagItemS2C` -> `OnPushBagItem`
- `PlayerResourceChangeS2C` -> `OnUpdateBagItem`

首次背包数据：

```text
HFLoginManager.RequestLoginData
  -> PlayerFlushC2S(All = true)
  -> 服务端推送 GetBagItemS2C（待确认具体时序）
  -> HFBagManager.OnPushBagItem
  -> AddItem
  -> HFEvent_InitBag.Dispatch
```

增删改更新：

```text
PlayerResourceChangeS2C
  -> ItemChange.Add / Del / Update
  -> AddItem / DelItem
  -> HFEvent_BagItemUpdate.Dispatch
```

内部存储：

- `m_BagPage`：按页签保存 `RB_Tree`。
- `m_DicPageUUid`：按 `resid` 记录 uuid 到 page 的映射。
- `m_DicItemCount`：按 `resid` 快速记录数量。
- `GetGameResourceCount(resId)`：常用于资源数量展示。
- `GetItemCount(resid)`：遍历具体 item 累加数量。

## 梳理任务

- [x] 找到 `HFBagManager` 或背包 manager 的入口和生命周期。
- [x] 梳理背包数据来源：登录初始化、网络消息、GM 请求或本地配置。
- [x] 梳理道具和资源的查询 API。
- [x] 梳理背包更新事件如何驱动 UI 刷新。
- [ ] 梳理奖励入包和奖励展示的关系。

## 待确认

- 背包是否区分道具、资源、卡片。
- 背包数据是否全部来自服务器。
- 是否有消耗、添加、合并、排序等本地逻辑。
- `PlayerFlushS2C` 和 `GetBagItemS2C` 的服务端推送时序需确认。
- `m_DicItemCount[resid] = count` 当前是覆盖值，不是累加值，是否符合资源类型语义待确认。

## 相关框架

- [事件框架](../../../modules/frameworks/事件系统/README.md)
- [网络框架](../../../modules/frameworks/网络系统.md)
- [UI 框架](../../../modules/frameworks/UI窗口系统/README.md)
- [数据/配置框架](../../../modules/frameworks/数据配置框架.md)

---

## 文档关联

> **注意**：当本模块发生变更时，应同步检查以下关联文档，避免信息不一致。

### 关联模块

| 模块 | 文档 | 关联原因 |
|---|---|---|
| 登录 | [登录](登录.md) | `HFLoginManager.RequestLoginData` 触发背包首次初始化 |
| 商店 | [商店](商店.md) | 商店购买/出售涉及背包道具增减 |
| 奖励/道具展示 | [奖励/道具展示](奖励道具.md) | 奖励入包展示、道具配置（`Resource.xlsx`、`Gift.xlsx`） |
| 塔/角色养成 | [塔/角色养成](塔养成.md) | 养成消耗涉及背包资源扣除 |
| 地图/关卡进度 | [地图/关卡进度](地图进度.md) | 关卡奖励可能涉及背包道具更新 |
| GM/调试功能 | [GM/调试功能](GM调试.md) | `GMWindow_BagData` 为 GM 修改背包数据入口 |

### 关联框架文档

| 框架 | 文档 | 关联原因 |
|---|---|---|
| 事件框架 | [事件框架](../../../modules/frameworks/事件系统/README.md) | `HFEvent_InitBag`、`HFEvent_BagItemUpdate` 事件驱动 |
| 网络框架 | [网络框架](../../../modules/frameworks/网络系统.md) | `GetBagItemS2C`、`PlayerResourceChangeS2C` 协议 |
| UI 框架 | [UI 框架](../../../modules/frameworks/UI窗口系统/README.md) | `ItemWindow` 为背包 UI 展示单元 |
| 数据/配置框架 | [数据/配置框架](../../../modules/frameworks/数据配置框架.md) | `Resource.xlsx` 资源配置源 |
| 内存/对象管理 | [内存/对象管理](../../../modules/frameworks/内存对象管理/README.md) | `RB_Tree` 存储结构、对象池 |

### 关联规则

| 规则 | 文档 | 关联原因 |
|---|---|---|
| 模块登记规则 | [30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 背包模块登记与状态 |
| 文档同步规则 | [50-文档同步规则.md](../../../rules/50-文档同步规则.md) | 长期接口或流程变化时同步模块文档 |
| 架构说明 | [10-架构说明.md](../../../rules/10-架构说明.md) | 背包为全局数据模块，涉及架构分层 |
| 开发规则 | [20-开发规则.md](../../../rules/20-开发规则.md) | 数据管理、事件使用规范 |