baiyue-firstleg/lastleg-service/src/main/resources/openapi/delivery-documents-v1.yaml

openapi: 3.0.3
info:
  title: 派送单三类资料
  version: 1.0.0
  description: |
    所有入口只允许平台，customerId 必须为真实派送所属客户；不得按 BOL 文本查找或复用其他客户/派送单文件。
    GET /delivery-orders 及 GET /delivery-orders/{deliveryNo} 的 order 行新增 bolNo 和 documentSummary，version/allowedActions 保持原契约。
    状态 PUT /delivery-orders/{deliveryNo}/status 请求保持 {status,expectedVersion,remark}，expectedVersion 必传。
    START_DELIVERY=DELIVERING（派送中）；COMPLETE_DELIVERY=DELIVERED（完成并记录签收时间、生成待回访）。同状态重放不重复副作用。
    资料不设必传门禁，不以三类齐全作为派送完成条件。业务失败使用统一 ApiResponse（A0422参数、A0409冲突），通常HTTP200。
security: [{ bearerAuth: [] }]
paths:
  /api/platform/v1/last-leg/delivery-orders/{deliveryNo}/documents:
    parameters:
      - { $ref: '#/components/parameters/DeliveryNo' }
      - { $ref: '#/components/parameters/CustomerId' }
    get:
      summary: 查询已保存三类资料
      description: 权限 platform:overseas-warehouse:delivery:list；空资料仍返回全部三类MISSING。上传未保存不计入摘要。
      responses:
        '200': { description: 当前快照, content: { application/json: { schema: { $ref: '#/components/schemas/DetailResponse' } } } }
    put:
      summary: 原子保存全部类别绑定与BOL号
      description: |
        权限 platform:overseas-warehouse:delivery:documents。documents为全量快照，遗漏类别清空；Admin须提交完整三类。
        同一派送单锁下校验expectedVersion、全部文件客户/派送单/类别归属后一起提交，任一失败不写任何绑定。
        保存增加派送version，与状态修改共享版本；幂等键按客户+派送单限定，同键同请求重放原结果、异请求冲突。
        替换/删除通过修改fileIds并保存表达，只解除当前绑定，历史对象和版本快照不可变保留。
      requestBody:
        required: true
        content: { application/json: { schema: { $ref: '#/components/schemas/Save' } } }
      responses:
        '200': { description: 保存结果或统一业务错误, content: { application/json: { schema: { $ref: '#/components/schemas/DetailResponse' } } } }
  /api/platform/v1/last-leg/delivery-orders/{deliveryNo}/documents/{category}/files:
    parameters:
      - { $ref: '#/components/parameters/DeliveryNo' }
      - { $ref: '#/components/parameters/CustomerId' }
      - { $ref: '#/components/parameters/Category' }
    post:
      summary: 上传一个待绑定文件
      description: |
        权限 platform:overseas-warehouse:delivery:documents。FormData唯一file，无额外幂等头。
        File沿用ARBITRARY任意格式、非空且不超过52428800字节(50MiB)，每类别最多20个文件由保存校验。
        上传仅产生不可变对象，不修改派送version或摘要；取消弹框/未保存不落绑定，不物理删除File对象。
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema: { type: object, required: [file], properties: { file: { type: string, format: binary } } }
      responses:
        '200':
          description: 单文件权威元数据
          content:
            application/json:
              schema:
                allOf:
                  - { $ref: '#/components/schemas/Envelope' }
                  - type: object
                    properties: { data: { $ref: '#/components/schemas/File' } }
  /api/platform/v1/last-leg/delivery-orders/{deliveryNo}/documents/history:
    parameters:
      - { $ref: '#/components/parameters/DeliveryNo' }
      - { $ref: '#/components/parameters/CustomerId' }
    get:
      summary: 查看不可变资料保存历史
      description: 权限 platform:overseas-warehouse:delivery:list；版本倒序，仅当前客户和派送单。
      responses:
        '200':
          description: 历史快照
          content:
            application/json:
              schema:
                allOf:
                  - { $ref: '#/components/schemas/Envelope' }
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          type: object
                          properties:
                            version: { type: integer, format: int64 }
                            operatorId: { type: string }
                            savedAt: { type: string, format: date-time }
                            snapshot: { $ref: '#/components/schemas/Detail' }
  /api/platform/v1/last-leg/delivery-orders/{deliveryNo}/documents/{category}/files/{fileId}/download:
    parameters:
      - { $ref: '#/components/parameters/DeliveryNo' }
      - { $ref: '#/components/parameters/CustomerId' }
      - { $ref: '#/components/parameters/Category' }
      - { in: path, name: fileId, required: true, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
      - { in: query, name: revisionVersion, required: false, schema: { type: integer, format: int64, minimum: 1 } }
    get:
      summary: 下载当前或指定保存版本已绑定文件
      description: 权限 platform:overseas-warehouse:delivery:list；省略revisionVersion只允许当前绑定。历史版本仍严格校验客户/单据/类别。未保存或跨单文件拒绝；附件响应no-store/nosniff。
      responses:
        '200': { description: 文件内容, content: { application/octet-stream: { schema: { type: string, format: binary } } } }
components:
  securitySchemes:
    bearerAuth: { type: http, scheme: bearer, bearerFormat: JWT }
  parameters:
    DeliveryNo: { in: path, name: deliveryNo, required: true, schema: { type: string } }
    CustomerId: { in: query, name: customerId, required: true, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
    Category: { in: path, name: category, required: true, schema: { $ref: '#/components/schemas/CategoryCode' } }
  schemas:
    CategoryCode:
      type: string
      enum: [LOADING_PHOTO, BOL, RECEIPT]
      description: 依次为装车照片、BOL文件（含签名）、签收文件（POD签收/快递签收）。BOL签名由用户提供，不进行OCR或电子签署验证。
    Save:
      type: object
      required: [expectedVersion, idempotencyKey, documents]
      properties:
        expectedVersion: { type: integer, format: int64, minimum: 0 }
        idempotencyKey: { type: string, minLength: 1, maxLength: 128 }
        bolNo: { type: string, nullable: true, maxLength: 128, description: 不作为文件复用或归属匹配依据；空值清空 }
        documents:
          type: array
          maxItems: 3
          items:
            type: object
            required: [category, fileIds]
            properties:
              category: { $ref: '#/components/schemas/CategoryCode' }
              fileIds: { type: array, maxItems: 20, uniqueItems: true, items: { type: string, pattern: '^[1-9][0-9]*$' } }
    File:
      type: object
      required: [fileId, fileName, sizeBytes, uploadedAt]
      properties:
        fileId: { type: string, pattern: '^[1-9][0-9]*$' }
        fileName: { type: string }
        contentType: { type: string, nullable: true }
        sizeBytes: { type: integer, format: int64, minimum: 1, maximum: 52428800 }
        uploadedAt: { type: string, format: date-time, description: File持久化的真实创建时间 }
    CategorySummary:
      type: object
      required: [category, status, fileCount]
      properties:
        category: { $ref: '#/components/schemas/CategoryCode' }
        status: { type: string, enum: [UPLOADED, MISSING] }
        fileCount: { type: integer, minimum: 0, maximum: 20 }
    DocumentSummary:
      type: object
      required: [uploadedCategoryCount, totalCategoryCount, categories]
      properties:
        uploadedCategoryCount: { type: integer, minimum: 0, maximum: 3 }
        totalCategoryCount: { type: integer, enum: [3] }
        categories: { type: array, minItems: 3, maxItems: 3, items: { $ref: '#/components/schemas/CategorySummary' } }
    Detail:
      type: object
      required: [deliveryNo, customerId, version, uploadedCategoryCount, totalCategoryCount, categories, allowedActions, replayed]
      properties:
        deliveryNo: { type: string }
        customerId: { type: string }
        version: { type: integer, format: int64 }
        bolNo: { type: string, nullable: true }
        uploadedCategoryCount: { type: integer, minimum: 0, maximum: 3 }
        totalCategoryCount: { type: integer, enum: [3] }
        categories:
          type: array
          minItems: 3
          maxItems: 3
          items:
            allOf:
              - { $ref: '#/components/schemas/CategorySummary' }
              - type: object
                required: [files]
                properties: { files: { type: array, maxItems: 20, items: { $ref: '#/components/schemas/File' } } }
        allowedActions: { type: array, items: { type: string, enum: [MANAGE_DOCUMENTS] }, description: 返回时按当前认证授权裁剪；只读用户为空，历史和幂等重放也不能沿用旧权限 }
        replayed: { type: boolean }
    Envelope:
      type: object
      properties:
        code: { type: string }
        message: { type: string }
    DetailResponse:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties: { data: { $ref: '#/components/schemas/Detail' } }