# 出国登记管理 API 接口文档 ## 📋 文档说明 ### 适用场景 - 出国登记信息管理 - 出国登记状态跟踪 - 出国登记记录查询 - 为 Cursor AI 提供完整的接口开发上下文 ### 模块特色 - **简化表单设计**:去除需要纸质盖章的字段,优化用户体验 - **状态管理**:草稿→已提交→已确认→已撤回的完整状态流转 - **数据完整性**:与出国申请系统关联,确保数据一致性 - **历史记录**:完整的登记历史追踪功能 --- ## 🔌 出国登记管理 API 接口文档 ### 模块概述 **模块名称**:overseas-registration / 出国登记管理 **基础路径**:`/api/rs/overseas-registration` **版本**:v1.0 **负责人**:weizzzz **更新时间**:2025-09-30 ### 模块功能 出国登记管理模块提供出国登记信息的完整管理功能,支持登记信息录入、状态管理、历史记录查询等核心功能。该模块与出国申请系统集成,为已审批通过的出国申请提供登记功能。 ### 重要变更记录 #### 2025-09-30 字段优化变更 **第二次更新:照片字段UI优化** - **UI变更**:照片字段从输入框改为右上角预留区域(32mm×36mm) - **功能调整**: - 删除照片上传输入框 - 在弹窗右上角添加照片预留位置标识 - 用于审批完成后下载附件线下张贴照片 - **字段保留**:photo字段在数据模型中保留(兼容性考虑) - **用户体验**:简化表单操作,明确线下张贴流程 **第一次更新:登记备案信息字段删除** - **删除字段**:`登记备案信息`和`联系方式`相关字段 - **删除原因**:这些字段需要下载后纸质版盖章,不适合在线填写 - **影响范围**:前端表单、API接口、数据模型 - **具体删除字段**: - `registrationUnit`:登记备案责任单位 - `unitLeaderSignature`:负责人签名 - `officePhone`:办公电话 - `mobilePhone`:移动电话 ### 权限说明 #### 出国登记权限 - **权限前缀**:`rs:overseas:registration:` - **权限列表**: - `rs:overseas:registration:list` - 查询登记列表权限 - `rs:overseas:registration:query` - 查询登记详情权限 - `rs:overseas:registration:add` - 新增登记权限 - `rs:overseas:registration:edit` - 编辑登记权限 - `rs:overseas:registration:remove` - 删除登记权限 - `rs:overseas:registration:export` - 导出登记权限 - `rs:overseas:registration:submit` - 提交登记权限 - `rs:overseas:registration:cancel` - 撤回登记权限 --- ## 📊 接口概览 ### 接口分类 #### 出国登记基础 CRUD 接口 | 接口名称 | HTTP 方法 | 路径 | 权限要求 | 功能描述 | | ---------------- | --------- | --------------------------------------- | ------------------------------------- | -------------------------- | | 查询登记列表 | GET | `/rs/overseas-registration/list` | `rs:overseas:registration:list` | 分页查询出国登记列表 | | 查询登记详情 | GET | `/rs/overseas-registration/{id}` | `rs:overseas:registration:query` | 根据ID查询出国登记详情 | | 新增登记 | POST | `/rs/overseas-registration` | `rs:overseas:registration:add` | 创建新的出国登记 | | 修改登记 | PUT | `/rs/overseas-registration` | `rs:overseas:registration:edit` | 更新出国登记信息 | | 删除登记 | DELETE | `/rs/overseas-registration/{ids}` | `rs:overseas:registration:remove` | 批量删除出国登记 | | 导出登记 | POST | `/rs/overseas-registration/export` | `rs:overseas:registration:export` | 导出出国登记数据 | #### 出国登记业务逻辑接口 | 接口名称 | HTTP 方法 | 路径 | 权限要求 | 功能描述 | | ------------------ | --------- | ------------------------------------------- | ------------------------------------- | -------------------------- | | 提交登记 | PUT | `/rs/overseas-registration/submit/{id}` | `rs:overseas:registration:submit` | 提交出国登记 | | 撤回登记 | PUT | `/rs/overseas-registration/cancel/{id}` | `rs:overseas:registration:cancel` | 撤回出国登记 | | 保存并提交 | POST | `/rs/overseas-registration/addAndSubmit` | `rs:overseas:registration:add` | 保存并提交出国登记 | #### 出国登记历史接口 | 接口名称 | HTTP 方法 | 路径 | 权限要求 | 功能描述 | | ------------------ | --------- | ------------------------------------------- | ------------------------------------- | -------------------------- | | 查询登记历史 | GET | `/rs/overseas-registration/history/list` | `rs:overseas:registration:list` | 查询出国登记历史列表 | | 查询历史详情 | GET | `/rs/overseas-registration/history/{id}` | `rs:overseas:registration:query` | 查询出国登记历史详情 | | 更新历史记录 | PUT | `/rs/overseas-registration/history` | `rs:overseas:registration:edit` | 更新出国登记历史记录 | | 导出历史记录 | POST | `/rs/overseas-registration/history/export` | `rs:overseas:registration:export` | 导出出国登记历史数据 | --- ## 🔧 数据模型 ### 出国登记表单对象(简化版) ```typescript interface OverseasRegistrationForm { // 基本信息 name: string; // 姓名 gender: string; // 性别(0-男,1-女) birthDate: string; // 出生日期 photo: string; // 照片预留(右上角32mm×36mm预留区域,用于审批完成后线下张贴,字段保留用于兼容性) idNumber: string; // 身份证号码 politicalStatus: string; // 政治面貌 registeredAddress: string; // 户籍所在地 // 工作信息 department: string; // 工作部门 position: string; // 职务职称 administrativeLevel: string; // 行政职级 personnelCategory: string; // 人员类别代码 // 关联信息 applicationId: string; // 关联出国申请ID remarks: string; // 备注 } ``` ### 字段变更说明 #### 已删除字段(2025-09-30) ```typescript // 以下字段已从表单中移除,因为需要纸质版盖章 interface RemovedFields { // 登记备案信息 registrationUnit: string; // 登记备案责任单位(已删除) unitLeaderSignature: string; // 负责人签名(已删除) // 联系方式 officePhone: string; // 办公电话(已删除) mobilePhone: string; // 移动电话(已删除) } ``` ### 表单验证规则(更新后) ```typescript const registrationRules = { name: [{ required: true, message: '请输入姓名', trigger: 'blur' }], gender: [{ required: true, message: '请选择性别', trigger: 'change' }], birthDate: [{ required: true, message: '请选择出生日期', trigger: 'change' }], idNumber: [ { required: true, message: '请输入身份证号', trigger: 'blur' }, { pattern: /^[1-9]\d{5}(18|19|20)\d{2}((0[1-9])|(1[0-2]))(([0-2][1-9])|10|20|30|31)\d{3}[0-9Xx]$/, message: '请输入正确的18位身份证号码', trigger: 'blur' } ], politicalStatus: [{ required: true, message: '请选择政治面貌', trigger: 'change' }], registeredAddress: [{ required: true, message: '请输入户籍所在地', trigger: 'blur' }], department: [{ required: true, message: '请输入工作部门', trigger: 'blur' }], position: [{ required: true, message: '请输入职务职称', trigger: 'blur' }] }; ``` ## 📝 接口详情 ### 1. 查询出国登记列表 **接口地址**:`GET /rs/overseas-registration/list` **接口描述**:分页查询出国登记列表,支持多条件筛选 **请求参数**: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | pageNum | number | 是 | 页码,从1开始 | | pageSize | number | 是 | 每页大小,最大100 | | name | string | 否 | 姓名(模糊匹配) | | gender | string | 否 | 性别(0-男,1-女) | | idNumber | string | 否 | 身份证号(模糊匹配) | | politicalStatus | string | 否 | 政治面貌 | | department | string | 否 | 工作部门(模糊匹配) | | position | string | 否 | 职务职称(模糊匹配) | | status | string | 否 | 登记状态(0-草稿,1-已提交,2-已确认,3-已撤回) | **响应示例**: ```json { "code": 200, "msg": "操作成功", "rows": [ { "registrationId": "1234567890123456789", "name": "张三", "gender": "0", "birthDate": "1990-01-01", "idNumber": "123456789012345678", "politicalStatus": "中共党员", "registeredAddress": "浙江省杭州市西湖区", "department": "信息工程学院", "position": "副教授", "status": "1", "statusText": "已提交", "registrationTime": "2025-09-30 10:00:00", "createTime": "2025-09-30 09:30:00" } ], "total": 1 } ``` ### 2. 新增出国登记 **接口地址**:`POST /rs/overseas-registration` **接口描述**:创建新的出国登记记录 **请求参数**: ```json { "name": "张三", "gender": "0", "birthDate": "1990-01-01", "photo": "", // 照片预留区域(32mm×36mm),不再接收上传地址 "idNumber": "123456789012345678", "politicalStatus": "中共党员", "registeredAddress": "浙江省杭州市西湖区某某街道", "department": "信息工程学院", "position": "副教授", "administrativeLevel": "副处级", "personnelCategory": "A001", "applicationId": "9876543210987654321", "remarks": "学术交流访问" } ``` **响应示例**: ```json { "code": 200, "msg": "新增成功", "data": { "registrationId": "1234567890123456789" } } ``` --- ## 🔄 业务流程 ### 登记状态流转 ``` 草稿(0) → 已提交(1) → 已确认(2) ↓ ↓ 删除 撤回(3) ``` ### 状态说明 - **草稿(0)**:初始创建状态,可编辑、删除 - **已提交(1)**:已提交待确认,不可编辑,可撤回 - **已确认(2)**:已确认完成,不可编辑撤回 - **已撤回(3)**:已撤回状态,可重新编辑提交 --- ## 🚨 注意事项 ### 字段变更影响 1. **前端表单**:已移除登记备案信息和联系方式输入框 2. **数据验证**:已移除相关字段的必填验证 3. **接口传参**:新增/修改接口不再包含已删除字段 4. **列表显示**:表格中不再显示移动电话列 5. **详情查看**:详情弹窗中不再显示相关信息 ### 开发建议 1. 确保后端接口也相应调整,移除已删除字段的处理 2. 数据库迁移需要考虑历史数据的处理 3. 相关导出功能需要同步调整字段列表 4. API文档需要及时更新,保持与实际接口一致 --- ## 📖 参考文档 - [API文档基础规范](./API文档基础规范.md) - [用户认证登录API](./用户认证登录API.md) - [出国申请管理API](./出国申请管理API.md) --- **文档维护**:weizzzz **创建时间**:2025-09-30 **最后更新**:2025-09-30