# 勤工俭学岗位管理API文档 ## 📋 文档信息 | 项目 | 信息 | |------|------| | **文档名称** | 勤工俭学岗位管理API文档 | | **模块名称** | 勤工俭学岗位管理 (WorkStudyPosition) | | **文档版本** | v1.0 | | **创建日期** | 2025-01-03 | | **最后更新** | 2025-01-03 | | **开发状态** | ✅ 前端完成 | --- ## 🎯 模块概述 勤工俭学岗位管理模块提供完整的岗位发布、管理、审核功能,支持二级学院和学生处的分级管理机制。 ### 核心功能 - 📝 岗位信息管理(CRUD) - 🎯 发布范围控制(本学院/全校) - 📊 岗位状态管理 - 📈 统计数据展示 - 🔄 岗位状态流转 --- ## 🗄️ 数据库设计 ### 表结构:jcbt_work_study_position | 字段名 | 类型 | 长度 | 必填 | 说明 | |--------|------|------|------|------| | id | bigint | 20 | ✅ | 主键ID(雪花ID) | | position_name | varchar | 100 | ✅ | 岗位名称 | | position_scope | varchar | 20 | ✅ | 发布范围(COLLEGE/UNIVERSITY) | | required_count | int | - | ✅ | 需求人数 | | work_time | varchar | 200 | ✅ | 工作时间 | | start_date | date | - | ✅ | 岗位有效期开始 | | end_date | date | - | ✅ | 岗位有效期结束 | | position_requirements | text | - | ✅ | 岗位要求 | | salary_info | varchar | 200 | ✅ | 薪资情况 | | contact_teacher | varchar | 50 | ✅ | 联系老师 | | contact_phone | varchar | 20 | ✅ | 联系电话 | | college_id | bigint | 20 | ✅ | 发布学院ID | | college_name | varchar | 100 | ✅ | 发布学院名称 | | status | varchar | 20 | ✅ | 岗位状态 | | current_count | int | - | ✅ | 当前申请通过人数 | | create_by | bigint | 20 | ✅ | 创建者 | | create_time | datetime | - | ✅ | 创建时间 | | update_by | bigint | 20 | ✅ | 更新者 | | update_time | datetime | - | ✅ | 更新时间 | | deleted | tinyint | 1 | ✅ | 逻辑删除标记 | | tenant_id | varchar | 20 | ✅ | 租户ID | --- ## 📡 API接口设计 ### 基础信息 - **模块前缀**: `/jcbt/workStudyPosition` - **认证方式**: Bearer Token - **数据格式**: JSON - **字符编码**: UTF-8 ### 接口列表 #### 1. 查询岗位列表 ```http GET /jcbt/workStudyPosition/list ``` **请求参数**: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | pageNum | int | ❌ | 页码(默认1) | | pageSize | int | ❌ | 每页数量(默认10) | | positionName | string | ❌ | 岗位名称(模糊查询) | | positionScope | string | ❌ | 发布范围 | | contactTeacher | string | ❌ | 联系老师 | | status | string | ❌ | 岗位状态 | | createTime | array | ❌ | 创建时间范围 | | validPeriod | array | ❌ | 有效期范围 | **响应示例**: ```json { "code": 200, "msg": "查询成功", "rows": [ { "id": "1742012345678901234", "positionName": "图书馆管理助理", "positionScope": "UNIVERSITY", "positionScopeName": "全校", "requiredCount": 5, "workTime": "周一至周五 14:00-17:00", "startDate": "2025-01-03", "endDate": "2025-06-30", "positionRequirements": "责任心强,有良好的沟通能力", "salaryInfo": "20元/小时,按月发放", "contactTeacher": "张老师", "contactPhone": "13812345678", "collegeId": 1, "collegeName": "图书馆", "status": "RECRUITING", "statusName": "招录中", "currentCount": 2, "createTime": "2025-01-03 10:00:00", "updateTime": "2025-01-03 10:00:00" } ], "total": 1 } ``` #### 2. 查询岗位详细信息 ```http GET /jcbt/workStudyPosition/{id} ``` **路径参数**: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | id | long | ✅ | 岗位ID | **响应示例**: ```json { "code": 200, "msg": "查询成功", "data": { "id": "1742012345678901234", "positionName": "图书馆管理助理", // ... 其他字段同列表查询 } } ``` #### 3. 新增岗位 ```http POST /jcbt/workStudyPosition ``` **请求体**: ```json { "positionName": "图书馆管理助理", "positionScope": "UNIVERSITY", "requiredCount": 5, "workTime": "周一至周五 14:00-17:00", "startDate": "2025-01-03", "endDate": "2025-06-30", "positionRequirements": "责任心强,有良好的沟通能力", "salaryInfo": "20元/小时,按月发放", "contactTeacher": "张老师", "contactPhone": "13812345678" } ``` **响应示例**: ```json { "code": 200, "msg": "新增成功" } ``` #### 4. 修改岗位 ```http PUT /jcbt/workStudyPosition ``` **请求体**: ```json { "id": "1742012345678901234", "positionName": "图书馆管理助理", // ... 其他字段 } ``` #### 5. 删除岗位 ```http DELETE /jcbt/workStudyPosition/{id} ``` #### 6. 获取统计数据 ```http GET /jcbt/workStudyPosition/statistics ``` **响应示例**: ```json { "code": 200, "msg": "查询成功", "data": { "totalCount": 10, "statusCount": { "DRAFT": 2, "PUBLISHED": 1, "RECRUITING": 5, "FULL": 1, "EXPIRED": 1, "SUSPENDED": 0, "CANCELLED": 0 }, "scopeCount": { "COLLEGE": 6, "UNIVERSITY": 4 } } } ``` #### 7. 岗位状态操作 ##### 发布岗位 ```http PUT /jcbt/workStudyPosition/publish/{id} ``` ##### 暂停招录 ```http PUT /jcbt/workStudyPosition/suspend/{id} ``` ##### 恢复招录 ```http PUT /jcbt/workStudyPosition/resume/{id} ``` ##### 取消岗位 ```http PUT /jcbt/workStudyPosition/cancel/{id} ``` #### 8. 导出岗位数据 ```http POST /jcbt/workStudyPosition/export ``` --- ## 🎨 前端实现 ### 页面文件结构 ``` web/src/views/jcbt/workstudy/Position/ ├── index.vue # 岗位列表主页面 ├── form.vue # 岗位表单组件 └── detail.vue # 岗位详情组件 web/src/api/jcbt/ └── workStudyPosition.ts # API接口定义 ``` ### 关键功能组件 #### 1. 统计卡片 - 📊 岗位总数统计 - ✅ 招录中岗位数量 - ⏰ 已发布岗位数量 - 📝 草稿岗位数量 #### 2. 搜索筛选 - 🔍 岗位名称模糊搜索 - 📍 发布范围筛选 - 👨‍🏫 联系老师筛选 - 📊 岗位状态筛选 - 📅 创建时间范围 - 📅 有效期范围 #### 3. 操作功能 - ➕ 新增岗位 - ✏️ 编辑岗位 - 👁️ 查看详情 - 🗑️ 删除岗位 - 📤 发布岗位 - ⏸️ 暂停/恢复招录 - ❌ 取消岗位 - 📊 数据导出 ### 状态管理 #### 岗位状态枚举 ```typescript enum PositionStatus { DRAFT = 'DRAFT', // 草稿 PUBLISHED = 'PUBLISHED', // 已发布 RECRUITING = 'RECRUITING', // 招录中 FULL = 'FULL', // 已满员 EXPIRED = 'EXPIRED', // 已过期 SUSPENDED = 'SUSPENDED', // 已暂停 CANCELLED = 'CANCELLED' // 已取消 } ``` #### 发布范围枚举 ```typescript enum PositionScope { COLLEGE = 'COLLEGE', // 本学院 UNIVERSITY = 'UNIVERSITY' // 全校 } ``` --- ## 🔒 权限控制 ### 接口权限 | 功能 | 权限标识 | 说明 | |------|----------|------| | 查询列表 | `jcbt:workStudyPosition:list` | 查看岗位列表 | | 查询详情 | `jcbt:workStudyPosition:query` | 查看岗位详情 | | 新增岗位 | `jcbt:workStudyPosition:add` | 创建新岗位 | | 修改岗位 | `jcbt:workStudyPosition:edit` | 编辑岗位信息 | | 删除岗位 | `jcbt:workStudyPosition:remove` | 删除岗位 | | 发布岗位 | `jcbt:workStudyPosition:publish` | 发布岗位 | | 暂停招录 | `jcbt:workStudyPosition:suspend` | 暂停岗位招录 | | 恢复招录 | `jcbt:workStudyPosition:resume` | 恢复岗位招录 | | 取消岗位 | `jcbt:workStudyPosition:cancel` | 取消岗位 | | 导出数据 | `jcbt:workStudyPosition:export` | 导出岗位数据 | ### 数据权限 - **学院管理员**: 只能管理本学院发布的岗位 - **学生处管理员**: 可以管理全校所有岗位 - **系统管理员**: 拥有所有权限 --- ## 🔄 状态流转 ### 岗位状态流转图 ``` 草稿(DRAFT) ↓ 发布 已发布(PUBLISHED) ↓ 开始招录 招录中(RECRUITING) ↓ ↓ ↓ 满员(FULL) | 暂停(SUSPENDED) | 过期(EXPIRED) ↓ ↓ ↓ 取消(CANCELLED) ←← 可从任意状态取消 ``` ### 状态变更规则 1. **草稿 → 已发布**: 手动发布操作 2. **已发布 → 招录中**: 自动触发(到达开始时间) 3. **招录中 → 已满员**: 自动触发(达到需求人数) 4. **招录中 → 已过期**: 自动触发(超过结束时间) 5. **招录中 → 已暂停**: 手动暂停操作 6. **已暂停 → 招录中**: 手动恢复操作 7. **任意状态 → 已取消**: 手动取消操作 --- ## 🧪 测试用例 ### 基础功能测试 - [ ] 岗位列表查询 - [ ] 岗位详情查询 - [ ] 岗位新增功能 - [ ] 岗位修改功能 - [ ] 岗位删除功能 - [ ] 统计数据查询 ### 状态管理测试 - [ ] 岗位发布功能 - [ ] 招录暂停/恢复 - [ ] 岗位取消功能 - [ ] 状态自动更新 ### 权限控制测试 - [ ] 学院管理员权限 - [ ] 学生处管理员权限 - [ ] 数据权限隔离 ### 边界条件测试 - [ ] 参数校验 - [ ] 数据格式验证 - [ ] 并发操作处理 --- ## 📈 性能优化 ### 数据库优化 - **索引设计**: - `idx_college_id` (college_id) - `idx_status` (status) - `idx_create_time` (create_time) - `idx_valid_period` (start_date, end_date) ### 缓存策略 - **字典数据**: 学院列表、状态选项 - **统计数据**: 岗位统计信息(5分钟缓存) - **热点数据**: 招录中的岗位列表 ### 前端优化 - **懒加载**: 表格数据分页加载 - **防抖搜索**: 搜索输入防抖处理 - **缓存**: 页面状态缓存 --- ## 🐛 已知问题 ### 当前限制 1. 暂无批量操作功能 2. 暂不支持岗位复制功能 3. 暂不支持岗位申请功能(后续开发) ### 待优化项 1. 增加岗位模板功能 2. 支持富文本岗位要求编辑 3. 增加岗位申请统计图表 --- ## 📚 相关文档 - [勤工俭学产品需求分析书](../../需求文档/奖惩补贴需求/勤工俭学产品需求分析书.md) - [后端开发规范](.cursor/cursorrules-backend.md) - [前端开发规范](.cursor/cursorrules-frontend.md) - [数据库设计规范](../设计文档/database/mysql-database-standard.md) --- ## ✅ 开发状态 ### 已完成功能 - ✅ 数据库表设计 - ✅ 后端API接口 - ✅ 前端页面组件 - ✅ 权限控制集成 - ✅ 基础功能测试 ### 待开发功能 - ⏳ 岗位申请模块 - ⏳ 申请审核流程 - ⏳ 移动端适配 - ⏳ 数据导入功能 --- **📝 文档状态**: ✅ 完成 **📅 最后更新**: 2025-01-03 **👥 维护团队**: 开发团队 **�� 更新频率**: 根据功能迭代及时更新