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项；服务端解析每个订单处于待审核、
        待测量/测量中、待分柜或装柜中的全部有效入仓片段；待审核订单先经 Order 批量权威核验并幂等准备
        PREPARING 入库投影。全部成员要求国内仓和渠道一致，并冻结全部片段及其满箱数。
        全部成员未进入装柜计划时创建 ACTIVE 组；全部成员已经按满箱数完整进入同一个装柜计划时直接创建并
        锁定为 LOCKED 组。仅部分成员进柜、分散在不同装柜计划、箱数不完整、已属于其他活动组或权威仓库/
        渠道快照缺失时拒绝。跨成员仓库或渠道不一致时返回入仓码及仓库名/渠道名；平台错误不得展示
        orderId、inboundId 或 groupId。
      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/by-inbound-code/{inboundCode}/cancel:
    post:
      summary: 整组取消同柜不可拆组
      description: 使用任一成员入仓码整组取消；仅 ACTIVE 组允许取消，不提供单成员编辑。
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - {name: inboundCode, in: path, required: true, schema: {type: string, minLength: 1, maxLength: 40}}
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/CancelColoadGroupByInboundCodeRequest'}
      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 查询；
        仅返回组业务状态、有效成员数和全部唯一成员入仓码。任一冻结成员缺少有效 inboundCode 时失败关闭；
        页面不持有或展示 groupId、groupNo、orderId，也不得从技术ID或订单号推导入仓码。
      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]*$'}
    CancelColoadGroupByInboundCodeRequest:
      type: object
      additionalProperties: false
      properties:
        reason: {type: string, maxLength: 500, nullable: true}
    ColoadGroupMember:
      type: object
      additionalProperties: false
      required: [tenantId, orderId, inboundId, inboundCode, 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]*$'}
        inboundCode: {type: string, minLength: 1, maxLength: 40, description: 冻结成员的全局唯一入仓码，禁止由技术ID推导}
        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'}