提交

lastleg-service/src/main/resources/openapi/cargo-discard-photos-v1.yaml

@@ -86,6 +86,7 @@ paths:
       - $ref: '#/components/parameters/PalletNo'
     post:
       summary: Confirm actual disposal with owned pallet photos
+      description: PalletTask.skus返回actualQuantityEditable布尔值。仅普通库存未保存具体箱唛时为true，PDA展示相关托盘并要求填写实际废弃箱数；库存和费用按实际数结算，未废弃预留释放。已完成任务相同数量重放不重复扣减，修改数量拒绝。
       x-permissions: [lastleg:pda:operate, ROLE_OVERSEAS_WAREHOUSE_PDA_OPERATOR]
       requestBody:
         required: true
@@ -103,7 +104,7 @@ paths:
                     required: [itemId, actualPackages]
                     properties:
                       itemId: { type: string, pattern: '^[1-9][0-9]*$' }
-                      actualPackages: { type: integer, minimum: 1, description: Must equal plannedPackages; must finish the application selection }
+                      actualPackages: { type: integer, minimum: 0, description: 无精确箱唛对应关系的普通库存允许0至plannedPackages的实际箱数，剩余预留释放；有具体选箱的明细必须等于plannedPackages }
                 scannedCartonMarks:
                   type: array
                   uniqueItems: true

lastleg-service/src/main/resources/openapi/cargo-discard-statistics-v1.yaml

@@ -0,0 +1,94 @@
+openapi: 3.0.3
+info:
+  title: 货物废弃全部筛选数量统计
+  version: 1.1.0
+paths:
+  /api/platform/v1/last-leg/cargo-discards/statistics:
+    get:
+      summary: 按平台允许的客户范围汇总全部筛选结果
+      description: 与废弃列表共用筛选条件，page和size不限制统计范围。未记录的实际数量、商品件数或托盘事实返回null。实际数取PDA确认事实，不从申请数或状态推算。
+      parameters:
+        - {name: customerId, in: query, schema: {type: string}}
+        - {$ref: '#/components/parameters/DiscardNo'}
+        - {$ref: '#/components/parameters/InboundCode'}
+        - {$ref: '#/components/parameters/Warehouse'}
+        - {$ref: '#/components/parameters/Status'}
+        - {$ref: '#/components/parameters/CreatedFrom'}
+        - {$ref: '#/components/parameters/CreatedTo'}
+        - {$ref: '#/components/parameters/CompletedFrom'}
+        - {$ref: '#/components/parameters/CompletedTo'}
+        - {$ref: '#/components/parameters/Page'}
+        - {$ref: '#/components/parameters/Size'}
+      responses:
+        '200':
+          description: 标准ApiResponse，data为全部筛选数量统计
+          content:
+            application/json:
+              schema: {$ref: '#/components/schemas/Envelope'}
+  /api/merchant/v1/last-leg/cargo-discards/statistics:
+    get:
+      summary: 按当前认证客户汇总全部筛选结果
+      description: 需要merchant:overseas-warehouse:discard:list权限；客户归属只取认证身份。完成时间筛选同时适用于列表。
+      parameters:
+        - {$ref: '#/components/parameters/DiscardNo'}
+        - {$ref: '#/components/parameters/InboundCode'}
+        - {$ref: '#/components/parameters/Warehouse'}
+        - {$ref: '#/components/parameters/Status'}
+        - {$ref: '#/components/parameters/CreatedFrom'}
+        - {$ref: '#/components/parameters/CreatedTo'}
+        - {$ref: '#/components/parameters/CompletedFrom'}
+        - {$ref: '#/components/parameters/CompletedTo'}
+        - {$ref: '#/components/parameters/Page'}
+        - {$ref: '#/components/parameters/Size'}
+      responses:
+        '200':
+          description: 标准ApiResponse，data为当前客户全部筛选统计
+          content:
+            application/json:
+              schema: {$ref: '#/components/schemas/Envelope'}
+components:
+  parameters:
+    DiscardNo: {name: discardNo, in: query, schema: {type: string}}
+    InboundCode: {name: inboundCode, in: query, schema: {type: string}}
+    Warehouse: {name: overseasWarehouseId, in: query, schema: {type: string}}
+    Status: {name: status, in: query, schema: {type: string}}
+    CreatedFrom: {name: createdFrom, in: query, schema: {type: string, format: date-time}}
+    CreatedTo: {name: createdTo, in: query, schema: {type: string, format: date-time}}
+    CompletedFrom: {name: completedFrom, in: query, description: 客户确认完成时间下界，包含边界, schema: {type: string, format: date-time}}
+    CompletedTo: {name: completedTo, in: query, description: 客户确认完成时间上界，包含边界, schema: {type: string, format: date-time}}
+    Page: {name: page, in: query, required: true, schema: {type: integer, minimum: 1}}
+    Size: {name: size, in: query, required: true, schema: {type: integer, minimum: 1, maximum: 200}}
+  schemas:
+    SummaryDimensions:
+      type: object
+      description: 平台及客户废弃列表records与详情summary均返回这些维度；totalPackages保留作业阶段展示箱数，申请箱数须读取requestedPackages。
+      required: [skuCodes, skuCount, requestedPackages, actualPackages]
+      properties:
+        skuCodes: {type: array, items: {type: string}, description: 申请明细去重并排序后的全部SKU}
+        skuCount: {type: integer, description: 本单SKU种数}
+        requestedPackages: {type: integer, description: 申请物理箱数，同一混装箱跨SKU仅计一次}
+        actualPackages: {type: integer, nullable: true, description: PDA已确认实际物理箱数，未作业为null}
+    CandidateSku:
+      type: object
+      description: 库存仓位按物理箱计量，箱内全部SKU从真实实收JSON投影；完整混箱必须携带全部SKU明细，库存冻结和扣减按仓位及箱身份去重。
+      properties:
+        skuCode: {type: string}
+        productName: {type: string, nullable: true}
+        availablePackages: {type: string, description: 包含本SKU的可选物理箱数}
+        availablePieces: {type: string, nullable: true, description: 真实箱内本SKU件数，缺失时null，不按箱规推算}
+    Envelope:
+      type: object
+      properties:
+        code: {type: string}
+        data: {$ref: '#/components/schemas/Statistics'}
+    Statistics:
+      type: object
+      description: Long值遵循全局序列化配置，可能以十进制字符串返回；退货SKU按件汇总并按实物箱去重，转运件数只取所选箱实点SKU事实，其他缺失事实保留null。
+      properties:
+        orderCount: {type: string, description: 筛选订单票数}
+        skuCount: {type: integer, description: 筛选内去重SKU种数}
+        requestedPackages: {type: string, description: 申请物理箱数}
+        actualPackages: {type: string, nullable: true, description: 已确认实际物理箱数}
+        requestedPieces: {type: string, nullable: true, description: 申请商品件数}
+        actualPieces: {type: string, nullable: true, description: 已确认实际商品件数}
+        palletCount: {type: integer, nullable: true, description: 客户和仓范围内去重真实来源托盘数，缺失或散箱返回null}

lastleg-service/src/main/resources/openapi/relabel-quantities-v1.yaml

@@ -4,6 +4,17 @@ info:
   version: 1.0.0
   description: 全部筛选结果汇总，不受 page/size 影响。件、箱、SKU分别统计；未知不能解释为零，禁止固定箱规换算。
 paths:
+  /api/platform/v1/last-leg/relabel-applications/inventory-candidates:
+    get:
+      operationId: platformRelabelInventoryCandidates
+      description: 平台代客创建候选；权限platform:overseas-warehouse:relabel:create。客户和公共作业仓均必须显式选择，返回与客户创建端相同的InventoryCandidate结构。
+      parameters:
+        - {name: customerId, in: query, required: true, schema: {type: string}}
+        - {name: operationWarehouseId, in: query, required: true, schema: {type: string}}
+        - {name: inboundCode, in: query, schema: {type: string}}
+      responses:
+        '200':
+          description: 标准ApiResponse，data为正式库存候选数组；普通库存包含inventoryBalanceId/inboundOrderId/positions，退货包含returnCartonId/cartonMark/cartonSkuItems/cartonAvailablePackages。所有Long ID为十进制字符串。
   /api/platform/v1/last-leg/relabel-applications/quantity-summary:
     get:
       operationId: platformRelabelQuantitySummary
@@ -61,12 +72,16 @@ components:
       type: object
       required: [orderCount, skuCount, knownLabelPieceCount, unknownPieceOrders, knownCartonCount, unknownCartonOrders, orders]
       properties:
-        orderCount: {type: integer, format: int64, minimum: 0}
-        skuCount: {type: integer, format: int64, minimum: 0, description: 全部筛选结果的不同旧SKU数}
-        knownLabelPieceCount: {type: integer, format: int64, minimum: 0}
-        unknownPieceOrders: {type: integer, format: int64, minimum: 0}
-        knownCartonCount: {type: integer, format: int64, minimum: 0}
-        unknownCartonOrders: {type: integer, format: int64, minimum: 0}
+        orderCount: {type: string, pattern: '^[0-9]+$'}
+        skuCount: {type: string, pattern: '^[0-9]+$', description: 全部筛选结果的不同旧SKU数}
+        knownLabelPieceCount: {type: string, pattern: '^[0-9]+$'}
+        unknownPieceOrders: {type: string, pattern: '^[0-9]+$'}
+        knownCartonCount: {type: string, pattern: '^[0-9]+$'}
+        unknownCartonOrders: {type: string, pattern: '^[0-9]+$'}
+        knownSourcePalletCount: {type: string, pattern: '^[0-9]+$', description: 已知完整原托快照按仓库和托盘码在全部筛选单据间去重}
+        unknownSourcePalletOrders: {type: string, pattern: '^[0-9]+$'}
+        knownTargetPalletCount: {type: string, pattern: '^[0-9]+$', description: 本轮完整目标快照按仓库和托盘码去重；返工旧轮目标不计}
+        unknownTargetPalletOrders: {type: string, pattern: '^[0-9]+$'}
         orders:
           type: object
           description: 以换标业务单号为键，覆盖全部筛选单据
@@ -74,10 +89,15 @@ components:
     Quantity:
       type: object
       properties:
-        labelPieceCount: {type: integer, format: int64, nullable: true, description: 按件任务采用通知件数；箱任务采用SKU子项件数；重复关联或缺失为null}
-        cartonCount: {type: integer, format: int64, nullable: true, description: 箱级任务按箱唛去重；按件来源标识不作为箱数}
+        labelPieceCount: {type: string, pattern: '^[0-9]+$', nullable: true, description: 按件任务采用通知件数；箱任务采用SKU子项件数；重复关联或缺失为null}
+        cartonCount: {type: string, pattern: '^[0-9]+$', nullable: true, description: 箱级任务按箱唛去重；按件任务仅在全部精确来源快照都是BOX时按来源主键去重，PALLET/PARCEL不冒充箱数}
         skuCount: {type: integer, minimum: 0}
         duplicateCarton: {type: boolean, description: 历史重复任务关联提示，不将同一来源不同SKU按件任务视为重复}
         quantityUnit: {type: string, enum: [PIECE, CARTON, UNKNOWN]}
-        sourcePalletCount: {type: integer, format: int64, nullable: true, description: 缺少不可变原托快照时为null}
-        targetPalletCount: {type: integer, format: int64, nullable: true, description: 未提供汇总，详情以本轮有效绑定历史为准}
+        sourcePalletCount: {type: string, pattern: '^[0-9]+$', nullable: true, description: 缺少不可变原托快照时为null}
+        targetPalletCount: {type: string, pattern: '^[0-9]+$', nullable: true, description: 每个任务本轮最后一次可信绑定的不同目标托盘数；未绑定完整为null}
+        sourceUnitCounts:
+          type: object
+          nullable: true
+          description: 首次认领时已清点且精确关联的退货来源主键按BOX/PARCEL/PALLET分类去重；任一来源缺失时为null，不按标识外形猜测
+          additionalProperties: {type: string, pattern: '^[0-9]+$'}

lastleg-service/src/main/resources/openapi/return-order-statistics-v1.yaml

@@ -0,0 +1,60 @@
+openapi: 3.0.3
+info:
+  title: 退货全筛选统计与托盘无效果恢复
+  version: 1.0.0
+paths:
+  /api/merchant/v1/last-leg/return-orders/statistics:
+    get:
+      summary: 当前客户退货全筛选统计
+      description: 使用与退货分页列表一致的 returnNo、status、skuCode、trackingNo 条件。客户由认证身份确定，忽略客户端归属输入。totals 不受 page/size 影响；pageDimensions 仅对应当前页。SKU 跨订单按去空白大写后的编码去重。件、箱、包裹、托独立统计；未提供的预报载体数不推算为零。需要 MERCHANT_RETURN_ORDER_LIST 对应正式权限。
+      operationId: merchantReturnOrderStatistics
+      responses:
+        '200':
+          description: ApiResponse，data 为 totals 与 pageDimensions；失败按统一响应契约返回。
+  /api/platform/v1/last-leg/return-orders/statistics:
+    get:
+      summary: 尾程筛选集合中原生退货订单的统计
+      description: 需要 platform:overseas-warehouse:last-mile-order:list。完整复用尾程列表筛选；totals 只聚合其中有原生退货记录的订单。pageDimensions 对应混合尾程列表当前页中的退货行，不单独分页退货子集。实收载体来自签收事实，出库不扣减历史签收数量。
+      operationId: platformReturnOrderStatistics
+      responses:
+        '200':
+          description: ApiResponse，data 为 totals 与 pageDimensions。
+  /api/platform/v1/last-leg/pallet-operation-recoveries/{id}:
+    parameters:
+      - in: path
+        name: id
+        required: true
+        schema: { type: integer, format: int64 }
+    get:
+      summary: 管理员只读核对原托盘作业
+      description: 需要 lastleg:inventory:manage，返回原状态、请求哈希、远端意图、原错误和更新时间，不返回会话凭据。
+      operationId: inspectPalletOperationRecovery
+      responses:
+        '200': { description: 原作业技术审计状态 }
+  /api/platform/v1/last-leg/pallet-operation-recoveries/{id}/close-no-effect:
+    parameters:
+      - in: path
+        name: id
+        required: true
+        schema: { type: integer, format: int64 }
+    post:
+      summary: 审计关闭无远端效果的超时换标组托
+      description: 需要 lastleg:inventory:manage。仅 RELABEL_PALLET_DISASSEMBLE、PROCESSING 或 FAILED_COMPENSATED、超过15分钟、版本一致、无结果且无任何远端意图允许关闭。未知/已确认/损坏远端记录均拒绝。原行行锁与远端意图条件写互斥；旧线程失败写不能覆盖恢复终态。原请求哈希及原错误不变，恢复管理员、原因、幂等键、原状态和时间写入原 result_json。相同管理员/键/原因重放返回同一审计，不另造业务成功结果。无需新增表，不写库存或远端实托。
+      operationId: closePalletOperationNoEffect
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [warehouseId, expectedUpdatedAt, idempotencyKey, reason]
+              properties:
+                warehouseId: { type: integer, format: int64, minimum: 1 }
+                expectedUpdatedAt: { type: string, format: date-time }
+                idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+                reason: { type: string, minLength: 1, maxLength: 1000 }
+      responses:
+        '200': { description: ApiResponse 恢复审计或正式业务拒绝 }
+        '403': { description: 权限不足 }
+        '404': { description: 原作业不存在 }
+        '409': { description: 原状态、版本、归属或远端效果不满足恢复条件 }

lastleg-service/src/main/resources/openapi/warehouse-transfer-quantities-v1.yaml

@@ -0,0 +1,120 @@
+openapi: 3.0.3
+info:
+  title: 仓储转运与混箱库存数量
+  version: 1.0.0
+  description: 件、箱、托分开记录。所有Long数量序列化为十进制字符串；未知件数保持null，空筛选返回零。同托部分出库可同时属于历史实收、剩余、出库集合，禁止托数相减。
+paths:
+  /api/platform/v1/last-leg/orders/warehouse-transfer-quantities:
+    get:
+      operationId: platformWarehouseTransferQuantityTotals
+      description: 权限platform:overseas-warehouse:last-mile-order:list，平台访问域与主订单列表一致。复用主订单全部Query筛选及relabelNo，额外限定WAREHOUSE_TRANSFER；page/size不参与汇总。
+      responses:
+        '200':
+          description: ApiResponse.data为TransferQuantityTotals。
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/TotalsEnvelope' }
+  /api/merchant/v1/last-leg/warehouse-transfers/quantities:
+    get:
+      operationId: merchantWarehouseTransferQuantityTotals
+      description: 权限merchant:overseas-warehouse:transfer:list，客户范围只从会话获取。复用转运列表完整筛选，包括transferNo/inboundCode/operatingWarehouseId/fbaWarehouseCode/status/needRelabel和创建、审核、清点完成、出库日期区间；日期区间上界包含端点。page/size不参与汇总。
+      responses:
+        '200':
+          description: ApiResponse.data为TransferQuantityTotals。
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/TotalsEnvelope' }
+  /api/platform/v1/last-leg/inventory/piece-projection:
+    get:
+      operationId: platformInventoryPieceProjection
+      description: 权限platform:overseas-warehouse:inventory:list，与库存列表相同平台客户访问域及BalanceQuery完整筛选，不分页。按原箱清点及正式目的仓签收凭据投影当前未占用可用库存。每仓位精确箱映射数量须等于available_packages，箱内SKU件数须等于箱总清点件数；缺失、不一致、无法追溯的非转运库存均为未知，不按箱规或首SKU推算。通用余额MIXED也逐箱读取全部SKU。SKU查询可命中混箱第二SKU。
+      responses:
+        '200':
+          description: ApiResponse.data为InventoryPieceProjection。
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code: { type: string }
+                  data: { $ref: '#/components/schemas/InventoryPieceProjection' }
+components:
+  schemas:
+    Count:
+      type: string
+      pattern: '^[0-9]+$'
+    NullableCount:
+      type: string
+      nullable: true
+      pattern: '^[0-9]+$'
+    TransferQuantityView:
+      type: object
+      description: 主订单列表与详情summary.warehouseTransferQuantity，仅转运订单提供。新到仓历史实收取counted_at非空且COUNTED/DISCARD_PENDING/DISCARDED/SHIPPED原箱；库存转运实收取正式目的仓签收凭据，件数取精确原箱清点。
+      properties:
+        lastlegOrderId: { $ref: '#/components/schemas/Count' }
+        declaredPieceCount: { $ref: '#/components/schemas/NullableCount' }
+        receivedPieceCount: { $ref: '#/components/schemas/NullableCount' }
+        declaredCartonCount: { $ref: '#/components/schemas/Count' }
+        receivedCartonCount: { $ref: '#/components/schemas/Count' }
+        receivedPalletCount: { $ref: '#/components/schemas/Count' }
+        availableCartonCount: { type: string, description: 原箱当前COUNTED数，非扣除其他业务预留后的可用库存。真实可用数读取库存投影。 }
+        shippedCartonCount: { $ref: '#/components/schemas/Count' }
+        remainingPalletCount: { $ref: '#/components/schemas/Count' }
+        shippedPalletCount: { $ref: '#/components/schemas/Count' }
+    TransferQuantityTotals:
+      allOf:
+        - { $ref: '#/components/schemas/TransferQuantityView' }
+        - type: object
+          properties:
+            orderCount: { $ref: '#/components/schemas/Count' }
+            knownDeclaredPieceCount: { $ref: '#/components/schemas/Count' }
+            unknownDeclaredOrderCount: { $ref: '#/components/schemas/Count' }
+            knownReceivedPieceCount: { $ref: '#/components/schemas/Count' }
+            unknownReceivedOrderCount: { $ref: '#/components/schemas/Count' }
+    TotalsEnvelope:
+      type: object
+      properties:
+        code: { type: string }
+        data: { $ref: '#/components/schemas/TransferQuantityTotals' }
+    Sku:
+      type: object
+      properties:
+        skuCode: { type: string }
+        quantity: { $ref: '#/components/schemas/Count' }
+    InventoryPieceProjection:
+      type: object
+      properties:
+        availablePieceCount: { $ref: '#/components/schemas/NullableCount' }
+        knownAvailablePieceCount: { $ref: '#/components/schemas/Count' }
+        unknownCartonCount: { $ref: '#/components/schemas/Count' }
+        availableCartonCount: { $ref: '#/components/schemas/Count' }
+        availablePalletCount: { $ref: '#/components/schemas/Count' }
+        groups:
+          type: array
+          items:
+            type: object
+            properties:
+              customerId: { type: string }
+              warehouseId: { type: string }
+              destinationCode: { type: string, nullable: true }
+              anchorSkuCode: { type: string, nullable: true, description: 原余额记账SKU，可能为MIXED。完整SKU在skuContents中。 }
+              availablePieceCount: { $ref: '#/components/schemas/NullableCount' }
+              knownAvailablePieceCount: { $ref: '#/components/schemas/Count' }
+              unknownCartonCount: { $ref: '#/components/schemas/Count' }
+              availableCartonCount: { $ref: '#/components/schemas/Count' }
+              availablePalletCount: { $ref: '#/components/schemas/Count' }
+              skuContents:
+                type: array
+                items: { $ref: '#/components/schemas/Sku' }
+              cartons:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    cartonMark: { type: string }
+                    inventoryPositionId: { type: string }
+                    palletId: { type: string, nullable: true }
+                    quantity: { $ref: '#/components/schemas/NullableCount' }
+                    items:
+                      type: array
+                      items: { $ref: '#/components/schemas/Sku' }