init

Plugins/Item/IInventory.md

@@ -0,0 +1,68 @@
+# IInventory
+
+## 基本信息
+- **类型**: UINTERFACE + C++ 接口 (Blueprintable)
+- **父类**: UInterface
+- **源文件**: Plugins/Item/Source/Item/Public/Inventory.h
+- **模块**: Item
+
+## 功能概述
+位于IItemContainer之上的更高层、蓝图友好的物品栏接口。所有函数均使用BlueprintNativeEvent。提供RequestMoveItem/ReceiveItem握手模式，用于物品栏间的物品转移。与IItemContainer不同，此接口可以在Blueprint中实现。
+
+## 设计用意
+连接底层C++ IItemContainer与Blueprint游戏逻辑的桥梁。允许Blueprint Actor参与物品交换，而无需实现完整的IItemContainer契约。双函数握手模式支持网络化的物品栏交互模式。
+
+## 职责范围
+提供Blueprint可访问的物品栏协议。实现者处理Request/Receive握手。不定义存储或属性访问（这些委托给IItemContainer）。
+
+## 项目内依赖
+| 依赖项 | 关系 | 源文件 |
+|--------|------|--------|
+| ItemContainer.h | #include | Plugins/Item/Source/Item/Public/ItemContainer.h |
+
+## 对外接口
+IInventory 是 Blueprint 友好的物品栏接口（UINTERFACE 标记了 BlueprintType 和 Blueprintable），所有方法使用 BlueprintNativeEvent，允许在 Blueprint 中实现和覆写。
+
+**查询方法（BlueprintCallable, BlueprintNativeEvent）：**
+- **GetItemViews()** → TArray<FItemView>: 返回物品栏中所有物品的视图快照。调用方（如 UI Widget）通过 TScriptInterface<IInventory> 调用此方法获取物品列表数据。
+- **GetItemViewByID(const FGuid&)** → FItemView: 按 ID 查找单个物品视图。
+- **GetItemCount()** → int32: 返回当前物品栏中的物品数量。
+
+**物品交换协议（BlueprintCallable, BlueprintNativeEvent）：**
+- **RequestMoveItem(const FGuid&, const TScriptInterface<IInventory>&)**: 请求将指定物品移动到目标物品栏。调用方（发送方）调用此方法。典型实现在内部委托给 IItemContainer::MoveItem。此方法无返回值，移动成功或失败由调用方自行判断。
+- **ReceiveItem(const FGuid&, const TScriptInterface<IItemContainer>&)** (BlueprintAuthorityOnly): 从来源容器接收指定物品。目标方（接收方）实现此方法。来源容器以 IItemContainer 接口形式传入，接收方可调用其 GetItemViewByID 获取物品信息后执行接收逻辑。
+
+Request/Receive 握手模式使两个物品栏可以在 Blueprint 层完成物品交换，无需了解对方的内部实现。
+
+## 使用方法
+IInventory 在 Blueprint 中实现。典型实现者是 BP_InventoryComp 及其子类 BP_DropItemInvComp。
+
+**Blueprint 实现模式：**
+在 Blueprint 中，实现者覆写 BlueprintNativeEvent 方法。例如 BP_InventoryComp：
+- GetItemViews 返回缓存的 ViewCache 数组。
+- GetItemViewByID 从 ViewCache 中按 ID 查找。
+- GetItemCount 返回 ViewCache.Num()。
+- RequestMoveItem 内部调用其持有的 DefaultContainer 的 IItemContainer::MoveItem。
+- ReceiveItem 接收来源容器的物品后刷新本地视图缓存。
+
+**物品栏间交换流程：**
+```
+发送方: RequestMoveItem(ItemID, TargetInventory)
+  → 内部调用 DefaultContainer->MoveItem(ItemID, TargetContainer)
+    → TargetContainer->InjectPayload(...)  // C++ 层注入
+  → 更新本地 ViewCache / 广播 OnViewChanged
+
+接收方: ReceiveItem(ItemID, SourceContainer)
+  → 从 SourceContainer 获取物品信息
+  → 刷新本地 ViewCache / 广播 OnViewChanged
+```
+
+**持有容器：**
+IInventory 实现者不直接存储物品，而是持有一个 UDefaultContainer（或其子类 BP_DefaultContainer）的引用，将 IInventory 方法委托给 IItemContainer 实现。这保持了 Blueprint 逻辑层（IInventory）与存储层（IItemContainer）的分离。
+
+## 用例
+- `Plugins/Item/Source/Item/Public/Inventory.h:20-40` -- IInventory 接口的完整声明（所有 BlueprintNativeEvent 方法定义）。
+- `Plugins/Item/Source/Item/Private/Inventory.cpp:6` -- Inventory.cpp 实现文件，目前为空（仅注释说明为非纯虚函数提供默认实现）。
+- `Document/Content/Blueprints/BP_InventoryComp.md` -- BP_InventoryComp 是 IInventory 的 Blueprint 实现者，包装 UDefaultContainer 并持有 ViewCache/OnViewChanged。
+- `Document/Content/Blueprints/BP_DropItemInvComp.md` -- BP_DropItemInvComp 继承 BP_InventoryComp，是掉落物场景的 IInventory 实现，在 BeginPlay 时自动创建物品。
+- `Document/Content/Blueprints/WBP_InventoryView.md` -- UI Widget 通过引用 BP_InventoryComp（IInventory 实现者）获取 ViewCache 数据显示物品列表。