aiotagro/jiebanke
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5fc1a4fcb908ec83a507ba590f4f1bb99645a56e
jiebanke/docs/管理后台接口设计文档.md

1946 lines
48 KiB
Markdown
Raw Normal View History

重构动物认领页面和导航菜单，统一使用SVG图标并优化交互体验
2025-09-21 21:12:27 +08:00
# 管理后台接口设计文档
## 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 <JWT_TOKEN>
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版本管理和功能扩展
该接口设计文档为前端开发、测试和运维提供了完整的技术规范，确保系统各模块间的高效协作和数据一致性。
Reference in New Issue Copy Permalink