# 党籍保留附件上传功能测试指南

## 📋 功能说明

**功能名称**：党籍保留附件上传  
**实现日期**：2025-10-10  
**适用模块**：出国申请管理  

### 业务场景
- 当申请人是**中共党员**且**出国天数超过30天**时，需要上传党籍保留附件
- 附件需要经过党组织审批并盖章后才能上传
- 支持PDF、JPG、PNG格式，文件大小限制10MB

---

## 🔧 部署前准备

### 1. 数据库更新

**执行SQL脚本**：
```bash
路径：docs/设计文档/database/【立即执行】添加党籍保留附件字段.sql
```

**操作步骤**：
1. 连接到 `hzdyjs_xg` 数据库
2. 执行整个SQL脚本
3. 检查执行结果，确认4个字段添加成功：
   - `party_retention_file_path` - 党籍保留附件文件路径
   - `party_retention_file_name` - 党籍保留附件文件名
   - `party_retention_upload_time` - 党籍保留附件上传时间
   - `party_retention_upload_status` - 党籍保留附件上传状态

### 2. 后端代码部署

**修改文件清单**：
1. ✅ `RsOverseasApplicationController.java` - 新增 `uploadPartyRetentionFile` 接口
2. ✅ `IRsOverseasApplicationService.java` - 新增接口方法声明
3. ✅ `RsOverseasApplicationServiceImpl.java` - 新增接口方法实现
4. ✅ `RsOverseasApplication.java` - 新增4个实体字段

**部署步骤**：
```bash
# 1. 切换到后端目录
cd /Users/weizzzz/Documents/Cursor/0828CURSOR/all-project/backend

# 2. 编译打包
mvn clean package -DskipTests

# 3. 重启后端服务
# 根据实际部署方式重启服务
```

### 3. 前端无需修改
前端代码已经包含党籍保留附件上传功能，无需修改。

---

## 🧪 功能测试步骤

### 测试场景1：符合上传条件的申请

#### 前置条件
- 申请人的政治面貌为：**中共党员**
- 出国天数设置为：**31天或以上**

#### 测试步骤
1. **登录系统**
   - 使用测试账号登录前端系统
   - 导航到：`人事管理` → `出国申请`

2. **创建新申请**
   - 点击"新增申请"按钮
   - 填写基本信息：
     - 申请人姓名：测试用户
     - 所属部门：技术部
     - 政治面貌：**中共党员**
     - 出国类型：因公出国
     - 目的地：美国
     - 出国天数：**35天**（超过30天）

3. **验证上传区域显示**
   - ✅ 应该自动显示"党籍保留附件上传"区域
   - ✅ 显示红色必填提示
   - ✅ 显示上传按钮和说明文字

4. **上传附件**
   - 点击"上传党籍保留附件"按钮
   - 选择一个PDF或图片文件（小于10MB）
   - 观察上传过程

5. **验证上传结果**
   - ✅ 上传成功后显示绿色成功提示："党籍保留附件上传成功！"
   - ✅ 文件列表中显示已上传的文件
   - ✅ 可以预览和删除文件
   - ✅ 按钮文字变为"重新上传"

6. **提交申请**
   - 填写其他必填项
   - 点击"提交"按钮
   - ✅ 申请提交成功

### 测试场景2：不符合上传条件的申请

#### 测试用例2.1：政治面貌为群众
- 政治面貌选择：**群众**
- 出国天数：35天
- ✅ **不应该**显示党籍保留附件上传区域

#### 测试用例2.2：出国天数≤30天
- 政治面貌选择：**中共党员**
- 出国天数：**28天**
- ✅ **不应该**显示党籍保留附件上传区域

### 测试场景3：文件格式验证

#### 测试用例3.1：支持的格式
- 上传 `.pdf` 文件 → ✅ 应该成功
- 上传 `.jpg` 文件 → ✅ 应该成功
- 上传 `.png` 文件 → ✅ 应该成功

#### 测试用例3.2：不支持的格式
- 上传 `.doc` 文件 → ❌ 提示"只支持PDF、JPG、PNG格式的文件！"
- 上传 `.xlsx` 文件 → ❌ 提示"只支持PDF、JPG、PNG格式的文件！"

### 测试场景4：文件大小验证

- 上传 5MB 文件 → ✅ 应该成功
- 上传 9.9MB 文件 → ✅ 应该成功
- 上传 11MB 文件 → ❌ 提示"文件大小不能超过 10MB"

### 测试场景5：API接口测试

#### 使用Postman或curl测试

**请求示例**：
```bash
POST /rs/overseas/application/uploadPartyRetentionFile

Headers:
  Authorization: Bearer {token}
  Content-Type: multipart/form-data

Body (form-data):
  file: [选择文件]
  applicationId: 1234567890
```

**成功响应**：
```json
{
  "code": 200,
  "msg": "党籍保留附件上传成功",
  "data": {
    "filePath": "https://oss.example.com/overseas/party-retention/party_retention_1234567890_1696935234567.pdf",
    "fileName": "党籍保留附件.pdf",
    "uploadTime": "2025-10-10 15:30:45"
  }
}
```

**失败响应示例**：
```json
{
  "code": 500,
  "msg": "不支持的文件格式，请上传PDF、JPG或PNG文件"
}
```

---

## 🔍 数据验证

### 1. 数据库验证

**查询上传记录**：
```sql
SELECT 
    application_id,
    applicant_name,
    party_retention_file_path,
    party_retention_file_name,
    party_retention_upload_time,
    party_retention_upload_status,
    political_status,
    duration
FROM rs_overseas_application
WHERE party_retention_upload_status = '1'
ORDER BY party_retention_upload_time DESC
LIMIT 10;
```

**验证点**：
- ✅ `party_retention_file_path` 应该有完整的OSS路径
- ✅ `party_retention_file_name` 应该是原始文件名
- ✅ `party_retention_upload_time` 应该是当前时间
- ✅ `party_retention_upload_status` 应该是 `'1'`

### 2. OSS存储验证

**文件存储路径**：
```
overseas/party-retention/party_retention_{applicationId}_{timestamp}.{ext}
```

**验证方式**：
- 登录OSS管理控制台
- 导航到 `overseas/party-retention/` 目录
- 确认文件已正确上传
- 验证文件可以正常下载和预览

---

## 🚨 常见问题排查

### 问题1：点击上传按钮后提示"Request method 'POST' is not supported"

**原因**：后端接口未部署或URL路径不正确

**排查步骤**：
1. 检查后端服务是否已重启
2. 检查接口路径：`/rs/overseas/application/uploadPartyRetentionFile`
3. 确认Controller中的 `@PostMapping` 注解配置正确
4. 查看后端日志，确认请求是否到达Controller

### 问题2：上传成功但数据库没有记录

**原因**：数据库字段未添加或Service层更新失败

**排查步骤**：
1. 执行SQL验证字段是否存在：
   ```sql
   SHOW COLUMNS FROM rs_overseas_application 
   WHERE Field LIKE 'party_retention%';
   ```
2. 检查后端日志中的异常信息
3. 确认Service层的 `updatePartyRetentionFileInfo` 方法被正确调用

### 问题3：文件上传失败，提示"系统异常"

**原因**：OSS配置问题或网络问题

**排查步骤**：
1. 检查OSS配置是否正确（application.yml）
2. 确认OSS AccessKey和SecretKey有效
3. 检查服务器到OSS的网络连接
4. 查看后端详细错误日志

### 问题4：上传区域不显示

**原因**：条件判断逻辑问题

**排查步骤**：
1. 确认政治面貌是否选择了"中共党员"
2. 确认出国天数是否>30天
3. 打开浏览器开发者工具，检查 `showPartyRetentionUpload` 的值
4. 检查前端计算逻辑是否正确

---

## ✅ 测试检查清单

### 功能性测试
- [ ] 符合条件时显示上传区域
- [ ] 不符合条件时不显示上传区域
- [ ] 文件格式验证正确（PDF、JPG、PNG）
- [ ] 文件大小验证正确（≤10MB）
- [ ] 上传成功后显示文件信息
- [ ] 可以重新上传替换文件
- [ ] 可以删除已上传文件
- [ ] 提交申请时数据正确保存

### 接口测试
- [ ] POST /uploadPartyRetentionFile 返回200
- [ ] 响应数据格式正确
- [ ] 错误处理正确（格式错误、大小超限等）

### 数据完整性
- [ ] 数据库字段值正确
- [ ] OSS文件存储成功
- [ ] 文件路径可访问
- [ ] 文件可以正常预览和下载

### 用户体验
- [ ] 上传过程有加载提示
- [ ] 成功/失败消息清晰友好
- [ ] 上传按钮状态正确切换
- [ ] 文件列表显示完整

---

## 📝 测试报告模板

```markdown
## 党籍保留附件上传功能测试报告

**测试日期**：2025-10-10  
**测试人员**：[测试人员姓名]  
**测试环境**：开发环境 / 测试环境 / 生产环境

### 测试结果汇总
- 测试用例总数：15
- 通过用例数：__
- 失败用例数：__
- 阻塞用例数：__

### 详细测试结果

#### 1. 上传条件判断
- [✅/❌] 中共党员 + 出国>30天：显示上传区域
- [✅/❌] 群众：不显示上传区域
- [✅/❌] 出国≤30天：不显示上传区域

#### 2. 文件上传功能
- [✅/❌] PDF文件上传成功
- [✅/❌] JPG文件上传成功
- [✅/❌] PNG文件上传成功
- [✅/❌] 不支持格式被拦截
- [✅/❌] 超大文件被拦截

#### 3. 数据存储
- [✅/❌] 数据库记录正确
- [✅/❌] OSS文件存储成功
- [✅/❌] 文件路径可访问

#### 4. 异常情况
- [✅/❌] 网络异常处理
- [✅/❌] 重复上传处理
- [✅/❌] 删除文件处理

### 发现的问题
1. [问题描述]
   - 严重程度：高/中/低
   - 复现步骤：...
   - 期望结果：...
   - 实际结果：...

### 测试结论
[ ] 通过，可以发布  
[ ] 通过，但有建议改进项  
[ ] 不通过，需要修复问题

### 备注
[其他说明]
```

---

## 🎯 验收标准

功能通过以下所有标准即可验收：

1. ✅ 当申请人是中共党员且出国天数>30天时，必须显示党籍保留附件上传区域
2. ✅ 不符合条件时，不显示上传区域，不影响正常申请流程
3. ✅ 文件上传成功后，数据库正确保存4个字段的值
4. ✅ 上传的文件正确存储在OSS的 `overseas/party-retention/` 目录下
5. ✅ 文件格式和大小验证正确，错误提示友好
6. ✅ 可以重新上传替换文件，旧文件被覆盖
7. ✅ 所有操作有明确的成功/失败提示
8. ✅ 不影响现有出国申请的其他功能

---

**文档维护人**：Cursor AI  
**最后更新**：2025-10-10  
**版本**：v1.0