提交

2026-10-16 16:18:28 +08:00
parent 000125c3ec
commit 488c0318ff
13 changed files with 417 additions and 48 deletions
@@ -4,10 +4,30 @@ info:
  description: 派送资料完整契约见同目录 delivery-documents-v1.yaml；派送列表/详情行返回 bolNo、documentSummary（三类状态与x/3），状态仍使用 version 和 allowedActions。
  version: 1.0.0
 paths:
+  /api/merchant/v1/last-leg/warehouse-transfers/{transferNo}/increase-forecast-cartons:
+    post:
+      summary: 测量完成前增加预报箱数并补充箱唛
+      description: 客户身份及transfer:create权限；仅外来货物待审核或待PDA测量可用，按原预报快照追加既有SKU的箱数，原箱唛与件数不变。补箱及PDA完工锁定同一订单；成功后PDA刷新继续清点，无新增表字段。
+      parameters:
+        - {name: transferNo, in: path, required: true, schema: {type: string}}
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [expectedPackageCount, transferItemId, expectedItemPackageCount, packageCount]
+              properties:
+                expectedPackageCount: {type: integer, minimum: 1, maximum: 5000, description: 修改前整单预报箱数}
+                transferItemId: {type: integer, format: int64, description: 当前单既有SKU明细}
+                expectedItemPackageCount: {type: integer, minimum: 0, maximum: 5000, description: 修改前该SKU预报箱数}
+                packageCount: {type: integer, minimum: 1, maximum: 5000, description: 增加后该SKU预报箱数}
+      responses:
+        '200': {description: 返回补箱后的转运详情，相同原快照和目标箱数重试不重复生成箱唛}
  /api/pda/v1/last-leg/warehouse-transfers/{transferNo}/carton-label:
    get:
      summary: PDA读取转运箱标签
-      description: 需要 lastleg:pda:operate 与 OVERSEAS_WAREHOUSE_PDA_OPERATOR；只可读取Token绑定仓的转运单标签，包含新增实收箱号。
+      description: 需要 lastleg:pda:operate 与 OVERSEAS_WAREHOUSE_PDA_OPERATOR；只可读取Token绑定仓的转运单标签，包含客户预报及后续补充预报的箱唛。
      parameters:
        - {name: transferNo, in: path, required: true, schema: {type: string}}
      responses:
@@ -33,7 +53,7 @@ paths:
  /api/pda/v1/last-leg/warehouse-transfers/{transferNo}/cartons/count:
    post:
      summary: 转运逐箱测量与清点
-      description: 仅限 lastleg:pda:operate 与 OVERSEAS_WAREHOUSE_PDA_OPERATOR，绑定仓由统一Token确定。先创建本单托盘号，每箱选择所属托盘，可包含多个本单预报SKU，逐项记录实点件数；同箱SKU不可重复，尺寸重量和实收箱数按实物箱计算一次，托盘体积重量由分配箱子汇总，全部实收箱子测量清点后才可完成打托入库，打托箱数与已清点实收箱数核平；短收箱保留未收到事实，超收生成系统箱号；差异需原因。事务锁定转运单；原键原载荷重试不重复写入，同键不同载荷拒绝，已确认事实不可覆盖。
+      description: 仅限 lastleg:pda:operate 与 OVERSEAS_WAREHOUSE_PDA_OPERATOR，绑定仓由统一Token确定。先创建本单托盘号，每箱选择所属托盘，可包含多个本单预报SKU，逐项记录实点件数；同箱SKU不可重复，尺寸重量和实收箱数按实物箱计算一次，托盘体积重量由分配箱子汇总，全部实收箱子测量清点后才可完成打托入库，打托箱数与已清点实收箱数核平；短收箱保留未收到事实，额外箱须客户先增加预报箱数补生成箱唛；清点允许暂不填写差异原因，最终完成测量时仅SKU实收件数有差异才必填原因。事务锁定转运单；原键原载荷重试不重复写入，同键不同载荷拒绝，已确认事实不可覆盖。
      parameters:
        - {name: transferNo, in: path, required: true, schema: {type: string}}
      requestBody:
@@ -42,20 +62,21 @@ paths:
          application/json:
            schema:
              type: object
-              required: [idempotencyKey, boxes]
+              required: [idempotencyKey, boxes, forecastPackageCount]
              properties:
                idempotencyKey: {type: string, maxLength: 255}
-                discrepancyReason: {type: string, maxLength: 1000, description: 短收超收时必填差异原因}
+                forecastPackageCount: {type: integer, minimum: 1, description: 设备读取的预报箱数，补箱后旧快照须刷新}
+                discrepancyReason: {type: string, maxLength: 1000, description: 清点阶段可选，最终完成测量时SKU实收件数有差异必填原因}
                boxes:
                  type: array
                  minItems: 1
                  maxItems: 5000
                  items:
                    type: object
-                    required: [transferPalletId, length, width, height, weight, items]
+                    required: [cartonMark, transferPalletId, length, width, height, weight, items]
                    properties:
-                      cartonMark: {type: string, maxLength: 255, nullable: true, description: 已有箱号；新增超收箱不传，由服务端生成}
-                      transferItemId: {type: integer, format: int64, nullable: true, description: 新增超收箱所属本单申报明细}
+                      cartonMark: {type: string, maxLength: 255, description: 必须为当前单预报中已存在的仓库唛头}
+                      transferItemId: {type: integer, format: int64, nullable: true, description: 箱子所属本单申报明细}
                      transferPalletId: {type: integer, format: int64, description: 本单已生成的转运托盘事实ID，逐箱关联，托盘箱数体积重量由箱子汇总}
                      length: {type: number, minimum: 0.01, description: 箱长厘米}
                      width: {type: number, minimum: 0.01, description: 箱宽厘米}
@@ -587,6 +587,7 @@ components:
      required: [idempotencyKey, photoFileIds]
      properties:
        idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+        discrepancyReason: { type: string, maxLength: 1000, nullable: true, description: 任一SKU实收件数与预报不同时完成测量必填，原因随完成事务保存 }
        photoFileIds:
          type: array
          minItems: 1