# 9.11 Excel 导入导出组件

:::tip 概述
前端 Excel 能力由 components/Excel 与 importFile 组件 + xlsx 库提供：导入走文件上传接口拿统计结果，导出走导出接口拿文件 URL 再下载。前后端协作协议见 [7.4 数据导入导出](../tools/excel)。
:::

## 组件与工具

| 模块 | 职责 |
|------|------|
| components/Excel | Excel 处理组件（导入解析/导出生成的前端封装） |
| components/importFile | 导入文件入口组件（选文件→上传→结果展示） |
| utils/downloadFile | 文件下载工具（导出 URL 触发浏览器下载） |
| xlsx（依赖） | SheetJS 解析/生成 |

## 导入协作流

```text
1. 页面"导入"按钮（v-permission="sys:xxx:import"）→ importFile 组件
2. 选择 xls/xlsx → POST /api/{module}/import（multipart，字段 file）
3. 后端 excel.ReadSheet → 逐行校验写入
4. 返回统计：{total, success, failed, reasons[]}
5. 组件展示结果（成功 N 条 / 失败 M 条 + 逐行原因列表）
6. 关闭后刷新列表
```

真实响应示例（example 导入）：

```json
{ "total": 100, "success": 98, "failed": 2,
  "reasons": ["第5行：案例名称为空", "第17行：写入失败 Duplicate entry..."] }
```

## 导出协作流

```text
1. 页面"导出"按钮（v-permission="sys:xxx:export"）
2. 携带当前列表筛选参数 GET /api/{module}/export
   （导出=所见：与列表同套筛选，含数据权限过滤）
3. 后端 ChunkQuery 分批 + excel.WriteSheet → 返回文件 URL
4. downloadFile 触发下载
```

## 导入模板约定

```text
表头 = 表单字段名（导出文件即导入模板——"导出→改数据→导入"闭环）
单元格全字符串解析（TrimSpace）；空行跳过
列序与后端 cellAt(row, N) 索引对应——改列序需同步后端解析
```

## 大文件注意

| 场景 | 说明 |
|------|------|
| 导出大结果集 | 后端 ChunkQuery 500/页 防 OOM；生成仍为单文件（Excel 行数上限 104 万内） |
| 导入大文件 | 逐行独立成败；超大批量建议分批导入（控制单请求耗时） |
| 导出文件有效期 | 导出文件落 /upload/temp/——受 tempExpireDays 清理，及时下载 |

## 新页面接入步骤

```text
1. 后端：Req（ImportReq 带 File 字段 / ExportReq 带筛选字段）+ logic 实现
   （参照 example 的 Import/Export 真实代码）
2. 权限节点：import/export（生成器默认自动建）
3. 前端：importFile 组件 + 导出按钮（downloadFile）
4. 列表页操作区挂两个按钮（v-permission 对齐）
```

## 排障

| 症状 | 原因 |
|------|------|
| 导入全部失败 | 表头/列序与后端解析不匹配；对照导出模板 |
| 导入部分失败 | 看 reasons 逐行原因（唯一冲突/必填缺失/字典值非法） |
| 导出内容与列表不符 | ExportReq 未带筛选字段或未走 applyFilters（对照 7.4 规范） |
| 导出 404 | 文件已被 temp 清理；重新导出立即下载 |
| 导出超时 | 结果集过大——确认 ChunkQuery 已接；拆分筛选条件分批导 |