baiyue-firstleg/firstleg/src/main/resources/openapi/phase3-loading-delivery-v1.yaml

openapi: 3.0.3
info:
  title: Phase 3 Loading Evidence and Picking API
  version: 1.0.0
paths:
  /api/platform/v1/inbounds/{inboundId}/loading/evidence/pda:
    get:
      summary: List loading evidence for the active PDA worker
      description: Requires the associated inbound to have entered the loading stage. PDA workflowStatus AWAITING_REVIEW does not bypass this gate; canonical claim or picking advances WAIT_SPLIT to LOADING.
      parameters: [{$ref: '#/components/parameters/InboundId'}, {$ref: '#/components/parameters/TenantId'}]
      responses:
        '200': {description: Business envelope; requires platform:firstleg:pda:work}
    post:
      summary: Append one PDA-captured loading evidence photo
      description: Requires the associated inbound process status to be LOADING. PDA workflowStatus AWAITING_REVIEW is a review projection and does not replace the inbound loading-stage gate.
      parameters: [{$ref: '#/components/parameters/InboundId'}, {$ref: '#/components/parameters/TenantId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
      requestBody:
        required: true
        content:
          application/json: {schema: {$ref: '#/components/schemas/UpsertEvidenceRequest'}}
      responses:
        '200': {description: Business envelope; requires platform:firstleg:pda:work}
  /api/platform/v1/inbounds/{inboundId}/loading/evidence:
    get:
      summary: List loading evidence bound to one customer inbound
      parameters: [{$ref: '#/components/parameters/InboundId'}, {$ref: '#/components/parameters/TenantId'}]
      responses:
        '200': {description: Business envelope containing the stable evidence array}
    post:
      summary: Append one real File service object to a loading evidence type
      parameters: [{$ref: '#/components/parameters/InboundId'}, {$ref: '#/components/parameters/TenantId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
      requestBody:
        required: true
        content:
          application/json: {schema: {$ref: '#/components/schemas/UpsertEvidenceRequest'}}
      responses:
        '200': {description: 'Business envelope; ownership, type and version failures use business error codes'}
  /api/platform/v1/inbounds/{inboundId}/loading/evidence/{evidenceId}/content/pda:
    get:
      summary: Download one loading evidence photo for the active PDA worker
      description: Uses the existing platform:firstleg:pda:work authority and validates customer, inbound and evidence ownership before proxying File service content.
      parameters: [{$ref: '#/components/parameters/InboundId'}, {$ref: '#/components/parameters/EvidenceId'}, {$ref: '#/components/parameters/TenantId'}]
      responses:
        '200': {description: Authenticated image bytes}
  /api/platform/v1/inbounds/{inboundId}/loading/evidence/{evidenceId}/void/pda:
    post:
      summary: Void an incorrect PDA loading evidence photo
      parameters: [{$ref: '#/components/parameters/InboundId'}, {$ref: '#/components/parameters/TenantId'}, {$ref: '#/components/parameters/EvidenceId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
      requestBody:
        required: true
        content:
          application/json: {schema: {$ref: '#/components/schemas/VoidEvidenceRequest'}}
      responses:
        '200': {description: Business envelope; requires platform:firstleg:pda:work}
  /api/platform/v1/inbounds/{inboundId}/loading/evidence/{evidenceId}/void:
    post:
      summary: Void an incorrect loading evidence photo without hard deletion
      parameters: [{$ref: '#/components/parameters/InboundId'}, {$ref: '#/components/parameters/TenantId'}, {$ref: '#/components/parameters/EvidenceId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
      requestBody:
        required: true
        content:
          application/json: {schema: {$ref: '#/components/schemas/VoidEvidenceRequest'}}
      responses:
        '200': {description: Business envelope containing the voided record and audit fields}
  /api/platform/v1/inbounds/{inboundId}/loading/picking/start:
    post:
      summary: Refresh the compatibility projection from canonical container PDA tasks
      deprecated: true
      description: expectedCount and pickedCount must exactly match the server-derived container-task aggregate.
      parameters: [{$ref: '#/components/parameters/InboundId'}, {$ref: '#/components/parameters/TenantId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
      requestBody:
        required: true
        content:
          application/json: {schema: {$ref: '#/components/schemas/PickingRequest'}}
      responses:
        '200': {description: Business envelope containing IN_PROGRESS task}
  /api/platform/v1/inbounds/{inboundId}/loading/picking/complete:
    post:
      summary: Mark the compatibility projection complete after all container PDA tasks are reviewed
      deprecated: true
      description: This endpoint cannot complete canonical picking; counts must match the server aggregate and every related container task must already be completed.
      parameters: [{$ref: '#/components/parameters/InboundId'}, {$ref: '#/components/parameters/TenantId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
      requestBody:
        required: true
        content:
          application/json: {schema: {$ref: '#/components/schemas/PickingRequest'}}
      responses:
        '200': {description: Business envelope containing COMPLETED task}
  /api/platform/v1/inbounds/{inboundId}/loading/picking:
    get:
      summary: Read the inbound-level PDA picking task
      parameters: [{$ref: '#/components/parameters/InboundId'}, {$ref: '#/components/parameters/TenantId'}]
      responses:
        '200': {description: Business envelope containing task or null}
  /api/platform/v1/inbounds/{inboundId}/loading/complete:
    post:
      summary: Compatibility endpoint for completing loading after the canonical PDA confirmation
      description: Canonical PDA confirmation atomically completes task, plan and inbound LOADED. This endpoint remains an idempotent server-side completion primitive; RELEASED booking, completed plan/picking and five ACTIVE evidence types remain hard gates. Truck status is not a prerequisite; the canonical PDA action completes the unique active appointment for the stable container booking when one exists.
      parameters: [{$ref: '#/components/parameters/InboundId'}, {$ref: '#/components/parameters/TenantId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
      requestBody:
        required: true
        content:
          application/json: {schema: {$ref: '#/components/schemas/CompleteLoadingRequest'}}
      responses:
        '200': {description: Business envelope containing LOADED status}
components:
  parameters:
    InboundId: {name: inboundId, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}}
    TenantId: {name: tenantId, in: query, required: true, schema: {type: integer, format: int64, minimum: 1}}
    EvidenceId: {name: evidenceId, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}}
    IdempotencyKey: {name: Idempotency-Key, in: header, required: true, schema: {type: string, maxLength: 128}}
  schemas:
    EvidenceResponse:
      type: object
      required: [id, inboundId, tenantId, evidenceType, fileId, previewUrl, version, status]
      properties:
        id: {type: integer, format: int64}
        inboundId: {type: integer, format: int64}
        tenantId: {type: integer, format: int64}
        evidenceType: {type: string, enum: [PHOTO_STEP_1, PHOTO_STEP_2, PHOTO_STEP_3, PHOTO_STEP_4, SEAL]}
        fileId: {type: integer, format: int64}
        fileName: {type: string}
        previewUrl: {type: string, description: Authenticated PDA image-content path; request with the current bearer token}
        version: {type: integer}
        status: {type: string}
    UpsertEvidenceRequest:
      type: object
      required: [expectedVersion, evidenceType, fileId]
      properties:
        expectedVersion: {type: integer, minimum: 0}
        evidenceType: {type: string, enum: [PHOTO_STEP_1, PHOTO_STEP_2, PHOTO_STEP_3, PHOTO_STEP_4, SEAL], description: PHOTO_STEP_1=空仓，PHOTO_STEP_2=半仓，PHOTO_STEP_3=满仓，PHOTO_STEP_4=锁仓，SEAL=带锁码照；同类型可多次追加}
        fileId: {type: integer, format: int64, minimum: 1}
        fileName: {type: string, maxLength: 255, deprecated: true, description: Ignored; server uses File metadata}
        sealNo: {type: string, maxLength: 64, description: Required when evidenceType is SEAL}
        remark: {type: string, maxLength: 1000}
    VoidEvidenceRequest:
      type: object
      required: [expectedVersion, reason]
      properties:
        expectedVersion: {type: integer, minimum: 0}
        reason: {type: string, minLength: 1, maxLength: 500, description: 作废原因，记录操作人和时间}
    PickingRequest:
      type: object
      required: [expectedVersion, expectedCount, pickedCount]
      properties:
        expectedVersion: {type: integer, minimum: 0}
        expectedCount: {type: integer, minimum: 1}
        pickedCount: {type: integer, minimum: 0}
        remark: {type: string, maxLength: 1000}
    CompleteLoadingRequest:
      type: object
      required: [expectedVersion]
      properties:
        expectedVersion: {type: integer, minimum: 0}
        remark: {type: string, maxLength: 1000}