live-forum/server/admin/需求/API接口文档.md

# Live Forum 后台管理 API 接口文档

## 基础信息

- **Base URL**: `/api/v1/admin`
- **认证方式**: 管理员Token认证
- **Content-Type**: `application/json`
- **文档版本**: v1.0
- **更新日期**: 2025-10-24

---

## 认证方式

### 管理员Token认证
```http
Authorization: Bearer {admin_token}
```

### 权限级别
- **只读权限**: 只能查看数据
- **编辑权限**: 可以修改内容状态
- **删除权限**: 可以删除内容
- **审核权限**: 可以审核内容和认证

---

## 1. 内容管理 API

### 1.1 帖子管理

#### 获取帖子列表
```http
GET /admin/posts
```

**请求参数**:
```json
{
  "pageIndex": 1,           // 页码，从1开始
  "pageSize": 20,           // 每页数量
  "status": 1,              // 帖子状态：0-草稿，1-发布，2-审核，3-下架
  "categoryId": 1,          // 分类ID
  "userId": 1001,           // 用户ID
  "keyword": "搜索关键词",   // 搜索关键词
  "startDate": "2024-01-01", // 开始日期
  "endDate": "2024-12-31",   // 结束日期
  "isTop": true,             // 是否置顶
  "isHot": true,             // 是否热门
  "isEssence": true          // 是否精华
}
```

**返回参数**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "total": 100,
    "pageIndex": 1,
    "pageSize": 20,
    "totalPages": 5,
    "items": [
      {
        "postId": 1001,
        "title": "帖子标题",
        "content": "帖子内容",
        "userId": 1001,
        "userName": "用户名",
        "userAvatar": "头像URL",
        "categoryId": 1,
        "categoryName": "分类名称",
        "status": 1,
        "statusText": "已发布",
        "isTop": false,
        "isHot": true,
        "isEssence": false,
        "viewCount": 1000,
        "likeCount": 50,
        "commentCount": 20,
        "shareCount": 10,
        "createdAt": "2024-01-01T10:00:00",
        "updatedAt": "2024-01-01T12:00:00",
        "images": [
          {
            "imageId": 2001,
            "imageUrl": "图片URL",
            "sortOrder": 1
          }
        ]
      }
    ]
  }
}
```

#### 获取帖子详情
```http
GET /admin/posts/{postId}
```

**返回参数**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "postId": 1001,
    "title": "帖子标题",
    "content": "帖子完整内容",
    "userId": 1001,
    "userName": "用户名",
    "userAvatar": "头像URL",
    "userLevel": "LV1",
    "isVip": true,
    "isCertified": false,
    "categoryId": 1,
    "categoryName": "分类名称",
    "status": 1,
    "statusText": "已发布",
    "isTop": false,
    "isHot": true,
    "isEssence": false,
    "viewCount": 1000,
    "likeCount": 50,
    "commentCount": 20,
    "shareCount": 10,
    "createdAt": "2024-01-01T10:00:00",
    "updatedAt": "2024-01-01T12:00:00",
    "images": [
      {
        "imageId": 2001,
        "imageUrl": "图片URL",
        "sortOrder": 1,
        "createdAt": "2024-01-01T10:00:00"
      }
    ],
    "comments": [
      {
        "commentId": 3001,
        "content": "评论内容",
        "userId": 1002,
        "userName": "评论用户",
        "likeCount": 5,
        "replyCount": 2,
        "createdAt": "2024-01-01T11:00:00"
      }
    ]
  }
}
```

#### 更新帖子状态
```http
POST /admin/posts/{postId}/status/update
```

**请求参数**:
```json
{
  "status": 2,              // 新状态：0-草稿，1-发布，2-审核，3-下架
  "reason": "审核不通过"     // 状态变更原因
}
```

#### 更新帖子特性
```http
POST /admin/posts/{postId}/feature/update
```

**请求参数**:
```json
{
  "isTop": true,            // 是否置顶
  "isHot": false,           // 是否热门
  "isEssence": true,        // 是否精华
  "categoryId": 2           // 分类ID
}
```

#### 删除帖子
```http
POST /admin/posts/{postId}/delete
```

**请求参数**:
```json
{
  "reason": "违规内容",     // 删除原因
  "isSoftDelete": true     // 是否软删除
}
```

#### 批量操作帖子
```http
POST /admin/posts/batch
```

**请求参数**:
```json
{
  "postIds": [1001, 1002, 1003], // 帖子ID列表
  "operation": "approve",        // 操作类型：approve-审核通过，reject-审核拒绝，delete-删除，setTop-置顶，cancelTop-取消置顶
  "reason": "批量审核通过"        // 操作原因
}
```

---

### 1.2 评论管理

#### 获取评论列表
```http
GET /admin/comments
```

**请求参数**:
```json
{
  "pageIndex": 1,
  "pageSize": 20,
  "postId": 1001,           // 帖子ID
  "userId": 1001,           // 用户ID
  "keyword": "搜索关键词",
  "startDate": "2024-01-01",
  "endDate": "2024-12-31"
}
```

#### 删除评论
```http
POST /admin/comments/{commentId}/delete
```

**请求参数**:
```json
{
  "reason": "违规评论",     // 删除原因
  "isSoftDelete": true     // 是否软删除
}
```

#### 批量操作评论
```http
POST /admin/comments/batch
```

**请求参数**:
```json
{
  "commentIds": [3001, 3002, 3003],
  "operation": "delete",   // 操作类型：delete-删除，hide-隐藏，show-显示
  "reason": "批量删除违规评论"
}
```

---

### 1.3 图片管理

#### 获取图片列表
```http
GET /admin/images
```

**请求参数**:
```json
{
  "pageIndex": 1,
  "pageSize": 20,
  "userId": 1001,           // 用户ID
  "postId": 1001,           // 帖子ID
  "startDate": "2024-01-01",
  "endDate": "2024-12-31",
  "minSize": 1024,          // 最小文件大小（字节）
  "maxSize": 10485760       // 最大文件大小（字节）
}
```

#### 删除图片
```http
POST /admin/images/{imageId}/delete
```

**请求参数**:
```json
{
  "reason": "违规图片",     // 删除原因
  "deleteFile": true       // 是否删除物理文件
}
```

---

## 2. 用户管理 API

### 2.1 用户信息管理

#### 获取用户列表
```http
GET /admin/users
```

**请求参数**:
```json
{
  "pageIndex": 1,
  "pageSize": 20,
  "status": 1,              // 用户状态：0-正常，1-禁用，2-冻结
  "levelId": 2,             // 等级ID
  "isVip": true,            // 是否VIP
  "isCertified": false,     // 是否认证
  "keyword": "搜索关键词",
  "startDate": "2024-01-01",
  "endDate": "2024-12-31"
}
```

#### 获取用户详情
```http
GET /admin/users/{userId}
```

**返回参数**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "userId": 1001,
    "userName": "用户名",
    "nickName": "昵称",
    "avatar": "头像URL",
    "phoneNumber": "138****8000",
    "email": "user@example.com",
    "gender": 1,
    "birthday": "1990-01-01",
    "signature": "个性签名",
    "status": 1,
    "statusText": "正常",
    "isVip": true,
    "vipExpireTime": "2025-12-31T23:59:59",
    "isCertified": false,
    "certifiedType": 1,
    "levelId": 2,
    "levelName": "LV1",
    "experience": 150,
    "postCount": 25,
    "commentCount": 100,
    "followingCount": 50,
    "followerCount": 80,
    "totalLikes": 500,
    "createdAt": "2024-01-01T10:00:00",
    "lastLoginAt": "2024-01-15T14:30:00",
    "lastLoginIp": "192.168.1.100",
    "registerIp": "192.168.1.1"
  }
}
```

#### 更新用户状态
```http
POST /admin/users/{userId}/status/update
```

**请求参数**:
```json
{
  "status": 1,              // 新状态：0-正常，1-禁用，2-冻结
  "reason": "违规行为",     // 状态变更原因
  "duration": 7             // 冻结时长（天），0表示永久
}
```

#### 更新用户等级
```http
POST /admin/users/{userId}/level/update
```

**请求参数**:
```json
{
  "levelId": 3,             // 新等级ID
  "experience": 500,        // 经验值
  "reason": "等级调整"      // 调整原因
}
```

#### 更新VIP状态
```http
POST /admin/users/{userId}/vip/update
```

**请求参数**:
```json
{
  "isVip": true,            // 是否VIP
  "expireTime": "2025-12-31T23:59:59", // VIP过期时间
  "reason": "VIP赠送"       // 操作原因
}
```

---

### 2.2 认证申请管理

#### 获取认证申请列表
```http
GET /admin/certifications
```

**请求参数**:
```json
{
  "pageIndex": 1,
  "pageSize": 20,
  "status": 0,              // 申请状态：0-待审核，1-已通过，2-已拒绝
  "certificationType": 1,   // 认证类型：1-SK认证
  "startDate": "2024-01-01",
  "endDate": "2024-12-31"
}
```

#### 审核认证申请
```http
POST /admin/certifications/{certificationId}/review
```

**请求参数**:
```json
{
  "status": 1,              // 审核结果：1-通过，2-拒绝
  "reason": "认证通过",     // 审核原因
  "reviewNotes": "审核备注" // 审核备注
}
```

---

## 3. 互动管理 API

### 3.1 举报管理

#### 获取举报列表
```http
GET /admin/reports
```

**请求参数**:
```json
{
  "pageIndex": 1,
  "pageSize": 20,
  "status": 0,              // 处理状态：0-待处理，1-已处理
  "reportType": 1,           // 举报类型：1-帖子，2-评论，3-用户
  "startDate": "2024-01-01",
  "endDate": "2024-12-31"
}
```

#### 处理举报
```http
POST /admin/reports/{reportId}/handle
```

**请求参数**:
```json
{
  "status": 1,              // 处理结果：1-有效，2-无效
  "action": "delete",       // 处理动作：delete-删除，warn-警告，ignore-忽略
  "reason": "处理原因",     // 处理原因
  "notes": "处理备注"       // 处理备注
}
```

---

### 3.2 点赞管理

#### 获取点赞统计
```http
GET /admin/likes/statistics
```

**请求参数**:
```json
{
  "startDate": "2024-01-01",
  "endDate": "2024-12-31",
  "targetType": 1,          // 目标类型：1-帖子，2-评论
  "userId": 1001           // 用户ID
}
```

#### 清理异常点赞
```http
POST /admin/likes/cleanup
```

**请求参数**:
```json
{
  "targetType": 1,          // 目标类型
  "targetId": 1001,         // 目标ID
  "reason": "刷赞行为"      // 清理原因
}
```

---

## 4. 内容配置 API

### 4.1 轮播图管理

#### 获取轮播图列表
```http
GET /admin/banners
```

#### 添加轮播图
```http
POST /admin/banners
```

**请求参数**:
```json
{
  "title": "轮播图标题",
  "imageUrl": "图片URL",
  "linkUrl": "跳转链接",
  "sortOrder": 1,
  "isActive": true,
  "startTime": "2024-01-01T00:00:00",
  "endTime": "2024-12-31T23:59:59"
}
```

#### 更新轮播图
```http
POST /admin/banners/{bannerId}/update
```

#### 删除轮播图
```http
POST /admin/banners/{bannerId}/delete
```

---

### 4.2 帖子分类管理

#### 获取分类列表
```http
GET /admin/categories
```

#### 添加分类
```http
POST /admin/categories
```

**请求参数**:
```json
{
  "categoryName": "分类名称",
  "description": "分类描述",
  "icon": "分类图标",
  "sortOrder": 1,
  "isActive": true
}
```

#### 更新分类
```http
POST /admin/categories/{categoryId}/update
```

#### 删除分类
```http
POST /admin/categories/{categoryId}/delete
```

---

### 4.3 用户等级管理

#### 获取等级列表
```http
GET /admin/levels
```

#### 添加等级
```http
POST /admin/levels
```

**请求参数**:
```json
{
  "levelName": "LV6",
  "levelIcon": "等级图标",
  "levelColor": "#FF0000",
  "minExperience": 1000,
  "maxExperience": 1999,
  "privileges": {
    "maxPostsPerDay": 20,
    "canComment": true,
    "canUploadVideo": true
  }
}
```

#### 更新等级
```http
POST /admin/levels/{levelId}/update
```

#### 删除等级
```http
POST /admin/levels/{levelId}/delete
```

---

### 4.4 协议内容管理

#### 获取协议列表
```http
GET /admin/agreements
```

#### 更新协议内容
```http
POST /admin/agreements/{agreementId}/update
```

**请求参数**:
```json
{
  "title": "用户协议",
  "content": "协议内容",
  "version": "v2.0",
  "effectiveDate": "2024-01-01T00:00:00"
}
```

---

## 5. 消息管理 API

### 5.1 系统通知管理

#### 获取通知列表
```http
GET /admin/notifications
```

#### 添加通知
```http
POST /admin/notifications
```

**请求参数**:
```json
{
  "title": "通知标题",
  "content": "通知内容",
  "notificationType": 1,    // 通知类型：1-系统公告，2-活动通知
  "targetUsers": [1001, 1002], // 目标用户ID列表，空表示全部用户
  "isActive": true,
  "publishTime": "2024-01-01T10:00:00",
  "expireTime": "2024-12-31T23:59:59"
}
```

#### 发布通知
```http
POST /admin/notifications/{notificationId}/publish
```

#### 删除通知
```http
POST /admin/notifications/{notificationId}/delete
```

---

### 5.2 用户消息管理

#### 获取消息列表
```http
GET /admin/messages
```

**请求参数**:
```json
{
  "pageIndex": 1,
  "pageSize": 20,
  "messageType": 1,         // 消息类型：1-评论回复，2-点赞，3-关注
  "userId": 1001,           // 用户ID
  "startDate": "2024-01-01",
  "endDate": "2024-12-31"
}
```

#### 删除消息
```http
POST /admin/messages/{messageId}/delete
```

---

## 6. 数据统计 API

### 6.1 内容统计

#### 获取内容统计
```http
GET /admin/statistics/content
```

**请求参数**:
```json
{
  "startDate": "2024-01-01",
  "endDate": "2024-12-31",
  "groupBy": "day"          // 分组方式：day-按天，week-按周，month-按月
}
```

**返回参数**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "posts": {
      "total": 1000,
      "today": 10,
      "trend": [
        {
          "date": "2024-01-01",
          "count": 15
        }
      ]
    },
    "comments": {
      "total": 5000,
      "today": 50,
      "trend": []
    },
    "images": {
      "total": 2000,
      "totalSize": "10GB",
      "trend": []
    },
    "users": {
      "total": 500,
      "active": 100,
      "trend": []
    }
  }
}
```

### 6.2 用户行为统计

#### 获取用户行为统计
```http
GET /admin/statistics/user-behavior
```

**请求参数**:
```json
{
  "startDate": "2024-01-01",
  "endDate": "2024-12-31",
  "metrics": ["login", "post", "comment", "like"] // 统计指标
}
```

### 6.3 系统性能统计

#### 获取系统性能统计
```http
GET /admin/statistics/system-performance
```

**请求参数**:
```json
{
  "startDate": "2024-01-01",
  "endDate": "2024-12-31",
  "metrics": ["api", "database", "cache", "storage"]
}
```

---

## 错误码说明

### 通用错误码
| 错误码 | 说明 |
|--------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未授权（未登录或Token过期） |
| 403 | 无权限访问 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |

### 管理功能错误码
| 错误码 | 说明 |
|--------|------|
| 60001 | 无管理权限 |
| 60002 | 操作目标不存在 |
| 60003 | 操作失败 |
| 60004 | 批量操作部分失败 |
| 60005 | 配置项不存在 |
| 60006 | 配置值无效 |

---

## 使用示例

### 获取帖子列表并筛选
```javascript
// 获取待审核的帖子
const response = await fetch('/api/v1/admin/posts?status=2&pageIndex=1&pageSize=20', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer ' + adminToken,
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data.data.items);
```

### 批量审核帖子
```javascript
// 批量审核通过帖子
const response = await fetch('/api/v1/admin/posts/batch', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + adminToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    postIds: [1001, 1002, 1003],
    operation: 'approve',
    reason: '批量审核通过'
  })
});
```

### 更新用户状态
```javascript
// 禁用用户
const response = await fetch('/api/v1/admin/users/1001/status/update', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + adminToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    status: 1,
    reason: '违规行为',
    duration: 7
  })
});
```

---

## 注意事项

1. **权限控制**: 所有管理API都需要管理员Token认证
2. **操作记录**: 所有管理操作都会记录到操作日志
3. **批量限制**: 批量操作建议单次不超过100条记录
4. **分页查询**: 建议使用分页查询，避免一次性查询大量数据
5. **错误处理**: 请根据错误码进行相应的错误处理
6. **数据安全**: 敏感操作需要二次确认

---

## 更新日志

### v1.0 (2025-10-24)
- ✅ 完成内容管理API设计
- ✅ 完成用户管理API设计
- ✅ 完成互动管理API设计
- ✅ 完成配置管理API设计
- ✅ 完成消息管理API设计
- ✅ 完成数据统计API设计