出国登记管理API.md 12 KB
出国登记管理 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 |
导出出国登记历史数据 |
🔧 数据模型
出国登记表单对象（简化版）
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）
// 以下字段已从表单中移除，因为需要纸质版盖章
interface RemovedFields {
// 登记备案信息
registrationUnit: string; // 登记备案责任单位（已删除）
unitLeaderSignature: string; // 负责人签名（已删除）
// 联系方式
officePhone: string; // 办公电话（已删除）
mobilePhone: string; // 移动电话（已删除）
}
表单验证规则（更新后）
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-已撤回） |
响应示例：
{
"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
接口描述：创建新的出国登记记录
请求参数：
{
"name": "张三",
"gender": "0",
"birthDate": "1990-01-01",
"photo": "", // 照片预留区域（32mm×36mm），不再接收上传地址
"idNumber": "123456789012345678",
"politicalStatus": "中共党员",
"registeredAddress": "浙江省杭州市西湖区某某街道",
"department": "信息工程学院",
"position": "副教授",
"administrativeLevel": "副处级",
"personnelCategory": "A001",
"applicationId": "9876543210987654321",
"remarks": "学术交流访问"
}
响应示例：
{
"code": 200,
"msg": "新增成功",
"data": {
"registrationId": "1234567890123456789"
}
}
🔄 业务流程
登记状态流转
草稿(0) → 已提交(1) → 已确认(2)
↓ ↓
删除 撤回(3)
状态说明
- 草稿(0)：初始创建状态，可编辑、删除
- 已提交(1)：已提交待确认，不可编辑，可撤回
- 已确认(2)：已确认完成，不可编辑撤回
- 已撤回(3)：已撤回状态，可重新编辑提交
🚨 注意事项
字段变更影响
- 前端表单：已移除登记备案信息和联系方式输入框
- 数据验证：已移除相关字段的必填验证
- 接口传参：新增/修改接口不再包含已删除字段
- 列表显示：表格中不再显示移动电话列
- 详情查看：详情弹窗中不再显示相关信息
开发建议
- 确保后端接口也相应调整，移除已删除字段的处理
- 数据库迁移需要考虑历史数据的处理
- 相关导出功能需要同步调整字段列表
- API文档需要及时更新，保持与实际接口一致
📖 参考文档
文档维护：weizzzz
创建时间：2025-09-30
最后更新：2025-09-30