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}