签入版本

2026-10-20 21:53:26 +08:00
parent 5cc3da657c
commit b33799aa63
427 changed files with 32547 additions and 1 deletions
@@ -0,0 +1,78 @@
+# 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 已接；拆分筛选条件分批导 |