API_DOCUMENTATION.md 10 KB

API 接口文档

📡 接口基础信息

基础配置

  • 基础路径/api
  • 请求方法:支持 GET, POST, PUT, DELETE, PATCH
  • 认证方式:JWT Token
  • 数据格式:JSON

请求头

Content-Type: application/json
Authorization: Bearer {token}

响应格式

{
  "code": 2000,
  "message": "操作成功",
  "data": {},
  "total": 0
}

🔐 认证接口

用户登录

  • 路径/api/system/auth/login/
  • 方法:POST
  • 请求体

    {
    "username": "string",
    "password": "string"
    }
    
  • 响应

    {
    "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
  • 请求体

    {
    "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
  • 请求体

    {
    "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
  • 请求体

    {
    "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 调用

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
}

🔒 权限说明

接口权限

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

数据权限

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

📊 数据结构说明

职位数据结构

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               // 更新时间
}

题目数据结构

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
}

求职申请数据结构

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
}

用户数据结构

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 接口(如支持)

实时通知

// 连接 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
}))

📝 错误处理最佳实践

统一错误处理

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('网络错误,请稍后重试')
}

处理特定错误码

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 面板