openapi: 3.0.3
info:
  title: 头程装柜与完成装柜清单接口
  version: 1.0.0
  description: 装柜计划仅允许 EDITING 到 LOADING 再到 COMPLETED 单向推进；EDITING 和 LOADING 均可维护未拣货明细，COMPLETED 后计划、明细与货柜运输信息永久只读，不提供回退或撤回接口。
paths:
  /api/platform/v1/first-leg/loading-plans:
    get:
      summary: 分页查询预装清单
      description: 默认返回全部仓库的装柜计划；可按客户和仓库筛选。
      x-permission: platform:firstleg:preload:list
      parameters:
        - {$ref: '#/components/parameters/Page'}
        - {$ref: '#/components/parameters/Size'}
        - {$ref: '#/components/parameters/Keyword'}
        - {$ref: '#/components/parameters/CustomerId'}
        - name: status
          in: query
          description: 预装状态
          schema: {type: string, enum: [EDITING, LOADING]}
        - {$ref: '#/components/parameters/OptionalWarehouseId'}
        - {$ref: '#/components/parameters/CreatedFrom'}
        - {$ref: '#/components/parameters/CreatedTo'}
      responses:
        '200': {$ref: '#/components/responses/PreloadPageResponse'}
  /api/platform/v1/first-leg/loading-plans/{planId}:
    get:
      summary: 查询预装清单详情
      x-permission: platform:firstleg:preload:list
      description: 返回同一装柜计划的汇总、冻结明细和完整操作历史。
      parameters: [{$ref: '#/components/parameters/PlanId'}, {$ref: '#/components/parameters/WarehouseId'}]
      responses:
        '200': {$ref: '#/components/responses/PreloadDetailResponse'}
        '409': {description: 计划已离开预装阶段；先查询 lifecycle 获取当前正式详情资源}
  /api/platform/v1/first-leg/loading-plans/{planId}/lifecycle:
    get:
      summary: 解析装柜计划当前详情阶段
      description: >-
        需要 platform:firstleg:preload:list 权限。同一 planId 从 EDITING、LOADING 到 COMPLETED 永久稳定；
        EDITING/LOADING 返回 PRELOAD，COMPLETED 返回 LOADING_LIST 及其独立读取权限。
        页面据此选择预装详情或正式装柜清单详情，不得以错误文案或 A0404 猜测阶段。
      x-permission: platform:firstleg:preload:list
      parameters: [{$ref: '#/components/parameters/PlanId'}, {$ref: '#/components/parameters/WarehouseId'}]
      responses:
        '200': {$ref: '#/components/responses/LifecycleResolutionResponse'}
        '403': {description: planId 不属于请求仓库或缺少平台读取权限}
        '404': {description: planId 真实不存在}
  /api/platform/v1/first-leg/loading-plans/{planId}/transport:
    patch:
      summary: 修改预装运输信息
      description: >-
        可在 EDITING 或 LOADING 阶段首次补录真实集装箱号；已有柜号的纠正仅限仍为 EDITING、PDA任务尚未领取且无任何物理作业事实时，并必须提供原因和当前版本；
        containerNo 为 null 表示保持当前值，非空时服务端移除格式空白、转大写并校验ISO 6346结构、设备类别和校验位，空白字符串非法且禁止清空。
      x-permission: platform:firstleg:preload:edit
      parameters:
        - {$ref: '#/components/parameters/PlanId'}
        - {$ref: '#/components/parameters/WarehouseId'}
        - {$ref: '#/components/parameters/IdempotencyKey'}
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/TransportUpdateRequest'}
      responses:
        '200': {$ref: '#/components/responses/PreloadDetailResponse'}
  /api/platform/v1/first-leg/loading-plans/{planId}/confirm:
    post:
      summary: 原子确认整份预装计划
      description: 以 loadingPlanId 为唯一范围，原子确认全部已分配入库预装票据。要求计划已 push 且仍为 EDITING、稳定 bridge 完整、真实订舱已关联并为 RELEASED；真实集装箱号可在PDA确认装柜完成前补录。任一票不满足均不写入。成功后唯一创建待领取 PDA task，claim 后才推进 LOADING。同一 Idempotency-Key 与相同请求精确重放原响应，不同 Key 重复确认返回业务冲突。
      x-permission: platform:firstleg:preload:edit
      parameters: [{$ref: '#/components/parameters/PlanId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
      requestBody:
        required: true
        content: {application/json: {schema: {$ref: '#/components/schemas/ConfirmPreloadRequest'}}}
      responses:
        '200': {$ref: '#/components/responses/PreloadConfirmationResponse'}
  /api/platform/v1/first-leg/loading-plans/{planId}/pallet-labels/prepare:
    post:
      summary: 生成并查询散货托盘码清单
      description: 预装确认且已有真实柜号后，按柜号-FBA地址内部编号-三位序号生成稳定清单；一件代发不参与。内部编号缺失时拒绝生成。
      parameters: [{$ref: '#/components/parameters/PlanId'}, {$ref: '#/components/parameters/WarehouseId'}]
      responses:
        '200': {description: 按 FBA 仓分组的散货托盘码清单, content: {application/json: {schema: {type: object}}}}
  /api/platform/v1/first-leg/loading-plans/{planId}/pallet-labels/print:
    post:
      summary: 打印散货托盘码
      description: 仓码和张数均为空时打印全部；均有值时打印该 FBA 仓从第1张开始的指定数量，用于补打。
      parameters: [{$ref: '#/components/parameters/PlanId'}, {$ref: '#/components/parameters/WarehouseId'}]
      requestBody:
        required: true
        content: {application/json: {schema: {$ref: '#/components/schemas/PalletLabelPrintRequest'}}}
      responses:
        '200': {description: 100mm × 100mm 托盘码 PDF, content: {application/pdf: {schema: {type: string, format: binary}}}}
  /api/platform/v1/first-leg/loading-lists:
    get:
      summary: 分页查询装柜清单
      description: 默认返回全部仓库的 COMPLETED 装柜计划；可按客户和仓库筛选。
      x-permission: platform:firstleg:loading-list:list
      parameters:
        - {$ref: '#/components/parameters/Page'}
        - {$ref: '#/components/parameters/Size'}
        - {$ref: '#/components/parameters/Keyword'}
        - {$ref: '#/components/parameters/CustomerId'}
        - {$ref: '#/components/parameters/OptionalWarehouseId'}
        - {$ref: '#/components/parameters/CreatedFrom'}
        - {$ref: '#/components/parameters/CreatedTo'}
      responses:
        '200': {$ref: '#/components/responses/ConfirmedPageResponse'}
  /api/platform/v1/first-leg/loading-lists/{planId}:
    get:
      summary: 查询装柜清单详情
      description: 返回已确认计划的汇总、冻结明细和操作历史，全部只读；查看权限与分页列表权限独立。
      x-permission: platform:firstleg:loading-list:list
      parameters: [{$ref: '#/components/parameters/PlanId'}, {$ref: '#/components/parameters/WarehouseId'}]
      responses:
        '200': {$ref: '#/components/responses/ConfirmedDetailResponse'}
        '409': {description: 计划尚未进入 COMPLETED 正式装柜清单阶段}
components:
  parameters:
    PlanId:
      name: planId
      in: path
      required: true
      description: 装柜计划 ID
      schema: {$ref: '#/components/schemas/LongId'}
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: 写操作幂等键，同一业务操作重试时必须保持不变
      schema: {type: string, minLength: 1, maxLength: 128}
    Page:
      name: page
      in: query
      description: 页码，从 1 开始
      schema: {type: integer, format: int64, minimum: 1, default: 1}
    Size:
      name: size
      in: query
      description: 每页条数
      schema: {type: integer, format: int64, minimum: 1, maximum: 200, default: 20}
    Keyword:
      name: keyword
      in: query
      description: 按预装单号、集装箱号或柜号模糊查询
      schema: {type: string, maxLength: 128}
    CustomerId:
      name: customerId
      in: query
      required: false
      description: 仅返回包含该客户货物的清单
      schema: {$ref: '#/components/schemas/LongId'}
    WarehouseId:
      name: warehouseId
      in: query
      required: true
      description: 仓库 ID；同一仓库内全部客户单据均可见
      schema: {$ref: '#/components/schemas/LongId'}
    OptionalWarehouseId:
      name: warehouseId
      in: query
      required: false
      description: 可选仓库 ID；不传时查询全部仓库
      schema: {$ref: '#/components/schemas/LongId'}
    CreatedFrom:
      name: createdFrom
      in: query
      description: 创建时间起点，包含该时间
      schema: {type: string, format: date-time}
    CreatedTo:
      name: createdTo
      in: query
      description: 创建时间终点，包含该时间
      schema: {type: string, format: date-time}
  responses:
    PreloadPageResponse:
      description: 预装清单分页查询成功或业务失败，按响应体 code 判断
      content: {application/json: {schema: {$ref: '#/components/schemas/PreloadPageEnvelope'}}}
    PreloadDetailResponse:
      description: 预装清单详情查询或操作成功，也可能返回业务失败
      content: {application/json: {schema: {$ref: '#/components/schemas/PreloadDetailEnvelope'}}}
    PreloadConfirmationResponse:
      description: 计划级预装确认成功、精确重放或业务失败
      content: {application/json: {schema: {$ref: '#/components/schemas/PreloadConfirmationEnvelope'}}}
    ConfirmedPageResponse:
      description: 装柜清单分页查询成功或业务失败，按响应体 code 判断
      content: {application/json: {schema: {$ref: '#/components/schemas/ConfirmedPageEnvelope'}}}
    ConfirmedDetailResponse:
      description: 装柜清单详情查询或确认成功，也可能返回业务失败
      content: {application/json: {schema: {$ref: '#/components/schemas/ConfirmedDetailEnvelope'}}}
    LifecycleResolutionResponse:
      description: 装柜计划生命周期解析成功或业务失败
      content: {application/json: {schema: {$ref: '#/components/schemas/LifecycleResolutionEnvelope'}}}
  schemas:
    LongId:
      type: string
      pattern: '^[1-9][0-9]*$'
      example: '1900000000000000001'
      description: 长整型 ID，JSON 中使用字符串避免前端精度丢失
    NullableLongId:
      allOf: [{$ref: '#/components/schemas/LongId'}]
      nullable: true
    ApiEnvelope:
      type: object
      required: [code, message, timestamp]
      properties:
        code: {type: string, description: 业务结果码，仅字符串 200 表示成功, example: '200'}
        message: {type: string, description: 结果说明}
        requestId: {type: string, nullable: true, description: 请求标识}
        traceId: {type: string, nullable: true, description: 链路标识}
        timestamp: {type: string, format: date-time, description: 服务端响应时间}
    PreloadPageEnvelope:
      allOf:
        - {$ref: '#/components/schemas/ApiEnvelope'}
        - type: object
          properties:
            data:
              allOf: [{$ref: '#/components/schemas/PreloadPage'}]
              nullable: true
    PreloadDetailEnvelope:
      allOf:
        - {$ref: '#/components/schemas/ApiEnvelope'}
        - type: object
          properties:
            data:
              allOf: [{$ref: '#/components/schemas/PreloadDetail'}]
              nullable: true
    PreloadConfirmationEnvelope:
      allOf:
        - {$ref: '#/components/schemas/ApiEnvelope'}
        - type: object
          properties:
            data:
              allOf: [{$ref: '#/components/schemas/PreloadConfirmation'}]
              nullable: true
    ConfirmedPageEnvelope:
      allOf:
        - {$ref: '#/components/schemas/ApiEnvelope'}
        - type: object
          properties:
            data:
              allOf: [{$ref: '#/components/schemas/ConfirmedPage'}]
              nullable: true
    ConfirmedDetailEnvelope:
      allOf:
        - {$ref: '#/components/schemas/ApiEnvelope'}
        - type: object
          properties:
            data:
              allOf: [{$ref: '#/components/schemas/ConfirmedDetail'}]
              nullable: true
    LifecycleResolutionEnvelope:
      allOf:
        - {$ref: '#/components/schemas/ApiEnvelope'}
        - type: object
          properties:
            data:
              allOf: [{$ref: '#/components/schemas/LifecycleResolution'}]
              nullable: true
    PreloadPage:
      type: object
      required: [records, page, size, total, pages]
      properties:
        records: {type: array, items: {$ref: '#/components/schemas/PreloadSummary'}}
        page: {type: string, pattern: '^[1-9][0-9]*$', description: 当前页码}
        size: {type: string, pattern: '^[1-9][0-9]*$', description: 每页条数}
        total: {type: string, pattern: '^[0-9]+$', description: 总记录数}
        pages: {type: string, pattern: '^[0-9]+$', description: 总页数}
    ConfirmedPage:
      type: object
      required: [records, page, size, total, pages]
      properties:
        records: {type: array, items: {$ref: '#/components/schemas/ConfirmedSummary'}}
        page: {type: string, pattern: '^[1-9][0-9]*$', description: 当前页码}
        size: {type: string, pattern: '^[1-9][0-9]*$', description: 每页条数}
        total: {type: string, pattern: '^[0-9]+$', description: 总记录数}
        pages: {type: string, pattern: '^[0-9]+$', description: 总页数}
    Customer:
      type: object
      required: [accountId, customerName]
      properties:
        accountId: {$ref: '#/components/schemas/LongId'}
        customerName: {type: string, nullable: true, description: 客户名称}
    LifecycleResolution:
      type: object
      additionalProperties: false
      required: [planId, containerBookingId, warehouseId, planNo, planStatus, detailResource, requiredPermission]
      properties:
        planId: {$ref: '#/components/schemas/LongId'}
        containerBookingId: {$ref: '#/components/schemas/LongId'}
        warehouseId: {$ref: '#/components/schemas/LongId'}
        planNo: {type: string, description: 预装与正式装柜清单沿用的稳定业务号}
        planStatus: {type: string, enum: [EDITING, LOADING, COMPLETED]}
        detailResource: {type: string, enum: [PRELOAD, LOADING_LIST], description: 当前应读取的唯一详情资源}
        requiredPermission: {type: string, enum: ['platform:firstleg:preload:list', 'platform:firstleg:loading-list:list']}
    PreloadSummary:
      type: object
      required: [planId, containerBookingId, preloadNo, customers, status, skuCount, totalPackageCount, totalVolumeCbm, totalGrossWeightKg, createdAt, version, readiness]
      properties:
        planId: {$ref: '#/components/schemas/LongId'}
        containerBookingId: {$ref: '#/components/schemas/LongId'}
        preloadNo: {type: string, pattern: '^LP-[0-9]{6}-[0-9]{4}$', example: LP-260818-0001, description: 预装单号；按北京时间创建日逐日编号，确认后继续作为同一装柜清单号使用}
        containerNo: {type: string, nullable: true, description: 集装箱号}
        cabinetNo: {type: string, nullable: true, pattern: '^CAB-[0-9]{6}-[0-9]{4}$', example: CAB-260818-0001, description: 稳定柜次号；不得与真实集装箱号混用}
        customers: {type: array, description: 计划包含的客户, items: {$ref: '#/components/schemas/Customer'}}
        warehouseId: {$ref: '#/components/schemas/NullableLongId'}
        warehouseName: {type: string, nullable: true, description: 仓库名称}
        vesselName: {type: string, nullable: true, description: 船名}
        voyageNo: {type: string, nullable: true, description: 航次}
        containerType: {type: string, nullable: true, description: 货柜类型}
        status: {type: string, enum: [EDITING, LOADING], description: 装柜计划状态}
        skuCount: {type: string, pattern: '^[0-9]+$', description: SKU 种类数}
        totalPackageCount: {type: string, pattern: '^[0-9]+$', description: 总箱数}
        totalVolumeCbm: {type: number, description: 总体积，单位立方米}
        totalGrossWeightKg: {type: number, description: 总毛重，单位千克}
        createdAt: {type: string, format: date-time, description: 创建时间}
        version: {type: integer, format: int32, minimum: 0, description: 乐观锁版本}
        readiness: {$ref: '#/components/schemas/PreloadReadiness'}
    PreloadReadiness:
      type: object
      required: [containerNoReady, preloadLinkCount, confirmedPreloadCount, confirmationStatus, canConfirm, readyForPda, blockingReasons]
      properties:
        containerNoReady: {type: boolean, description: 是否已录入真实集装箱号 containerNo}
        preloadLinkCount: {type: integer, format: int32, minimum: 0, description: 计划关联的入库预装票据数}
        confirmedPreloadCount: {type: integer, format: int32, minimum: 0, description: 已确认预装票据数}
        oceanBookingId: {$ref: '#/components/schemas/NullableLongId'}
        oceanBookingStatus: {type: string, nullable: true, enum: [CONFIRMED, CHANGE_PENDING, RELEASED, CANCELLED], description: 真实订舱当前状态}
        pdaTaskId: {$ref: '#/components/schemas/NullableLongId'}
        pdaTaskStatus: {type: string, nullable: true, description: PDA task 当前状态}
        confirmationStatus: {type: string, enum: [PENDING, PARTIALLY_CONFIRMED, CONFIRMED], description: 整份计划的预装确认状态}
        canConfirm: {type: boolean, description: 当前是否可调用计划级确认接口}
        readyForPda: {type: boolean, description: PDA 创建前置条件是否全部满足；不依赖真实集装箱号，task 已创建后仍为 true}
        blockingReasons:
          type: array
          description: 阻止计划确认的稳定原因码
          items: {type: string, enum: [LOADING_PLAN_NOT_EDITING, PRELOAD_LINK_MISSING, OCEAN_BOOKING_NOT_LINKED, OCEAN_BOOKING_NOT_RELEASED, PDA_TASK_ALREADY_CREATED, PRELOAD_ALREADY_CONFIRMED]}
    ConfirmPreloadRequest:
      type: object
      required: [expectedVersion, operationReason]
      additionalProperties: false
      properties:
        expectedVersion: {type: integer, format: int32, minimum: 0, description: 当前装柜计划 version}
    PreloadConfirmation:
      type: object
      required: [planId, containerBookingId, confirmationStatus, version, readiness]
      properties:
        planId: {$ref: '#/components/schemas/LongId'}
        containerBookingId: {$ref: '#/components/schemas/LongId'}
        confirmationStatus: {type: string, enum: [CONFIRMED]}
        version: {type: integer, format: int32, minimum: 0, description: 确认后的装柜计划 version}
        readiness: {$ref: '#/components/schemas/PreloadReadiness'}
    ConfirmedSummary:
      type: object
      required: [planId, containerBookingId, loadingListNo, status, totalPackageCount, totalGrossWeightKg, totalNetWeightKg, totalVolumeCbm, totalQuantity, createdAt, version]
      properties:
        planId: {$ref: '#/components/schemas/LongId'}
        containerBookingId: {$ref: '#/components/schemas/LongId'}
        loadingListNo: {type: string, pattern: '^LP-[0-9]{6}-[0-9]{4}$', example: LP-260818-0001, description: 装柜清单号；沿用预装阶段生成的同一编号}
        warehouseId: {$ref: '#/components/schemas/NullableLongId'}
        warehouseName: {type: string, nullable: true, description: 仓库名称}
        containerNo: {type: string, nullable: true, description: 集装箱号}
        cabinetNo: {type: string, nullable: true, pattern: '^CAB-[0-9]{6}-[0-9]{4}$', example: CAB-260818-0001, description: 稳定柜次号}
        status: {type: string, enum: [COMPLETED], description: 装柜清单状态}
        totalPackageCount: {type: string, pattern: '^[0-9]+$', description: 总箱数}
        totalGrossWeightKg: {type: number, description: 总毛重，单位千克}
        totalNetWeightKg: {type: number, description: 总净重，单位千克}
        totalVolumeCbm: {type: number, description: 总体积，单位立方米}
        totalQuantity: {type: string, pattern: '^[0-9]+$', description: 产品总数量}
        remark: {type: string, nullable: true, description: 备注}
        createdBy: {$ref: '#/components/schemas/NullableLongId'}
        createdByName: {type: string, nullable: true, description: 创建人姓名}
        createdAt: {type: string, format: date-time, description: 创建时间}
        version: {type: integer, format: int32, minimum: 0, description: 乐观锁版本}
    LoadingItem:
      type: object
      required: [itemId, accountId, orderId, orderNo, inboundId, inboundDetailId, packageCount, palletCount, grossWeightKg, netWeightKg, volumeCbm, dimensionalWeightKg, productQuantity, unitsPerPackage, loadSequence, itemVersion]
      properties:
        itemId: {$ref: '#/components/schemas/LongId'}
        accountId: {$ref: '#/components/schemas/LongId'}
        customerName: {type: string, nullable: true, description: 客户名称快照}
        customsTaxMode: {type: string, enum: [TAX_REFUND, BUY_DECLARATION], nullable: true, description: 订单/入仓片段冻结的报关方式；不根据退税文件推断}
        taxRefundFlag: {type: boolean, nullable: true, description: customsTaxMode为TAX_REFUND时为true、BUY_DECLARATION时为false；缺少权威事实时为null}
        orderId: {$ref: '#/components/schemas/LongId'}
        orderNo: {type: string, description: 订单号快照}
        inboundId: {$ref: '#/components/schemas/LongId'}
        inboundDetailId: {$ref: '#/components/schemas/LongId'}
        inboundCode: {type: string, nullable: true, description: 入仓码}
        containerNo: {type: string, nullable: true, description: 当前 ACTIVE 柜次的真实集装箱号}
        skuCode: {type: string, nullable: true, description: SKU 编码快照}
        destinationWarehouse: {type: string, nullable: true, description: 目的仓名称快照}
        chineseName: {type: string, nullable: true, description: 中文品名快照}
        englishName: {type: string, nullable: true, description: 英文品名快照}
        goodsImageUrl: {type: string, nullable: true, description: 产品图片地址快照}
        packageCount: {type: integer, format: int32, minimum: 0, description: 箱数}
        palletCount: {type: integer, format: int32, minimum: 0, description: 托盘数}
        grossWeightKg: {type: number, description: 毛重，单位千克}
        netWeightKg: {type: number, description: 净重，单位千克}
        volumeCbm: {type: number, description: 体积，单位立方米}
        dimensionalWeightKg: {type: number, description: 材积重，单位千克}
        productQuantity: {type: string, pattern: '^[0-9]+$', description: 产品数量}
        unitsPerPackage: {type: integer, format: int32, minimum: 0, description: 每箱数量}
        fbaTrackingNo: {type: string, nullable: true, description: FBA 跟踪编号}
        shipmentNo: {type: string, nullable: true, description: 货件号}
        shippingMark: {type: string, nullable: true, description: 唛头}
        internalRemark: {type: string, nullable: true, description: 内部备注}
        customerRemark: {type: string, nullable: true, description: 客户备注}
        warehouseRemark: {type: string, nullable: true, description: 仓库备注}
        customerServiceRemark: {type: string, nullable: true, description: 客服备注}
        loadSequence: {type: integer, format: int32, minimum: 0, description: 装柜顺序}
        frozenAt: {type: string, format: date-time, nullable: true, description: 明细冻结时间}
        itemVersion: {type: integer, format: int32, minimum: 0, description: 明细乐观锁版本；更新仓库备注时作为 expectedItemVersion}
    OperationHistory:
      type: object
      required: [historyId, operationId, actionType, operatorId, occurredAt]
      properties:
        historyId: {$ref: '#/components/schemas/LongId'}
        itemId: {$ref: '#/components/schemas/NullableLongId'}
        operationId: {type: string, minLength: 1, maxLength: 128, description: 稳定业务动作或幂等事件标识；客户端据此识别重放，不按展示文案去重}
        actionType: {type: string, description: 操作类型}
        fromStatus: {type: string, nullable: true, description: 操作前状态}
        toStatus: {type: string, nullable: true, description: 操作后状态}
        beforeSnapshot: {type: string, nullable: true, description: 操作前快照}
        afterSnapshot: {type: string, nullable: true, description: 操作后快照}
        operatorId: {$ref: '#/components/schemas/LongId'}
        operatorName: {type: string, nullable: true, description: 操作人姓名}
        operationReason: {type: string, nullable: true, description: 操作原因}
        occurredAt: {type: string, format: date-time, description: 操作时间}
    PreloadDetail:
      type: object
      required: [summary, items, histories]
      properties:
        summary: {$ref: '#/components/schemas/PreloadSummary'}
        items: {type: array, description: 装柜中明细，可维护未拣货项, items: {$ref: '#/components/schemas/LoadingItem'}}
        histories: {type: array, description: 计划操作历史, items: {$ref: '#/components/schemas/OperationHistory'}}
    ConfirmedDetail:
      type: object
      required: [summary, items, histories]
      properties:
        summary: {$ref: '#/components/schemas/ConfirmedSummary'}
        items: {type: array, description: 已完成且永久只读的装柜明细, items: {$ref: '#/components/schemas/LoadingItem'}}
        histories: {type: array, description: 计划操作历史, items: {$ref: '#/components/schemas/OperationHistory'}}
    TransportUpdateRequest:
      type: object
      required: [expectedVersion]
      additionalProperties: false
      properties:
        containerNo: {type: string, maxLength: 64, nullable: true, description: 新真实集装箱号；null表示保持当前值，空白字符串非法，禁止清空}
        voyageNo: {type: string, maxLength: 64, nullable: true, description: 航次}
        expectedVersion: {type: integer, format: int32, minimum: 0, description: 当前乐观锁版本}
        operationReason: {type: string, minLength: 1, maxLength: 500, nullable: true, description: 纠正已有真实集装箱号时必填；首次补录或保持当前柜号时可省略}
    PalletLabelPrintRequest:
      type: object
      additionalProperties: false
      properties:
        destinationWarehouseCode: {type: string, maxLength: 64, nullable: true}
        count: {type: integer, minimum: 1, maximum: 999, nullable: true}