# Poyee Easy 包功能说明

## 概述

`com.poyee.easy` 包是 Poyee 基础框架中的一个重要组件，主要提供了基于 EasyExcel 的 Excel 导入导出功能，并且特别支持国际化（i18n）处理。该包通过封装 Alibaba EasyExcel 库，提供了更高级的功能和更简洁的 API，使得 Excel 的导入导出操作更加便捷，特别是在需要多语言支持的国际化应用场景中。

## 核心组件

### 1. EasyExcelUtil

这是一个用于 Excel 导出的工具类，主要功能包括：

- 支持普通 Excel 导出和国际化 Excel 导出
- 提供链式调用 API，如 `init()`, `i18nConfig()`, `build()` 等
- 支持文件导出和流导出两种方式
- 支持多 Sheet 导出，特别是国际化场景下的多语言 Sheet

**主要方法：**

- `init(Class<T> clazz, List<T> data)`: 初始化导出工具
- `init(Class<T> clazz, List<T> data, String sheet)`: 初始化导出工具并指定 sheet 名称
- `i18nConfig(EasyI18nConfig i18nConfig)`: 设置国际化配置
- `build()`: 构建导出工具
- `doWrite(String path)`: 导出到文件
- `doWriteStream(OutputStream out)`: 导出到输出流

**使用示例：**

```java
EasyExcelUtil<ChecklistExcelDto, Object> easyExcelUtil = EasyExcelUtil.init(ChecklistExcelDto.class, checklistExcelDtos, baseInfo.getDisplayName())
    .i18nConfig(i18nConfig)
    .build();
easyExcelUtil.doWriteStream(outputStream);
```

### 2. EasyExcelImportUtil

这是一个用于 Excel 导入的工具类，主要功能包括：

- 支持普通 Excel 导入和国际化 Excel 导入
- 提供链式调用 API，如 `create()`, `i18nConfig()`, `batch()`, `async()` 等
- 支持批量处理和异步处理导入数据
- 支持从 URL 下载 Excel 文件并解析

**主要方法：**

- `create(Class<T> clazz, Consumer<List<R>> consumer, Function<T, R> rowConverter)`: 创建导入工具
- `i18nConfig(boolean isI18n, EasyI18nConfig i18nConfig)`: 设置国际化配置
- `batch()`: 启用批量处理
- `batch(int batchCount)`: 启用批量处理并设置批处理数量
- `async(ThreadPoolExecutor executor)`: 启用异步处理
- `doRead(InputStream inputStream)`: 从输入流读取
- `doRead(String fileUrl)`: 从 URL 读取

**使用示例：**

```java
List<PaniniChecklistImport> list = new ArrayList<>();
EasyExcelImportUtil<PaniniChecklistImport, PaniniChecklistImport> importer = 
    EasyExcelImportUtil.create(PaniniChecklistImport.class, list::addAll, Function.identity())
    .i18nConfig(true, i18nConfig)
    .batch();
importer.doRead(url);
```

### 3. EasyExcelReadSheetListener

这是一个 EasyExcel 的事件监听器，用于处理 Excel 读取过程中的事件，特别是国际化数据的处理：

- 继承自 `AnalysisEventListener`，用于监听 Excel 读取过程
- 支持多 Sheet 读取，特别是国际化场景下的多语言 Sheet
- 提供数据转换和处理功能

**主要方法：**

- `EasyExcelReadSheetListener(EasyI18nConfig config, Function<T, R> rowConverter, Consumer<List<R>> consumer)`: 构造函数
- `init()`: 初始化监听器
- `invoke(T data, AnalysisContext context)`: 处理每行数据
- `doAfterAllAnalysed(AnalysisContext context)`: 所有数据解析完成后的处理

### 4. EasyI18nConfig

这是一个国际化配置类，用于配置国际化 Excel 的导入导出：

- 定义了 Sheet 的结构，包括 key、name、header 和 data 等属性
- 支持多语言配置

**主要属性：**

- `sheet`: Sheet 配置列表

**Sheet 类属性：**

- `index`: Sheet 索引
- `key`: Sheet 映射的字段
- `name`: Sheet 名称
- `header`: Sheet 头部映射
- `data`: Sheet 数据

**使用示例：**

```java
EasyI18nConfig i18nConfig = new EasyI18nConfig();
List<EasyI18nConfig.Sheet> sheetList = new ArrayList<>();
sheetList.add(new EasyI18nConfig.Sheet("playerTranslations", "player", Language.getLangEnMap()));
sheetList.add(new EasyI18nConfig.Sheet("teamTranslations", "team", Language.getLangEnMap()));
i18nConfig.setSheet(sheetList);
```

## 国际化支持

该包特别强调了对国际化的支持，主要体现在：

1. **多语言 Sheet**：支持在一个 Excel 文件中包含多个语言的 Sheet，如主数据 Sheet 和语言翻译 Sheet

2. **国际化注解**：使用 `@ExcelI18nFromat` 和 `@i18n` 注解来标记需要国际化处理的字段

3. **动态语言处理**：根据 `ServletUtils.isI18nSupport()` 判断是否需要进行国际化处理

4. **JSON 处理**：使用 fastjson 库处理国际化数据的 JSON 格式化和解析

## 业务应用

在项目中，这些工具类主要用于：

1. **Checklist 导入导出**：如 `CardChecklistBaseInfoServiceImpl` 中的 `downloadAndImport` 和 `downloadCheckList` 方法

2. **国际化数据处理**：如 `doI18nImportChecklist` 和 `downloadI18nExcelAndParseExcel` 方法

## 最佳实践

### 导出 Excel

```java
// 1. 准备数据
List<YourDto> dataList = ...

// 2. 创建国际化配置（如果需要）
EasyI18nConfig i18nConfig = new EasyI18nConfig();
List<EasyI18nConfig.Sheet> sheetList = new ArrayList<>();
sheetList.add(new EasyI18nConfig.Sheet("fieldName", "sheetName", languageMap));
i18nConfig.setSheet(sheetList);

// 3. 初始化导出工具
EasyExcelUtil<YourDto, Object> easyExcelUtil = EasyExcelUtil.init(YourDto.class, dataList, "Sheet名称")
    .i18nConfig(i18nConfig)  // 如果需要国际化
    .build();

// 4. 导出到文件或流
easyExcelUtil.doWrite("path/to/file.xlsx");  // 导出到文件
// 或
easyExcelUtil.doWriteStream(outputStream);  // 导出到流
```

### 导入 Excel

```java
// 1. 准备接收数据的集合
List<YourDto> list = new ArrayList<>();

// 2. 创建国际化配置（如果需要）
EasyI18nConfig i18nConfig = new EasyI18nConfig();
List<EasyI18nConfig.Sheet> sheetList = new ArrayList<>();
sheetList.add(new EasyI18nConfig.Sheet("fieldName", "sheetName", languageMap));
i18nConfig.setSheet(sheetList);

// 3. 创建导入工具
EasyExcelImportUtil<YourDto, YourDto> importer = 
    EasyExcelImportUtil.create(YourDto.class, list::addAll, Function.identity())
    .i18nConfig(true, i18nConfig)  // 如果需要国际化
    .batch(500)  // 批量处理，每500条处理一次
    .async(executor);  // 如果需要异步处理

// 4. 从文件或URL读取
importer.doRead(inputStream);  // 从输入流读取
// 或
importer.doRead("http://example.com/file.xlsx");  // 从URL读取
```

## 注意事项

1. 在使用国际化功能时，需要确保 DTO 类中有正确的注解标记

2. 导入大量数据时，建议使用批量处理和异步处理功能

3. 导出国际化 Excel 时，需要正确配置 EasyI18nConfig

4. 使用 URL 导入时，需要确保 URL 可访问且格式正确

## 总结

`com.poyee.easy` 包是一个专注于 Excel 处理的工具包，它基于 EasyExcel 库，提供了更高级的功能，特别是国际化支持。它通过链式 API 和注解的方式，简化了 Excel 导入导出的开发工作，并且特别适合需要多语言支持的国际化应用场景。