SocialFarm模块API接口文档

概述

SocialFarm模块提供社交农场功能的API接口，包括偷菜、互助、访问等功能。所有接口都需要用户认证。

基础信息

模块路径: /api/social-farm
认证方式: Bearer Token
响应格式: JSON
字符编码: UTF-8

通用响应格式

成功响应

{
    "success": true,
    "data": {
        // 具体数据
    },
    "message": "操作成功"
}

失败响应

{
    "success": false,
    "code": "ERROR_CODE",
    "message": "错误描述",
    "data": null
}

接口列表

1. 获取可偷菜的好友列表

接口地址: GET /api/social-farm/stealable-friends

功能描述: 获取当前用户可以偷菜的好友列表

请求参数: 无

响应示例:

{
    "success": true,
    "data": [
        {
            "user_id": 123,
            "nickname": "农场主小明",
            "avatar": "https://example.com/avatar.jpg",
            "level": 15,
            "stealable_count": 3,
            "last_visit_time": "2025-07-02 10:30:00"
        }
    ]
}

2. 访问好友农场

接口地址: POST /api/social-farm/visit-farm

功能描述: 访问指定好友的农场

请求参数:

{
    "owner_id": 123,
    "visit_type": 1
}

参数说明:

owner_id: 农场主用户ID (必填)
visit_type: 访问类型 (可选，默认1普通访问)

响应示例:

{
    "success": true,
    "data": {
        "visit_id": 456,
        "farm_info": {
            "owner": {
                "user_id": 123,
                "nickname": "农场主小明",
                "level": 15
            },
            "lands": [
                {
                    "id": 1,
                    "position_x": 0,
                    "position_y": 0,
                    "crop": {
                        "id": 789,
                        "item_id": 1001,
                        "item_name": "胡萝卜",
                        "growth_stage": 4,
                        "is_mature": true,
                        "can_steal": true,
                        "steal_reason": ""
                    },
                    "help_types": [1, 2]
                }
            ]
        },
        "permissions": {
            "can_steal": true,
            "can_help": true,
            "daily_steal_remaining": 8
        }
    }
}

3. 偷菜操作

接口地址: POST /api/social-farm/steal-crop

功能描述: 偷取指定土地的作物

请求参数:

{
    "owner_id": 123,
    "land_id": 456
}

参数说明:

owner_id: 农场主用户ID (必填)
land_id: 土地ID (必填)

响应示例:

{
    "success": true,
    "data": {
        "steal_id": 789,
        "item_id": 1001,
        "item_name": "胡萝卜",
        "item_amount": 5,
        "original_amount": 20,
        "steal_ratio": 0.25,
        "exp_gained": 10,
        "message": "成功偷到5个胡萝卜！"
    }
}

错误响应示例:

{
    "success": false,
    "code": "CROP_NOT_READY",
    "message": "作物还未成熟，无法偷菜"
}

4. 互助操作

接口地址: POST /api/social-farm/help-friend

功能描述: 帮助好友处理农场事务

请求参数:

{
    "owner_id": 123,
    "land_id": 456,
    "help_type": 1
}

参数说明:

owner_id: 农场主用户ID (必填)
land_id: 土地ID (必填)
help_type: 帮助类型 (必填，1浇水 2施肥 3除草 4杀虫 5收获)

响应示例:

{
    "success": true,
    "data": {
        "help_id": 321,
        "help_type": 1,
        "help_type_name": "浇水",
        "exp_gained": 5,
        "reward_item": {
            "item_id": 2001,
            "item_name": "经验药水",
            "amount": 1
        },
        "message": "成功帮助好友浇水，获得5点经验！"
    }
}

5. 获取用户社交设置

接口地址: GET /api/social-farm/settings

功能描述: 获取当前用户的社交农场设置

请求参数: 无

响应示例:

{
    "success": true,
    "data": {
        "allow_steal": true,
        "allow_help": true,
        "allow_visit": true,
        "steal_protection_hours": 2,
        "daily_steal_limit": 10,
        "daily_help_limit": 20,
        "notification_enabled": true,
        "auto_revenge": false,
        "friend_only": true,
        "blacklist_count": 0,
        "whitelist_count": 0
    }
}

6. 更新用户社交设置

接口地址: PUT /api/social-farm/settings

功能描述: 更新当前用户的社交农场设置

请求参数:

{
    "allow_steal": true,
    "allow_help": true,
    "allow_visit": true,
    "steal_protection_hours": 2,
    "daily_steal_limit": 10,
    "daily_help_limit": 20,
    "notification_enabled": true,
    "auto_revenge": false,
    "friend_only": true
}

响应示例:

{
    "success": true,
    "data": {
        "allow_steal": true,
        "allow_help": true,
        "allow_visit": true,
        "steal_protection_hours": 2,
        "daily_steal_limit": 10,
        "daily_help_limit": 20,
        "notification_enabled": true,
        "auto_revenge": false,
        "friend_only": true
    },
    "message": "设置更新成功"
}

7. 获取社交统计

接口地址: GET /api/social-farm/stats

功能描述: 获取用户的社交行为统计数据

请求参数:

date: 统计日期 (可选，格式：YYYY-MM-DD，默认今天)

响应示例:

{
    "success": true,
    "data": {
        "steal_count": 5,
        "stolen_count": 3,
        "help_count": 8,
        "helped_count": 6,
        "visit_count": 12,
        "visited_count": 9,
        "steal_items_gained": 25,
        "steal_items_lost": 15,
        "help_rewards_gained": 3,
        "total_exp_gained": 45
    }
}

8. 获取偷菜记录

接口地址: GET /api/social-farm/steal-logs

功能描述: 获取用户的偷菜记录

请求参数:

type: 记录类型 (可选，steal我偷的 stolen被偷的，默认steal)
page: 页码 (可选，默认1)
limit: 每页数量 (可选，默认20)

响应示例:

{
    "success": true,
    "data": {
        "items": [
            {
                "id": 123,
                "stealer": {
                    "user_id": 456,
                    "nickname": "偷菜小能手"
                },
                "owner": {
                    "user_id": 789,
                    "nickname": "农场主大佬"
                },
                "item": {
                    "item_id": 1001,
                    "item_name": "胡萝卜",
                    "amount": 5
                },
                "steal_time": "2025-07-02 14:30:00",
                "steal_status": 1,
                "steal_status_desc": "偷菜成功"
            }
        ],
        "pagination": {
            "current_page": 1,
            "total_pages": 5,
            "total_items": 100,
            "per_page": 20
        }
    }
}

9. 获取访问记录

接口地址: GET /api/social-farm/visit-logs

功能描述: 获取农场访问记录

请求参数:

type: 记录类型 (可选，visit我访问的 visited被访问的，默认visit)
page: 页码 (可选，默认1)
limit: 每页数量 (可选，默认20)

响应示例:

{
    "success": true,
    "data": {
        "items": [
            {
                "id": 456,
                "visitor": {
                    "user_id": 123,
                    "nickname": "访客小明"
                },
                "owner": {
                    "user_id": 789,
                    "nickname": "农场主大佬"
                },
                "visit_time": "2025-07-02 15:20:00",
                "visit_type": 2,
                "visit_type_desc": "偷菜访问",
                "duration": 180,
                "steal_count": 2,
                "help_count": 1
            }
        ],
        "pagination": {
            "current_page": 1,
            "total_pages": 3,
            "total_items": 60,
            "per_page": 20
        }
    }
}

错误码说明

错误码	描述
NO_PERMISSION	无权限访问
NOT_FRIEND	不是好友关系
FARM_NOT_FOUND	农场不存在
LAND_NOT_FOUND	土地不存在
CROP_NOT_FOUND	作物不存在
CROP_NOT_READY	作物未成熟
ALREADY_STOLEN	作物已被偷过
STEAL_LIMIT_EXCEEDED	超过偷菜次数限制
HELP_LIMIT_EXCEEDED	超过互助次数限制
UNDER_PROTECTION	农场受保护中
INSUFFICIENT_ITEMS	道具不足
INVALID_HELP_TYPE	无效的帮助类型
OPERATION_FAILED	操作失败

状态码说明

偷菜状态 (steal_status)

1: 偷菜成功
2: 偷菜失败
3: 受保护无法偷
4: 无权限偷菜
5: 超过次数限制
6: 作物未成熟
7: 已被偷过

访问类型 (visit_type)

1: 普通访问
2: 偷菜访问
3: 互助访问
4: 社交访问
5: 报复访问

帮助类型 (help_type)

1: 浇水
2: 施肥
3: 除草
4: 杀虫
5: 收获

注意事项

频率限制: 每个用户每分钟最多调用100次API
数据缓存: 农场信息会缓存5分钟，偷菜后立即更新
事务处理: 偷菜和互助操作使用数据库事务确保数据一致性
日志记录: 所有关键操作都会记录详细日志
安全验证: 所有操作前都会验证用户权限和好友关系

开发建议

错误处理: 客户端应该妥善处理各种错误情况
用户体验: 建议在操作前显示确认对话框
数据刷新: 操作成功后应该刷新相关页面数据
离线处理: 网络异常时应该提供重试机制

API接口文档.md 9.7 KB Lịch sử Raw

SocialFarm模块API接口文档

概述

基础信息

通用响应格式

成功响应

失败响应

接口列表

1. 获取可偷菜的好友列表

2. 访问好友农场

3. 偷菜操作

4. 互助操作

5. 获取用户社交设置

6. 更新用户社交设置

7. 获取社交统计

8. 获取偷菜记录

9. 获取访问记录

错误码说明

状态码说明

偷菜状态 (steal_status)

访问类型 (visit_type)

帮助类型 (help_type)

注意事项

开发建议

API接口文档.md 9.7 KB

Lịch sử Raw