feat(selfop): provide frozen turnover batches for backend Excel exports

2026-10-15 15:00:03 +08:00
parent 22d79e08f9
commit dbb93a06c2
18 changed files with 546 additions and 9 deletions
@@ -21,9 +21,11 @@ import java.time.LocalDateTime;
 import java.util.Locale;
 import java.util.Map;
 import java.util.TreeMap;
+import java.util.Set;

@Service
 public class ExportTaskService {
+    private static final String TURNOVER = "SELFOP_INVENTORY_TURNOVER";
    @Resource private ExportTaskRepository repository;
    @Resource private ExportStorage storage;
    @Resource private ObjectMapper objectMapper;
@@ -34,6 +36,7 @@ public class ExportTaskService {
    public ExportTaskResponse create(AuthenticatedUser user, CreateExportTaskRequest request) {
        requirePlatform(user);
        String type = request.exportType().trim().toUpperCase(Locale.ROOT);
+        if (TURNOVER.equals(type) && user.impersonated()) throw new BizException(ResultCode.FORBIDDEN, "平台自营导出不支持代登录");
        String format = request.format().trim().toUpperCase(Locale.ROOT);
        var definition = registry.require(type);
        if (!"XLSX".equals(format)) throw new BizException(ResultCode.VALIDATION_FAILED, "当前仅支持 XLSX 格式");
@@ -135,6 +138,9 @@ public class ExportTaskService {
    }

    private void requireExportCostAccess(AuthenticatedUser user, FileExportTask task) {
+        if (TURNOVER.equals(task.getExportType()) && (user.impersonated() || !user.permissions().contains("platform:self-operated-analytics:export"))) {
+            throw new BizException(ResultCode.FORBIDDEN, "缺少平台自营导出权限");
+        }
        if (!"TRIP_OPERATIONS_LIST".equals(task.getExportType())) return;
        try {
            if (objectMapper.readTree(task.getParametersJson()).path("costVisible").asBoolean(false)
@@ -172,11 +178,14 @@ public class ExportTaskService {
        }
        values.forEach((key, value) -> {
            if (key == null || key.isBlank() || key.length() > 64) throw new BizException(ResultCode.VALIDATION_FAILED, "导出筛选键无效");
-            validateParameterValue(value, 1);
+            if (TURNOVER.equals(type) && "snapshotContext".equals(key)) {
+                if (!(value instanceof String text) || text.isBlank() || text.length() > 16000)
+                    throw new BizException(ResultCode.VALIDATION_FAILED, "库存周转查询版本无效，请刷新后重新导出");
+            } else validateParameterValue(value, 1);
        });
        try {
            int maxBytes = ExportSchemaContracts.DOMESTIC_WAREHOUSE_ORDER_LIST.equals(type)
-                ? 512 * 1024 : 4096;
+                ? 512 * 1024 : TURNOVER.equals(type) ? 64 * 1024 : 4096;
            if (objectMapper.writeValueAsBytes(values).length > maxBytes) {
                throw new BizException(ResultCode.VALIDATION_FAILED,
                    "导出筛选条件不能超过 " + (maxBytes / 1024) + "KB");
@@ -210,6 +219,22 @@ public class ExportTaskService {
    }

    private void validateTypeParameters(String type, Map<String, Object> parameters) {
+        if (TURNOVER.equals(type)) {
+            Map<String,Object> values=parameters==null?Map.of():parameters;
+            if (!values.keySet().containsAll(Set.of("sourceAccount","warehouseCode","endDate","baseWindowDays","snapshotContext","columns","expectedTotal"))
+                || !Set.of("sourceAccount","warehouseCode","endDate","baseWindowDays","groupBy","customerCodes","sku","focus","coverageDaysThreshold","turnoverStatus","sortBy","hideZeroInventory","snapshotContext","columns","expectedTotal").containsAll(values.keySet()))
+                throw new BizException(ResultCode.VALIDATION_FAILED, "库存周转导出筛选无效");
+            if (!(values.get("columns") instanceof java.util.List<?> columns) || columns.isEmpty() || columns.size()>30
+                || columns.stream().anyMatch(v -> !(v instanceof String)) || new java.util.HashSet<>(columns).size()!=columns.size())
+                throw new BizException(ResultCode.VALIDATION_FAILED, "库存周转导出列无效");
+            if (values.containsKey("customerCodes") && (!(values.get("customerCodes") instanceof java.util.List<?> owners) || owners.size()>100 || owners.stream().anyMatch(v -> !(v instanceof String))))
+                throw new BizException(ResultCode.VALIDATION_FAILED, "库存周转货主范围无效");
+            try {
+                long count=new java.math.BigDecimal(String.valueOf(values.get("expectedTotal"))).longValueExact();
+                if(count<0 || count>200000) throw new ArithmeticException();
+            } catch(RuntimeException e) { throw new BizException(ResultCode.VALIDATION_FAILED, "库存周转导出条数无效"); }
+            return;
+        }
        if (!ExportSchemaContracts.BUY_DECLARATION_ITEMS.equals(type)) return;
        Map<String, Object> values = parameters == null ? Map.of() : parameters;
        if (!values.keySet().equals(java.util.Set.of("loadingPlanId"))) {
@@ -224,6 +224,15 @@ baiyue:
          max-rows: 200000
          max-attempts: 3
          batch-size: 200
+        SELFOP_INVENTORY_TURNOVER:
+          provider-service: lastleg-service
+          provider-path: /internal/exports/v1/SELFOP_INVENTORY_TURNOVER/batches
+          required-permission: platform:self-operated-analytics:export
+          app-scope: PLATFORM
+          enabled: true
+          max-rows: 200000
+          max-attempts: 3
+          batch-size: 100
        OVERSEAS_INVENTORY_LEDGER:
          provider-service: lastleg-service
          provider-path: /internal/exports/v1/OVERSEAS_INVENTORY_LEDGER/batches
@@ -0,0 +1,50 @@
+openapi: 3.0.3
+info:
+  title: 库存周转后台导出
+  version: 1.0.0
+  description: File 下载中心生成 XLSX，Lastleg 内部 Provider 按固定库存周转版本供数。浏览器不分页取数、不生成文件。
+paths:
+  /api/platform/v1/files/export-tasks:
+    post:
+      summary: 提交库存周转 Excel 导出
+      description: |
+        仅平台、非代登录身份及 platform:self-operated-analytics:export 权限。
+        保留列表的 sourceAccount、warehouseCode、endDate、baseWindowDays、groupBy、customerCodes、sku、focus、coverageDaysThreshold、turnoverStatus、sortBy、hideZeroInventory、snapshotContext。
+        columns 为当前显示列的有序白名单键，服务端决定列名、格式并追加周转率证据列；expectedTotal 为已查询总条数，范围0至200000。
+        不接受 current/size/includeOverview。snapshotContext 最长16000字符，整组参数最大64KiB。空结果生成只有表头的文件。
+        后台每批最多100条，沿用固定上下文30分钟有效期；过期、服务重启或历史版本失效须刷新列表重新提交，不自动改用新版本。
+        版本或条数变化、分页缺失、超行数、生成失败时不提供部分文件。下载中心复用进度、临时失败退避重试、归属校验及过期规则。
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [exportType, format, taskName, parameters]
+              properties:
+                exportType: {type: string, enum: [SELFOP_INVENTORY_TURNOVER]}
+                format: {type: string, enum: [XLSX]}
+                taskName: {type: string, maxLength: 128}
+                parameters:
+                  type: object
+                  required: [sourceAccount, warehouseCode, endDate, baseWindowDays, snapshotContext, columns, expectedTotal]
+                  properties:
+                    snapshotContext: {type: string, minLength: 1, maxLength: 16000}
+                    columns: {type: array, minItems: 1, maxItems: 30, uniqueItems: true, items: {type: string}}
+                    expectedTotal: {type: integer, minimum: 0, maximum: 200000}
+                  additionalProperties: true
+      responses:
+        '200': {description: ApiResponse 包装下载中心任务；业务错误遵循通用 code 契约}
+        '403': {description: 无平台自营导出权限或非平台身份}
+  /api/platform/v1/files/export-tasks/{taskId}/download:
+    get:
+      summary: 下载后台生成的库存周转 Excel
+      description: 校验任务归属、完成状态、有效期，以及当前非代登录身份和平台自营导出权限。
+      parameters:
+        - {name: taskId, in: path, required: true, schema: {type: string}}
+      responses:
+        '200':
+          description: XLSX 文件
+          content:
+            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
+              schema: {type: string, format: binary}