SocialFarm模块 - 社交农场系统
SocialFarm模块是开心农场系统的社交互动核心模块，负责处理好友间的农场互动功能，包括偷菜、互助、访问等社交玩法。
📋 目录
🎯 模块概述
基本信息
- 模块名称: 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 |
奖励数量 |
🔧 配置说明
系统配置
// 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周)
第二阶段：完善功能 (预计2周)
第三阶段：扩展功能 (预计1周)
📚 相关文档
🔗 模块依赖
依赖的模块
- Friend模块: 获取好友关系和好友列表
- Farm模块: 获取农场和作物信息
- GameItems模块: 处理物品奖励和消耗
- User模块: 获取用户基础信息
- Notification模块: 发送社交行为通知
被依赖的模块
📝 开发注意事项
- 数据一致性: 所有涉及多个操作的功能都使用数据库事务
- 性能优化: 社交查询和统计应考虑缓存策略
- 安全验证: 所有操作前验证用户权限和好友关系
- 防刷机制: 实现完善的防刷和限流机制
- 日志记录: 记录关键操作，便于问题排查和数据分析
📈 版本信息
- 创建时间: 2025年07月02日
- 当前版本: v1.0.0-dev
- 开发状态: 🚧 开发中
- 维护者: 开发团队
如需了解具体功能的详细信息，请查看Docs目录下的相关文档。
AI Assistant
6dd3e863db
优化推广统计方法性能：使用UrsUserRelationCache替代多次查询