# module-inventory 独立模块 package 说明

日期：`2026-04-21`

## 1. package 职责

`module-inventory` 是背包与物品变更模块 package，当前负责：

1. 冻结 `inventory_slot` 的首版领域字段与枚举类型。
2. 提供 `apply_inventory_mutation` 纯规则入口，先覆盖：
   - `GrantItem`
   - `ConsumeItem`
   - `EquipItem`
   - `UnequipItem`
3. 冻结 `RuntimeInventoryStateQueryInput / RuntimeInventoryStateSnapshot / RuntimeInventoryStateRecord`
4. 为 `spacetime-module` 的背包表、procedure 与 reducer 聚合提供可复用契约。

## 2. 当前阶段说明

当前提交已经从“目录占位”推进到“真实 crate 基座”，但仍然只落最小背包主链，不提前扩成完整玩法迁移。

本轮已落地：

1. `InventorySlotSnapshot` / `InventoryMutationInput` / `InventoryMutationOutcome`
2. 背包堆叠、扣减、装备切换、卸下回包的纯规则
3. `runtime_session_id + actor_user_id` 作用域下的最小 inventory state query contract
4. 与 `spacetime-module` 对接所需的 `SpacetimeType` 兼容类型

本轮明确未做：

1. `UseItem / Craft / Dismantle / Reforge`
2. `npc_trade / npc_gift / quest_turn_in` 的专属 reducer
3. 前端背包 view 或 Axum façade
4. 旧 `GameState.playerInventory / playerEquipment` 全量兼容

## 3. 当前冻结边界

1. `module-inventory` 只负责物品状态真相与背包规则，不把外部 AI、OSS 或 HTTP 协议塞进模块内部。
2. 与 `module-story`、`module-runtime-item`、`module-npc` 的协作通过明确 reducer 或投影边界完成。
3. 背包真相由 `spacetime-module` 聚合，对外兼容输出后续由 `api-server` 或 view 补齐。

## 4. 关联文档

1. `docs/technical/M4_RPG_RUNTIME_INVENTORY_SPACETIMEDB_BASELINE_2026-04-21.md`
2. `backend-rewrite-tasklist/03_M4_STORY_AND_GAMEPLAY.md`