优化

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

@@ -483,16 +483,72 @@ paths:
         '403': {description: 无智能装柜查询权限}
   /api/platform/v1/first-leg/smart-loading/inbound-candidates:
     get:
-      summary: 按入仓码查询智能装柜候选
+      summary: 全局分页查询智能装柜候选
       description: >-
-        需要 platform:firstleg:smart-loading:list 权限。每个入库单/入仓码只返回一行；
+        需要 platform:firstleg:smart-loading:list 权限。查询不绑定柜次；渠道、仓库、客户、入仓码、
+        预计到货日期和订单状态共同作用于全局候选。每个普通入库单返回一行；同柜不可拆组作为一个
+        分页单元返回，groupMembers 包含完整成员，不会跨页或因单个成员命中搜索条件而拆散。
         平均单箱毛重、净重按整票实测重量除以总箱数，平均单箱体积按剩余规格数量加权。
-        响应携带订单状态快照 orderStatusSnapshot 与预计到货时间 expectedArrivalAt，供平台筛选候选入仓码；
-        这些数据用于数量级计划，不表示具体箱号已核验归属。
+        只返回当前具备实际装柜候选资格的 WAIT_SPLIT 数据；PENDING_REVIEW、WAIT_MEASURE、LOADING
+        是统一筛选枚举，但在候选接口中返回空页。LOADED、COMPLETED 与已锁定或成员不完整的组永不返回。
+        分配时仍由目标 planId 接口复核真实渠道、仓库、容量、组锁和并发版本。
       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: 成功，data 为入仓码级候选列表}}
+        - name: channelGroupCodes
+          in: query
+          required: true
+          description: >-
+            至少一项，可重复传参。分组到实际渠道：MATSON_CLX=[MATSON_CLX_TRUCK,MATSON_CLX_PARCEL]；
+            MATSON_MAX=[MATSON_MAX_TRUCK,MATSON_MAX_PARCEL]；EXX=[EXX_TRUCK,EXX_RAIL_NY]；
+            HEDE=[HEDE_TRUCK,HEDE_PARCEL]；OA_LA=[OA_LA_TRUCK,OA_LA_FULL_TRUCK,OA_PARCEL]；
+            OA_CHICAGO=[OA_CHICAGO_RAIL]；OA_HOUSTON=[OA_HOUSTON_TRUCK]；
+            OA_SAVANNAH=[OA_SAVANNAH_TRUCK]；OA_NEW_YORK_TRUCK=[OA_NEW_YORK_TRUCK]。
+          schema:
+            type: array
+            minItems: 1
+            maxItems: 9
+            uniqueItems: true
+            items: {type: string, enum: [MATSON_CLX, MATSON_MAX, EXX, HEDE, OA_LA, OA_CHICAGO, OA_HOUSTON, OA_SAVANNAH, OA_NEW_YORK_TRUCK]}
+        - {name: warehouseId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+        - {name: customerId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+        - {name: inboundCode, in: query, required: false, schema: {type: string, maxLength: 40}}
+        - {name: expectedArrivalStart, in: query, required: false, schema: {type: string, format: date}}
+        - {name: expectedArrivalEnd, in: query, required: false, schema: {type: string, format: date}}
+        - {name: orderStatus, in: query, required: false, schema: {type: string, enum: [PENDING_REVIEW, WAIT_MEASURE, WAIT_SPLIT, LOADING]}}
+        - {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: 成功，data 为标准分页；total/pages 按普通入库单或完整同柜组分页单元统计
+          content: {application/json: {schema: {$ref: '#/components/schemas/SmartLoadingInboundCandidatePageEnvelope'}}}
+  /api/platform/v1/first-leg/smart-loading/containers:
+    get:
+      summary: 分页查询智能装柜工作台柜次
+      description: >-
+        需要 platform:firstleg:smart-loading:list 权限。与全局候选使用相同的渠道、仓库、客户、入仓码、
+        预计到货日期及订单状态筛选；客户及入仓事实以柜内任一有效装柜明细命中为准，查询不会修改或拆散同柜组。
+        只返回 WAIT_LOADING、EDITING 或 LOADING 的 ACTIVE 柜次，COMPLETED 永不返回。
+      parameters:
+        - name: channelGroupCodes
+          in: query
+          required: true
+          schema:
+            type: array
+            minItems: 1
+            maxItems: 9
+            uniqueItems: true
+            items: {type: string, enum: [MATSON_CLX, MATSON_MAX, EXX, HEDE, OA_LA, OA_CHICAGO, OA_HOUSTON, OA_SAVANNAH, OA_NEW_YORK_TRUCK]}
+        - {name: warehouseId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+        - {name: customerId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+        - {name: inboundCode, in: query, required: false, schema: {type: string, maxLength: 40}}
+        - {name: expectedArrivalStart, in: query, required: false, schema: {type: string, format: date}}
+        - {name: expectedArrivalEnd, in: query, required: false, schema: {type: string, format: date}}
+        - {name: orderStatus, in: query, required: false, schema: {type: string, enum: [PENDING_REVIEW, WAIT_MEASURE, WAIT_SPLIT, LOADING]}}
+        - {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: 成功，柜次按更新时间、技术ID倒序稳定分页
+          content: {application/json: {schema: {$ref: '#/components/schemas/SmartLoadingWorkbenchContainerPageEnvelope'}}}
   /api/platform/v1/first-leg/loading-associations/summary:
     get:
       summary: 查询入仓片段的装柜与国内PDA关联摘要
@@ -1203,10 +1259,10 @@ components:
           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}
+            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]+$'}
     UnifiedInboundListEnvelope:
       type: object
       properties:
@@ -1880,6 +1936,103 @@ components:
         candidateInboundCount: {type: integer, format: int64, minimum: 0, description: 当前可分配的唯一入仓码数量}
         availablePackageCount: {type: integer, format: int64, minimum: 0, description: 当前候选规格剩余可分配箱数合计}
         availableContainerCount: {type: integer, format: int64, minimum: 0, description: 当前 WAIT_LOADING、EDITING 或 LOADING 可编排柜次数量}
+    SmartLoadingInboundCandidatePageEnvelope:
+      type: object
+      required: [code, message, data]
+      properties:
+        code: {type: string, example: '200'}
+        message: {type: string}
+        data:
+          type: object
+          required: [records, page, size, total, pages]
+          properties:
+            records: {type: array, items: {$ref: '#/components/schemas/SmartLoadingInboundCandidate'}}
+            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}
+    SmartLoadingInboundCandidate:
+      type: object
+      required: [accountId, customerId, inboundId, orderId, orderNo, inboundCode, warehouseId, channelCode,
+        channelName, customerName, goodsSummary, availablePackageCount, unitGrossWeightKg,
+        unitNetWeightKg, averageUnitVolumeCbm, availableVolumeCbm, locked, groupMembers]
+      properties:
+        accountId: {type: string, pattern: '^[1-9][0-9]*$'}
+        customerId: {type: string, pattern: '^[1-9][0-9]*$', description: 与 accountId 相同的客户技术关联ID}
+        inboundId: {type: string, pattern: '^[1-9][0-9]*$', description: 普通候选ID；组聚合行中为可用于整组分配的稳定代表成员ID}
+        orderId: {type: string, pattern: '^[1-9][0-9]*$'}
+        orderNo: {type: string}
+        inboundCode: {type: string}
+        orderStatusSnapshot: {type: string, nullable: true}
+        expectedArrivalAt: {type: string, format: date-time, nullable: true}
+        warehouseId: {type: string, pattern: '^[1-9][0-9]*$'}
+        channelCode: {type: string}
+        channelName: {type: string}
+        destinationWarehouseId: {type: string, pattern: '^[1-9][0-9]*$', nullable: true}
+        destinationWarehouseCode: {type: string, nullable: true}
+        destinationWarehouseName: {type: string, nullable: true}
+        customerName: {type: string}
+        goodsSummary: {type: string}
+        availablePackageCount: {type: integer, minimum: 1, description: 普通行剩余箱数；组行完整成员箱数合计}
+        unitGrossWeightKg: {type: number, minimum: 0}
+        unitNetWeightKg: {type: number, minimum: 0}
+        averageUnitVolumeCbm: {type: number, minimum: 0}
+        availableVolumeCbm: {type: number, minimum: 0}
+        coLoadGroupId: {type: string, pattern: '^[1-9][0-9]*$', nullable: true}
+        groupNo: {type: string, nullable: true}
+        memberCount: {type: integer, minimum: 2, nullable: true}
+        groupTotalBoxes: {type: integer, minimum: 1, nullable: true}
+        locked: {type: boolean}
+        blockReason: {type: string, nullable: true}
+        groupMembers:
+          type: array
+          description: 同柜组聚合行的完整成员；普通候选为空数组
+          items:
+            type: object
+            required: [accountId, inboundId, orderId, orderNo, inboundCode, customerName, availablePackageCount]
+            properties:
+              accountId: {type: string, pattern: '^[1-9][0-9]*$'}
+              inboundId: {type: string, pattern: '^[1-9][0-9]*$'}
+              orderId: {type: string, pattern: '^[1-9][0-9]*$'}
+              orderNo: {type: string}
+              inboundCode: {type: string}
+              customerName: {type: string}
+              availablePackageCount: {type: integer, minimum: 1}
+              orderStatusSnapshot: {type: string, nullable: true}
+              expectedArrivalAt: {type: string, format: date-time, nullable: true}
+    SmartLoadingWorkbenchContainerPageEnvelope:
+      type: object
+      required: [code, message, data]
+      properties:
+        code: {type: string, example: '200'}
+        message: {type: string}
+        data:
+          type: object
+          required: [records, page, size, total, pages]
+          properties:
+            records: {type: array, items: {$ref: '#/components/schemas/SmartLoadingWorkbenchContainer'}}
+            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]+$'}
+    SmartLoadingWorkbenchContainer:
+      type: object
+      required: [bookingId, bookingNo, cabinetNo, warehouseId, warehouseName, channelCode,
+        channelName, containerType, planStatus, version]
+      properties:
+        bookingId: {type: string, pattern: '^[1-9][0-9]*$', description: containerBookingId 技术关联}
+        bookingNo: {type: string, description: 货柜登记业务号}
+        cabinetNo: {type: string, description: 稳定柜次业务号}
+        containerNo: {type: string, nullable: true, description: 真实集装箱号，允许在装柜前后补}
+        warehouseId: {type: string, pattern: '^[1-9][0-9]*$'}
+        warehouseName: {type: string}
+        channelCode: {type: string}
+        channelName: {type: string}
+        containerType: {type: string}
+        planId: {type: string, pattern: '^[1-9][0-9]*$', nullable: true}
+        planNo: {type: string, nullable: true}
+        planStatus: {type: string, enum: [WAIT_LOADING, EDITING, LOADING]}
+        version: {type: integer, minimum: 0, description: 柜次版本}
     SmartLoadingPlan:
       type: object
       required: [id, planNo, status, bookingId, version, canAssign, canEdit, finalCompletionStatus, items]