# 管理后台接口设计文档 ## 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/auth/login` - **接口描述**：管理员登录获取访问令牌 - **是否需要认证**：否 #### 请求参数 ```json { "username": "admin", "password": "password123", "captcha": "ABCD", "captcha_key": "captcha_key_123" } ``` | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | username | string | 是 | 用户名或邮箱 | | password | string | 是 | 密码 | | captcha | string | 是 | 验证码 | | captcha_key | string | 是 | 验证码key | #### 响应示例 ```json { "code": 200, "message": "登录成功", "data": { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "expires_in": 7200, "token_type": "Bearer", "admin_info": { "id": 1, "username": "admin", "email": "admin@example.com", "real_name": "系统管理员", "avatar_url": "https://example.com/avatar.jpg", "roles": ["super_admin"], "permissions": ["*"] } } } ``` ### 3.2 刷新令牌 #### 接口信息 - **接口路径**：`POST /api/v1/auth/refresh` - **接口描述**：使用刷新令牌获取新的访问令牌 - **是否需要认证**：否 #### 请求参数 ```json { "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } ``` #### 响应示例 ```json { "code": 200, "message": "令牌刷新成功", "data": { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "expires_in": 7200, "token_type": "Bearer" } } ``` ### 3.3 退出登录 #### 接口信息 - **接口路径**：`POST /api/v1/auth/logout` - **接口描述**：管理员退出登录 - **是否需要认证**：是 #### 响应示例 ```json { "code": 200, "message": "退出成功" } ``` ### 3.4 获取验证码 #### 接口信息 - **接口路径**：`GET /api/v1/auth/captcha` - **接口描述**：获取登录验证码 - **是否需要认证**：否 #### 响应示例 ```json { "code": 200, "message": "获取成功", "data": { "captcha_key": "captcha_key_123", "captcha_image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...", "expires_in": 300 } } ``` ## 4. 用户管理接口 ### 4.1 获取用户列表 #### 接口信息 - **接口路径**：`GET /api/v1/users` - **接口描述**：分页获取用户列表 - **是否需要认证**：是 - **所需权限**：`user:read` #### 查询参数 | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | page | integer | 否 | 页码，默认1 | | size | integer | 否 | 每页数量，默认20 | | sort | string | 否 | 排序，默认created_at:desc | | keyword | string | 否 | 搜索关键词（用户名、邮箱、手机号） | | status | integer | 否 | 用户状态：0-禁用，1-正常，2-待验证 | | user_type | integer | 否 | 用户类型：1-普通用户，2-商家用户 | | created_start | string | 否 | 创建时间开始（YYYY-MM-DD） | | created_end | string | 否 | 创建时间结束（YYYY-MM-DD） | #### 响应示例 ```json { "code": 200, "message": "获取成功", "data": { "items": [ { "id": 1, "uuid": "user_123456", "username": "testuser", "email": "test@example.com", "phone": "13800138000", "nickname": "测试用户", "avatar_url": "https://example.com/avatar.jpg", "gender": 1, "birthday": "1990-01-01", "location": "北京市", "status": 1, "user_type": 1, "email_verified_at": "2024-01-01T10:00:00Z", "phone_verified_at": "2024-01-01T10:00:00Z", "last_login_at": "2024-01-15T09:30:00Z", "created_at": "2024-01-01T10:00:00Z", "updated_at": "2024-01-15T09:30:00Z" } ], "pagination": { "page": 1, "size": 20, "total": 100, "pages": 5 } } } ``` ### 4.2 获取用户详情 #### 接口信息 - **接口路径**：`GET /api/v1/users/{id}` - **接口描述**：获取指定用户的详细信息 - **是否需要认证**：是 - **所需权限**：`user:read` #### 路径参数 | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | id | integer | 是 | 用户ID | #### 响应示例 ```json { "code": 200, "message": "获取成功", "data": { "id": 1, "uuid": "user_123456", "username": "testuser", "email": "test@example.com", "phone": "13800138000", "nickname": "测试用户", "avatar_url": "https://example.com/avatar.jpg", "gender": 1, "birthday": "1990-01-01", "location": "北京市", "bio": "这是个人简介", "status": 1, "user_type": 1, "email_verified_at": "2024-01-01T10:00:00Z", "phone_verified_at": "2024-01-01T10:00:00Z", "last_login_at": "2024-01-15T09:30:00Z", "created_at": "2024-01-01T10:00:00Z", "updated_at": "2024-01-15T09:30:00Z", "profile": { "real_name": "张三", "id_card": "110101199001011234", "id_card_verified": 1, "occupation": "软件工程师", "education": "本科", "income_level": 3, "travel_experience": "去过很多地方...", "interests": ["旅行", "摄影", "美食"], "languages": ["中文", "英语"], "emergency_contact": { "name": "李四", "phone": "13900139000", "relationship": "朋友" } }, "statistics": { "travel_count": 5, "adoption_count": 2, "order_count": 10, "total_spent": 5000.00 } } } ``` ### 4.3 创建用户 #### 接口信息 - **接口路径**：`POST /api/v1/users` - **接口描述**：创建新用户 - **是否需要认证**：是 - **所需权限**：`user:create` #### 请求参数 ```json { "username": "newuser", "email": "newuser@example.com", "phone": "13800138001", "password": "password123", "nickname": "新用户", "gender": 1, "birthday": "1995-05-15", "location": "上海市", "user_type": 1, "status": 1 } ``` | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | username | string | 是 | 用户名，3-20字符 | | email | string | 是 | 邮箱地址 | | phone | string | 否 | 手机号码 | | password | string | 是 | 密码，6-20字符 | | nickname | string | 否 | 昵称 | | gender | integer | 否 | 性别：0-未知，1-男，2-女 | | birthday | string | 否 | 生日，格式：YYYY-MM-DD | | location | string | 否 | 所在地 | | user_type | integer | 否 | 用户类型，默认1 | | status | integer | 否 | 状态，默认1 | #### 响应示例 ```json { "code": 201, "message": "创建成功", "data": { "id": 101, "uuid": "user_654321", "username": "newuser", "email": "newuser@example.com", "phone": "13800138001", "nickname": "新用户", "status": 1, "user_type": 1, "created_at": "2024-01-15T10:30:00Z" } } ``` ### 4.4 更新用户信息 #### 接口信息 - **接口路径**：`PUT /api/v1/users/{id}` - **接口描述**：更新用户信息 - **是否需要认证**：是 - **所需权限**：`user:update` #### 请求参数 ```json { "nickname": "更新的昵称", "gender": 2, "birthday": "1995-05-15", "location": "深圳市", "bio": "更新的个人简介", "status": 1 } ``` #### 响应示例 ```json { "code": 200, "message": "更新成功", "data": { "id": 1, "uuid": "user_123456", "username": "testuser", "nickname": "更新的昵称", "gender": 2, "location": "深圳市", "updated_at": "2024-01-15T10:35:00Z" } } ``` ### 4.5 删除用户 #### 接口信息 - **接口路径**：`DELETE /api/v1/users/{id}` - **接口描述**：删除用户（软删除） - **是否需要认证**：是 - **所需权限**：`user:delete` #### 响应示例 ```json { "code": 200, "message": "删除成功" } ``` ### 4.6 批量操作用户 #### 接口信息 - **接口路径**：`POST /api/v1/users/batch` - **接口描述**：批量操作用户（启用、禁用、删除） - **是否需要认证**：是 - **所需权限**：`user:batch` #### 请求参数 ```json { "action": "disable", "user_ids": [1, 2, 3, 4, 5], "reason": "违规操作" } ``` | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | action | string | 是 | 操作类型：enable-启用，disable-禁用，delete-删除 | | user_ids | array | 是 | 用户ID列表 | | reason | string | 否 | 操作原因 | #### 响应示例 ```json { "code": 200, "message": "批量操作成功", "data": { "success_count": 4, "failed_count": 1, "failed_items": [ { "user_id": 3, "reason": "用户不存在" } ] } } ``` ## 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, "budget_min": 2000.00, "budget_max": 3000.00, "travel_type": "cultural", "status": 1, "is_featured": 0, "view_count": 156, "like_count": 23, "comment_count": 8, "creator": { "id": 1, "username": "traveler001", "nickname": "旅行达人", "avatar_url": "https://example.com/avatar.jpg" }, "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, "min_age": 18, "max_age": 60, "gender_limit": 0, "budget_min": 2000.00, "budget_max": 3000.00, "travel_type": "cultural", "transportation": "高铁+包车", "accommodation": "客栈", "itinerary": [ { "day": 1, "title": "抵达大理", "activities": ["接机", "入住客栈", "古城夜游"], "meals": ["晚餐"] }, { "day": 2, "title": "大理古城游览", "activities": ["洱海骑行", "三塔寺参观", "古城购物"], "meals": ["早餐", "午餐", "晚餐"] } ], "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/animals` - **接口描述**：分页获取动物列表 - **是否需要认证**：是 - **所需权限**：`animal:read` #### 查询参数 | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | page | integer | 否 | 页码，默认1 | | size | integer | 否 | 每页数量，默认20 | | sort | string | 否 | 排序，默认created_at:desc | | keyword | string | 否 | 搜索关键词（动物名称） | | species | string | 否 | 物种 | | breed | string | 否 | 品种 | | status | integer | 否 | 状态：0-不可认领，1-可认领，2-已认领，3-暂停认领 | | location | string | 否 | 所在地 | | farm_id | integer | 否 | 农场ID | #### 响应示例 ```json { "code": 200, "message": "获取成功", "data": { "items": [ { "id": 1, "uuid": "animal_123456", "name": "小花", "species": "猫", "breed": "英国短毛猫", "gender": 2, "age": 24, "weight": 4.5, "color": "银渐层", "description": "性格温顺，喜欢晒太阳", "health_status": "健康", "location": "北京市朝阳区", "adoption_fee": 500.00, "monthly_cost": 200.00, "status": 1, "is_featured": 1, "view_count": 89, "like_count": 15, "adoption_count": 0, "images": [ "https://example.com/cat1.jpg", "https://example.com/cat2.jpg" ], "farm": { "id": 1, "name": "爱心动物农场", "location": "北京市朝阳区" }, "created_at": "2024-01-10T10:00:00Z", "updated_at": "2024-01-15T10:00:00Z" } ], "pagination": { "page": 1, "size": 20, "total": 30, "pages": 2 } } } ``` ### 6.2 获取动物详情 #### 接口信息 - **接口路径**：`GET /api/v1/animals/{id}` - **接口描述**：获取动物详细信息 - **是否需要认证**：是 - **所需权限**：`animal:read` #### 响应示例 ```json { "code": 200, "message": "获取成功", "data": { "id": 1, "uuid": "animal_123456", "name": "小花", "species": "猫", "breed": "英国短毛猫", "gender": 2, "age": 24, "weight": 4.5, "color": "银渐层", "description": "小花是一只非常温顺的英国短毛猫，喜欢晒太阳和玩毛线球...", "personality": "温顺、亲人、活泼", "health_status": "健康", "vaccination_status": { "rabies": { "vaccinated": true, "date": "2023-12-01", "next_due": "2024-12-01" }, "feline_distemper": { "vaccinated": true, "date": "2023-12-01", "next_due": "2024-12-01" } }, "medical_history": "2023年11月进行了绝育手术，恢复良好", "location": "北京市朝阳区", "adoption_fee": 500.00, "monthly_cost": 200.00, "status": 1, "is_featured": 1, "view_count": 89, "like_count": 15, "adoption_count": 0, "images": [ "https://example.com/cat1.jpg", "https://example.com/cat2.jpg" ], "videos": [ "https://example.com/cat_video1.mp4" ], "farm": { "id": 1, "name": "爱心动物农场", "location": "北京市朝阳区", "contact_phone": "13800138000", "description": "专业的动物救助机构" }, "caretaker": { "id": 1, "name": "张三", "phone": "13900139000", "experience": "5年动物护理经验" }, "adoptions": [ { "id": 1, "user_id": 2, "user": { "nickname": "爱心用户", "avatar_url": "https://example.com/avatar.jpg" }, "adoption_type": 1, "start_date": "2024-02-01", "status": 1, "created_at": "2024-01-15T10:00:00Z" } ], "created_at": "2024-01-10T10:00:00Z", "updated_at": "2024-01-15T10:00:00Z" } } ``` ### 6.3 创建动物信息 #### 接口信息 - **接口路径**：`POST /api/v1/animals` - **接口描述**：创建新的动物信息 - **是否需要认证**：是 - **所需权限**：`animal:create` #### 请求参数 ```json { "name": "小白", "species": "狗", "breed": "金毛寻回犬", "gender": 1, "age": 36, "weight": 25.5, "color": "金黄色", "description": "性格活泼，喜欢运动", "personality": "活泼、友善、聪明", "health_status": "健康", "location": "上海市浦东新区", "farm_id": 2, "caretaker_id": 3, "adoption_fee": 800.00, "monthly_cost": 300.00, "images": [ "https://example.com/dog1.jpg", "https://example.com/dog2.jpg" ], "status": 1 } ``` #### 响应示例 ```json { "code": 201, "message": "创建成功", "data": { "id": 101, "uuid": "animal_654321", "name": "小白", "species": "狗", "breed": "金毛寻回犬", "status": 1, "created_at": "2024-01-15T10:30:00Z" } } ``` ### 6.4 获取认领申请列表 #### 接口信息 - **接口路径**：`GET /api/v1/adoptions` - **接口描述**：分页获取动物认领申请列表 - **是否需要认证**：是 - **所需权限**：`adoption:read` #### 查询参数 | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | page | integer | 否 | 页码，默认1 | | size | integer | 否 | 每页数量，默认20 | | sort | string | 否 | 排序，默认created_at:desc | | status | integer | 否 | 状态：0-申请中，1-已通过，2-已拒绝，3-进行中，4-已完成，5-已取消 | | animal_id | integer | 否 | 动物ID | | user_id | integer | 否 | 用户ID | | adoption_type | integer | 否 | 认领类型：1-长期认领，2-短期认领，3-共同认领 | #### 响应示例 ```json { "code": 200, "message": "获取成功", "data": { "items": [ { "id": 1, "uuid": "adoption_123456", "animal": { "id": 1, "name": "小花", "species": "猫", "breed": "英国短毛猫", "images": ["https://example.com/cat1.jpg"] }, "user": { "id": 2, "username": "user002", "nickname": "爱心用户", "avatar_url": "https://example.com/avatar.jpg" }, "adoption_type": 1, "duration_months": 12, "start_date": "2024-02-01", "end_date": "2025-02-01", "monthly_fee": 200.00, "total_fee": 2400.00, "payment_status": 1, "status": 1, "special_requirements": "希望能定期收到小花的照片和视频", "approved_at": "2024-01-16T09:00:00Z", "created_at": "2024-01-15T15:30:00Z" } ], "pagination": { "page": 1, "size": 20, "total": 15, "pages": 1 } } } ``` ### 6.5 审核认领申请 #### 接口信息 - **接口路径**：`POST /api/v1/adoptions/{id}/review` - **接口描述**：审核动物认领申请 - **是否需要认证**：是 - **所需权限**：`adoption:review` #### 请求参数 ```json { "action": "approve", "reason": "申请人条件符合要求，同意认领" } ``` | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | action | string | 是 | 审核动作：approve-通过，reject-拒绝 | | reason | string | 是 | 审核理由 | #### 响应示例 ```json { "code": 200, "message": "审核成功", "data": { "id": 1, "status": 1, "approved_at": "2024-01-16T09:00:00Z", "review_reason": "申请人条件符合要求，同意认领" } } ``` ## 7. 订单管理接口 ### 7.1 获取订单列表 #### 接口信息 - **接口路径**：`GET /api/v1/orders` - **接口描述**：分页获取订单列表 - **是否需要认证**：是 - **所需权限**：`order:read` #### 查询参数 | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | page | integer | 否 | 页码，默认1 | | size | integer | 否 | 每页数量，默认20 | | sort | string | 否 | 排序，默认created_at:desc | | order_no | string | 否 | 订单号 | | user_id | integer | 否 | 用户ID | | order_type | string | 否 | 订单类型：travel,adoption,service | | status | integer | 否 | 订单状态：0-待支付，1-已支付，2-已完成，3-已取消，4-已退款 | | payment_status | integer | 否 | 支付状态：0-未支付，1-支付中，2-支付成功，3-支付失败 | | created_start | string | 否 | 创建时间开始（YYYY-MM-DD） | | created_end | string | 否 | 创建时间结束（YYYY-MM-DD） | | amount_min | number | 否 | 金额下限 | | amount_max | number | 否 | 金额上限 | #### 响应示例 ```json { "code": 200, "message": "获取成功", "data": { "items": [ { "id": 1, "order_no": "ORD202401150001", "user": { "id": 2, "username": "user002", "nickname": "小明", "avatar_url": "https://example.com/avatar.jpg" }, "order_type": "adoption", "related_id": 1, "title": "认领小花（英国短毛猫）", "description": "12个月长期认领", "amount": 2400.00, "discount_amount": 0.00, "final_amount": 2400.00, "currency": "CNY", "status": 2, "payment_method": "wechat", "payment_status": 2, "paid_at": "2024-01-15T16:30:00Z", "completed_at": "2024-01-15T16:35:00Z", "created_at": "2024-01-15T16:00:00Z", "updated_at": "2024-01-15T16:35:00Z" } ], "pagination": { "page": 1, "size": 20, "total": 100, "pages": 5 } } } ``` ### 7.2 获取订单详情 #### 接口信息 - **接口路径**：`GET /api/v1/orders/{id}` - **接口描述**：获取订单详细信息 - **是否需要认证**：是 - **所需权限**：`order:read` #### 响应示例 ```json { "code": 200, "message": "获取成功", "data": { "id": 1, "order_no": "ORD202401150001", "user": { "id": 2, "username": "user002", "nickname": "小明", "avatar_url": "https://example.com/avatar.jpg", "phone": "13900139000" }, "order_type": "adoption", "related_id": 1, "related_info": { "animal": { "id": 1, "name": "小花", "species": "猫", "breed": "英国短毛猫", "images": ["https://example.com/cat1.jpg"] }, "adoption": { "id": 1, "adoption_type": 1, "duration_months": 12, "start_date": "2024-02-01", "end_date": "2025-02-01" } }, "title": "认领小花（英国短毛猫）", "description": "12个月长期认领，包含日常照料、医疗保健等服务", "amount": 2400.00, "discount_amount": 0.00, "final_amount": 2400.00, "currency": "CNY", "status": 2, "payment_method": "wechat", "payment_status": 2, "paid_at": "2024-01-15T16:30:00Z", "completed_at": "2024-01-15T16:35:00Z", "metadata": { "promotion_code": null, "source": "miniprogram" }, "payments": [ { "id": 1, "payment_no": "PAY202401150001", "payment_method": "wechat", "amount": 2400.00, "status": 2, "third_party_no": "wx_transaction_123456", "paid_at": "2024-01-15T16:30:00Z" } ], "created_at": "2024-01-15T16:00:00Z", "updated_at": "2024-01-15T16:35:00Z" } } ``` ### 7.3 订单退款 #### 接口信息 - **接口路径**：`POST /api/v1/orders/{id}/refund` - **接口描述**：处理订单退款 - **是否需要认证**：是 - **所需权限**：`order:refund` #### 请求参数 ```json { "refund_amount": 2400.00, "refund_reason": "用户申请退款", "refund_type": "full" } ``` | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | refund_amount | number | 是 | 退款金额 | | refund_reason | string | 是 | 退款原因 | | refund_type | string | 是 | 退款类型：full-全额退款，partial-部分退款 | #### 响应示例 ```json { "code": 200, "message": "退款处理成功", "data": { "order_id": 1, "refund_amount": 2400.00, "refund_status": "processing", "refund_no": "REF202401150001", "estimated_arrival": "2024-01-18T16:30:00Z" } } ``` ## 8. 系统管理接口 ### 8.1 获取管理员列表 #### 接口信息 - **接口路径**：`GET /api/v1/admins` - **接口描述**：分页获取管理员列表 - **是否需要认证**：是 - **所需权限**：`admin:read` #### 查询参数 | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | page | integer | 否 | 页码，默认1 | | size | integer | 否 | 每页数量，默认20 | | sort | string | 否 | 排序，默认created_at:desc | | keyword | string | 否 | 搜索关键词（用户名、邮箱、真实姓名） | | status | integer | 否 | 状态：0-禁用，1-正常 | #### 响应示例 ```json { "code": 200, "message": "获取成功", "data": { "items": [ { "id": 1, "username": "admin", "email": "admin@example.com", "real_name": "系统管理员", "avatar_url": "https://example.com/admin_avatar.jpg", "phone": "13800138000", "status": 1, "roles": [ { "id": 1, "name": "超级管理员", "code": "super_admin" } ], "last_login_at": "2024-01-15T09:30:00Z", "created_at": "2024-01-01T10:00:00Z", "updated_at": "2024-01-15T09:30:00Z" } ], "pagination": { "page": 1, "size": 20, "total": 5, "pages": 1 } } } ``` ### 8.2 创建管理员 #### 接口信息 - **接口路径**：`POST /api/v1/admins` - **接口描述**：创建新管理员 - **是否需要认证**：是 - **所需权限**：`admin:create` #### 请求参数 ```json { "username": "newadmin", "email": "newadmin@example.com", "password": "password123", "real_name": "新管理员", "phone": "13900139000", "role_ids": [2, 3], "status": 1 } ``` #### 响应示例 ```json { "code": 201, "message": "创建成功", "data": { "id": 6, "username": "newadmin", "email": "newadmin@example.com", "real_name": "新管理员", "status": 1, "created_at": "2024-01-15T10:30:00Z" } } ``` ### 8.3 获取角色列表 #### 接口信息 - **接口路径**：`GET /api/v1/roles` - **接口描述**：获取所有角色列表 - **是否需要认证**：是 - **所需权限**：`role:read` #### 响应示例 ```json { "code": 200, "message": "获取成功", "data": { "items": [ { "id": 1, "name": "超级管理员", "code": "super_admin", "description": "拥有所有权限的超级管理员", "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 /api/v1/dashboard/stats` - **接口描述**：获取仪表板统计数据 - **是否需要认证**：是 - **所需权限**：`dashboard:read` #### 查询参数 | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | period | string | 否 | 统计周期：today,week,month,year，默认today | #### 响应示例 ```json { "code": 200, "message": "获取成功", "data": { "overview": { "total_users": 1250, "new_users_today": 15, "total_travels": 89, "active_travels": 23, "total_animals": 156, "adopted_animals": 67, "total_orders": 445, "total_revenue": 125600.00 }, "trends": { "user_growth": [ {"date": "2024-01-08", "count": 8}, {"date": "2024-01-09", "count": 12}, {"date": "2024-01-10", "count": 15}, {"date": "2024-01-11", "count": 10}, {"date": "2024-01-12", "count": 18}, {"date": "2024-01-13", "count": 22}, {"date": "2024-01-14", "count": 15} ], "order_trends": [ {"date": "2024-01-08", "count": 5, "amount": 2500.00}, {"date": "2024-01-09", "count": 8, "amount": 4200.00}, {"date": "2024-01-10", "count": 12, "amount": 6800.00}, {"date": "2024-01-11", "count": 6, "amount": 3200.00}, {"date": "2024-01-12", "count": 15, "amount": 8500.00}, {"date": "2024-01-13", "count": 18, "amount": 9200.00}, {"date": "2024-01-14", "count": 10, "amount": 5500.00} ] }, "distributions": { "user_types": [ {"type": "普通用户", "count": 1100, "percentage": 88.0}, {"type": "商家用户", "count": 150, "percentage": 12.0} ], "travel_types": [ {"type": "文化旅行", "count": 25, "percentage": 28.1}, {"type": "休闲旅行", "count": 32, "percentage": 36.0}, {"type": "探险旅行", "count": 18, "percentage": 20.2}, {"type": "商务旅行", "count": 14, "percentage": 15.7} ], "animal_species": [ {"species": "猫", "count": 78, "percentage": 50.0}, {"species": "狗", "count": 45, "percentage": 28.8}, {"species": "兔子", "count": 20, "percentage": 12.8}, {"species": "其他", "count": 13, "percentage": 8.3} ] } } } ``` ### 9.2 获取用户统计 #### 接口信息 - **接口路径**：`GET /api/v1/statistics/users` - **接口描述**：获取用户相关统计数据 - **是否需要认证**：是 - **所需权限**：`statistics:read` #### 查询参数 | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | start_date | string | 否 | 开始日期（YYYY-MM-DD） | | end_date | string | 否 | 结束日期（YYYY-MM-DD） | | group_by | string | 否 | 分组方式：day,week,month，默认day | #### 响应示例 ```json { "code": 200, "message": "获取成功", "data": { "summary": { "total_users": 1250, "active_users": 890, "new_users": 156, "retention_rate": 71.2 }, "registration_trends": [ {"date": "2024-01-01", "count": 12}, {"date": "2024-01-02", "count": 15}, {"date": "2024-01-03", "count": 8} ], "activity_trends": [ {"date": "2024-01-01", "active_count": 245}, {"date": "2024-01-02", "active_count": 289}, {"date": "2024-01-03", "active_count": 267} ], "demographics": { "age_groups": [ {"range": "18-25", "count": 320, "percentage": 25.6}, {"range": "26-35", "count": 450, "percentage": 36.0}, {"range": "36-45", "count": 280, "percentage": 22.4}, {"range": "46+", "count": 200, "percentage": 16.0} ], "gender_distribution": [ {"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版本管理和功能扩展 该接口设计文档为前端开发、测试和运维提供了完整的技术规范，确保系统各模块间的高效协作和数据一致性。