完善物品模块文档：保留事务日志表设计，更新迁移指南和设计文档

app/Module/GameItems_obsolete/OBSOLETE_MIGRATION.md

@@ -7,53 +7,51 @@
 - **ItemCraft**: 物品合成
 - **ItemDismantle**: 物品分解
 
-## 2. 数据表迁移对照
-
-### 2.1 基础物品表
-| 旧表 | 新模块 | 新表 | 说明 |
-|------|--------|------|------|
-| item_items | Item | items | 基础物品定义 |
-| item_categories | Item | 已废弃 | 分类功能由标签系统替代 |
-| item_instances | Item | user_items | 单独属性物品移至用户物品表 |
-| item_users | Item | user_items | 整合到统一用户物品表 |
-
-### 2.2 宝箱系统表
-| 旧表 | 新模块 | 新表 | 说明 |
-|------|--------|------|------|
-| item_chest_configs | ItemChest | chest_configs | 宝箱配置 |
-| item_pity_times | ItemChest | pity_times | 保底计数 |
-| item_chest_open_logs | ItemChest | open_logs | 开启日志 |
-
-### 2.3 物品合成表
-| 旧表 | 新模块 | 新表 | 说明 |
-|------|--------|------|------|
-| item_recipes | ItemCraft | recipes | 配方定义 |
-| item_recipe_materials | ItemCraft | recipe_materials | 配方材料 |
-| item_user_recipes | ItemCraft | user_recipes | 用户配方 |
-| item_craft_logs | ItemCraft | craft_logs | 合成日志 |
-
-### 2.4 物品分解表
-| 旧表 | 新模块 | 新表 | 说明 |
-|------|--------|------|------|
-| item_dismantle_rules | ItemDismantle | dismantle_rules | 分解规则 |
-| item_dismantle_logs | ItemDismantle | dismantle_logs | 分解日志 |
-
-## 3. 特殊处理表
-
-### 3.1 需要人工迁移的表
-| 表名 | 处理方式 |
-|------|----------|
-| item_groups | 迁移到Game模块的奖励组系统 |
-| item_group_items | 迁移到Game模块的奖励组系统 |
-
-### 3.2 功能替代表
-| 表名 | 替代方案 |
-|------|----------|
-| item_output_limits | 由Game模块的全局限制系统替代 |
-| item_user_output_counters | 由Game模块的玩家限制系统替代 |
-
-## 4. 完全废弃的表
-以下表不再使用，数据可归档删除：
-- item_freeze_logs
-- item_transaction_logs
-- item_metrics (所有排行榜相关表)
+## 2. 数据表迁移总表
+
+| 旧表名 | 新模块 | 新表名 | 处理状态 | 说明 |
+|--------|--------|--------|----------|------|
+| **基础物品表** | | | | |
+| item_items | Item | items | ✅ 已迁移 | 基础物品定义 |
+| item_categories | - | - | ⚠️ 废弃 | 分类功能由标签系统替代 |
+| item_instances | Item | user_items | ✅ 已迁移 | 单独属性物品移至用户物品表 |
+| item_users | Item | user_items | ✅ 已迁移 | 整合到统一用户物品表 |
+| **宝箱系统表** | | | | |
+| item_chest_configs | ItemChest | chest_configs | ✅ 已迁移 | 宝箱配置 |
+| item_pity_times | ItemChest | pity_times | ✅ 已迁移 | 保底计数 |
+| item_chest_open_logs | ItemChest | open_logs | ✅ 已迁移 | 开启日志 |
+| **物品合成表** | | | | |
+| item_recipes | ItemCraft | recipes | ✅ 已迁移 | 配方定义 |
+| item_recipe_materials | ItemCraft | recipe_materials | ✅ 已迁移 | 配方材料 |
+| item_user_recipes | ItemCraft | user_recipes | ✅ 已迁移 | 用户配方 |
+| item_craft_logs | ItemCraft | craft_logs | ✅ 已迁移 | 合成日志 |
+| **物品分解表** | | | | |
+| item_dismantle_rules | ItemDismantle | dismantle_rules | ✅ 已迁移 | 分解规则 |
+| item_dismantle_logs | ItemDismantle | dismantle_logs | ✅ 已迁移 | 分解日志 |
+| **物品变更日志** | | | | |
+| item_transaction_logs | Item | transaction_logs | ✅ 已迁移 | 物品获取/消耗记录 |
+| **特殊处理表** | | | | |
+| item_groups | Game | reward_groups | 🔄 需人工迁移 | 迁移到Game模块的奖励组系统 |
+| item_group_items | Game | reward_group_items | 🔄 需人工迁移 | 迁移到Game模块的奖励组系统 |
+| item_output_limits | Game | global_limits | ⚙️ 功能替代 | 由Game模块的全局限制系统替代 |
+| item_user_output_counters | Game | user_limit_counters | ⚙️ 功能替代 | 由Game模块的玩家限制系统替代 |
+| **废弃表** | | | | |
+| item_freeze_logs | - | - | ❌ 废弃删除 | 功能已整合到事务日志 |
+| item_metrics* | - | - | ❌ 废弃删除 | 所有排行榜相关表 |
+
+> 状态说明：  
+> ✅ 已迁移 - 数据已自动迁移  
+> 🔄 需人工迁移 - 需要手动执行迁移脚本  
+> ⚙️ 功能替代 - 新方案完全替代旧功能  
+> ❌ 废弃删除 - 数据可安全删除  
+
+## 3. 迁移进度说明
+- **✅ 自动迁移完成**：基础物品、宝箱、合成、分解相关表
+- **🔄 需人工迁移**：物品组相关表需执行迁移脚本
+- **⚙️ 功能替代**：产出限制由Game模块新机制替代
+- **❌ 废弃表处理**：冻结日志等表可直接归档删除
+
+## 4. 迁移工具
+```bash
+# 执行物品组迁移脚本
+php artisan migrate:item-groups

app/Module/Item/Docs/Database.md

@@ -38,6 +38,19 @@
 | created_at | TIMESTAMP | 创建时间 |  |
 | updated_at | TIMESTAMP | 更新时间 |  |
 
+### 1.4 transaction_logs 物品变更日志表
+| 字段 | 类型 | 说明 | 索引 |
+|------|------|------|------|
+| id | BIGINT | 日志ID，主键 | PK |
+| user_id | BIGINT | 用户ID | IDX_user |
+| item_id | BIGINT | 物品ID | IDX_item |
+| warehouse_id | BIGINT | 仓库ID | IDX_warehouse |
+| quantity | INT | 变动数量 |  |
+| operation | ENUM('add','remove','transfer') | 操作类型 |  |
+| source | VARCHAR(50) | 来源系统 |  |
+| details | JSON | 操作详情 |  |
+| created_at | TIMESTAMP | 创建时间 |  |
+
 ## 2. 表关系设计
 
 ```mermaid
@@ -45,6 +58,7 @@ erDiagram
     users ||--o{ warehouses : "1:N"
     warehouses ||--o{ user_items : "1:N"
     items ||--o{ user_items : "1:N"
+    user_items ||--o{ transaction_logs : "1:N"
     
     users {
         BIGINT id PK
@@ -62,6 +76,12 @@ erDiagram
         BIGINT item_id FK
         BIGINT warehouse_id FK
     }
+    transaction_logs {
+        BIGINT id PK
+        BIGINT user_id FK
+        BIGINT item_id FK
+        BIGINT warehouse_id FK
+    }
 ```
 
 ## 3. 索引设计
@@ -96,6 +116,18 @@ CREATE INDEX idx_user_item_warehouse ON user_items(warehouse_id);
 CREATE INDEX idx_user_item_expire ON user_items(expire_at);
 ```
 
+### 3.4 事务日志表索引
+```sql
+-- 用户操作历史
+CREATE INDEX idx_log_user_operation ON transaction_logs(user_id, operation);
+
+-- 物品操作记录
+CREATE INDEX idx_log_item ON transaction_logs(item_id);
+
+-- 时间范围查询
+CREATE INDEX idx_log_created ON transaction_logs(created_at);
+```
+
 ## 4. 关键查询示例
 
 ### 4.1 获取用户仓库物品
@@ -129,4 +161,18 @@ SELECT
 FROM warehouses w
 LEFT JOIN user_items ui ON w.id = ui.warehouse_id
 WHERE w.user_id = 123
-GROUP BY w.id;
+GROUP BY w.id;
+```
+
+### 4.4 查询物品变更历史
+```sql
+SELECT 
+    tl.operation,
+    tl.quantity,
+    tl.created_at,
+    i.name AS item_name
+FROM transaction_logs tl
+JOIN items i ON tl.item_id = i.id
+WHERE tl.user_id = 123
+  AND tl.created_at BETWEEN '2023-01-01' AND '2023-12-31'
+ORDER BY tl.created_at DESC;

app/Module/Item/Docs/Design.md

@@ -3,12 +3,18 @@
 ## 1. 仓库系统设计
 
 ### 1.1 仓库类型
-| 类型 | 功能 | 容量规则 | 转移限制 |
-|------|------|----------|---------|
-| 可用仓库 | 日常使用物品 | 基础100格，随等级扩展 | 可自由转入储藏仓库 |
-| 冻结仓库 | 临时保管活动物品 | 固定50格 | 转入需活动条件，转出有24h冷却 |
+| 类型 | 功能说明 | 容量限制 | 转移限制 |
+|----------|---------|---------|---------|
+| 可用仓库 | 日常使用物品 | 基础容量，可扩展 | 可自由转入储藏仓库 |
+| 冻结仓库 | 临时保管物品（如活动奖励） | 固定容量 | 转入需活动条件，转出有24h冷却 |
 | 储藏仓库 | 长期存储稀有物品 | 初始20格，金币解锁 | 物品只进不出 |
 
+**仓库转移规则**：
+1. 可用仓库 → 储藏仓库：无限制
+2. 可用仓库 → 冻结仓库：需满足活动条件
+3. 冻结仓库 → 可用仓库：冷却时间24小时
+4. 储藏仓库物品不可直接使用
+
 ### 1.2 仓库转移机制
 ```mermaid
 stateDiagram-v2
@@ -52,9 +58,56 @@ sequenceDiagram
 3. 发送过期通知给玩家
 4. 7天后自动清除冻结仓库中的过期物品
 
-## 4. 扩展属性系统
+## 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 日志查询接口
+```php
+// 获取用户最近物品变更
+$logs = ItemLogService::getUserLogs(
+    userId: 123, 
+    itemId: 456, 
+    startTime: '2023-01-01',
+    endTime: '2023-12-31'
+);
+
+// 响应结构
+[
+    {
+        "id": 1,
+        "operation": "add",
+        "quantity": 5,
+        "item_name": "金币",
+        "created_at": "2023-06-15 10:30:00"
+    }
+]
+```
+
+## 5. 扩展属性系统
 
-### 4.1 特殊属性配置
+### 5.1 特殊属性配置
 通过JSON字段扩展物品功能：
 ```json
 // 宠物蛋物品
@@ -70,7 +123,7 @@ sequenceDiagram
 }
 ```
 
-### 4.2 属性验证机制
+### 5.2 属性验证机制
 - 白名单校验：只允许预定义的属性键
 - 类型检查：数值/字符串严格匹配
 - 范围验证：概率值必须在0-100之间