JDAirPort.Ems.Back/docs/Excel图片导入导出使用指南.md

# Excel图片导入导出使用指南

## 技术方案概述

### 技术架构
- **框架**: RuoYi (SpringBoot + Vue + Redis + MyBatis)
- **部署环境**: 麒麟系统
- **数据库**: TiDB
- **Excel处理**: Apache POI 4.1.2
- **图片存储**: 本地文件系统

### 核心功能
1. Excel中嵌入图片的导出
2. Excel中图片的提取和导入
3. 图片文件的本地存储管理
4. 数据库路径信息的维护

## 实现架构

### 1. 核心工具类

#### ImageExcelUtils.java
专门处理Excel图片操作的工具类

**主要功能:**
- `insertImageToCell()`: 向Excel单元格插入图片
- `extractImagesFromSheet()`: 从Excel提取所有图片
- `saveImageFromExcel()`: 保存提取的图片到本地
- `isSupportedImageFormat()`: 验证图片格式
- `cleanupTempImages()`: 清理临时图片文件

**支持格式:**
- JPG/JPEG
- PNG
- GIF (转换为JPEG)
- BMP (转换为JPEG)

#### ExcelUtil.java (增强版)
集成图片处理功能的Excel工具类

**新增功能:**
- 在`setCellVo()`中集成图片插入
- 在`importExcel()`中集成图片提取
- 自动处理图片的导入导出流程

### 2. 实体类配置

```java
public class PowerEnergySparePartsRegistration {
    /** 图片位置 */
    @Excel(name = "图片位置", 
           cellType = Excel.ColumnType.IMAGE, 
           width = 30, 
           height = 80)
    private String imageLocation;
}
```

**注解说明:**
- `cellType = Excel.ColumnType.IMAGE`: 指定为图片类型
- `width = 30`: 单元格宽度
- `height = 80`: 单元格高度

### 3. Controller层实现

#### 新增接口

1. **导入模板下载**
   ```
   POST /ems/info/powerEnergyRegistration/importTemplate
   ```

2. **数据导入（含图片）**
   ```
   POST /ems/info/powerEnergyRegistration/importData
   参数: file (MultipartFile), updateSupport (boolean)
   ```

3. **数据导出（含图片）**
   ```
   POST /ems/info/powerEnergyRegistration/export
   ```

## 使用流程

### 导出流程

1. **准备数据**
   ```java
   List<PowerEnergySparePartsRegistration> list = service.selectList(params);
   ```

2. **设置图片路径**
   确保实体对象的`imageLocation`字段包含正确的图片路径

3. **执行导出**
   ```java
   ExcelUtil<PowerEnergySparePartsRegistration> util = new ExcelUtil<>(PowerEnergySparePartsRegistration.class);
   util.exportExcel(response, list, "备件登记数据");
   ```

4. **结果**
   - 生成包含图片的Excel文件
   - 图片自动嵌入到对应单元格中
   - 图片尺寸根据注解自动调整

### 导入流程

1. **上传Excel文件**
   - 支持.xlsx和.xls格式
   - 文件中可包含嵌入的图片

2. **图片提取**
   ```java
   List<PowerEnergySparePartsRegistration> list = util.importExcel(inputStream);
   ```

3. **图片处理**
   - 自动提取Excel中的图片
   - 保存到服务器本地路径: `/profile/excel-images/`
   - 生成唯一文件名避免冲突

4. **数据验证**
   - 验证必填字段
   - 验证图片格式
   - 检查重复记录

5. **数据保存**
   - 图片路径保存到数据库
   - 支持新增和更新模式

## 图片存储结构

### 存储路径
```
{ruoyi.profile}/excel-images/
├── 2025/01/28/
│   ├── uuid1.jpg
│   ├── uuid2.png
│   └── ...
└── ...
```

### 路径格式
- **完整路径**: `/media/tao_iot/ruoyi/uploadPath/excel-images/2025/01/28/uuid.jpg`
- **数据库存储**: `/excel-images/2025/01/28/uuid.jpg`
- **访问URL**: `http://domain/profile/excel-images/2025/01/28/uuid.jpg`

## 配置要求

### 1. 系统配置 (application.yml)
```yaml
ruoyi:
  profile: /media/tao_iot/ruoyi/uploadPath
```

### 2. 权限配置
```
ems/info:powerEnergyRegistration:import
ems/info:powerEnergyRegistration:export
ems/info:powerEnergyRegistration:list
```

### 3. 文件系统要求
- 确保上传目录有读写权限
- 预留足够磁盘空间
- 定期清理临时文件

## 错误处理

### 常见错误及解决方案

1. **图片格式不支持**
   - 错误: `图片格式不支持: xxx.tiff`
   - 解决: 使用支持的格式 (jpg/png/gif/bmp)

2. **文件路径不存在**
   - 错误: `图片文件不存在: /path/to/image.jpg`
   - 解决: 检查图片路径是否正确

3. **权限不足**
   - 错误: `创建图片存储目录失败`
   - 解决: 检查文件系统权限

4. **内存不足**
   - 错误: `OutOfMemoryError`
   - 解决: 增加JVM内存或分批处理

### 异常处理机制

1. **导入失败时自动清理临时图片**
2. **详细的错误信息反馈**
3. **事务回滚保证数据一致性**
4. **日志记录便于问题排查**

## 性能优化建议

### 1. 图片处理优化
- 控制图片尺寸 (建议 < 1MB)
- 批量处理时分页处理
- 使用图片压缩减少存储空间

### 2. Excel处理优化
- 大数据量时使用SXSSFWorkbook流式处理
- 设置合适的缓存行数 (默认500)
- 及时释放资源避免内存泄漏

### 3. 麒麟系统优化
- 使用本地高速存储
- 配置合适的文件系统权限
- 定期清理临时文件

## 安全考虑

### 1. 文件安全
- 验证上传文件类型
- 限制文件大小
- 扫描恶意文件

### 2. 路径安全
- 防止路径遍历攻击
- 使用相对路径存储
- 验证文件扩展名

### 3. 权限控制
- 基于角色的访问控制
- 操作日志记录
- 敏感数据脱敏

## 测试用例

### 1. 功能测试
- [x] 导出带图片的Excel文件
- [x] 导入含图片的Excel文件
- [x] 图片格式验证
- [x] 错误处理机制

### 2. 性能测试
- [ ] 大量数据导出性能
- [ ] 大量图片处理性能
- [ ] 并发访问压力测试

### 3. 兼容性测试
- [x] 不同Excel版本兼容性
- [x] 不同图片格式支持
- [x] 麒麟系统环境测试

## 维护指南

### 1. 日常维护
- 监控磁盘空间使用
- 清理过期临时文件
- 检查错误日志

### 2. 故障排查
- 检查文件系统权限
- 验证图片路径正确性
- 分析异常日志信息

### 3. 性能监控
- 监控内存使用情况
- 跟踪处理时间
- 分析并发性能

## 扩展功能

### 1. 图片处理增强
- 图片压缩
- 格式转换
- 水印添加

### 2. 存储扩展
- 分布式文件存储
- 对象存储集成
- 图片CDN加速

### 3. 功能扩展
- 批量图片处理
- 图片预览功能
- 历史版本管理