# 招生迎新管理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) ```java 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) ```java 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 获取报名表单配置 ```http GET /api/zsjy/mobile/enrollment/form-config ``` **接口说明**: 获取报名表单的配置信息,包括专业列表、校服尺码等选项 **请求参数**: 无 **响应数据**: ```json { "code": 200, "msg": "操作成功", "data": { "majors": [ { "code": "DQZD001", "name": "电气自动化设备安装与维修", "type": "高级工", "department": "机械工程系" } ], "uniformSizes": ["150/84A", "155/86A", "160/88A"], "nations": ["汉族", "回族", "维吾尔族"], "regions": ["杭州市", "宁波市", "温州市"] } } ``` #### 1.2 提交报名信息 ```http POST /api/zsjy/mobile/enrollment/submit ``` **接口说明**: 学生提交报名信息 **请求参数**: ```json { "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": "三好学生、优秀班干部" } ``` **响应数据**: ```json { "code": 200, "msg": "报名提交成功", "data": { "enrollmentId": 1001, "applicationNumber": "ZS20250115001", "status": "0", "applicationTime": "2025-01-15 10:30:00" } } ``` #### 1.3 查询报名状态 ```http GET /api/zsjy/mobile/enrollment/status ``` **接口说明**: 学生查询自己的报名状态和进度 **请求参数**: - `idCard` (string): 身份证号 **响应数据**: ```json { "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 分页查询报名信息 ```http 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): 报名结束时间 **响应数据**: ```json { "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 查询报名详情 ```http GET /api/zsjy/enrollment/{id} ``` **接口说明**: 根据ID查询报名详细信息 **权限要求**: `zsjy:enrollment:query` **路径参数**: - `id` (long): 报名信息ID **响应数据**: ```json { "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 修改报名信息 ```http PUT /api/zsjy/enrollment/{id} ``` **接口说明**: 修改报名信息(仅A老师有权限) **权限要求**: `zsjy:enrollment:edit` **请求参数**: EnrollmentInfoBo对象 **响应数据**: ```json { "code": 200, "msg": "修改成功", "data": null } ``` ### 3. 信息审核接口(A老师) #### 3.1 获取待审核列表 ```http GET /api/zsjy/audit/pending-list ``` **接口说明**: 获取待信息审核的报名列表 **权限要求**: `zsjy:audit:info` **请求参数**: - `pageNum` (int): 页码 - `pageSize` (int): 每页大小 - `name` (string): 学生姓名(可选) - `appliedMajor` (string): 报考专业(可选) **响应数据**: ```json { "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 信息审核通过 ```http POST /api/zsjy/audit/info/approve ``` **接口说明**: A老师审核通过报名信息 **权限要求**: `zsjy:audit:info` **请求参数**: ```json { "enrollmentId": 1001, "auditOpinion": "信息完整,审核通过" } ``` **响应数据**: ```json { "code": 200, "msg": "审核通过成功", "data": null } ``` #### 3.3 信息审核驳回 ```http POST /api/zsjy/audit/info/reject ``` **接口说明**: A老师驳回报名信息 **权限要求**: `zsjy:audit:info` **请求参数**: ```json { "enrollmentId": 1001, "auditOpinion": "身份证号码格式有误,请重新填写" } ``` **响应数据**: ```json { "code": 200, "msg": "审核驳回成功", "data": null } ``` ### 4. 录取处理接口(B老师) #### 4.1 获取录取处理列表 ```http GET /api/zsjy/admission/pending-list ``` **接口说明**: 获取通过信息审核的学生列表 **权限要求**: `zsjy:admission:process` **响应数据**: ```json { "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 录取处理 ```http POST /api/zsjy/admission/process ``` **接口说明**: B老师处理录取信息 **权限要求**: `zsjy:admission:process` **请求参数**: ```json { "enrollmentId": 1001, "paymentStatus": "1", "paymentConfirmTime": "2025-01-15 16:00:00", "noticeNumber": "ZS2025001001", "admissionOpinion": "缴费确认完成,录取通知书号码已分配" } ``` **响应数据**: ```json { "code": 200, "msg": "录取处理成功", "data": null } ``` ### 5. 最终确认接口(部门领导) #### 5.1 获取待确认列表 ```http GET /api/zsjy/final/pending-list ``` **接口说明**: 获取待最终确认的录取列表 **权限要求**: `zsjy:final:audit` **响应数据**: ```json { "code": 200, "msg": "查询成功", "rows": [ { "id": 1001, "name": "张三", "appliedMajor": "电气自动化设备安装与维修", "paymentStatus": "1", "noticeNumber": "ZS2025001001", "admissionTime": "2025-01-15 16:00:00" } ], "total": 1 } ``` #### 5.2 最终确认 ```http POST /api/zsjy/final/confirm ``` **接口说明**: 部门领导最终确认录取 **权限要求**: `zsjy:final:audit` **请求参数**: ```json { "enrollmentIds": [1001, 1002, 1003], "finalAuditOpinion": "录取信息核实无误,确认录取" } ``` **响应数据**: ```json { "code": 200, "msg": "最终确认成功", "data": { "successCount": 3, "failCount": 0 } } ``` ### 6. 统计分析接口 #### 6.1 招生数据统计 ```http GET /api/zsjy/statistics/overview ``` **接口说明**: 获取招生数据统计概览 **权限要求**: `zsjy:statistics:view` **请求参数**: - `startDate` (string): 开始日期 - `endDate` (string): 结束日期 **响应数据**: ```json { "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 专业统计 ```http GET /api/zsjy/statistics/by-major ``` **接口说明**: 按专业统计招生数据 **权限要求**: `zsjy:statistics:view` **响应数据**: ```json { "code": 200, "msg": "操作成功", "data": [ { "majorName": "电气自动化设备安装与维修", "applicationCount": 85, "maleCount": 60, "femaleCount": 25, "admissionCount": 75, "completionCount": 70, "admissionRate": 88.2 } ] } ``` #### 6.3 地域统计 ```http GET /api/zsjy/statistics/by-region ``` **接口说明**: 按地域统计生源分布 **权限要求**: `zsjy:statistics:view` **响应数据**: ```json { "code": 200, "msg": "操作成功", "data": [ { "region": "杭州市", "applicationCount": 450, "admissionCount": 380, "percentage": 36.0 } ] } ``` #### 6.4 分数段统计 ```http GET /api/zsjy/statistics/by-score ``` **接口说明**: 按分数段统计学生分布 **权限要求**: `zsjy:statistics:view` **响应数据**: ```json { "code": 200, "msg": "操作成功", "data": [ { "scoreRange": "500-550", "count": 280, "percentage": 22.4, "admissionCount": 250, "admissionRate": 89.3 } ] } ``` ### 7. 数据导出接口 #### 7.1 导出报名信息 ```http POST /api/zsjy/export/enrollment ``` **接口说明**: 导出报名信息Excel文件 **权限要求**: `zsjy:enrollment:export` **请求参数**: ```json { "enrollmentStatus": "4", "appliedMajor": "电气自动化设备安装与维修", "startDate": "2025-01-01", "endDate": "2025-01-31" } ``` **响应**: Excel文件下载 #### 7.2 导出录取名单 ```http POST /api/zsjy/export/admission-list ``` **接口说明**: 导出最终录取名单 **权限要求**: `zsjy:admission:export` **请求参数**: ```json { "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 # 导出统计数据 ``` ### 角色权限配置 ```sql -- 招生老师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. 报名流程测试 ```bash # 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. 权限测试 ```bash # 测试无权限访问 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接口 | 技术团队 | ## 📋 注意事项 1. **数据验证**: 所有接口都需要进行参数验证,特别是身份证号、手机号等格式验证 2. **状态控制**: 严格控制状态流转,防止越权操作 3. **并发控制**: 审核操作需要考虑并发情况,防止重复审核 4. **日志记录**: 重要操作需要记录操作日志,便于追溯 5. **性能优化**: 列表查询需要合理使用索引,避免全表扫描 6. **安全防护**: 敏感信息需要脱敏处理,防止信息泄露