优化

2026-08-03 18:28:35 +08:00
parent eac3da9dd8
commit fdb1e8af1c
43 changed files with 1707 additions and 69 deletions
@@ -0,0 +1,161 @@
+# 公共导出与下载中心接入说明
+
+## 1. 目标与边界
+
+`file-service` 统一承载异步导出任务、XLSX 文件生成结果、过期清理和下载鉴权。业务服务仍是业务数据唯一事实来源，通过内部、只读、分批接口向 File 提供导出数据。
+
+- 浏览器不得拉取全部分页后自行生成 Excel。
+- File 不跨库查询 IAM、Order、Warehouse 等业务数据库。
+- 任务不保存用户 Bearer Token；服务间调用使用 `X-Internal-Service-Token`。
+- 当前首个导出类型为 `CUSTOMER_LIST`，数据由 IAM 提供。
+- 当前存储实现沿用 `FILE_STORAGE_ROOT` 下的共享目录；生产多实例必须挂载同一持久化目录，后续可替换为对象存储。
+
+## 2. 调用流程
+
+```text
+Admin/Client
+  -> POST /api/platform/v1/files/export-tasks
+  -> file_export_task(PENDING)
+  -> File worker 原子领取(RUNNING)
+  -> 业务服务 internal export API（最多 500 条/批）
+  -> SXSSFWorkbook 流式生成 XLSX
+  -> file_export_task(SUCCEEDED)
+  -> GET /api/platform/v1/files/export-tasks/{id}/download
+```
+
+任务状态只允许：
+
+```text
+PENDING -> RUNNING -> SUCCEEDED
+                   -> FAILED -> PENDING（手工重试）
+SUCCEEDED -> EXPIRED
+```
+
+服务重启后数据库中的 `PENDING` 会继续处理；超过配置阈值的 `RUNNING` 会重新排队。多个 File 实例通过 `PENDING` 条件更新原子领取，只有一个实例能成功。
+
+## 3. 平台公开接口
+
+所有接口都经过 Gateway 的现有 `/api/platform/v1/files/**` 路由。
+
+### 3.1 创建导出任务
+
+`POST /api/platform/v1/files/export-tasks`
+
+```json
+{
+  "exportType": "CUSTOMER_LIST",
+  "format": "XLSX",
+  "taskName": "客户列表",
+  "parameters": {
+    "keyword": "柏悦",
+    "status": "ACTIVE"
+  }
+}
+```
+
+创建接口按 `exportType` 校验来源权限。客户导出要求 `platform:customer:export`。筛选参数在创建时形成快照，后续页面修改筛选条件不会改变已提交任务。
+
+### 3.2 下载中心列表
+
+`GET /api/platform/v1/files/export-tasks?page=1&size=20&exportType=CUSTOMER_LIST&status=SUCCEEDED&requestedFrom=2026-08-01&requestedTo=2026-08-03`
+
+需要 `platform:download:list`。默认只返回当前登录用户创建的任务；拥有 `platform:download:all` 时可查看同一租户和应用域内所有用户任务。
+
+### 3.3 任务详情、下载和重试
+
+- `GET /api/platform/v1/files/export-tasks/{id}`
+- `GET /api/platform/v1/files/export-tasks/{id}/download`
+- `POST /api/platform/v1/files/export-tasks/{id}/retry`
+
+下载仅允许 `SUCCEEDED` 且未过期的任务。重试仅允许 `FAILED`，并重新校验该导出类型的来源权限。服务端始终校验任务租户、应用域和申请人归属，前端按钮隐藏不能替代鉴权。
+
+## 4. IAM 客户数据提供契约
+
+File 调用：
+
+`GET /internal/iam/exports/customers?cursor={lastId}&limit=500&keyword={keyword}&status={status}`
+
+请求头：
+
+```http
+X-Internal-Service-Token: ${INTERNAL_SERVICE_TOKEN}
+```
+
+响应：
+
+```json
+{
+  "code": "200",
+  "data": {
+    "records": [],
+    "nextCursor": 190000000000000001,
+    "hasMore": false
+  }
+}
+```
+
+IAM 按租户 ID 升序游标读取，只查询 `tenant_type=MERCHANT`，并复用客户列表的 `keyword/status` 语义。导出 DTO 与平台列表 DTO 分离，因此不会复用列表中的电话和邮箱脱敏结果。
+
+## 5. 新增其他导出类型
+
+以订单导出为例：
+
+1. 数据所属服务提供带内部令牌校验的只读游标接口，不允许 File 直接访问其数据库。
+2. 在 File 增加一个 `ExportTaskHandler` Bean：
+   - `exportType()` 返回稳定编码，例如 `FIRST_LEG_ORDER_LIST`；
+   - `requiredPermission()` 返回创建该任务所需的业务权限；
+   - `export(...)` 分批调用来源服务、流式写入文件并报告进度。
+3. 增加对应 Feign Client 和导出专用 DTO，不复用面向页面的脱敏或分页 DTO。
+4. 添加稳定权限资源、管理员授权和前端任务类型显示。
+5. 增加处理器 XLSX 内容测试、来源接口筛选/游标测试和前端提交测试。
+
+不要在公共 Controller 中增加按类型展开的业务查询分支；类型扩展通过 Spring 注入的 `ExportTaskHandler` 注册表完成。
+
+## 6. 存储、保留与配置
+
+```yaml
+baiyue:
+  file:
+    storage-root: ${FILE_STORAGE_ROOT}
+    export:
+      retention-days: ${FILE_EXPORT_RETENTION_DAYS:7}
+      worker-delay-ms: ${FILE_EXPORT_WORKER_DELAY_MS:2000}
+      stale-running-minutes: ${FILE_EXPORT_STALE_RUNNING_MINUTES:30}
+```
+
+导出文件位于 `${FILE_STORAGE_ROOT}/exports/{taskId}/{uuid}.xlsx`。`object_key` 必须匹配服务端固定格式，任意绝对路径、`..` 或非 XLSX 后缀都会被拒绝。任务过期后先删除文件，再标记 `EXPIRED`。
+
+## 7. SQL 与部署顺序
+
+新环境：
+
+1. 执行 `iam/src/main/resources/db/phase1-admin-rbac.sql` 及后续 IAM 权限脚本。
+2. 执行 `file/src/main/resources/db/file.sql` 创建 `file_export_task`。
+3. 部署 IAM，再部署 File，最后部署 Admin 静态资源。
+
+现有测试环境可执行 `deploy/sql/2026-07-31一期回归测试环境增量迁移.sql`。脚本幂等创建任务表并补齐：
+
+- `platform:customer:export`
+- `platform:download:list`
+- `platform:download:all`
+
+File 启动前必须确认 `FILE_STORAGE_ROOT` 是持久化且可写的共享目录。
+
+## 8. 错误与追踪
+
+- 创建、列表和重试使用统一 `ApiResponse`，失败记录业务码、`requestId`、`traceId`。
+- 下载接口成功返回文件流；失败仍由统一异常处理返回 JSON 错误。
+- 来源服务不可用或返回非成功业务码时任务进入 `FAILED`，下载中心展示可理解的失败原因。
+- File 日志使用任务 ID 和导出类型关联故障；不得打印内部令牌、Bearer Token 或完整导出数据。
+
+## 9. 验收清单
+
+- 创建任务后浏览器没有批量调用业务列表，也没有生成 HTML `.xls`。
+- 当前筛选条件原样进入 `parameters_json`。
+- 两个 worker 同时领取时只有一个能将任务从 `PENDING` 更新为 `RUNNING`。
+- XLSX 可被标准办公软件打开，表头和数据列匹配。
+- 普通用户看不到、下载不了其他用户任务；`platform:download:all` 用户可以。
+- `FAILED` 可以重试，其他状态不能重试。
+- 过期任务不能下载，文件被清理。
+- 服务重启后 `PENDING` 继续执行，超时 `RUNNING` 能重新排队。
+- Admin 下载中心覆盖加载、空数据、失败、处理中、完成、失败、过期和窄屏操作状态。
@@ -83,7 +83,7 @@ baiyue-firstleg/
 | `firstleg` | `firstleg-service` | 9202 | `baiyue_firstleg` | 履约任务、操作分配和分配历史；不是订单主数据服务 |
 | `order` | `order-service` | 9204 | `baiyue_order` | 订单草稿、编辑、提交、详情、状态历史、货物、往来单位快照、内部备注和 Outbox |
 | `warehouse` | `warehouse-service` | 9205 | `baiyue_warehouse` | 仓库、仓库地址、服务能力、启停校验，以及往来单位查询；往来单位不单独拆服务 |
-| `file` | `file-service` | 9206 | `baiyue_file` | 文件存储与鉴权；当前主要实现企业资质、营业执照上传和预览 |
+| `file` | `file-service` | 9206 | `baiyue_file` | 文件存储与鉴权；实现企业资质上传预览及公共异步导出、下载中心 |
 | `print` | `print-service` | 9207 | `baiyue_print` | 打印中心边界已经建立；当前主要是服务骨架、健康检查和数据库结构，打印模板与任务仍需继续完善 |
 | `integration-service` | `integration-service` | 9210 | 无 | 百度 OCR、Amazon SP-API 等第三方适配器和启停状态；默认关闭外部调用 |
 | `event-bridge-service` | `event-bridge-service` | 9300 | `baiyue_event_bridge` | 国内外事件接收、签名/内部令牌保护、幂等 Inbox 和接收结果 |
@@ -177,6 +177,8 @@ IAM 以 `tenant_id` 作为核心隔离维度，同时维护两套访问域：商

 - `QualificationFileController`：商户端企业资质文件
 - `PlatformQualificationFileController`：平台端鉴权查看
+- `PlatformExportTaskController`：平台异步导出任务、下载与失败重试
+- `ExportTaskHandler`：业务导出类型扩展点；接入规则见 `docs/公共导出与下载中心接入说明.md`
 - `QualificationFileStorage`：存储抽象
 - `LocalQualificationStorage`：当前本地磁盘实现
 - `IamQualificationClient`：校验企业资质访问权限