勤工俭学岗位管理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. 查询岗位列表

GET /jcbt/workStudyPosition/list

请求参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | pageNum | int | ❌ | 页码（默认1） | | pageSize | int | ❌ | 每页数量（默认10） | | positionName | string | ❌ | 岗位名称（模糊查询） | | positionScope | string | ❌ | 发布范围 | | contactTeacher | string | ❌ | 联系老师 | | status | string | ❌ | 岗位状态 | | createTime | array | ❌ | 创建时间范围 | | validPeriod | array | ❌ | 有效期范围 |

响应示例:

{
  "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. 查询岗位详细信息

GET /jcbt/workStudyPosition/{id}

路径参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | id | long | ✅ | 岗位ID |

响应示例:

{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "id": "1742012345678901234",
    "positionName": "图书馆管理助理",
    // ... 其他字段同列表查询
  }
}

3. 新增岗位

POST /jcbt/workStudyPosition

请求体:

{
  "positionName": "图书馆管理助理",
  "positionScope": "UNIVERSITY",
  "requiredCount": 5,
  "workTime": "周一至周五 14:00-17:00",
  "startDate": "2025-01-03",
  "endDate": "2025-06-30",
  "positionRequirements": "责任心强，有良好的沟通能力",
  "salaryInfo": "20元/小时，按月发放",
  "contactTeacher": "张老师",
  "contactPhone": "13812345678"
}

响应示例:

{
  "code": 200,
  "msg": "新增成功"
}

4. 修改岗位

PUT /jcbt/workStudyPosition

请求体:

{
  "id": "1742012345678901234",
  "positionName": "图书馆管理助理",
  // ... 其他字段
}

5. 删除岗位

DELETE /jcbt/workStudyPosition/{id}

6. 获取统计数据

GET /jcbt/workStudyPosition/statistics

响应示例:

{
  "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. 岗位状态操作

发布岗位

PUT /jcbt/workStudyPosition/publish/{id}

暂停招录

PUT /jcbt/workStudyPosition/suspend/{id}

恢复招录

PUT /jcbt/workStudyPosition/resume/{id}

取消岗位

PUT /jcbt/workStudyPosition/cancel/{id}

8. 导出岗位数据

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. 操作功能

➕ 新增岗位
✏️ 编辑岗位
👁️ 查看详情
🗑️ 删除岗位
📤 发布岗位
⏸️ 暂停/恢复招录
❌ 取消岗位
📊 数据导出

状态管理

岗位状态枚举

enum PositionStatus {
  DRAFT = 'DRAFT',           // 草稿
  PUBLISHED = 'PUBLISHED',   // 已发布
  RECRUITING = 'RECRUITING', // 招录中
  FULL = 'FULL',            // 已满员
  EXPIRED = 'EXPIRED',      // 已过期
  SUSPENDED = 'SUSPENDED',  // 已暂停
  CANCELLED = 'CANCELLED'   // 已取消
}

发布范围枚举

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) ←← 可从任意状态取消

状态变更规则

草稿 → 已发布: 手动发布操作
已发布 → 招录中: 自动触发（到达开始时间）
招录中 → 已满员: 自动触发（达到需求人数）
招录中 → 已过期: 自动触发（超过结束时间）
招录中 → 已暂停: 手动暂停操作
已暂停 → 招录中: 手动恢复操作
任意状态 → 已取消: 手动取消操作

🧪 测试用例

基础功能测试

岗位列表查询
岗位详情查询
岗位新增功能
岗位修改功能
岗位删除功能
统计数据查询

状态管理测试

岗位发布功能
招录暂停/恢复
岗位取消功能
状态自动更新

权限控制测试

学院管理员权限
学生处管理员权限
数据权限隔离

边界条件测试

参数校验
数据格式验证
并发操作处理

📈 性能优化

数据库优化

索引设计:
- idx_college_id (college_id)
- idx_status (status)
- idx_create_time (create_time)
- idx_valid_period (start_date, end_date)

缓存策略

字典数据: 学院列表、状态选项
统计数据: 岗位统计信息（5分钟缓存）
热点数据: 招录中的岗位列表

前端优化

懒加载: 表格数据分页加载
防抖搜索: 搜索输入防抖处理
缓存: 页面状态缓存

🐛 已知问题

当前限制

暂无批量操作功能
暂不支持岗位复制功能
暂不支持岗位申请功能（后续开发）

待优化项

增加岗位模板功能
支持富文本岗位要求编辑
增加岗位申请统计图表

📚 相关文档

✅ 开发状态

已完成功能

✅ 数据库表设计
✅ 后端API接口
✅ 前端页面组件
✅ 权限控制集成
✅ 基础功能测试

待开发功能

⏳ 岗位申请模块
⏳ 申请审核流程
⏳ 移动端适配
⏳ 数据导入功能

📝 文档状态: ✅ 完成
📅 最后更新: 2025-01-03
👥 维护团队: 开发团队
�� 更新频率: 根据功能迭代及时更新

勤工俭学岗位管理API.md 11 KB Bezpośredni odnośnik Historia Czysty

勤工俭学岗位管理API文档

📋 文档信息

🎯 模块概述

核心功能

🗄️ 数据库设计

表结构：jcbt_work_study_position

📡 API接口设计

基础信息

接口列表

1. 查询岗位列表

2. 查询岗位详细信息

3. 新增岗位

4. 修改岗位

5. 删除岗位

6. 获取统计数据

7. 岗位状态操作

发布岗位

暂停招录

恢复招录

取消岗位

8. 导出岗位数据

🎨 前端实现

页面文件结构

关键功能组件

1. 统计卡片

2. 搜索筛选

3. 操作功能

状态管理

岗位状态枚举

发布范围枚举

🔒 权限控制

接口权限

数据权限

🔄 状态流转

岗位状态流转图

状态变更规则

🧪 测试用例

基础功能测试

状态管理测试

权限控制测试

边界条件测试

📈 性能优化

数据库优化

缓存策略

前端优化

🐛 已知问题

当前限制

待优化项

📚 相关文档

✅ 开发状态

已完成功能

待开发功能

勤工俭学岗位管理API.md 11 KB

Bezpośredni odnośnik Historia Czysty