# 开心农场系统模块目录
> 更新时间：2025年07月02日 13:23:44 CST
## 模块概览
开心农场系统采用模块化架构设计，将不同的业务功能拆分为独立的模块，每个模块负责特定的业务领域。系统共包含 **37个模块**，分为核心业务模块、资金管理模块、用户与社交模块、基础服务模块、工具模块、内容模块和扩展模块七大类。
## 模块列表
### 🎮 [核心业务模块](#核心业务模块) (8个)
- [AppGame - 游戏适配模块](#1-appgame---游戏适配模块) ✅
- [Farm - 农场模块](#2-farm---农场模块) ✅
- [GameItems - 游戏物品模块](#3-gameitems---游戏物品模块) ✅
- [Pet - 宠物模块](#4-pet---宠物模块) ✅
- [Shop - 商店模块](#5-shop---商店模块) ✅
- [Activity - 活动模块](#6-activity---活动模块) 📋
- [Task - 任务模块](#7-task---任务模块) ✅
- [Promotion - 团队模块](#8-promotion---团队模块) ✅
### 💰 [资金管理模块](#资金管理模块) (4个)
- [Fund - 资金模块](#9-fund---资金模块) ✅
- [Point - 积分模块](#10-point---积分模块) ✅
- [Mex - 交易所模块](#11-mex---交易所模块) ✅
- [Transfer - 划转模块](#12-transfer---划转模块) ✅
### 👥 [用户与社交模块](#用户与社交模块) (3个)
- [User - 用户模块](#13-user---用户模块) 🔧
- [Friend - 好友模块](#14-friend---好友模块) ✅
- [Game - 游戏统筹模块](#15-game---游戏统筹模块) ✅
### 🔧 [基础服务模块](#基础服务模块) (10个)
- [ThirdParty - 第三方服务管理模块](#16-thirdparty---第三方服务管理模块) ✅
- [OpenAPI - 对外开放API管理模块](#17-openapi---对外开放api管理模块) ✅
- [Admin - 后台基础功能扩展模块](#18-admin---后台基础功能扩展模块) ✅
- [System - 系统模块](#19-system---系统模块) ✅
- [File - 文件模块](#20-file---文件模块) ✅
- [Notification - 通知模块](#21-notification---通知模块) ✅
- [Sms - 短信模块](#22-sms---短信模块) ✅
- [Mail - 邮件模块](#23-mail---邮件模块) ✅
- [Push - 推送模块](#24-push---推送模块) ✅
- [OAuth - OAuth认证模块](#25-oauth---oauth认证模块) ✅
### 🛠️ [工具模块](#工具模块) (7个)
- [LCache - 本地缓存模块](#26-lcache---本地缓存模块) ✅
- [DelayQueue - 延迟队列模块](#27-delayqueue---延迟队列模块) ✅
- [Test - 测试模块](#28-test---测试模块) ✅
- [Dev - 开发者模块](#29-dev---开发者模块) ✅
- [Ulogic - 用户逻辑模块](#30-ulogic---用户逻辑模块) ✅
- [Protobuf - Protobuf模块](#31-protobuf---protobuf模块) ✅
- [Cleanup - 数据清理模块](#32-cleanup---数据清理模块) 🔧
### 📝 [内容模块](#内容模块) (2个)
- [Article - 文章模块](#33-article---文章模块) 🔧
- [China - 中国特殊内容模块](#34-china---中国特殊内容模块) ✅
### 🚀 [扩展模块](#扩展模块) (2个)
- [UrsPromotion - URS推广模块](#35-urspromotion---urs推广模块) 🚧
- [TransferOld - 旧版划转模块](#36-transferold---旧版划转模块) ⏸️
## 模块分类
### 🎮 核心业务模块 (8个)
这些模块构成了开心农场游戏的核心玩法和业务逻辑：
#### 1. **AppGame** - 游戏适配模块
- **路径**: `app/Module/AppGame`
- **功能**: 适配模块，将游戏逻辑适配App的输入/输出，不负责具体逻辑
- **状态**: ✅ 已完成
- **依赖**: 所有业务模块
- **特点**: 包含Handler处理器、Session管理、中间件等
#### 2. **Farm** - 农场模块
- **路径**: `app/Module/Farm`
- **功能**: 农场系统核心模块，管理土地、房屋、种子、作物等
- **状态**: ✅ 已完成
- **核心功能**:
- 土地管理（普通、红土地、黑土地、特殊土地）
- 房屋管理（12级房屋系统）
- 种子管理（神秘种子、普通种子、巨化种子）
- 作物管理（生长周期、灾害系统、收获系统）
- 神灵加持系统
#### 3. **GameItems** - 游戏物品模块
- **路径**: `app/Module/GameItems`
- **功能**: 综合管理游戏内所有物品的生命周期
- **状态**: ✅ 已完成
- **核心功能**:
- 物品基础属性管理
- 物品获取与消耗逻辑
- 物品库存管理
- 宝箱系统（保底机制）
- 物品过期管理
- 物品合成与分解系统
- 物品冻结功能（拆堆模式）
#### 4. **Pet** - 宠物模块
- **路径**: `app/Module/Pet`
- **功能**: 宠物属性、技能、战斗、宠物争霸赛
- **状态**: ✅ 已完成
- **核心功能**:
- 品阶体系（4个品阶：一品60%/二品25%/三品10%/四品5%）
- 成长属性（1-30级，体力值0-100）
- 技能系统（自动收菜、自动播种、灾害防护）
- 松狮争霸赛系统
- 洗髓系统
#### 5. **Shop** - 商店模块
- **路径**: `app/Module/Shop`
- **功能**: 游戏商店系统，商品展示、购买等功能
- **状态**: ✅ 已完成
- **核心功能**:
- 商品分类管理
- 商品信息管理
- 促销活动管理
- 购买记录管理
- 折扣价格计算
#### 6. **Activity** - 活动模块
- **路径**: `app/Module/Activity`
- **功能**: 管理和执行各类游戏活动
- **状态**: 📋 文档阶段
- **核心功能**:
- 礼包活动系统（推荐礼包、补偿礼包、新人礼包、认证礼包）
- 限时活动系统
- 活动管理功能
- 奖励管理
#### 7. **Task** - 任务模块
- **路径**: `app/Module/Task`
- **功能**: 任务系统，管理游戏内各类任务
- **状态**: ✅ 已完成
- **核心功能**:
- 多类型任务管理（日常、周常、成就、活动、新手引导、团队）
- 任务进度跟踪
- 任务奖励系统
- 任务重置机制（被动重置）
- 任务通知
#### 8. **Promotion** - 团队模块
- **路径**: `app/Module/Promotion`
- **功能**: 管理用户推荐关系、团队结构、达人等级和收益分成
- **状态**: ✅ 已完成
- **核心功能**:
- 推荐关系管理（直推、间推）
- 达人等级系统（5个等级）
- 团队收益分成
- 团队数据统计
- 推荐码生成
### 💰 资金管理模块 (4个)
专门处理游戏内各种资金和积分的管理：
#### 10. **Fund** - 资金模块
- **路径**: `app/Module/Fund`
- **功能**: 资金管理系统，处理用户资金相关操作
- **状态**: ✅ 已完成
- **核心功能**:
- 账户余额管理
- 资金转账
- 资金冻结
- 资金日志记录
- 订单管理
- 货币类型管理
- **特点**: 使用DECIMAL(30,10)存储，支持10位小数精度
#### 11. **Point** - 积分模块
- **路径**: `app/Module/Point`
- **功能**: 积分管理系统，专注于整数型积分逻辑处理
- **状态**: ✅ 已完成
- **核心功能**:
- 积分账户管理
- 积分转账
- 积分冻结
- 积分日志记录
- 积分订单管理
- 积分类型管理
- **特点**: 基于Fund模块创建，专注整数型积分，无小数运算
#### 12. **Mex** - 交易所模块
- **路径**: `app/Module/Mex`
- **功能**: 物品交易所系统，用户买入卖出物品撮合交易
- **状态**: ✅ 已完成
- **核心功能**:
- 挂单系统（买入/卖出）
- 撮合交易
- 仓库管理
- 价格配置
- 交易记录
- **特点**: 仓库账户USER_ID为15，调控账户USER_ID为16
#### 13. **Transfer** - 划转模块
- **路径**: `app/Module/Transfer`
- **功能**: 资金划转/流转系统，处理用户与外部系统之间的资金转入转出操作
- **状态**: ✅ 已完成
- **核心功能**:
- 资金转入/转出管理
- 多应用支持和汇率转换
- 手续费机制和统计
- 订单管理和状态跟踪
- 自动化处理和回调
- 第三方应用集成
- **特点**: 基于TransferOld重新设计，采用现代化架构，支持完整的手续费统计功能
### 👥 用户与社交模块 (3个)
处理用户管理和社交功能：
#### 13. **User** - 用户模块
- **路径**: `app/Module/User`
- **功能**: 用户服务
- **状态**: 🔧 基础功能
- **核心功能**: 用户基础信息管理
#### 14. **Friend** - 好友模块
- **路径**: `app/Module/Friend`
- **功能**: 好友系统
- **状态**: ✅ 已完成
- **核心功能**:
- 好友关系管理
- 好友请求处理
- 好友状态管理
#### 15. **Game** - 游戏统筹模块
- **路径**: `app/Module/Game`
- **功能**: 游戏的统筹模块，对逻辑进行统筹管理
- **状态**: ✅ 已完成
- **特点**: 不实现具体游戏逻辑，提供暂存系统等统筹功能
### 🔧 基础服务模块 (10个)
提供系统基础功能和服务：
#### 16. **ThirdParty** - 第三方服务管理模块
- **路径**: `app/Module/ThirdParty`
- **功能**: 专门处理接入第三方服务的需求，提供统一的第三方服务管理、认证、监控和调用功能
- **状态**: ✅ 已完成
- **核心功能**:
- 服务配置管理（统一管理各种第三方服务的配置信息）
- 认证凭证管理（安全存储和管理API密钥、Token等认证信息）
- 服务状态监控（实时监控第三方服务的可用性和响应时间）
- 调用日志记录（详细记录所有第三方API调用的日志信息）
- 错误处理和重试（统一的错误处理机制和智能重试策略）
- 配额和限流管理（管理第三方服务的调用配额和频率限制）
- **特点**: 与OpenAPI模块互补，OpenAPI是提供API给别人，ThirdParty是使用别人的API
- **支持服务**: 短信、邮件、推送、支付、存储、地图、AI、社交、分析、CDN、验证码、翻译等12种服务类型
#### 17. **OpenAPI** - 对外开放API管理模块
- **路径**: `app/Module/OpenAPI`
- **功能**: 专门处理对外开放API的需求，为第三方应用提供安全、稳定的API接入服务
- **状态**: ✅ 已完成
- **核心功能**:
- 应用管理（第三方应用注册、审核、密钥管理、状态控制）
- 认证授权（API Key、OAuth2.0、JWT、签名认证等多种认证方式）
- 权限控制（19种权限范围、细粒度权限管理、动态权限分配）
- 访问控制（频率限制、IP白名单、时间窗口控制、并发限制）
- 监控统计（实时调用监控、日志记录、统计分析、性能指标）
- 开发支持（API文档、多语言SDK、在线调试工具、错误码说明）
- **特点**: 完整的API管理生态，支持多种认证方式，提供丰富的监控和开发工具
#### 18. **Admin** - 后台基础功能扩展模块
- **路径**: `app/Module/Admin`
- **功能**: 扩展后台基础功能，提供通用的后台管理组件和工具
- **状态**: ✅ 已完成
- **核心功能**:
- 仪表板功能（系统概览、性能监控、快捷操作）
- 缓存管理（状态查看、清理操作、预热功能）
- 日志管理（操作记录、查看筛选、导出清理）
- 系统信息（服务器信息、PHP环境、数据库状态）
- 通用组件（表格辅助、表单辅助、小部件组件）
- 系统维护（维护操作、备份管理、性能优化）
- **特点**: 专注后台基础功能，不处理具体业务逻辑，为其他模块提供通用组件
#### 19. **System** - 系统模块
- **路径**: `app/Module/System`
- **功能**: 系统基础功能
- **状态**: ✅ 已完成
- **核心功能**:
- 系统配置管理
- 管理员操作日志
- 系统日志管理
- 缓存管理
- 工具类
#### 20. **File** - 文件模块
- **路径**: `app/Module/File`
- **功能**: 文件和图片上传、存储和访问的基础模块
- **状态**: ✅ 已完成
- **核心功能**:
- 文件上传
- 图片处理
- 文件访问
- 临时文件处理
- 文件模板
#### 21. **Notification** - 通知模块
- **路径**: `app/Module/Notification`
- **功能**: 统一的消息通知系统
- **状态**: ✅ 已完成
- **核心功能**:
- 通知模板管理
- 多渠道通知（短信、邮件、推送）
- 通知记录
- 批量发送
#### 22. **Sms** - 短信模块
- **路径**: `app/Module/Sms`
- **功能**: 统一的短信发送系统
- **状态**: ✅ 已完成
- **核心功能**:
- 短信发送
- 短信模板管理
- 多服务商支持
- 发送记录
#### 23. **Mail** - 邮件模块
- **路径**: `app/Module/Mail`
- **功能**: 统一的邮件发送系统
- **状态**: ✅ 已完成
- **核心功能**:
- 邮件发送
- 邮件模板管理
- 多服务商支持
- 发送记录
#### 24. **Push** - 推送模块
- **路径**: `app/Module/Push`
- **功能**: 统一的手机推送系统
- **状态**: ✅ 已完成
- **核心功能**:
- 推送发送
- 推送模板管理
- 多服务商支持
- 设备管理
#### 25. **OAuth** - OAuth认证模块
- **路径**: `app/Module/OAuth`
- **功能**: OAuth认证服务
- **状态**: ✅ 已完成
- **核心功能**:
- OAuth认证
- 客户端管理
- 访问令牌管理
### 🛠️ 工具模块 (7个)
提供开发和运维工具：
#### 26. **LCache** - 本地缓存模块
- **路径**: `app/Module/LCache`
- **功能**: 本地缓存系统
- **状态**: ✅ 已完成
- **核心功能**: 缓存管理、队列缓存
#### 27. **DelayQueue** - 延迟队列模块
- **路径**: `app/Module/DelayQueue`
- **功能**: 延迟队列(Redis)
- **状态**: ✅ 已完成
- **核心功能**: Redis延迟队列处理
#### 28. **Test** - 测试模块
- **路径**: `app/Module/Test`
- **功能**: 示例模块，展示模块化开发最佳实践
- **状态**: ✅ 已完成
- **特点**: 包含完整的模块结构示例
#### 29. **Dev** - 开发者模块
- **路径**: `app/Module/Dev`
- **功能**: 开发者工具
- **状态**: ✅ 已完成
- **核心功能**: 开发调试工具
#### 30. **Ulogic** - 用户逻辑模块
- **路径**: `app/Module/Ulogic`
- **功能**: 常见用户逻辑处理
- **状态**: ✅ 已完成
- **核心功能**:
- 站内信
- 封号
- 惩罚
- 时间处理
#### 31. **Protobuf** - Protobuf模块
- **路径**: `app/Module/Protobuf`
- **功能**: Protobuf相关功能
- **状态**: ✅ 已完成
- **核心功能**: 枚举验证器
#### 32. **Cleanup** - 数据清理模块
- **路径**: `app/Module/Cleanup`
- **功能**: 专门用于数据清理的系统模块，提供灵活的数据清理配置和执行功能
- **状态**: 🔧 基础功能（75%完成）
- **核心功能**:
- 灵活表选择（自定义、模块、分类、全量、混合）
- 5种清理类型（清空表、删除所有、按时间、按用户、按条件）
- 安全机制（多重确认、预览模式、自动备份）
- 批量处理和实时监控
- 命令行工具和后台管理
- **特点**: 主要用于测试环境数据清理，支持Model扫描和自动配置生成
### 📝 内容模块 (2个)
处理内容管理：
#### 32. **Article** - 文章模块
- **路径**: `app/Module/Article`
- **功能**: 文章管理
- **状态**: 🔧 基础功能
#### 34. **China** - 中国特殊内容模块
- **路径**: `app/Module/China`
- **功能**: 中国特殊内容模块
- **状态**: ✅ 已完成
### 🚀 扩展模块 (2个)
处理特殊业务需求和扩展功能：
#### 35. **UrsPromotion** - URS推广模块
- **路径**: `app/Module/UrsPromotion`
- **功能**: 专门为URS业务场景设计的推广模块，管理URS用户推荐关系和团队收益分成
- **状态**: 🚧 开发中
- **核心功能**:
- URS推荐关系管理（直推、间推、三推）
- URS达人等级系统（6个等级）
- URS团队收益分成（推广收益、种植收益）
- URS转账手续费配置（基于房屋等级和达人等级）
- 用户映射关系管理
- **特点**: 与Promotion模块完全独立，采用分离映射关系设计，支持跳过机制
#### 36. **TransferOld** - 旧版划转模块
- **路径**: `app/Module/TransferOld`
- **功能**: 旧版资金划转系统，已被Transfer模块替代
- **状态**: ⏸️ 已废弃
- **说明**: 保留用于数据迁移和兼容性，新功能请使用Transfer模块
## 模块状态说明
- ✅ **已完成**: 模块功能完整，可正常使用
- 🔧 **基础功能**: 模块基本功能可用，可能需要进一步完善
- 📋 **文档阶段**: 模块处于设计文档阶段，未开始开发
- 🚧 **开发中**: 模块正在开发中
- ⏸️ **已废弃**: 模块已废弃，不再维护
## 模块状态分布
### 状态分布图表
```mermaid
pie title 模块状态分布 (总计37个模块)
"✅ 已完成" : 31
"🔧 基础功能" : 3
"📋 文档阶段" : 1
"🚧 开发中" : 1
"⏸️ 已废弃" : 1
```
### 详细统计
- ✅ **已完成**: 31个模块 (84%) - 功能完整，可正常使用
- 🔧 **基础功能**: 3个模块 (8%) - 基本功能可用，需进一步完善
- 📋 **文档阶段**: 1个模块 (3%) - 处于设计文档阶段，未开始开发
- 🚧 **开发中**: 1个模块 (3%) - 正在开发中
- ⏸️ **已废弃**: 1个模块 (3%) - 已废弃，不再维护
## 模块依赖关系
### 模块依赖关系图
```mermaid
graph TD
%% 适配层
AppGame[AppGame
游戏适配模块]
%% 业务层
Farm[Farm
农场模块]
GameItems[GameItems
游戏物品模块]
Pet[Pet
宠物模块]
Shop[Shop
商店模块]
Activity[Activity
活动模块]
Task[Task
任务模块]
Promotion[Promotion
团队模块]
%% 资金层
Fund[Fund
资金模块]
Point[Point
积分模块]
Mex[Mex
交易所模块]
Transfer[Transfer
划转模块]
%% 用户层
User[User
用户模块]
Friend[Friend
好友模块]
Game[Game
游戏统筹模块]
%% 基础服务层
ThirdParty[ThirdParty
第三方服务]
OpenAPI[OpenAPI
对外API]
Admin[Admin
后台基础功能]
System[System
系统模块]
File[File
文件模块]
Notification[Notification
通知模块]
Sms[Sms
短信模块]
Mail[Mail
邮件模块]
Push[Push
推送模块]
OAuth[OAuth
认证模块]
%% 工具模块
LCache[LCache
本地缓存]
DelayQueue[DelayQueue
延迟队列]
Ulogic[Ulogic
用户逻辑]
Cleanup[Cleanup
数据清理]
%% 扩展模块
UrsPromotion[UrsPromotion
URS推广模块]
%% 依赖关系
AppGame --> Farm
AppGame --> GameItems
AppGame --> Pet
AppGame --> Shop
AppGame --> Activity
AppGame --> Task
AppGame --> Promotion
Farm --> GameItems
Pet --> GameItems
Shop --> GameItems
Activity --> GameItems
Task --> GameItems
Shop --> Fund
Activity --> Fund
Mex --> Fund
Point --> Fund
Transfer --> Fund
Mex --> GameItems
Pet --> Game
Fund --> User
Point --> User
GameItems --> User
Pet --> User
Shop --> User
Activity --> User
Task --> User
Promotion --> User
UrsPromotion --> User
Friend --> User
Notification --> Sms
Notification --> Mail
Notification --> Push
ThirdParty --> System
ThirdParty --> User
OpenAPI --> OAuth
OpenAPI --> User
OpenAPI --> Admin
OpenAPI --> System
Admin --> System
Admin --> File
Admin --> User
%% 样式定义
classDef coreModule fill:#e1f5fe,stroke:#01579b,stroke-width:2px
classDef fundModule fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
classDef userModule fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px
classDef serviceModule fill:#fff3e0,stroke:#e65100,stroke-width:2px
classDef toolModule fill:#fce4ec,stroke:#880e4f,stroke-width:2px
classDef extModule fill:#f1f8e9,stroke:#33691e,stroke-width:2px
class AppGame,Farm,GameItems,Pet,Shop,Activity,Task,Promotion coreModule
class Fund,Point,Mex,Transfer fundModule
class User,Friend,Game userModule
class ThirdParty,OpenAPI,Admin,System,File,Notification,Sms,Mail,Push,OAuth serviceModule
class LCache,DelayQueue,Ulogic,Cleanup toolModule
class UrsPromotion extModule
```
### 核心依赖链
```
AppGame (适配层)
↓
Farm + GameItems + Pet + Shop + Activity + Task + Promotion (业务层)
↓
Fund + Point + Mex + Transfer (资金层)
↓
User + Friend + Game (用户层)
↓
ThirdParty + OpenAPI + Admin + System + File + Notification + Sms + Mail + Push + OAuth (基础服务层)
↓
UrsPromotion (扩展层)
```
### 重要依赖关系
- **ThirdParty模块**: 为系统提供第三方服务接入能力，被Sms、Mail、Push等模块依赖，依赖System、User模块
- **OpenAPI模块**: 为第三方应用提供API接入服务，依赖OAuth、User、Admin、System模块
- **Admin模块**: 为所有模块提供后台基础功能和通用组件，依赖System、File、User模块
- **GameItems模块**: 被Farm、Pet、Shop、Activity、Task等模块依赖
- **Fund模块**: 被Mex、Shop、Activity、Transfer等模块依赖，提供资金管理
- **Point模块**: 基于Fund模块架构，专门处理积分
- **Transfer模块**: 基于Fund模块，提供资金划转功能，替代TransferOld模块
- **Notification模块**: 整合Sms、Mail、Push模块，提供统一通知接口
- **Game模块**: 提供暂存系统，被Pet等模块使用
- **UrsPromotion模块**: 独立的URS推广系统，与Promotion模块完全分离
- **Cleanup模块**: 独立的数据清理工具，可清理所有模块数据
## 开发规范
### 目录结构标准
每个模块都遵循统一的目录结构：
```
app/Module/ModuleName/
├── AdminControllers/ # 后台管理控制器
├── Commands/ # 命令行工具
├── Databases/ # 数据库相关文件
├── Docs/ # 详细文档目录
├── Enums/ # 枚举类型定义
├── Events/ # 事件类
├── Listeners/ # 事件监听器
├── Logics/ # 业务逻辑类（内部使用）
├── Models/ # 数据模型
├── Providers/ # 服务提供者
├── Repositorys/ # 数据仓库（后台专用）
├── Services/ # 服务类（对外接口）
├── Validations/ # 验证规则
├── Validators/ # 验证器
└── README.md # 模块文档
```
### 命名规范
- **表名前缀**: 所有数据库表使用`kku_`前缀
- **模块表前缀**:
- 物品模块: `item_`
- 宠物模块: `pet_`
- 农场模块: `farm_`
- 资金模块: `fund_`
- 积分模块: `point_`
- 第三方服务模块: `thirdparty_`
- **Handler命名空间**: `App\Module\AppGame\Handler`
- **枚举命名**: 使用PHP enum语法，避免魔法数字
### 架构原则
- **服务是对外的**: Services层提供对外接口
- **Logic是内部的**: Logics层处理内部业务逻辑
- **模型无业务逻辑**: Models层只负责数据结构
- **Repository后台专用**: 只用于后台管理数据访问
- **事务保证一致性**: 所有涉及多个操作的功能都使用数据库事务
## 最后更新
本文档最后更新时间：**2025年07月02日 13:23:44 CST**
### 本次更新内容
- 更新模块总数从35个到37个
- 新增Transfer模块（资金划转系统）
- 新增Cleanup模块（数据清理工具）
- 新增UrsPromotion模块（URS推广系统）
- 标记TransferOld模块为已废弃
- 修正模块分类和依赖关系
- 更新统计图表和状态分布
如需了解具体模块的详细信息，请查看各模块目录下的README.md文件。