1

README.md

@@ -1 +1,4 @@
 # KK-U
+
+
+• 编辑工具增强: search_and_replace 和 insert_content 工具已得到改进，并从实验性状态毕业

app/Module/GameItems/README.roo.md

@@ -1,302 +0,0 @@
-# GameItems 模块设计文档
-
-## 模块概述
-GameItems模块负责游戏内物品系统的管理，包括基础物品属性和特殊物品(如宝箱)的管理。
-
-## 功能特性
-1. **物品基础管理**
-   - 名称、TID、类型等基础属性管理
-   - 物品获取与消耗逻辑
-   - 库存管理及变更事件通知
-
-2. **宝箱类物品**
-   - 多物品宝箱系统：支持一个宝箱同时掉落多个物品
-   - 可配置每个物品的数量范围和概率
-   - 宝箱开启记录
-
-3. **过期机制**
-   - 全局过期时间设置
-   - 用户特定过期时间设置
-
-4. **属性系统**
-   - 键值对存储物品属性
-   - 支持复杂物品效果实现
-
-## 目录结构
-```
-GameItems/
-├── Actions/                # 物品操作类
-├── Enums/                  # 枚举类
-├── Events/                 # 事件类
-├── Handlers/               # 处理器
-├── Models/                 # 模型
-├── Repositories/           # 数据仓库
-├── Services/               # 服务类
-├── Validations/            # 验证类
-├── README.md               # 模块说明
-└── README.roo.md           # 设计文档
-```
-
-## 核心类设计
-
-### 1. Item (基础物品)
-- **属性**:
-  - tid: 物品唯一标识
-  - name: 物品名称
-  - type: 物品类型
-  - display_attrs: 展示属性(JSON) - 名称、描述、图标等
-  - numeric_attrs: 数值属性(JSON) - 攻击力、耐久度等
-  - expire_at: 全局过期时间
-
-- **方法**:
-  - acquire(): 获取物品
-  - consume(): 消耗物品
-  - checkExpired(): 检查是否过期
-
-### 4. ItemInstance (物品实例类)
-- **属性**:
-  - instance_id: 实例唯一ID
-  - item_tid: 物品模板ID
-  - display_attrs: 实例展示属性(JSON) - 自定义名称、皮肤等
-  - numeric_attrs: 实例数值属性(JSON) - 当前耐久度、附加属性等
-  - expire_at: 过期时间
-
-- **方法**:
-  - updateAttributes(): 更新实例属性
-  - checkExpired(): 检查是否过期
-  - serialize(): 序列化为数组
-
-### 2. Chest (宝箱类)
-继承自Item，增加宝箱特有功能:
-- **属性**:
-  - rewards: 奖励配置(JSON)
-  - open_limit: 开启限制
-
-- **方法**:
-  - open(): 开启宝箱
-  - getRewards(): 获取奖励配置
-  - recordOpen(): 记录开启
-
-### 3. ItemService (物品服务)
-- **方法**:
-  - getItem(tid): 获取物品模板
-  - getItemInstance(instance_id): 获取物品实例
-  - createItemInstance(user_id, item_tid, attributes): 创建物品实例
-  - updateInventory(): 更新可堆叠物品库存
-  - updateItemInstance(instance_id, attributes): 更新物品实例属性
-  - dispatchEvent(): 分发物品事件
-
-## 使用示例
-
-### 获取物品
-```php
-$item = ItemService::getItem('item_tid');
-$item->acquire($user, $amount);
-```
-
-### 开启宝箱
-```php
-$chest = ItemService::getItem('chest_tid');
-$rewards = $chest->open($user);
-```
-
-## 数据库设计
-
-### 1. 物品基础表 (game_items)
-```sql
-CREATE TABLE `game_items` (
-  `id` bigint unsigned NOT NULL AUTO_INCREMENT,
-  `tid` varchar(64) NOT NULL COMMENT '物品唯一标识',
-  `name` varchar(128) NOT NULL COMMENT '物品名称',
-  `type` varchar(32) NOT NULL COMMENT '物品类型',
-  `display_attrs` json DEFAULT NULL COMMENT '展示属性(名称、描述、图标等)',
-  `numeric_attrs` json DEFAULT NULL COMMENT '数值属性(攻击力、耐久度等)',
-  `expire_at` timestamp NULL DEFAULT NULL COMMENT '全局过期时间',
-  `created_at` timestamp NULL DEFAULT NULL,
-  `updated_at` timestamp NULL DEFAULT NULL,
-  PRIMARY KEY (`id`),
-  UNIQUE KEY `game_items_tid_unique` (`tid`)
-) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
-```
-
-### 7. 物品组表 (item_groups)
-```sql
-CREATE TABLE `item_groups` (
-  `id` bigint unsigned NOT NULL AUTO_INCREMENT,
-  `group_id` varchar(64) NOT NULL COMMENT '组ID',
-  `name` varchar(128) NOT NULL COMMENT '组名称',
-  `items` json NOT NULL COMMENT '组内物品配置',
-  `created_at` timestamp NULL DEFAULT NULL,
-  `updated_at` timestamp NULL DEFAULT NULL,
-  PRIMARY KEY (`id`),
-  UNIQUE KEY `item_groups_group_id_unique` (`group_id`)
-) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
-```
-
-### 2. 宝箱配置表 (game_chests)
-```sql
-CREATE TABLE `game_chests` (
-  `id` bigint unsigned NOT NULL AUTO_INCREMENT,
-  `item_tid` varchar(64) NOT NULL COMMENT '关联物品TID',
-  `rewards` json NOT NULL COMMENT '奖励配置(可配置物品或物品组)',
-  `open_limit` int DEFAULT NULL COMMENT '开启限制',
-  `created_at` timestamp NULL DEFAULT NULL,
-  `updated_at` timestamp NULL DEFAULT NULL,
-  PRIMARY KEY (`id`),
-  UNIQUE KEY `game_chests_item_tid_unique` (`item_tid`)
-) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
-```
-
-#### 物品组配置示例
-```json
-{
-  "group_id": "weapon_group_1",
-  "name": "初级武器组",
-  "items": [
-    {
-      "item_tid": "sword_1",
-      "weight": 30
-    },
-    {
-      "item_tid": "axe_1",
-      "weight": 20
-    }
-  ]
-}
-```
-
-#### 宝箱奖励配置支持物品组
-```json
-{
-  "rewards": [
-    {
-      "type": "group",
-      "group_id": "weapon_group_1",
-      "count": 1
-    }
-  ]
-}
-```
-
-#### 奖励配置(rewards)JSON结构说明
-```json
-{
-  "rewards": [
-    {
-      "item_tid": "物品TID",
-      "min": 1,
-      "max": 3,
-      "probability": 0.5,
-      "conditions": {
-        "level": 10,
-        "vip_level": 3
-      }
-    }
-  ],
-  "guarantees": [
-    {
-      "item_tid": "保底物品TID",
-      "count": 10,
-      "amount": 1
-    }
-  ]
-}
-```
-
-字段说明：
-- `rewards`: 常规奖励列表
-  - `item_tid`: 奖励物品TID
-  - `min`: 最小数量
-  - `max`: 最大数量
-  - `probability`: 掉落概率(0-1)
-  - `conditions`: 获取条件(可选)
-- `guarantees`: 保底奖励列表(可选)
-  - `item_tid`: 保底物品TID
-  - `count`: 开启次数达到后触发
-  - `amount`: 奖励数量
-
-### 3. 用户物品库存表 (item_users)
-```sql
-CREATE TABLE `item_users` (
-  `id` bigint unsigned NOT NULL AUTO_INCREMENT,
-  `user_id` bigint unsigned NOT NULL COMMENT '用户ID',
-  `item_tid` varchar(64) NOT NULL COMMENT '物品TID',
-  `quantity` int NOT NULL DEFAULT '0' COMMENT '数量(仅用于可堆叠物品)',
-  `expire_at` timestamp NULL DEFAULT NULL COMMENT '用户特定过期时间',
-  `created_at` timestamp NULL DEFAULT NULL,
-  `updated_at` timestamp NULL DEFAULT NULL,
-  PRIMARY KEY (`id`),
-  UNIQUE KEY `user_items_user_id_item_tid_unique` (`user_id`,`item_tid`)
-) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
-```
-
-### 6. 物品实例表 (item_instances)
-```sql
-CREATE TABLE `item_instances` (
-  `id` bigint unsigned NOT NULL AUTO_INCREMENT,
-  `user_id` bigint unsigned NOT NULL COMMENT '用户ID',
-  `item_tid` varchar(64) NOT NULL COMMENT '物品TID',
-  `instance_id` varchar(64) NOT NULL COMMENT '实例唯一ID',
-  `display_attrs` json NOT NULL COMMENT '展示属性(名称、图标、皮肤等)',
-  `numeric_attrs` json NOT NULL COMMENT '数值属性(攻击力、耐久度等)',
-  `expire_at` timestamp NULL DEFAULT NULL COMMENT '过期时间',
-  `created_at` timestamp NULL DEFAULT NULL,
-  `updated_at` timestamp NULL DEFAULT NULL,
-  PRIMARY KEY (`id`),
-  UNIQUE KEY `item_instances_instance_id_unique` (`instance_id`),
-  KEY `item_instances_user_id_index` (`user_id`),
-  KEY `item_instances_item_tid_index` (`item_tid`)
-) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
-```
-
-#### 物品实例化设计说明
-1. **可堆叠物品**：使用user_items表记录数量
-2. **不可堆叠物品**：使用item_instances表记录每个实例
-   - 每把"刀"作为一个独立实例存储
-   - 每个实例有唯一的instance_id
-   - 实例属性存储在attributes字段(JSON)
-3. **混合模式**：某些物品可同时支持两种存储方式
-
-### 4. 宝箱开启记录表 (chest_open_logs)
-```sql
-CREATE TABLE `chest_open_logs` (
-  `id` bigint unsigned NOT NULL AUTO_INCREMENT,
-  `user_id` bigint unsigned NOT NULL COMMENT '用户ID',
-  `chest_tid` varchar(64) NOT NULL COMMENT '宝箱TID',
-  `rewards` json NOT NULL COMMENT '获得的奖励',
-  `opened_at` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '开启时间',
-  PRIMARY KEY (`id`),
-  KEY `chest_open_logs_user_id_index` (`user_id`),
-  KEY `chest_open_logs_chest_tid_index` (`chest_tid`)
-) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
-```
-
-### 5. 用户宝箱开启计数表 (user_chest_counts)
-```sql
-CREATE TABLE `user_chest_counts` (
-  `id` bigint unsigned NOT NULL AUTO_INCREMENT,
-  `user_id` bigint unsigned NOT NULL COMMENT '用户ID',
-  `chest_tid` varchar(64) NOT NULL COMMENT '宝箱TID',
-  `open_count` int NOT NULL DEFAULT 0 COMMENT '开启次数',
-  `last_opened_at` timestamp NULL DEFAULT NULL COMMENT '最后开启时间',
-  `created_at` timestamp NULL DEFAULT NULL,
-  `updated_at` timestamp NULL DEFAULT NULL,
-  PRIMARY KEY (`id`),
-  UNIQUE KEY `user_chest_counts_user_chest_unique` (`user_id`, `chest_tid`)
-) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
-```
-
-#### 保底奖励实现逻辑
-1. 用户每次开启宝箱时，更新`user_chest_counts`表中的`open_count`
-2. 当`open_count`达到保底配置中的`count`值时：
-   - 发放保底奖励
-   - 重置该宝箱的`open_count`为0
-3. 保底奖励与常规奖励可同时获得
-
-## 开发规范
-1. 所有物品操作必须通过Validation验证
-2. 物品属性使用JSON存储，避免频繁修改表结构
-3. 库存变更必须触发相应事件
-4. 宝箱奖励配置使用概率表，便于调整
-5. 过期时间支持Carbon对象处理
-6. 数据库变更需人工执行上述SQL语句