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

openapi: 3.0.3
info:
  title: Firstleg Coload Group API
  version: 1.0.0
  description: 同柜且不可拆组平台管理契约；跨客户成组，但仓库、渠道和目的仓港必须一致。
paths:
  /api/platform/v1/first-leg/coload-groups:
    post:
      summary: 创建同柜不可拆组
      description: >-
        需要 platform:firstleg:smart-loading:assign。orderIds 至少2项；服务端解析每个订单唯一当前权威入库单，
        要求 WAIT_SPLIT、原始MASTER、未拆分、未分配、无子单或拆分批次，并冻结全部成员满箱数。
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/CreateColoadGroupRequest'}
      responses:
        '200': {$ref: '#/components/responses/ColoadGroupResponse'}
        '403': {description: 缺少智能排柜分配权限}
  /api/platform/v1/first-leg/coload-groups/{groupId}/cancel:
    post:
      summary: 整组取消同柜不可拆组
      description: 仅 ACTIVE 组允许取消；不提供单成员编辑，修改成员必须取消后重建。
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - {name: groupId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/CancelColoadGroupRequest'}
      responses:
        '200': {$ref: '#/components/responses/ColoadGroupResponse'}
        '403': {description: 缺少智能排柜分配权限}
  /api/platform/v1/first-leg/coload-groups/batch-query:
    post:
      summary: 按订单ID批量查询同柜不可拆组
      description: >-
        需要 platform:firstleg:smart-loading:assign。最多200个订单；返回当前非取消组的组号、状态、
        全部成员和整组满箱数，供平台订单列表批量补齐，不按单成员修改。
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/BatchQueryColoadGroupRequest'}
      responses:
        '200':
          description: 业务响应
          content:
            application/json:
              schema:
                allOf:
                  - {$ref: '#/components/schemas/ApiEnvelope'}
                  - type: object
                    properties:
                      data:
                        type: array
                        maxItems: 200
                        items: {$ref: '#/components/schemas/OrderColoadGroupInfo'}
        '403': {description: 缺少智能排柜分配权限}
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema: {type: string, minLength: 1, maxLength: 128}
  responses:
    ColoadGroupResponse:
      description: 成功或业务失败，按响应体 code 判断
      content:
        application/json:
          schema:
            allOf:
              - {$ref: '#/components/schemas/ApiEnvelope'}
              - type: object
                properties:
                  data: {$ref: '#/components/schemas/ColoadGroup'}
  schemas:
    ApiEnvelope:
      type: object
      required: [code, message, timestamp]
      properties:
        code: {type: string, example: '200'}
        message: {type: string}
        requestId: {type: string, nullable: true}
        traceId: {type: string, nullable: true}
        timestamp: {type: string, format: date-time}
    CreateColoadGroupRequest:
      type: object
      additionalProperties: false
      required: [orderIds]
      properties:
        orderIds:
          type: array
          minItems: 2
          maxItems: 100
          uniqueItems: true
          items: {type: string, pattern: '^[1-9][0-9]*$'}
    CancelColoadGroupRequest:
      type: object
      additionalProperties: false
      required: [expectedVersion]
      properties:
        expectedVersion: {type: integer, minimum: 0}
        reason: {type: string, maxLength: 500, nullable: true}
    BatchQueryColoadGroupRequest:
      type: object
      additionalProperties: false
      required: [orderIds]
      properties:
        orderIds:
          type: array
          minItems: 1
          maxItems: 200
          uniqueItems: true
          items: {type: string, pattern: '^[1-9][0-9]*$'}
    ColoadGroupMember:
      type: object
      additionalProperties: false
      required: [tenantId, orderId, inboundId, fullPackageCount]
      properties:
        tenantId: {type: string, pattern: '^[1-9][0-9]*$'}
        orderId: {type: string, pattern: '^[1-9][0-9]*$'}
        inboundId: {type: string, pattern: '^[1-9][0-9]*$'}
        fullPackageCount: {type: integer, minimum: 1}
    ColoadGroup:
      type: object
      additionalProperties: false
      required: [groupId, groupNo, status, warehouseId, channelCode, destinationType,
                 version, members, fullPackageCount, createdAt, updatedAt]
      properties:
        groupId: {type: string, pattern: '^[1-9][0-9]*$'}
        groupNo: {type: string, pattern: '^CLG-[1-9][0-9]*$'}
        status: {type: string, enum: [ACTIVE, LOCKED, CONSUMED, CANCELLED]}
        warehouseId: {type: string, pattern: '^[1-9][0-9]*$'}
        channelCode: {type: string}
        destinationType: {type: string}
        destinationWarehouseId: {type: string, nullable: true}
        destinationCode: {type: string, nullable: true}
        lockedPlanId: {type: string, nullable: true}
        version: {type: integer, minimum: 0}
        members:
          type: array
          minItems: 2
          maxItems: 100
          items: {$ref: '#/components/schemas/ColoadGroupMember'}
        fullPackageCount: {type: integer, minimum: 2, description: 全部成员满箱数之和}
        createdAt: {type: string, format: date-time}
        updatedAt: {type: string, format: date-time}
    OrderColoadGroupInfo:
      type: object
      additionalProperties: false
      required: [orderId, inboundId, group]
      properties:
        orderId: {type: string, pattern: '^[1-9][0-9]*$'}
        inboundId: {type: string, pattern: '^[1-9][0-9]*$'}
        group: {$ref: '#/components/schemas/ColoadGroup'}