# SocialFarm模块 - 社交农场系统 SocialFarm模块是开心农场系统的社交互动核心模块，负责处理好友间的农场互动功能，包括偷菜、互助、访问等社交玩法。 ## 📋 目录 - [模块概述](#模块概述) - [核心功能](#核心功能) - [架构设计](#架构设计) - [数据库设计](#数据库设计) - [API接口](#api接口) - [模块交互](#模块交互) - [配置说明](#配置说明) - [开发指南](#开发指南) ## 🎯 模块概述 ### 基本信息 - **模块名称**: SocialFarm - **功能定位**: 社交农场互动系统 - **开发状态**: 🚧 开发中 - **依赖模块**: Friend、Farm、GameItems、User、Notification ### 主要特性 - **好友农场访问**: 访问好友农场，查看农场状态 - **偷菜系统**: 偷取好友成熟作物，获得物品奖励 - **互助功能**: 帮助好友处理农场事务（浇水、施肥、除草等） - **社交记录**: 完整的社交行为记录和统计 - **权限控制**: 灵活的农场访问权限设置 - **防护机制**: 偷菜保护、次数限制等平衡机制 ## 🎮 核心功能 ### 1. 偷菜系统 - **偷菜条件检查**: 好友关系、作物状态、权限验证 - **偷菜执行**: 计算收益、更新作物、记录日志 - **偷菜限制**: 每日次数限制、冷却时间、保护机制 - **收益计算**: 基于作物类型、成熟度的动态收益 ### 2. 好友农场访问 - **农场浏览**: 查看好友农场布局和作物状态 - **访问记录**: 记录访问行为和时间 - **权限控制**: 基于好友关系的访问权限 - **实时状态**: 获取农场实时数据 ### 3. 互助功能 - **帮助浇水**: 帮助好友给作物浇水 - **协助施肥**: 使用道具帮助好友施肥 - **清除灾害**: 帮助清除好友农场的灾害 - **互助奖励**: 互助行为的奖励机制 ### 4. 社交设置 - **隐私控制**: 设置农场访问权限 - **偷菜保护**: 开启偷菜保护时间 - **互助设置**: 允许/禁止好友互助 - **通知设置**: 社交行为通知开关 ## 🏗️ 架构设计 ### 目录结构 ``` app/Module/SocialFarm/ ├── AdminControllers/ # 后台管理控制器 │ ├── StealLogController.php # 偷菜记录管理 │ ├── VisitLogController.php # 访问记录管理 │ ├── SocialSettingController.php # 社交设置管理 │ └── Helper/ # 辅助类 ├── Commands/ # 命令行工具 │ ├── CleanExpiredLogsCommand.php # 清理过期日志 │ └── SocialFarmStatsCommand.php # 社交统计命令 ├── Databases/ # 数据库相关文件 │ ├── createsql/ # 表创建SQL │ └── GenerateSql/ # 生成的SQL文件 ├── Docs/ # 详细文档目录 │ ├── 设计概述.md # 设计概述 │ ├── 数据库设计.md # 数据库设计 │ ├── API接口文档.md # API接口文档 │ ├── 偷菜系统设计.md # 偷菜系统设计 │ └── 互助系统设计.md # 互助系统设计 ├── Dtos/ # 数据传输对象 │ ├── FarmVisitDto.php # 农场访问DTO │ ├── StealResultDto.php # 偷菜结果DTO │ └── SocialActionDto.php # 社交行为DTO ├── Enums/ # 枚举定义 │ ├── STEAL_STATUS.php # 偷菜状态枚举 │ ├── SOCIAL_ACTION.php # 社交行为枚举 │ ├── VISIT_TYPE.php # 访问类型枚举 │ └── PROTECTION_TYPE.php # 保护类型枚举 ├── Events/ # 事件类 │ ├── CropStolenEvent.php # 作物被偷事件 │ ├── FarmVisitedEvent.php # 农场被访问事件 │ └── HelpActionEvent.php # 互助行为事件 ├── Listeners/ # 事件监听器 │ ├── SendStealNotificationListener.php # 发送偷菜通知 │ └── UpdateSocialStatsListener.php # 更新社交统计 ├── Logics/ # 业务逻辑类 │ ├── StealLogic.php # 偷菜逻辑 │ ├── VisitLogic.php # 访问逻辑 │ ├── HelpLogic.php # 互助逻辑 │ └── PermissionLogic.php # 权限逻辑 ├── Models/ # 数据模型 │ ├── SocialFarmStealLog.php # 偷菜记录模型 │ ├── SocialFarmVisitLog.php # 访问记录模型 │ ├── SocialFarmSetting.php # 社交设置模型 │ └── SocialFarmHelpLog.php # 互助记录模型 ├── Providers/ # 服务提供者 │ └── SocialFarmServiceProvider.php # 模块服务提供者 ├── Repositories/ # 数据仓库（后台专用） │ ├── StealLogRepository.php # 偷菜记录仓库 │ └── VisitLogRepository.php # 访问记录仓库 ├── Services/ # 对外服务类 │ ├── SocialFarmService.php # 主服务类 │ ├── StealService.php # 偷菜服务 │ ├── VisitService.php # 访问服务 │ └── HelpService.php # 互助服务 ├── Validations/ # 验证规则 │ ├── StealValidation.php # 偷菜验证 │ └── VisitValidation.php # 访问验证 ├── Validators/ # 验证器 │ ├── StealValidator.php # 偷菜验证器 │ └── PermissionValidator.php # 权限验证器 └── README.md # 本文档 ``` ### 核心类设计 #### 1. 服务层 (Services) - **SocialFarmService**: 主服务类，提供统一的对外接口 - **StealService**: 偷菜功能服务 - **VisitService**: 农场访问服务 - **HelpService**: 互助功能服务 #### 2. 逻辑层 (Logics) - **StealLogic**: 偷菜业务逻辑处理 - **VisitLogic**: 访问权限和逻辑处理 - **HelpLogic**: 互助行为逻辑处理 - **PermissionLogic**: 权限验证逻辑 #### 3. 数据层 (Models) - **SocialFarmStealLog**: 偷菜记录数据模型 - **SocialFarmVisitLog**: 访问记录数据模型 - **SocialFarmSetting**: 用户社交设置模型 - **SocialFarmHelpLog**: 互助记录数据模型 ## 📊 数据库设计 ### 核心数据表 #### 1. 偷菜记录表 (social_farm_steal_logs) | 字段名 | 类型 | 说明 | |--------|------|------| | id | bigint | 主键ID | | stealer_id | bigint | 偷菜者用户ID | | owner_id | bigint | 农场主用户ID | | land_id | bigint | 被偷的土地ID | | crop_id | bigint | 被偷的作物ID | | item_id | bigint | 偷到的物品ID | | item_amount | int | 偷到的物品数量 | | steal_time | timestamp | 偷菜时间 | | steal_status | tinyint | 偷菜状态 | #### 2. 农场访问记录表 (social_farm_visit_logs) | 字段名 | 类型 | 说明 | |--------|------|------| | id | bigint | 主键ID | | visitor_id | bigint | 访问者用户ID | | owner_id | bigint | 农场主用户ID | | visit_time | timestamp | 访问时间 | | visit_type | tinyint | 访问类型 | | actions | json | 访问期间的行为记录 | | duration | int | 访问持续时间(秒) | #### 3. 社交设置表 (social_farm_settings) | 字段名 | 类型 | 说明 | |--------|------|------| | id | bigint | 主键ID | | user_id | bigint | 用户ID | | allow_steal | tinyint | 允许偷菜 | | allow_help | tinyint | 允许互助 | | allow_visit | tinyint | 允许访问 | | steal_protection_hours | int | 偷菜保护时长 | | daily_steal_limit | int | 每日偷菜次数限制 | | notification_enabled | tinyint | 通知开关 | #### 4. 互助记录表 (social_farm_help_logs) | 字段名 | 类型 | 说明 | |--------|------|------| | id | bigint | 主键ID | | helper_id | bigint | 帮助者用户ID | | owner_id | bigint | 农场主用户ID | | land_id | bigint | 帮助的土地ID | | help_type | tinyint | 帮助类型 | | help_time | timestamp | 帮助时间 | | reward_item_id | bigint | 奖励物品ID | | reward_amount | int | 奖励数量 | ## 🔧 配置说明 ### 系统配置 ```php // config/socialfarm.php return [ // 偷菜配置 'steal' => [ 'daily_limit' => 10, // 每日偷菜次数限制 'cooldown_minutes' => 5, // 偷菜冷却时间(分钟) 'protection_hours' => 2, // 默认保护时长(小时) 'min_yield_ratio' => 0.1, // 最小偷菜收益比例 'max_yield_ratio' => 0.3, // 最大偷菜收益比例 ], // 访问配置 'visit' => [ 'max_duration' => 1800, // 最大访问时长(秒) 'log_retention_days' => 30, // 访问日志保留天数 ], // 互助配置 'help' => [ 'daily_limit' => 20, // 每日互助次数限制 'reward_probability' => 0.3, // 互助奖励概率 'exp_reward' => 5, // 互助经验奖励 ], ]; ``` ## 🚀 开发计划 ### 第一阶段：基础功能 (预计2周) - [x] 模块目录结构创建 - [ ] 数据库表设计和创建 - [ ] 基础模型和枚举定义 - [ ] 核心服务类框架 - [ ] 基础偷菜功能实现 ### 第二阶段：完善功能 (预计2周) - [ ] 农场访问功能 - [ ] 权限控制系统 - [ ] 社交设置管理 - [ ] 通知系统集成 - [ ] 后台管理界面 ### 第三阶段：扩展功能 (预计1周) - [ ] 互助功能实现 - [ ] 社交统计和排行 - [ ] 性能优化 - [ ] 测试和文档完善 ## 📚 相关文档 - [设计概述](Docs/设计概述.md) - 模块整体设计思路 - [数据库设计](Docs/数据库设计.md) - 详细的数据库表结构 - [API接口文档](Docs/API接口文档.md) - 完整的API接口说明 - [偷菜系统设计](Docs/偷菜系统设计.md) - 偷菜功能详细设计 - [互助系统设计](Docs/互助系统设计.md) - 互助功能详细设计 ## 🔗 模块依赖 ### 依赖的模块 - **Friend模块**: 获取好友关系和好友列表 - **Farm模块**: 获取农场和作物信息 - **GameItems模块**: 处理物品奖励和消耗 - **User模块**: 获取用户基础信息 - **Notification模块**: 发送社交行为通知 ### 被依赖的模块 - **AppGame模块**: 提供客户端接口处理 ## 📝 开发注意事项 1. **数据一致性**: 所有涉及多个操作的功能都使用数据库事务 2. **性能优化**: 社交查询和统计应考虑缓存策略 3. **安全验证**: 所有操作前验证用户权限和好友关系 4. **防刷机制**: 实现完善的防刷和限流机制 5. **日志记录**: 记录关键操作，便于问题排查和数据分析 ## 📈 版本信息 - **创建时间**: 2025年07月02日 - **当前版本**: v1.0.0-dev - **开发状态**: 🚧 开发中 - **维护者**: 开发团队 --- 如需了解具体功能的详细信息，请查看Docs目录下的相关文档。