cykj/hzdyjs

0 Fork 0

Files

T

zlwu 94f07a059b 提交

2025-07-26 17:54:01 +08:00

18 KiB

Raw Blame History

招生迎新管理API接口文档

📋 文档信息

项目	信息
项目名称	校园管理系统 - 招生迎新模块
API模块	招生信息填报与录取管理
文档版本	V1.0.0
创建时间	2025-01-15
基础路径	`/api/zsjy`

🎯 API概述

模块说明

招生迎新管理系统提供完整的学生报名、审核、录取流程API接口，支持移动端报名和Web端管理功能。

技术规范

认证方式: Bearer Token (Sa-Token)
数据格式: JSON
响应格式: 统一使用R类型或TableDataInfo分页格式
权限控制: 基于角色的权限管理(RBAC)

权限角色

学生: 填写报名信息，查看报名状态
招生老师A: 审核报名信息
招生老师B: 录取处理
招就部门领导: 最终确认
学生处管理员: 查看录取结果

📊 数据模型

报名信息VO (EnrollmentInfoVo)

public class EnrollmentInfoVo {
    private Long id;                    // 主键ID
    private String name;                // 姓名
    private String idCard;              // 身份证号
    private String gender;              // 性别（0-男 1-女）
    private Boolean isBoarding;         // 是否住校
    private Date birthDate;             // 出生日期
    private String phone1;              // 联系手机号码1
    private String phone2;              // 联系手机号码2
    private String nation;              // 民族
    private String homeAddress;         // 家庭地址
    private String middleSchool;        // 初中毕业学校
    private String examNumber;          // 准考证号码
    private String examRegion;          // 参加中考地区
    private Integer totalScoreFull;     // 当地中考满分
    private Integer totalScore;         // 考生中考成绩
    private BigDecimal chineseScore;    // 语文成绩
    private BigDecimal mathScore;       // 数学成绩
    private BigDecimal englishScore;    // 英语成绩
    private BigDecimal scienceScore;    // 科学成绩
    private BigDecimal socialScore;     // 社会成绩
    private BigDecimal peScore;         // 体育成绩
    private String appliedMajor;        // 报考专业
    private String majorCode;           // 专业代码
    private String uniformSize;         // 校服尺码
    private String healthStatus;        // 健康情况
    private String specialties;         // 特长
    private String awards;              // 奖惩情况
    private String enrollmentStatus;    // 报名状态
    private Date applicationTime;       // 报名时间
    private String remark;              // 备注
}

录取流程VO (EnrollmentProcessVo)

public class EnrollmentProcessVo {
    private Long id;                        // 主键ID
    private Long enrollmentId;              // 报名信息ID
    private String studentName;             // 学生姓名
    private String idCard;                  // 身份证号
    private String currentStatus;           // 当前状态
    private String currentHandlerName;      // 当前处理人
    
    // 信息审核
    private String infoAuditStatus;         // 信息审核状态
    private String infoAuditUserName;       // 信息审核人
    private Date infoAuditTime;             // 信息审核时间
    private String infoAuditOpinion;        // 信息审核意见
    
    // 录取处理
    private String admissionStatus;         // 录取处理状态
    private String admissionUserName;       // 录取处理人
    private Date admissionTime;             // 录取处理时间
    private String paymentStatus;           // 缴费状态
    private Date paymentConfirmTime;        // 缴费确认时间
    private String noticeNumber;            // 录取通知书号码
    private String admissionOpinion;        // 录取处理意见
    
    // 最终确认
    private String finalAuditStatus;        // 最终审核状态
    private String finalAuditUserName;      // 最终审核人
    private Date finalAuditTime;            // 最终审核时间
    private String finalAuditOpinion;       // 最终审核意见
    
    private Boolean isCompleted;            // 是否完成
    private Date completionTime;            // 完成时间
}

📱 移动端API接口

1. 学生报名相关接口

1.1 获取报名表单配置

GET /api/zsjy/mobile/enrollment/form-config

接口说明: 获取报名表单的配置信息，包括专业列表、校服尺码等选项

请求参数: 无

响应数据:

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "majors": [
      {
        "code": "DQZD001",
        "name": "电气自动化设备安装与维修",
        "type": "高级工",
        "department": "机械工程系"
      }
    ],
    "uniformSizes": ["150/84A", "155/86A", "160/88A"],
    "nations": ["汉族", "回族", "维吾尔族"],
    "regions": ["杭州市", "宁波市", "温州市"]
  }
}

1.2 提交报名信息

POST /api/zsjy/mobile/enrollment/submit

接口说明: 学生提交报名信息

请求参数:

{
  "name": "张三",
  "idCard": "330101200501010001",
  "gender": "M",
  "isBoarding": true,
  "birthDate": "2005-01-01",
  "phone1": "13800138000",
  "phone2": "13900139000",
  "nation": "汉族",
  "homeAddress": "浙江省杭州市西湖区",
  "middleSchool": "杭州市第一中学",
  "examNumber": "2024001001",
  "examRegion": "杭州市",
  "totalScoreFull": 600,
  "totalScore": 520,
  "chineseScore": 95.5,
  "mathScore": 88.0,
  "englishScore": 92.5,
  "scienceScore": 85.0,
  "socialScore": 90.0,
  "peScore": 45.0,
  "appliedMajor": "电气自动化设备安装与维修",
  "uniformSize": "170/92A",
  "healthStatus": "身体健康，无重大疾病史",
  "specialties": "篮球、计算机编程",
  "awards": "三好学生、优秀班干部"
}

响应数据:

{
  "code": 200,
  "msg": "报名提交成功",
  "data": {
    "enrollmentId": 1001,
    "applicationNumber": "ZS20250115001",
    "status": "0",
    "applicationTime": "2025-01-15 10:30:00"
  }
}

1.3 查询报名状态

GET /api/zsjy/mobile/enrollment/status

接口说明: 学生查询自己的报名状态和进度

请求参数:

idCard (string): 身份证号

响应数据:

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "enrollmentId": 1001,
    "studentName": "张三",
    "idCard": "330101200501010001",
    "appliedMajor": "电气自动化设备安装与维修",
    "currentStatus": "1",
    "currentStatusName": "信息审核中",
    "applicationTime": "2025-01-15 10:30:00",
    "processSteps": [
      {
        "step": 1,
        "name": "信息审核",
        "status": "processing",
        "handler": "李老师",
        "time": null
      },
      {
        "step": 2,
        "name": "录取处理",
        "status": "pending",
        "handler": "王老师",
        "time": null
      }
    ]
  }
}

🖥️ Web端管理API接口

2. 报名信息管理

2.1 分页查询报名信息

GET /api/zsjy/enrollment/list

接口说明: 分页查询报名信息列表，支持多条件筛选

权限要求: zsjy:enrollment:list

请求参数:

pageNum (int): 页码，默认1
pageSize (int): 每页大小，默认10
name (string): 学生姓名（模糊查询）
idCard (string): 身份证号
appliedMajor (string): 报考专业
enrollmentStatus (string): 报名状态
applicationTimeStart (string): 报名开始时间
applicationTimeEnd (string): 报名结束时间

响应数据:

{
  "code": 200,
  "msg": "查询成功",
  "rows": [
    {
      "id": 1001,
      "name": "张三",
      "idCard": "330101200501010001",
      "gender": "M",
      "phone1": "13800138000",
      "appliedMajor": "电气自动化设备安装与维修",
      "enrollmentStatus": "1",
      "enrollmentStatusName": "信息审核中",
      "applicationTime": "2025-01-15 10:30:00",
      "totalScore": 520
    }
  ],
  "total": 1
}

2.2 查询报名详情

GET /api/zsjy/enrollment/{id}

接口说明: 根据ID查询报名详细信息

权限要求: zsjy:enrollment:query

路径参数:

id (long): 报名信息ID

响应数据:

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": 1001,
    "name": "张三",
    "idCard": "330101200501010001",
    "gender": "M",
    "birthDate": "2005-01-01",
    "phone1": "13800138000",
    "appliedMajor": "电气自动化设备安装与维修",
    "totalScore": 520,
    "chineseScore": 95.5,
    "mathScore": 88.0,
    "enrollmentStatus": "1",
    "applicationTime": "2025-01-15 10:30:00"
  }
}

2.3 修改报名信息

PUT /api/zsjy/enrollment/{id}

接口说明: 修改报名信息（仅A老师有权限）

权限要求: zsjy:enrollment:edit

请求参数: EnrollmentInfoBo对象

响应数据:

{
  "code": 200,
  "msg": "修改成功",
  "data": null
}

3. 信息审核接口（A老师）

3.1 获取待审核列表

GET /api/zsjy/audit/pending-list

接口说明: 获取待信息审核的报名列表

权限要求: zsjy:audit:info

请求参数:

pageNum (int): 页码
pageSize (int): 每页大小
name (string): 学生姓名（可选）
appliedMajor (string): 报考专业（可选）

响应数据:

{
  "code": 200,
  "msg": "查询成功",
  "rows": [
    {
      "id": 1001,
      "name": "张三",
      "idCard": "330101200501010001",
      "appliedMajor": "电气自动化设备安装与维修",
      "applicationTime": "2025-01-15 10:30:00",
      "totalScore": 520,
      "enrollmentStatus": "0"
    }
  ],
  "total": 1
}

3.2 信息审核通过

POST /api/zsjy/audit/info/approve

接口说明: A老师审核通过报名信息

权限要求: zsjy:audit:info

请求参数:

{
  "enrollmentId": 1001,
  "auditOpinion": "信息完整，审核通过"
}

响应数据:

{
  "code": 200,
  "msg": "审核通过成功",
  "data": null
}

3.3 信息审核驳回

POST /api/zsjy/audit/info/reject

接口说明: A老师驳回报名信息

权限要求: zsjy:audit:info

请求参数:

{
  "enrollmentId": 1001,
  "auditOpinion": "身份证号码格式有误，请重新填写"
}

响应数据:

{
  "code": 200,
  "msg": "审核驳回成功",
  "data": null
}

4. 录取处理接口（B老师）

4.1 获取录取处理列表

GET /api/zsjy/admission/pending-list

接口说明: 获取通过信息审核的学生列表

权限要求: zsjy:admission:process

响应数据:

{
  "code": 200,
  "msg": "查询成功",
  "rows": [
    {
      "id": 1001,
      "name": "张三",
      "idCard": "330101200501010001",
      "appliedMajor": "电气自动化设备安装与维修",
      "infoAuditTime": "2025-01-15 14:30:00",
      "paymentStatus": "0",
      "noticeNumber": null
    }
  ],
  "total": 1
}

4.2 录取处理

POST /api/zsjy/admission/process

接口说明: B老师处理录取信息

权限要求: zsjy:admission:process

请求参数:

{
  "enrollmentId": 1001,
  "paymentStatus": "1",
  "paymentConfirmTime": "2025-01-15 16:00:00",
  "noticeNumber": "ZS2025001001",
  "admissionOpinion": "缴费确认完成，录取通知书号码已分配"
}

响应数据:

{
  "code": 200,
  "msg": "录取处理成功",
  "data": null
}

5. 最终确认接口（部门领导）

5.1 获取待确认列表

GET /api/zsjy/final/pending-list

接口说明: 获取待最终确认的录取列表

权限要求: zsjy:final:audit

响应数据:

{
  "code": 200,
  "msg": "查询成功",
  "rows": [
    {
      "id": 1001,
      "name": "张三",
      "appliedMajor": "电气自动化设备安装与维修",
      "paymentStatus": "1",
      "noticeNumber": "ZS2025001001",
      "admissionTime": "2025-01-15 16:00:00"
    }
  ],
  "total": 1
}

5.2 最终确认

POST /api/zsjy/final/confirm

接口说明: 部门领导最终确认录取

权限要求: zsjy:final:audit

请求参数:

{
  "enrollmentIds": [1001, 1002, 1003],
  "finalAuditOpinion": "录取信息核实无误，确认录取"
}

响应数据:

{
  "code": 200,
  "msg": "最终确认成功",
  "data": {
    "successCount": 3,
    "failCount": 0
  }
}

6. 统计分析接口

6.1 招生数据统计

GET /api/zsjy/statistics/overview

接口说明: 获取招生数据统计概览

权限要求: zsjy:statistics:view

请求参数:

startDate (string): 开始日期
endDate (string): 结束日期

响应数据:

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "totalApplications": 1250,      // 总报名数
    "maleCount": 680,               // 男生数量
    "femaleCount": 570,             // 女生数量
    "admissionCount": 1100,         // 录取数量
    "paymentCount": 980,            // 缴费数量
    "completionCount": 950,         // 完成数量
    "admissionRate": 88.0,          // 录取率
    "paymentRate": 89.1,            // 缴费率
    "completionRate": 96.9          // 完成率
  }
}

6.2 专业统计

GET /api/zsjy/statistics/by-major

接口说明: 按专业统计招生数据

权限要求: zsjy:statistics:view

响应数据:

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "majorName": "电气自动化设备安装与维修",
      "applicationCount": 85,
      "maleCount": 60,
      "femaleCount": 25,
      "admissionCount": 75,
      "completionCount": 70,
      "admissionRate": 88.2
    }
  ]
}

6.3 地域统计

GET /api/zsjy/statistics/by-region

接口说明: 按地域统计生源分布

权限要求: zsjy:statistics:view

响应数据:

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "region": "杭州市",
      "applicationCount": 450,
      "admissionCount": 380,
      "percentage": 36.0
    }
  ]
}

6.4 分数段统计

GET /api/zsjy/statistics/by-score

接口说明: 按分数段统计学生分布

权限要求: zsjy:statistics:view

响应数据:

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "scoreRange": "500-550",
      "count": 280,
      "percentage": 22.4,
      "admissionCount": 250,
      "admissionRate": 89.3
    }
  ]
}

7. 数据导出接口

7.1 导出报名信息

POST /api/zsjy/export/enrollment

接口说明: 导出报名信息Excel文件

权限要求: zsjy:enrollment:export

请求参数:

{
  "enrollmentStatus": "4",
  "appliedMajor": "电气自动化设备安装与维修",
  "startDate": "2025-01-01",
  "endDate": "2025-01-31"
}

响应: Excel文件下载

7.2 导出录取名单

POST /api/zsjy/export/admission-list

接口说明: 导出最终录取名单

权限要求: zsjy:admission:export

请求参数:

{
  "majorCode": "DQZD001",
  "completionStatus": true
}

响应: Excel文件下载

🔐 权限配置

权限编码规范

zsjy:enrollment:list      # 查看报名列表
zsjy:enrollment:query     # 查看报名详情
zsjy:enrollment:add       # 新增报名信息
zsjy:enrollment:edit      # 修改报名信息
zsjy:enrollment:remove    # 删除报名信息
zsjy:enrollment:export    # 导出报名信息

zsjy:audit:info           # 信息审核权限
zsjy:admission:process    # 录取处理权限
zsjy:final:audit          # 最终确认权限

zsjy:statistics:view      # 查看统计数据
zsjy:statistics:export    # 导出统计数据

角色权限配置

-- 招生老师A角色
INSERT INTO sys_role_menu VALUES (role_id, menu_id) -- 信息审核菜单

-- 招生老师B角色  
INSERT INTO sys_role_menu VALUES (role_id, menu_id) -- 录取处理菜单

-- 招就部门领导角色
INSERT INTO sys_role_menu VALUES (role_id, menu_id) -- 最终确认菜单

-- 学生处管理员角色
INSERT INTO sys_role_menu VALUES (role_id, menu_id) -- 录取结果查看菜单

🧪 接口测试

测试用例

1. 报名流程测试

# 1. 提交报名
curl -X POST http://localhost:8080/api/zsjy/mobile/enrollment/submit \
  -H "Content-Type: application/json" \
  -d '{"name":"测试学生","idCard":"330101200501010001",...}'

# 2. 查询状态
curl -X GET "http://localhost:8080/api/zsjy/mobile/enrollment/status?idCard=330101200501010001"

# 3. 信息审核
curl -X POST http://localhost:8080/api/zsjy/audit/info/approve \
  -H "Authorization: Bearer token" \
  -d '{"enrollmentId":1001,"auditOpinion":"审核通过"}'

2. 权限测试

# 测试无权限访问
curl -X GET http://localhost:8080/api/zsjy/enrollment/list
# 预期返回: 401 Unauthorized

# 测试有权限访问
curl -X GET http://localhost:8080/api/zsjy/enrollment/list \
  -H "Authorization: Bearer valid_token"
# 预期返回: 200 OK

📝 接口变更记录

版本	日期	变更内容	变更人
V1.0.0	2025-01-15	初始版本，包含完整的招生迎新API接口	技术团队

📋 注意事项

数据验证: 所有接口都需要进行参数验证，特别是身份证号、手机号等格式验证
状态控制: 严格控制状态流转，防止越权操作
并发控制: 审核操作需要考虑并发情况，防止重复审核
日志记录: 重要操作需要记录操作日志，便于追溯
性能优化: 列表查询需要合理使用索引，避免全表扫描
安全防护: 敏感信息需要脱敏处理，防止信息泄露

18 KiB Raw Blame History

招生迎新管理API接口文档

📋 文档信息

🎯 API概述

模块说明

技术规范

权限角色

📊 数据模型

报名信息VO (EnrollmentInfoVo)

录取流程VO (EnrollmentProcessVo)

📱 移动端API接口

1. 学生报名相关接口

1.1 获取报名表单配置

1.2 提交报名信息

1.3 查询报名状态

🖥️ Web端管理API接口

2. 报名信息管理

2.1 分页查询报名信息

2.2 查询报名详情

2.3 修改报名信息

3. 信息审核接口（A老师）

3.1 获取待审核列表

3.2 信息审核通过

3.3 信息审核驳回

4. 录取处理接口（B老师）

4.1 获取录取处理列表

4.2 录取处理

5. 最终确认接口（部门领导）

5.1 获取待确认列表

5.2 最终确认

6. 统计分析接口

6.1 招生数据统计

6.2 专业统计

6.3 地域统计

6.4 分数段统计

7. 数据导出接口

7.1 导出报名信息

7.2 导出录取名单

🔐 权限配置

权限编码规范

角色权限配置

🧪 接口测试

测试用例

1. 报名流程测试

2. 权限测试

📝 接口变更记录

📋 注意事项

18 KiB

Raw Blame History