记忆习惯
语言和文档偏好
- 用户偏好使用中文进行交流和编写文档，在代码中增加中文注释
- 用户希望在Model类中添加field start/end注释块，并只保留被// attrlist start/end标识符包围的$fillable定义
- 用户希望在自动生成的目录下添加README.md文件，声明该目录内容是自动生成的不能修改
- 用户希望在任务开始前/后检查
git status，提交代码并Push，使用中文编写CommitMessage
- 用户希望在任务完成后，将任务记录创建于'./AiWork/年月/'目录，文件名'日时分-任务标题.md'，更新WORK.md文件
- 用户偏好在文档中使用明确的关键词：'买入'应改为'用户买入物品'，'卖出'应改为'用户卖出物品'，以避免概念混淆
代码结构和命名规范
- 用户偏好handler命名空间为'App\Module\AppGame\Handler'
- 用户偏好表名前缀：物品模块'item'，宠物模块'pet'，所有数据库表有'kku_'前缀
- 用户偏好enum文件遵循PSR-4命名标准，避免使用魔法数字，并且使用PHP enum语法而不是class+const方式定义枚举
- 用户偏好controller和repository名称与关联的表名匹配
- 用户偏好Validator类名以'Validator'结尾，Repository类以'Repository'结尾
- 用户偏好将功能拆分为独立的简单静态类，避免复杂的设计模式
模型和数据访问设计
- 模型应继承自\UCore\ModelCore，保持无业务逻辑，使用单独的Validator类进行验证
- 模型中不需要设置$prefix属性，因为表前缀已在config/database.php中全局配置
- 用户希望在模型中定义访问器而不是在控制器中实现逻辑
- 用户要求为模型创建独立的Cast类，不同模型不应共用同一个Cast类
- 用户不使用数据库迁移类，需要直接提供SQL语句来修改数据库结构
- 模型中不应存在业务逻辑需要移除
控制器和仓库实现规范
- 后端控制器应继承自UCore\DcatAdmin\AdminController
- 用户偏好使用Grid/Show/Form的'make'方法进行实例化
- 用户偏好使用GridHelper/ShowHelper/FormHelper/FilterHelper
- Repository类应该参考Fund模块的Repository实现，其内不应包含任何方法，只用于后台管理数据访问
- 用户偏好后台控制器需要添加路由注释，并将路由加入后台菜单的适当位置
- 用户偏好在后台列表页面中，来源表名列应该可点击并跳转到对应来源的详情页面
服务层和逻辑层设计
- 服务层分为对外的Service(静态方法)和内部的Logic类
- 服务层应直接使用逻辑层和模型，而仓库层仅供后台控制器使用
- 模块间应通过Service层进行交互，不应直接访问其他模块的模型
- 服务层应返回DTO对象而非直接返回Model，在Handler中将DTO转换为protobuf格式
- 逻辑层(Logic层)中不能开启事务，需要检查并修复逻辑层中的事务开启代码
验证机制
- 用户偏好使用Validation和Validator类进行验证逻辑处理，参考GodActivationValidation的模式
- Validator类应实现单一验证逻辑，使用addError方法而非throwMessage进行错误处理
- Validator类中的字段Key应使用$arg参数传入，而不是直接硬编码
- Validation类使用规范：禁止动态属性赋值，需要先定义属性并声明类型
Handler和模块设计
- Handler类应参考PesticideHandler模式：先验证再执行操作，创建必要的Validation和Validator类
- Handler类中不应该设置异常处理，应该继续抛出异常交由框架处理
- 用户偏好在Handler成功时使用RESPONSE_CODE常量设置响应码，而不是使用魔法数字0
- 事件用于模块间通信，模块内部不应使用事件机制，模块的事件注册和监听应在模块内实现
- 用户偏好在动作型方法中使用Res对象处理返回值，而不是直接返回数组
游戏系统功能
- 用户希望实现消耗组、条件组和奖励组功能，支持多种类型的配置和验证
- 奖励组系统支持复杂的随机奖励机制，包括概率获得和必中获得，并支持倍率功能
- 用户要求为奖励组/消耗组/条件组增加标签功能，三个组共用一个标签数据库表，标签用于后台查询筛选
- 用户偏好皮肤系统使用单表设计：game模块中创建game_user_skins表，用一个字段表示当前使用皮肤，一个字段表示持有的皮肤
模块特定设计
Fund模块
- Fund模块全面采用小数存储模式，数据库使用DECIMAL(30,10)直接存储小数值，不再使用整数存储转换
- Fund模块精度配置硬编码到FUND_CURRENCY_TYPE枚举中，用于显示格式化和精度验证
- Fund模块需要支持冻结账户功能，钻石币种支持10位小数精度，冻结账户作为特殊账户类型与普通账户同属一个币种
- Fund模块中'币种ID'概念明确指FUND_CURRENCY_TYPE枚举的value值（1=金币,2=钻石,3=人民币,4=美元），而不是fund_currency数据库表的自增ID字段
- Point模块基于Fund模块创建，专注于整数型积分逻辑处理，不使用小数模式
Mex模块
- Mex模块业务规则：仓库账户USER_ID为15，用户卖出时资金从仓库转出到用户、物品转入仓库，用户买入时资金从仓库转入用户、物品从仓库转出到用户，调控账户USER_ID为16用于市场调控操作，确保总量不变
- Mex模块资金物品流向规则：买入时资金从用户可用→冻结→仓库，物品从仓库→用户；卖出时物品从用户可用→冻结→仓库，挂单操作只在用户内部转移不改变总量
- Mex模块交易机制：挂单时无价格验证，最低价和最高价仅为参考，挂单不会立即成交，所有订单先创建后由撮合任务处理成交，价格验证仅在撮合成交时进行
- Mex模块挂单操作没有价格限制，这是重要的业务规则
- Mex模块撮合算法设计原则：大额订单应该卡住小额订单，这是业务需求而非要避免的问题
- Mex模块中系统总量守恒验证不可用，因为交易期间会产生新的物品和资金，总量会发生变化
- Mex模块的买入/卖出应该分为两个独立的任务处理，流程图也需要分开设计
- Mex模块需要支持多币种适配功能，默认币种为钻石，通过FundLogic类管理币种与账户类型的映射关系
- Mex模块多币种适配：订单表和成交记录表增加currency_type字段，FundLogic提供币种映射，MexAccountLogic支持币种参数传递
- Mex模块AddHandler资金验证已修正支持多币种：MexOrderValidator根据币种动态选择账户类型，MatchexchangeAddValidation自动添加默认币种信息，确保资金验证使用正确的币种和精度
- Mex模块不再自行处理Fund模块的数值精度，移除了number_format和bcpow等精度处理代码，改为信任Fund模块的数据，数额验证直接使用Fund模块的FundService进行比较
GameItem模块
- GameItem模块需要实现物品冻结功能，用于匹配交易过程中卖出物品时的状态管理
- GameItem模块冻结功能设计原则：交易日志不记录冻结信息（冻结不改变归属），冻结采用拆堆模式（如1000个堆叠冻结200个则拆分为200个冻结堆+800个可用堆），ItemUser表增加is_frozen字段标识冻结状态，冻结记录表使用source_id和source_type而非order_id，不需要自动解冻逻辑（由冻结发起方处理），ItemUser表只需frozen_log_id字段关联冻结日志，不需要冻结数量、原因、时间、过期时间等冗余字段
- ItemInstance表是物品实例表，记录物品信息而不存在物品归属概念，因此不应该在ItemInstance表中添加冻结相关字段
Protobuf适配
- Protobuf的DataItem已更新，堆id现在对应item_user表的id，需要适配DataHandler查询和Lastdata数据同步
- 完成了Protobuf DataItem适配工作，设置堆id（iu_id）字段为item_user表的id，更新了DataHandler、QueryHandler、AppGameProtobufResponseListener、LastDataHelper和ItemUserDto，确保所有物品数据传输包含完整的堆叠标识和冻结状态信息
调试和错误处理
- 任务开始前获取时间，使用'date'命令
- 使用mcp测试网页的修改
- 使用mcp执行sql
- 当遇到接口数据问题时，优先检查数据结构字段名是否匹配，特别注意Logic层返回的字段名与Handler中访问的字段名要一致
- 在Handler中处理protobuf响应时，确保所有必需字段都有正确的数据源，特别是user_id等关键字段
- 使用
php artisan debug:reproduce-error命令回放错误请求进行调试验证
