# 管理后台接口设计文档 ## 1. 概述 ### 1.1 项目简介 本文档详细描述了结伴客管理后台系统的所有API接口设计，包括用户管理、旅行管理、动物认领管理、订单管理、系统管理等模块的接口规范。 ### 1.2 接口设计原则 - **RESTful风格**：遵循REST架构风格 - **统一响应格式**：所有接口采用统一的响应格式 - **版本控制**：支持API版本管理 - **安全认证**：JWT Token认证机制 - **错误处理**：统一的错误码和错误信息 ### 1.3 技术规范 - **协议**：HTTPS - **数据格式**：JSON - **字符编码**：UTF-8 - **认证方式**：JWT Bearer Token - **API版本**：v1 ## 2. 通用规范 ### 2.1 请求格式 #### 2.1.1 请求头 ```http Content-Type: application/json Authorization: Bearer Accept: application/json User-Agent: JieBanKe-Admin/1.0.0 ``` #### 2.1.2 请求参数 - **路径参数**：用于资源标识，如 `/api/v1/users/{id}` - **查询参数**：用于过滤、排序、分页等，如 `?page=1&size=20&sort=created_at:desc` - **请求体**：JSON格式的数据 ### 2.2 响应格式 #### 2.2.1 成功响应 ```json { "code": 200, "message": "操作成功", "data": { // 具体数据 }, "timestamp": "2024-01-15T10:30:00Z", "request_id": "req_123456789" } ``` #### 2.2.2 分页响应 ```json { "code": 200, "message": "获取成功", "data": { "items": [ // 数据列表 ], "pagination": { "page": 1, "size": 20, "total": 100, "pages": 5 } }, "timestamp": "2024-01-15T10:30:00Z", "request_id": "req_123456789" } ``` #### 2.2.3 错误响应 ```json { "code": 400, "message": "请求参数错误", "error": { "type": "VALIDATION_ERROR", "details": [ { "field": "email", "message": "邮箱格式不正确" } ] }, "timestamp": "2024-01-15T10:30:00Z", "request_id": "req_123456789" } ``` ### 2.3 状态码规范 | 状态码 | 说明 | 使用场景 | |--------|------|----------| | 200 | 成功 | 请求成功处理 | | 201 | 创建成功 | 资源创建成功 | | 204 | 无内容 | 删除成功或更新成功无返回内容 | | 400 | 请求错误 | 参数错误、格式错误 | | 401 | 未授权 | 未登录或token无效 | | 403 | 禁止访问 | 权限不足 | | 404 | 资源不存在 | 请求的资源不存在 | | 409 | 冲突 | 资源冲突，如用户名已存在 | | 422 | 实体错误 | 业务逻辑错误 | | 500 | 服务器错误 | 内部服务器错误 | ### 2.4 分页参数 | 参数名 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | page | integer | 1 | 页码，从1开始 | | size | integer | 20 | 每页数量，最大100 | | sort | string | created_at:desc | 排序字段和方向 | ### 2.5 排序参数格式 - 单字段排序：`sort=created_at:desc` - 多字段排序：`sort=status:asc,created_at:desc` - 支持的排序方向：`asc`（升序）、`desc`（降序） ## 3. 认证授权接口 ### 3.1 管理员登录 #### 接口信息 - **接口路径**：`POST /api/v1/admin/login` - **接口描述**：管理员登录获取访问令牌 - **是否需要认证**：否 #### 请求参数 ```json { "username": "admin", "password": "password123" } ``` | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | username | string | 是 | 用户名 | | password | string | 是 | 密码 | #### 响应示例 ```json { "success": true, "code": 200, "message": "登录成功", "data": { "admin": { "id": 1, "username": "admin", "role": "super_admin", "created_at": "2024-01-01T10:00:00Z" }, "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } } ``` ### 3.2 获取管理员信息 #### 接口信息 - **接口路径**：`GET /api/v1/admin/profile` - **接口描述**：获取当前登录管理员的信息 - **是否需要认证**：是 #### 响应示例 ```json { "success": true, "code": 200, "message": "获取成功", "data": { "id": 1, "username": "admin", "role": "super_admin", "created_at": "2024-01-01T10:00:00Z", "last_login_at": "2024-01-15T09:30:00Z" } } ``` ### 3.3 获取仪表板数据 #### 接口信息 - **接口路径**：`GET /api/v1/admin/dashboard` - **接口描述**：获取管理后台仪表板统计数据 - **是否需要认证**：是 #### 响应示例 ```json { "success": true, "code": 200, "message": "获取成功", "data": { "statistics": { "totalUsers": 1000, "totalAnimals": 300, "totalTravels": 200, "totalOrders": 1500 }, "recentActivities": [ { "type": "user_register", "message": "新用户注册", "time": "2024-01-15T10:30:00Z" } ], "systemInfo": { "nodeVersion": "v18.17.0", "platform": "linux", "uptime": 86400 } } } ``` ## 4. 用户管理接口 ### 4.1 获取用户列表 #### 接口信息 - **接口路径**：`GET /api/v1/admin/users` - **接口描述**：获取用户列表，支持分页、搜索和筛选 - **是否需要认证**：是 #### 查询参数 | 参数名 | 类型 | 必填 | 默认值 | 说明 | |--------|------|------|--------|------| | page | integer | 否 | 1 | 页码 | | pageSize | integer | 否 | 10 | 每页数量 | | keyword | string | 否 | - | 搜索关键词（昵称、手机号、邮箱） | | userType | string | 否 | - | 用户类型 | | status | string | 否 | - | 用户状态（active/inactive/banned） | | startDate | string | 否 | - | 开始日期 | | endDate | string | 否 | - | 结束日期 | | sortField | string | 否 | created_at | 排序字段 | | sortOrder | string | 否 | desc | 排序方向（asc/desc） | #### 响应示例 ```json { "success": true, "code": 200, "message": "获取成功", "data": { "users": [ { "id": 1, "openid": "wx_openid_123456", "unionid": "wx_unionid_789012", "nickname": "张三", "avatar": "https://example.com/avatar.jpg", "phone": "13800138000", "email": "zhangsan@example.com", "gender": 1, "birthday": "1990-01-01", "location": "北京市朝阳区", "bio": "热爱旅行和小动物", "user_type": "regular", "status": "active", "interests": ["旅行", "摄影"], "occupation": "软件工程师", "real_name": "张三", "id_card": "110101199001011234", "real_name_verified": true, "phone_verified": true, "email_verified": false, "balance": 1500.00, "points": 1200, "level": 3, "travel_count": 5, "animal_claim_count": 2, "last_login_at": "2024-01-15T10:30:00Z", "created_at": "2024-01-01T10:00:00Z", "updated_at": "2024-01-15T10:30:00Z" } ], "pagination": { "page": 1, "pageSize": 10, "total": 100, "totalPages": 10 } } } ``` ### 4.2 获取用户详情 #### 接口信息 - **接口路径**：`GET /api/v1/admin/users/{userId}` - **接口描述**：获取指定用户的详细信息 - **是否需要认证**：是 #### 路径参数 | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | userId | integer | 是 | 用户ID | #### 响应示例 ```json { "success": true, "code": 200, "message": "获取成功", "data": { "user": { "id": 1, "openid": "wx_openid_123456", "unionid": "wx_unionid_789012", "nickname": "张三", "avatar": "https://example.com/avatar.jpg", "phone": "13800138000", "email": "zhangsan@example.com", "gender": 1, "birthday": "1990-01-01", "location": "北京市朝阳区", "bio": "热爱旅行和小动物", "user_type": "regular", "status": "active", "interests": ["旅行", "摄影"], "occupation": "软件工程师", "real_name": "张三", "id_card": "110101199001011234", "real_name_verified": true, "phone_verified": true, "email_verified": false, "balance": 1500.00, "points": 1200, "level": 3, "travel_count": 5, "animal_claim_count": 2, "recentTravels": [ { "id": 1, "title": "北京三日游", "destination": "北京", "start_date": "2024-01-10", "end_date": "2024-01-12", "status": "completed", "created_at": "2024-01-05T10:00:00Z" } ], "recentClaims": [ { "id": 1, "animal_name": "小白", "status": "approved", "created_at": "2024-01-08T10:00:00Z" } ], "last_login_at": "2024-01-15T10:30:00Z", "created_at": "2024-01-01T10:00:00Z", "updated_at": "2024-01-15T10:30:00Z" } } } ``` ### 4.3 更新用户状态 #### 接口信息 - **接口路径**：`PUT /api/v1/admin/users/{userId}/status` - **接口描述**：更新用户状态 - **是否需要认证**：是 #### 路径参数 | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | userId | integer | 是 | 用户ID | #### 请求参数 ```json { "status": "banned", "reason": "违规行为" } ``` | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | status | string | 是 | 用户状态（active/inactive/banned） | | reason | string | 否 | 操作原因 | #### 响应示例 ```json { "success": true, "code": 200, "message": "状态更新成功" } ``` ### 4.4 批量更新用户状态 #### 接口信息 - **接口路径**：`PUT /api/v1/admin/users/batch-status` - **接口描述**：批量更新用户状态 - **是否需要认证**：是 #### 请求参数 ```json { "userIds": [1, 2, 3], "status": "inactive", "reason": "批量操作" } ``` | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | userIds | array | 是 | 用户ID数组 | | status | string | 是 | 用户状态（active/inactive/banned） | | reason | string | 否 | 操作原因 | #### 响应示例 ```json { "success": true, "code": 200, "message": "批量更新成功", "data": { "successCount": 3, "failedCount": 0 } } ``` ### 4.5 获取用户统计数据 #### 接口信息 - **接口路径**：`GET /api/v1/admin/users/statistics` - **接口描述**：获取用户统计数据 - **是否需要认证**：是 #### 查询参数 | 参数名 | 类型 | 必填 | 默认值 | 说明 | |--------|------|------|--------|------| | period | string | 否 | 30d | 统计周期（7d/30d/90d/1y） | #### 响应示例 ```json { "success": true, "code": 200, "message": "获取成功", "data": { "totalUsers": 1000, "activeUsers": 800, "newUsersToday": 10, "newUsersThisWeek": 50, "newUsersThisMonth": 200, "userGrowthChart": [ { "date": "2024-01-01", "count": 10 } ], "statusDistribution": { "active": 800, "inactive": 150, "banned": 50 }, "levelDistribution": { "1": 400, "2": 300, "3": 200, "4": 80, "5": 20 } } } ``` ### 4.6 导出用户数据 #### 接口信息 - **接口路径**：`GET /api/v1/admin/users/export` - **接口描述**：导出用户数据为Excel文件 - **是否需要认证**：是 #### 查询参数 | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | format | string | 否 | 导出格式（excel/csv），默认excel | | keyword | string | 否 | 搜索关键词 | | status | string | 否 | 用户状态筛选 | | startDate | string | 否 | 开始日期 | | endDate | string | 否 | 结束日期 | #### 响应 - 成功时返回文件流 - 失败时返回JSON错误信息 ## 5. 旅行管理接口 ### 5.1 获取旅行列表 #### 接口信息 - **接口路径**：`GET /api/v1/travels` - **接口描述**：分页获取旅行活动列表 - **是否需要认证**：是 - **所需权限**：`travel:read` #### 查询参数 | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | page | integer | 否 | 页码，默认1 | | size | integer | 否 | 每页数量，默认20 | | sort | string | 否 | 排序，默认created_at:desc | | keyword | string | 否 | 搜索关键词（标题、目的地） | | status | integer | 否 | 状态：0-草稿，1-发布，2-进行中，3-已完成，4-已取消 | | travel_type | string | 否 | 旅行类型 | | creator_id | integer | 否 | 创建者ID | | destination | string | 否 | 目的地 | | start_date | string | 否 | 开始日期（YYYY-MM-DD） | | end_date | string | 否 | 结束日期（YYYY-MM-DD） | #### 响应示例 ```json { "code": 200, "message": "获取成功", "data": { "items": [ { "id": 1, "uuid": "travel_123456", "title": "云南大理古城深度游", "description": "探索大理古城的历史文化...", "destination": "云南大理", "start_date": "2024-03-01", "end_date": "2024-03-05", "duration_days": 5, "max_participants": 8, "current_participants": 3, "price_per_person": 2500.00, "includes": "住宿、早餐、门票、导游", "excludes": "午餐、晚餐、个人消费", "itinerary": [ { "day": 1, "title": "抵达大理", "activities": ["机场接机", "入住酒店", "古城漫步"] } ], "requirements": "身体健康，有一定体力", "travel_type": "cultural", "status": "recruiting", "is_featured": false, "view_count": 156, "like_count": 23, "comment_count": 8, "created_by": 1, "images": [ "https://example.com/image1.jpg", "https://example.com/image2.jpg" ], "created_at": "2024-01-15T10:00:00Z", "updated_at": "2024-01-15T10:00:00Z" } ], "pagination": { "page": 1, "size": 20, "total": 50, "pages": 3 } } } ``` ### 5.2 获取旅行详情 #### 接口信息 - **接口路径**：`GET /api/v1/travels/{id}` - **接口描述**：获取旅行活动详细信息 - **是否需要认证**：是 - **所需权限**：`travel:read` #### 响应示例 ```json { "code": 200, "message": "获取成功", "data": { "id": 1, "uuid": "travel_123456", "title": "云南大理古城深度游", "description": "探索大理古城的历史文化，体验白族风情...", "destination": "云南大理", "destination_detail": { "province": "云南省", "city": "大理市", "district": "大理古城", "address": "大理古城南门", "latitude": 25.6916, "longitude": 100.1669 }, "start_date": "2024-03-01", "end_date": "2024-03-05", "duration_days": 5, "max_participants": 8, "current_participants": 3, "price_per_person": 2500.00, "includes": "住宿、早餐、门票、导游", "excludes": "午餐、晚餐、个人消费", "travel_type": "cultural", "itinerary": [ { "day": 1, "title": "抵达大理", "activities": ["接机", "入住客栈", "古城夜游"] }, { "day": 2, "title": "大理古城游览", "activities": ["洱海骑行", "三塔寺参观", "古城购物"] } ], "requirements": "身体健康，有一定体力", "contact_info": { "wechat": "traveler001", "phone": "13800138000" }, "images": [ "https://example.com/image1.jpg", "https://example.com/image2.jpg" ], "tags": ["文化", "古城", "摄影"], "status": 1, "is_featured": 0, "view_count": 156, "like_count": 23, "comment_count": 8, "share_count": 5, "creator": { "id": 1, "username": "traveler001", "nickname": "旅行达人", "avatar_url": "https://example.com/avatar.jpg", "travel_count": 15, "rating": 4.8 }, "participants": [ { "id": 1, "user_id": 2, "username": "user002", "nickname": "小明", "avatar_url": "https://example.com/avatar2.jpg", "status": 1, "applied_at": "2024-01-10T15:30:00Z", "approved_at": "2024-01-11T09:00:00Z" } ], "created_at": "2024-01-15T10:00:00Z", "updated_at": "2024-01-15T10:00:00Z" } } ``` ### 5.3 审核旅行活动 #### 接口信息 - **接口路径**：`POST /api/v1/travels/{id}/review` - **接口描述**：审核旅行活动 - **是否需要认证**：是 - **所需权限**：`travel:review` #### 请求参数 ```json { "action": "approve", "reason": "内容符合规范，通过审核", "is_featured": 1 } ``` | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | action | string | 是 | 审核动作：approve-通过，reject-拒绝 | | reason | string | 是 | 审核理由 | | is_featured | integer | 否 | 是否设为精选：0-否，1-是 | #### 响应示例 ```json { "code": 200, "message": "审核成功", "data": { "id": 1, "status": 1, "is_featured": 1, "reviewed_at": "2024-01-15T10:30:00Z", "review_reason": "内容符合规范，通过审核" } } ``` ### 5.4 获取旅行参与者 #### 接口信息 - **接口路径**：`GET /api/v1/travels/{id}/participants` - **接口描述**：获取旅行活动参与者列表 - **是否需要认证**：是 - **所需权限**：`travel:read` #### 查询参数 | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | status | integer | 否 | 参与状态：0-申请中，1-已通过，2-已拒绝，3-已退出 | #### 响应示例 ```json { "code": 200, "message": "获取成功", "data": { "items": [ { "id": 1, "user_id": 2, "user": { "id": 2, "username": "user002", "nickname": "小明", "avatar_url": "https://example.com/avatar2.jpg", "gender": 1, "age": 28, "location": "北京市" }, "status": 1, "join_reason": "对大理文化很感兴趣，希望能参加这次旅行", "contact_info": { "wechat": "xiaoming123", "phone": "13900139000" }, "emergency_contact": { "name": "李四", "phone": "13800138000", "relationship": "朋友" }, "special_requirements": "素食主义者", "applied_at": "2024-01-10T15:30:00Z", "approved_at": "2024-01-11T09:00:00Z" } ] } } ``` ## 6. 动物认领管理接口 ### 6.1 获取动物列表 #### 接口信息 - **接口路径**：`GET /api/v1/admin/animals` - **接口描述**：获取动物列表，支持分页、搜索和筛选 - **是否需要认证**：是 #### 查询参数 | 参数名 | 类型 | 必填 | 默认值 | 说明 | |--------|------|------|--------|------| | page | integer | 否 | 1 | 页码 | | limit | integer | 否 | 10 | 每页数量 | | keyword | string | 否 | - | 搜索关键词（动物名称） | | type | string | 否 | - | 动物类型 | | status | string | 否 | - | 状态（available/claimed/unavailable） | | farmer_id | integer | 否 | - | 农场主ID | | start_date | string | 否 | - | 开始日期 | | end_date | string | 否 | - | 结束日期 | | sort_by | string | 否 | created_at | 排序字段 | | sort_order | string | 否 | desc | 排序方向（asc/desc） | #### 响应示例 ```json { "success": true, "code": 200, "message": "获取成功", "data": { "animals": [ { "id": 1, "name": "小花", "species": "猫", "breed": "英国短毛猫", "age": 24, "gender": "female", "price": 500.00, "status": "available", "description": "性格温顺，喜欢晒太阳", "images": [ "https://example.com/cat1.jpg", "https://example.com/cat2.jpg" ], "merchant_id": 1, "merchant_name": "爱心动物农场", "claim_count": 0, "created_at": "2024-01-10T10:00:00Z", "updated_at": "2024-01-15T10:00:00Z" } ], "pagination": { "page": 1, "limit": 10, "total": 30, "pages": 3 } } } ``` ### 6.2 获取动物详情 #### 接口信息 - **接口路径**：`GET /api/v1/admin/animals/{animal_id}` - **接口描述**：获取指定动物的详细信息 - **是否需要认证**：是 #### 路径参数 | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | animal_id | integer | 是 | 动物ID | #### 响应示例 ```json { "success": true, "code": 200, "message": "获取成功", "data": { "animal": { "id": 1, "name": "小花", "type": "猫", "breed": "英国短毛猫", "age": 24, "gender": "female", "price": 500.00, "daily_cost": 15.00, "location": "北京市朝阳区", "status": "available", "health_status": "健康", "description": "小花是一只非常温顺的英国短毛猫，喜欢晒太阳和玩毛线球...", "images": [ "https://example.com/cat1.jpg", "https://example.com/cat2.jpg" ], "vaccination_records": [ { "vaccine": "狂犬疫苗", "date": "2024-01-01", "next_date": "2025-01-01" } ], "farmer": { "id": 1, "name": "爱心动物农场", "contact_phone": "13800138000" }, "claim_count": 0, "recent_claims": [ { "id": 1, "user_name": "张三", "status": "pending", "created_at": "2024-01-15T10:00:00Z" } ], "created_at": "2024-01-10T10:00:00Z", "updated_at": "2024-01-15T10:00:00Z" } } } ``` ### 6.3 更新动物状态 #### 接口信息 - **接口路径**：`PUT /api/v1/admin/animals/{animal_id}/status` - **接口描述**：更新动物状态 - **是否需要认证**：是 #### 路径参数 | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | animal_id | integer | 是 | 动物ID | #### 请求参数 ```json { "status": "unavailable", "reason": "动物生病，暂停认领" } ``` | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | status | string | 是 | 动物状态（available/claimed/unavailable） | | reason | string | 否 | 操作原因 | #### 响应示例 ```json { "success": true, "code": 200, "message": "状态更新成功" } ``` ### 6.4 批量更新动物状态 #### 接口信息 - **接口路径**：`PUT /api/v1/admin/animals/batch/status` - **接口描述**：批量更新动物状态 - **是否需要认证**：是 #### 请求参数 ```json { "animal_ids": [1, 2, 3], "status": "unavailable", "reason": "批量下架" } ``` | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | animal_ids | array | 是 | 动物ID数组 | | status | string | 是 | 动物状态（available/claimed/unavailable） | | reason | string | 否 | 操作原因 | #### 响应示例 ```json { "success": true, "code": 200, "message": "批量更新成功", "data": { "successCount": 3, "failedCount": 0 } } ``` ### 6.5 获取动物统计数据 #### 接口信息 - **接口路径**：`GET /api/v1/admin/animals/statistics` - **接口描述**：获取动物统计数据 - **是否需要认证**：是 #### 响应示例 ```json { "success": true, "code": 200, "message": "获取成功", "data": { "totalStats": { "total_animals": 100, "available_animals": 60, "claimed_animals": 30, "total_claims": 150, "avg_price": 450.00 }, "speciesStats": [ { "species": "猫", "count": 50, "percentage": 50.0 }, { "species": "狗", "count": 30, "percentage": 30.0 } ], "statusStats": { "available": 60, "claimed": 30, "unavailable": 10 }, "monthlyTrends": [ { "month": "2024-01", "new_animals": 10, "claims": 15 } ] } } ``` ### 6.6 导出动物数据 #### 接口信息 - **接口路径**：`GET /api/v1/admin/animals/export` - **接口描述**：导出动物数据 - **是否需要认证**：是 #### 查询参数 | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | format | string | 否 | 导出格式（csv/json），默认csv | | keyword | string | 否 | 搜索关键词 | | species | string | 否 | 物种筛选 | | status | string | 否 | 状态筛选 | | merchant_id | integer | 否 | 商家ID筛选 | | start_date | string | 否 | 开始日期 | | end_date | string | 否 | 结束日期 | #### 响应 - 成功时返回文件流 - 失败时返回JSON错误信息 ### 6.7 获取动物认领记录 #### 接口信息 - **接口路径**：`GET /api/v1/admin/animals/{animal_id}/claims` - **接口描述**：获取指定动物的认领记录 - **是否需要认证**：是 #### 路径参数 | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | animal_id | integer | 是 | 动物ID | #### 查询参数 | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | page | integer | 否 | 页码，默认1 | | limit | integer | 否 | 每页数量，默认10 | | status | string | 否 | 认领状态（pending/approved/rejected/cancelled） | #### 响应示例 ```json { "success": true, "code": 200, "message": "获取成功", "data": { "claims": [ { "id": 1, "user_id": 2, "user_name": "张三", "user_phone": "13800138000", "status": "pending", "claim_reason": "喜欢小动物，有养宠经验", "admin_note": "", "created_at": "2024-01-15T10:00:00Z", "updated_at": "2024-01-15T10:00:00Z" } ], "pagination": { "page": 1, "limit": 10, "total": 5, "pages": 1 } } } ``` - **所需权限**：`animal:create` #### 请求参数 ```json { "name": "小白", "type": "狗", "breed": "金毛寻回犬", "gender": 1, "age": 36, "weight": 25.5, "color": "金黄色", "description": "性格活泼，喜欢运动", "personality": "活泼、友善、聪明", "health_status": "健康", "vaccination_records": "已完成基础疫苗接种", "location": "上海市浦东新区", "farmer_id": 2, "price": 800.00, "daily_cost": 15.00, "images": [ "https://example.com/dog1.jpg", "https://example.com/dog2.jpg" ], "status": "available" } ``` #### 响应示例 ```json { "code": 201, "message": "创建成功", "data": { "id": 101, "uuid": "animal_654321", "name": "小白", "species": "狗", "breed": "金毛寻回犬", "status": 1, "created_at": "2024-01-15T10:30:00Z" } } ``` ## 7. 认领管理接口 ### 7.1 获取认领申请列表 #### 接口信息 - **接口路径**：`GET /api/v1/admin/animal-claims` - **接口描述**：获取所有认领申请列表，支持分页、搜索和筛选 - **是否需要认证**：是 #### 查询参数 | 参数名 | 类型 | 必填 | 默认值 | 说明 | |--------|------|------|--------|------| | page | integer | 否 | 1 | 页码 | | limit | integer | 否 | 10 | 每页数量 | | status | string | 否 | - | 申请状态（pending/approved/rejected/cancelled） | | animal_type | string | 否 | - | 动物类型 | | user_id | integer | 否 | - | 用户ID | | start_date | string | 否 | - | 开始日期 | | end_date | string | 否 | - | 结束日期 | #### 响应示例 ```json { "success": true, "code": 200, "message": "获取成功", "data": { "claims": [ { "id": 1, "claim_no": "CLAIM202401150001", "animal_id": 1, "animal_name": "小花", "animal_type": "猫", "animal_image": "https://example.com/cat1.jpg", "user_id": 2, "username": "张三", "user_phone": "13800138000", "claim_reason": "喜欢小动物，有养宠经验", "claim_duration": 12, "total_amount": 2400.00, "contact_info": "微信：zhangsan123", "status": "pending", "created_at": "2024-01-15T10:00:00Z", "updated_at": "2024-01-15T10:00:00Z" } ], "pagination": { "page": 1, "limit": 10, "total": 30, "pages": 3 } } } ``` ### 7.2 获取认领申请详情 #### 接口信息 - **接口路径**：`GET /api/v1/admin/animal-claims/{claim_id}` - **接口描述**：获取指定认领申请的详细信息 - **是否需要认证**：是 #### 路径参数 | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | claim_id | integer | 是 | 认领申请ID | #### 响应示例 ```json { "success": true, "code": 200, "message": "获取成功", "data": { "claim": { "id": 1, "claim_no": "CLAIM202401150001", "animal": { "id": 1, "name": "小花", "species": "猫", "breed": "英国短毛猫", "images": ["https://example.com/cat1.jpg"] }, "user": { "id": 2, "username": "张三", "phone": "13800138000", "avatar_url": "https://example.com/avatar.jpg" }, "claim_reason": "喜欢小动物，有养宠经验，家里环境适合养宠物", "claim_duration": 12, "total_amount": 2400.00, "contact_info": "微信：zhangsan123，QQ：123456789", "status": "pending", "review_remark": "", "reviewed_by": null, "reviewed_at": null, "created_at": "2024-01-15T10:00:00Z", "updated_at": "2024-01-15T10:00:00Z" } } } ``` ### 7.3 审核认领申请 #### 接口信息 - **接口路径**：`PUT /api/v1/admin/animal-claims/{claim_id}/review` - **接口描述**：审核认领申请 - **是否需要认证**：是 #### 路径参数 | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | claim_id | integer | 是 | 认领申请ID | #### 请求参数 ```json { "status": "approved", "review_remark": "申请人条件符合要求，同意认领" } ``` | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | status | string | 是 | 审核状态（approved/rejected） | | review_remark | string | 否 | 审核备注 | #### 响应示例 ```json { "success": true, "code": 200, "message": "认领申请审核通过", "data": { "claim": { "id": 1, "status": "approved", "review_remark": "申请人条件符合要求，同意认领", "reviewed_by": 1, "reviewed_at": "2024-01-16T09:00:00Z" } } } ``` ### 7.4 获取认领统计数据 #### 接口信息 - **接口路径**：`GET /api/v1/admin/animal-claims/statistics` - **接口描述**：获取认领申请统计数据 - **是否需要认证**：是 #### 响应示例 ```json { "success": true, "code": 200, "message": "获取成功", "data": { "totalStats": { "total_claims": 150, "pending_claims": 20, "approved_claims": 100, "rejected_claims": 25, "cancelled_claims": 5, "total_amount": 360000.00, "avg_duration": 10.5 }, "statusStats": { "pending": 20, "approved": 100, "rejected": 25, "cancelled": 5 }, "monthlyTrends": [ { "month": "2024-01", "new_claims": 15, "approved_claims": 12, "total_amount": 28800.00 } ], "animalTypeStats": [ { "animal_type": "猫", "count": 80, "percentage": 53.3 }, { "animal_type": "狗", "count": 50, "percentage": 33.3 } ] } } ``` ### 7.5 导出认领数据 #### 接口信息 - **接口路径**：`GET /api/v1/admin/animal-claims/export` - **接口描述**：导出认领申请数据 - **是否需要认证**：是 #### 查询参数 | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | format | string | 否 | 导出格式（csv/json），默认csv | | status | string | 否 | 状态筛选 | | animal_type | string | 否 | 动物类型筛选 | | user_id | integer | 否 | 用户ID筛选 | | start_date | string | 否 | 开始日期 | | end_date | string | 否 | 结束日期 | #### 响应 - 成功时返回文件流 - 失败时返回JSON错误信息 ## 7. 订单管理 ### 7.1 获取订单列表 **接口路径：** `GET /orders/admin` **接口描述：** 管理员获取所有订单列表，支持分页和筛选 **查询参数：** - `page` (integer, optional): 页码，默认为1 - `limit` (integer, optional): 每页数量，默认为10 - `status` (string, optional): 订单状态筛选 **响应示例：** ```json { "success": true, "data": [ { "id": 1, "order_no": "ORD20231201001", "user_id": 1, "user_name": "张三", "animal_id": 1, "animal_name": "小花", "merchant_id": 1, "merchant_name": "爱心农场", "total_amount": 299.00, "status": "paid", "created_at": "2023-12-01T10:00:00Z", "updated_at": "2023-12-01T10:30:00Z" } ], "pagination": { "current_page": 1, "per_page": 10, "total": 50, "total_pages": 5 } } ``` ### 7.2 获取订单详情 **接口路径：** `GET /orders/{orderId}` **接口描述：** 获取指定订单的详细信息 **路径参数：** - `orderId` (integer, required): 订单ID **响应示例：** ```json { "success": true, "data": { "order": { "id": 1, "order_no": "ORD20231201001", "user_id": 1, "user_name": "张三", "user_phone": "13800138000", "animal_id": 1, "animal_name": "小花", "animal_species": "猫", "merchant_id": 1, "merchant_name": "爱心农场", "total_amount": 299.00, "status": "paid", "payment_method": "wechat", "payment_time": "2023-12-01T10:30:00Z", "created_at": "2023-12-01T10:00:00Z", "updated_at": "2023-12-01T10:30:00Z" } } } ``` ### 7.3 更新订单状态 **接口路径：** `PUT /orders/{orderId}/status` **接口描述：** 管理员更新订单状态 **路径参数：** - `orderId` (integer, required): 订单ID **请求参数：** ```json { "status": "cancelled", "reason": "用户申请取消" } ``` **响应示例：** ```json { "success": true, "message": "订单状态更新成功", "data": { "order_id": 1, "status": "cancelled", "updated_at": "2023-12-01T15:30:00Z" } } ``` ### 7.4 删除订单 **接口路径：** `DELETE /orders/{orderId}` **接口描述：** 管理员删除订单 **路径参数：** - `orderId` (integer, required): 订单ID **响应示例：** ```json { "success": true, "message": "订单删除成功" } ``` ### 7.5 获取订单统计数据 **接口路径：** `GET /admin/system/order-stats` **接口描述：** 获取订单统计数据 **响应示例：** ```json { "success": true, "code": 200, "message": "获取成功", "data": { "total": 1250, "totalAmount": 125000.00, "byStatus": [ { "status": "pending", "count": 45 }, { "status": "paid", "count": 980 }, { "status": "cancelled", "count": 225 } ], "byDate": [ { "date": "2023-12-01", "count": 25, "amount": 2500.00 } ] } } ``` ## 8. 系统管理 ### 8.1 获取管理员列表 **接口路径：** `GET /admin` **接口描述：** 获取管理员列表，支持分页和筛选 **查询参数：** - `page` (integer, optional): 页码，默认为1 - `pageSize` (integer, optional): 每页数量，默认为10 - `username` (string, optional): 用户名搜索 - `role` (string, optional): 角色筛选 - `status` (integer, optional): 状态筛选 **响应示例：** ```json { "success": true, "code": 200, "message": "获取成功", "data": { "admins": [ { "id": 1, "username": "admin", "email": "admin@example.com", "nickname": "系统管理员", "role": "super_admin", "status": 1, "last_login_at": "2023-12-01T09:30:00Z", "created_at": "2023-01-01T10:00:00Z", "updated_at": "2023-12-01T09:30:00Z" } ], "pagination": { "current_page": 1, "per_page": 10, "total": 5, "total_pages": 1 } } } ``` ### 8.2 创建管理员 **接口路径：** `POST /admin` **接口描述：** 创建新管理员 **请求参数：** ```json { "username": "newadmin", "password": "password123", "email": "newadmin@example.com", "nickname": "新管理员", "role": "admin" } ``` **响应示例：** ```json { "success": true, "code": 201, "message": "创建成功", "data": { "admin": { "id": 6, "username": "newadmin", "email": "newadmin@example.com", "nickname": "新管理员", "role": "admin", "status": 1, "created_at": "2023-12-01T10:30:00Z" } } } ``` ### 8.3 更新管理员 **接口路径：** `PUT /admin/{id}` **接口描述：** 更新管理员信息 **路径参数：** - `id` (integer, required): 管理员ID **请求参数：** ```json { "email": "updated@example.com", "nickname": "更新后的昵称", "role": "admin", "status": 1 } ``` **响应示例：** ```json { "success": true, "code": 200, "message": "更新成功", "data": { "admin": { "id": 6, "username": "newadmin", "email": "updated@example.com", "nickname": "更新后的昵称", "role": "admin", "status": 1, "updated_at": "2023-12-01T15:30:00Z" } } } ``` ### 8.4 删除管理员 **接口路径：** `DELETE /admin/{id}` **接口描述：** 删除管理员 **路径参数：** - `id` (integer, required): 管理员ID **响应示例：** ```json { "success": true, "code": 200, "message": "删除成功" } ``` "status": 1, "permissions": [ { "id": 1, "name": "用户管理", "code": "user:*", "type": "menu" } ], "created_at": "2024-01-01T10:00:00Z" } ] } } ``` ### 8.4 获取权限列表 #### 接口信息 - **接口路径**：`GET /api/v1/permissions` - **接口描述**：获取权限树形结构 - **是否需要认证**：是 - **所需权限**：`permission:read` #### 响应示例 ```json { "code": 200, "message": "获取成功", "data": { "items": [ { "id": 1, "name": "系统管理", "code": "system", "type": "menu", "parent_id": null, "sort_order": 1, "children": [ { "id": 2, "name": "用户管理", "code": "user", "type": "menu", "parent_id": 1, "sort_order": 1, "children": [ { "id": 3, "name": "查看用户", "code": "user:read", "type": "button", "parent_id": 2, "sort_order": 1 }, { "id": 4, "name": "创建用户", "code": "user:create", "type": "button", "parent_id": 2, "sort_order": 2 } ] } ] } ] } } ``` ## 9. 统计分析 ### 9.1 获取系统概览统计 **接口路径：** `GET /admin/statistics/overview` **接口描述：** 获取系统概览统计数据 **响应示例：** ```json { "success": true, "code": 200, "message": "获取成功", "data": { "users": { "total_users": 1250, "active_users": 890, "new_users_today": 15, "new_users_week": 89 }, "travels": { "total_travels": 156, "published_travels": 89, "new_travels_today": 3 }, "animals": { "total_animals": 234, "available_animals": 156, "claimed_animals": 78 }, "orders": { "total_orders": 445, "completed_orders": 389, "pending_orders": 56, "total_revenue": 125600.00 } } } ``` ### 9.2 获取用户增长趋势 **接口路径：** `GET /admin/statistics/user-growth` **接口描述：** 获取用户增长趋势数据 **查询参数：** - `period` (string, optional): 统计周期，可选值：7d, 30d, 90d, 365d，默认30d **响应示例：** ```json { "success": true, "code": 200, "message": "获取成功", "data": { "period": "30d", "trendData": [ { "date": "2023-11-01", "new_users": 12, "total_users": 1180 }, { "date": "2023-11-02", "new_users": 15, "total_users": 1195 } ] } } ``` ### 9.3 获取业务统计 **接口路径：** `GET /admin/statistics/business` **接口描述：** 获取业务相关统计数据 **查询参数：** - `period` (string, optional): 统计周期，可选值：7d, 30d, 90d，默认30d **响应示例：** ```json { "success": true, "code": 200, "message": "获取成功", "data": { "period": "30d", "travelStats": [ { "date": "2023-11-01", "new_travels": 5, "published_travels": 3, "total_views": 245 } ], "claimStats": [ { "date": "2023-11-01", "new_claims": 8, "approved_claims": 6, "rejected_claims": 1 } ], "orderStats": [ { "date": "2023-11-01", "new_orders": 12, "completed_orders": 10, "daily_revenue": 2500.00 } ] } } ``` ### 9.4 获取地域分布统计 **接口路径：** `GET /admin/statistics/geographic` **接口描述：** 获取地域分布统计数据 **响应示例：** ```json { "success": true, "code": 200, "message": "获取成功", "data": { "userDistribution": [ { "province": "北京市", "city": "北京市", "user_count": 156 }, { "province": "上海市", "city": "上海市", "user_count": 134 } ], "provinceStats": [ { "province": "北京市", "user_count": 156, "farmer_count": 23, "merchant_count": 12 } ], "destinationStats": [ { "destination": "云南大理", "travel_count": 45 }, { "destination": "西藏拉萨", "travel_count": 38 } ] } } ``` ### 9.5 获取用户行为分析 **接口路径：** `GET /admin/statistics/user-behavior` **接口描述：** 获取用户行为分析数据 **响应示例：** ```json { "success": true, "code": 200, "message": "获取成功", "data": { "activityStats": [ { "activity_level": "高活跃", "user_count": 234 }, { "activity_level": "中活跃", "user_count": 456 }, { "activity_level": "低活跃", "user_count": 560 } ], "levelDistribution": [ { "level": "新手", "user_count": 456, "avg_points": 120.5, "avg_travel_count": 1.2, "avg_claim_count": 0.8 } ], "behaviorStats": [ { "behavior_type": "浏览旅行", "user_count": 890 }, { "behavior_type": "发布旅行", "user_count": 234 }, { "behavior_type": "认领动物", "user_count": 156 } ] } } ``` ### 9.6 获取收入统计 **接口路径：** `GET /admin/statistics/revenue` **接口描述：** 获取收入统计数据 **查询参数：** - `period` (string, optional): 统计周期，可选值：7d, 30d, 90d, 365d，默认30d **响应示例：** ```json { "success": true, "code": 200, "message": "获取成功", "data": { "period": "30d", "revenueStats": [ { "date": "2023-11-01", "total_revenue": 2500.00, "order_count": 12, "avg_order_value": 208.33 } ], "categoryStats": [ { "category": "旅行费用", "total_revenue": 45600.00, "order_count": 156, "avg_order_value": 292.31 } ], "paymentMethodStats": [ { "payment_method": "微信支付", "order_count": 234, "total_amount": 56780.00 }, { "payment_method": "支付宝", "order_count": 189, "total_amount": 45230.00 } ] } } ``` ### 9.7 导出统计报告 **接口路径：** `GET /admin/statistics/export` **接口描述：** 导出统计报告 **查询参数：** - `reportType` (string, optional): 报告类型，可选值：overview, users, revenue，默认overview - `period` (string, optional): 统计周期，可选值：7d, 30d, 90d，默认30d - `format` (string, optional): 导出格式，可选值：csv, json，默认csv **响应示例：** ```json { "success": true, "code": 200, "message": "导出成功", "data": { "downloadUrl": "https://example.com/exports/report_20231201.csv", "filename": "统计报告_20231201.csv", "fileSize": 2048 } } ``` {"gender": "男", "count": 580, "percentage": 46.4}, {"gender": "女", "count": 620, "percentage": 49.6}, {"gender": "未知", "count": 50, "percentage": 4.0} ], "location_distribution": [ {"province": "北京", "count": 180, "percentage": 14.4}, {"province": "上海", "count": 165, "percentage": 13.2}, {"province": "广东", "count": 220, "percentage": 17.6}, {"province": "浙江", "count": 145, "percentage": 11.6}, {"province": "其他", "count": 540, "percentage": 43.2} ] } } } ``` ## 10. 文件管理接口 ### 10.1 上传文件 #### 接口信息 - **接口路径**：`POST /api/v1/files/upload` - **接口描述**：上传文件（图片、视频、文档等） - **是否需要认证**：是 - **所需权限**：`file:upload` #### 请求参数 - **Content-Type**：`multipart/form-data` | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | file | file | 是 | 上传的文件 | | type | string | 否 | 文件类型：image,video,document，默认auto | | category | string | 否 | 文件分类：avatar,travel,animal,other | #### 响应示例 ```json { "code": 200, "message": "上传成功", "data": { "id": 1, "filename": "image_20240115_103000.jpg", "original_name": "beautiful_scenery.jpg", "file_path": "/uploads/images/2024/01/15/image_20240115_103000.jpg", "file_url": "https://cdn.example.com/uploads/images/2024/01/15/image_20240115_103000.jpg", "file_size": 1024000, "mime_type": "image/jpeg", "file_type": "image", "category": "travel", "uploaded_at": "2024-01-15T10:30:00Z" } } ``` ### 10.2 批量上传文件 #### 接口信息 - **接口路径**：`POST /api/v1/files/batch-upload` - **接口描述**：批量上传多个文件 - **是否需要认证**：是 - **所需权限**：`file:upload` #### 请求参数 - **Content-Type**：`multipart/form-data` | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | files[] | file[] | 是 | 上传的文件数组 | | category | string | 否 | 文件分类 | #### 响应示例 ```json { "code": 200, "message": "批量上传完成", "data": { "success_count": 3, "failed_count": 1, "success_files": [ { "id": 1, "filename": "image1.jpg", "file_url": "https://cdn.example.com/uploads/images/image1.jpg" }, { "id": 2, "filename": "image2.jpg", "file_url": "https://cdn.example.com/uploads/images/image2.jpg" } ], "failed_files": [ { "filename": "large_file.jpg", "error": "文件大小超过限制" } ] } } ``` ### 10.3 获取文件列表 #### 接口信息 - **接口路径**：`GET /api/v1/files` - **接口描述**：分页获取文件列表 - **是否需要认证**：是 - **所需权限**：`file:read` #### 查询参数 | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | page | integer | 否 | 页码，默认1 | | size | integer | 否 | 每页数量，默认20 | | file_type | string | 否 | 文件类型：image,video,document | | category | string | 否 | 文件分类 | | keyword | string | 否 | 搜索关键词（文件名） | #### 响应示例 ```json { "code": 200, "message": "获取成功", "data": { "items": [ { "id": 1, "filename": "image_20240115_103000.jpg", "original_name": "beautiful_scenery.jpg", "file_url": "https://cdn.example.com/uploads/images/2024/01/15/image_20240115_103000.jpg", "file_size": 1024000, "mime_type": "image/jpeg", "file_type": "image", "category": "travel", "uploaded_at": "2024-01-15T10:30:00Z" } ], "pagination": { "page": 1, "size": 20, "total": 100, "pages": 5 } } } ``` ## 11. 消息通知接口 ### 11.1 获取通知列表 #### 接口信息 - **接口路径**：`GET /api/v1/notifications` - **接口描述**：分页获取系统通知列表 - **是否需要认证**：是 - **所需权限**：`notification:read` #### 查询参数 | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | page | integer | 否 | 页码，默认1 | | size | integer | 否 | 每页数量，默认20 | | type | string | 否 | 通知类型：system,order,travel,adoption | | status | integer | 否 | 状态：0-未读，1-已读 | | user_id | integer | 否 | 用户ID | #### 响应示例 ```json { "code": 200, "message": "获取成功", "data": { "items": [ { "id": 1, "type": "order", "title": "订单支付成功", "content": "您的订单 ORD202401150001 支付成功，感谢您的支持！", "user_id": 2, "related_type": "order", "related_id": 1, "status": 0, "created_at": "2024-01-15T16:30:00Z" } ], "pagination": { "page": 1, "size": 20, "total": 50, "pages": 3 } } } ``` ### 11.2 发送通知 #### 接口信息 - **接口路径**：`POST /api/v1/notifications` - **接口描述**：发送系统通知 - **是否需要认证**：是 - **所需权限**：`notification:send` #### 请求参数 ```json { "type": "system", "title": "系统维护通知", "content": "系统将于今晚22:00-24:00进行维护，期间可能影响正常使用，敬请谅解。", "target_type": "all", "user_ids": [], "send_immediately": true } ``` | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | type | string | 是 | 通知类型：system,order,travel,adoption | | title | string | 是 | 通知标题 | | content | string | 是 | 通知内容 | | target_type | string | 是 | 目标类型：all-所有用户，specific-指定用户 | | user_ids | array | 否 | 用户ID列表（target_type为specific时必填） | | send_immediately | boolean | 否 | 是否立即发送，默认true | #### 响应示例 ```json { "code": 200, "message": "通知发送成功", "data": { "notification_id": 101, "target_count": 1250, "sent_count": 1250, "failed_count": 0 } } ``` ## 12. 系统配置接口 ### 12.1 获取系统配置 #### 接口信息 - **接口路径**：`GET /api/v1/system/config` - **接口描述**：获取系统配置信息 - **是否需要认证**：是 - **所需权限**：`system:config:read` #### 响应示例 ```json { "code": 200, "message": "获取成功", "data": { "site": { "name": "结伴客", "description": "专业的旅行结伴和动物认领平台", "logo_url": "https://example.com/logo.png", "favicon_url": "https://example.com/favicon.ico", "keywords": "旅行,结伴,动物认领,宠物", "icp_number": "京ICP备12345678号" }, "upload": { "max_file_size": 10485760, "allowed_image_types": ["jpg", "jpeg", "png", "gif", "webp"], "allowed_video_types": ["mp4", "avi", "mov"], "allowed_document_types": ["pdf", "doc", "docx", "xls", "xlsx"] }, "payment": { "wechat_enabled": true, "alipay_enabled": true, "min_amount": 0.01, "max_amount": 50000.00 }, "notification": { "email_enabled": true, "sms_enabled": true, "push_enabled": true } } } ``` ### 12.2 更新系统配置 #### 接口信息 - **接口路径**：`PUT /api/v1/system/config` - **接口描述**：更新系统配置 - **是否需要认证**：是 - **所需权限**：`system:config:update` #### 请求参数 ```json { "site": { "name": "结伴客", "description": "专业的旅行结伴和动物认领平台" }, "upload": { "max_file_size": 20971520 } } ``` #### 响应示例 ```json { "code": 200, "message": "配置更新成功", "data": { "updated_keys": ["site.name", "site.description", "upload.max_file_size"], "updated_at": "2024-01-15T10:30:00Z" } } ``` ## 13. 错误码说明 ### 13.1 通用错误码 | 错误码 | HTTP状态码 | 说明 | |--------|------------|------| | 200 | 200 | 请求成功 | | 400 | 400 | 请求参数错误 | | 401 | 401 | 未授权，需要登录 | | 403 | 403 | 权限不足 | | 404 | 404 | 资源不存在 | | 409 | 409 | 资源冲突 | | 422 | 422 | 业务逻辑错误 | | 429 | 429 | 请求频率限制 | | 500 | 500 | 服务器内部错误 | ### 13.2 业务错误码 | 错误码 | 说明 | |--------|------| | 10001 | 用户名已存在 | | 10002 | 邮箱已存在 | | 10003 | 手机号已存在 | | 10004 | 用户不存在 | | 10005 | 密码错误 | | 10006 | 验证码错误 | | 10007 | 验证码已过期 | | 20001 | 旅行活动不存在 | | 20002 | 旅行活动已满员 | | 20003 | 旅行活动已结束 | | 20004 | 已参加该旅行活动 | | 30001 | 动物不存在 | | 30002 | 动物不可认领 | | 30003 | 动物已被认领 | | 30004 | 已认领该动物 | | 40001 | 订单不存在 | | 40002 | 订单状态错误 | | 40003 | 支付失败 | | 40004 | 退款失败 | | 50001 | 文件上传失败 | | 50002 | 文件类型不支持 | | 50003 | 文件大小超限 | ## 14. 接口测试 ### 14.1 测试环境 - **测试地址**：`https://api-test.jiebanke.com` - **测试账号**： - 用户名：`test_admin` - 密码：`test123456` ### 14.2 Postman集合 提供完整的Postman测试集合，包含所有接口的测试用例和环境变量配置。 ### 14.3 接口文档 - **在线文档**：`https://docs.jiebanke.com/api` - **Swagger UI**：`https://api-test.jiebanke.com/docs` ## 15. 总结 本文档详细描述了结伴客管理后台系统的所有API接口规范，包括： 1. **完整的接口定义**：涵盖认证、用户管理、旅行管理、动物认领、订单管理等所有核心功能 2. **统一的规范标准**：采用RESTful风格，统一的请求响应格式和错误处理机制 3. **详细的参数说明**：每个接口都包含完整的请求参数、响应示例和错误码说明 4. **安全认证机制**：基于JWT的认证体系和细粒度的权限控制 5. **扩展性设计**：支持API版本管理和功能扩展 该接口设计文档为前端开发、测试和运维提供了完整的技术规范，确保系统各模块间的高效协作和数据一致性。