Merge branch 'master' of e.coding.net:g-ueau9359/kku/kku_laravel

app/Module/Test/README.md

@@ -23,6 +23,9 @@ Test模块是一个标准的示例模块，用于展示项目中模块化开发
 - **完整示例**：包含所有必要的目录和文件结构
 - **最佳实践**：展示代码组织、命名规范、设计模式等最佳实践
 - **参考模板**：为新模块开发提供标准模板
+- **逻辑模块**：默认不提供Api、前端页面，专注业务逻辑实现
+- **注解路由**：使用注解方式注册路由，不使用路由配置文件
+- **中文友好**：支持中文注释和文档，便于团队协作
 
 ## 2. 目录结构
 
@@ -111,7 +114,7 @@ Test模块采用标准的分层架构设计：
 
 ```
 ┌─────────────────┐
-│   Controllers   │ ← HTTP请求处理
+│   Controllers   │ ← HTTP请求处理（非对外模块不提供）
 ├─────────────────┤
 │    Services     │ ← 对外服务接口
 ├─────────────────┤
@@ -126,15 +129,20 @@ Test模块采用标准的分层架构设计：
 1. **单一职责原则**：每个类只负责一个功能领域
 2. **关注点分离**：模型只负责数据结构，业务逻辑由Logic类处理
 3. **依赖注入**：通过构造函数注入依赖，提高可测试性
-4. **事务完整性**：涉及多个操作的功能使用数据库事务
+4. **事务完整性**：涉及多个操作的功能使用数据库事务（注意：Logic层不能开启事务）
 5. **日志记录**：关键操作记录详细日志
+6. **简单设计**：功能拆分为独立简单静态类，避免复杂设计模式
+7. **中文注释**：代码中增加中文注释，提高可读性
+8. **异常透传**：Handler中不设置异常处理，继续抛出异常交由框架处理
 
 ### 3.3 模块交互
 
-- **服务层对外**：其他模块只能通过Services层访问功能
-- **逻辑层内部**：Logic类处理具体业务规则
-- **事件通信**：模块间通过事件进行松耦合通信
-- **数据访问**：Repository层仅供后台管理使用
+- **服务层对外**：其他模块只能通过Services层访问功能，不直接访问其他模块模型
+- **逻辑层内部**：Logic类处理具体业务规则，服务层直接使用逻辑层和模型
+- **事件通信**：模块间通过事件进行松耦合通信，模块内部不使用事件机制
+- **数据访问**：Repository层仅供后台管理使用，参考Fund模块实现
+- **DTO传输**：服务层返回DTO对象而非Model，Handler中将DTO转换为protobuf格式
+- **响应规范**：Handler成功时使用RESPONSE_CODE常量设置响应码，不使用魔法数字0
 
 ## 4. 开发规范
 
@@ -150,13 +158,16 @@ Test模块采用标准的分层架构设计：
 - **DTO类**：以`Dto`结尾，如`TestDto`
 
 #### 4.1.2 数据库命名
-- **表名前缀**：使用模块前缀，如`test_`
-- **全局前缀**：所有表都有`kku_`前缀
+- **表名前缀**：使用模块前缀，如`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`（接口层）
+- **Handler命名空间**：`App\Module\AppGame\Handler`（接口层，专门的对外接口模块）
+- **路由使用注解**：不使用路由配置文件，采用注解方式注册路由
+- **模块定位**：模块默认不提供Api、前端页面，为逻辑模块
 
 ### 4.2 代码规范
 
@@ -171,6 +182,12 @@ use UCore\ModelCore;
 /**
  * 测试项目模型
  *
+ * 设计原则：
+ * - 继承自\UCore\ModelCore，保持无业务逻辑
+ * - 不设置$prefix属性（全局配置在config/database.php）
+ * - 在模型中定义访问器而非控制器中实现逻辑
+ * - 为模型创建独立Cast类，不同模型不共用Cast类
+ *
  * field start
  * @property int $id 主键ID
  * @property string $name 项目名称
@@ -189,7 +206,7 @@ class TestItem extends ModelCore
     // attrlist end
 
     /**
-     * 状态访问器
+     * 状态访问器 - 获取状态名称
      */
     public function getStatusNameAttribute(): string
     {
@@ -210,7 +227,11 @@ use App\Module\Test\Logics\Test as TestLogic;
 /**
  * 测试服务类
  *
- * 对外提供测试相关功能接口
+ * 设计原则：
+ * - 对外Service使用静态方法，内部Logic类处理业务逻辑
+ * - 服务层直接使用逻辑层和模型，不使用Repository
+ * - 模块间通过Service层交互，不直接访问其他模块模型
+ * - 服务层返回DTO对象而非Model
  */
 class TestService
 {
@@ -285,6 +306,8 @@ enum TEST_STATUS: int
 
 ### 4.3 验证机制
 
+@docs/Validation使用示例.md
+
 #### 4.3.1 Validation类
 ```php
 <?php
@@ -295,6 +318,10 @@ use UCore\Validation\ValidationCore;
 
 /**
  * 测试创建验证类
+ *
+ * 设计原则：
+ * - 使用Validation和Validator类处理验证逻辑，参考GodActivationValidation模式
+ * - 禁止动态属性赋值，需先定义属性并声明类型
  */
 class TestCreateValidation extends ValidationCore
 {
@@ -326,6 +353,10 @@ use UCore\Validation\ValidatorCore;
 
 /**
  * 测试状态验证器
+ *
+ * 设计原则：
+ * - 实现单一验证逻辑，使用addError方法而非throwMessage
+ * - 字段Key使用$arg参数传入，不直接硬编码
  */
 class TestStatusValidator extends ValidatorCore
 {
@@ -381,6 +412,13 @@ CREATE TABLE `kku_test_logs` (
 - **查询索引**：常用查询条件建立索引
 - **复合索引**：多字段查询建立复合索引
 
+#### 5.1.3 数据库设计规范
+- **不使用迁移类**：直接提供SQL语句修改数据库结构
+- **小数存储**：全面采用DECIMAL(30,10)直接存储小数值（参考Fund模块）
+- **精度配置**：硬编码到枚举中，如FUND_CURRENCY_TYPE枚举
+- **字段注释**：所有字段必须添加中文注释说明
+- **时间字段**：使用timestamp类型，设置默认值和自动更新
+
 ### 5.2 事件系统
 
 #### 5.2.1 事件定义
@@ -445,6 +483,13 @@ use UCore\DcatAdmin\AdminController;
 /**
  * 测试后台控制器
  *
+ * 设计原则：
+ * - 继承自UCore\DcatAdmin\AdminController
+ * - 使用Grid/Show/Form的'make'方法实例化
+ * - 使用GridHelper/ShowHelper/FormHelper/FilterHelper辅助类
+ * - Repository类参考Fund模块实现，内部不包含方法，仅供后台管理数据访问
+ * - 添加路由注释，加入后台菜单适当位置
+ *
  * @route /admin/test-items
  */
 class TestController extends AdminController
@@ -464,7 +509,113 @@ class TestController extends AdminController
 }
 ```
 
-### 5.4 测试规范
+### 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
@@ -565,13 +716,48 @@ Test模块可以参考Farm模块的以下设计：
 
 1. **模型无业务逻辑**：模型只负责数据结构定义
 2. **服务层对外**：其他模块只能通过Service层访问
-3. **事务保护**：多步骤操作必须使用数据库事务
+3. **事务保护**：多步骤操作必须使用数据库事务（注意：Logic层不能开启事务）
 4. **异常处理**：Handler中不设置异常处理，继续抛出
 5. **日志记录**：关键操作记录详细日志
 6. **中文注释**：代码中添加中文注释说明
 7. **文档维护**：及时更新模块文档
-
-### 7.3 扩展建议
+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. **性能优化**：添加缓存机制和索引优化