openapi: 3.0.3
info:
  title: File Domestic Warehouse Order Export Contract
  version: 1.0.0
  description: >-
    File 只持有异步任务、XLSX 文件、任务归属和下载权限。订单筛选、数据权限、分页游标及行数据由
    Order 的 DOMESTIC_WAREHOUSE_ORDER_LIST Provider 持有，File 不复制订单业务查询。
paths:
  /api/platform/v1/files/export-tasks:
    post:
      summary: 创建国内仓订单 XLSX 导出任务
      description: >-
        exportType 固定 DOMESTIC_WAREHOUSE_ORDER_LIST，format 固定 XLSX，调用人必须具有
        platform:order:export。selectedOrderNos 非空时导出勾选业务订单号；为空或省略时由 Order
        按 parameters 中当前列表筛选导出全部匹配记录，parameters 不接受 page、size 或内部数据库 ID。
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/CreateDomesticOrderExportTask'}
      responses:
        '200':
          description: 返回异步任务，初始状态 PENDING
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ExportTaskRetryState'}
        '403': {description: 缺少 platform:order:export}
  /api/platform/v1/files/export-tasks/{taskId}/retry:
    post:
      summary: 人工重试订单导出任务
      description: >-
        FAILED 任务重新开始一次执行；PENDING 且已自动失败过的退避任务立即到期并复用当前投递消息，
        不新增并发任务。RUNNING、初次等待消费及已完成任务不允许重复重试。
      parameters:
        - {name: taskId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
      responses:
        '200':
          description: 返回已重新进入立即执行队列的任务
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ExportTaskRetryState'}
        '409': {description: 任务当前状态不允许重试或已进入执行队列}
  /api/platform/v1/files/export-tasks/{taskId}/download:
    get:
      summary: 下载本人已完成的订单导出文件
      parameters:
        - {name: taskId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
      responses:
        '200':
          description: XLSX 文件；他人任务仅 platform:download:all 可下载
          headers:
            Cache-Control: {schema: {type: string, example: no-store}}
            Content-Disposition: {schema: {type: string, example: attachment}}
          content:
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              schema: {type: string, format: binary}
components:
  schemas:
    ExportTaskRetryState:
      type: object
      required: [id, status, attemptCount, maxAttempts]
      properties:
        id: {type: string, pattern: '^[1-9][0-9]*$'}
        status: {type: string, enum: [PENDING, RUNNING, SUCCEEDED, FAILED, EXPIRED]}
        failureMessage: {type: string, nullable: true}
        attemptCount: {type: integer, minimum: 0}
        maxAttempts: {type: integer, minimum: 1}
        nextRetryAt: {type: string, format: date-time, nullable: true}
    CreateDomesticOrderExportTask:
      type: object
      required: [exportType, format, taskName, parameters]
      properties:
        exportType: {type: string, enum: [DOMESTIC_WAREHOUSE_ORDER_LIST]}
        format: {type: string, enum: [XLSX]}
        taskName: {type: string, minLength: 1, maxLength: 128}
        parameters: {$ref: '#/components/schemas/DomesticOrderExportParameters'}
    DomesticOrderExportParameters:
      type: object
      description: >-
        透传给 Order Provider；selectedOrderNos 非空时优先，其余字段与平台订单列表当前筛选一致。
      properties:
        selectedOrderNos:
          type: array
          maxItems: 5000
          uniqueItems: true
          items: {type: string, minLength: 1, maxLength: 64, description: 订单业务编号}
        tenantId: {type: string, pattern: '^[1-9][0-9]*$'}
        keyword: {type: string, maxLength: 64}
        orderNo: {type: string, maxLength: 64}
        mainStatus: {type: string}
        customerId: {type: string, pattern: '^[1-9][0-9]*$'}
        receivingWarehouseId: {type: string, pattern: '^[1-9][0-9]*$'}
        destinationWarehouseId: {type: string, pattern: '^[1-9][0-9]*$'}
        inboundCode: {type: string, maxLength: 64}
        internalOrderStatus: {type: string, maxLength: 32}
        expectedArrivalDate: {type: string, format: date}
        feeReviewStatus: {type: string}
        channelName: {type: string, maxLength: 128}
        containerNo: {type: string, maxLength: 64}
        cabinetNo: {type: string, maxLength: 64}
        sailingDate: {type: string, format: date}
        loaded: {type: boolean}
        fullContainer: {type: boolean}
        measurementReviewStatus: {type: string}
        fbaCode: {type: string, maxLength: 64}
        createdFrom: {type: string, format: date-time}
        createdTo: {type: string, format: date-time}
    DomesticOrderExportColumns:
      type: object
      description: Provider schemaVersion=1 固定列顺序；不包含任何内部数据库 ID。
      properties:
        inboundCode: {type: string, title: 入仓码}
        orderNo: {type: string, title: 订单号}
        mainStatus: {type: string, title: 订单主状态}
        customerName: {type: string, title: 客户}
        channelName: {type: string, title: 渠道}
        channelChanged: {type: string, title: 曾变更渠道, description: 是或否}
        receivingWarehouseName: {type: string, title: 定位仓库}
        destinationWarehouseName: {type: string, title: 交货仓}
        expectedShipDate: {type: string, format: date, title: 预计出运日期}
        expectedArrivalAt: {type: string, format: date-time, title: 预计到货时间}
        expectedVolumeCbm: {type: number, title: 预计体积(m³)}
        totalPackageCount: {type: integer, title: 箱数}
        totalQuantity: {type: integer, title: 产品数量}
        actualGrossWeightKg: {type: number, title: 实测毛重(kg)}
        actualVolumeCbm: {type: number, title: 实测体积(m³)}
        chargeableWeightKg: {type: number, title: 计费重量(kg)}
        chargeableVolumeCbm: {type: number, title: 计费体积(m³)}
        feeReviewStatus: {type: string, title: 费用审核状态}
        skuNos: {type: string, title: SKU}
        taxMode: {type: string, title: 报关方式}
        containerMode: {type: string, title: 装柜方式}
        customsInspection: {type: string, title: 是否商检, description: 是或否}
        containerNo: {type: string, title: 集装箱号}
        cabinetNo: {type: string, title: 柜次号}
        vesselName: {type: string, title: 船名}
        voyageNo: {type: string, title: 航次}
        createdAt: {type: string, format: date-time, title: 创建时间}