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

openapi: 3.0.3
info:
  title: 柏悦头程订单 API
  description: 业务成功和失败均使用 HTTP 200；仅响应体 code 为字符串 "200" 时表示成功，其他 code 表示失败。
  version: 1.7.0
security:
  - bearerAuth: []
paths:
  /internal/exports/v1/DOMESTIC_WAREHOUSE_ORDER_LIST/batches:
    post:
      security: []
      summary: File 异步导出中心分页读取国内仓订单
      description: >-
        仅接受内部服务令牌。selectedOrderNos 非空时忽略查询筛选并严格按所选业务订单号导出；
        selectedOrderNos 为空时按与平台统一订单列表一致的筛选条件导出全部匹配记录，page/size 不属于请求参数。
        Provider 只返回结构化数据，不生成文件；调用方创建 File 任务时 exportType 固定为
        DOMESTIC_WAREHOUSE_ORDER_LIST、format 固定为 XLSX，并需要 platform:order:export。
      parameters:
        - name: X-Internal-Service-Token
          in: header
          required: true
          schema: {type: string, minLength: 32}
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/DomesticWarehouseOrderExportBatchRequest'}
      responses:
        '200': {description: 返回固定列定义、当前批数据、游标与首批总数}
        '403': {description: 内部服务令牌无效}
  /api/merchant/v1/orders/first-leg/addresses:
    get:
      summary: 查询当前客户下单地址簿
      parameters:
        - name: addressType
          in: query
          required: false
          schema: {type: string, enum: [PICKUP, PRIVATE_DESTINATION]}
      responses:
        '200': {description: 只返回登录客户可用地址}
        '403': {description: 需要订单查看、创建或编辑权限}
    post:
      summary: 保存当前客户下单地址
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/CustomerOrderAddressSaveRequest'}
      responses:
        '200': {description: 返回地址内部 ID，Long 按字符串序列化}
        '403': {description: 需要 merchant:order:create 权限}
  /api/merchant/v1/orders/first-leg/addresses/{id}:
    put:
      summary: 修改当前客户下单地址
      description: 已创建订单保存独立快照，本操作不会修改历史订单。
      parameters:
        - {name: id, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/CustomerOrderAddressSaveRequest'}
      responses: {'200': {description: 成功}, '403': {description: 需要 merchant:order:edit 权限}}
    delete:
      summary: 停用当前客户下单地址
      description: 停用后不能用于新订单，历史订单快照不受影响。
      parameters:
        - {name: id, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
      responses: {'200': {description: 成功}, '403': {description: 需要 merchant:order:edit 权限}}
  /api/merchant/v1/orders/first-leg/batch-imports/template:
    get:
      summary: 下载 Excel 批量下单模板
      description: >-
        返回仅含中文业务列名的 xlsx。静态业务枚举使用中文下拉；仓库、渠道和客户地址按当前登录客户及正式主数据实时生成，
        工作表不暴露内部 ID。示例与填写规则位于独立说明页，不占用可导入数据行。导入时重新校验动态选项的状态、归属和组合有效性。
      responses:
        '200': {description: xlsx 模板}
        '403': {description: 需要 merchant:order:create 权限}
  /api/merchant/v1/orders/first-leg/batch-imports:
    post:
      summary: 上传 Excel 批量创建订单草稿
      description: >-
        ATOMIC 在任一行失败时整批回滚；PARTIAL 每行独立事务，错误行不影响成功行。
        同一操作者重试必须复用 Idempotency-Key，每行再以 clientRowId 派生稳定幂等键。
        仅接受当前中文模板，中文下拉值由服务端映射为权威代码，不兼容历史英文技术表头。
        原文件和错误报告分别通过 File 的 ORDER_BATCH_IMPORT_SOURCE、ORDER_BATCH_IMPORT_ERROR_REPORT 契约保存。
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - name: mode
          in: query
          required: true
          schema: {type: string, enum: [ATOMIC, PARTIAL]}
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file: {type: string, format: binary, description: 最大 5MB，仅 xlsx；最多 50 行}
      responses:
        '200': {description: 返回逐行结果、原文件 ID 及可选错误报告文件 ID}
        '403': {description: 需要 merchant:order:create 权限}
  /api/platform/v1/orders/first-leg/inbound-code-policy:
    get:
      summary: 平台端查询全系统入仓码模式
      description: 与客户下单端返回同一份全局策略，不按客户区分。
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: {type: string, example: '200'}
                  data: {$ref: '#/components/schemas/InboundCodePolicy'}
        '403': {description: 需要平台订单列表、创建、编辑或提交权限之一}
  /api/platform/v1/orders/first-leg/inbound-code-associations/{inboundCode}:
    get:
      summary: 平台按全局入仓码查询订单基础关联
      description: >-
        需要 platform:order:list。入仓码和订单业务号是主要展示键；Long ID 均以字符串返回，
        只供页面路由和后续接口关联。查询直接使用 Order 全局唯一入仓码事实，不跨库读取 Firstleg。
      parameters:
        - $ref: '#/components/parameters/InboundCodePath'
      responses:
        '200':
          description: 查询成功或业务失败，按响应体 code 判断
          content:
            application/json:
              schema: {$ref: '#/components/schemas/InboundCodeAssociationEnvelope'}
        '403': {description: 需要平台身份和 platform:order:list 权限}
  /api/platform/v1/orders:
    get:
      summary: 平台统一订单列表
      description: >-
        统一返回七态产品主状态、下一步动作及测量/预装/装柜/派送摘要，需要 platform:order:list。
        入仓码来源由全系统统一模式控制：AUTO 在订单提交时按物流渠道生成，格式为物流前缀+YYMMDD+当天全平台票序；
        LEGACY_MANUAL 在草稿中录入旧系统入仓码。两种模式下入仓码一经提交均固定；有入库单时同时返回
        inboundId、inboundVersion、loadingVersion、pickingVersion；inboundVersion
        才是 C04 loading/complete 的 expectedVersion，loadingVersion 当前等于 pickingVersion（兼容别名）。
        tenantId 省略时跨全部客户；mainStatus 省略时按订单创建时间分页，指定 PENDING_REVIEW 时由 Order 查询，
        指定其他主状态时由 Firstleg 精确分页。旧 /orders/first-leg 接口保持兼容。
        列表行同时返回 customerRemark（客户下单备注）、latestInternalNote（最新一条平台内部备注）和
        relation（仅有关联时返回；PARENT 含 childCount，CHILD 含 rootOrderId、parentOrderId 与 splitSequence）。
        coLoadGroup 仅平台响应返回，由 Order 经 Firstleg 内部批量只读契约聚合；成员业务标识由 Order 权威订单片段补齐。
      parameters:
        - {name: tenantId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - $ref: '#/components/parameters/UnifiedKeyword'
        - $ref: '#/components/parameters/UnifiedOrderNo'
        - $ref: '#/components/parameters/UnifiedMainStatus'
        - {name: customerId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {name: receivingWarehouseId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {name: destinationWarehouseId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - $ref: '#/components/parameters/UnifiedInboundCode'
        - $ref: '#/components/parameters/UnifiedInternalOrderStatus'
        - $ref: '#/components/parameters/UnifiedExpectedArrivalDate'
        - $ref: '#/components/parameters/UnifiedFeeReviewStatus'
        - $ref: '#/components/parameters/UnifiedChannelName'
        - $ref: '#/components/parameters/UnifiedContainerNo'
        - $ref: '#/components/parameters/UnifiedCabinetNo'
        - $ref: '#/components/parameters/UnifiedSailingDate'
        - $ref: '#/components/parameters/UnifiedLoaded'
        - $ref: '#/components/parameters/UnifiedFullContainer'
        - $ref: '#/components/parameters/UnifiedMeasurementReviewStatus'
        - $ref: '#/components/parameters/UnifiedFbaCode'
        - $ref: '#/components/parameters/UnifiedCreatedFrom'
        - $ref: '#/components/parameters/UnifiedCreatedTo'
        - $ref: '#/components/parameters/UnifiedPage'
        - $ref: '#/components/parameters/UnifiedSize'
      responses:
        '200':
          description: 成功或业务失败，响应体 code 为字符串 200 时成功
          content:
            application/json:
              schema: {$ref: '#/components/schemas/UnifiedOrderPageEnvelope'}
        '403': {description: 需要平台身份和 platform:order:list 权限}
  /api/platform/v1/orders/{orderId}:
    get:
      summary: 平台统一订单详情
      description: 合并 Order 与 Firstleg 时间线并按发生时间升序返回；返回当前订单片段的 inboundCode 与同柜组摘要；平台可见内部备注。
      parameters:
        - $ref: '#/components/parameters/UnifiedOrderId'
        - $ref: '#/components/parameters/UnifiedTenantId'
      responses:
        '200':
          description: 成功或业务失败，按响应体 code 判断
          content:
            application/json:
              schema: {$ref: '#/components/schemas/UnifiedOrderDetailEnvelope'}
        '403': {description: 需要平台身份和 platform:order:list 权限}
  /api/platform/v1/orders/{orderId}/internal-notes:
    post:
      summary: 添加订单内部备注
      description: 添加仅平台内部可见的订单备注，需要 platform:order:note 权限。
      parameters:
        - $ref: '#/components/parameters/UnifiedOrderId'
        - $ref: '#/components/parameters/UnifiedTenantId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [content]
              properties:
                content: {type: string, minLength: 1, maxLength: 2000}
      responses:
        '200': {description: 备注添加成功或业务失败，按响应体 code 判断}
        '403': {description: 需要 platform:order:note 权限}
  /api/platform/v1/orders/{orderId}/declaration:
    put:
      summary: 版本化修改客户原始申报资料
      description: >-
        需要 platform:order:declaration:edit。货物使用订单内 itemNo 定位，不接受货物数据库 ID；
        不允许修改客户、国内收货仓、订单号、入仓码、状态、仓库/PDA/设备实测、测量审核或计费事实。
        仅待审核、待测量数据、待分柜阶段允许修改；进入装柜中及后续阶段后拒绝修改。
        已有测量或计费事实不阻断客户申报快照更新，详情继续以最新申报与既有实测分别展示；
        只有渠道发生变化时才在写入前校验同柜/分柜/装柜可逆性和重新计价资格，任何校验失败均不写入。
        正式门禁分别为 /internal/firstleg/v1/inbounds/order-channel-changes/validate 与
        /internal/firstleg/v1/pricing/order-channel-changes/validate，两个服务均失败关闭。
        国内收货仓或中转仓如需变化必须重新下单。成功后通过 ORDER_DECLARATION_UPDATED_V1 Outbox
        同步 Firstleg；消费者按 eventId 幂等、version 顺序刷新申报快照，不覆盖实测、箱码或已确认费用。
        本次 changes 含渠道字段时，同版本 Outbox 还必须调用
        /internal/firstleg/v1/pricing/order-channel-changes/apply，使未确认价格预估显式失效；普通申报更新不得调用。
      parameters:
        - $ref: '#/components/parameters/UnifiedOrderId'
        - $ref: '#/components/parameters/UnifiedTenantId'
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/OrderDeclarationUpdateRequest'}
      responses:
        '200': {description: 成功返回新版本、渠道历史标记和字段级前后值；版本冲突、渠道与不可逆履约或已确认费用不兼容时响应体业务码为 A0409}
        '403': {description: 无权限或非平台身份}
  /api/platform/v1/orders/{orderId}/planning:
    put:
      summary: 版本化修改订单运营预估
      description: 需要 platform:order:declaration:edit；只修改预计到货时间与平台预估体积，客户下单和仓库实测体积不受影响。
      parameters:
        - $ref: '#/components/parameters/UnifiedOrderId'
        - $ref: '#/components/parameters/UnifiedTenantId'
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/OrderPlanningUpdateRequest'}
      responses:
        '200': {description: 成功返回新订单版本；版本冲突时响应体业务码为 A0409}
        '403': {description: 无权限或非平台身份}
  /api/merchant/v1/orders:
    get:
      summary: 客户统一订单列表
      description: >-
        只按登录态客户隔离查询，需要 merchant:order:list；不接受目标客户参数。
        有入库单时同时返回 inboundId、inboundVersion、loadingVersion、pickingVersion；inboundVersion
        才是 C04 loading/complete 的 expectedVersion，loadingVersion 当前等于 pickingVersion（兼容别名）。
      parameters:
        - $ref: '#/components/parameters/UnifiedKeyword'
        - $ref: '#/components/parameters/UnifiedOrderNo'
        - $ref: '#/components/parameters/UnifiedMainStatus'
        - {name: customerId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {name: receivingWarehouseId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {name: destinationWarehouseId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - $ref: '#/components/parameters/UnifiedInboundCode'
        - $ref: '#/components/parameters/UnifiedInternalOrderStatus'
        - $ref: '#/components/parameters/UnifiedExpectedArrivalDate'
        - $ref: '#/components/parameters/UnifiedFeeReviewStatus'
        - $ref: '#/components/parameters/UnifiedChannelName'
        - $ref: '#/components/parameters/UnifiedContainerNo'
        - $ref: '#/components/parameters/UnifiedCabinetNo'
        - $ref: '#/components/parameters/UnifiedSailingDate'
        - $ref: '#/components/parameters/UnifiedLoaded'
        - $ref: '#/components/parameters/UnifiedFullContainer'
        - $ref: '#/components/parameters/UnifiedMeasurementReviewStatus'
        - $ref: '#/components/parameters/UnifiedFbaCode'
        - $ref: '#/components/parameters/UnifiedCreatedFrom'
        - $ref: '#/components/parameters/UnifiedCreatedTo'
        - $ref: '#/components/parameters/UnifiedPage'
        - $ref: '#/components/parameters/UnifiedSize'
      responses:
        '200':
          description: 成功或业务失败，按响应体 code 判断
          content:
            application/json:
              schema: {$ref: '#/components/schemas/UnifiedOrderPageEnvelope'}
        '403': {description: 需要 merchant:order:list 权限}
  /api/merchant/v1/orders/{orderId}:
    get:
      summary: 客户统一订单详情
      description: 仅返回登录客户所属订单及客户可见时间线，不返回平台内部备注。
      parameters:
        - $ref: '#/components/parameters/UnifiedOrderId'
      responses:
        '200':
          description: 成功或业务失败，按响应体 code 判断
          content:
            application/json:
              schema: {$ref: '#/components/schemas/UnifiedOrderDetailEnvelope'}
        '403': {description: 需要 merchant:order:view 权限}
  /api/merchant/v1/orders/first-leg:
    get:
      summary: 客户端入库订单聚合列表
      description: 按当前登录客户分页返回订单、货物汇总、收货方快照及头程入仓编码，需要 merchant:order:list 权限；客户 ID 从 JWT 的 tenantId 兼容字段取得。
      parameters:
        - {name: keyword, in: query, required: false, schema: {type: string, maxLength: 64}}
        - {name: orderNo, in: query, required: false, schema: {type: string, maxLength: 64}}
        - {name: receivingWarehouseId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {name: channelName, in: query, required: false, schema: {type: string, maxLength: 128}}
        - {name: customerContact, in: query, required: false, description: 客户名称、联系人或手机号, schema: {type: string, maxLength: 128}}
        - {name: customerId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {name: status, in: query, required: false, schema: {type: string}}
        - {name: operationStatus, in: query, required: false, description: 操作状态，优先于兼容参数 status, schema: {type: string}}
        - {name: destinationType, in: query, required: false, schema: {type: string, maxLength: 32}}
        - {name: destinationWarehouseId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {name: createdFrom, in: query, required: false, schema: {type: string, format: date-time}}
        - {name: createdTo, in: query, required: false, schema: {type: string, format: date-time}}
        - {name: page, in: query, required: false, schema: {type: integer, minimum: 1, default: 1}}
        - {name: size, in: query, required: false, schema: {type: integer, minimum: 1, maximum: 200, default: 20}}
      responses:
        '200':
          description: 成功或业务失败，响应体 code 为字符串 200 时成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  items: {type: array, items: {$ref: '#/components/schemas/FirstLegOrderSummary'}}
    post:
      summary: 创建订单草稿
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/FirstLegOrderDraft'}
      responses:
        '200': {description: 成功或业务失败，按响应体 code 判断}
  /api/merchant/v1/orders/first-leg/inbound-code-associations/{inboundCode}:
    get:
      summary: 客户按入仓码查询本客户订单基础关联
      description: >-
        需要 merchant:order:list。客户范围仅取登录态，不接受客户 ID 参数；其他客户的入仓码统一按不存在处理。
        入仓码和订单业务号是主要展示键，Long ID 只供路由关联。
      parameters:
        - $ref: '#/components/parameters/InboundCodePath'
      responses:
        '200':
          description: 查询成功、不存在或其他业务失败，按响应体 code 判断
          content:
            application/json:
              schema: {$ref: '#/components/schemas/InboundCodeAssociationEnvelope'}
        '403': {description: 需要客户身份和 merchant:order:list 权限}
  /api/merchant/v1/orders/first-leg/batch:
    post:
      summary: 批量创建头程订单草稿
      description: >-
        一次请求为多个外层行创建草稿；每个数组元素对应一张草稿，元素内 cargoes
        对应该行的多个产品明细。每项独立处理，允许部分成功；草稿仅校验渠道、目的仓、SKU
        和箱数，提交审核前再执行完整货物与提货资料校验。最多 50 项。
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              minItems: 1
              maxItems: 50
              items: {$ref: '#/components/schemas/FirstLegBatchDraftItem'}
      responses:
        '200':
          description: 批量处理完成；业务失败通过 items.errorCode 和 items.errorMessage 逐项返回
          content:
            application/json:
              schema: {$ref: '#/components/schemas/FirstLegBatchDraftResponse'}
        '400': {description: 请求数组为空、超过 50 项或幂等键缺失}
        '403': {description: 需要 merchant:order:create 权限}
  /api/merchant/v1/orders/first-leg/inbound-code-policy:
    get:
      summary: 查询全系统入仓码模式
      description: >-
        返回订单服务当前统一运行模式。AUTO 表示提交时由新系统生成；LEGACY_MANUAL
        表示两套系统并跑期间必须录入旧系统生成的入仓码。该策略不按客户区分。
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: {type: string, example: '200'}
                  data: {$ref: '#/components/schemas/InboundCodePolicy'}
        '403': {description: 需要 merchant:order:list、merchant:order:create 或 merchant:order:edit 权限之一}
  /api/merchant/v1/orders/first-leg/{id}/submit:
    post:
      summary: 提交订单
      parameters:
        - $ref: '#/components/parameters/OrderId'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200': {description: 成功或业务失败，按响应体 code 判断}
  /api/platform/v1/orders/first-leg:
    get:
      summary: 平台分页查询头程订单
      description: tenantId 是目标客户 ID 的兼容参数名；省略时查询全部客户订单，传入时仅查询指定客户。
      parameters:
        - name: tenantId
          in: query
          required: false
          description: 可选的目标客户筛选；tenantId 为历史兼容参数名
          schema: {type: integer, format: int64, minimum: 1}
      responses:
        '200': {description: 查询成功或业务失败，按响应体 code 判断}
        '403': {description: 需要 platform:order:list 权限和平台身份}
    post:
      summary: 平台代客创建订单草稿
      parameters:
        - $ref: '#/components/parameters/TenantId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/FirstLegOrderDraft'}
      responses:
        '200': {description: 成功或业务失败，按响应体 code 判断}
        '403': {description: 需要 platform:order:create 权限}
  /api/platform/v1/orders/first-leg/tenant-statistics:
    get:
      tags: [Platform first-leg orders]
      summary: 查询客户累计及本月运单数
      description: 仅统计 submitted_at 非空的 MASTER 根运单，草稿和 CHILD 拆分单不计入；累计不受取消或驳回影响；月份按 Asia/Shanghai 半开区间计算。
      parameters:
        - {$ref: '#/components/parameters/TenantId'}
      responses:
        '200':
          description: 成功；需要 platform:order:list 权限
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: {type: string, example: '200'}
                  data: {$ref: '#/components/schemas/TenantOrderStatisticsResponse'}
        '403': {description: 需要平台身份和 platform:order:list 权限}

  /api/platform/v1/orders/first-leg/tenant-counts:
    get:
      summary: 批量查询客户运单数
      description: 按客户 ID 返回真实头程运单数量，tenantIds 为历史兼容参数名；最多 200 个客户。
      parameters:
        - name: tenantIds
          in: query
          required: true
          schema: {type: array, maxItems: 200, items: {type: integer, format: int64}}
      responses:
        '200': {description: 查询成功或业务失败，按响应体 code 判断}
        '403': {description: 需要 platform:order:list 权限}
  /api/platform/v1/orders/first-leg/{id}/submit:
    post:
      summary: 平台代客提交指定订单
      parameters:
        - $ref: '#/components/parameters/OrderId'
        - $ref: '#/components/parameters/TenantId'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200': {description: 成功或业务失败，按响应体 code 判断}
        '403': {description: 需要 platform:order:submit 权限}
  /api/platform/v1/orders/first-leg/{id}:
    put:
      summary: 平台编辑指定订单草稿
      parameters:
        - $ref: '#/components/parameters/OrderId'
        - $ref: '#/components/parameters/TenantId'
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/FirstLegOrderDraft'}
      responses:
        '200': {description: 成功或业务失败，按响应体 code 判断}
        '403': {description: 需要 platform:order:edit 权限}
  /internal/order/v1/fulfillment-splits:
    post:
      summary: 创建父订单装柜拆分（Firstleg 内部）
      parameters:
        - $ref: '#/components/parameters/InternalToken'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/FulfillmentSplitCreateRequest' }
      responses:
        '200': { description: 成功, content: { application/json: { schema: { $ref: '#/components/schemas/FulfillmentSplitResponse' } } } }
    
  /internal/order/v1/fulfillment-splits/{tenantId}/{parentOrderId}:
    get:
      summary: 查询根订单、已完成分片与当前余量（Firstleg 内部）
      parameters:
        - $ref: '#/components/parameters/InternalToken'
        - { name: tenantId, in: path, required: true, schema: { type: integer, format: int64 } }
        - { name: parentOrderId, in: path, required: true, schema: { type: integer, format: int64 } }
      responses:
        '200': { description: 成功；返回原始箱数、累计已装和当前余量 }
        '403': { description: 内部凭证无效 }

  /api/platform/v1/orders/{orderId}/fulfillment-tree:
    get:
      summary: 查询父子订单与柜次数量摘要
      parameters:
        - { name: orderId, in: path, required: true, schema: { type: integer, format: int64 } }
        - { name: tenantId, in: query, required: true, schema: { type: integer, format: int64 } }
      responses: { '200': { description: 成功 }, '403': { description: 无权限 } }

  /api/merchant/v1/orders/{orderId}/fulfillment-tree:
    get:
      summary: 查询我的父子订单与柜次数量摘要
      parameters:
        - { name: orderId, in: path, required: true, schema: { type: integer, format: int64 } }
      responses: { '200': { description: 成功 }, '403': { description: 无权限 } }

  /api/platform/v1/orders/container-bookings/{containerBookingId}/fulfillment-slices:
    get:
      summary: 平台按柜次查询全部订单分片
      description: tenantId 可选；省略时跨客户汇总。响应不包含照片、锁码或内部审计字段。
      parameters:
        - {name: containerBookingId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {name: tenantId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
      responses:
        '200': {description: 成功；无分片时返回空数组}
        '403': {description: 需要平台身份和 platform:order:list 权限}
  /api/merchant/v1/orders/container-bookings/{containerBookingId}/fulfillment-slices:
    get:
      summary: 客户按柜次查询本客户订单分片
      description: 客户范围来自登录态，不接受目标客户参数。
      parameters:
        - {name: containerBookingId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
      responses:
        '200': {description: 成功；无分片时返回空数组}
        '403': {description: 需要 merchant:order:view 权限}

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    DomesticWarehouseOrderExportBatchRequest:
      type: object
      required: [taskId, tenantId, appCode, requestedBy, dispatchVersion, parameters, limit]
      properties:
        taskId: {type: string, pattern: '^[1-9][0-9]*$'}
        tenantId: {type: string, enum: ['0'], description: 平台导出固定为0}
        appCode: {type: string, enum: [PLATFORM]}
        requestedBy: {type: string, pattern: '^[1-9][0-9]*$'}
        dispatchVersion: {type: integer, minimum: 1}
        parameters: {$ref: '#/components/schemas/DomesticWarehouseOrderExportParameters'}
        cursor: {type: string, nullable: true}
        snapshotToken: {type: string, nullable: true, maxLength: 512}
        limit: {type: integer, minimum: 1, maximum: 500}
    DomesticWarehouseOrderExportParameters:
      type: object
      description: >-
        selectedOrderNos 非空时仅导出所选订单；为空或省略时使用其余筛选字段导出全量匹配结果。
        筛选字段与 GET /api/platform/v1/orders 一致，但不得传 page、size。
      properties:
        selectedOrderNos:
          type: array
          maxItems: 5000
          uniqueItems: true
          items: {type: string, minLength: 1, maxLength: 64}
        tenantId: {type: string, pattern: '^[1-9][0-9]*$'}
        keyword: {type: string, maxLength: 64}
        orderNo: {type: string, maxLength: 64}
        mainStatus: {type: string, enum: [PENDING_REVIEW, WAIT_MEASURE, INBOUNDED, WAIT_SPLIT, LOADING, LOADED, DELIVERED]}
        customerId: {type: string, pattern: '^[1-9][0-9]*$'}
        receivingWarehouseId: {type: string, pattern: '^[1-9][0-9]*$'}
        destinationWarehouseId: {type: string, pattern: '^[1-9][0-9]*$'}
        inboundCode: {type: string, maxLength: 64}
        internalOrderStatus: {type: string, maxLength: 32}
        expectedArrivalDate: {type: string, format: date}
        feeReviewStatus: {type: string, enum: [UNRECORDED, PENDING, APPROVED, REJECTED]}
        channelName: {type: string, maxLength: 128}
        containerNo: {type: string, maxLength: 64}
        cabinetNo: {type: string, maxLength: 64}
        sailingDate: {type: string, format: date}
        loaded: {type: boolean}
        fullContainer: {type: boolean}
        measurementReviewStatus: {type: string, enum: [UNRECORDED, PENDING, APPROVED, REJECTED]}
        fbaCode: {type: string, maxLength: 64}
        createdFrom: {type: string, format: date-time}
        createdTo: {type: string, format: date-time}
    OrderDeclarationUpdateRequest:
      type: object
      required: [expectedVersion, cargoes]
      properties:
        expectedVersion: {type: integer, minimum: 0}
        customerRemark: {type: string, nullable: true, maxLength: 1000}
        expectedArrivalAt: {type: string, format: date-time, nullable: true}
        estimatedVolumeCbm: {type: number, minimum: 0.0001, nullable: true, description: 平台运营预估体积，独立于客户下单货物体积与仓库实测体积}
        channelCode: {type: string, maxLength: 64, description: 与 channelName 同时传；变更时重新校验价格渠道，入仓码保持不变}
        channelName: {type: string, maxLength: 128}
        cargoes: {type: array, minItems: 1, maxItems: 500, items: {$ref: '#/components/schemas/OrderDeclarationCargo'}}
    OrderPlanningUpdateRequest:
      type: object
      required: [expectedVersion]
      properties:
        expectedVersion: {type: integer, minimum: 0}
        expectedArrivalAt: {type: string, format: date-time, nullable: true}
        estimatedVolumeCbm: {type: number, minimum: 0.0001, nullable: true}
    OrderDeclarationCargo:
      type: object
      required: [itemNo, cargoName, packageCount, totalQuantity, lengthCm, widthCm, heightCm, grossWeightKg, volumeCbm]
      properties:
        itemNo: {type: integer, minimum: 1, maximum: 500, description: 订单内稳定货物行号}
        cargoName: {type: string, maxLength: 128}
        cargoNameEn: {type: string, nullable: true, maxLength: 128}
        skuNo: {type: string, nullable: true, maxLength: 64}
        model: {type: string, nullable: true, maxLength: 64}
        packageCount: {type: integer, minimum: 1}
        totalQuantity: {type: integer, minimum: 1}
        lengthCm: {type: number, minimum: 0.01}
        widthCm: {type: number, minimum: 0.01}
        heightCm: {type: number, minimum: 0.01}
        grossWeightKg: {type: number, minimum: 0.001}
        volumeCbm: {type: number, minimum: 0.0001}
        netWeightKg: {type: number, nullable: true, minimum: 0.001}
        hsCode: {type: string, nullable: true, maxLength: 20}
        customsHsCode: {type: string, nullable: true, maxLength: 20}
        unitsPerPackage: {type: integer, nullable: true, minimum: 1}
        unitDeclaredValue: {type: number, nullable: true, minimum: 0}
        declaredValue: {type: number, nullable: true, minimum: 0}
        currency: {type: string, nullable: true, pattern: '^[A-Z]{3}$'}
        material: {type: string, nullable: true, maxLength: 128}
        usage: {type: string, nullable: true, maxLength: 128}
        brand: {type: string, nullable: true, maxLength: 64}
        cargoRemark: {type: string, nullable: true, maxLength: 500}
    TenantOrderStatisticsResponse:
      type: object
      required: [tenantId, totalSubmittedOrders, currentMonthSubmittedOrders, monthStart, nextMonthStart, zoneId, asOf]
      properties:
        tenantId: {type: string, pattern: '^[1-9][0-9]*$', description: Long 按字符串序列化以避免 JavaScript 精度丢失}
        totalSubmittedOrders: {type: string, pattern: '^[0-9]+$', description: Long 按字符串序列化}
        currentMonthSubmittedOrders: {type: string, pattern: '^[0-9]+$', description: Long 按字符串序列化}
        monthStart: {type: string, format: date-time}
        nextMonthStart: {type: string, format: date-time}
        zoneId: {type: string, example: Asia/Shanghai}
        asOf: {type: string, format: date-time}
    UnifiedMainStatus:
      type: string
      enum: [PENDING_REVIEW, WAIT_MEASURE, INBOUNDED, WAIT_SPLIT, LOADING, LOADED, DELIVERED]
      description: >-
        统一订单七态产品主状态。WAIT_SPLIT 为正式待分柜状态，INBOUNDED 仅兼容存量已入库记录。
    UnifiedOrderPageEnvelope:
      type: object
      properties:
        code: {type: string, example: '200'}
        message: {type: string}
        data: {$ref: '#/components/schemas/UnifiedOrderPage'}
    UnifiedOrderPage:
      type: object
      properties:
        records: {type: array, items: {$ref: '#/components/schemas/UnifiedOrderRow'}}
        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}
    UnifiedOrderDetailEnvelope:
      type: object
      properties:
        code: {type: string, example: '200'}
        message: {type: string}
        data: {$ref: '#/components/schemas/UnifiedOrderDetail'}
    UnifiedOrderDetail:
      type: object
      properties:
        summary: {$ref: '#/components/schemas/UnifiedOrderRow'}
        order:
          type: object
          properties:
            order: {type: object, description: Order 服务订单主实体}
            cargoes: {type: array, items: {type: object}}
            parties: {type: array, items: {type: object}}
            internalNotes: {type: array, items: {type: object}, description: 客户详情始终为空数组}
            statusHistory: {type: array, items: {type: object}}
        timeline: {type: array, items: {$ref: '#/components/schemas/UnifiedOrderTimelineEvent'}}
    UnifiedOrderRow:
      type: object
      properties:
        orderId: {type: integer, format: int64}
        orderVersion: {type: integer, nullable: true, description: 列表行编辑使用的订单乐观锁版本，不作为业务编号展示}
        tenantId: {type: integer, format: int64}
        orderNo: {type: string}
        mainStatus: {$ref: '#/components/schemas/UnifiedMainStatus'}
        nextAction: {type: string, nullable: true}
        relation: {$ref: '#/components/schemas/UnifiedOrderRelation'}
        internalOrderStatus: {type: string, enum: [DRAFT, SUBMITTED, APPROVED, ACCEPTED, REJECTED, CANCELLED, PROCESSING, COMPLETED], nullable: true}
        customerId: {type: integer, format: int64, nullable: true}
        customerName: {type: string, nullable: true}
        channelCode: {type: string, nullable: true, description: 稳定物流渠道编码，仅供业务校验；直接来自当前 Order 或 Firstleg 权威快照，不由 channelName 推导}
        channelName: {type: string, nullable: true}
        channelChanged: {type: boolean, description: 当前订单历史上是否由平台变更过渠道}
        receivingWarehouseId: {type: integer, format: int64, nullable: true}
        receivingWarehouseName: {type: string, nullable: true}
        destinationWarehouseId: {type: integer, format: int64, nullable: true}
        destinationWarehouseName: {type: string, nullable: true}
        inboundId: {type: integer, format: int64, nullable: true}
        inboundVersion: {type: integer, nullable: true, description: C04 loading/complete 的 expectedVersion}
        inboundCode: {type: string, nullable: true, description: 当前订单片段的权威入仓码；缺失时为 null，不得回退为 orderId 或 orderNo}
        expectedShipDate: {type: string, format: date, nullable: true}
        totalPackageCount: {type: integer, nullable: true, description: 无入仓事实时为当前订单有效货物箱数合计；存在入仓业务单元后为该单元履约总箱数，拆分后不以父单原始箱数覆盖}
        recommendedPalletType: {type: string, nullable: true, description: 当前无列表级权威事实时返回 null，不得返回固定托盘类型}
        locationCodes: {type: string, nullable: true}
        estimatedVolumeCbm: {type: number, nullable: true, description: 平台运营填写的预估体积，不得与客户下单或实测体积混用}
        expectedVolumeCbm: {type: number, nullable: true, description: Order 客户下单货物体积合计，不得与平台预估或实测体积混用}
        actualGrossWeightKg: {type: number, nullable: true, description: 仅 Firstleg 实测毛重；无实测时返回 null}
        actualVolumeCbm: {type: number, nullable: true, description: 仅 Firstleg 实测体积；无实测时返回 null}
        expectedArrivalAt: {type: string, format: date-time, nullable: true}
        feeReviewStatus: {type: string, nullable: true, description: Firstleg 入仓费用审核快照；财务状态不在本字段表达}
        companyName: {type: string, nullable: true}
        businessType: {type: string, nullable: true}
        pickupMethod: {type: string, nullable: true}
        requestedPickupAt: {type: string, format: date-time, nullable: true, description: Customer-requested pickup appointment from the pickup snapshot}
        taxMode: {type: string, nullable: true}
        containerMode: {type: string, nullable: true}
        customsInspection: {type: boolean, nullable: true}
        destinationType: {type: string, nullable: true}
        destinationCode: {type: string, nullable: true}
        totalPalletCount: {type: integer, nullable: true}
        chargeableWeightKg: {type: number, nullable: true, description: Firstleg confirmed billing snapshot chargeable weight in kilograms}
        chargeableVolumeCbm: {type: number, nullable: true}
        volumetricWeightKg: {type: number, nullable: true}
        totalNetWeightKg: {type: number, nullable: true, description: 统一订单货物净重展示字段；严格来源 Firstleg actualNetWeightKg，不以毛重回退}
        measurementCompletedAt: {type: string, format: date-time, nullable: true}
        inboundCompletedAt: {type: string, format: date-time, nullable: true}
        expressCompany: {type: string, nullable: true}
        expressTrackingNo: {type: string, nullable: true}
        createdBy: {type: string, nullable: true}
        skuNos: {type: array, nullable: true, items: {type: string}}
        totalQuantity: {type: integer, nullable: true}
        shipmentId: {type: string, nullable: true}
        referenceId: {type: string, nullable: true}
        measurement: {$ref: '#/components/schemas/UnifiedMeasurementSummary'}
        preload: {$ref: '#/components/schemas/UnifiedPreloadSummary'}
        loading: {$ref: '#/components/schemas/UnifiedLoadingSummary'}
        delivery: {$ref: '#/components/schemas/UnifiedDeliverySummary'}
        transport: {$ref: '#/components/schemas/UnifiedTransportSummary'}
        coLoadGroup: {$ref: '#/components/schemas/UnifiedCoLoadGroupSummary'}
        customerRemark: {type: string, nullable: true}
        latestInternalNote: {type: string, nullable: true, description: 客户详情不返回平台内部备注}
        createdAt: {type: string, format: date-time, nullable: true}
        updatedAt: {type: string, format: date-time, nullable: true}
    UnifiedOrderRelation:
      type: object
      nullable: true
      properties:
        role: {type: string, enum: [PARENT, CHILD]}
        rootOrderId: {type: integer, format: int64, nullable: true}
        parentOrderId: {type: integer, format: int64, nullable: true}
        splitSequence: {type: integer, nullable: true}
        childCount: {type: integer, nullable: true}
    UnifiedCoLoadGroupSummary:
      type: object
      nullable: true
      description: 仅平台统一订单列表与详情返回；未加入同柜组时为 null
      properties:
        status: {type: string}
        memberCount: {type: integer, minimum: 0}
        memberInboundCodes:
          type: array
          items: {type: string, nullable: true, description: 同柜组成员订单片段的权威入仓码；缺失时保留 null，不回退内部ID}
    UnifiedMeasurementSummary:
      type: object
      nullable: true
      properties:
        reviewStatus: {type: string, nullable: true}
        actualGrossWeightKg: {type: number, nullable: true, description: Firstleg 实测毛重；不得使用净重回退}
        actualVolumeCbm: {type: number, nullable: true}
        chargeableWeightKg: {type: number, nullable: true}
        completedAt: {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}
    UnifiedTransportSummary:
      type: object
      nullable: true
      properties:
        containerNo: {type: string, nullable: true}
        cabinetNo: {type: string, nullable: true}
        vesselName: {type: string, nullable: true}
        voyageNo: {type: string, nullable: true}
        estimatedSailingAt: {type: string, format: date-time, nullable: true, description: 当前关联柜次预计开船时间}
        actualSailingAt: {type: string, format: date-time, nullable: true, description: 当前关联柜次实际开船时间}
        effectiveSailingAt: {type: string, format: date-time, nullable: true, description: 实际开船时间优先，否则预计开船时间}
        effectiveSailingAtEstimated: {type: boolean, nullable: true}
        estimatedPortArrivalAt: {type: string, format: date-time, nullable: true, description: 当前关联柜次预计到港时间}
        actualPortArrivalAt: {type: string, format: date-time, nullable: true, description: 当前关联柜次实际到港时间}
        effectivePortArrivalAt: {type: string, format: date-time, nullable: true, description: 实际到港时间优先，否则预计到港时间}
        effectivePortArrivalAtEstimated: {type: boolean, nullable: true}
    UnifiedOrderTimelineEvent:
      type: object
      properties:
        source: {type: string}
        eventType: {type: string}
        mainStatus: {$ref: '#/components/schemas/UnifiedMainStatus'}
        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}
    FulfillmentSplitQuantityLine:
      type: object
      required: [sourceDetailId, packageCount]
      properties:
        sourceDetailId: {type: integer, format: int64, minimum: 1}
        packageCount: {type: integer, minimum: 1}
    FulfillmentSplitCreateRequest:
      type: object
      required: [tenantId, parentOrderId, sourceOrderId, loadingPlanId, containerBookingId,
                 sourcePackageCount, loadedPackageCount, remainingPackageCount, idempotencyKey, lines]
      properties:
        tenantId: {type: integer, format: int64, minimum: 1}
        parentOrderId: {type: integer, format: int64, minimum: 1}
        sourceOrderId: {type: integer, format: int64, minimum: 1}
        loadingPlanId: {type: integer, format: int64, minimum: 1}
        containerBookingId: {type: integer, format: int64, minimum: 1}
        sourcePackageCount: {type: integer, minimum: 1}
        loadedPackageCount: {type: integer, minimum: 1}
        remainingPackageCount: {type: integer, minimum: 0}
        expectedParentVersion: {type: integer, minimum: 0, description: 可选；省略时仍在父订单行锁下串行拆分}
        idempotencyKey: {type: string, minLength: 1, maxLength: 128}
        operationId: {type: string, maxLength: 64}
        operatorName: {type: string, maxLength: 64}
        lines:
          type: array
          minItems: 1
          items: {$ref: '#/components/schemas/FulfillmentSplitQuantityLine'}
    FulfillmentSplitChild:
      type: object
      properties:
        orderId: {type: integer, format: int64}
        orderNo: {type: string}
        splitSequence: {type: integer, minimum: 1}
        splitRole: {type: string, enum: [LOADED, REMAINDER]}
        packageCount: {type: integer, minimum: 1}
        sourceOrderId: {type: integer, format: int64}
        loadingPlanId: {type: integer, format: int64}
        containerBookingId: {type: integer, format: int64}
    FulfillmentSplitResponse:
      type: object
      properties:
        parentOrderId: {type: integer, format: int64}
        parentOrderNo: {type: string}
        parentVersion: {type: integer, minimum: 0}
        loadedChild:
          allOf: [{$ref: '#/components/schemas/FulfillmentSplitChild'}]
          description: 新写入时指向承接本次实装的来源订单本身；历史双子单仍返回原已装子订单
        remainderChild:
          allOf: [{$ref: '#/components/schemas/FulfillmentSplitChild'}]
          nullable: true
          description: 未装数量大于0时唯一创建的余量子订单；全部装完时为空
        sourcePackageCount: {type: integer, minimum: 1}
        loadedPackageCount: {type: integer, minimum: 1}
        remainingPackageCount: {type: integer, minimum: 0}
        loadingPlanId: {type: integer, format: int64}
        containerBookingId: {type: integer, format: int64}
        idempotencyKey: {type: string}
    FulfillmentSplitTree:
      type: object
      properties:
        parentOrderId: {type: integer, format: int64}
        parentOrderNo: {type: string}
        parentVersion: {type: integer, minimum: 0}
        children:
          type: array
          items: {$ref: '#/components/schemas/FulfillmentSplitChild'}
        allocatedPackageCount: {type: integer, minimum: 0, deprecated: true}
        remainingPackageCount: {type: integer, minimum: 0, deprecated: true}
        originalPackageCount: {type: integer, minimum: 0, description: 根订单最初箱数}
        cumulativeLoadedPackageCount: {type: integer, minimum: 0, description: 所有已完成来源分片累计实装箱数}
        currentRemainderPackageCount: {type: integer, minimum: 0, description: 当前唯一有效余量箱数}
    PricingTaxMode:
      type: string
      enum: [TAX_INCLUDED, TAX_EXCLUDED]
      description: 报价包税维度；独立于订单 taxMode 的买单/退税语义
    FirstLegOrderDraft:
      type: object
      required: [customerName, transportMode, cargoes, pickupMethod, receivingWarehouseId, receivingWarehouseName, channelCode, channelName, taxMode, pricingTaxMode, destinationType]
      properties:
        fulfillmentType:
          type: string
          enum: [STANDARD, ONE_CLICK_DROPSHIP]
          default: STANDARD
          description: 独立履约类型；省略为普通头程，不复用业务/计费 businessType
        inboundCode:
          type: string
          maxLength: 40
          pattern: '^[A-Za-z0-9._:-]+$'
          description: 仅 LEGACY_MANUAL 模式填写的旧系统入仓码；AUTO 模式必须省略
        pricingTaxMode: {$ref: '#/components/schemas/PricingTaxMode'}
        senderAddressId: {type: string, pattern: '^[1-9][0-9]*$', description: PICKUP 时必填；必须是本客户 PICKUP 地址}
        privateDestinationAddressId: {type: string, pattern: '^[1-9][0-9]*$', description: PRIVATE 时必填；必须是本客户 PRIVATE_DESTINATION 地址}
        customsInspection: {type: boolean, nullable: true, description: 非木制品可空；任一货物 woodenProduct=true 时必须为 true}
        cargoes:
          type: array
          minItems: 1
          items: {$ref: '#/components/schemas/FirstLegOrderCargo'}
      description: >-
        订单保存请求中的完整字段以服务端 FirstLegOrderSaveRequest 为准；fulfillmentType
        省略时固定为 STANDARD，一键代发必须显式传 ONE_CLICK_DROPSHIP，且不复用计费 businessType；pricingTaxMode
        是新建和编辑订单的必填报价维度；customerId 不接受客户端指定，服务端始终使用认证企业 ID；
        发货与私人目的仓只接受客户地址 ID，服务端在订单参与方表冻结快照；地址簿后续修改不回写历史订单。
        私人目的仓不得写入或伪装为 Warehouse 平台仓主档。历史存量订单的响应字段仍允许为空。
    CustomerOrderAddressSaveRequest:
      type: object
      required: [addressType, addressName, companyName, contactName, phone, countryCode, city, addressLine, defaultAddress]
      properties:
        addressType: {type: string, enum: [PICKUP, PRIVATE_DESTINATION]}
        addressName: {type: string, maxLength: 64}
        companyName: {type: string, maxLength: 128}
        contactName: {type: string, maxLength: 64}
        phone: {type: string, maxLength: 32}
        email: {type: string, format: email, maxLength: 128, nullable: true}
        countryCode: {type: string, minLength: 2, maxLength: 2}
        province: {type: string, maxLength: 64, nullable: true}
        city: {type: string, maxLength: 64}
        district: {type: string, maxLength: 64, nullable: true}
        addressLine: {type: string, maxLength: 255}
        postalCode: {type: string, maxLength: 20, nullable: true}
        defaultAddress: {type: boolean}
    InboundCodePolicy:
      type: object
      required: [mode, manualEntryRequired]
      properties:
        mode: {type: string, enum: [AUTO, LEGACY_MANUAL]}
        manualEntryRequired: {type: boolean}
    InboundCodeAssociationEnvelope:
      type: object
      properties:
        code: {type: string, example: '200'}
        message: {type: string}
        data: {$ref: '#/components/schemas/InboundCodeAssociationSummary'}
    InboundCodeAssociationSummary:
      type: object
      required: [inboundCode, orderNo, orderStatus, orderId, customerId, customerName, destinationType]
      properties:
        inboundCode: {type: string, maxLength: 40, pattern: '^[A-Za-z0-9._:-]+$', description: 主要展示键：全局唯一入仓码}
        orderNo: {type: string, description: 主要展示键：订单业务号}
        orderStatus: {type: string, description: Order 权威交易状态}
        orderId: {type: string, pattern: '^[1-9][0-9]*$', description: 内部 ID，仅供路由关联}
        customerId: {type: string, pattern: '^[1-9][0-9]*$', description: 客户 ID，字符串避免精度损失}
        customerName: {type: string}
        destinationType: {type: string}
        destinationCountryCode: {type: string, nullable: true}
        destinationWarehouseId: {type: string, pattern: '^[1-9][0-9]*$', nullable: true, description: 内部 ID，仅供路由关联}
        destinationWarehouseCode: {type: string, nullable: true, description: 目的仓业务编码；FBA 场景为 Amazon 仓码}
        destinationWarehouseName: {type: string, nullable: true}
    FirstLegBatchDraftItem:
      type: object
      required: [clientRowId, draft]
      properties:
        clientRowId:
          type: string
          maxLength: 128
          description: 前端外层行标识；同一批次内必须唯一，用于幂等重试和结果关联
        draft:
          $ref: '#/components/schemas/FirstLegOrderDraft'
    FirstLegBatchDraftResponse:
      type: object
      required: [total, succeeded, failed, items]
      properties:
        total: {type: integer, minimum: 0}
        succeeded: {type: integer, minimum: 0}
        failed: {type: integer, minimum: 0}
        items:
          type: array
          items: {$ref: '#/components/schemas/FirstLegBatchDraftResult'}
    FirstLegBatchDraftResult:
      type: object
      required: [index, success]
      properties:
        index: {type: integer, minimum: 0}
        clientRowId: {type: string}
        success: {type: boolean}
        orderId: {type: string, pattern: '^[1-9][0-9]*$'}
        orderNo: {type: string}
        inboundCode: {type: string, pattern: '^[A-Za-z0-9._:-]+$', example: ZBYHK2608140001, description: AUTO 模式为渠道前缀+业务日期+全局票序；LEGACY_MANUAL 模式为录入的旧系统入仓码；履约拆分的子订单追加 splitSequence 后缀}
        errorCode: {type: string}
        errorMessage: {type: string}
    FirstLegOrderCargo:
      type: object
      required: [packageCount, woodenProduct]
      properties:
        skuNo: {type: string, maxLength: 64}
        cargoName: {type: string, maxLength: 128}
        cargoNameEn: {type: string, maxLength: 128}
        productImageFileId: {type: string, pattern: '^[1-9][0-9]*$'}
        hsCode: {type: string, maxLength: 20, description: 报关 HS CODE}
        customsHsCode: {type: string, maxLength: 20, description: 清关 HS CODE}
        lengthCm: {type: number, minimum: 0, description: 箱规长（厘米）}
        widthCm: {type: number, minimum: 0, description: 箱规宽（厘米）}
        heightCm: {type: number, minimum: 0, description: 箱规高（厘米）}
        unitsPerPackage: {type: integer, minimum: 1, description: 每箱数量}
        packageCount: {type: integer, minimum: 1, description: 箱数}
        grossWeightKg: {type: number, exclusiveMinimum: true, minimum: 0, description: 总毛重}
        volumeCbm: {type: number, exclusiveMinimum: true, minimum: 0, description: 总体积}
        totalQuantity: {type: integer, minimum: 1, description: 总数量}
        netWeightKg: {type: number, exclusiveMinimum: true, minimum: 0, description: 总净重}
        unitDeclaredValue: {type: number, minimum: 0, description: 清关申报单价（USD）}
        declaredValue: {type: number, minimum: 0, description: 清关申报金额（USD）}
        material: {type: string, maxLength: 128}
        usage: {type: string, maxLength: 128}
        model: {type: string, maxLength: 64}
        brand: {type: string, maxLength: 64}
        productLengthCm: {type: number, minimum: 0}
        productWidthCm: {type: number, minimum: 0}
        productHeightCm: {type: number, minimum: 0}
        shipmentId: {type: string, maxLength: 64}
        referenceId: {type: string, maxLength: 64}
        upcNo: {type: string, maxLength: 64}
        cargoRemark: {type: string, maxLength: 500}
        packageType: {type: string, maxLength: 32}
        dangerousGoods: {type: boolean}
        woodenProduct: {type: boolean, description: 木制品权威判定快照；为 true 时订单 customsInspection 必须为 true}
      description: >-
        原型货物明细字段。FBA 货物的 skuNo、upcNo、shipmentId、referenceId 由服务端按每条货物校验；
        productImageFileId 必须属于当前登录客户。
    FirstLegOrderSummary:
      type: object
      properties:
        orderId: {type: string, pattern: '^[1-9][0-9]*$'}
        orderNo: {type: string}
        inboundId: {type: string, pattern: '^[1-9][0-9]*$', nullable: true}
        inboundCode: {type: string}
        channelName: {type: string}
        pickupMethod: {type: string, enum: [SELF_EXPRESS, PICKUP, SELF_TRUCK], nullable: true}
        destinationWarehouseName: {type: string}
        status: {type: string}
        packageCount: {type: integer}
        expressCompany: {type: string}
        trackingNo: {type: string}
        skuNos: {type: string, description: 多个 SKU 使用中文顿号分隔}
        totalGrossWeightKg: {type: number}
        totalNetWeightKg: {type: number}
        totalVolumeCbm: {type: number}
        totalQuantity: {type: integer}
        remark: {type: string}
        shipmentId: {type: string}
        referenceId: {type: string}
        pricingTaxMode: {$ref: '#/components/schemas/PricingTaxMode'}
    ContainerSlice:
      type: object
      properties:
        containerBookingId: {type: string}
        tenantId: {type: string}
        parentOrderId: {type: string}
        parentOrderNo: {type: string}
        childOrderId: {type: string}
        childOrderNo: {type: string}
        sourceOrderId: {type: string}
        sourceOrderNo: {type: string}
        splitRole: {type: string, enum: [LOADED, REMAINDER]}
        packageCount: {type: integer}
        loadingPlanId: {type: string}
  parameters:
    InboundCodePath:
      name: inboundCode
      in: path
      required: true
      schema: {type: string, minLength: 1, maxLength: 40, pattern: '^[A-Za-z0-9._:-]+$'}
      description: 全局唯一业务入仓码
    InternalToken:
      name: X-Internal-Service-Token
      in: header
      required: true
      schema: {type: string, minLength: 1}
    UnifiedKeyword:
      name: keyword
      in: query
      required: false
      schema: {type: string, maxLength: 64}
    UnifiedOrderNo:
      name: orderNo
      in: query
      required: false
      schema: {type: string, maxLength: 64}
    UnifiedMainStatus:
      name: mainStatus
      in: query
      required: false
      description: 统一订单七态主状态筛选；WAIT_SPLIT 与存量兼容状态 INBOUNDED 独立查询
      schema:
        type: string
        enum: [PENDING_REVIEW, WAIT_MEASURE, INBOUNDED, LOADING, LOADED, DELIVERED, WAIT_SPLIT]
    UnifiedInboundCode:
      {name: inboundCode, in: query, required: false, description: 订单创建时生成的入仓码，所有订单状态均可查询, schema: {type: string, maxLength: 40}}
    UnifiedInternalOrderStatus:
      name: internalOrderStatus
      in: query
      required: false
      description: Order 内部生命周期状态；不是七态产品主状态
      schema: {type: string, enum: [DRAFT, SUBMITTED, APPROVED, ACCEPTED, REJECTED, CANCELLED, PROCESSING, COMPLETED]}
    UnifiedExpectedArrivalDate:
      {name: expectedArrivalDate, in: query, required: false, schema: {type: string, format: date}}
    UnifiedFeeReviewStatus:
      name: feeReviewStatus
      in: query
      required: false
      description: 当前最高版本入库费用审核状态；UNRECORDED 表示尚无费用记录
      schema: {type: string, enum: [UNRECORDED, PENDING, APPROVED, REJECTED]}
    UnifiedChannelName:
      {name: channelName, in: query, required: false, schema: {type: string, maxLength: 128}}
    UnifiedContainerNo:
      {name: containerNo, in: query, required: false, schema: {type: string, maxLength: 64}}
    UnifiedCabinetNo:
      {name: cabinetNo, in: query, required: false, schema: {type: string, maxLength: 64}}
    UnifiedSailingDate:
      {name: sailingDate, in: query, required: false, schema: {type: string, format: date}}
    UnifiedLoaded:
      name: loaded
      in: query
      required: false
      description: true 表示运输装载状态存在且不是 UNLOADED/PENDING；false 表示无该状态
      schema: {type: boolean}
    UnifiedFullContainer:
      name: fullContainer
      in: query
      required: false
      description: true 对应 FULL_CONTAINER，false 对应 LCL
      schema: {type: boolean}
    UnifiedMeasurementReviewStatus:
      name: measurementReviewStatus
      in: query
      required: false
      description: 测量审核状态；UNRECORDED 表示字段为空
      schema: {type: string, enum: [UNRECORDED, PENDING, APPROVED, REJECTED]}
    UnifiedFbaCode:
      name: fbaCode
      in: query
      required: false
      description: 兼容匹配订单货物 sku_no
      schema: {type: string, maxLength: 64}
    UnifiedCreatedFrom:
      name: createdFrom
      in: query
      required: false
      description: 无主状态或待审核筛选按订单创建时间；其他主状态按履约快照创建时间
      schema: {type: string, format: date-time}
    UnifiedCreatedTo:
      name: createdTo
      in: query
      required: false
      description: 无主状态或待审核筛选按订单创建时间；其他主状态按履约快照创建时间
      schema: {type: string, format: date-time}
    UnifiedPage:
      name: page
      in: query
      required: false
      schema: {type: integer, minimum: 1, default: 1}
    UnifiedSize:
      name: size
      in: query
      required: false
      schema: {type: integer, minimum: 1, maximum: 200, default: 20}
    UnifiedOrderId:
      name: orderId
      in: path
      required: true
      schema: {type: string, pattern: '^[1-9][0-9]*$'}
    UnifiedTenantId:
      name: tenantId
      in: query
      required: true
      schema: {type: string, pattern: '^[1-9][0-9]*$'}
    TenantId:
      name: tenantId
      in: query
      required: true
      schema: {type: integer, format: int64}
    OrderId:
      name: id
      in: path
      required: true
      schema: {type: integer, format: int64}
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: 同一客户和操作者重试同一请求时必须保持不变
      schema: {type: string, minLength: 1, maxLength: 128}