完善Test模块README.md文档

- 基于物品模块、Mex模块、农场模块的架构设计完善Test模块文档
- 添加详细的目录结构说明和架构设计
- 补充开发规范、命名规范、代码示例
- 增加最佳实践和参考示例
- 提供完整的开发指南和注意事项
- 文档结构清晰，便于新模块开发参考

app/Module/Test/README.md

@@ -1,29 +1,589 @@
 # Test 模块
 
-## 模块说明
-Test 模块是一个示例模块，用于展示模块化开发的最佳实践。
-
-## 目录结构
-```
-├── AdminControllers/    # 后台控制器
-├── Commands/            # 命令目录
-├── Config/              # 配置目录
-├── Database/            # 数据库目录
-│   └── create.sql       # 创建数据表的SQL
-└── Enums/               # 枚举（枚举的名和Case全大写）
-├── Models/              # 模型目录
-├── Providers/           # Providers
-├── Events/              # 事件目录
-├── Logic/               # Logic目录/逻辑目录
-├── Listeners/           # 监听器目录 
-├── Queues/              # 队列目录
-├── Repositorys/         # 仓库目录（后台控制器专用，其他场景不要用）
-├── Services/            # 服务目录（供其他模块使用）
-│   └──  TestService.php       # 服务之一
-├── Validations/         # Validation 目录（不是Laravel的Validation规则）
-├── Validators/          # Validator目录
-└── Tests/               # 测试目录
-```
-
-## 注意事项
+> 示例模块 - 展示模块化开发的最佳实践和标准架构
+
+## 目录
+
+1. [模块概述](#1-模块概述)
+2. [目录结构](#2-目录结构)
+3. [架构设计](#3-架构设计)
+4. [开发规范](#4-开发规范)
+5. [最佳实践](#5-最佳实践)
+6. [参考示例](#6-参考示例)
+
+## 1. 模块概述
+
+### 1.1 功能与目的
+
+Test模块是一个标准的示例模块，用于展示项目中模块化开发的最佳实践。它提供了完整的模块架构参考，包括数据层、业务逻辑层、服务层、控制器层等各个层次的标准实现方式。
+
+### 1.2 主要特点
+
+- **标准架构**：遵循项目统一的分层架构设计
+- **完整示例**：包含所有必要的目录和文件结构
+- **最佳实践**：展示代码组织、命名规范、设计模式等最佳实践
+- **参考模板**：为新模块开发提供标准模板
+
+## 2. 目录结构
+
+### 2.1 完整目录树
+
+```
+app/Module/Test/
+├── AdminControllers/           # 后台管理控制器
+│   ├── Helper/                # 控制器辅助类
+│   │   ├── TestGridHelper.php # 表格辅助类
+│   │   ├── TestFormHelper.php # 表单辅助类
+│   │   └── TestFilterHelper.php # 筛选辅助类
+│   ├── Actions/               # 控制器动作类
+│   │   └── TestExportAction.php # 导出动作
+│   └── TestController.php     # 主控制器
+├── Commands/                   # 命令行工具
+│   └── TestCommand.php        # 示例命令
+├── Config/                     # 配置文件
+│   └── test.php               # 模块配置
+├── Databases/                  # 数据库相关
+│   ├── GenerateSql/           # SQL文件
+│   │   ├── test_items.sql     # 创建数据表的SQL
+│   │   └── test_logs.sql      # 日志表SQL
+│   └── Repositories/          # 数据仓库（后台专用）
+│       └── TestRepository.php # 测试仓库
+├── Docs/                       # 文档目录
+│   ├── README.md              # 模块文档索引
+│   ├── 设计文档.md             # 设计文档
+│   └── 开发指南.md             # 开发指南
+├── Dtos/                       # 数据传输对象
+│   └── TestDto.php            # 测试DTO
+├── Enums/                      # 枚举类型定义
+│   ├── TEST_STATUS.php        # 状态枚举
+│   └── TEST_TYPE.php          # 类型枚举
+├── Events/                     # 事件类
+│   └── TestCreatedEvent.php   # 测试创建事件
+├── Exceptions/                 # 自定义异常
+│   └── TestException.php      # 测试异常
+├── Listeners/                  # 事件监听器
+│   └── TestCreatedListener.php # 测试创建监听器
+├── Logics/                     # 业务逻辑类（内部使用）
+│   └── Test.php               # 测试逻辑
+├── Models/                     # 数据模型
+│   ├── TestItem.php           # 测试项目模型
+│   └── TestLog.php            # 测试日志模型
+├── Providers/                  # 服务提供者
+│   └── TestServiceProvider.php # 测试服务提供者
+├── Services/                   # 服务类（对外接口）
+│   └── TestService.php        # 测试服务
+├── Validations/                # 验证类（业务验证）
+│   └── TestCreateValidation.php # 创建验证
+├── Validators/                 # 验证器（单一验证逻辑）
+│   └── TestStatusValidator.php # 状态验证器
+└── Tests/                      # 测试目录
+    ├── TestServiceTest.php     # 服务测试
+    └── test_manual.php         # 手动测试脚本
+```
+
+### 2.2 目录说明
+
+| 目录 | 用途 | 说明 |
+|------|------|------|
+| **AdminControllers/** | 后台管理界面 | 继承自UCore\DcatAdmin\AdminController |
+| **Commands/** | 命令行工具 | 定时任务、数据处理等命令 |
+| **Config/** | 配置文件 | 模块相关配置参数 |
+| **Databases/** | 数据库相关 | SQL文件和Repository类 |
+| **Docs/** | 文档目录 | 模块设计和开发文档 |
+| **Dtos/** | 数据传输对象 | 继承自UCore\Dto\BaseDto |
+| **Enums/** | 枚举定义 | 使用PHP enum语法，避免魔法数字 |
+| **Events/** | 事件类 | 模块间通信事件 |
+| **Exceptions/** | 自定义异常 | 业务异常处理 |
+| **Listeners/** | 事件监听器 | 处理事件响应 |
+| **Logics/** | 业务逻辑 | 内部业务处理，不对外暴露 |
+| **Models/** | 数据模型 | 继承自UCore\ModelCore，无业务逻辑 |
+| **Providers/** | 服务提供者 | 注册服务和事件 |
+| **Services/** | 服务接口 | 对外提供功能，调用Logics层 |
+| **Validations/** | 验证类 | 复合验证逻辑 |
+| **Validators/** | 验证器 | 单一验证逻辑 |
+| **Tests/** | 测试文件 | 单元测试和手动测试 |
+
+## 3. 架构设计
+
+### 3.1 分层架构
+
+Test模块采用标准的分层架构设计：
+
+```
+┌─────────────────┐
+│   Controllers   │ ← HTTP请求处理
+├─────────────────┤
+│    Services     │ ← 对外服务接口
+├─────────────────┤
+│     Logics      │ ← 内部业务逻辑
+├─────────────────┤
+│     Models      │ ← 数据模型层
+└─────────────────┘
+```
+
+### 3.2 设计原则
+
+1. **单一职责原则**：每个类只负责一个功能领域
+2. **关注点分离**：模型只负责数据结构，业务逻辑由Logic类处理
+3. **依赖注入**：通过构造函数注入依赖，提高可测试性
+4. **事务完整性**：涉及多个操作的功能使用数据库事务
+5. **日志记录**：关键操作记录详细日志
+
+### 3.3 模块交互
+
+- **服务层对外**：其他模块只能通过Services层访问功能
+- **逻辑层内部**：Logic类处理具体业务规则
+- **事件通信**：模块间通过事件进行松耦合通信
+- **数据访问**：Repository层仅供后台管理使用
+
+## 4. 开发规范
+
+### 4.1 命名规范
+
+#### 4.1.1 类命名
+- **模型类**：继承自`\UCore\ModelCore`，如`TestItem`
+- **服务类**：以`Service`结尾，如`TestService`
+- **逻辑类**：简单类名，如`Test`
+- **验证类**：以`Validation`结尾，如`TestCreateValidation`
+- **验证器**：以`Validator`结尾，如`TestStatusValidator`
+- **枚举类**：全大写，如`TEST_STATUS`
+- **DTO类**：以`Dto`结尾，如`TestDto`
+
+#### 4.1.2 数据库命名
+- **表名前缀**：使用模块前缀，如`test_`
+- **全局前缀**：所有表都有`kku_`前缀
+- **完整表名**：`kku_test_items`、`kku_test_logs`
+
+#### 4.1.3 命名空间
+- **基础命名空间**：`App\Module\Test`
+- **Handler命名空间**：`App\Module\AppGame\Handler`（接口层）
+
+### 4.2 代码规范
+
+#### 4.2.1 模型设计
+```php
+<?php
+
+namespace App\Module\Test\Models;
+
+use UCore\ModelCore;
+
+/**
+ * 测试项目模型
+ *
+ * field start
+ * @property int $id 主键ID
+ * @property string $name 项目名称
+ * @property int $status 状态
+ * @property \Carbon\Carbon $created_at 创建时间
+ * @property \Carbon\Carbon $updated_at 更新时间
+ * field end
+ */
+class TestItem extends ModelCore
+{
+    // attrlist start
+    protected $fillable = [
+        'name',
+        'status',
+    ];
+    // attrlist end
+
+    /**
+     * 状态访问器
+     */
+    public function getStatusNameAttribute(): string
+    {
+        return TEST_STATUS::getName($this->status);
+    }
+}
+```
+
+#### 4.2.2 服务层设计
+```php
+<?php
+
+namespace App\Module\Test\Services;
+
+use App\Module\Test\Dtos\TestDto;
+use App\Module\Test\Logics\Test as TestLogic;
+
+/**
+ * 测试服务类
+ *
+ * 对外提供测试相关功能接口
+ */
+class TestService
+{
+    /**
+     * 创建测试项目
+     *
+     * @param array $data 项目数据
+     * @return TestDto
+     */
+    public static function createTest(array $data): TestDto
+    {
+        $result = TestLogic::createTest($data);
+        return TestDto::fromModel($result);
+    }
+
+    /**
+     * 获取测试项目列表
+     *
+     * @param array $filters 筛选条件
+     * @return array
+     */
+    public static function getTestList(array $filters = []): array
+    {
+        return TestLogic::getTestList($filters);
+    }
+}
+```
+
+#### 4.2.3 枚举设计
+```php
+<?php
+
+namespace App\Module\Test\Enums;
+
+/**
+ * 测试状态枚举
+ */
+enum TEST_STATUS: int
+{
+    case PENDING = 1;    // 待处理
+    case PROCESSING = 2; // 处理中
+    case COMPLETED = 3;  // 已完成
+    case FAILED = 4;     // 失败
+
+    /**
+     * 获取状态名称
+     */
+    public function getName(): string
+    {
+        return match ($this) {
+            self::PENDING => '待处理',
+            self::PROCESSING => '处理中',
+            self::COMPLETED => '已完成',
+            self::FAILED => '失败',
+        };
+    }
+
+    /**
+     * 获取所有状态
+     */
+    public static function getAll(): array
+    {
+        return [
+            self::PENDING->value => self::PENDING->getName(),
+            self::PROCESSING->value => self::PROCESSING->getName(),
+            self::COMPLETED->value => self::COMPLETED->getName(),
+            self::FAILED->value => self::FAILED->getName(),
+        ];
+    }
+}
+```
+
+### 4.3 验证机制
+
+#### 4.3.1 Validation类
+```php
+<?php
+
+namespace App\Module\Test\Validations;
+
+use UCore\Validation\ValidationCore;
+
+/**
+ * 测试创建验证类
+ */
+class TestCreateValidation extends ValidationCore
+{
+    public function rules($rules = []): array
+    {
+        return [
+            ['name', 'required'],
+            ['name', 'string', 'max' => 255],
+            ['status', 'integer', 'min' => 1],
+        ];
+    }
+
+    public function default(): array
+    {
+        return [
+            'status' => TEST_STATUS::PENDING->value,
+        ];
+    }
+}
+```
+
+#### 4.3.2 Validator类
+```php
+<?php
+
+namespace App\Module\Test\Validators;
+
+use UCore\Validation\ValidatorCore;
+
+/**
+ * 测试状态验证器
+ */
+class TestStatusValidator extends ValidatorCore
+{
+    public function validate($value, $arg = null): bool
+    {
+        if (!in_array($value, array_keys(TEST_STATUS::getAll()))) {
+            $this->addError($arg, '状态值无效');
+            return false;
+        }
+        return true;
+    }
+}
+```
+
+## 5. 最佳实践
+
+### 5.1 数据库设计
+
+#### 5.1.1 表结构设计
+```sql
+-- 测试项目表
+CREATE TABLE `kku_test_items` (
+  `id` int NOT NULL AUTO_INCREMENT COMMENT '主键ID',
+  `name` varchar(255) NOT NULL COMMENT '项目名称',
+  `description` text COMMENT '项目描述',
+  `status` tinyint NOT NULL DEFAULT 1 COMMENT '状态：1待处理，2处理中，3已完成，4失败',
+  `config` json DEFAULT NULL COMMENT '配置信息',
+  `created_at` timestamp NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+  `updated_at` timestamp NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  KEY `idx_status` (`status`),
+  KEY `idx_created_at` (`created_at`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='测试项目表';
+
+-- 测试日志表
+CREATE TABLE `kku_test_logs` (
+  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '日志ID',
+  `test_id` int NOT NULL COMMENT '测试项目ID',
+  `action` varchar(100) NOT NULL COMMENT '操作类型',
+  `message` text COMMENT '日志消息',
+  `data` json DEFAULT NULL COMMENT '相关数据',
+  `created_at` timestamp NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+  PRIMARY KEY (`id`),
+  KEY `idx_test_id` (`test_id`),
+  KEY `idx_action` (`action`),
+  KEY `idx_created_at` (`created_at`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='测试日志表';
+```
+
+#### 5.1.2 索引设计原则
+- **主键索引**：每个表必须有主键
+- **外键索引**：关联字段建立索引
+- **查询索引**：常用查询条件建立索引
+- **复合索引**：多字段查询建立复合索引
+
+### 5.2 事件系统
+
+#### 5.2.1 事件定义
+```php
+<?php
+
+namespace App\Module\Test\Events;
+
+use App\Module\Test\Models\TestItem;
+use Illuminate\Foundation\Events\Dispatchable;
+
+/**
+ * 测试创建事件
+ */
+class TestCreatedEvent
+{
+    use Dispatchable;
+
+    public TestItem $testItem;
+
+    public function __construct(TestItem $testItem)
+    {
+        $this->testItem = $testItem;
+    }
+}
+```
+
+#### 5.2.2 事件监听器
+```php
+<?php
+
+namespace App\Module\Test\Listeners;
+
+use App\Module\Test\Events\TestCreatedEvent;
+
+/**
+ * 测试创建监听器
+ */
+class TestCreatedListener
+{
+    public function handle(TestCreatedEvent $event): void
+    {
+        // 处理测试创建后的逻辑
+        // 如：发送通知、更新统计等
+    }
+}
+```
+
+### 5.3 后台管理
+
+#### 5.3.1 控制器设计
+```php
+<?php
+
+namespace App\Module\Test\AdminControllers;
+
+use App\Module\Test\AdminControllers\Helper\TestGridHelper;
+use App\Module\Test\AdminControllers\Helper\TestFormHelper;
+use App\Module\Test\Repositories\TestRepository;
+use UCore\DcatAdmin\AdminController;
+
+/**
+ * 测试后台控制器
+ *
+ * @route /admin/test-items
+ */
+class TestController extends AdminController
+{
+    protected string $title = '测试管理';
+    protected string $repository = TestRepository::class;
+
+    protected function grid()
+    {
+        return TestGridHelper::make($this->repository());
+    }
+
+    protected function form()
+    {
+        return TestFormHelper::make();
+    }
+}
+```
+
+### 5.4 测试规范
+
+#### 5.4.1 单元测试
+```php
+<?php
+
+namespace App\Module\Test\Tests;
+
+use App\Module\Test\Services\TestService;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * 测试服务单元测试
+ */
+class TestServiceTest extends TestCase
+{
+    public function testCreateTest()
+    {
+        $data = [
+            'name' => '测试项目',
+            'description' => '这是一个测试项目',
+        ];
+
+        $result = TestService::createTest($data);
+
+        $this->assertNotNull($result);
+        $this->assertEquals($data['name'], $result->name);
+    }
+}
+```
+
+#### 5.4.2 手动测试
+```php
+<?php
+// app/Module/Test/Tests/test_manual.php
+
+require_once __DIR__ . '/../../../../bootstrap/app.php';
+
+use App\Module\Test\Services\TestService;
+
+// 测试创建功能
+$data = [
+    'name' => '手动测试项目',
+    'description' => '手动测试描述',
+];
+
+try {
+    $result = TestService::createTest($data);
+    echo "创建成功：" . json_encode($result, JSON_UNESCAPED_UNICODE) . "\n";
+} catch (Exception $e) {
+    echo "创建失败：" . $e->getMessage() . "\n";
+}
+```
+
+## 6. 参考示例
+
+### 6.1 物品模块参考
+
+Test模块可以参考GameItems模块的以下设计：
+
+- **冻结功能**：物品冻结机制的实现方式
+- **拆堆模式**：统一属性物品的数量管理
+- **事务处理**：多步骤操作的事务保护
+- **日志记录**：完整的操作审计机制
+
+### 6.2 Mex模块参考
+
+Test模块可以参考Mex模块的以下设计：
+
+- **撮合算法**：复杂业务逻辑的处理方式
+- **状态机**：订单状态的流转管理
+- **定时任务**：后台任务的设计模式
+- **多币种适配**：灵活的配置管理
+
+### 6.3 农场模块参考
+
+Test模块可以参考Farm模块的以下设计：
+
+- **生长周期**：时间相关业务的处理
+- **灾害系统**：随机事件的实现机制
+- **升级系统**：进度管理的设计模式
+- **神灵加持**：临时效果的管理方式
+
+## 7. 开发指南
+
+### 7.1 新建模块步骤
+
+1. **创建目录结构**：按照标准目录结构创建文件夹
+2. **定义枚举类型**：先定义业务相关的枚举
+3. **设计数据模型**：创建数据库表和模型类
+4. **实现业务逻辑**：编写Logic类处理业务规则
+5. **提供服务接口**：创建Service类对外提供功能
+6. **添加验证机制**：实现Validation和Validator类
+7. **创建后台管理**：实现AdminController和Helper类
+8. **编写测试用例**：添加单元测试和手动测试
+9. **完善文档**：编写详细的模块文档
+
+### 7.2 注意事项
+
+1. **模型无业务逻辑**：模型只负责数据结构定义
+2. **服务层对外**：其他模块只能通过Service层访问
+3. **事务保护**：多步骤操作必须使用数据库事务
+4. **异常处理**：Handler中不设置异常处理，继续抛出
+5. **日志记录**：关键操作记录详细日志
+6. **中文注释**：代码中添加中文注释说明
+7. **文档维护**：及时更新模块文档
+
+### 7.3 扩展建议
+
+1. **功能扩展**：基于现有架构添加新功能
+2. **性能优化**：添加缓存机制和索引优化
+3. **监控告警**：实现业务监控和异常告警
+4. **国际化**：支持多语言和多地区
+5. **API接口**：提供RESTful API接口
+6. **移动端适配**：支持移动端应用接入
+
+---
+
+**最后更新时间**：2025年06月16日
+**文档版本**：v1.0
+**维护人员**：开发团队
+```