# 学员基本信息与认证管理接口文档 ## 1. 通用约定 - 基础路径由部署环境决定,以下均为相对路径。 - 请求头:`Authorization: Bearer `,兼容不带 `Bearer ` 前缀的项目历史调用方式。 - 学员接口只使用 JWT 中的当前用户,不接收 `userId`;管理端接口要求“管理员”角色。 - 普通 JSON 成功响应为 `Result`;分页响应为项目统一 `TableDataInfo`,核心字段为 `code`、`msg`、`total`、`rows`。 - 日期格式为 `yyyy-MM-dd`,日期时间格式为 `yyyy-MM-dd HH:mm:ss`。 ## 2. 学员端资料 ### 2.1 查询资料 `GET /student/certification-profile` 返回账号旧字段预填值、最新班级以及报名资料。`completed=false` 表示尚未正式提交;`editable=false` 表示账户已归档。 ```json { "code": 200, "data": { "studentId": "190001", "name": "张三", "gender": "男", "birthday": "1995-06-01", "householdType": "本市城镇", "idType": "身份证", "idCard": "310101199506011234", "highestEducation": "大专", "administrativeDistrict": "浦东新区", "personTypes": ["在职"], "homeAddress": "上海市浦东新区示例路1号", "zipCode": "200120", "phoneNumber": "13800138000", "workUnit": "示例水务公司", "currentWorkYears": 5, "socialSecurityYears": 5, "trainingOccupation": "污水处理工", "trainingLevel": "五级", "trainingCategory": "企业培训", "subsidyFlag": true, "jobYears": 5, "assessmentOccupation": "污水处理工", "assessmentLevel": "五级", "classId": 12, "className": "2026污水五级一班", "classOccupation": "污水", "classLevelName": "五级", "accountStatus": "PENDING", "completed": false, "editable": true, "submitTime": null } } ``` ### 2.2 保存资料 `PUT /student/certification-profile` 请求体不传 `studentId`、班级信息、状态和提交时间。完整示例: ```json { "name": "张三", "gender": "男", "birthday": "1995-06-01", "householdType": "本市城镇", "idType": "身份证", "idCard": "310101199506011234", "highestEducation": "大专", "major": "环境工程", "administrativeDistrict": "浦东新区", "personTypes": ["在职"], "personTypeOther": null, "homeAddress": "上海市浦东新区示例路1号", "zipCode": "200120", "phoneNumber": "13800138000", "workUnit": "示例水务公司", "unitPhone": "021-12345678", "workUnitAddress": "上海市示例路2号", "laborBookNo": "LD-001", "currentWorkYears": 5, "socialSecurityYears": 5, "previousOccupation": "污水处理工", "previousLevel": "五级", "previousCertNo": "CERT-001", "previousIssueDate": "2024-01-01", "previousIssueDept": "上海市职业技能鉴定中心", "previousLevelCertNo": null, "graduationSchool": "示例职业学院", "graduationDate": "2016-06-30", "graduationCertNo": "GRAD-001", "trainingOccupation": "污水处理工", "trainingLevel": "五级", "trainingCategory": "企业培训", "subsidyFlag": true, "jobYears": 5, "assessmentOccupation": "污水处理工", "assessmentLevel": "五级" } ``` 成功响应与查询接口的数据结构相同。首次成功提交会把 `PENDING` 更新为 `STUDYING` 并清除首次登录标记;后续编辑不会改变 `STUDYING`、`GRADUATED` 等已有状态。 字段规则:姓名、性别、出生日期、户口性质、证件类型/号码、最高学历、行政区、人员类别、地址、手机号、三个年限、培训工种/等级/类别、补贴标记、鉴定工种/等级必填。手机号为 `1` 开头的 11 位数字,邮编为空或 6 位数字,证件号码至少 15 位,年限均为 0~60,社保年限不得大于本工种工作年限。人员类别可多选,选择“其他”时 `personTypeOther` 必填。培训类别只传一个字符串。申报一级至四级时 `previousLevelCertNo` 必填。 常见业务错误会通过项目统一异常响应返回明确中文提示,例如“联系电话已被其他账户使用”“申报一级至四级必须填写上一等级职业资格证书编号”。 ## 3. 管理端认证管理 ### 3.1 范围树 `GET /certification/admin/tree?keyword=污水` 返回 `OCCUPATION → LEVEL → CLASS` 三级节点。`count` 为节点下资料已完善且未删除的有效学员人数,关键字匹配工种、等级和班级名称。 ```json {"code":200,"data":[{"nodeType":"OCCUPATION","label":"污水","value":"污水","count":30,"classId":null,"children":[{"nodeType":"LEVEL","label":"五级","value":"五级","count":30,"classId":null,"children":[{"nodeType":"CLASS","label":"2026污水五级一班","value":"12","count":30,"classId":12,"children":[]}]}]}]} ``` ### 3.2 分页列表 `POST /certification/admin/page` ```json {"pageNum":1,"pageSize":20,"keyword":"张","occupation":"污水","levelName":"五级","classId":12} ``` `keyword` 同时模糊匹配姓名和证件号码。`rows` 包含 `studentId`、`name`、`gender`、`idCard`、`assessmentOccupation`、`assessmentLevel`、`classId`、`className`、`workUnit`、`jobYears`、`socialSecurityYears`。仅返回已完善资料。 ```json {"code":200,"msg":"查询成功","total":1,"rows":[{"studentId":"190001","name":"张三","gender":"男","idCard":"310101199506011234","assessmentOccupation":"污水处理工","assessmentLevel":"五级","classId":12,"className":"2026污水五级一班","workUnit":"示例水务公司","jobYears":5,"socialSecurityYears":5}]} ``` ### 3.3 详情 `GET /certification/admin/{studentId}` 响应字段与学员端查询一致,但固定 `editable=false`;本接口不提供修改能力。未完善、已删除或不存在时返回“学员不存在或报名资料尚未完善”。 ### 3.4 单人导出 `GET /certification/admin/{studentId}/export` - `Content-Type: application/msword` - `Content-Disposition: attachment; filename*=UTF-8''...` - 文件名:`{姓名}_B2学员培训鉴定报名表.doc` ### 3.5 批量导出 `POST /certification/admin/export` 勾选导出: ```json {"studentIds":["190001","190002"]} ``` 筛选结果导出: ```json {"keyword":"张","occupation":"污水","levelName":"五级","classId":12} ``` `studentIds` 非空时优先按 ID 导出,否则使用筛选条件。最多 500 人,响应为 `application/zip`,ZIP 名称为 `B2学员培训鉴定报名表_yyyyMMddHHmmss.zip`;内部文件名为 `{姓名}_{证件后四位}_B2学员培训鉴定报名表.doc`,重名时追加学员 ID。文件名中的 Windows 非法字符会替换为下划线。 ## 4. 推荐联调顺序 1. 学员登录后调用查询接口显示账号和班级预填值。 2. 提交一份完整资料,确认 `completed=true`,首次账户状态变为 `STUDYING`。 3. 管理员调用范围树,再按树节点调用分页接口。 4. 通过列表 `studentId` 查询只读详情。 5. 分别验证单人 `.doc` 和勾选/筛选批量 ZIP 下载。 6. 修改已完善或已结业学员资料,确认账户状态不被重置。