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