---
title: 后台 API
description: WWJCloud 后台管理员访问的 API 接口文档
---

# 后台 API

::: info 后台 API 说明

后台 API 是面向系统管理员的接口，提供会员管理、系统配置、权限管理等功能。

:::

## API 基础信息

- **基础路径**: `/adminapi/`
- **认证方式**: JWT Bearer Token
- **内容类型**: `application/json`
- **字符编码**: `UTF-8`
- **权限要求**: 管理员权限

## 模块列表

### 👥 会员管理 (`/adminapi/member/`)

后台会员管理功能：

- **会员列表** - 获取会员列表，支持分页和搜索
- **会员详情** - 查看会员详细信息
- **创建会员** - 后台创建新会员
- **更新会员** - 修改会员信息
- **删除会员** - 删除会员（软删除）
- **批量操作** - 批量删除、状态更新、等级分配
- **积分管理** - 调整会员积分
- **余额管理** - 调整会员余额

### 🔧 管理员管理 (`/adminapi/admin/`)

系统管理员管理功能：

- **管理员列表** - 获取管理员列表
- **创建管理员** - 创建新的管理员账户
- **更新管理员** - 修改管理员信息
- **删除管理员** - 删除管理员账户
- **权限分配** - 为管理员分配权限
- **登录日志** - 查看管理员登录记录

### 🔐 权限管理 (`/adminapi/rbac/`)

基于角色的访问控制：

- **角色管理** - 角色的增删改查
- **权限管理** - 权限的增删改查
- **角色权限** - 为角色分配权限
- **用户角色** - 为用户分配角色
- **权限验证** - 验证用户权限

### ⚙️ 系统管理 (`/adminapi/system/`)

系统配置管理：

- **菜单管理** - 系统菜单配置
- **系统设置** - 系统参数配置
- **数据字典** - 系统数据字典
- **操作日志** - 系统操作日志
- **系统监控** - 系统运行状态

### 📢 通知管理 (`/adminapi/notice/`)

通知消息管理：

- **消息模板** - 消息模板管理
- **推送记录** - 消息推送历史
- **微信通知** - 微信消息推送
- **短信通知** - 短信消息推送

## 认证流程

### 1. 管理员登录

```http
POST /adminapi/admin/login
Content-Type: application/json

{
  "username": "admin",
  "password": "admin123",
  "captcha": "1234"
}
```

**响应示例**:

```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 7200,
    "admin_info": {
      "admin_id": 1,
      "username": "admin",
      "nickname": "超级管理员",
      "role": "super_admin",
      "permissions": ["member:list", "member:create", "member:update", "member:delete"]
    }
  }
}
```

### 2. 获取会员列表

```http
GET /adminapi/member?page=1&limit=10&keyword=test&status=1
Authorization: Bearer <your-jwt-token>
```

**响应示例**:

```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "list": [
      {
        "member_id": 1001,
        "username": "user@example.com",
        "nickname": "用户昵称",
        "phone": "13800138000",
        "email": "user@example.com",
        "status": 1,
        "points": 1000,
        "balance": 99.99,
        "level": {
          "level_id": 1,
          "level_name": "普通会员"
        },
        "create_time": 1640995200,
        "last_login_time": 1640995200
      }
    ],
    "total": 100,
    "page": 1,
    "limit": 10,
    "pages": 10
  }
}
```

### 3. 创建会员

```http
POST /adminapi/member
Authorization: Bearer <your-jwt-token>
Content-Type: application/json

{
  "username": "newuser@example.com",
  "password": "password123",
  "nickname": "新用户",
  "phone": "13800138001",
  "email": "newuser@example.com",
  "level_id": 1
}
```

**响应示例**:

```json
{
  "code": 201,
  "message": "创建成功",
  "data": {
    "member_id": 1002,
    "username": "newuser@example.com",
    "nickname": "新用户",
    "create_time": 1640995200
  }
}
```

## 权限控制

### 权限验证

所有后台 API 都需要验证管理员权限：

```typescript
// 权限装饰器示例
@Roles('admin', 'super_admin')
@UseGuards(JwtAuthGuard, RolesGuard)
@Controller('adminapi/member')
export class MemberController {
  // ...
}
```

### 权限级别

| 权限级别 | 说明 | 示例 |
|----------|------|------|
| super_admin | 超级管理员 | 所有权限 |
| admin | 普通管理员 | 部分管理权限 |
| operator | 操作员 | 只读权限 |

### 权限检查

```javascript
// 前端权限检查示例
const checkPermission = (permission) => {
  const userPermissions = getUserPermissions();
  return userPermissions.includes(permission);
};

// 使用示例
if (checkPermission('member:create')) {
  // 显示创建按钮
}
```

## 查询参数

### 通用查询参数

所有列表接口支持以下查询参数：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | number | 否 | 页码，默认 1 |
| limit | number | 否 | 每页数量，默认 10，最大 100 |
| keyword | string | 否 | 关键词搜索 |
| status | number | 否 | 状态筛选 |
| start_time | number | 否 | 开始时间（时间戳） |
| end_time | number | 否 | 结束时间（时间戳） |
| sort | string | 否 | 排序字段 |
| order | string | 否 | 排序方向，asc/desc |

### 高级查询

支持复杂的查询条件：

```http
GET /adminapi/member?page=1&limit=20&keyword=test&status=1&level_id=2&start_time=1640995200&end_time=1641081600&sort=create_time&order=desc
```

## 批量操作

### 批量删除

```http
POST /adminapi/member/batch-delete
Authorization: Bearer <your-jwt-token>
Content-Type: application/json

{
  "member_ids": [1001, 1002, 1003]
}
```

### 批量更新状态

```http
POST /adminapi/member/batch-update-status
Authorization: Bearer <your-jwt-token>
Content-Type: application/json

{
  "member_ids": [1001, 1002, 1003],
  "status": 0
}
```

### 批量分配等级

```http
POST /adminapi/member/batch-assign-level
Authorization: Bearer <your-jwt-token>
Content-Type: application/json

{
  "member_ids": [1001, 1002, 1003],
  "level_id": 2
}
```

## 数据导出

### 导出会员列表

```http
GET /adminapi/member/export?format=excel&keyword=test&status=1
Authorization: Bearer <your-jwt-token>
```

**支持格式**:
- Excel (.xlsx)
- CSV (.csv)
- PDF (.pdf)

## 错误处理

### 权限错误

```json
{
  "code": 403,
  "message": "权限不足",
  "data": {
    "required_permission": "member:delete",
    "current_permissions": ["member:list", "member:view"]
  }
}
```

### 参数验证错误

```json
{
  "code": 400,
  "message": "参数验证失败",
  "data": {
    "errors": [
      {
        "field": "username",
        "message": "用户名已存在"
      },
      {
        "field": "password",
        "message": "密码长度不能少于6位"
      }
    ]
  }
}
```

## 操作日志

所有后台操作都会记录操作日志：

```json
{
  "log_id": 1001,
  "admin_id": 1,
  "action": "member:create",
  "target": "member",
  "target_id": 1002,
  "description": "创建会员：newuser@example.com",
  "ip": "192.168.1.100",
  "user_agent": "Mozilla/5.0...",
  "create_time": 1640995200
}
```

## 开发建议

### 1. 权限管理

```javascript
// 权限管理工具函数
const PermissionManager = {
  // 检查是否有权限
  hasPermission(permission) {
    const permissions = this.getUserPermissions();
    return permissions.includes(permission);
  },
  
  // 检查是否有任意一个权限
  hasAnyPermission(permissions) {
    const userPermissions = this.getUserPermissions();
    return permissions.some(p => userPermissions.includes(p));
  },
  
  // 检查是否有所有权限
  hasAllPermissions(permissions) {
    const userPermissions = this.getUserPermissions();
    return permissions.every(p => userPermissions.includes(p));
  }
};
```

### 2. 请求封装

```javascript
// API 请求封装
const adminApi = {
  // 获取会员列表
  async getMemberList(params) {
    return await request.get('/adminapi/member', { params });
  },
  
  // 创建会员
  async createMember(data) {
    return await request.post('/adminapi/member', data);
  },
  
  // 更新会员
  async updateMember(id, data) {
    return await request.put(`/adminapi/member/${id}`, data);
  },
  
  // 删除会员
  async deleteMember(id) {
    return await request.delete(`/adminapi/member/${id}`);
  },
  
  // 批量操作
  async batchOperation(action, data) {
    return await request.post(`/adminapi/member/batch-${action}`, data);
  }
};
```

### 3. 错误处理

```javascript
// 统一错误处理
const handleApiError = (error) => {
  if (error.response) {
    const { status, data } = error.response;
    
    switch (status) {
      case 401:
        // Token 过期，跳转登录
        router.push('/login');
        break;
      case 403:
        // 权限不足
        ElMessage.error('权限不足');
        break;
      case 429:
        // 请求过于频繁
        ElMessage.error('请求过于频繁，请稍后再试');
        break;
      default:
        ElMessage.error(data.message || '请求失败');
    }
  }
};
```

## 测试工具

### Swagger UI

访问 `http://localhost:3000/api/admin` 查看完整的后台 API 文档和在线测试功能。

### Postman 集合

可以导入以下 Postman 集合进行测试：

```json
{
  "info": {
    "name": "WWJCloud 后台 API",
    "description": "后台管理 API 接口集合"
  },
  "item": [
    {
      "name": "会员管理",
      "item": [
        {
          "name": "获取会员列表",
          "request": {
            "method": "GET",
            "url": "{{base_url}}/adminapi/member"
          }
        },
        {
          "name": "创建会员",
          "request": {
            "method": "POST",
            "url": "{{base_url}}/adminapi/member"
          }
        }
      ]
    }
  ]
}
``` 