签入版本

RXThinkCMF_Laravel13_AntdVue/zh/frontend/excel-components.md

@@ -1,10 +1,10 @@
 # 9.11 Excel 导入导出组件
 
 :::tip 概述
-本节介绍前端项目中的 Excel 导入导出组件，包括导入组件（ImportExcel）和导出功能（Export2Excel）的使用方法。
+本节介绍前端项目中的 Excel 导入导出组件，包括导入组件（ImportExcel）和导出功能（Export2Excel）的使用方法，并说明前端解析与后端导入两条链路的选择。
 :::
 
-## 导入组件
+## 导入组件（前端解析）
 
 ```vue
 <template>
@@ -22,7 +22,41 @@ const onImportSuccess = (data) => {
 </script>
 ```
 
-## 导出功能
+:::tip 前端解析 vs 后端导入
+- **前端解析（本组件）**：`xlsx` 库本地解析，适合导入前预览、无业务校验的场景；
+- **后端导入（推荐）**：`el-upload` 直传 `/api/{module}/import`，由 Service 逐行 `add()`（字典反查、唯一校验、事务隔离、错误行明细），见 [7.4 数据导入导出](/zh/tools/excel.html)。
+:::
+
+### 后端导入对接
+
+```vue
+<template>
+  <el-upload
+    :action="'/api/example/import'"
+    :headers="{ Authorization: `Bearer ${token}` }"
+    :on-success="handleImportSuccess"
+    accept=".xls,.xlsx"
+  >
+    <el-button type="primary">导入</el-button>
+  </el-upload>
+</template>
+
+<script setup>
+const handleImportSuccess = (response) => {
+  if (response.code === 0) {
+    const { count, errors } = response.data;
+    if (errors.length === 0) {
+      ElMessage.success(`成功导入 ${count} 条数据`);
+    } else {
+      ElMessage.warning(`成功 ${count} 条，失败 ${errors.length} 条`);
+      // errors: [{ row: 3, name: '...', reason: '...' }]
+    }
+  }
+};
+</script>
+```
+
+## 导出功能（前端导出）
 
 ```typescript
 import { jsonToSheetXlsx } from '@/components/Excel/src/Export2Excel';
@@ -41,17 +75,18 @@ const handleExport = () => {
 };
 ```
 
-## 后端导出对接
+## 后端导出对接（推荐）
 
 ```typescript
-// 调用后端导出接口，返回文件 URL
+// 调用后端导出接口，返回文件 URL（全量数据 + 权限控制 + 字典翻译）
 const handleExport = async () => {
-  const url = await exampleExport(searchParams.value);
-  // 下载文件
-  window.open(url);
+  const res = await exampleExport(searchParams.value);   // 文件地址
+  window.open(res);
 };
 ```
 
+后端接口由 `Controller::_export()` 封装（`#[OperationLog(TYPE_EXPORT)]` + `#[Permission]` + `ExcelService`），大数据量时 Service 内改用 `chunkExport` 分批导出。
+
 ## 导入模板下载
 
 ```typescript
@@ -66,12 +101,20 @@ const handleDownloadTemplate = async () => {
 
 | 场景 | 说明 |
 |------|------|
-| 大数据量导出 | 后端自动分批导出，避免内存溢出 |
-| 导入模板 | 第一行为表头，第二行起为数据 |
-| 字段映射 | 后端 `headerMap` 配置表头与字段的对应关系 |
-| 枚举翻译 | 导入时自动将文本转为枚举值，导出时自动将枚举值转为文本 |
+| 大数据量导出 | 后端 `chunkExport` 分批导出（回调取空终止），避免内存溢出 |
+| 导入模板 | 第一行为表头，第二行起为数据（行号反馈 `row = 索引 + 2`） |
+| 字段映射 | 后端 `headerMap` 配置表头与字段的对应关系（未声明列忽略） |
+| 枚举翻译 | 导入时 `DictCacheService::getValue` 文本转值，导出时 `serializeMaps` 值转文本 |
+| 文件限制 | 仅 `xls/xlsx`、10MB 上限、finfo MIME 检测（`_import` 内置） |
+
+## 两种方案选择
+
+| 方式 | 适用场景 | 校验 |
+|------|---------|------|
+| 前端 `ImportExcel` 解析 | 导入预览、轻量转换 | 仅格式解析 |
+| 后端 `/import` 接口 | 正式导入 | FormRequest/钩子/唯一性/字典全量校验 |
 
 ## 相关文档
 
 - [数据导入导出](/zh/tools/excel.html)
-- [上传配置详解](/zh/tools/upload-config.html)
+- [上传配置详解](/zh/tools/upload-config.html)