# API 接口文档

## 📡 接口基础信息

### 基础配置
- **基础路径**：`/api`
- **请求方法**：支持 GET, POST, PUT, DELETE, PATCH
- **认证方式**：JWT Token
- **数据格式**：JSON

### 请求头
```http
Content-Type: application/json
Authorization: Bearer {token}
```

### 响应格式
```json
{
  "code": 2000,
  "message": "操作成功",
  "data": {},
  "total": 0
}
```

## 🔐 认证接口

### 用户登录
- **路径**：`/api/system/auth/login/`
- **方法**：POST
- **请求体**：
```json
{
  "username": "string",
  "password": "string"
}
```
- **响应**：
```json
{
  "code": 2000,
  "data": {
    "token": "string",
    "refresh_token": "string",
    "user_info": {}
  }
}
```

## 👤 用户管理接口

### 用户列表
- **路径**：`/api/system/user/`
- **方法**：GET
- **参数**：
  - `page`: 页码
  - `limit`: 每页数量
  - `username`: 用户名（可选）
  - `dept_id`: 部门ID（可选）

### 用户详情
- **路径**：`/api/system/user/{id}/`
- **方法**：GET

### 创建用户
- **路径**：`/api/system/user/`
- **方法**：POST
- **请求体**：
```json
{
  "username": "string",
  "password": "string",
  "name": "string",
  "email": "string",
  "mobile": "string",
  "dept_id": "integer",
  "roles": ["integer"]
}
```

### 更新用户
- **路径**：`/api/system/user/{id}/`
- **方法**：PUT/PATCH

### 删除用户
- **路径**：`/api/system/user/{id}/`
- **方法**：DELETE

## 🏢 职位管理接口

### 职位列表
- **路径**：`/api/position/list/`
- **方法**：GET
- **参数**：
  - `page`: 页码
  - `limit`: 每页数量
  - `status`: 状态（可选）
  - `keyword`: 关键词（可选）

### 职位详情
- **路径**：`/api/position/detail/{id}/`
- **方法**：GET

### 创建职位
- **路径**：`/api/position/create/`
- **方法**：POST

### 更新职位
- **路径**：`/api/position/update/{id}/`
- **方法**：PUT

### 职位配置
- **路径**：`/api/position/config/{id}/`
- **方法**：GET/POST/PUT
- **说明**：获取/创建/更新职位面试配置

### 职位能力关联
- **路径**：`/api/position/competency/{id}/`
- **方法**：POST/GET
- **说明**：职位与能力模型的关联管理

## 📚 题库管理接口

### 题目列表
- **路径**：`/api/question_bank/list/`
- **方法**：GET
- **参数**：
  - `page`: 页码
  - `limit`: 每页数量
  - `category_id`: 分类ID（可选）
  - `tag_id`: 标签ID（可选）
  - `difficulty`: 难度（可选）
  - `type`: 题型（可选）

### 题目详情
- **路径**：`/api/question_bank/{id}/`
- **方法**：GET

### 创建题目
- **路径**：`/api/question_bank/create/`
- **方法**：POST
- **请求体**：
```json
{
  "type": "choice",
  "title": "string",
  "options": [],
  "answer": "string",
  "difficulty": "easy",
  "score": 10,
  "category_id": "integer",
  "tags": ["integer"]
}
```

### 批量操作
- **路径**：`/api/question_bank/batch/`
- **方法**：POST
- **说明**：批量修改分类、标签等

### 题目分类列表
- **路径**：`/api/question_bank/class/`
- **方法**：GET

### 题目标签列表
- **路径**：`/api/question_bank/tag/`
- **方法**：GET

## 💼 求职申请接口

### 申请列表
- **路径**：`/api/job_application/list/`
- **方法**：GET
- **参数**：
  - `page`: 页码
  - `limit`: 每页数量
  - `position_id`: 职位ID（可选）
  - `status`: 状态（可选）

### 申请详情
- **路径**：`/api/job_application/{id}/`
- **方法**：GET

### 更新申请状态
- **路径**：`/api/job_application/status/{id}/`
- **方法**：PATCH
- **请求体**：
```json
{
  "status": "interviewed",
  "remark": "string"
}
```

### 批量更新状态
- **路径**：`/api/job_application/batch_status/`
- **方法**：POST

## 👥 人才管理接口

### 人才列表
- **路径**：`/api/talent/list/`
- **方法**：GET

### 人才详情
- **路径**：`/api/talent/{id}/`
- **方法**：GET

### 海外人才列表
- **路径**：`/api/talent/overseas/`
- **方法**：GET

## 🤖 数字人面试接口

### 数字人列表
- **路径**：`/api/digital_human/list/`
- **方法**：GET

### 数字人详情
- **路径**：`/api/digital_human/{id}/`
- **方法**：GET

### 面试记录
- **路径**：`/api/digital_human/interview/{id}/`
- **方法**：GET

## 🔧 系统管理接口

### 菜单管理
- **路径**：`/api/system/menu/`
- **方法**：GET/POST/PUT/DELETE

### 角色管理
- **路径**：`/api/system/role/`
- **方法**：GET/POST/PUT/DELETE

### 部门管理
- **路径**：`/api/system/dept/`
- **方法**：GET/POST/PUT/DELETE

### 字典管理
- **路径**：`/api/system/dict/`
- **方法**：GET/POST/PUT/DELETE

### 地区管理
- **路径**：`/api/system/area/`
- **方法**：GET

### 文件上传
- **路径**：`/api/system/file/`
- **方法**：POST
- **Content-Type**：multipart/form-data
- **字段名**：`file`

### 文件列表
- **路径**：`/api/system/file/list/`
- **方法**：GET

### 操作日志
- **路径**：`/api/system/log/operation/`
- **方法**：GET

### 登录日志
- **路径**：`/api/system/log/login/`
- **方法**：GET

## 🎯 错误码说明

| 错误码 | 说明 |
|--------|------|
| 2000 | 操作成功 |
| 4000 | 参数错误 |
| 4001 | 认证失败 |
| 4003 | 权限不足 |
| 4040 | 资源不存在 |
| 5000 | 服务器错误 |

## 📝 接口调用示例

### 使用 Axios 调用
```typescript
import { request } from '@/utils/service'

// GET 请求
const getList = async () => {
  const res = await request({
    url: '/api/position/list/',
    method: 'get',
    params: {
      page: 1,
      limit: 20
    }
  })
  return res.data
}

// POST 请求
const createItem = async (data: any) => {
  const res = await request({
    url: '/api/position/create/',
    method: 'post',
    data: data
  })
  return res.data
}

// PUT 请求
const updateItem = async (id: number, data: any) => {
  const res = await request({
    url: `/api/position/update/${id}/`,
    method: 'put',
    data: data
  })
  return res.data
}

// DELETE 请求
const deleteItem = async (id: number) => {
  const res = await request({
    url: `/api/position/delete/${id}/`,
    method: 'delete'
  })
  return res.data
}
```

## 🔒 权限说明

### 接口权限
- 所有接口默认需要登录认证
- 部分接口需要特定角色权限
- 可以在系统菜单管理中配置接口权限

### 数据权限
- 支持按部门过滤数据
- 支持按角色过滤数据
- 管理员可以查看所有数据

## 📊 数据结构说明

### 职位数据结构
```typescript
interface Position {
  id: number
  name: string                    // 职位名称
  department: string               // 部门
  location: string                 // 地点
  type: string                     // 类型（全职/兼职/实习）
  status: 'published' | 'draft'   // 状态
  description: string              // 职位描述
  requirements: string             // 职位要求
  salary_min: number              // 最低薪资
  salary_max: number              // 最高薪资
  created_at: string               // 创建时间
  updated_at: string               // 更新时间
}
```

### 题目数据结构
```typescript
interface Question {
  id: number
  type: 'choice' | 'blank' | 'essay'  // 题型
  title: string                        // 题目
  options?: string[]                   // 选项（选择题）
  answer: string                        // 答案
  difficulty: 'easy' | 'medium' | 'hard' // 难度
  score: number                         // 分值
  category_id: number                   // 分类ID
  tags: number[]                        // 标签ID数组
  created_at: string
  updated_at: string
}
```

### 求职申请数据结构
```typescript
interface JobApplication {
  id: number
  position_id: number
  talent_id: number
  status: 'pending' | 'reviewing' | 'interviewed' | 'rejected' | 'hired'
  resume_url: string
  interview_time?: string
  interview_location?: string
  remark?: string
  created_at: string
  updated_at: string
}
```

### 用户数据结构
```typescript
interface User {
  id: number
  username: string
  name: string
  email: string
  mobile: string
  avatar: string
  dept_id: number
  roles: number[]
  is_active: boolean
  created_at: string
  updated_at: string
}
```

## 🔄 数据流转示例

### 完整面试流程
1. **创建职位** → POST `/api/position/create/`
2. **发布职位** → PUT `/api/position/{id}/` (status: published)
3. **候选人申请** → POST `/api/job_application/`
4. **HR 筛选** → PATCH `/api/job_application/status/{id}/`
5. **安排面试** → PUT `/api/job_application/{id}/`
6. **完成面试** → PATCH `/api/job_application/{id}/`
7. **发送通知** → POST `/api/job_application/notify/{id}/`

## 🔔 WebSocket 接口（如支持）

### 实时通知
```typescript
// 连接 WebSocket
const ws = new WebSocket('wss://example.com/ws/')

// 监听消息
ws.onmessage = (event) => {
  const data = JSON.parse(event.data)
  console.log('收到通知:', data)
}

// 订阅频道
ws.send(JSON.stringify({
  action: 'subscribe',
  channel: 'job_application',
  user_id: currentUserId
}))
```

## 📝 错误处理最佳实践

### 统一错误处理
```typescript
import { ElMessage } from 'element-plus'

try {
  const res = await request({
    url: '/api/some-endpoint/',
    method: 'post',
    data: formData
  })
  
  if (res.code === 2000) {
    ElMessage.success(res.message || '操作成功')
  } else {
    ElMessage.error(res.message || '操作失败')
  }
} catch (error) {
  console.error('请求错误:', error)
  ElMessage.error('网络错误，请稍后重试')
}
```

### 处理特定错误码
```typescript
function handleApiError(error: any) {
  switch (error.response?.status) {
    case 400:
      ElMessage.error('参数错误')
      break
    case 401:
      ElMessage.error('登录已过期，请重新登录')
      // 跳转到登录页
      router.push('/login')
      break
    case 403:
      ElMessage.error('权限不足')
      break
    case 404:
      ElMessage.error('资源不存在')
      break
    case 500:
      ElMessage.error('服务器错误')
      break
    default:
      ElMessage.error('未知错误')
  }
}
```

---

**注意**：本接口文档基于当前项目结构编写，实际接口路径和数据格式可能因后端实现而有所不同。建议查看后端 API 文档获取准确信息。

**API 测试工具推荐**：
- Postman
- Insomnia
- HTTPie
- Chrome DevTools Network 面板

