# 偏好习惯

## 语言和文档偏好

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

### 文档规范
- Model类添加field start/end注释块，只保留// attrlist start/end标识符包围的$fillable定义
- 自动生成目录下添加README.md声明内容自动生成不可修改
- README.md使用可点击目录结构，包含锚点链接和状态图标
- 文档使用明确关键词：'买入'改为'用户买入物品'，'卖出'改为'用户卖出物品'
- 基于成熟模块架构设计完善文档，提炼通用开发规范和最佳实践

### 任务管理
- 任务开始前/后检查`git status`，提交代码并Push，使用中文CommitMessage
- 任务完成后创建记录于'./AiWork/年月/'目录，文件名'日时分-任务标题.md'，更新WORK.md
- 模块开发完成情况全面检查：服务层、逻辑层、模型层、接口层、事件系统、后台管理、验证系统
- 清理模块残留时全面检查：代码文件、数据库表、文档内容

## 代码结构和命名规范

### 命名空间和前缀
- Handler命名空间：'App\Module\AppGame\Handler'
- 数据库表前缀：全局'kku_'，物品模块'item_'，宠物模块'pet_'

### 类命名规范
- 枚举：遵循PSR-4标准，使用PHP enum语法，避免魔法数字
- 控制器和仓库：名称与关联表名匹配
- Validator类：以'Validator'结尾
- Repository类：以'Repository'结尾

### 设计原则
- 功能拆分为独立简单静态类，避免复杂设计模式

## 架构设计偏好

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

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

### 服务层和逻辑层
- 服务层：对外Service(静态方法)，内部Logic类
- 服务层直接使用逻辑层和模型，仓库层仅供后台控制器使用
- 模块间通过Service层交互，不直接访问其他模块模型
- 服务层返回DTO对象而非Model，Handler中将DTO转换为protobuf格式
- 逻辑层不能开启事务
- DTO类继承自UCore\Dto\BaseDto，实现fromModel静态方法，使用驼峰命名公共属性

### 验证机制
- 使用Validation和Validator类处理验证逻辑，参考GodActivationValidation模式
- Validator类实现单一验证逻辑，使用addError方法而非throwMessage
- Validator类字段Key使用$arg参数传入，不直接硬编码
- Validation类禁止动态属性赋值，需先定义属性并声明类型

### Handler和模块设计
- Handler类参考PesticideHandler模式：先验证再执行操作
- Handler类不设置异常处理，继续抛出异常交由框架处理
- Handler成功时使用RESPONSE_CODE常量设置响应码，不使用魔法数字0
- 事件用于模块间通信，模块内部不使用事件机制
- 动作型方法使用Res对象处理返回值，不直接返回数组

## 游戏系统功能偏好

### 奖励系统
- 实现消耗组、条件组和奖励组功能，支持多种类型配置和验证
- 奖励组系统支持复杂随机奖励机制：概率获得、必中获得、倍率功能
- 奖励组/消耗组/条件组增加标签功能，三个组共用标签数据库表，用于后台查询筛选

### 皮肤系统
- 使用单表设计：game模块创建game_user_skins表
- 一个字段表示当前使用皮肤，一个字段表示持有皮肤

## 核心模块设计偏好

### Fund模块（资金系统）
- 全面采用小数存储模式：DECIMAL(30,10)直接存储小数值
- 精度配置硬编码到FUND_CURRENCY_TYPE枚举中
- 支持冻结账户功能，钻石币种支持10位小数精度
- '币种ID'指FUND_CURRENCY_TYPE枚举value值（1=金币,2=钻石,3=人民币,4=美元）
- Point模块基于Fund模块创建，专注整数型积分逻辑，不使用小数模式

### Mex模块（农贸市场交易系统）
#### 账户体系
- 仓库账户USER_ID=15：用户卖出时资金从仓库转出到用户、物品转入仓库；用户买入时资金从仓库转入用户、物品从仓库转出到用户
- 调控账户USER_ID=16：用于市场调控操作，确保总量不变

#### 交易机制
- 挂单时无价格验证，最低价和最高价仅为参考
- 挂单不会立即成交，所有订单先创建后由撮合任务处理成交
- 价格验证仅在撮合成交时进行
- 挂单操作没有价格限制（重要业务规则）

#### 撮合算法
- 大额订单应该卡住小额订单（业务需求而非要避免的问题）
- 系统总量守恒验证不可用（交易期间会产生新的物品和资金）
- 买入/卖出分为两个独立任务处理，流程图分开设计

#### 多币种适配
- 默认币种为钻石，通过FundLogic类管理币种与账户类型映射关系
- 订单表和成交记录表增加currency_type字段
- MexOrderValidator根据币种动态选择账户类型
- 不再自行处理Fund模块数值精度，信任Fund模块数据
- 数额验证直接使用Fund模块FundService进行比较

#### 资金物品流向
- 买入：资金从用户可用→冻结→仓库，物品从仓库→用户
- 卖出：物品从用户可用→冻结→仓库，挂单操作只在用户内部转移

### GameItem模块（物品系统）
#### 物品冻结功能
- 用于匹配交易过程中卖出物品时的状态管理
- 冻结功能设计原则：
  - 交易日志不记录冻结信息（冻结不改变归属）
  - 冻结采用拆堆模式（1000个堆叠冻结200个则拆分为200个冻结堆+800个可用堆）
  - ItemUser表增加is_frozen字段标识冻结状态
  - 冻结记录表使用source_id和source_type而非order_id
  - 不需要自动解冻逻辑（由冻结发起方处理）
  - ItemUser表只需frozen_log_id字段关联冻结日志
  - 不需要冻结数量、原因、时间、过期时间等冗余字段
- ItemInstance表是物品实例表，记录物品信息而不存在物品归属概念，不应添加冻结相关字段

#### Protobuf适配
- DataItem已更新，堆id对应item_user表的id
- 设置堆id（iu_id）字段为item_user表的id
- 更新DataHandler、QueryHandler、AppGameProtobufResponseListener、LastDataHelper和ItemUserDto
- 确保所有物品数据传输包含完整的堆叠标识和冻结状态信息

## 调试和测试偏好

### 调试工具
- 任务开始前获取时间，使用'date'命令
- 使用mcp测试网页修改和执行sql
- 使用`php artisan debug:reproduce-error`命令回放错误请求进行调试验证

### 错误处理
- 接口数据问题时优先检查数据结构字段名匹配
- 注意Logic层返回字段名与Handler中访问字段名一致
- Handler处理protobuf响应时确保所有必需字段有正确数据源

### 测试规范
- 在tests目录编写非模块phpunit测试
- 使用vendor/bin/phpunit运行测试
- 不使用laravel console组织测试

## 项目环境和特殊模块偏好

### 项目环境
- 使用Docker运行，访问地址：http://kku_laravel.local.gd

### Cleanup模块（数据清理系统）
- 创建专门的Cleanup模块实现数据清理功能，不在game模块中创建清理命令
- 设计为独立数据清理系统，提供后台管理界面配置每个表的清理条件
- 包含完整安全机制：多重确认、预览模式、权限控制、操作审计、分批处理
- 支持完全自由的表选择，不局限于模块边界
- 5种表选择方式：自定义、模块、分类、全量、混合选择
- 不同清理方式：清空表、删除所有、按时间删除、按用户删除、按条件删除
- 表级别独立配置：清理类型、条件、优先级、备份设置、说明备注
- 数据库备份为默认备份方式：将INSERT语句直接存储到数据库表中，查询快速、管理便捷、安全可靠
### ThirdParty模块（第三方服务对接）
- 专门处理接入第三方服务需求，与OpenAPI模块互补（OpenAPI提供API给别人，ThirdParty使用别人的API）
- 实现标准化基础架构：BaseRequest请求基类、BaseWebhook基类、WebhookDispatchService分发服务
- 路由规则：/thirdParty/webhook/{包名}/{Handler路由}
- 支持ThirdParty命名空间下的包管理，自动处理配置读取、配额检查、日志记录、错误处理
- Request机制规范：一个Request类只完成一种请求，遵循单一职责原则
- WebhookHandler只处理一种请求类型，webhook只支持POST请求
- Webhook签名验证应在接收器实例化之前进行
- 后台管理菜单结构：外接管理作为一级菜单，下设OpenApi模块和ThirdParty模块作为二级菜单
- 完全符合dcat admin设计规范：使用Content/Row/Column布局系统，创建ServiceOverviewCard统计卡片
- 设计完整三方登录方案：基于OAuth2.0统一架构，支持微信、QQ、支付宝、微博等主流平台

### UrsPromotion模块（URS推广系统）
- 专门为URS业务场景设计的推广系统，与Promotion模块完全独立
- 使用独立命名空间App\Module\UrsPromotion和数据库表前缀urs_promotion_
- 三代推广系统：支持直推、间推、三推三代推广关系
- 两种收益类型：推广收益（下级进入农场）和种植收益（下级收获作物）
- 6个达人等级（非达人到顶级达人），不同等级享有不同收益分成比例
- 分离映射关系设计：独立用户映射表 + 纯URS推荐关系表
- 推荐关系只存储urs_user_id，通过映射表关联农场用户
- 奖励分发逻辑：检查用户映射关系，未进入农场的用户跳过
- 已移除推荐码功能，直接通过URS用户ID建立关系
- 数据库升级到v3版本：字段名统一(user_id->urs_user_id)，新增farm_user_id冗余字段

### OpenAPI模块（API开放平台）
- 扩展钻石充值/提取功能，每个开发者应用分配专用账户
- 充值账户=100000+应用ID，提取账户=200000+应用ID
- 钻石操作使用FUND_TYPE::FUND2类型，支持10位小数精度
- 包含完整的验证、事务处理和操作日志记录机制

### Transfer模块（划转系统）
#### 核心概念
- 转入订单：用户充值/存入资金到农场系统
- 转出订单：用户提现/转出资金到外部系统
- 外部金额：第三方系统的金额单位
- 内部金额：农场系统的钻石数量
- 汇率：外部金额与内部金额的转换比例

#### 金额转换逻辑
- 第三方应用转出：外部金额 × 汇率 = 内部金额
- 普通应用转出：内部金额 ÷ 汇率 = 外部金额
- 转入：外部金额 × 汇率 = 内部金额
- 避免双重转换：只在TransferLogic层进行一次转换

#### 手续费处理机制
- 转出：手续费额外收取（用户支付转出金额+手续费，外部收到完整转出金额）
- 转入：手续费从金额中扣除（用户收到转入金额-手续费）
- 手续费计算：支持最低/最高限制，按比例计算后应用限制
- 手续费收取账户：默认UID=1，可配置专用账户

#### 第三方应用集成
- TransferThirdPartyService专门处理第三方应用需求
- createTransferOutForThirdParty方法跳过密码验证
- 支持回调机制：配置回调URL时发送状态通知
- 应用权限控制：独立控制转入/转出操作权限

#### 验证和安全
- 余额验证：转出检查转出金额+手续费总和
- 事务处理：Fund模块trade方法要求在事务中执行
- 汇率验证：确保汇率大于0，避免计算异常
- 重复订单检查：外部订单ID唯一性验证

### 系统模块概况
- 系统包含35个模块
- Promotionurs模块已被移除，创建新的UrsPromotion模块替代