9.11 Excel 导入导出组件

概述

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

组件与工具

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

导入协作流

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 导入）：

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

导出协作流

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

导入模板约定

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

大文件注意

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

新页面接入步骤

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 已接；拆分筛选条件分批导