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、
        未分配且未属于其他活动组的可用入库片段，要求国内仓和渠道一致，并冻结全部片段及其满箱数。
      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/by-inbound-code/{inboundCode}:
    get:
      summary: 按入仓码查询同柜组业务摘要
      description: >-
        需要 platform:firstleg:smart-loading:list。使用任一有效成员的全局唯一 inboundCode 查询；
        仅返回组业务状态、有效成员数和去重后的全部成员入仓码。页面不持有或展示 groupId、groupNo、orderId。
      parameters:
        - name: inboundCode
          in: path
          required: true
          schema: {type: string, minLength: 1, maxLength: 40}
      responses:
        '200':
          description: 业务响应
          content:
            application/json:
              schema:
                allOf:
                  - {$ref: '#/components/schemas/ApiEnvelope'}
                  - type: object
                    properties:
                      data: {$ref: '#/components/schemas/ColoadGroupBusinessSummary'}
        '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}
    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, 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}
        lockedPlanId: {type: string, nullable: true}
        version: {type: integer, minimum: 0}
        members:
          type: array
          minItems: 2
          items: {$ref: '#/components/schemas/ColoadGroupMember'}
        fullPackageCount: {type: integer, minimum: 2, description: 全部成员满箱数之和}
        createdAt: {type: string, format: date-time}
        updatedAt: {type: string, format: date-time}
    ColoadGroupBusinessMember:
      type: object
      additionalProperties: false
      required: [inboundCode]
      properties:
        inboundCode: {type: string, minLength: 1, maxLength: 40}
    ColoadGroupBusinessSummary:
      type: object
      additionalProperties: false
      required: [status, memberCount, members]
      properties:
        status: {type: string, enum: [ACTIVE, LOCKED, CONSUMED]}
        memberCount: {type: integer, minimum: 1}
        members:
          type: array
          minItems: 1
          uniqueItems: true
          items: {$ref: '#/components/schemas/ColoadGroupBusinessMember'}