优化

2026-08-17 15:41:42 +08:00
parent 4abcb2b80f
commit 5f79616623
60 changed files with 1457 additions and 270 deletions
@@ -357,6 +357,53 @@ paths:
      responses:
        '200': {description: 成功、计划不存在或计划已进入预装流程}
        '403': {description: 无智能装柜查询权限}
+  /api/platform/v1/first-leg/smart-loading/plans/{planId}/assignments:
+    post:
+      summary: 向预装计划新增入库单明细
+      description: >-
+        EDITING 或 LOADING 且 PDA task 尚未完成时可用。服务端按 planId 锁定同一 PDA task，
+        校验仓库、渠道、客户范围、可用箱数、容积和限重后原子新增/累加明细；LOADING 时同步到原 taskId，
+        递增 planVersion、taskVersion，原 inventorySnapshotToken 随即失效。与 PDA batch/final complete 并发时，
+        锁顺序为 PDA task 行锁 -> plan 乐观锁；仅先取得任务锁且持有匹配版本的一方成功，另一方返回 A0409。
+        PDA 应重新 GET task detail 与 inventory snapshot，Admin 应重新 GET SmartLoadingPlan。新增项沿用原 taskId、
+        loadingPlanId、containerBookingId 和 inbound identity；已全拣任务会因新增 PENDING item 从 AWAITING_REVIEW
+        回到 IN_PROGRESS，已有证据不删除，但 final complete 门禁撤回。
+      parameters:
+        - {name: planId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+      requestBody:
+        required: true
+        content: {application/json: {schema: {$ref: '#/components/schemas/SmartLoadingAssignRequest'}}}
+      responses:
+        '200': {description: 成功或业务失败，data 为最新 SmartLoadingPlan}
+  /api/platform/v1/first-leg/smart-loading/plans/{planId}/items/{itemId}:
+    patch:
+      summary: 调整预装计划明细箱数
+      description: >-
+        EDITING/LOADING 均可；packageCount 不得小于已拣 pickedPackageCount。成功递增 plan、计划明细和现有 PDA task 版本，
+        原 inventorySnapshotToken 失效。PDA task 已完成或并发版本变化返回 A0409，事务零写入；调用方须刷新
+        SmartLoadingPlan，PDA 在下一次写入前须刷新 task detail 与 inventory snapshot。
+      parameters:
+        - {name: planId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+        - {name: itemId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+      requestBody:
+        required: true
+        content: {application/json: {schema: {$ref: '#/components/schemas/SmartLoadingAdjustRequest'}}}
+      responses:
+        '200': {description: 成功或业务失败，data 为最新 SmartLoadingPlan}
+    delete:
+      summary: 删除未拣预装计划明细
+      description: >-
+        仅 pickedPackageCount=0 且计划/PDA task 未最终完成时允许。成功递增 plan 和 task 版本并使原库存快照失效；
+        已拣、COMPLETED 或并发版本变化返回 A0409，事务零写入。PDA final complete 与本操作使用相同 task 行锁，
+        因而只允许一个事务成功；失败方刷新计划、task detail 与 inventory snapshot 后再决定后续操作。
+      parameters:
+        - {name: planId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+        - {name: itemId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+      requestBody:
+        required: true
+        content: {application/json: {schema: {$ref: '#/components/schemas/SmartLoadingDeleteRequest'}}}
+      responses:
+        '200': {description: 成功或业务失败，data 为最新 SmartLoadingPlan}
  /api/platform/v1/first-leg/smart-loading/plans/{planId}/push-preload:
    post:
      summary: 推送智能装柜计划到预装清单
@@ -1303,6 +1350,67 @@ components:
      required: [expectedVersion]
      properties:
        expectedVersion: {type: integer, minimum: 0}
+    SmartLoadingAssignRequest:
+      type: object
+      required: [inboundId, inboundDetailId, packageCount, expectedVersion, operationId]
+      properties:
+        inboundId: {type: string, pattern: '^[1-9][0-9]*$'}
+        inboundDetailId: {type: string, pattern: '^[1-9][0-9]*$'}
+        packageCount: {type: integer, minimum: 1}
+        expectedVersion: {type: integer, minimum: 0, description: 当前 planVersion}
+        operationId: {type: string, minLength: 1, maxLength: 128}
+    SmartLoadingAdjustRequest:
+      type: object
+      required: [packageCount, expectedPlanVersion, expectedItemVersion, operationId]
+      properties:
+        packageCount: {type: integer, minimum: 1, description: 不得小于响应中的 minPackageCount}
+        expectedPlanVersion: {type: integer, minimum: 0}
+        expectedItemVersion: {type: integer, minimum: 0}
+        operationId: {type: string, minLength: 1, maxLength: 128}
+    SmartLoadingDeleteRequest:
+      type: object
+      required: [expectedPlanVersion, expectedItemVersion, operationId]
+      properties:
+        expectedPlanVersion: {type: integer, minimum: 0}
+        expectedItemVersion: {type: integer, minimum: 0}
+        operationId: {type: string, minLength: 1, maxLength: 128}
+    SmartLoadingPlan:
+      type: object
+      required: [id, planNo, status, bookingId, version, canAssign, canEdit, finalCompletionStatus, items]
+      properties:
+        id: {type: string}
+        planNo: {type: string}
+        status: {type: string, enum: [EDITING, LOADING, COMPLETED]}
+        bookingId: {type: string}
+        containerNo: {type: string, nullable: true}
+        voyageNo: {type: string, nullable: true}
+        version: {type: integer, minimum: 0, description: planVersion，写请求使用此值}
+        canAssign: {type: boolean}
+        canEdit: {type: boolean}
+        blockedReason: {type: string, nullable: true}
+        finalCompletionStatus: {type: string, enum: [NOT_STARTED, IN_PROGRESS, COMPLETED], description: IN_PROGRESS 表示 final complete 门禁尚未通过；增量新增 PENDING item 会保持或恢复此值，COMPLETED 后 canAssign/canEdit 均为 false}
+        pdaTaskId: {type: string, nullable: true}
+        pdaTaskStatus: {type: string, nullable: true, enum: [LOADING, COMPLETED], description: LOADING task 在增量后保持原 taskId；COMPLETED 永久拒绝增量}
+        pdaTaskVersion: {type: integer, minimum: 0, nullable: true, description: 服务端同步后最新 taskVersion；Admin 写操作不提交该值}
+        items:
+          type: array
+          items: {$ref: '#/components/schemas/SmartLoadingPlanItem'}
+    SmartLoadingPlanItem:
+      type: object
+      required: [id, packageCount, version, pickedPackageCount, minPackageCount, canAdjust, canRemove]
+      properties:
+        id: {type: string}
+        inboundId: {type: string}
+        inboundDetailId: {type: string}
+        orderNo: {type: string, nullable: true}
+        inboundCode: {type: string, nullable: true}
+        customerName: {type: string, nullable: true}
+        packageCount: {type: integer, minimum: 1}
+        version: {type: integer, minimum: 0, description: itemVersion，调整/删除写请求使用此值}
+        pickedPackageCount: {type: integer, minimum: 0}
+        minPackageCount: {type: integer, minimum: 1}
+        canAdjust: {type: boolean}
+        canRemove: {type: boolean}
    ContainerDocumentAttachRequest:
      type: object
      required: [fileId, expectedVersion]