kknongchang_2506/.augment-guidelines

# Augment Guidelines for KKU Laravel Project

## 项目概述
这是一个基于Laravel 11的农场游戏系统，本地使用Docker运行，访问地址：http://kku_laravel.local.gd
- 当前项目处理维护期，不得随意对数据库的表结构进行修改，不得对涉及游戏数值的表进行修改

## 工作流程规范

### 任务开始前
1. 获取当前时间：使用 `date` 命令
2. 检查git状态：`git status`

### 任务执行中
1. 使用MCP测试网页修改
2. 使用MCP执行SQL操作
3. 使用 `php artisan debug:reproduce-error` 命令进行请求（sys_request_logs表）回放
4. 编写代码时添加中文注释

### 任务完成后
1. 检查git状态并提交代码：使用中文CommitMessage
2. Push代码到远程仓库
3. 创建任务记录：`./AiWork/年月/日时分-任务标题.md`

## 代码编写规范

### 语言和注释
- 使用中文进行交流和编写文档
- 代码中增加中文注释

### 命名规范
- 枚举：遵循PSR-4标准，使用PHP enum语法，避免魔法数字

### 设计原则
- 功能拆分为独立简单静态类，避免复杂设计模式
- 模块间通过Service层交互，不直接访问其他模块模型
- 事件用于模块间通信，模块内部不使用事件机制

## 架构设计规范

### 模型层 (Model)
- 继承自 `\UCore\ModelCore`，保持无业务逻辑
- 不设置$prefix属性（全局配置在config/database.php）
- 在模型中定义访问器而非控制器中实现逻辑
- 为模型创建独立Cast类，不同模型不共用Cast类
- 不使用数据库迁移类，直接提供SQL语句修改数据库结构

### 后台(Admin)
- 后台控制器继承自 `UCore\DcatAdmin\AdminController`
- 使用Grid/Show/Form的'make'方法实例化
- 使用GridHelper/ShowHelper/FormHelper/FilterHelper辅助类
- 后台控制器添加路由注释，加入后台菜单适当位置
- 后台列表页面来源表名列可点击跳转到对应详情页面
- Repository类参考Fund模块实现，内部不包含方法，仅供后台管理数据访问
- 仓库层仅供后台控制器使用

### 服务层 (Service) 和逻辑层 (Logic)
- 服务层：对外Service(静态方法)，内部Logic类
- 服务层直接使用逻辑层和模型，仓库层仅供后台控制器使用
- 服务层返回DTO对象而非Model，Handler中将DTO转换为protobuf格式
- 逻辑层不能开启事务,需要事务进行事务开启检查

### DTO层
- DTO类继承自 `UCore\Dto\BaseDto`
- 实现fromModel静态方法
- 使用驼峰命名公共属性

### 验证层 (Validation/Validator)
- 使用Validation和Validator类处理验证逻辑，参考'docs/Validation使用示例.md'
- Validation类禁止动态属性赋值，需先定义属性并声明类型

### Handler层
- Handler类参考PesticideHandler模式：先验证再执行操作
- Handler类不设置异常处理，继续抛出异常交由框架处理

## 包管理规范
- 始终使用包管理器进行依赖管理，不手动编辑包配置文件

## 测试规范
- 在tests目录编写非模块phpunit测试
- 使用 `vendor/bin/phpunit` 运行测试
- 测试的 Command在Test模块编写
- 建议为新功能编写测试并执行验证

## 文档规范
- README.md使用可点击目录结构，包含锚点链接和状态图标
- 文档偏好包含流程图和图表以便更好地可视化

## 调试和错误处理
- 接口数据问题时优先检查数据结构字段名匹配
- 注意Logic层返回字段名与Handler中访问字段名一致
- Handler处理protobuf响应时确保所有必需字段有正确数据源
- 使用 `php artisan debug:reproduce-error` 命令回放错误请求进行调试验证

## 特殊注意事项
- 不使用数据库迁移，不注册路由（使用注解），不包含视图/前端资源/中间件/计划任务
- 后台管理界面使用Dcat Admin框架，不使用通用REST API