# 导入重复检测功能测试文档索引

## 文档概述

本文档集为"导入文件内部主键重复检测"功能提供完整的测试支持,包括测试用例、测试脚本、使用说明等。

## 文档结构

```
doc/
├── test-scripts/                           # 测试脚本和文档
│   ├── test_import_duplicate_detection.py          # Python自动化测试脚本
│   ├── test_import_duplicate_detection_cases.md    # 详细测试用例文档
│   └── README_TEST.md                               # 测试使用说明
├── test-data/                             # 测试数据
│   ├── temp/                               # 临时测试数据(自动生成)
│   ├── employee/                           # 员工测试数据
│   ├── recruitment/                        # 招聘测试数据
│   └── README.md                           # 测试数据说明
└── test-reports/                          # 测试报告
    └── README.md                           # 测试报告说明
```

## 快速导航

### 1. 测试执行
- **快速开始**: 查看 [测试使用说明](test-scripts/README_TEST.md)
- **运行测试**: 双击 `run_duplicate_test.bat` 或运行Python脚本
- **查看报告**: 查看 `test-reports/` 目录下的JSON报告

### 2. 测试用例
- **详细用例**: 查看 [测试用例文档](test-scripts/test_import_duplicate_detection_cases.md)
- **场景1**: 采购交易 - Excel内采购事项ID重复
- **场景2**: 员工信息 - Excel内柜员号重复
- **场景3**: 员工信息 - Excel内身份证号重复
- **场景4**: 混合重复(数据库+Excel)

### 3. 测试数据
- **数据说明**: 查看 [测试数据说明](test-data/README.md)
- **自动生成**: 运行测试脚本自动生成临时测试数据
- **手动测试**: 使用现有的员工/招聘测试数据

### 4. 测试报告
- **报告说明**: 查看 [测试报告说明](test-reports/README.md)
- **报告格式**: JSON格式,包含详细的测试结果
- **报告位置**: `doc/test-reports/test_report_YYYYMMDD_HHMMSS.json`

## 功能概述

### 测试目标
验证导入功能能够正确检测并处理Excel文件内部的主键重复数据:
1. ✅ 采购交易导入 - 检测采购事项ID重复
2. ✅ 员工信息导入 - 检测柜员号和身份证号重复

### 核心逻辑
- 同一Excel文件内,重复的主键只会导入第一条
- 后续重复记录会被跳过,并记录到失败列表
- 提供清晰的错误提示信息
- 正确区分数据库重复和Excel内重复

### 错误消息格式
- **数据库重复**: "采购事项ID[xxx]已存在,请勿重复导入"
- **Excel内重复**: "采购事项ID[xxx]在导入文件中重复,已跳过此条记录"
- **柜员号重复**: "柜员号[xxx]在导入文件中重复,已跳过此条记录"
- **身份证号重复**: "身份证号[xxx]在导入文件中重复,已跳过此条记录"

## 测试环境要求

### 必需组件
- Python 3.7+
- 后端服务运行在 http://localhost:8080
- 测试账号: admin / admin123

### Python依赖
```bash
pip install requests openpyxl
```

### 数据库准备
- 场景4需要预先在数据库中插入测试数据
- 其他场景不需要预先准备数据

## 测试执行方式

### 方式1: 批处理脚本(推荐)
```bash
# Windows
双击 run_duplicate_test.bat

# Linux/Mac
bash run_duplicate_test.sh
```

### 方式2: Python命令
```bash
python doc/test-scripts/test_import_duplicate_detection.py
```

### 方式3: IDE运行
- 使用PyCharm/VS Code打开测试脚本
- 直接运行

## 测试结果解读

### 成功标准
- ✅ 所有4个测试场景通过
- ✅ 通过率 >= 75% (场景4可能因缺少预置数据而部分失败)
- ✅ 错误消息格式正确

### 失败处理
1. 查看测试报告中的error_message
2. 检查后端日志
3. 确认测试环境是否正确
4. 确认测试账号权限是否正确

### 常见问题
- **连接失败**: 确认后端服务是否启动
- **登录失败**: 确认测试账号密码是否正确
- **权限不足**: 确认admin账号是否有导入权限
- **超时**: 增加等待时间或检查后端性能

## 代码实现

### 后端实现
- **采购交易**: `CcdiPurchaseTransactionImportServiceImpl.java` (第54-82行)
- **员工信息**: `CcdiEmployeeImportServiceImpl.java` (第52-101行)

### 关键代码片段

#### 采购交易重复检测
```java
// 用于跟踪Excel文件内已处理的采购事项ID
Set<String> processedIds = new HashSet<>();

for (int i = 0; i < excelList.size(); i++) {
    CcdiPurchaseTransactionExcel excel = excelList.get(i);

    if (existingIds.contains(excel.getPurchaseId())) {
        // 数据库中已存在
        throw new RuntimeException("采购事项ID[" + excel.getPurchaseId() + "]已存在,请勿重复导入");
    } else if (processedIds.contains(excel.getPurchaseId())) {
        // Excel文件内部重复
        throw new RuntimeException("采购事项ID[" + excel.getPurchaseId() + "]在导入文件中重复,已跳过此条记录");
    } else {
        // 正常导入
        newRecords.add(transaction);
        processedIds.add(excel.getPurchaseId()); // 标记为已处理
    }
}
```

#### 员工信息重复检测
```java
// 用于跟踪Excel文件内已处理的主键
Set<Long> processedEmployeeIds = new HashSet<>();
Set<String> processedIdCards = new HashSet<>();

for (int i = 0; i < excelList.size(); i++) {
    CcdiEmployeeExcel excel = excelList.get(i);

    // 统一检查Excel内重复
    if (processedEmployeeIds.contains(excel.getEmployeeId())) {
        throw new RuntimeException("柜员号[" + excel.getEmployeeId() + "]在导入文件中重复,已跳过此条记录");
    }
    if (StringUtils.isNotEmpty(excel.getIdCard()) &&
        processedIdCards.contains(excel.getIdCard())) {
        throw new RuntimeException("身份证号[" + excel.getIdCard() + "]在导入文件中重复,已跳过此条记录");
    }

    // 统一标记为已处理
    processedEmployeeIds.add(excel.getEmployeeId());
    processedIdCards.add(excel.getIdCard());
}
```

## API接口

### 采购交易导入
- **上传**: `POST /ccdi/purchaseTransaction/importData`
- **状态**: `GET /ccdi/purchaseTransaction/importStatus/{taskId}`
- **失败记录**: `GET /ccdi/purchaseTransaction/importFailures/{taskId}`

### 员工信息导入
- **上传**: `POST /ccdi/employee/importData`
- **状态**: `GET /ccdi/employee/importStatus/{taskId}`
- **失败记录**: `GET /ccdi/employee/importFailures/{taskId}`

### Swagger文档
访问 http://localhost:8080/swagger-ui/index.html 查看完整API文档

## 版本历史

### v1.0 (2026-02-09)
- ✅ 创建测试框架
- ✅ 实现4个测试场景
- ✅ 生成完整测试文档
- ✅ 支持自动化测试和手动测试

## 贡献指南

### 添加新测试场景
1. 在ExcelGenerator中添加数据生成方法
2. 创建新的TestCase子类
3. 更新测试用例文档
4. 运行测试验证

### 修改测试逻辑
1. 修改对应的TestCase类
2. 更新测试用例文档
3. 运行完整测试确保不影响其他场景

### 报告问题
如发现问题,请提供:
- 测试报告JSON文件
- 后端日志
- 复现步骤
- 环境信息

## 联系方式

如有问题或建议,请联系开发团队。

---

**最后更新**: 2026-02-09
**文档版本**: v1.0
**维护者**: 测试团队