cykj/hzdyjs
1
0 Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
1e6dcb164c76b6ac029d8bed1074d91591662f3b
hzdyjs/docs/开发文档/API/奖学金名额分配管理API.md
T
wuzhen 9b7a6e2103 wuzhen update
2025-08-07 18:40:25 +08:00

14 KiB
Raw Blame History

奖学金名额分配管理API文档

文档版本: v1.0
创建时间: 2025-01-27
模块名称: 奖惩补贴系统 - 名额分配管理
技术栈: Spring Boot 3.4.6 + MyBatis-Plus

📋 1. 接口概览

1.1 模块说明

奖学金名额分配管理模块提供按批次进行名额分配的核心功能，支持多级分配、自动分配、名额调整等业务场景。

1.2 基础信息

  • 服务地址: http://localhost:8080
  • 接口前缀: /jcbt/scholarshipQuota
  • 认证方式: Bearer Token + Sa-Token
  • 数据格式: JSON

1.3 接口列表

序号 接口名称 请求方式 路径 权限标识
1 分页查询名额分配 GET /list jcbt:scholarshipQuota:list
2 按批次查询名额分配 GET /listByBatch/{batchId} jcbt:scholarshipQuota:list
3 按批次和类型查询 GET /listByBatchAndType jcbt:scholarshipQuota:list
4 查询名额树形结构 GET /tree jcbt:scholarshipQuota:list
5 查询名额使用统计 GET /statistics/{batchId} jcbt:scholarshipQuota:list
6 导出名额分配 POST /export jcbt:scholarshipQuota:export
7 获取详细信息 GET /{id} jcbt:scholarshipQuota:query
8 新增名额分配 POST / jcbt:scholarshipQuota:add
9 修改名额分配 PUT / jcbt:scholarshipQuota:edit
10 删除名额分配 DELETE /{ids} jcbt:scholarshipQuota:remove
11 批量分配名额 POST /batchAllocate jcbt:scholarshipQuota:add
12 调整名额分配 POST /adjust jcbt:scholarshipQuota:edit
13 锁定名额分配 PUT /lock/{id} jcbt:scholarshipQuota:edit
14 自动分配名额 POST /autoAllocate jcbt:scholarshipQuota:edit
15 复制名额分配 POST /copy jcbt:scholarshipQuota:add
16 更新名额使用 PUT /updateUsage/{id} jcbt:scholarshipQuota:edit
17 验证名额分配 POST /validate jcbt:scholarshipQuota:query

🔍 2. 查询类接口

2.1 分页查询名额分配列表

接口描述: 分页查询奖学金名额分配列表，支持多条件筛选

请求信息

GET /jcbt/scholarshipQuota/list?pageNum=1&pageSize=10&batchId=1&scholarshipTypeId=1
Content-Type: application/json
Authorization: Bearer {token}
clientid: e5cd7e4891bf95d1d19206ce24a7b32e

请求参数

{
  "pageNum": 1,           // 页码（必填）
  "pageSize": 10,         // 页大小（必填）
  "batchId": 1,           // 批次ID（可选）
  "scholarshipTypeId": 1, // 奖学金类型ID（可选）
  "allocationLevel": "COLLEGE", // 分配级别（可选）
  "targetDeptId": 101,    // 目标部门ID（可选）
  "status": "ACTIVE",     // 状态（可选）
  "isLocked": 0           // 是否锁定（可选）
}

响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "total": 25,
    "rows": [
      {
        "id": 1,
        "batchId": 1,
        "batchName": "2024-2025学年第一学期国家奖学金",
        "batchCode": "GJ202401",
        "academicYear": "2024-2025",
        "semester": 1,
        "scholarshipTypeId": 1,
        "scholarshipTypeName": "国家奖学金",
        "scholarshipLevel": "国家级",
        "allocationLevel": "COLLEGE",
        "allocationLevelName": "学院",
        "targetDeptId": 101,
        "targetDeptName": "计算机学院",
        "parentQuotaId": null,
        "parentDeptName": null,
        "totalQuota": 10,
        "usedQuota": 3,
        "reservedQuota": 1,
        "availableQuota": 6,
        "allocationRule": null,
        "allocationBasis": "按学院学生人数比例分配",
        "allocationMethod": "MANUAL",
        "allocationMethodName": "手动分配",
        "isAdjustable": 1,
        "isLocked": 0,
        "status": "ACTIVE",
        "statusName": "生效",
        "remark": "",
        "tenantId": 1,
        "createBy": 1,
        "createTime": "2025-01-27 10:00:00",
        "updateBy": 1,
        "updateTime": "2025-01-27 10:00:00"
      }
    ]
  }
}

2.2 按批次查询名额分配列表

接口描述: 查询指定批次的所有名额分配

请求信息

GET /jcbt/scholarshipQuota/listByBatch/1
Authorization: Bearer {token}
clientid: e5cd7e4891bf95d1d19206ce24a7b32e

响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "id": 1,
      "batchId": 1,
      "batchName": "2024-2025学年第一学期国家奖学金",
      "scholarshipTypeName": "国家奖学金",
      "allocationLevel": "COLLEGE",
      "targetDeptName": "计算机学院",
      "totalQuota": 10,
      "usedQuota": 3,
      "availableQuota": 6,
      "status": "ACTIVE"
    }
  ]
}

2.3 查询名额分配树形结构

接口描述: 查询指定批次和奖学金类型的名额分配层级结构

请求信息

GET /jcbt/scholarshipQuota/tree?batchId=1&scholarshipTypeId=1
Authorization: Bearer {token}
clientid: e5cd7e4891bf95d1d19206ce24a7b32e

响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "id": 1,
      "allocationLevel": "UNIVERSITY",
      "targetDeptName": "全校",
      "totalQuota": 100,
      "children": [
        {
          "id": 2,
          "allocationLevel": "COLLEGE",
          "targetDeptName": "计算机学院",
          "totalQuota": 30,
          "parentQuotaId": 1,
          "children": [
            {
              "id": 3,
              "allocationLevel": "MAJOR",
              "targetDeptName": "计算机科学与技术",
              "totalQuota": 15,
              "parentQuotaId": 2
            }
          ]
        }
      ]
    }
  ]
}

2.4 查询名额使用统计

接口描述: 查询指定批次的名额使用统计信息

请求信息

GET /jcbt/scholarshipQuota/statistics/1
Authorization: Bearer {token}
clientid: e5cd7e4891bf95d1d19206ce24a7b32e

响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "totalQuota": 100,      // 总名额
    "usedQuota": 45,        // 已使用名额
    "availableQuota": 50,   // 可用名额
    "usageRate": 0.45,      // 使用率
    "allocationCount": 15   // 分配记录数
  }
}

✏️ 3. 新增修改类接口

3.1 新增名额分配

接口描述: 创建新的奖学金名额分配记录

请求信息

POST /jcbt/scholarshipQuota
Content-Type: application/json
Authorization: Bearer {token}
clientid: e5cd7e4891bf95d1d19206ce24a7b32e

请求参数

{
  "batchId": 1,                    // 批次ID（必填）
  "scholarshipTypeId": 1,          // 奖学金类型ID（必填）
  "allocationLevel": "COLLEGE",    // 分配级别（必填）
  "targetDeptId": 101,             // 目标部门ID（必填）
  "parentQuotaId": null,           // 上级名额ID（可选）
  "totalQuota": 10,                // 总名额（必填）
  "usedQuota": 0,                  // 已使用名额（可选，默认0）
  "reservedQuota": 1,              // 预留名额（可选，默认0）
  "allocationRule": "",            // 分配规则（可选）
  "allocationBasis": "按学院学生人数比例分配", // 分配依据（可选）
  "allocationMethod": "MANUAL",    // 分配方式（可选，默认MANUAL）
  "isAdjustable": 1,              // 是否可调整（可选，默认1）
  "status": "ACTIVE",             // 状态（可选，默认ACTIVE）
  "remark": ""                    // 备注（可选）
}

响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": null
}

3.2 修改名额分配

接口描述: 修改已存在的名额分配记录

请求信息

PUT /jcbt/scholarshipQuota
Content-Type: application/json
Authorization: Bearer {token}
clientid: e5cd7e4891bf95d1d19206ce24a7b32e

请求参数

{
  "id": 1,                        // 主键ID（必填）
  "batchId": 1,                   // 批次ID（必填）
  "scholarshipTypeId": 1,         // 奖学金类型ID（必填）
  "allocationLevel": "COLLEGE",   // 分配级别（必填）
  "targetDeptId": 101,            // 目标部门ID（必填）
  "totalQuota": 12,               // 总名额（必填）
  "usedQuota": 3,                 // 已使用名额
  "reservedQuota": 1,             // 预留名额
  "allocationBasis": "调整后的分配依据",
  "remark": "名额调整"
}

3.3 批量分配名额

接口描述: 为指定批次和奖学金类型批量创建名额分配

请求信息

POST /jcbt/scholarshipQuota/batchAllocate?batchId=1&scholarshipTypeId=1
Content-Type: application/json
Authorization: Bearer {token}
clientid: e5cd7e4891bf95d1d19206ce24a7b32e

请求参数

[
  {
    "allocationLevel": "COLLEGE",
    "targetDeptId": 101,
    "totalQuota": 10,
    "allocationBasis": "计算机学院分配"
  },
  {
    "allocationLevel": "COLLEGE", 
    "targetDeptId": 102,
    "totalQuota": 8,
    "allocationBasis": "软件学院分配"
  }
]

🔧 4. 业务操作类接口

4.1 调整名额分配

接口描述: 在两个名额分配之间调整名额数量

请求信息

POST /jcbt/scholarshipQuota/adjust?fromQuotaId=1&toQuotaId=2&adjustAmount=2&reason=学院需求调整
Authorization: Bearer {token}
clientid: e5cd7e4891bf95d1d19206ce24a7b32e

参数说明

  • fromQuotaId: 源名额分配ID
  • toQuotaId: 目标名额分配ID
  • adjustAmount: 调整数量（正整数）
  • reason: 调整原因

4.2 锁定/解锁名额分配

接口描述: 锁定或解锁名额分配，锁定后不允许修改

请求信息

PUT /jcbt/scholarshipQuota/lock/1?isLocked=1
Authorization: Bearer {token}
clientid: e5cd7e4891bf95d1d19206ce24a7b32e

参数说明

  • id: 名额分配ID
  • isLocked: 是否锁定（0-否，1-是）

4.3 自动分配名额

接口描述: 根据配置的规则自动分配名额

请求信息

POST /jcbt/scholarshipQuota/autoAllocate?batchId=1&scholarshipTypeId=1&allocationRule=按比例分配
Authorization: Bearer {token}
clientid: e5cd7e4891bf95d1d19206ce24a7b32e

参数说明

  • batchId: 批次ID
  • scholarshipTypeId: 奖学金类型ID
  • allocationRule: 分配规则（JSON格式或文本）

4.4 复制名额分配

接口描述: 从源批次复制名额分配到目标批次

请求信息

POST /jcbt/scholarshipQuota/copy?sourceBatchId=1&targetBatchId=2
Content-Type: application/json
Authorization: Bearer {token}
clientid: e5cd7e4891bf95d1d19206ce24a7b32e

请求参数

[1, 2, 3]  // 要复制的奖学金类型ID列表

4.5 更新名额使用情况

接口描述: 更新名额的使用数量

请求信息

PUT /jcbt/scholarshipQuota/updateUsage/1?usedChange=1
Authorization: Bearer {token}
clientid: e5cd7e4891bf95d1d19206ce24a7b32e

参数说明

  • id: 名额分配ID
  • usedChange: 使用数量变化（正数增加，负数减少）

🗑️ 5. 删除类接口

5.1 删除名额分配

接口描述: 删除指定的名额分配记录（支持批量删除）

请求信息

DELETE /jcbt/scholarshipQuota/1,2,3
Authorization: Bearer {token}
clientid: e5cd7e4891bf95d1d19206ce24a7b32e

响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": null
}

📤 6. 导出类接口

6.1 导出名额分配

接口描述: 导出名额分配数据到Excel文件

请求信息

POST /jcbt/scholarshipQuota/export
Content-Type: application/json
Authorization: Bearer {token}
clientid: e5cd7e4891bf95d1d19206ce24a7b32e

请求参数

{
  "batchId": 1,           // 批次ID（可选）
  "scholarshipTypeId": 1, // 奖学金类型ID（可选）
  "allocationLevel": "COLLEGE" // 分配级别（可选）
}

🔍 7. 工具类接口

7.1 验证名额分配

接口描述: 验证名额分配数据的有效性

请求信息

POST /jcbt/scholarshipQuota/validate
Content-Type: application/json
Authorization: Bearer {token}
clientid: e5cd7e4891bf95d1d19206ce24a7b32e

请求参数

{
  "batchId": 1,
  "scholarshipTypeId": 1,
  "allocationLevel": "COLLEGE",
  "targetDeptId": 101,
  "totalQuota": 10,
  "usedQuota": 3,
  "reservedQuota": 1
}

响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": null  // null表示验证通过，有错误信息则返回具体错误
}

📋 8. 数据字典

8.1 分配级别 (allocation_level)

  • UNIVERSITY: 全校
  • COLLEGE: 学院
  • MAJOR: 专业
  • CLASS: 班级

8.2 分配方式 (allocation_method)

  • MANUAL: 手动分配
  • AUTO: 自动分配
  • PROPORTIONAL: 按比例分配

8.3 分配状态 (status)

  • ACTIVE: 生效
  • INACTIVE: 失效
  • PENDING: 待审核

⚠️ 9. 错误处理

9.1 常见错误码

  • 400: 请求参数错误
  • 401: 未授权访问
  • 403: 权限不足
  • 404: 资源不存在
  • 500: 服务器内部错误

9.2 业务错误示例

{
  "code": 500,
  "msg": "总名额必须大于0",
  "data": null
}

{
  "code": 500,
  "msg": "该批次和奖学金类型下已存在相同部门的名额分配",
  "data": null
}

📝 10. 接口测试示例

10.1 测试环境

  • 服务地址: http://localhost:8080
  • 测试账号: admin/admin123
  • 测试工具: Postman、ApiPost

10.2 完整测试流程

  1. 登录获取Token
  2. 查询评定批次列表
  3. 创建名额分配
  4. 查询名额分配列表
  5. 修改名额分配
  6. 执行名额调整
  7. 查询使用统计
  8. 导出数据

文档维护人: 开发团队
最后更新: 2025-01-27
版本说明: 首次创建，包含完整的17个API接口

Reference in new issue View Git Blame Copy Permalink