|
|
@@ -0,0 +1,155 @@
|
|
|
+# Augment Guidelines for KKU Laravel Project
|
|
|
+
|
|
|
+## 项目概述
|
|
|
+这是一个基于Laravel的农场游戏系统，包含35个模块，使用Docker运行，访问地址：http://kku_laravel.local.gd
|
|
|
+
|
|
|
+## 工作流程规范
|
|
|
+
|
|
|
+### 任务开始前
|
|
|
+1. 获取当前时间：使用 `date` 命令
|
|
|
+2. 检查git状态：`git status`
|
|
|
+3. 加载项目偏好习惯：查看 `AiWork/偏好习惯.md`
|
|
|
+4. 使用codebase-retrieval工具获取相关代码信息
|
|
|
+
|
|
|
+### 任务执行中
|
|
|
+1. 使用MCP测试网页修改
|
|
|
+2. 使用MCP执行SQL操作
|
|
|
+3. 使用 `php artisan debug:reproduce-error` 命令调试验证
|
|
|
+4. 编写代码时添加中文注释
|
|
|
+
|
|
|
+### 任务完成后
|
|
|
+1. 检查git状态并提交代码：使用中文CommitMessage
|
|
|
+2. Push代码到远程仓库
|
|
|
+3. 创建任务记录：`./AiWork/年月/日时分-任务标题.md`
|
|
|
+4. 更新WORK.md文件
|
|
|
+
|
|
|
+## 代码编写规范
|
|
|
+
|
|
|
+### 语言和注释
|
|
|
+- 使用中文进行交流和编写文档
|
|
|
+- 代码中增加中文注释
|
|
|
+- 文档使用明确关键词：'买入'改为'用户买入物品'，'卖出'改为'用户卖出物品'
|
|
|
+
|
|
|
+### 命名规范
|
|
|
+- 数据库表前缀：全局'kku_'，物品模块'item_'，宠物模块'pet_'
|
|
|
+- Handler命名空间：'App\Module\AppGame\Handler'
|
|
|
+- 枚举：遵循PSR-4标准，使用PHP enum语法，避免魔法数字
|
|
|
+- 控制器和仓库：名称与关联表名匹配
|
|
|
+- Validator类：以'Validator'结尾
|
|
|
+- Repository类：以'Repository'结尾
|
|
|
+
|
|
|
+### 设计原则
|
|
|
+- 功能拆分为独立简单静态类，避免复杂设计模式
|
|
|
+- 模块间通过Service层交互，不直接访问其他模块模型
|
|
|
+- 事件用于模块间通信，模块内部不使用事件机制
|
|
|
+
|
|
|
+## 架构设计规范
|
|
|
+
|
|
|
+### 模型层 (Model)
|
|
|
+- 继承自 `\UCore\ModelCore`，保持无业务逻辑
|
|
|
+- 不设置$prefix属性（全局配置在config/database.php）
|
|
|
+- 在模型中定义访问器而非控制器中实现逻辑
|
|
|
+- 为模型创建独立Cast类，不同模型不共用Cast类
|
|
|
+- 不使用数据库迁移类，直接提供SQL语句修改数据库结构
|
|
|
+- Model类添加field start/end注释块，只保留// attrlist start/end标识符包围的$fillable定义
|
|
|
+
|
|
|
+### 控制器层 (Controller)
|
|
|
+- 后端控制器继承自 `UCore\DcatAdmin\AdminController`
|
|
|
+- 使用Grid/Show/Form的'make'方法实例化
|
|
|
+- 使用GridHelper/ShowHelper/FormHelper/FilterHelper辅助类
|
|
|
+- 后台控制器添加路由注释，加入后台菜单适当位置
|
|
|
+- 后台列表页面来源表名列可点击跳转到对应详情页面
|
|
|
+
|
|
|
+### 仓库层 (Repository)
|
|
|
+- Repository类参考Fund模块实现，内部不包含方法，仅供后台管理数据访问
|
|
|
+- 仓库层仅供后台控制器使用
|
|
|
+
|
|
|
+### 服务层 (Service) 和逻辑层 (Logic)
|
|
|
+- 服务层：对外Service(静态方法)，内部Logic类
|
|
|
+- 服务层直接使用逻辑层和模型，仓库层仅供后台控制器使用
|
|
|
+- 服务层返回DTO对象而非Model，Handler中将DTO转换为protobuf格式
|
|
|
+- 逻辑层不能开启事务
|
|
|
+
|
|
|
+### DTO层
|
|
|
+- DTO类继承自 `UCore\Dto\BaseDto`
|
|
|
+- 实现fromModel静态方法
|
|
|
+- 使用驼峰命名公共属性
|
|
|
+
|
|
|
+### 验证层 (Validation/Validator)
|
|
|
+- 使用Validation和Validator类处理验证逻辑，参考GodActivationValidation模式
|
|
|
+- Validator类实现单一验证逻辑，使用addError方法而非throwMessage
|
|
|
+- Validator类字段Key使用$arg参数传入，不直接硬编码
|
|
|
+- Validation类禁止动态属性赋值，需先定义属性并声明类型
|
|
|
+
|
|
|
+### Handler层
|
|
|
+- Handler类参考PesticideHandler模式：先验证再执行操作
|
|
|
+- Handler类不设置异常处理，继续抛出异常交由框架处理
|
|
|
+- Handler成功时使用RESPONSE_CODE常量设置响应码，不使用魔法数字0
|
|
|
+- 动作型方法使用Res对象处理返回值，不直接返回数组
|
|
|
+
|
|
|
+## 包管理规范
|
|
|
+- 始终使用包管理器进行依赖管理，不手动编辑包配置文件
|
|
|
+- Laravel项目使用 `composer require/remove` 命令
|
|
|
+- 前端依赖使用 `npm install/uninstall` 或 `yarn add/remove`
|
|
|
+
|
|
|
+## 测试规范
|
|
|
+- 在tests目录编写非模块phpunit测试
|
|
|
+- 使用 `vendor/bin/phpunit` 运行测试
|
|
|
+- 不使用laravel console组织测试
|
|
|
+- 建议为新功能编写测试并执行验证
|
|
|
+
|
|
|
+## 文档规范
|
|
|
+- 自动生成目录下添加README.md声明内容自动生成不可修改
|
|
|
+- README.md使用可点击目录结构，包含锚点链接和状态图标
|
|
|
+- 基于成熟模块架构设计完善文档，提炼通用开发规范和最佳实践
|
|
|
+- 文档偏好包含流程图和图表以便更好地可视化
|
|
|
+
|
|
|
+## 核心模块特殊规范
|
|
|
+
|
|
|
+### Fund模块（资金系统）
|
|
|
+- 全面采用小数存储模式：DECIMAL(30,10)直接存储小数值
|
|
|
+- 精度配置硬编码到FUND_CURRENCY_TYPE枚举中
|
|
|
+- 支持冻结账户功能，钻石币种支持10位小数精度
|
|
|
+- '币种ID'指FUND_CURRENCY_TYPE枚举value值（1=金币,2=钻石,3=人民币,4=美元）
|
|
|
+
|
|
|
+### GameItem模块（物品系统）
|
|
|
+- 物品冻结功能采用拆堆模式
|
|
|
+- ItemUser表增加is_frozen字段标识冻结状态
|
|
|
+- 冻结记录表使用source_id和source_type而非order_id
|
|
|
+- 不需要自动解冻逻辑（由冻结发起方处理）
|
|
|
+
|
|
|
+### Mex模块（农贸市场交易系统）
|
|
|
+- 仓库账户USER_ID=15，调控账户USER_ID=16
|
|
|
+- 挂单时无价格验证，最低价和最高价仅为参考
|
|
|
+- 挂单不会立即成交，所有订单先创建后由撮合任务处理成交
|
|
|
+- 大额订单应该卡住小额订单（业务需求而非要避免的问题）
|
|
|
+
|
|
|
+### UrsPromotion模块（URS推广系统）
|
|
|
+- 使用独立命名空间App\Module\UrsPromotion和数据库表前缀urs_promotion_
|
|
|
+- 三代推广系统：支持直推、间推、三推三代推广关系
|
|
|
+- 分离映射关系设计：独立用户映射表 + 纯URS推荐关系表
|
|
|
+- 推荐关系只存储urs_user_id，通过映射表关联农场用户
|
|
|
+
|
|
|
+### Cleanup模块（数据清理系统）
|
|
|
+- 创建专门的Cleanup模块实现数据清理功能
|
|
|
+- 设计为独立数据清理系统，提供后台管理界面配置每个表的清理条件
|
|
|
+- 包含完整安全机制：多重确认、预览模式、权限控制、操作审计、分批处理
|
|
|
+- 支持完全自由的表选择，不局限于模块边界
|
|
|
+
|
|
|
+### ThirdParty模块（第三方服务对接）
|
|
|
+- 专门处理接入第三方服务需求，与OpenAPI模块互补
|
|
|
+- 实现标准化基础架构：BaseRequest请求基类、BaseWebhook基类
|
|
|
+- 路由规则：/thirdParty/webhook/{包名}/{Handler路由}
|
|
|
+- 一个Request类只完成一种请求，遵循单一职责原则
|
|
|
+
|
|
|
+## 调试和错误处理
|
|
|
+- 接口数据问题时优先检查数据结构字段名匹配
|
|
|
+- 注意Logic层返回字段名与Handler中访问字段名一致
|
|
|
+- Handler处理protobuf响应时确保所有必需字段有正确数据源
|
|
|
+- 使用 `php artisan debug:reproduce-error` 命令回放错误请求进行调试验证
|
|
|
+
|
|
|
+## 特殊注意事项
|
|
|
+- 系统使用双用户ID概念：urs_user_id作为核心用户ID对应URS系统用户，user_id作为辅助ID对应农场用户
|
|
|
+- 推荐码功能已移除
|
|
|
+- 不使用数据库迁移，不注册路由（使用注解），不包含视图/前端资源/中间件/计划任务
|
|
|
+- 后台管理界面使用Dcat Admin框架，不使用通用REST API
|
