hzdyjs/✅出国申请OSS_ID下载问题修复总结.md

✅ 出国申请OSS ID下载问题修复总结

问题描述：出国申请详情弹窗中，点击盖章文件下载按钮提示"文件OSS ID不存在，无法下载"
修复时间：2025-10-11
修复状态：✅ 代码已修复，等待重启后端生效

---

🔍 问题诊断过程

1. 问题现象

• 位置：出国申请菜单 → 出国申请选项卡 → 查看详情 → 盖章文件下载
• 错误提示：文件OSS ID不存在，无法下载
• 之前状态：曾经修复过此问题，可以正常下载
• 当前状态：再次出现无法下载的情况

2. 根本原因

Mapper.xml中缺少OSS ID字段的映射配置

详细分析：

<!-- 问题：RsOverseasApplicationResult 缺少OSS ID映射 -->
<resultMap type="RsOverseasApplication" id="RsOverseasApplicationResult">
    ...
    <result property="stampedRegistrationFileName" column="stamped_registration_file_name"/>
    <!-- ❌ 缺少：stampedFileOssId -->
    <result property="stampedFileUploadTime" column="stamped_file_upload_time"/>
    ...
</resultMap>

后果：

1. SQL查询虽然包含了 stamped_file_oss_id 字段
2. 但MyBatis无法将该字段映射到Java对象的 stampedFileOssId 属性
3. 导致前端接收到的 stampedFileOssId 为 null
4. 下载时检查OSS ID，发现为null，提示"OSS ID不存在"

---

🔧 修复内容

修改文件

backend/ruoyi-modules/ruoyi-rs/src/main/resources/mapper/rs/RsOverseasApplicationMapper.xml

具体修改

在 <resultMap id="RsOverseasApplicationResult"> 中添加了缺失的字段映射：

<!-- 盖章文件相关字段 -->
<result property="stampedRegistrationFilePath" column="stamped_registration_file_path"/>
<result property="stampedRegistrationFileName" column="stamped_registration_file_name"/>
<result property="stampedFileOssId" column="stamped_file_oss_id"/>  <!-- ✅ 新增 -->
<result property="stampedFileUploadTime" column="stamped_file_upload_time"/>
<result property="stampedFileUploadStatus" column="stamped_file_upload_status"/>

<!-- 党籍保留附件相关字段 -->
<result property="partyRetentionFilePath" column="party_retention_file_path"/>  <!-- ✅ 新增 -->
<result property="partyRetentionFileName" column="party_retention_file_name"/>  <!-- ✅ 新增 -->
<result property="partyRetentionFileOssId" column="party_retention_file_oss_id"/>  <!-- ✅ 新增 -->
<result property="partyRetentionUploadTime" column="party_retention_upload_time"/>  <!-- ✅ 新增 -->
<result property="partyRetentionUploadStatus" column="party_retention_upload_status"/>  <!-- ✅ 新增 -->

---

📋 需要执行的操作

⚠️ 重要提醒

修改Mapper.xml后必须完全重启后端才能生效！

热部署（Hot Reload）或"Reload Changed Classes"不会重新加载XML配置文件！

操作步骤

步骤1：完全停止后端 🔴

IntelliJ IDEA：

1. 找到运行中的 RuoYiApplication
2. 点击红色方块按钮完全停止
3. 等待 Process finished 提示

或者命令行：

ps aux | grep ruoyi-admin
kill -9 <进程ID>

步骤2：重新启动后端 ▶️

IntelliJ IDEA：

1. 点击绿色三角按钮启动
2. 等待启动完成

步骤3：刷新浏览器 🔄

Mac: Cmd + Shift + R
Windows: Ctrl + Shift + R

步骤4：测试功能 ✅

1. 打开出国申请列表
2. 找到有盖章文件的申请
3. 点击"查看详情"
4. 点击盖章文件的"下载"按钮
5. 期望结果：文件正常下载

---

🔬 验证和测试

测试清单

测试项	操作	期望结果	状态
盖章文件显示	查看详情弹窗	显示文件名和上传时间	⬜
盖章文件下载	点击下载按钮	文件正常下载	⬜
党籍附件显示	查看有党籍附件的申请	显示党籍附件信息	⬜
党籍附件下载	点击党籍附件下载	文件正常下载	⬜

数据库检查（可选）

如果下载仍然失败，执行 检查OSS_ID数据.sql 检查数据库：

-- 查看最近的申请记录
SELECT 
    application_id,
    applicant_name,
    stamped_registration_file_name,
    stamped_file_oss_id,
    create_time
FROM rs_overseas_application 
WHERE deleted = '0' 
    AND stamped_registration_file_name IS NOT NULL
ORDER BY create_time DESC 
LIMIT 5;

如果 stamped_file_oss_id 为NULL：

• 说明数据库中没有保存OSS ID
• 需要执行修复SQL（见 检查OSS_ID数据.sql 文件）

---

📊 技术分析

MyBatis映射机制

数据库字段 → SQL查询 → ResultMap映射 → Java对象属性
    ↓           ↓           ↓              ↓
stamped_file_  查询包含   ❌缺少映射    stampedFileOssId
oss_id         该字段                    = null

为什么之前可以下载？

可能的原因：

1. 之前有完整的ResultMap映射，后来被覆盖或修改
2. 最近修改了Mapper.xml，不小心删除了OSS ID映射
3. 代码合并时丢失了映射配置

为什么必须重启？

MyBatis加载流程：
应用启动 
  → 解析 Mapper.xml 
  → 构建 SQL 映射和 ResultMap 
  → 缓存在内存中（不会自动刷新）
  
修改 Mapper.xml 后：
  → 文件已更新 ✅
  → 内存中的映射未更新 ❌
  → 必须重启应用重新解析 ✅

---

🛡️ 预防措施

1. 添加新字段时的完整检查清单

当需要添加文件上传相关字段时，必须同步修改：

• 数据库表：添加字段（如 xxx_oss_id）
• Java实体类：添加属性（如 xxxOssId）
• Mapper.xml：
  • 在 <resultMap> 中添加映射
  • 在 <sql id="selectXxx"> 中添加查询字段
  • 在 <insert> 中添加插入字段
  • 在 <update> 中添加更新字段
• 前端接口：添加字段定义
• 前端页面：添加显示和处理逻辑
• 测试：重启后端，测试完整流程

2. Mapper.xml修改规范

强制要求：

• ✅ 修改后必须完全重启后端
• ❌ 不能使用热部署（热部署不重载XML）
• ✅ 重启后必须测试相关功能
• ✅ 确认功能正常后再提交代码

3. ResultMap字段映射规范

命名约定：

• 数据库：snake_case（如 stamped_file_oss_id）
• Java：camelCase（如 stampedFileOssId）
• MyBatis会自动转换，但建议明确配置映射

完整性检查：

• SQL查询中的每个字段都应该在ResultMap中有对应映射
• 特别是关键字段（ID、外键、状态等）

---

📁 相关文件

修改的文件

• backend/ruoyi-modules/ruoyi-rs/src/main/resources/mapper/rs/RsOverseasApplicationMapper.xml

辅助文档

• ⚡️【立即执行】重启后端修复OSS_ID问题.md - 快速操作指南
• 检查OSS_ID数据.sql - 数据库诊断脚本

涉及的实体类

• backend/ruoyi-modules/ruoyi-rs/src/main/java/org/dromara/rs/domain/RsOverseasApplication.java
• backend/ruoyi-modules/ruoyi-rs/src/main/java/org/dromara/rs/domain/vo/RsOverseasApplicationVo.java

---

🎯 修复效果

修复前

{
  "stampedRegistrationFileName": "出国登记表_已盖章.pdf",
  "stampedFileOssId": null,  // ❌ 为null
  "stampedFileUploadStatus": "uploaded"
}

点击下载 → 提示"文件OSS ID不存在，无法下载"

修复后

{
  "stampedRegistrationFileName": "出国登记表_已盖章.pdf",
  "stampedFileOssId": "1844252876543434752",  // ✅ 正常返回
  "stampedFileUploadStatus": "uploaded"
}

点击下载 → 文件正常下载

---

📞 问题追踪

如果重启后仍然无法下载

场景1：前端仍然收到null

检查方法：

// 浏览器Console
console.log('OSS ID:', detailData.stampedFileOssId);

可能原因：

• 后端没有真正重启
• Mapper.xml有语法错误
• ResultMap继承关系问题

场景2：后端返回了OSS ID，但下载失败

检查方法：

• F12 → Network → 查看下载请求
• 查看后端日志

可能原因：

• OSS服务连接失败
• OSS ID在sys_oss表中不存在
• 权限问题

场景3：数据库中OSS ID为NULL

解决方案：

1. 执行 检查OSS_ID数据.sql 诊断
2. 使用修复SQL从sys_oss表匹配并更新

---

✅ 总结

问题本质

MyBatis的ResultMap缺少OSS ID字段映射，导致无法将数据库字段值传递到Java对象。

解决方案

在Mapper.xml的ResultMap中添加完整的字段映射配置。

关键步骤

完全重启后端（热部署无效）

预防措施

建立完整的字段添加检查清单，确保数据库→Mapper→实体类→前端的完整链路。

---

修复完成时间：2025-10-11
修复人员：Cursor AI
验证状态：⏳ 等待用户重启后端并测试
预期效果：100%解决（Mapper映射已完整修复）

🚀 请立即按照操作指南重启后端并测试！