cykj/hzdyjs

0 Fork 0

Files

T

zlwu 375a2c8df7 提交代码

2025-11-28 20:01:32 +08:00

15 KiB

Raw Blame History

出国行程变更管理API文档

📋 文档信息

模块名称: 出国行程变更申请管理
功能概述: 提供出国行程变更申请的新增、查询、审批等功能
创建日期: 2025-10-13
最后更新: 2025-10-13
数据库版本: v1.1（包含个人信息字段）

🎯 业务说明

功能概述

出国行程变更管理模块允许用户对已审批通过的出国申请提交行程变更申请，支持变更目的地、时间、行程安排等信息。

业务流程

1. 用户查看已审批通过的出国申请
2. 用户选择一个出国申请，填写变更信息
3. 提交变更申请（状态：待审核）
4. 管理员审批变更申请
   - 通过：状态变为"已通过"，成为变更记录
   - 拒绝：状态变为"已拒绝"
5. 用户可撤回待审核的变更申请

数据分类

变更申请: 所有状态的变更申请记录（待审核、已通过、已拒绝、已撤回）
变更记录: 只包含已通过审批的变更申请，代表真正生效的变更记录

🔌 API接口列表

1. 查询变更申请列表

接口说明: 查询所有的行程变更申请（包括所有状态）

请求方式: GET

接口地址: /rs/itinerary/change/list

权限标识: rs:itineraryChange:list

请求参数:

参数名	类型	必填	说明
pageNum	Integer	否	页码（默认1）
pageSize	Integer	否	每页条数（默认10）
applicantName	String	否	申请人姓名（模糊查询）
status	String	否	变更状态（0=待审核，1=已通过，2=已拒绝，3=已撤回）
changeType	String	否	变更类型

响应示例:

{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "total": 10,
    "rows": [
      {
        "changeId": "1977740586114916354",
        "applicationId": "1977123456789012345",
        "applicantId": "1",
        "applicantName": "admin",
        "status": "0",
        "statusText": "待审核",
        "changeType": "destination_change",
        "changeTypeText": "目的地变更",
        "originalDestination": "美国",
        "newDestination": "加拿大",
        "originalStartDate": "2025-11-01",
        "newStartDate": "2025-11-05",
        "changeReason": "会议时间调整",
        "createTime": "2025-10-13 10:00:00"
      }
    ]
  }
}

2. 查询变更记录列表

接口说明: 查询当前用户的变更记录（只返回已通过的变更申请）

重要说明:

🔴 此接口只返回status='1'（已通过）的变更申请
变更记录代表真正生效的变更记录，不包括待审核、已拒绝、已撤回的申请

请求方式: GET

接口地址: /rs/itinerary/change/my/list

权限标识: rs:itineraryChange:list

请求参数:

参数名	类型	必填	说明
pageNum	Integer	否	页码（默认1）
pageSize	Integer	否	每页条数（默认10）
changeType	String	否	变更类型

后端自动过滤条件:

applicantId = 当前登录用户ID（自动设置）
status = '1'（只查询已通过的，自动设置）

响应示例:

{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "total": 5,
    "rows": [
      {
        "changeId": "1977740586114916354",
        "applicationId": "1977123456789012345",
        "applicantId": "1",
        "applicantName": "admin",
        "status": "1",
        "statusText": "已通过",
        "changeType": "destination_change",
        "changeTypeText": "目的地变更",
        "originalDestination": "美国",
        "newDestination": "加拿大",
        "approverName": "管理员",
        "approveTime": "2025-10-13 14:00:00",
        "createTime": "2025-10-13 10:00:00"
      }
    ]
  }
}

字段补充说明（2025-11-28）

approverName：后台统一返回审批人的昵称，若用户未设置昵称则自动回退到账号；前端无需再做用户名到昵称的手动映射。

3. 查询待审批列表

接口说明: 查询待审批的行程变更申请（status='0'）

请求方式: GET

接口地址: /rs/itinerary/change/pending/list

权限标识: rs:itineraryChange:approve

请求参数:

参数名	类型	必填	说明
pageNum	Integer	否	页码（默认1）
pageSize	Integer	否	每页条数（默认10）
applicantName	String	否	申请人姓名（模糊查询）

后端自动过滤条件:

status = '0'（只查询待审核的，自动设置）

4. 查询变更申请详情

接口说明: 根据变更ID查询详细信息

请求方式: GET

接口地址: /rs/itinerary/change/{changeId}

权限标识: rs:itineraryChange:query

路径参数:

参数名	类型	必填	说明
changeId	Long	是	变更ID

响应示例:

{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "changeId": "1977740586114916354",
    "applicationId": "1977123456789012345",
    "applicantName": "admin",
    "gender": "0",
    "birthDate": "1990-01-01",
    "politicalStatus": "中共党员",
    "status": "1",
    "statusText": "已通过",
    "changeType": "destination_change",
    "changeTypeText": "目的地变更",
    "originalDestination": "美国",
    "newDestination": "加拿大",
    "originalStartDate": "2025-11-01",
    "newStartDate": "2025-11-05",
    "changeReason": "会议时间调整",
    "supportingDocuments": "http://xxx.com/file.pdf",
    "approverName": "管理员",
    "approveTime": "2025-10-13 14:00:00",
    "approveOpinion": "同意变更"
  }
}

5. 新增变更申请

接口说明: 提交新的行程变更申请

请求方式: POST

接口地址: /rs/itinerary/change

权限标识: rs:itineraryChange:add

请求体示例:

{
  "applicationId": "1977123456789012345",
  "changeType": "destination_change",
  "newDestination": "加拿大",
  "newDestinationCity": "多伦多",
  "newStartDate": "2025-11-05",
  "newEndDate": "2025-11-15",
  "newDuration": 10,
  "changeReason": "会议时间调整",
  "supportingDocuments": "http://xxx.com/file.pdf"
}

后端自动设置字段:

applicantId: 当前登录用户ID
applicantName: 当前登录用户姓名
status: '0'（待审核）
tenantId: 当前租户ID
从原出国申请中复制：originalDestination、originalStartDate等原始信息

业务校验:

✅ 出国申请必须存在且状态为"已通过"
✅ 不能对同一个出国申请同时提交多个待审核的变更申请

6. 修改变更申请（重新提交）

接口说明: 修改待审核或已拒绝的变更申请并重新提交

请求方式: PUT

接口地址: /rs/itinerary/change

权限标识: rs:itineraryChange:edit

请求体示例:

{
  "changeId": "1977740586114916354",
  "changeType": "destination_change",
  "newDestination": "英国",
  "newDestinationCity": "伦敦",
  "changeReason": "更新后的变更原因"
}

7. 删除变更申请

接口说明: 删除变更申请（逻辑删除）

请求方式: DELETE

接口地址: /rs/itinerary/change/{changeIds}

权限标识: rs:itineraryChange:remove

路径参数:

参数名	类型	必填	说明
changeIds	Long[]	是	变更ID数组（逗号分隔）

8. 撤回变更申请

接口说明: 撤回待审核的变更申请

请求方式: PUT

接口地址: /rs/itinerary/change/cancel/{changeId}

权限标识: rs:itineraryChange:cancel

路径参数:

参数名	类型	必填	说明
changeId	Long	是	变更ID

业务规则:

✅ 只能撤回状态为"待审核"的申请
撤回后状态变为'3'（已撤回）

9. 审批变更申请

接口说明: 审批行程变更申请（通过/拒绝）

请求方式: PUT

接口地址: /rs/itinerary/change/approve

权限标识: rs:itineraryChange:approve

请求体示例:

{
  "changeId": "1977740586114916354",
  "approved": true,
  "opinion": "同意变更"
}

参数说明:

参数名	类型	必填	说明
changeId	Long	是	变更ID
approved	Boolean	是	是否通过（true=通过，false=拒绝）
opinion	String	否	审批意见

重要提示:

⚠️ 后端接口使用Map接收参数，前端必须发送正确的字段名
✅ 字段名：changeId、approved、opinion
❌ 不要使用：approvalStatus、approvalOpinion

审批结果:

approved=true: 状态变为'1'（已通过）→ 成为变更记录
approved=false: 状态变为'2'（已拒绝）

响应示例:

{
  "code": 200,
  "msg": "操作成功"
}

10. 获取可用的出国申请列表

接口说明: 获取已审批通过的出国申请列表（用于新增变更时选择原申请）

请求方式: GET

接口地址: /rs/itinerary/change/available-records

权限标识: rs:itineraryChange:list

响应说明: 返回当前用户的所有已通过审批的出国申请

11. 查询某个出国申请的变更历史

接口说明: 查询某个出国申请的所有变更记录

请求方式: GET

接口地址: /rs/itinerary/change/record/{recordId}/history

权限标识: rs:itineraryChange:query

路径参数:

参数名	类型	必填	说明
recordId	Long	是	出国记录ID（或申请ID）

📊 数据字典

变更状态（rs_itinerary_change_status）

字典值	标签	样式	说明
0	待审核	primary	待审批状态
1	已通过	success	已通过审批，成为变更记录
2	已拒绝	danger	已拒绝
3	已撤回	info	用户撤回

变更类型（rs_itinerary_change_type）

字典值	标签	说明
destination_change	目的地变更	更改出国目的地
time_change	时间变更	更改出国时间
itinerary_change	行程变更	更改行程安排
transportation_change	交通方式变更	更改交通方式
accommodation_change	住宿变更	更改住宿安排

🎯 前端Tab说明

变更申请Tab（all）

数据来源: /rs/itinerary/change/list
显示内容: 所有的变更申请（包括所有状态）
功能: 新增、编辑、删除、查看、撤回

变更记录Tab（my）

数据来源: /rs/itinerary/change/my/list
显示内容: 🔴 只显示已通过的变更申请（status='1'）
业务含义: 真正生效的变更记录
功能: 查看已通过的变更记录

🔐 权限配置

权限标识	说明
rs:itineraryChange:list	查询变更申请/记录列表
rs:itineraryChange:query	查看变更详情
rs:itineraryChange:add	新增变更申请
rs:itineraryChange:edit	修改变更申请
rs:itineraryChange:remove	删除变更申请
rs:itineraryChange:cancel	撤回变更申请
rs:itineraryChange:approve	审批变更申请
rs:itineraryChange:export	导出变更申请

📝 业务规则总结

✅ 新增变更申请: 只能为已通过审批的出国申请提交变更
✅ 并发控制: 同一个出国申请不能同时有多个待审核的变更申请
✅ 撤回限制: 只能撤回待审核状态的申请
✅ 变更记录: 只有已通过的变更申请才会显示在"变更记录"Tab中
✅ 权限控制: 所有接口都需要相应的权限标识

🔧 故障排查

问题1：Unknown column 'gender' in 'field list'

错误描述:

java.sql.SQLSyntaxErrorException: Unknown column 'gender' in 'field list'

原因分析:

数据库表 rs_overseas_itinerary_change 缺少个人信息字段
后端Mapper查询包含了这些字段，但表中不存在

解决方案:

1️⃣ 执行修复SQL:

文件位置: docs/设计文档/database/⚡一键修复-添加缺失字段.sql
执行方式: 直接在MySQL中执行

2️⃣ 重启后端服务（清除MyBatis缓存）

3️⃣ 重新测试功能

缺失字段列表:

gender - 性别
birth_date - 出生日期
political_status - 政治面貌
professional_title - 职称
position - 职务
document_name - 申领证件名称
document_number - 证件号码
department - 部门

详细修复指南: docs/问题解决方案/🚨数据库字段缺失修复指南.md

问题2：审批接口参数错误

错误描述:

Cannot invoke "Object.toString()" because the return value of "java.util.Map.get(Object)" is null

原因分析:

前端发送的字段名与后端期望不匹配
前端: approvalStatus + approvalOpinion
后端: approved + opinion

解决方案:

前端必须发送正确的参数：

{
  "changeId": 123,
  "approved": true,    // ✅ 布尔值，不是字符串
  "opinion": "同意变更"
}

详细修复总结: docs/问题解决方案/行程变更审批接口参数错误修复总结.md

问题3：变更记录Tab显示不正确

问题描述:

"变更记录"Tab显示了所有状态的数据
预期只显示已通过(status='1')的数据

原因分析:

前端查询参数未设置status过滤条件

解决方案:

前端在查询"变更记录"时必须传递 status: '1':

const queryParams = ref<ItineraryChangeQuery>({
  pageNum: 1,
  pageSize: 10,
  status: '1'  // ✅ 只查询已通过的记录
});

详细修复总结: docs/问题解决方案/变更记录Tab显示逻辑修复总结.md

📞 相关文档

开发文档

数据库脚本

问题解决方案

文档创建时间: 2025-10-13
文档版本: v1.1
维护人员: weizzzz
最后更新: 2025-10-13（新增故障排查部分）

15 KiB Raw Blame History Unescape Escape

出国行程变更管理API文档

📋 文档信息

🎯 业务说明

功能概述

业务流程

数据分类

🔌 API接口列表

1. 查询变更申请列表

2. 查询变更记录列表

字段补充说明（2025-11-28）

3. 查询待审批列表

4. 查询变更申请详情

5. 新增变更申请

6. 修改变更申请（重新提交）

7. 删除变更申请

8. 撤回变更申请

9. 审批变更申请

10. 获取可用的出国申请列表

11. 查询某个出国申请的变更历史

📊 数据字典

变更状态（rs_itinerary_change_status）

变更类型（rs_itinerary_change_type）

🎯 前端Tab说明

变更申请Tab（all）

变更记录Tab（my）

🔐 权限配置

📝 业务规则总结

🔧 故障排查

问题1：Unknown column 'gender' in 'field list'

问题2：审批接口参数错误

问题3：变更记录Tab显示不正确

📞 相关文档

开发文档

数据库脚本

问题解决方案

15 KiB

Raw Blame History