baiyue-firstleg/firstleg/src/main/resources/openapi/firstleg-v1.yaml

openapi: 3.0.3
info:
  title: 柏悦头程履约 API
  description: 业务成功和失败均使用 HTTP 200；仅响应体 code 为字符串 "200" 时表示成功，其他 code 表示失败。
  version: 1.1.0
security:
  - bearerAuth: []
paths:
  /api/merchant/v1/first-leg/inbounds/{inboundId}/carton-label-pdf:
    post:
      summary: 客户端生成本客户入库单箱唛 PDF
      parameters:
        - {name: inboundId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {name: cartonIndex, in: query, required: false, schema: {type: array, items: {type: integer, minimum: 1}}}
      responses:
        '200': {description: PDF 文件}
        '403': {description: 非客户端身份、无订单查看权限或入库单不属于当前客户}
  /api/merchant/v1/first-leg/orders/{orderId}/carton-label-pdf:
    post:
      summary: 客户端按订单生成本客户草稿或正式订单箱唛 PDF
      description: 后端按登录客户和 orderId 查找真实预入库单；不要求客户端先取得 inboundId。
      parameters:
        - {name: orderId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {name: cartonIndex, in: query, required: false, schema: {type: array, items: {type: integer, minimum: 1}}}
      responses:
        '200': {description: PDF 文件}
        '403': {description: 非客户端身份、无订单查看权限或订单不属于当前客户}
        '404': {description: 订单尚未生成预入库单}
  /internal/firstleg/v1/customer-dimension-configs/defaults:
    post:
      summary: 幂等初始化客户四箱规默认配置
      description: 原子创建 SMALL、MEDIUM、LARGE、EXTRA_LARGE 四行；同一客户和 initializationKey 重试稳定返回 createdByThisInitialization=true，configId 为 SMALL 行 ID。
      security:
        - internalServiceToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/CustomerDimensionConfigInitializeRequest'}
      responses:
        '200': {description: 成功或业务失败，data 返回 configId 和 createdByThisInitialization}
    delete:
      summary: 补偿删除本次新建且尚未修改的四箱规默认配置
      description: 仅当四行均匹配 initializationKey、默认尺寸、默认2cm和version=0时整组物理删除，不会部分删除。
      security:
        - internalServiceToken: []
      parameters:
        - {name: tenantId, in: query, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {name: initializationKey, in: query, required: true, schema: {type: string, minLength: 1, maxLength: 128}}
      responses:
        '200': {description: 幂等补偿完成}
  /internal/firstleg/v1/pricing/channels/validate:
    post:
      summary: 校验订单渠道并返回进仓编码前缀
      description: 仅供订单服务调用；前缀按渠道和目的仓类型选择，同一渠道的包税与不包税订单共用编码前缀。
      security:
        - internalServiceToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [tenantId, originWarehouseId, channelCode, destinationType]
              properties:
                tenantId: {type: string, pattern: '^[1-9][0-9]*$'}
                originWarehouseId: {type: string, pattern: '^[1-9][0-9]*$'}
                channelCode: {type: string, minLength: 1, maxLength: 64}
                destinationType: {type: string, enum: [FBA, OVERSEAS, PRIVATE]}
      responses:
        '200': {description: 成功时 data 返回 channelCode 和 inboundCodePrefix；未配置对应进仓编码时返回业务冲突}
  /api/platform/v1/first-leg/customer-dimension-config:
    get:
      summary: 查询客户固定四箱规尺寸配置
      description: 需要 firstleg:dimension-config:view 权限；按 SMALL、MEDIUM、LARGE、EXTRA_LARGE 固定顺序返回；规则用于实测尺寸归档和计费体积加权，不包含价格。
      parameters:
        - {name: tenantId, in: query, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
      responses:
        '200': {description: 成功时 data 为 CustomerDimensionConfigGroupResponse}
        '403': {description: 无查询权限}
    put:
      summary: 整组编辑客户固定四箱规尺寸配置
      description: 需要 firstleg:dimension-config:edit 权限；请求必须恰好包含四种固定 boxType，四行逐行乐观锁并在同一事务原子保存。
      parameters:
        - {name: tenantId, in: query, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/CustomerDimensionConfigUpdateRequest'}
      responses:
        '200': {description: 成功时 data 为更新后的 CustomerDimensionConfigGroupResponse}
        '403': {description: 无编辑权限}
  /internal/firstleg/v1/inbounds/order-approved:
    post:
      summary: 订单审核通过后幂等创建入库单
      description: 仅供订单服务调用；入仓码由订单提交时生成，Firstleg 必须原样沿用。
      security:
        - internalServiceToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/OrderApprovedInboundCommand'}
      responses:
        '200': {description: 成功或业务失败；相同客户和订单重放返回已有入库单 ID}
  /internal/firstleg/v1/inbounds/unified-orders/query:
    post:
      summary: 按统一订单条件分页查询履约摘要（Order 内部）
      description: >-
        mainStatus 接受六态产品状态；WAIT_SPLIT 为入库完成后的唯一待分柜状态。
        计费与入库处理中状态在完成前仍归并为 WAIT_MEASURE，不提前开放分柜。
      security:
        - internalServiceToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/UnifiedInboundQuery'}
      responses:
        '200':
          description: 成功或业务失败，按响应体 code 判断
          content:
            application/json:
              schema: {$ref: '#/components/schemas/UnifiedInboundPageEnvelope'}
  /internal/firstleg/v1/inbounds/unified-orders/summaries:
    post:
      summary: 按订单 ID 批量查询统一履约摘要（Order 内部）
      security:
        - internalServiceToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/UnifiedInboundBatchRequest'}
      responses:
        '200':
          description: 成功或业务失败，按响应体 code 判断
          content:
            application/json:
              schema: {$ref: '#/components/schemas/UnifiedInboundListEnvelope'}
  /internal/firstleg/v1/inbounds/unified-orders/detail:
    post:
      summary: 按订单 ID 查询统一履约详情（Order 内部）
      description: 时间线保留 Firstleg 内部 fromStatus/toStatus；summary.mainStatus 使用六态产品状态。
      security:
        - internalServiceToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/UnifiedInboundDetailRequest'}
      responses:
        '200':
          description: 成功或业务失败；找不到对应入库单时 data 为 null
          content:
            application/json:
              schema: {$ref: '#/components/schemas/UnifiedInboundDetailEnvelope'}
  /api/platform/v1/first-leg/tasks:
    get:
      summary: 分页查询履约任务
      description: 需要 platform:firstleg:task:list 权限
      parameters:
        - $ref: '#/components/parameters/TenantId'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
        - {name: keyword, in: query, schema: {type: string, maxLength: 64}}
        - {name: status, in: query, schema: {type: string, enum: [PENDING_ASSIGNMENT, ASSIGNED, PROCESSING, COMPLETED, CANCELLED]}}
        - {name: assigneeId, in: query, schema: {type: integer, format: int64}}
      responses:
        '200': {description: 成功或业务失败，按响应体 code 判断}
        '403': {description: 无查询权限}
  /api/platform/v1/first-leg/tasks/{taskId}:
    get:
      summary: 查询履约任务详情
      description: 需要 platform:firstleg:task:view 权限
      parameters:
        - $ref: '#/components/parameters/TenantId'
        - $ref: '#/components/parameters/TaskId'
      responses:
        '200': {description: 成功或业务失败，按响应体 code 判断}
        '403': {description: 无查看权限}
  /api/platform/v1/first-leg/tasks/by-order/{orderId}:
    get:
      summary: 按订单查询履约任务
      description: 需要 platform:firstleg:task:view 权限
      parameters:
        - $ref: '#/components/parameters/TenantId'
        - {name: orderId, in: path, required: true, schema: {type: integer, format: int64}}
      responses:
        '200': {description: 成功或业务失败，按响应体 code 判断}
        '403': {description: 无查看权限}
  /api/platform/v1/first-leg/tasks/{taskId}/assignment-history:
    get:
      summary: 分页查询任务分配历史
      description: 需要 platform:firstleg:assignment:history 权限
      parameters:
        - $ref: '#/components/parameters/TenantId'
        - $ref: '#/components/parameters/TaskId'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
      responses:
        '200': {description: 成功或业务失败，按响应体 code 判断}
        '403': {description: 无历史查看权限}
  /api/platform/v1/first-leg/tasks/{taskId}/assignment:
    post:
      summary: 分配或改派履约任务
      description: 需要 platform:firstleg:assignment:assign 权限
      parameters:
        - $ref: '#/components/parameters/TenantId'
        - $ref: '#/components/parameters/TaskId'
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/AssignRequest'}
      responses:
        '200': {description: 成功或业务失败，按响应体 code 判断}
        '403': {description: 无分配权限}
  /api/platform/v1/containers:
    get:
      summary: 分页查询平台货柜
      description: 需要 platform:firstleg:container:list 权限；货柜为平台级数据，不传 tenant/account
      parameters:
        - {$ref: '#/components/parameters/Page'}
        - {$ref: '#/components/parameters/Size'}
        - {name: keyword, in: query, schema: {type: string, maxLength: 128}}
        - {name: customerId, in: query, description: 仅返回包含该客户货物的柜次, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {name: containerNo, in: query, schema: {type: string, maxLength: 64}}
        - {name: cabinetNo, in: query, schema: {type: string, maxLength: 64}}
        - {name: warehouseId, in: query, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {name: status, in: query, schema: {type: string, enum: [WAIT_LOADING, EDITING, LOADING, COMPLETED]}}
      responses:
        '200':
          description: 成功或业务失败，按响应体 code 判断
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ContainerBookingPageEnvelope'}
        '403': {description: 无货柜查询权限}
    post:
      summary: 新增内部模拟柜
      description: 需要 platform:firstleg:container:create 权限；服务端生成稳定 containerBookingId/cabinetNo，不要求真实柜号或订舱
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/ContainerSimulationCreateRequest'}
      responses:
        '200': {description: 成功或重复号、参数校验等业务失败}
        '403': {description: 无新增按钮权限}
  /api/platform/v1/containers/{id}/ocean-booking-link:
    post:
      summary: 将内部模拟柜关联到真实已确认订舱柜
      description: 需要 platform:firstleg:container:edit；首次关联允许 WAIT_LOADING 或已有预排货的 EDITING 柜，保留原 containerBookingId/cabinetNo/loadingPlanId/items；存在 PDA、有效装柜证据、业务单证或已进入 LOADING/COMPLETED 等不可逆事实时拒绝。
      parameters: [{$ref: '#/components/parameters/ContainerBookingId'}]
      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ContainerOceanBookingLinkRequest'}}}}
      responses: {'200': {description: 关联后的同一 containerBookingId/cabinetNo}}
    delete:
      summary: 解除内部模拟柜的真实订舱关联
      description: 需要 platform:firstleg:container:edit；解绑或换绑仅允许完全空的 WAIT_LOADING 模拟柜；任何排货、PDA、有效装柜证据或业务单证事实均拒绝。
      parameters: [{$ref: '#/components/parameters/ContainerBookingId'}]
      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ContainerOceanBookingUnlinkRequest'}}}}
      responses: {'200': {description: 解除后的同一 containerBookingId/cabinetNo}}
  /api/platform/v1/containers/{id}:
    get:
      summary: 查询平台货柜详情
      description: 需要 platform:firstleg:container:list 权限
      parameters:
        - {$ref: '#/components/parameters/ContainerBookingId'}
      responses:
        '200': {description: 成功或货柜不存在}
        '403': {description: 无货柜查询权限}
    put:
      summary: 草稿阶段完整编辑货柜
      description: 需要 platform:firstleg:container:edit 权限；仅待装柜或计划为 EDITING（预装柜中）时允许
      parameters:
        - {$ref: '#/components/parameters/ContainerBookingId'}
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/ContainerFullUpdateRequest'}
      responses:
        '200': {description: 成功或状态、版本、重复号冲突}
        '403': {description: 无货柜编辑权限}
  /api/platform/v1/containers/{id}/transport:
    patch:
      summary: 修改集装箱号和航次
      description: 需要 platform:firstleg:container:edit 权限；LOADING 仅开放此白名单，COMPLETED 全部只读
      parameters:
        - {$ref: '#/components/parameters/ContainerBookingId'}
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/ContainerTransportUpdateRequest'}
      responses:
        '200': {description: 成功或状态、版本、重复号冲突}
        '403': {description: 无货柜编辑权限}
  /api/platform/v1/containers/{id}/clearance:
    get:
      summary: 查询货柜目的港清关资料
      description: 需要 platform:firstleg:customs:manage 权限
      parameters: [{$ref: '#/components/parameters/ContainerBookingId'}]
      responses: {'200': {description: 成功或货柜不存在}}
  /api/platform/v1/containers/{id}/clearance/document:
    post:
      summary: 上传或替换货柜目的港清关资料
      description: 需要 platform:firstleg:customs:manage 权限，fileId 必须严格绑定当前货柜
      parameters: [{$ref: '#/components/parameters/ContainerBookingId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
      requestBody:
        required: true
        content: {application/json: {schema: {$ref: '#/components/schemas/ContainerDocumentAttachRequest'}}}
      responses: {'200': {description: 成功、文件归属不匹配或版本冲突}}
  /api/platform/v1/containers/{id}/clearance/document/upload:
    post:
      summary: 直接选择文件上传或替换货柜目的港清关资料
      description: Firstleg 使用内部服务令牌上传 File，浏览器不得传递 fileId 或内部令牌；旧 JSON document 接口仅兼容存量调用。
      parameters: [{$ref: '#/components/parameters/ContainerBookingId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema: {$ref: '#/components/schemas/ContainerDocumentUploadRequest'}
      responses: {'200': {description: 成功、文件上传失败或版本冲突}}
  /api/platform/v1/containers/{id}/clearance/complete:
    post:
      summary: 点击完成目的港清关
      description: 需要 platform:firstleg:customs:manage 权限
      parameters: [{$ref: '#/components/parameters/ContainerBookingId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
      requestBody:
        required: true
        content: {application/json: {schema: {$ref: '#/components/schemas/ContainerDocumentCompleteRequest'}}}
      responses: {'200': {description: 成功、未上传资料或版本冲突}}
  /api/platform/v1/first-leg/smart-loading/plans/by-booking/{bookingId}:
    get:
      summary: 按货柜恢复智能装柜草稿
      description: 需要 platform:firstleg:smart-loading:list 权限；仅返回 EDITING 草稿
      parameters:
        - {name: bookingId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
      responses:
        '200': {description: 成功、草稿不存在或计划已进入预装流程}
        '403': {description: 无智能装柜查询权限}
  /api/platform/v1/first-leg/smart-loading/candidates:
    get:
      summary: Query same-channel smart-loading candidates
      parameters:
        - {name: bookingId, in: query, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {name: warehouseId, in: query, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
      responses: {'200': {description: Candidates filtered by the server to the booking channel}}
  /api/platform/v1/first-leg/smart-loading/plans/{planId}:
    get:
      summary: 查询智能装柜草稿详情
      description: 需要 platform:firstleg:smart-loading:list 权限；返回草稿及当前未删除明细
      parameters:
        - {name: planId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
      responses:
        '200': {description: 成功、计划不存在或计划已进入预装流程}
        '403': {description: 无智能装柜查询权限}
  /api/platform/v1/first-leg/smart-loading/plans/{planId}/push-preload:
    post:
      summary: 推送智能装柜计划到预装清单
      description: >-
        需要 platform:firstleg:smart-loading:push 权限。push-preload 不要求真实柜号，
        只冻结 EDITING 柜次计划的明细并建立稳定预装关联，不创建 PDA 作业任务；计划必须处于 EDITING 且版本匹配。
        预装页面随后补录真实柜号；只有预装 CONFIRMED、真实柜号存在、已关联 CONFIRMED/RELEASED 订舱时才创建待领取 PDA 任务，领取后才进入 LOADING。
        智能装柜首次分配会创建入库单级 PENDING 预装聚合；push 会在同一事务内对全部实际分配再次确保该聚合存在且仍为 PENDING，
        但不会覆盖 CONFIRMING/CONFIRMED 记录，也不会在 LOADING 后补建。
        推送事务会先为所有已分配入库单建立 PENDING 预装计划与 EDITING 柜次计划的正式关联，
        任一关联缺失、版本冲突或分配数量为零都会整体失败并禁止 PDA/LOADING；不得在 LOADING 后补关联。
      parameters:
        - {name: planId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {$ref: '#/components/parameters/IdempotencyKey'}
      requestBody:
        required: true
        content: {application/json: {schema: {$ref: '#/components/schemas/SmartLoadingPushRequest'}}}
      responses:
        '200': {description: 推送成功或业务失败，按响应体 code 判断}
        '403': {description: 无智能装柜推送权限}
  /openapi/v1/inbound-measurements:
    post:
      summary: 提交一条第三方箱规测量结果和一张图片
      description: >-
        data 中的 inboundCode 匹配入库单，inboundDetailId 必须匹配该入库单关联订单中的已有货物明细；
        每次只保存一条箱规明细和一张图片，不审核、不计费、不入库，也不改变入库单状态。
        首轮联调可由服务端配置 signature-required=false：此时只强制固定 X-App-Key 和
        Idempotency-Key，X-Timestamp、X-Nonce、X-Signature 可不传；恢复签名后按下述规则计算。
        签名串依次为 METHOD、原始 PATH、X-Timestamp、X-Nonce、Idempotency-Key、
        签名body的 SHA-256 小写十六进制，六部分使用 LF（\n）连接且末尾不追加换行。
        签名body = data原始UTF-8文本 + LF + image文件内容SHA-256小写十六进制。
        三层语义：Nonce 防短时重放；Idempotency-Key 标识一次 HTTP 写操作；
        appKey + eventNo 标识第三方业务事件。多台设备可共用同一 appKey/secret，
        但 deviceCode、eventNo 和 Idempotency-Key 必须由调用方生成全局唯一值，
        不得仅在单台设备内从 1 开始递增。
      security:
        - measurementAppKey: []
          measurementTimestamp: []
          measurementNonce: []
          measurementSignature: []
      parameters:
        - {$ref: '#/components/parameters/XTimestamp'}
        - {$ref: '#/components/parameters/XNonce'}
        - {$ref: '#/components/parameters/IdempotencyKey'}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [boxCode, length, width, height, machineNo, picture]
              properties:
                boxCode: {type: string, maxLength: 128, example: 'ZBYHK2608140001#4-1'}
                shipment_id: {type: string, maxLength: 64, example: 'FBA19L5KMY2CU000002', description: '可选；设备从Amazon FBA箱标实际扫描得到，有则原样上传；系统只保存，不生成且不覆盖客户下单值'}
                length: {type: number, format: decimal, minimum: 0.001}
                width: {type: number, format: decimal, minimum: 0.001}
                height: {type: number, format: decimal, minimum: 0.001}
                weight: {type: number, format: decimal, minimum: 0.001, nullable: true}
                machineNo: {type: string, maxLength: 64}
                measuredAt: {type: string, format: date-time, nullable: true}
                picture: {type: string, description: 'data:image/jpeg;base64,...'}
          multipart/form-data:
            schema:
              type: object
              required: [data, image]
              properties:
                data:
                  type: string
                  description: InboundMeasurementCallbackRequest 的原始UTF-8 JSON文本
                image:
                  type: string
                  format: binary
                  description: 当前测量明细唯一对应图片，JPG/PNG/BMP且不超过5MB
      responses:
        '200':
          description: JSON 墨家协议在正式箱码匹配或未匹配联调收件成功时均返回 code=200；data.matched 区分结果。其他业务失败按 code 判断。
          content:
            application/json:
              schema: {$ref: '#/components/schemas/MojiaMeasurementUploadEnvelope'}
        '413': {description: 请求体超过网关限制}
        '415': {description: Content-Type 不支持}
  /openapi/v1/inbound-measurements/events/{eventNo}:
    get:
      summary: 查询第三方测量事件状态
      description: >-
        signature-required=false 时只需固定 X-App-Key；恢复签名后，GET 签名串的
        Idempotency-Key 行为空字符串，body 摘要为空字节 SHA-256。
      security:
        - measurementAppKey: []
          measurementTimestamp: []
          measurementNonce: []
          measurementSignature: []
      parameters:
        - name: eventNo
          in: path
          required: true
          schema: {type: string, pattern: '^[A-Za-z0-9._:-]{1,128}$'}
        - {$ref: '#/components/parameters/XTimestamp'}
        - {$ref: '#/components/parameters/XNonce'}
      responses:
        '200': {description: 成功或业务失败，按响应体字符串 code 判断}
  /api/platform/inbounds:
    get:
      summary: 分页查询入库单
      description: 需要 platform:firstleg:inbound:list 权限；默认查询全部企业，可选 tenantId 筛选；仅使用 V2 四个页签
      parameters:
        - {name: tenantId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {name: tab, in: query, schema: {type: string, enum: [WAIT_MEASURE, WAIT_REVIEW, WAIT_FEE_SEND, WAIT_SPLIT]}}
      responses:
        '200':
          description: 成功或业务失败，按响应体 code 判断；每条记录携带后续客户隔离操作所需的 tenantId，该字段当前表示客户 ID
          content:
            application/json:
              schema: {$ref: '#/components/schemas/InboundOrderPageEnvelope'}
        '403': {description: 无查询权限}
  /api/platform/inbounds/{inboundId}:
    get:
      summary: 查询入库单详情
      description: 需要 platform:firstleg:inbound:view 权限
      parameters:
        - {name: tenantId, in: query, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {name: inboundId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
      responses:
        '200': {description: 成功或业务失败，按响应体 code 判断}
        '403': {description: 无查看权限}
  /api/platform/inbounds/{inboundId}/carton-label-pdf:
    post:
      summary: 生成或补打入仓箱唛 PDF
      description: 需要 platform:firstleg:inbound:view 权限；首次打印冻结整单箱号，重复打印和部分补打复用原映射。
      parameters:
        - {name: tenantId, in: query, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {name: inboundId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - name: cartonIndex
          in: query
          required: false
          style: form
          explode: true
          schema: {type: array, items: {type: integer, minimum: 1}}
          description: 不传时打印整单；可重复传入以部分补打指定箱下标。
      responses:
        '200':
          description: 成功返回 PDF；业务失败返回统一 JSON 响应，调用方必须按 Content-Type 区分。
          content:
            application/pdf: {schema: {type: string, format: binary}}
            application/json:
              schema:
                type: object
                required: [code, message]
                properties:
                  code: {type: string}
                  message: {type: string}
                  requestId: {type: string, nullable: true}
                  traceId: {type: string, nullable: true}
        '403': {description: 无查看权限}
  /api/platform/v1/first-leg/inbounds/{inboundId}/measurement/carton-scans:
    post:
      summary: 平台模拟单箱设备扫描
      description: >-
        需要 platform:firstleg:inbound:measure:edit 权限；仅用于平台联调和代设备录入，
        复用正式单箱覆盖规则，不代表最终第三方设备协议或鉴权方式。
      parameters:
        - {name: tenantId, in: query, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {name: inboundId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [data, image]
              properties:
                data:
                  type: object
                  required: [boxCode, length, width, height, machineNo, measuredAt]
                  properties:
                    boxCode: {type: string, maxLength: 128}
                    length: {type: number, format: double, minimum: 0.001}
                    width: {type: number, format: double, minimum: 0.001}
                    height: {type: number, format: double, minimum: 0.001}
                    weight: {type: number, format: double, minimum: 0.001, nullable: true}
                    machineNo: {type: string, maxLength: 64}
                    measuredAt: {type: string, format: date-time}
                image: {type: string, format: binary}
      responses:
        '200': {description: 成功或业务失败，按响应体 code 判断}
        '403': {description: 无测量编辑权限}
  /api/platform/v1/first-leg/inbounds/{inboundId}/measurement/manual-cartons:
    post:
      summary: 平台人工录入单箱测量
      description: >-
        需要 platform:firstleg:inbound:measure:manual-entry 权限；人工录入独立记录为 MANUAL/PLATFORM，
        复用正式单箱绑定、图片、计算和覆盖规则，不影响设备扫描入口。
      parameters:
        - {name: tenantId, in: query, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {name: inboundId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [data, image]
              properties:
                data:
                  type: object
                  required: [boxCode, length, width, height, machineNo, measuredAt]
                  properties:
                    boxCode: {type: string, maxLength: 128}
                    length: {type: number, format: double, minimum: 0.001}
                    width: {type: number, format: double, minimum: 0.001}
                    height: {type: number, format: double, minimum: 0.001}
                    weight: {type: number, format: double, minimum: 0.001, nullable: true}
                    machineNo: {type: string, maxLength: 64}
                    measuredAt: {type: string, format: date-time}
                image: {type: string, format: binary}
      responses:
        '200': {description: 成功或业务失败，按响应体 code 判断}
        '403': {description: 无测量编辑权限}
  /api/platform/v1/first-leg/inbounds/{inboundId}/weight-pallet-options:
    get:
      summary: 查询称重可选托盘快照
      description: >-
        需要入库测量查看或称重编辑权限。Firstleg 按入库单 warehouseId 查询 Warehouse 公共托盘快照；
        仅限定同仓且未删除，不校验托盘状态或占用资格，Admin 不需要 platform:pallet:list。
      parameters:
        - {name: tenantId, in: query, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {name: inboundId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
      responses:
        '200':
          description: 成功或业务失败，按响应体 code 判断
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: {type: string}
                  message: {type: string}
                  data: {type: array, items: {$ref: '#/components/schemas/WeightPalletSnapshot'}}
        '403': {description: 无入库测量查看或称重编辑权限}
  /api/platform/v1/first-leg/inbounds/{inboundId}/weight-results:
    post:
      summary: 登记称重图片 OCR 毛重结果
      description: >-
        需要称重编辑权限。请求必须绑定 palletId；Firstleg 按入库单 warehouseId 读取 Warehouse
        权威快照并固化托盘编码、类型、容量和皮重，不信任前端托盘快照。
      parameters:
        - {name: tenantId, in: query, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {name: inboundId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/CreateWeightResultRequest'}
      responses:
        '200':
          description: 成功或业务失败，按响应体 code 判断
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: {type: string}
                  message: {type: string}
                  data: {$ref: '#/components/schemas/InboundWeightResult'}
        '403': {description: 无称重编辑权限}
  /api/platform/v1/first-leg/inbounds/{inboundId}/weight-results/{resultId}/confirm:
    post:
      summary: 确认 OCR 重量
      description: >-
        需要 platform:firstleg:inbound:weight:confirm 权限；携带人工修改字段时还需要
        platform:firstleg:inbound:weight:edit 权限。修改与确认在同一事务内完成，保留 OCR 原值，
        分别写入 CORRECT 和 CONFIRM 修订记录。输入表示含托盘毛重；服务端统一换算为 KG，
        使用创建时固化的托盘皮重计算 netWeightKg，且毛重必须大于皮重。
        入库单 actualGrossWeightKg 明确保留为下游货物实际毛重字段，值汇总所有已确认 netWeightKg。
      parameters:
        - {name: tenantId, in: query, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {name: inboundId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {name: resultId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/ConfirmWeightResultRequest'}
      responses:
        '200':
          description: 成功或业务失败，按响应体 code 判断
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: {type: string}
                  message: {type: string}
                  data: {$ref: '#/components/schemas/InboundWeightResult'}
        '403': {description: 无确认权限，或修改重量时无编辑权限}
  /api/platform/v1/first-leg/inbounds/{inboundId}/weight-results/{resultId}:
    put:
      summary: 人工修正 OCR 毛重
      description: >-
        需要称重编辑权限。修正值仍表示含托盘毛重；保留 OCR 原值，已确认结果修正后立即移出净重汇总并回到待确认。
      parameters:
        - {name: tenantId, in: query, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {name: inboundId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {name: resultId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/CorrectWeightResultRequest'}
      responses:
        '200':
          description: 成功或业务失败，按响应体 code 判断
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: {type: string}
                  message: {type: string}
                  data: {$ref: '#/components/schemas/InboundWeightResult'}
        '403': {description: 无称重编辑权限}
    delete:
      summary: 删除称重图片及重量结果
      description: >-
        需要 platform:firstleg:inbound:weight:edit 权限；仅允许在可编辑的测量状态删除。
        删除已确认图片后重新汇总剩余已确认图片的净重，删除最后一张时 actualGrossWeightKg 恢复为空。
      parameters:
        - {name: tenantId, in: query, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {name: version, in: query, required: true, schema: {type: integer, format: int32, minimum: 0}}
        - {name: inboundId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {name: resultId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
      responses:
        '200': {description: 成功或业务失败，按响应体 code 判断}
        '403': {description: 无重量编辑权限}
  /api/platform/v1/inbounds/{inboundId}/measurements/approve:
    post:
      summary: 审核通过测量
      description: 需要 firstleg:inbound:measurement-review 权限。审核通过后立即进入 WAIT_SPLIT，并按该次测量数据尽力生成 CALCULATED 初算费用；价格未覆盖或初算异常只返回非阻断提示，不影响审核结果和待分柜状态。
      parameters:
        - {name: inboundId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {name: tenantId, in: query, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {name: Idempotency-Key, in: header, required: true, schema: {type: string}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [measurementId, expectedVersion]
              properties:
                measurementId: {type: string, pattern: '^[1-9][0-9]*$'}
                expectedVersion: {type: integer, minimum: 0}
                reason: {type: string, maxLength: 1000}
      responses:
        '200': {description: 成功或业务失败，按响应体 code 判断；审核成功 data.processStatus 固定为 WAIT_SPLIT，initialPricingSucceeded 表示是否同时生成初算费用，初算失败时 feeStatus=UNPRICED 且主流程仍成功}
  /api/platform/v1/inbounds/{inboundId}/measurements/reject:
    post:
      summary: 驳回测量
      description: 需要 firstleg:inbound:measurement-review 权限；只退回测量数据修改，已确认托盘和库位占用保持不动。
      parameters:
        - {name: inboundId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {name: Idempotency-Key, in: header, required: true, schema: {type: string}}
      responses:
        '200': {description: 成功或业务失败}
  /api/platform/v1/inbounds/{inboundId}/measurements/submit:
    post:
      summary: 提交测量完成
      description: 测量提交后立即按总体积拆分普通托盘、分配并确认占用库位，再进入客服待审核；无普通空闲位时共享 A0。
      parameters:
        - {name: tenantId, in: query, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {name: inboundId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
      responses:
        '200': {description: 成功时 processStatus=MEASURE_PENDING、measureReviewStatus=PENDING，且库位已 OCCUPIED}
        '403': {description: 无测量提交权限}
  /api/merchant/v1/first-leg/orders/{orderId}/inbound-billing:
    get:
      summary: 客户查询已完成入库结果和最新已发布费用
      description: 需要 merchant:order:view 权限；客户只读查看，不需要确认费用，仅 WAIT_SPLIT + APPROVED + CONFIRMED 的二期终态可见。
      parameters:
        - {name: orderId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
      responses:
        '200':
          description: 成功；publishedFeeDetail 是后台和客户共同读取的同一条已发布入库运费明细，latestFee 仅为兼容保留的计费快照
          content:
            application/json:
              schema: {$ref: '#/components/schemas/MerchantInboundBillingEnvelope'}
        '403': {description: 非当前客户或无订单查看权限}
  /api/platform/v1/inbounds/{inboundId}/measurements/exception-release:
    post:
      summary: 测量异常放行
      description: 需要 firstleg:inbound:exception-release 权限
      parameters:
        - {name: inboundId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {name: Idempotency-Key, in: header, required: true, schema: {type: string}}
      responses:
        '200': {description: 成功或业务失败}
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    measurementAppKey:
      type: apiKey
      in: header
      name: X-App-Key
      description: 分配给测量服务商的应用标识
    measurementTimestamp:
      type: apiKey
      in: header
      name: X-Timestamp
      description: Unix 毫秒时间戳
    measurementNonce:
      type: apiKey
      in: header
      name: X-Nonce
      description: 每次请求唯一的随机串
    measurementSignature:
      type: apiKey
      in: header
      name: X-Signature
      description: HMAC-SHA256 小写十六进制签名
    internalServiceToken:
      type: apiKey
      in: header
      name: X-Internal-Service-Token
  parameters:
    XTimestamp:
      name: X-Timestamp
      in: header
      required: true
      schema: {type: string, pattern: '^[0-9]{13}$', example: '1785551400000'}
    XNonce:
      name: X-Nonce
      in: header
      required: true
      schema: {type: string, minLength: 1, maxLength: 128}
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema: {type: string, minLength: 1, maxLength: 128}
    TenantId:
      name: tenantId
      in: query
      required: true
      schema: {type: integer, format: int64, minimum: 1}
    TaskId:
      name: taskId
      in: path
      required: true
      schema: {type: integer, format: int64}
    Page:
      name: page
      in: query
      schema: {type: integer, format: int64, minimum: 1, default: 1}
    Size:
      name: size
      in: query
      schema: {type: integer, format: int64, minimum: 1, maximum: 200, default: 20}
    ContainerBookingId:
      name: id
      in: path
      required: true
      schema: {type: string, pattern: '^[1-9][0-9]*$'}
  schemas:
    UnifiedMainStatus:
      type: string
      enum: [PENDING_REVIEW, WAIT_MEASURE, WAIT_SPLIT, LOADING, LOADED, DELIVERED]
      description: 六态产品主状态；WAIT_SPLIT 为入库完成后的唯一待分柜状态
    UnifiedInboundQuery:
      type: object
      properties:
        tenantId: {type: integer, format: int64, nullable: true}
        keyword: {type: string, maxLength: 64, nullable: true}
        orderNo: {type: string, maxLength: 64, nullable: true}
        mainStatus:
          type: string
          enum: [PENDING_REVIEW, WAIT_MEASURE, WAIT_SPLIT, LOADING, LOADED, DELIVERED]
          nullable: true
          description: WAIT_SPLIT 为唯一待分柜筛选值
        customerId: {type: integer, format: int64, nullable: true}
        receivingWarehouseId: {type: integer, format: int64, nullable: true}
        destinationWarehouseId: {type: integer, format: int64, nullable: true}
        inboundCode: {type: string, maxLength: 64, nullable: true}
        internalOrderStatus: {type: string, maxLength: 32, nullable: true}
        expectedArrivalDate: {type: string, format: date, nullable: true}
        feeReviewStatus: {type: string, maxLength: 32, nullable: true}
        channelName: {type: string, maxLength: 128, nullable: true}
        containerNo: {type: string, maxLength: 64, nullable: true}
        cabinetNo: {type: string, maxLength: 64, nullable: true}
        sailingDate: {type: string, format: date, nullable: true}
        loaded: {type: boolean, nullable: true}
        fullContainer: {type: boolean, nullable: true}
        measurementReviewStatus: {type: string, maxLength: 32, nullable: true}
        candidateOrderIds: {type: array, nullable: true, items: {type: integer, format: int64}}
        createdFrom: {type: string, format: date-time, nullable: true}
        createdTo: {type: string, format: date-time, nullable: true}
        page: {type: integer, format: int64, minimum: 1, default: 1}
        size: {type: integer, format: int64, minimum: 1, maximum: 200, default: 20}
    UnifiedInboundBatchRequest:
      type: object
      required: [orderIds]
      properties:
        tenantId: {type: integer, format: int64, nullable: true}
        orderIds:
          type: array
          minItems: 1
          maxItems: 200
          items: {type: integer, format: int64, minimum: 1}
    UnifiedInboundDetailRequest:
      type: object
      required: [tenantId, orderId]
      properties:
        tenantId: {type: integer, format: int64, minimum: 1}
        orderId: {type: integer, format: int64, minimum: 1}
    UnifiedInboundPageEnvelope:
      type: object
      properties:
        code: {type: string, example: '200'}
        message: {type: string}
        data:
          type: object
          properties:
            records: {type: array, items: {$ref: '#/components/schemas/UnifiedInboundSummary'}}
            page: {type: integer, format: int64, minimum: 1}
            size: {type: integer, format: int64, minimum: 1}
            total: {type: integer, format: int64, minimum: 0}
            pages: {type: integer, format: int64, minimum: 0}
    UnifiedInboundListEnvelope:
      type: object
      properties:
        code: {type: string, example: '200'}
        message: {type: string}
        data: {type: array, items: {$ref: '#/components/schemas/UnifiedInboundSummary'}}
    UnifiedInboundDetailEnvelope:
      type: object
      properties:
        code: {type: string, example: '200'}
        message: {type: string}
        data:
          allOf: [{$ref: '#/components/schemas/UnifiedInboundDetail'}]
          nullable: true
    UnifiedInboundDetail:
      type: object
      properties:
        summary: {$ref: '#/components/schemas/UnifiedInboundSummary'}
        timeline:
          type: array
          items:
            type: object
            properties:
              source: {type: string}
              eventType: {type: string}
              fromStatus: {type: string, nullable: true}
              toStatus: {type: string, nullable: true}
              action: {type: string, nullable: true}
              remark: {type: string, nullable: true}
              operatorId: {type: integer, format: int64, nullable: true}
              operatorName: {type: string, nullable: true}
              occurredAt: {type: string, format: date-time, nullable: true}
    UnifiedInboundSummary:
      type: object
      properties:
        inbound: {$ref: '#/components/schemas/UnifiedInboundOrderSummary'}
        mainStatus: {$ref: '#/components/schemas/UnifiedMainStatus'}
        nextAction: {type: string, nullable: true}
        preload: {$ref: '#/components/schemas/UnifiedPreloadSummary'}
        loading: {$ref: '#/components/schemas/UnifiedLoadingSummary'}
        delivery: {$ref: '#/components/schemas/UnifiedDeliverySummary'}
    UnifiedInboundOrderSummary:
      type: object
      description: InboundOrderSummary 的内部统一订单投影
      properties:
        id: {type: integer, format: int64}
        tenantId: {type: integer, format: int64}
        orderId: {type: integer, format: int64, nullable: true}
        orderNo: {type: string, nullable: true}
        inboundCode: {type: string, nullable: true}
        processStatus: {type: string, nullable: true, description: Firstleg 内部状态；入库完成记录进入 WAIT_SPLIT}
        orderStatusSnapshot: {type: string, nullable: true}
        measureReviewStatus: {type: string, nullable: true}
        feeStatus: {type: string, nullable: true}
        feeReviewStatus: {type: string, nullable: true}
        notificationStatus: {type: string, nullable: true}
        version: {type: integer, nullable: true}
        expectedArrivalAt: {type: string, format: date-time, nullable: true}
        customerId: {type: integer, format: int64, nullable: true}
        customerName: {type: string, nullable: true}
        companyId: {type: integer, format: int64, nullable: true}
        companyName: {type: string, nullable: true}
        warehouseId: {type: integer, format: int64, nullable: true}
        warehouseName: {type: string, nullable: true}
        deliveryWarehouseId: {type: integer, format: int64, nullable: true}
        deliveryWarehouseName: {type: string, nullable: true}
        businessType: {type: string, nullable: true}
        channelCode: {type: string, nullable: true}
        channelName: {type: string, nullable: true}
        taxMode: {type: string, nullable: true}
        pricingTaxMode: {type: string, nullable: true}
        containerMode: {type: string, nullable: true}
        customsInspection: {type: boolean, nullable: true}
        destinationType: {type: string, nullable: true}
        destinationWarehouseId: {type: integer, format: int64, nullable: true}
        destinationCode: {type: string, nullable: true}
        destinationName: {type: string, nullable: true}
        holdFlag: {type: boolean, nullable: true}
        currentHoldReason: {type: string, nullable: true}
        totalPackageCount: {type: integer, nullable: true}
        locationCodes: {type: string, nullable: true}
        actualGrossWeightKg: {type: number, nullable: true}
        actualNetWeightKg: {type: number, nullable: true}
        actualVolumeCbm: {type: number, nullable: true}
        volumeWeightKg: {type: number, nullable: true}
        chargeableWeightKg: {type: number, nullable: true}
        chargeableVolumeCbm: {type: number, nullable: true}
        palletCount: {type: integer, nullable: true}
        measureCompletedAt: {type: string, format: date-time, nullable: true}
        inboundedAt: {type: string, format: date-time, nullable: true}
        expressCompanyCode: {type: string, nullable: true}
        expressCompanyName: {type: string, nullable: true}
        loadingStatus: {type: string, nullable: true}
        containerNo: {type: string, nullable: true}
        cabinetNo: {type: string, nullable: true}
        vesselName: {type: string, nullable: true}
        voyageNo: {type: string, nullable: true}
        sailingAt: {type: string, format: date-time, nullable: true}
        portArrivalAt: {type: string, format: date-time, nullable: true}
        expressTrackingNo: {type: string, nullable: true}
        createdAt: {type: string, format: date-time, nullable: true}
        updatedAt: {type: string, format: date-time, nullable: true}
    UnifiedPreloadSummary:
      type: object
      nullable: true
      properties:
        status: {type: string, nullable: true}
        version: {type: integer, nullable: true}
        itemCount: {type: integer, nullable: true}
        updatedAt: {type: string, format: date-time, nullable: true}
    UnifiedLoadingSummary:
      type: object
      nullable: true
      properties:
        status: {type: string, nullable: true}
        loadingVersion: {type: integer, nullable: true, description: 当前为 pickingVersion 兼容别名}
        pickingVersion: {type: integer, nullable: true}
        expectedCount: {type: integer, nullable: true}
        pickedCount: {type: integer, nullable: true}
        evidenceCount: {type: integer, nullable: true}
        sealNo: {type: string, nullable: true}
        updatedAt: {type: string, format: date-time, nullable: true}
    UnifiedDeliverySummary:
      type: object
      nullable: true
      properties:
        status: {type: string, nullable: true}
        completedAt: {type: string, format: date-time, nullable: true}
        trackingNo: {type: string, nullable: true}
    MojiaMeasurementUploadEnvelope:
      type: object
      properties:
        code: {type: string, example: '200'}
        message: {type: string, example: success}
        data: {$ref: '#/components/schemas/MojiaMeasurementUploadResponse'}
    MojiaMeasurementUploadResponse:
      type: object
      required: [accepted, matched, boxCode, created]
      properties:
        accepted: {type: boolean, example: true}
        matched: {type: boolean, description: true 表示已写入正式箱级测量；false 表示已写入联调收件箱等待排查}
        receiptId: {type: string, nullable: true, description: matched=false 时返回的联调收件记录ID}
        measurementId: {type: string, nullable: true}
        itemId: {type: string, nullable: true}
        boxCode: {type: string}
        imageFileId: {type: string, nullable: true}
        created: {type: boolean}
    CustomerDimensionConfigUpdateRequest:
      type: object
      required: [rules]
      properties:
        rules:
          type: array
          minItems: 4
          maxItems: 4
          description: 必须恰好包含 SMALL、MEDIUM、LARGE、EXTRA_LARGE 各一行
          items: {$ref: '#/components/schemas/CustomerDimensionConfigRuleUpdateRequest'}
    CustomerDimensionConfigRuleUpdateRequest:
      type: object
      required: [boxType, innerLengthCm, innerWidthCm, innerHeightCm, edgeAdditionCm, version]
      properties:
        boxType: {type: string, enum: [SMALL, MEDIUM, LARGE, EXTRA_LARGE]}
        innerLengthCm: {type: number, minimum: 0.001, multipleOf: 0.001}
        innerWidthCm: {type: number, minimum: 0.001, multipleOf: 0.001}
        innerHeightCm: {type: number, minimum: 0.001, multipleOf: 0.001}
        edgeAdditionCm:
          type: number
          minimum: 0.001
          maximum: 100
          multipleOf: 0.001
          description: 箱规长、宽、高三个方向分别使用的每侧加宽厘米数
          example: 2.000
        remark: {type: string, maxLength: 500, nullable: true}
        version: {type: integer, minimum: 0, description: 乐观锁版本号}
    CustomerDimensionConfigGroupResponse:
      type: object
      required: [tenantId, rules]
      properties:
        tenantId: {type: string, pattern: '^[1-9][0-9]*$'}
        rules:
          type: array
          minItems: 4
          maxItems: 4
          items: {$ref: '#/components/schemas/CustomerDimensionConfigRuleResponse'}
    CustomerDimensionConfigRuleResponse:
      type: object
      required: [id, boxType, boxTypeName, innerLengthCm, innerWidthCm, innerHeightCm, edgeAdditionCm, outerLengthCm, outerWidthCm, outerHeightCm, volumeCbm, version]
      properties:
        id: {type: string, pattern: '^[1-9][0-9]*$'}
        boxType: {type: string, enum: [SMALL, MEDIUM, LARGE, EXTRA_LARGE]}
        boxTypeName: {type: string, enum: [小箱, 中箱, 大箱, 特大箱]}
        innerLengthCm: {type: number, minimum: 0.001, multipleOf: 0.001}
        innerWidthCm: {type: number, minimum: 0.001, multipleOf: 0.001}
        innerHeightCm: {type: number, minimum: 0.001, multipleOf: 0.001}
        edgeAdditionCm: {type: number, minimum: 0.001, maximum: 100, example: 2.000}
        outerLengthCm: {type: number, minimum: 0.001, description: innerLengthCm + edgeAdditionCm * 2}
        outerWidthCm: {type: number, minimum: 0.001, description: innerWidthCm + edgeAdditionCm * 2}
        outerHeightCm: {type: number, minimum: 0.001, description: innerHeightCm + edgeAdditionCm * 2}
        volumeCbm: {type: number, multipleOf: 0.001, description: 使用未舍入外径完整计算后四舍五入保留3位}
        remark: {type: string, nullable: true}
        version: {type: integer, minimum: 0}
        createdAt: {type: string, format: date-time, nullable: true}
        updatedAt: {type: string, format: date-time, nullable: true}
    CustomerDimensionConfigInitializeRequest:
      type: object
      required: [tenantId, operatorId, initializationKey]
      properties:
        tenantId: {type: string, pattern: '^[1-9][0-9]*$'}
        operatorId: {type: string, pattern: '^[0-9]+$'}
        initializationKey: {type: string, minLength: 1, maxLength: 128}
    CustomerDimensionConfigInitializeResponse:
      type: object
      required: [configId, createdByThisInitialization]
      properties:
        configId: {type: string, pattern: '^[1-9][0-9]*$'}
        createdByThisInitialization: {type: boolean}
    WeightPalletSnapshot:
      type: object
      required: [palletId, palletCode, palletType, capacityCbm, tareWeightKg]
      properties:
        palletId: {type: string, pattern: '^[1-9][0-9]*$'}
        palletCode: {type: string}
        palletType: {type: string}
        capacityCbm: {type: number, format: double, minimum: 0.0001}
        tareWeightKg: {type: number, format: double, minimum: 0, multipleOf: 0.001}
    CreateWeightResultRequest:
      type: object
      required: [fileId, palletId]
      properties:
        fileId: {type: string, pattern: '^[1-9][0-9]*$'}
        palletId: {type: string, pattern: '^[1-9][0-9]*$'}
        ocrProvider: {type: string, maxLength: 64, nullable: true}
        ocrRawText: {type: string, maxLength: 1000, nullable: true}
        ocrWeightValue: {type: number, format: double, minimum: 0, nullable: true, description: OCR 原始含托盘毛重}
        ocrWeightUnit: {type: string, maxLength: 8, nullable: true}
        confidence: {type: number, format: double, minimum: 0, maximum: 1, nullable: true}
    CorrectWeightResultRequest:
      type: object
      required: [version, adjustedWeightValue, adjustedWeightUnit, adjustmentReason]
      properties:
        version: {type: integer, minimum: 0}
        adjustedWeightValue: {type: number, format: double, minimum: 0.001, description: 人工修正后的含托盘毛重}
        adjustedWeightUnit: {type: string, enum: [KG, LB]}
        adjustmentReason: {type: string, minLength: 1, maxLength: 500}
    InboundWeightResult:
      type: object
      required: [id, fileId, palletId, palletCode, palletType, palletCapacityCbm, palletTareWeightKg, recognitionStatus, version]
      properties:
        id: {type: string, pattern: '^[1-9][0-9]*$'}
        fileId: {type: string, pattern: '^[1-9][0-9]*$'}
        palletId: {type: string, pattern: '^[1-9][0-9]*$'}
        palletCode: {type: string}
        palletType: {type: string}
        palletCapacityCbm: {type: number, format: double, minimum: 0.0001}
        palletTareWeightKg: {type: number, format: double, minimum: 0, multipleOf: 0.001}
        ocrProvider: {type: string, nullable: true}
        ocrRawText: {type: string, nullable: true}
        ocrWeightValue: {type: number, format: double, nullable: true, description: OCR 原始含托盘毛重}
        ocrWeightUnit: {type: string, nullable: true}
        confidence: {type: number, format: double, nullable: true}
        grossWeightKg: {type: number, format: double, nullable: true, multipleOf: 0.001, description: 确认时标准化的含托盘毛重 KG}
        adjustedWeightValue: {type: number, format: double, nullable: true, description: 人工修正后的含托盘毛重}
        adjustedWeightUnit: {type: string, nullable: true}
        netWeightKg: {type: number, format: double, nullable: true, multipleOf: 0.001, description: grossWeightKg - palletTareWeightKg}
        recognitionStatus: {type: string, enum: [PENDING, PENDING_CONFIRM, NEEDS_MANUAL, CONFIRMED]}
        adjustmentReason: {type: string, nullable: true}
        adjustedBy: {type: string, nullable: true}
        adjustedAt: {type: string, format: date-time, nullable: true}
        confirmedBy: {type: string, nullable: true}
        confirmedAt: {type: string, format: date-time, nullable: true}
        version: {type: integer, minimum: 0}
    ConfirmWeightResultRequest:
      type: object
      required: [version]
      description: 人工修改字段表示含托盘毛重且必须同时提供；全部省略时直接确认现有 OCR 或已修正毛重。
      properties:
        version: {type: integer, minimum: 0}
        adjustedWeightValue: {type: number, format: double, minimum: 0.001, nullable: true}
        adjustedWeightUnit: {type: string, enum: [KG, LB], nullable: true}
        adjustmentReason: {type: string, minLength: 1, maxLength: 500, nullable: true}
    OrderApprovedInboundCommand:
      type: object
      required: [tenantId, orderId, inboundCode, customerName, warehouseId]
      properties:
        tenantId: {type: string, pattern: '^[1-9][0-9]*$', description: 当前客户隔离 ID}
        orderId: {type: string, pattern: '^[1-9][0-9]*$'}
        orderNo: {type: string, nullable: true}
        inboundCode: {type: string, minLength: 1, maxLength: 40, example: ZBYHK2608140001}
        customerId: {type: string, pattern: '^[1-9][0-9]*$', nullable: true}
        customerName: {type: string, minLength: 1}
        warehouseId: {type: string, pattern: '^[1-9][0-9]*$'}
        warehouseName: {type: string, nullable: true}
        deliveryWarehouseId: {type: string, pattern: '^[1-9][0-9]*$', nullable: true}
        deliveryWarehouseName: {type: string, nullable: true}
        expectedArrivalAt: {type: string, format: date-time, nullable: true}
        businessType: {type: string, nullable: true}
        channelCode: {type: string, nullable: true}
        channelName: {type: string, nullable: true}
        carrierId: {type: string, pattern: '^[1-9][0-9]*$', nullable: true, description: 历史兼容的内部运输供应商快照}
        carrierName: {type: string, nullable: true}
        taxMode: {type: string, nullable: true}
        pricingTaxMode: {type: string, enum: [TAX_INCLUDED, TAX_EXCLUDED], nullable: true, description: 报价包税维度；独立于订单taxMode}
        containerMode: {type: string, nullable: true}
        customsInspection: {type: boolean, nullable: true}
        destinationType: {type: string, nullable: true}
        destinationWarehouseId: {type: string, pattern: '^[1-9][0-9]*$', nullable: true}
        destinationCode: {type: string, nullable: true}
        destinationName: {type: string, nullable: true}
        publicRemark: {type: string, nullable: true}
        expressCompanyName: {type: string, nullable: true}
        expressTrackingNo: {type: string, nullable: true}
    ContainerBookingPageEnvelope:
      type: object
      properties:
        code: {type: string, example: '200'}
        message: {type: string}
        data:
          type: object
          properties:
            records: {type: array, items: {$ref: '#/components/schemas/ContainerBooking'}}
            page: {type: string, pattern: '^[1-9][0-9]*$'}
            size: {type: string, pattern: '^[1-9][0-9]*$'}
            total: {type: string, pattern: '^[0-9]+$'}
            pages: {type: string, pattern: '^[0-9]+$'}
    ContainerBooking:
      type: object
      required: [id, bookingNo, cabinetNo, warehouseId, warehouseName, containerType, capacityCbm, maxWeightKg, planStatus, version]
      properties:
        id: {type: string, pattern: '^[1-9][0-9]*$'}
        planId: {type: string, pattern: '^[1-9][0-9]*$', nullable: true, description: 关联智能装柜计划ID；未创建计划时为空}
        bookingNo: {type: string, maxLength: 40}
        containerNo: {type: string, maxLength: 64, nullable: true}
        cabinetNo: {type: string, maxLength: 64}
        channelCode: {type: string, maxLength: 64, nullable: true, description: Missing legacy snapshots are blocked from loading until explicitly backfilled}
        channelName: {type: string, maxLength: 128, nullable: true}
        oceanBookingId: {type: string, pattern: '^[1-9][0-9]*$', nullable: true}
        oceanBookingRequirementId: {type: string, pattern: '^[1-9][0-9]*$', nullable: true}
        warehouseId: {type: string, pattern: '^[1-9][0-9]*$'}
        warehouseName: {type: string, maxLength: 128}
        billOfLadingNo: {type: string, maxLength: 128, nullable: true}
        vesselName: {type: string, maxLength: 128, nullable: true}
        voyageNo: {type: string, maxLength: 64, nullable: true}
        containerType: {type: string, enum: [20GP, 40GP, 40HC, 40NR, 45HC], description: 平台固定柜型}
        shippingCompanyId: {type: string, nullable: true}
        shippingCompanyName: {type: string, maxLength: 128, nullable: true}
        departurePortCode: {type: string, maxLength: 32, nullable: true}
        departurePortName: {type: string, maxLength: 128, nullable: true}
        destinationPortCode: {type: string, maxLength: 32, nullable: true}
        destinationPortName: {type: string, maxLength: 128, nullable: true}
        destinationWarehouseCode: {type: string, maxLength: 64, nullable: true}
        destinationWarehouseName: {type: string, maxLength: 128, nullable: true}
        capacityCbm: {type: number, exclusiveMinimum: true, minimum: 0, description: 必须等于柜型固定容量}
        maxWeightKg: {type: number, exclusiveMinimum: true, minimum: 0, description: 必须等于柜型固定限重}
        terminalTruckingCompanyId: {type: string, pattern: '^[1-9][0-9]*$', nullable: true, description: ACTIVE Warehouse Supplier ID validated as TRUCKING}
        terminalTruckingCompany: {type: string, maxLength: 128, nullable: true, description: Server-frozen Warehouse supplier name snapshot}
        loadingAt: {type: string, format: date-time, nullable: true}
        estimatedSailingAt: {type: string, format: date-time, nullable: true}
        actualSailingAt: {type: string, format: date-time, nullable: true}
        estimatedPortArrivalAt: {type: string, format: date-time, nullable: true}
        actualPortArrivalAt: {type: string, format: date-time, nullable: true}
        estimatedWarehouseArrivalAt: {type: string, format: date-time, nullable: true}
        actualWarehouseArrivalAt: {type: string, format: date-time, nullable: true}
        planStatus: {type: string, enum: [WAIT_LOADING, EDITING, LOADING, COMPLETED]}
        version: {type: integer, minimum: 0}
    ContainerSaveRequest:
      type: object
      required: [cabinetNo, warehouseId, warehouseName, containerType, capacityCbm, maxWeightKg]
      properties:
        containerNo: {type: string, maxLength: 64, nullable: true}
        cabinetNo: {type: string, maxLength: 64}
        warehouseId: {type: string, pattern: '^[1-9][0-9]*$'}
        warehouseName: {type: string, maxLength: 128}
        billOfLadingNo: {type: string, maxLength: 128, nullable: true}
        vesselName: {type: string, maxLength: 128, nullable: true}
        voyageNo: {type: string, maxLength: 64, nullable: true}
        containerType: {type: string, enum: [20GP, 40GP, 40HC, 40NR, 45HC], description: 平台固定柜型}
        shippingCompanyId: {type: string, pattern: '^[1-9][0-9]*$', nullable: true}
        shippingCompanyName: {type: string, maxLength: 128, nullable: true}
        departurePortCode: {type: string, maxLength: 32, nullable: true}
        departurePortName: {type: string, maxLength: 128, nullable: true}
        destinationPortCode: {type: string, maxLength: 32, nullable: true}
        destinationPortName: {type: string, maxLength: 128, nullable: true}
        destinationWarehouseCode: {type: string, maxLength: 64, nullable: true}
        destinationWarehouseName: {type: string, maxLength: 128, nullable: true}
        capacityCbm: {type: number, exclusiveMinimum: true, minimum: 0, description: 必须等于柜型固定容量}
        maxWeightKg: {type: number, exclusiveMinimum: true, minimum: 0, description: 必须等于柜型固定限重}
        terminalTruckingCompanyId: {type: string, pattern: '^[1-9][0-9]*$', nullable: true, description: ACTIVE Warehouse Supplier ID validated as TRUCKING}
        terminalTruckingCompany: {type: string, maxLength: 128, nullable: true, description: Optional consistency hint; persisted name always comes from Warehouse and cannot replace the ID}
        loadingAt: {type: string, format: date-time, nullable: true}
        estimatedSailingAt: {type: string, format: date-time, nullable: true}
        actualSailingAt: {type: string, format: date-time, nullable: true}
        estimatedPortArrivalAt: {type: string, format: date-time, nullable: true}
        actualPortArrivalAt: {type: string, format: date-time, nullable: true}
        estimatedWarehouseArrivalAt: {type: string, format: date-time, nullable: true}
        actualWarehouseArrivalAt: {type: string, format: date-time, nullable: true}
    ContainerFullUpdateRequest:
      type: object
      required: [version, data]
      properties:
        version: {type: integer, minimum: 0}
        data: {$ref: '#/components/schemas/ContainerSaveRequest'}
    ContainerTransportUpdateRequest:
      type: object
      required: [version, reason]
      properties:
        containerNo: {type: string, maxLength: 64, nullable: true, description: 真实集装箱号；PDA任务创建前可空，任务创建后允许替换但禁止清空}
        voyageNo: {type: string, maxLength: 64, nullable: true}
        version: {type: integer, minimum: 0}
        reason: {type: string, maxLength: 500}
    SmartLoadingPushRequest:
      type: object
      required: [expectedVersion]
      properties:
        expectedVersion: {type: integer, minimum: 0}
    ContainerDocumentAttachRequest:
      type: object
      required: [fileId, expectedVersion]
      properties:
        fileId: {type: string, pattern: '^[1-9][0-9]*$'}
        expectedVersion: {type: integer, minimum: 0}
        operationReason: {type: string, maxLength: 500, nullable: true}
    ContainerDocumentCompleteRequest:
      type: object
      required: [expectedVersion]
      properties:
        expectedVersion: {type: integer, minimum: 0}
        operationReason: {type: string, maxLength: 500, nullable: true}
    ContainerDocumentUploadRequest:
      type: object
      required: [file, expectedVersion]
      additionalProperties: false
      properties:
        file: {type: string, format: binary, description: 用户直接选择的清关资料}
        expectedVersion: {type: integer, minimum: 0, description: 当前文档乐观锁版本，首次上传为 0}
        operationReason: {type: string, maxLength: 500, nullable: true}
    MerchantInboundBillingEnvelope:
      type: object
      properties:
        code: {type: string, example: '200'}
        message: {type: string}
        data:
          type: object
          properties:
            inbound: {type: object, description: 入库单详情}
            measurementSummary: {type: object, description: 测量汇总}
            measurementItems: {type: array, items: {type: object}}
            weightResults: {type: array, items: {type: object}}
            measurementImages: {type: array, items: {type: object}}
            weightImages: {type: array, items: {type: object}}
            billingBasis: {type: object, description: 计费依据}
            latestFee: {type: object, nullable: true, description: 兼容保留的最新计费快照}
            publishedFeeDetail:
              allOf:
                - {$ref: '#/components/schemas/PublishedFreightFeeDetail'}
              nullable: true
              description: 后台与客户共用的已发布FBA头程运费应收明细
    PublishedFreightFeeDetail:
      type: object
      description: 审核发布后绑定入库单的FBA头程运费应收明细
      properties:
        id: {type: integer, format: int64, description: 入库费用明细ID}
        inboundId: {type: integer, format: int64}
        inboundCode: {type: string}
        sourceFeeId: {type: integer, format: int64, description: 来源计费快照ID}
        sourceFeeVersion: {type: integer}
        sourceFeeNo: {type: string}
        direction: {type: string, enum: [RECEIVABLE]}
        businessDate: {type: string, format: date}
        customerId: {type: integer, format: int64}
        customerName: {type: string}
        invoiceTitle: {type: string, nullable: true}
        channelCode: {type: string, nullable: true}
        channelName: {type: string, nullable: true}
        destinationCode: {type: string, nullable: true}
        destinationName: {type: string, nullable: true}
        packageCount: {type: integer, nullable: true}
        actualGrossWeightKg: {type: number, format: double, nullable: true}
        actualVolumeCbm: {type: number, format: double, nullable: true}
        volumeWeightKg: {type: number, format: double, nullable: true}
        chargeableWeightKg: {type: number, format: double, nullable: true}
        chargeableVolumeCbm: {type: number, format: double, nullable: true}
        chargeableQuantity: {type: number, format: double}
        chargeUnit: {type: string, enum: [KG, CBM]}
        feeTypeName: {type: string, example: FBA头程运费}
        unitPrice: {type: number, format: double}
        currency: {type: string, example: CNY}
        amount: {type: number, format: double, description: 客户应收金额}
        reviewStatus: {type: string, enum: [APPROVED]}
        publicationStatus: {type: string, enum: [PUBLISHED]}
        publishedAt: {type: string, format: date-time}
        inboundedAt: {type: string, format: date-time, nullable: true}
        settlementIncluded: {type: boolean, example: true}
    InboundOrderPageEnvelope:
      type: object
      properties:
        code: {type: string, example: '200'}
        message: {type: string}
        data: {$ref: '#/components/schemas/InboundOrderPage'}
    InboundOrderPage:
      type: object
      properties:
        records:
          type: array
          items: {$ref: '#/components/schemas/InboundOrderSummary'}
        page: {type: integer, minimum: 1}
        size: {type: integer, minimum: 1}
        total: {type: integer, format: int64, minimum: 0}
        pages: {type: integer, format: int64, minimum: 0}
    InboundOrderSummary:
      type: object
      required: [id, tenantId]
      properties:
        id: {type: string, pattern: '^[1-9][0-9]*$'}
        tenantId: {type: string, pattern: '^[1-9][0-9]*$', description: 记录所属客户 ID；字段名为历史兼容，用于详情和处理接口的客户隔离}
        orderId: {type: string, nullable: true}
        orderNo: {type: string, nullable: true}
        inboundCode: {type: string, nullable: true}
        processStatus: {type: string}
        customerId: {type: string, nullable: true}
        companyId: {type: string, nullable: true}
        taxMode: {type: string, nullable: true, description: 订单报关方式快照}
        pricingTaxMode: {type: string, enum: [TAX_INCLUDED, TAX_EXCLUDED], nullable: true, description: 下单时选择的报价包税维度快照}
    InboundMeasurementCallbackRequest:
      type: object
      required: [eventNo, externalDetailNo, warehouseCode, inboundCode, inboundDetailId, deviceCode, measuredAt, boxSpecification, packageCount, lengthCm, widthCm, heightCm]
      properties:
        eventNo: {type: string, maxLength: 128, pattern: '^[A-Za-z0-9._:-]+$', example: M202608010001}
        externalDetailNo: {type: string, maxLength: 128, pattern: '^[A-Za-z0-9._:-]+$', example: BOX-20260801-0001}
        warehouseCode: {type: string, maxLength: 50, example: CN-YW-01}
        inboundCode: {type: string, maxLength: 40, example: ZBYHK2608140001}
        inboundDetailId: {type: string, example: '190000000000000001', description: 柏悦订单货物明细ID}
        deviceCode: {type: string, maxLength: 64, example: DEVICE-01}
        measuredAt: {type: string, format: date-time, example: '2026-08-01T10:30:00+08:00'}
        boxSpecification: {type: string, maxLength: 64, example: '40x30x47cm'}
        lengthCm: {type: number, exclusiveMinimum: true, minimum: 0, example: 50.20}
        widthCm: {type: number, exclusiveMinimum: true, minimum: 0, example: 40.10}
        heightCm: {type: number, exclusiveMinimum: true, minimum: 0, example: 30.00}
        packageCount: {type: integer, minimum: 1, maximum: 1000000, example: 50}
        unitWeightKg: {type: number, exclusiveMinimum: true, minimum: 0, nullable: true, example: 20}
        remark: {type: string, maxLength: 500, nullable: true}
    InboundMeasurementEventResponse:
      type: object
      properties:
        eventNo: {type: string}
        inboundCode: {type: string}
        inboundDetailId: {type: string}
        measurementId: {type: string}
        measurementItemId: {type: string}
        imageFileId: {type: string}
        accepted: {type: boolean}
        status: {type: string, enum: [RECEIVED]}
        receivedAt: {type: string, format: date-time}
    AssignRequest:
      type: object
      required: [assigneeId, assigneeName]
      properties:
        assigneeId: {type: integer, format: int64}
        assigneeName: {type: string, maxLength: 64}
        reason: {type: string, maxLength: 500}
    ContainerSimulationCreateRequest:
      type: object
      required: [channelCode, warehouseId, containerType, capacityCbm, maxWeightKg]
      properties:
        channelCode: {type: string, maxLength: 64, description: 当前 ACTIVE 价格簿中的真实物流渠道}
        warehouseId: {type: integer, format: int64, minimum: 1}
        containerType: {type: string, enum: [20GP, 40GP, 40HC, 40NR, 45HC], description: 与订舱共用的平台固定柜型}
        capacityCbm: {type: number, minimum: 0, exclusiveMinimum: true, description: 必须等于柜型固定容量}
        maxWeightKg: {type: number, minimum: 0, exclusiveMinimum: true, description: 必须等于柜型固定限重}
    ContainerOceanBookingLinkRequest:
      type: object
      required: [oceanBookingId, requirementId, expectedVersion]
      properties:
        oceanBookingId: {type: integer, format: int64, minimum: 1}
        requirementId: {type: integer, format: int64, minimum: 1}
        expectedVersion: {type: integer, minimum: 0}
    ContainerOceanBookingUnlinkRequest:
      type: object
      required: [expectedVersion, reason]
      properties:
        expectedVersion: {type: integer, minimum: 0}
        reason: {type: string, minLength: 1, maxLength: 500}