kknongchang_2506/CLAUDE.md

CLAUDE.md

这个文件为 Claude Code (claude.ai/code) 提供在此仓库中工作的指导。

项目概述

KK-U 是一个基于 Laravel 的农场游戏系统，集成了 URS 推广系统，采用模块化架构并配备完善的后台管理。

核心架构

技术栈

• 框架: Laravel 11.x + PHP 8.3
• 后台: Dcat Admin 2.0
• 数据库: MySQL 支持 JSON 字段
• 缓存: Redis
• 队列: Laravel Queue
• API: Protobuf 协议
• 前端: TailwindCSS + Vite

模块化系统

位于 app/Module/ 的自包含模块：

• Farm: 核心农场系统（土地、作物、房屋、种子）
• Game: 游戏协调层
• GameItems: 带冻结/解冻功能的库存管理
• UrsPromotion: 3级推广返利系统
• Mex: 农产品交易市场
• Transfer: 跨系统转账
• ThirdParty: 外部系统集成

框架层 (UCore/)

• ModelCore: 带属性管理的模型基类
• Validation: 综合验证系统
• Queue: 增强队列管理

开发命令

环境搭建

docker compose -f docker-compose.dev.yml up -d
php artisan ucore:generate-model-annotation

测试

./vendor/bin/phpunit                    # 全部测试
./vendor/bin/phpunit --testsuite=Unit   # 单元测试
./vendor/bin/phpunit tests/Unit/Farm/   # 特定模块

开发工作流

npm run dev                # Vite 开发服务器
php artisan serve          # Laravel 服务器
php artisan queue:listen   # 队列工作进程
php artisan pail --timeout=0  # 日志监控

代码生成

composer proto                    # Protobuf 类
php artisan gameitems:generate-json  # 游戏配置 JSON

关键模式

服务层

• Services/ 目录中的静态方法
• 复杂数据使用 DTO 返回
• 事务安全操作

验证系统

• 基于模型的验证规则
• UCore/Validator/ 中的自定义验证器
• 批处理操作的 Foreach 验证

数据库设计

• 灵活配置的 JSON 字段
• 标准软删除
• Bigint 主键
• 时间戳跟踪

URS 集成

• 用户映射: urs_promotion_user_mappings 表
• 推广系统: 3级推广奖励（直推、间推、三推）
• 达人等级: 影响奖励/手续费的6级系统
• 转账手续费: 基于房屋等级+达人等级的动态计算

测试结构

• 单元测试: 组件隔离测试
• 功能测试: 端到端测试
• 手动测试: tests/manual_* 特定场景
• 模块测试: 位于各模块目录内

文件位置

• 配置: config/ (admin, database, app)
• Protobuf: proto/game.proto
• 测试: tests/ 含 Unit/Feature 子目录
• 资源: resources/ (css, js, views)