# Test 模块

> 示例模块 - 展示模块化开发的最佳实践和标准架构

## 目录

1. [模块概述](#1-模块概述)
2. [目录结构](#2-目录结构)
3. [架构设计](#3-架构设计)
4. [开发规范](#4-开发规范)
5. [最佳实践](#5-最佳实践)
6. [参考示例](#6-参考示例)

## 1. 模块概述

### 1.1 功能与目的

Test模块是一个标准的示例模块，用于展示项目中模块化开发的最佳实践。它提供了完整的模块架构参考，包括数据层、业务逻辑层、服务层、控制器层等各个层次的标准实现方式。

### 1.2 主要特点

- **标准架构**：遵循项目统一的分层架构设计
- **完整示例**：包含所有必要的目录和文件结构
- **最佳实践**：展示代码组织、命名规范、设计模式等最佳实践
- **参考模板**：为新模块开发提供标准模板
- **逻辑模块**：默认不提供Api、前端页面，专注业务逻辑实现
- **注解路由**：使用注解方式注册路由，不使用路由配置文件
- **中文友好**：支持中文注释和文档，便于团队协作

## 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               # 模块配置
├── Casts/                      # 自定义类型转换器
│   └── TestAttributesCast.php # 测试属性转换器
├── Databases/                  # 数据库相关
│   └── create.sql             # 数据库创建脚本
├── 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 # 测试服务提供者
├── Repositorys/                # 数据仓库（后台专用）
│   └── TestRepository.php     # 测试仓库
├── Services/                   # 服务类（对外接口）
│   └── TestService.php        # 测试服务
├── Validations/                # 验证类（业务验证）
│   └── TestCreateValidation.php # 创建验证
├── Validators/                 # 验证器（单一验证逻辑）
│   └── TestStatusValidator.php # 状态验证器
└── Tests/                      # 测试目录
    ├── TestServiceTest.php     # 服务测试
    └── test_manual.php         # 手动测试脚本
```

### 2.2 目录说明

| 目录 | 用途 | 说明 |
|------|------|------|
| **AdminControllers/** | 后台管理界面 | 继承自UCore\DcatAdmin\AdminController |
| **Commands/** | 命令行工具 | 定时任务、数据处理等命令 |
| **Casts/** | 自定义类型转换器 | 处理JSON属性等特殊字段 |
| **Config/** | 配置文件 | 模块相关配置参数 |
| **Databases/** | 数据库相关 | SQL创建脚本 |
| **Docs/** | 文档目录 | 模块设计和开发文档 |
| **Dtos/** | 数据传输对象 | 继承自UCore\Dto\BaseDto |
| **Enums/** | 枚举定义 | 使用PHP enum语法，避免魔法数字 |
| **Events/** | 事件类 | 模块间通信事件 |
| **Exceptions/** | 自定义异常 | 业务异常处理 |
| **Listeners/** | 事件监听器 | 处理事件响应 |
| **Logics/** | 业务逻辑 | 内部业务处理，不对外暴露 |
| **Models/** | 数据模型 | 继承自UCore\ModelCore，无业务逻辑 |
| **Providers/** | 服务提供者 | 注册服务和事件 |
| **Repositorys/** | 数据仓库 | 封装数据库操作，仅供后台管理使用 |
| **Services/** | 服务接口 | 对外提供功能，调用Logics层 |
| **Validations/** | 验证类 | 复合验证逻辑 |
| **Validators/** | 验证器 | 单一验证逻辑 |
| **Tests/** | 测试文件 | 单元测试和手动测试 |

## 3. 架构设计

### 3.1 分层架构

Test模块采用标准的分层架构设计：

```
┌─────────────────┐
│   Controllers   │ ← HTTP请求处理（非对外模块不提供）
├─────────────────┤
│    Services     │ ← 对外服务接口
├─────────────────┤
│     Logics      │ ← 内部业务逻辑
├─────────────────┤
│     Models      │ ← 数据模型层
└─────────────────┘
```

### 3.2 设计原则

1. **单一职责原则**：每个类只负责一个功能领域
2. **关注点分离**：模型只负责数据结构，业务逻辑由Logic类处理
3. **依赖注入**：通过构造函数注入依赖，提高可测试性
4. **事务完整性**：涉及多个操作的功能使用数据库事务（注意：Logic层不能开启事务）
5. **日志记录**：关键操作记录详细日志
6. **简单设计**：功能拆分为独立简单静态类，避免复杂设计模式
7. **中文注释**：代码中增加中文注释，提高可读性
8. **异常透传**：Handler中不设置异常处理，继续抛出异常交由框架处理

### 3.3 模块交互

- **服务层对外**：其他模块只能通过Services层访问功能，不直接访问其他模块模型
- **逻辑层内部**：Logic类处理具体业务规则，服务层直接使用逻辑层和模型
- **事件通信**：模块间通过事件进行松耦合通信，模块内部不使用事件机制
- **数据访问**：Repositorys层仅供后台管理使用，参考Fund模块实现
- **DTO传输**：服务层返回DTO对象而非Model，Handler中将DTO转换为protobuf格式
- **响应规范**：Handler成功时使用RESPONSE_CODE常量设置响应码，不使用魔法数字0

## 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_`（物品模块`item_`，宠物模块`pet_`）
- **全局前缀**：所有表都有`kku_`前缀（在config/database.php中全局配置）
- **完整表名**：`kku_test_items`、`kku_test_logs`
- **币种标识**：币种ID指FUND_CURRENCY_TYPE枚举value值（1=金币,2=钻石,3=人民币,4=美元）

#### 4.1.3 命名空间
- **基础命名空间**：`App\Module\Test`
- **Handler命名空间**：`App\Module\AppGame\Handler`（接口层，专门的对外接口模块）
- **路由使用注解**：不使用路由配置文件，采用注解方式注册路由
- **模块定位**：模块默认不提供Api、前端页面，为逻辑模块

### 4.2 代码规范

#### 4.2.1 模型设计
```php
<?php

namespace App\Module\Test\Models;

use UCore\ModelCore;

/**
 * 测试项目模型
 *
 * 设计原则：
 * - 继承自\UCore\ModelCore，保持无业务逻辑
 * - 不设置$prefix属性（全局配置在config/database.php）
 * - 在模型中定义访问器而非控制器中实现逻辑
 * - 为模型创建独立Cast类，不同模型不共用Cast类
 *
 * 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;

/**
 * 测试服务类
 *
 * 设计原则：
 * - 对外Service使用静态方法，内部Logic类处理业务逻辑
 * - 服务层直接使用逻辑层和模型，不使用Repositorys
 * - 模块间通过Service层交互，不直接访问其他模块模型
 * - 服务层返回DTO对象而非Model
 */
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 验证机制

@docs/Validation使用示例.md

#### 4.3.1 Validation类
```php
<?php

namespace App\Module\Test\Validations;

use UCore\Validation\ValidationCore;

/**
 * 测试创建验证类
 *
 * 设计原则：
 * - 使用Validation和Validator类处理验证逻辑，参考GodActivationValidation模式
 * - 禁止动态属性赋值，需先定义属性并声明类型
 */
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;

/**
 * 测试状态验证器
 *
 * 设计原则：
 * - 实现单一验证逻辑，使用addError方法而非throwMessage
 * - 字段Key使用$arg参数传入，不直接硬编码
 */
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.1.3 数据库设计规范
- **不使用迁移类**：直接提供SQL语句修改数据库结构
- **小数存储**：全面采用DECIMAL(30,10)直接存储小数值（参考Fund模块）
- **精度配置**：硬编码到枚举中，如FUND_CURRENCY_TYPE枚举
- **字段注释**：所有字段必须添加中文注释说明
- **时间字段**：使用timestamp类型，设置默认值和自动更新

### 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\Repositorys\TestRepository;
use UCore\DcatAdmin\AdminController;

/**
 * 测试后台控制器
 *
 * 设计原则：
 * - 继承自UCore\DcatAdmin\AdminController
 * - 使用Grid/Show/Form的'make'方法实例化
 * - 使用GridHelper/ShowHelper/FormHelper/FilterHelper辅助类
 * - Repositorys类参考Fund模块实现，内部不包含方法，仅供后台管理数据访问
 * - 添加路由注释，加入后台菜单适当位置
 *
 * @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 DTO设计规范

#### 5.4.1 DTO类设计
```php
<?php

namespace App\Module\Test\Dtos;

use UCore\Dto\BaseDto;
use App\Module\Test\Models\TestItem;

/**
 * 测试DTO类
 *
 * 设计原则：
 * - 继承自UCore\Dto\BaseDto
 * - 实现fromModel静态方法
 * - 使用驼峰命名公共属性
 * - 服务层返回DTO对象而非Model
 */
class TestDto extends BaseDto
{
    public int $id;
    public string $name;
    public int $status;
    public string $statusName;
    public string $createdAt;
    public string $updatedAt;

    /**
     * 从模型创建DTO
     */
    public static function fromModel(TestItem $model): self
    {
        $dto = new self();
        $dto->id = $model->id;
        $dto->name = $model->name;
        $dto->status = $model->status;
        $dto->statusName = $model->status_name;
        $dto->createdAt = $model->created_at->toDateTimeString();
        $dto->updatedAt = $model->updated_at->toDateTimeString();

        return $dto;
    }
}
```

### 5.5 Handler设计规范

#### 5.5.1 Handler类设计
```php
<?php

namespace App\Module\AppGame\Handler;

use App\Module\Test\Services\TestService;
use App\Module\Test\Validations\TestCreateValidation;
use UCore\Handler\HandlerCore;

/**
 * 测试Handler类
 *
 * 设计原则：
 * - 参考PesticideHandler模式：先验证再执行操作
 * - 不设置异常处理，继续抛出异常交由框架处理
 * - 成功时使用RESPONSE_CODE常量设置响应码，不使用魔法数字0
 * - Handler中将DTO转换为protobuf格式
 * - 动作型方法使用Res对象处理返回值，不直接返回数组
 */
class TestHandler extends HandlerCore
{
    /**
     * 创建测试项目
     */
    public function createTest($request)
    {
        // 验证请求数据
        $validation = new TestCreateValidation();
        $data = $validation->check($request);

        // 执行业务逻辑
        $result = TestService::createTest($data);

        // 返回响应
        return $this->success([
            'test' => $this->convertToProtobuf($result)
        ]);
    }

    /**
     * 转换DTO为protobuf格式
     */
    private function convertToProtobuf($dto): array
    {
        return [
            'id' => $dto->id,
            'name' => $dto->name,
            'status' => $dto->status,
            'status_name' => $dto->statusName,
            'created_at' => $dto->createdAt,
            'updated_at' => $dto->updatedAt,
        ];
    }
}
```

### 5.6 测试规范

#### 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. **事务保护**：多步骤操作必须使用数据库事务（注意：Logic层不能开启事务）
4. **异常处理**：Handler中不设置异常处理，继续抛出
5. **日志记录**：关键操作记录详细日志
6. **中文注释**：代码中添加中文注释说明
7. **文档维护**：及时更新模块文档
8. **任务管理**：任务开始前/后检查`git status`，提交代码并Push，使用中文CommitMessage
9. **完成检查**：模块开发完成情况全面检查（服务层、逻辑层、模型层、接口层、事件系统、后台管理、验证系统）
10. **清理检查**：清理模块残留时全面检查（代码文件、数据库表、文档内容）

### 7.2.1 任务记录规范
- **任务记录**：任务完成后创建记录于'./AiWork/年月/'目录
- **文件命名**：'日时分-任务标题.md'格式
- **工作更新**：更新WORK.md文件
- **自动生成目录**：添加README.md声明内容自动生成不可修改

### 7.3 项目环境

#### 7.3.1 开发环境
- **运行环境**：使用Docker运行
- **访问地址**：http://kku_laravel.local.gd
- **调试工具**：使用`php artisan debug:reproduce-error`命令回放错误请求

#### 7.3.2 测试环境
- **单元测试**：在tests目录编写非模块phpunit测试
- **测试运行**：使用vendor/bin/phpunit运行测试
- **手动测试**：不使用laravel console组织测试

### 7.4 调试和错误处理

#### 7.4.1 调试规范
- **任务开始前**：使用'date'命令获取时间
- **网页测试**：使用mcp测试网页修改
- **SQL执行**：使用mcp执行sql
- **数据问题**：优先检查数据结构字段名匹配
- **字段一致性**：确保Logic层返回字段名与Handler中访问字段名一致

#### 7.4.2 错误处理原则
- **异常透传**：Handler中不设置异常处理，继续抛出异常交由框架处理
- **响应规范**：成功时使用RESPONSE_CODE常量，不使用魔法数字0
- **protobuf处理**：确保所有必需字段有正确数据源

### 7.5 扩展建议

1. **功能扩展**：基于现有架构添加新功能
2. **性能优化**：添加缓存机制和索引优化
3. **监控告警**：实现业务监控和异常告警
4. **国际化**：支持多语言和多地区
5. **API接口**：提供RESTful API接口
6. **移动端适配**：支持移动端应用接入

---

**最后更新时间**：2025年06月16日
**文档版本**：v1.0
**维护人员**：开发团队
```