导入导出功能接入指南

一、接口说明

1.1 导入接口（TaskImportController）

创建导入任务：

POST /sys/v1/task/import/create
Content-Type: multipart/form-data

file: <Excel文件>
taskType: dictImport
taskParam: {"overwrite": true}  # 可选参数

响应示例：

{
    "code": 200,
    "data": 12345,
    "message": "成功创建导入任务"
}

查询导入状态：

GET /sys/v1/task/import/status?id=12345

响应示例：

{
    "code": 200,
    "data": "SUCCESS",
    "message": "获取任务执行状态"
}

1.2 导出接口（TaskExportController）

创建导出任务：

POST /sys/v1/task/export/create
Content-Type: application/json

{
    "taskType": "dictExport",
    "taskParam": {
        "dictCode": "sys*",
        "dictName": ""
    }
}

响应示例：

{
    "code": 200,
    "data": 12346,
    "message": "成功创建异步任务"
}

二、Handler 实现示例

2.1 导入 Handler（DictImportHandler）

完整代码：DictImportHandler.java

@Component
public class DictImportHandler extends AbstractImportHandler {

    @Autowired
    DictService dictService;

    public DictImportHandler() {
        super("dictImport", "字典导入", DictImportDTO.class.getName());
    }

    @Override
    protected Object doImport(TaskExecuteDTO executeDTO) {
        List<DictImportDTO> list = (List<DictImportDTO>) executeDTO.getFileList();
        return dictService.importExcel(list);
    }
}

实现步骤：

1. 继承 AbstractImportHandler
2. 构造函数注册任务类型：super("taskType", "任务名称", "导入DTO类名")
3. 实现 doImport() 方法：
   • 从 executeDTO.getFileList() 获取解析后的Excel数据
   • 调用业务Service处理数据
   • 返回处理结果（会自动生成Excel并上传OSS）

导入DTO必须包含的字段：

错误信息返回方式：

在业务Service中处理每条数据时，设置 checkResult 和 checkMsg：

// DictService.importExcel() 内部处理逻辑
for (DictImportDTO dto : list) {
    try {
        // 数据校验
        validate(dto);
  
        // 保存数据
        dictMapper.insert(convertToEntity(dto));
  
        // 标记成功
        dto.setCheckResult("1");
        dto.setCheckMsg("导入成功");
    } catch (Exception e) {
        // 标记失败并记录错误信息
        dto.setCheckResult("0");
        dto.setCheckMsg("导入失败: " + e.getMessage());
    }
}
return list;

注意点：

• 返回的List会自动生成Excel并上传到OSS
• 任务完成后，通过 GET /sys/v1/task/{id} 获取 fileId
• 通过OSS下载地址下载包含错误信息的结果文件

2.2 导出 Handler（DictExportHandler）

完整代码：DictExportHandler.java

@Component
public class DictExportHandler extends AbstractExportHandler {

    @Autowired
    DictService dictService;

    public DictExportHandler() {
        super("dictExport", "字典导出", DictExportViewDTO.class.getName());
    }

    @Override
    protected Object doExport(Object taskParam) {
        DictExportDTO dto = ObjectUtils.objToClass(taskParam, DictExportDTO.class);
        return dictService.exportExcel(dto);
    }
}

实现步骤：

1. 继承 AbstractExportHandler
2. 构造函数注册任务类型：super("taskType", "任务名称", "导出DTO类名")
3. 实现 doExport() 方法：
   • 用 ObjectUtils.objToClass() 转换查询参数
   • 调用业务Service查询数据
   • 返回查询结果（会自动生成Excel并上传OSS）

注意点：

• 返回的List会自动生成Excel并上传到OSS
• 任务完成后，通过 GET /sys/v1/task/{id} 获取 fileId
• 通过OSS下载地址下载导出文件

三、状态说明

四、文件下载

任务执行成功后，可通过以下方式下载文件：

4.1 下载地址

下载地址格式：

http://192.168.168.207:30000/sieapi/kernel/oss/file/manager/download/id?id={fileId}

4.2 获取 fileId

GET /sys/v1/task/{taskId}

响应示例：

{
    "id": 12345,
    "fileId": "813084343742533",
    "status": "SUCCESS"
}

4.3 文件用途

4.4 下载示例

http://192.168.168.207:30000/sieapi/kernel/oss/file/manager/download/id?id=813084343742533

五、错误处理

5.1 导入错误处理

导入时的错误信息返回流程：

1. 逐条校验：在Service层对每条数据进行校验
2. 记录状态：设置 checkResult 和 checkMsg 字段
3. 返回结果：返回包含所有记录（成功+失败）的List
4. 生成文件：框架自动将结果List生成Excel并上传OSS
5. 下载查看：通过 fileId 下载结果文件查看错误详情

示例：

// 导入结果Excel包含的字段
public class DictImportDTO {
    private String dictCode;
    private String dictName;
    private String parentPath;
  
    // 必须包含的结果字段
    private String checkResult;  // "1"=成功, "0"=失败
    private String checkMsg;     // 错误信息
}

5.2 任务失败处理

任务失败时：

• 查询任务详情获取错误信息：GET /sys/v1/task/{id}
• 错误信息在 errorMessage 字段
• 完整堆栈在 errorStack 字段

重试失败任务：

POST /sys/v1/task/retry/12345

六、Handler 注意事项

6.1 导入 Handler

1. taskType 必须唯一 — 启动时会检查重复，重复会报错
2. 导入DTO必须字段 — 必须包含 checkResult 和 checkMsg 字段
3. Handler 必须加 @Component — 否则不会被自动注册
4. 错误信息设置 — 在Service层处理每条数据时，必须设置 checkResult 和 checkMsg
5. 返回值 — doImport() 必须返回 List<?>，框架会自动生成Excel

6.2 导出 Handler

1. taskType 必须唯一 — 启动时会检查重复，重复会报错
2. 导出DTO字段 — 字段上使用 @ExcelProperty 注解定义Excel列名
3. Handler 必须加 @Component — 否则不会被自动注册
4. 返回值 — doExport() 必须返回 List<?>，框架会自动生成Excel