hzdyjs/docs/开发文档/API/出国登记管理API.md

出国登记管理 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)：已撤回状态，可重新编辑提交

---

🚨 注意事项

字段变更影响

1. 前端表单：已移除登记备案信息和联系方式输入框
2. 数据验证：已移除相关字段的必填验证
3. 接口传参：新增/修改接口不再包含已删除字段
4. 列表显示：表格中不再显示移动电话列
5. 详情查看：详情弹窗中不再显示相关信息

开发建议

1. 确保后端接口也相应调整，移除已删除字段的处理
2. 数据库迁移需要考虑历史数据的处理
3. 相关导出功能需要同步调整字段列表
4. API文档需要及时更新，保持与实际接口一致

---

📖 参考文档

• API文档基础规范
• 用户认证登录API
• 出国申请管理API

---

文档维护：weizzzz
创建时间：2025-09-30
最后更新：2025-09-30