u

2026-10-13 22:32:50 +08:00
1 parent f3936cec61
commit 15e0ae5b67
@@ -0,0 +1,124 @@
+---
+title: 导出
+description: 列表导出、行数统计与合计查询
+pageClass: g3-api
+---
+
+# 导出
+
+导出接口，前缀 `/export/**`。三个接口**走完全相同的权限链路与同一套聚合 SQL**，因此「共 N 条」、列表底部合计与导出文件里的内容必然一致。
+
+| 接口 | 返回 | 用途 |
+|---|---|---|
+| `/export/list` | **文件流**（xlsx 或 zip） | 导出列表 |
+| `/export/count` | JSON | 批量导出弹窗的「共 N 条」 |
+| `/export/totals` | JSON | 列表底部的「总合计」 |
+
+<G3ApiParams title="共同的请求字段">
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `moduleId` | string | 是 | 模块编码（决定列、查询表与权限） |
+| `searchCondition` | string | | 查询条件（布尔表达式片段） |
+| `orderBy` | string | | 排序，如 `b_id ASC`，多列逗号分隔 |
+| `rowKeys` | any[] | | 勾选行的主键；**传了就是「按勾选导出」** |
+| `keyField` | string | | 配合 `rowKeys` 的主键列名 |
+| `columns` | string[] | | 指定导出列（默认按模块配置） |
+| `rangeStart` / `rangeEnd` | int | | 行号区间（1 起，闭区间），导出当前页/区间 |
+| `volumeSize` | int | | 分卷大小；传了则返回 **zip**，按此条数分卷 |
+| `withSummary` | bool | | 是否输出合计行，**默认 `true`** |
+
+</G3ApiParams>
+
+## `POST` `/export/list`
+
+导出并直接返回文件流。
+
+<G3ApiPayload title="请求体">
+
+```json
+{
+  "moduleId": "v_b_othercompany",
+  "searchCondition": "b_canuse = 1",
+  "orderBy": "b_id ASC",
+  "withSummary": true
+}
+```
+
+</G3ApiPayload>
+
+**响应不是 JSON**，而是文件流，按 `Content-Type` 区分：
+
+| 场景 | Content-Type | 说明 |
+|---|---|---|
+| 普通导出 | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` | 单个 xlsx |
+| 分卷导出（传了 `volumeSize`） | `application/zip` | 多个 xlsx 打包 |
+
+响应头带 `Content-Disposition: attachment; filename*=UTF-8''...`（文件名已做 URL 编码，中文名可直接还原）。
+
+**几种请求形态的差异**：
+
+| 形态 | 传什么 | 结果 |
+|---|---|---|
+| 全部导出 | 不传 `rowKeys` / 区间 | 当前条件下的**全部行**（不是当前页） |
+| 勾选导出 | `rowKeys` + `keyField` | 只导出选中的行 |
+| 区间导出 | `rangeStart` / `rangeEnd` | 导出指定行号区间 |
+| 分卷导出 | `volumeSize` | 按条数切成多个 xlsx，打包返回 |
+
+> `rowKeys` 里的数字主键**按原值透传**，不做字符串化——否则数字主键变成字符串后索引失效。
+
+## `POST` `/export/count`
+
+符合条件的行数。请求字段同上（通常只传 `moduleId` / `searchCondition`）。
+
+<G3ApiPayload title="响应" :code="0">
+
+```json
+{
+  "code": 0,
+  "message": "操作成功",
+  "data": { "total": 128 }
+}
+```
+
+</G3ApiPayload>
+
+> 因为与导出共用同一条权限链路与同一套 WHERE，这个数字**与真正导出的行数一致**——可以直接用来做「共 N 条」提示。
+
+## `POST` `/export/totals`
+
+各合计列的聚合值。请求字段同上。
+
+<G3ApiPayload title="响应" :code="0">
+
+```json
+{
+  "code": 0,
+  "message": "操作成功",
+  "data": {
+    "b_amount": 123456.78,
+    "b_qty": 320
+  }
+}
+```
+
+</G3ApiPayload>
+
+返回的键是**列名**，值是聚合结果（`sum` / `count` 等，取决于模块里该列的配置）。
+
+> **没有配置任何合计列时返回空对象** ``，不是错误——前端据此不渲染合计行。
+
+## 错误与权限
+
+- **权限过滤发生在 SQL 里**：导出按 `SqlPermissionService` 的三层判定裁剪字段与数据范围。
+  - **字段权限**：`b_view=0` 或 `b_export=0` 的列会被**移除**（不会导出空列）。
+  - **数据范围**：按 `s_user_data_power` 追加条件。
+- **没有导出动作权限**时拒绝：`1000`「没有模块「x」的动作权限「export」，请联系管理员授权」。
+- **参数错误也在写流之前抛出**，所以失败时响应体仍是 JSON（HTTP 200 + `code != 0`），**不会返回半截损坏的 xlsx**。前端可**按 `Content-Type` 判断**拿到的是文件还是错误 JSON。
+
+| 场景 | 表现 |
+|---|---|
+| 模块不存在 | `1000`，`message` 含「模块」 |
+| 缺少 `moduleId` | `1000`「moduleId 不能为空」 |
+| `rangeStart` 等不是整数 | `1000`「rangeStart 必须是有效整数」 |
+| 无导出权限 | `1000`「没有模块「x」的动作权限「export」」 |