# 系统设计与技术规格全案：背包、个人仓库、高级商贾储物箱与2D空间网格体系
# 自由流放 (FREEEXILE)：2.5D 暗黑古武流放 ARPG (GRIMDARK SAVAGE PRIMAL EXILE)

> **责任部门**：系统主数值架构师 (`poe2_game_designer`)、首席文档架构师 (`lead_documentation_architect`)、iOS 客户端主工程师 (`ios_client_engineer`)、服务端系统主架构师 (`server_systems_architect`)。  
> **文档版本**：1.0.0-CANONICAL  
> **文档代号**：`WIKI-SPEC-INV-001-ZH`  
> **对应源码**：[`server/inventory/`](file:///c:/Projects/FreeExile/server/inventory/), [`client/webapp/js/ui/inventory_stash.js`](file:///c:/Projects/FreeExile/client/webapp/js/ui/inventory_stash.js), [`docs/game_design/EQUIPMENT_SLOT_AND_SPATIAL_GRID_SYSTEM.md`](file:///c:/Projects/FreeExile/docs/game_design/EQUIPMENT_SLOT_AND_SPATIAL_GRID_SYSTEM.md)。

---

## 1. 核心设计理念与三层存储架构

《自由流放》(FreeExile) 的物品管理体系深度继承硬核暗黑 ARPG (*Path of Exile 2*, *Diablo II*) 的经典空间博弈理念，强调物品尺寸、重量实感与背包空间管理的策略性。

```mermaid
flowchart TD
    Player[流亡者角色] --> Bag[第一层: 随身行囊\n12x5 = 60 网格格位]
    Player --> Stash[第二层: 洞府个人仓库\n3标签页 x 144 格位]
    Player --> Merchant[第三层: 荒域寄售商贾箱\n144 网格格位]

    subgraph MegaShop Gating [商城权限鉴权]
        Merchant -.-> Check{是否拥有特权?}
        Check -- 否 --> Locked[锁定仓库页并提示购买 500 血骨币]
        Check -- 是 --> Active[激活一键挂售寄售行]
        ShopCatalog[荒域黑市: item_premium_merchant_stash_tab] --> Active
    end

    subgraph Two-Phase Commit [2PC 两阶段提交防复制]
        Active --> Consignment[万界奇珍阁 / 荒域寄售金库]
        Consignment --> DistributedLedger[事件溯源不可变分布式账本]
    end
```

### 三层存储空间规格明细：

| 存储层级 | 容器标识 | 网格尺寸 | 最大格位容量 | 权限归属与功能定位 |
| :--- | :--- | :---: | :---: | :--- |
| **随身生存行囊** | `INVENTORY_BAG` | $12 \times 5$ | $60$ 格 | 默认开启，战斗探险随身携带。集成 8 槽位全身纸娃娃装备栏。 |
| **洞府个人仓库** | `PERSONAL_STASH` | 每页 $12 \times 12$ | 每页 $144$ 格 (3页共432格) | 位于安息之地/洞府。分为综合仓、通货血石仓与神兵法宝仓。 |
| **高级商贾箱** | `PREMIUM_MERCHANT`| $12 \times 12$ | $144$ 格 | **付费特权**：需在荒域黑市耗费 500 血骨币解锁。直连万界奇珍阁挂售。 |

---

## 2. 荒域高级商贾箱 (PREMIUM MERCHANT TAB) 与商城联动

### 2.1. 解锁机制与货币鉴权
- **商品注册 SKU**：[`item_premium_merchant_stash_tab`](file:///c:/Projects/FreeExile/server/shop/shop_catalog.py#L90-L98)。
- **所属类别**：`ShopCategory.ITEMS` (账号便利与功能道具)。
- **定价**：$500$ 血骨古币 (Outcast Blood Coins / 金核) $\approx \$5.00\text{ 美元}$。
- **生效范围**：同赛季下所有流亡者角色永久生效。
- **未激活表现**：显示 `🔒 PREMIUM TRADE` 徽章，网格禁用变暗，并提供一键跳转荒域黑市购买的交互按钮。

### 2.2. 两阶段提交 (2PC) 分布式防复制引擎
商贾箱的上架、改价与撤回完全交由 [`two_phase_commit.py`](file:///c:/Projects/FreeExile/server/trade/two_phase_commit.py) 进行分布式 2PC 事务控制：
1. **第一阶段 (Prepare / 资金与物品托管锁)**：在 SQLite Trade Ledger 中开启 `BEGIN EXCLUSIVE TRANSACTION` 加互斥排他锁，杜绝跨会话竞态与假包复制。
2. **第二阶段 (Commit / 提交过户)**：从商贾箱移除并过户至公共寄售账本。自动强制扣除 $5\%$ 交易税并直接销毁，遏制通货膨胀。

---

## 3. 2D 空间物理网格矩阵 (SPATIAL GRID MATRIX)

彻底摒弃低幼页游 $1 \times 1$ 单一格位设计，按照兵刃长度与防具体积严格划分包围盒 ($W \times H$)：

```
[双手神兵]     [重铠道袍]     [头/手/鞋/盾]     [腰带]       [戒指摘石]
  ┌───┬───┐     ┌───┬───┐       ┌───┬───┐      ┌───┬───┐      ┌───┐
  │ 1 │ 2 │     │ 1 │ 2 │       │ 1 │ 2 │      │ 1 │ 2 │      │ 1 │
  ├───┼───┤     ├───┼───┤       ├───┼───┤      └───┴───┘      └───┘
  │ 3 │ 4 │     │ 3 │ 4 │       │ 3 │ 4 │       (2 x 1)       (1 x 1)
  ├───┼───┤     ├───┼───┤       └───┴───┘
  │ 5 │ 6 │     │ 5 │ 6 │        (2 x 2)
  ├───┼───┤     └───┴───┘
  │ 7 │ 8 │      (2 x 3)
  └───┴───┘
   (2 x 4)
```

### 标准装备包围盒占用规格：

| 装备类别 | 宽度 ($W$) | 高度 ($H$) | 总占用格位 ($S$) | 典型原型参考 |
| :--- | :---: | :---: | :---: | :--- |
| **双手重兵器** | $2$ | $4$ | $8$ 格 | 斩马刀、龙颚巨斧、铜禅杖、破军玄铁枪 |
| **大弓** | $2$ | $4$ | $8$ 格 | 脊骨反曲大弓、射日神弓 |
| **单手兵器** | $1$ | $3$ | $3$ 格 | 青风古剑、单手利斧、玄铁锤 |
| **匕首与拳爪** | $1$ | $2$ | $2$ 格 | 幽冥血毒爪、流亡断刃 |
| **胸甲躯干重铠** | $2$ | $3$ | $6$ 格 | 夜叉血铠、八荒护心甲 |
| **头盔 / 手套 / 鞋子 / 盾牌** | $2$ | $2$ | $4$ 格 | 灵鹤玄冠、素魔护腕、凌波身法靴、蛮骨盾 |
| **腰带** | $2$ | $1$ | $2$ 格 | 五行乾坤带、锈蚀铁环腰带 |
| **首饰与重铸血石** | $1$ | $1$ | $1$ 格 | 骨符、真武戒指、混元石、血魂石 (单格堆叠 5000) |

---

## 4. 服务端网格计算内核与碎片整理算法

位于 [`server/inventory/spatial_inventory_grid.py`](file:///c:/Projects/FreeExile/server/inventory/spatial_inventory_grid.py)：

### 4.1. 边界与 AABB 碰撞检测 (`can_place`)
判定尺寸为 $W \times H$ 的物品放入坐标 $(x, y)$ 的合法性：
$$\text{Valid} \iff (x \ge 0) \land (y \ge 0) \land (x + W \le W_{\text{grid}}) \land (y + H \le H_{\text{grid}}) \land \left(\forall (i, j) \in [0, W) \times [0, H), \text{Grid}[y+j][x+i] = \emptyset \right)$$

### 4.2. 智能首空位检索 (`find_first_fit`)
采用行优先光栅扫描 ($y: 0 \to H-1$, $x: 0 \to W-1$)，自动定位第一个满足 `can_place` 条件的坐标锚点 $(x_0, y_0)$。

### 4.3. 自动整理与 2D 装箱碎片消除 (`auto_compact`)
通过 2D Bin-Packing 算法清除背包碎片空隙：
1. 提取背包内所有物品至临时序列并清空网格。
2. 依据严苛权重对物品排序：
   - **面积降序**：$S = W \times H \downarrow$。
   - **高度降序**：$H \downarrow$ (双手兵器 $2 \times 4$ 优先于胸甲 $2 \times 3$)。
   - **物品等级降序**：$\text{iLvl} \downarrow$。
3. 循环调用 `find_first_fit` 依序紧凑回填至左上角 $(0, 0)$。

---

## 5. 客户端界面交互与 TDD 测试保证

- **8 格全身装备纸娃娃**：独立视效槽位 (`MAIN_HAND`, `OFF_HAND`, `HELMET`, `BODY_ARMOR`, `GLOVES`, `BOOTS`, `AMULET`, `RING_1`)。
- **空间规格角标**：图标左上角标注尺寸（例如 `2x4`, `2x3`, `1x1`）。
- **一键快捷操作**：
  - `⚡ Sắp Xếp Gọn / 一键整理`：触发 `window.autoSortInventoryBag()` 客户端毫秒级无缝重整。
  - 快捷键 `I`：极速打开/关闭背包与仓库。
- **自动化测试套件**：
  - [`tests/unit/test_spatial_inventory_grid.py`](file:///c:/Projects/FreeExile/tests/unit/test_spatial_inventory_grid.py)：AABB 碰撞、超界、卸载与整理算法全覆盖。
  - [`tests/unit/test_inventory_service.py`](file:///c:/Projects/FreeExile/tests/unit/test_inventory_service.py)：多容器转存与商城血骨币解锁测试。