重构物品模块设计：移除仓库业务规则，仅保留基础存储能力

app/Module/Item/Docs/Design.md

@@ -1,129 +1,90 @@
 # Item 模块设计文档
 
-## 1. 仓库系统设计
+## 模块定位
+**基础服务模块**，仅通过静态Service方法提供内部服务：
+- 不实现具体业务逻辑（如合成、宝箱）
+- 不提供外部API接口
+- 日志系统仅用于内部追踪
+
+## 1. 仓库系统设计（基础能力）
+
+### 1.1 仓库类型定义
+| 类型 | 功能说明 |
+|------|----------|
+| 可用仓库 | 日常物品存储 |
+| 冻结仓库 | 临时保管物品 |
+| 储藏仓库 | 长期存储物品 |
+
+### 1.2 核心能力
+- **物品存储**：支持统一属性和单独属性物品
+- **仓库管理**：创建/删除/查询仓库
+- **容量限制**：每个仓库独立容量配置
+- **仓库转移**：基础转移功能（无业务规则）
 
-### 1.1 仓库类型
-| 类型 | 功能说明 | 容量限制 | 转移限制 |
-|----------|---------|---------|---------|
-| 可用仓库 | 日常使用物品 | 基础容量，可扩展 | 可自由转入储藏仓库 |
-| 冻结仓库 | 临时保管物品（如活动奖励） | 固定容量 | 转入需活动条件，转出有24h冷却 |
-| 储藏仓库 | 长期存储稀有物品 | 初始20格，金币解锁 | 物品只进不出 |
-
-**仓库转移规则**：
-1. 可用仓库 → 储藏仓库：无限制
-2. 可用仓库 → 冻结仓库：需满足活动条件
-3. 冻结仓库 → 可用仓库：冷却时间24小时
-4. 储藏仓库物品不可直接使用
-
-### 1.2 仓库转移机制
 ```mermaid
 stateDiagram-v2
     [*] --> 可用仓库
-    可用仓库 --> 储藏仓库： 无限制
-    可用仓库 --> 冻结仓库： 需满足活动条件
-    冻结仓库 --> 可用仓库： 24h冷却后
+    可用仓库 --> 储藏仓库
+    可用仓库 --> 冻结仓库
+    冻结仓库 --> 可用仓库
 ```
 
+> 注意：冷却、只进不出等业务规则由调用模块实现
+
 ## 2. 物品存储设计
 
 ### 2.1 存储模型
 - **统一属性物品**：堆叠存储（同种物品合并）
-  - 最大堆叠量：100（基础物品）/20（稀有物品）
 - **单独属性物品**：独立实例存储
-  - 每个物品独立存储（装备、宠物等）
-  - 支持自定义属性（品质、耐久度等）
 
 ### 2.2 物品获取流程
 ```mermaid
 sequenceDiagram
-    任务系统->>物品模块： 添加物品(物品ID, 数量)
-    物品模块->>仓库系统： 分配目标仓库(按物品类型)
-    仓库系统->>数据库： 创建/更新物品记录
-    数据库-->>仓库系统： 操作结果
+    调用模块->>物品模块： addItem(itemId, quantity, warehouse)
+    物品模块->>仓库系统： 存储物品
+    仓库系统->>数据库： 创建/更新记录
+    数据库-->>仓库系统： 结果
     仓库系统-->>物品模块： 成功通知
-    物品模块-->>任务系统： 完成添加
+    物品模块-->>调用模块： 完成
 ```
 
-## 3. 过期管理系统
-
-### 3.1 过期类型
-| 类型 | 触发条件 | 处理方式 |
-|------|----------|---------|
-| 全局过期 | 到达预设时间点 | 全服物品统一失效 |
-| 用户过期 | 获取后计时 | 按玩家独立计算 |
-
-### 3.2 过期处理流程
-1. 每日3:00执行过期检查
-2. 过期物品移至冻结仓库
-3. 发送过期通知给玩家
-4. 7天后自动清除冻结仓库中的过期物品
+## 3. 基础服务接口
 
-## 4. 变更日志系统
-
-### 4.1 日志记录范围
-| 操作类型 | 记录内容 | 日志级别 |
-|----------|---------|---------|
-| 物品添加 | 来源系统、数量、仓库 | INFO |
-| 物品消耗 | 消耗原因、数量、仓库 | INFO |
-| 物品转移 | 源仓库、目标仓库、数量 | DEBUG |
-| 过期处理 | 过期物品详情 | WARNING |
-
-### 4.2 日志存储结构
-```json
-{
-  "user_id": 123,
-  "item_id": 456,
-  "operation": "add",
-  "quantity": 5,
-  "source": "任务系统",
-  "details": {
-    "task_id": 789,
-    "reward_type": "日常奖励"
-  }
-}
-```
-
-### 4.3 日志查询接口
+### 3.1 核心方法
 ```php
-// 获取用户最近物品变更
-$logs = ItemLogService::getUserLogs(
-    userId: 123, 
-    itemId: 456, 
-    startTime: '2023-01-01',
-    endTime: '2023-12-31'
+// 添加物品到仓库
+ItemService::addItem(
+    userId: int, 
+    itemId: int, 
+    quantity: int, 
+    warehouse: string // 仓库标识
 );
 
-// 响应结构
-[
-    {
-        "id": 1,
-        "operation": "add",
-        "quantity": 5,
-        "item_name": "金币",
-        "created_at": "2023-06-15 10:30:00"
-    }
-]
-```
+// 仓库间转移物品
+ItemService::transferItem(
+    userId: int,
+    itemId: int,
+    fromWarehouse: string,
+    toWarehouse: string,
+    quantity: int
+);
 
-## 5. 扩展属性系统
+// 获取仓库物品列表
+ItemService::getWarehouseItems(
+    userId: int,
+    warehouse: string
+);
+```
 
-### 5.1 特殊属性配置
-通过JSON字段扩展物品功能：
+### 3.2 扩展属性支持
 ```json
-// 宠物蛋物品
-{
-  "pet_type": "cat",
-  "pet_quality": 85
-}
-
-// 神像物品
 {
-  "god_type": 2,
-  "duration": 86400
+  "custom_attr1": "value1",
+  "custom_attr2": 100
 }
 ```
 
-### 5.2 属性验证机制
-- 白名单校验：只允许预定义的属性键
-- 类型检查：数值/字符串严格匹配
-- 范围验证：概率值必须在0-100之间
+### 3.3 属性验证
+- 白名单校验
+- 类型检查
+- 范围验证

app/Module/Item/README.md

@@ -1,75 +1,57 @@
 # Item 基础物品模块
 
-## 概述
-提供物品基础属性管理和多仓库系统：
-- 物品定义（名称、类型、属性）
-- 多仓库支持（可用/冻结/储藏仓库）
-- 仓库间物品转移
-- 物品过期管理
+## 模块定位
+**基础服务模块**，仅提供核心物品管理能力：
+- 不实现具体业务逻辑（如合成、宝箱）
+- 不提供外部API接口
+- 通过静态Service方法供其他模块调用
 
 ## 核心功能
-- **仓库管理**：创建/查询/管理用户仓库
-- **物品存储**：按仓库隔离存储物品
-- **容量控制**：每个仓库独立容量限制
-- **物品转移**：仓库间安全转移物品
-
-## 详细设计
-
-### 仓库系统
-系统支持三种仓库类型，满足不同存储需求：
-
-| 仓库类型 | 功能说明 | 容量限制 |
-|----------|---------|---------|
-| 可用仓库 | 日常使用物品 | 基础容量，可扩展 |
-| 冻结仓库 | 临时保管物品（如活动奖励） | 固定容量 |
-| 储藏仓库 | 长期存储稀有物品 | 高容量，需解锁 |
-
-**仓库转移规则**：
-1. 可用仓库 → 储藏仓库：无限制
-2. 可用仓库 → 冻结仓库：需满足活动条件
-3. 冻结仓库 → 可用仓库：冷却时间24小时
-4. 储藏仓库物品不可直接使用
-
-### 物品存储
-采用双层存储结构：
-1. **统一属性物品**：堆叠存储（支持最大堆叠量）
-2. **单独属性物品**：独立存储（如装备、宠物）
-
-```mermaid
-graph TD
-    A[用户物品] --> B(统一属性)
-    A --> C(单独属性)
-    B --> D[堆叠存储]
-    C --> E[独立实例存储]
-```
-
-### 过期管理
-- **全局过期**：所有玩家统一过期时间（活动物品）
-- **用户过期**：按玩家获取时间计算
-- 过期物品自动移至冻结仓库，保留7天后清除
-
-## 物品属性
-
-### 基础属性
-| 属性 | 类型 | 说明 |
-|------|------|------|
-| `name` | string | 物品名称 |
-| `type` | enum | 物品类型（消耗品/装备等） |
-| `max_stack` | int | 最大堆叠数量 |
-| `tradable` | bool | 是否可交易 |
-
-### 特殊属性
-通过JSON字段扩展功能：
-```json
-{
-  "pet_type": "dog",      // 宠物类型
-  "god_duration": 86400   // 神像持续时间(秒)
-}
+1. **物品定义管理**：
+   - 统一属性物品（堆叠存储）
+   - 单独属性物品（实例存储）
+
+2. **仓库系统**：
+   - 多仓库支持（基础能力）
+   - 仓库间物品转移
+   - 独立容量配置
+
+3. **基础服务**：
+   - 物品添加/获取
+   - 仓库管理
+   - 属性扩展支持
+
+## 服务接口
+```php
+// 添加物品到仓库
+ItemService::addItem(
+    userId: int, 
+    itemId: int, 
+    quantity: int, 
+    warehouse: string
+);
+
+// 仓库间转移物品
+ItemService::transferItem(
+    userId: int,
+    itemId: int,
+    fromWarehouse: string,
+    toWarehouse: string,
+    quantity: int
+);
+
+// 获取仓库物品列表
+ItemService::getWarehouseItems(
+    userId: int,
+    warehouse: string
+);
 ```
 
-## 依赖关系
-- **Game模块**：仓库容量扩展依赖玩家等级
-- **Log模块**：物品操作日志记录
+## 模块依赖
+| 模块 | 依赖类型 | 说明 |
+|------|----------|------|
+| Game | 强依赖 | 仓库容量扩展依赖玩家等级 |
+| Log | 弱依赖 | 物品操作日志记录（可选） |
 
 ## 设计文档
 [Docs/Design.md](Docs/Design.md)