012-kaopeilian/frontend/前后端接口约定.md

# 前后端接口约定

## 基础规范

### 请求格式

- **Base URL**: `http://localhost:8000` (开发) / `https://aiedu.ireborn.com.cn` (生产)
- **Content-Type**: `application/json`
- **认证**: `Authorization: Bearer <jwt_token>`响应格式

```json
{
  "code": 200,
  "message": "success",
  "data": {}
}
```

### 状态码

- `200`: 成功
- `400`: 参数错误
- `401`: 未认证
- `403`: 权限不足
- `404`: 资源不存在
- `500`: 服务器错误

## 核心接口

### 1. 认证模块 `/api/v1/auth`

#### 登录

```http
POST /api/v1/auth/login
{
  "username": "string",
  "password": "string"
}
```

#### 注册

```http
POST /api/v1/auth/register
{
  "username": "string",
  "email": "string",
  "password": "string",
  "name": "string"
}
```

#### 刷新Token

```http
POST /api/v1/auth/refresh
{
  "refresh_token": "string"
}
```

### 2. 用户模块 `/api/v1/users`

#### 用户列表

```http
GET /api/v1/users?page=1&size=10&keyword=string
```

#### 当前用户

```http
GET /api/v1/users/me
```

#### 更新用户

```http
PUT /api/v1/users/{id}
{
  "name": "string",
  "email": "string"
}
```

### 3. 课程模块 `/api/v1/courses`

#### 课程列表

```http
GET /api/v1/courses?page=1&size=10&category=string
```

#### 课程详情

```http
GET /api/v1/courses/{id}
```

#### 课程材料

```http
GET /api/v1/courses/{id}/materials
```

### 4. 考试模块 `/api/v1/exams`

#### 开始考试

```http
POST /api/v1/exams/dynamic/start
{
  "courseId": 1,
  "totalRounds": 10
}
```

#### 提交答案

```http
POST /api/v1/exams/dynamic/submit
{
  "sessionId": "string",
  "questionId": "string",
  "answer": "string"
}
```

#### 考试记录

```http
GET /api/v1/exams/records?page=1&size=10
```

### 5. 陪练模块 `/api/v1/training`

#### 陪练场景

```http
GET /api/v1/training-scenes
```

#### 开始陪练

```http
POST /api/v1/training/start
{
  "sceneId": 1
}
```

#### 陪练记录

```http
GET /api/v1/training-records?page=1&size=10
```

#### WebSocket陪练

```
WS /ws/v1/training/{sessionId}
```

### 6. 分析模块 `/api/v1/analytics`

#### 系统概览

```http
GET /api/v1/analytics/overview?timeRange=30d
```

#### 能力雷达图

```http
GET /api/v1/analytics/ability-radar?userId=1
```

## 数据结构

### 用户信息

```json
{
  "id": 1,
  "username": "string",
  "email": "string",
  "name": "string",
  "role": "admin|manager|trainee",
  "status": "active|inactive"
}
```

### 课程信息

```json
{
  "id": 1,
  "title": "string",
  "description": "string",
  "category": "string",
  "difficulty": "beginner|intermediate|advanced",
  "duration": 60,
  "progress": 0,
  "status": "published|draft"
}
```

### 考试题目

```json
{
  "id": "string",
  "type": "single|multiple|judge|fill",
  "content": "string",
  "options": [{"id": "A", "content": "string"}],
  "score": 10
}
```

### 陪练场景

```json
{
  "id": 1,
  "name": "string",
  "description": "string",
  "category": "string",
  "difficulty": "easy|medium|hard",
  "status": "active|inactive"
}
```

## 分页格式

### 请求参数

- `page`: 页码 (从1开始)
- `size`: 每页数量 (默认10)

### 响应格式

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "items": [],
    "total": 100,
    "page": 1,
    "size": 10
  }
}
```

## 文件上传

```http
POST /api/v1/upload
Content-Type: multipart/form-data

file: <binary>
type: "avatar|course-cover|material"
```

**响应**:

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "url": "string",
    "filename": "string"
  }
}
```

## 错误格式

```json
{
  "code": 400,
  "message": "参数错误",
  "data": null,
  "errors": [
    {
      "field": "email",
      "message": "邮箱格式不正确"
    }
  ]
}
```