优化

2026-10-21 15:53:33 +08:00
parent 94595c810b
commit 090591076f
41 changed files with 459 additions and 63 deletions
@@ -1907,6 +1907,7 @@ CREATE TABLE IF NOT EXISTS ll_dispatch_order (
  review_state VARCHAR(32) NOT NULL DEFAULT 'DRAFT' COMMENT '审核子流程当前状态',
  review_round BIGINT NOT NULL DEFAULT 0 COMMENT '当前审核轮次',
  review_basis_hash CHAR(64) NULL COMMENT '本审核轮次核对的货物和资源依据摘要',
+  exceptions_json JSON NULL COMMENT '派送异常登记记录及图片引用，不改变派送及库存状态',
  dispatch_review_json JSON NULL COMMENT '当前调度审核事实快照',
  loading_review_json JSON NULL COMMENT '当前理货审核事实快照',
  resources_json JSON NULL COMMENT '本趟主档或临时车辆司机的真实资源快照',
@@ -1682,6 +1682,49 @@ paths:
      required: true
      schema:
        type: string
+  /api/platform/v1/last-leg/dispatches/{dispatchNo}/exceptions:
+    post:
+      summary: 登记派送异常
+      description: 权限 platform:overseas-warehouse:dispatch:edit；仅有效仓库派送单DELIVERING可登记，保存后阶段不变，不产生退货、签收或库存变化。原键重试恢复原结果。
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: 统一ApiResponse；业务失败通过code返回，不能仅凭HTTP200判断成功。
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code:
+                    type: string
+                  message:
+                    type: string
+                  requestId:
+                    type: string
+                    nullable: true
+                  traceId:
+                    type: string
+                    nullable: true
+                  timestamp:
+                    type: string
+                    format: date-time
+                  data:
+                    allOf:
+                    - $ref: '#/components/schemas/DispatchCommandResult'
+                    nullable: true
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/DispatchMarkException'
+    parameters:
+    - name: dispatchNo
+      in: path
+      required: true
+      schema:
+        type: string
  /api/platform/v1/last-leg/dispatches/{dispatchNo}/loading-complete:
    post:
      summary: 确认装车完成并自动进入派送中
@@ -1880,7 +1923,7 @@ paths:
  /api/platform/v1/last-leg/dispatches/{dispatchNo}/evidence/{kind}:
    post:
      summary: 上传本趟车辆或司机证据
-      description: 客服阶段使用 platform:overseas-warehouse:dispatch:edit；调度待审/理货待审分别使用 platform:fleet:trip:dispatch-review / platform:fleet:trip:loading-review，无需维护车辆权限。VEHICLE和DRIVER支持PDF/JPG/PNG，DRIVER_PHOTO仅JPG/PNG，非空且不超过10MiB；平台、本车、类型复合归属。审核补充附件随ReviewCommand保存，不修改资源，不重启审核。
+      description: 客服阶段使用 platform:overseas-warehouse:dispatch:edit；调度待审/理货待审分别使用 platform:fleet:trip:dispatch-review / platform:fleet:trip:loading-review，无需维护车辆权限。VEHICLE和DRIVER支持PDF/JPG/PNG，DRIVER_PHOTO和EXCEPTION仅JPG/PNG；EXCEPTION仅派送中使用排车edit权限，引用随异常登记保存。非空且不超过10MiB；平台、本车、类型复合归属。审核补充附件随ReviewCommand保存，不修改资源，不重启审核。
      security:
      - bearerAuth: []
      responses:
@@ -1935,6 +1978,7 @@ paths:
        - VEHICLE
        - DRIVER
        - DRIVER_PHOTO
+        - EXCEPTION
  /api/platform/v1/last-leg/dispatches/{dispatchNo}/evidence/{kind}/{fileId}:
    get:
      summary: 读取本车证据元数据
@@ -1981,6 +2025,7 @@ paths:
        - VEHICLE
        - DRIVER
        - DRIVER_PHOTO
+        - EXCEPTION
    - name: fileId
      in: path
      required: true
@@ -2024,6 +2069,7 @@ paths:
        - VEHICLE
        - DRIVER
        - DRIVER_PHOTO
+        - EXCEPTION
    - name: fileId
      in: path
      required: true
@@ -3503,12 +3549,13 @@ components:
        remark: { type: string, maxLength: 500, nullable: true }
    ContainerArrivalTimeView:
      type: object
-      required: [sourceContainerBookingId, version]
+      required: [sourceContainerBookingId, version, planCount]
      properties:
        sourceContainerBookingId: { type: string }
-        estimatedWarehouseArrivalAt: { type: string, format: date-time, nullable: true }
+        estimatedWarehouseArrivalAt: { type: string, format: date-time, nullable: true, description: 人工维护或入库计划冻结的整柜时间；未维护未建计划时为空，由页面按到港当地日期加两个自然日展示默认日期 }
        actualWarehouseArrivalAt: { type: string, format: date-time, nullable: true, description: 海外 PDA 首次开始收货时间 }
-        version: { type: integer, minimum: 0 }
+        version: { type: integer, minimum: -1, description: -1表示柜内时间版本不一致 }
+        planCount: { type: integer, format: int64, minimum: 0, description: 整柜已有入库计划数量；非零时禁止默认推算及改期 }
    ContainerPlanProgressDetail:
      type: object
      required: [summary, orders]
@@ -5142,6 +5189,7 @@ components:
      - LOADING_COMPLETE
      - ARRANGE_DELIVERY
      - DEPART
+      - MARK_EXCEPTION
    DispatchGate:
      type: object
      x-java-record: DispatchContracts.Gate
@@ -6314,6 +6362,10 @@ components:
          items:
            $ref: '#/components/schemas/DispatchBatchReference'
          nullable: true
+        exceptions:
+          type: array
+          items:
+            $ref: '#/components/schemas/DispatchExceptionRecord'
      required:
      - route
      - plannedDepartureAt
@@ -6321,6 +6373,7 @@ components:
      - estimatedArrivalAt
      - fbaAppointments
      - appointmentBatches
+      - exceptions
    DispatchDocuments:
      type: object
      x-java-record: DispatchViews.Documents
@@ -7940,5 +7993,66 @@ components:
      - sourceInboundOrderNo
      - sourceInboundCode
      - productQuantity
+
+    DispatchExceptionType:
+      type: string
+      enum: [REFUSED, PARTIAL_RECEIPT, VEHICLE_EXCEPTION]
+      description: 拒收、部分签收、车辆异常。
+    DispatchReturnDirection:
+      type: string
+      enum: [OVERSEAS_WAREHOUSE, OTHER]
+      description: 退回海外仓、其他；仅登记去向，不自动退货入库。
+    DispatchMarkException:
+      type: object
+      x-java-record: DispatchCommands.MarkException
+      required: [recordVersion, idempotencyKey, exceptionType]
+      properties:
+        recordVersion:
+          oneOf:
+          - type: string
+            pattern: ^[0-9]+$
+          - type: integer
+            minimum: 0
+        idempotencyKey:
+          type: string
+        exceptionType:
+          $ref: '#/components/schemas/DispatchExceptionType'
+        returnDirection:
+          allOf:
+          - $ref: '#/components/schemas/DispatchReturnDirection'
+          nullable: true
+        description:
+          type: string
+          maxLength: 1000
+          nullable: true
+        imageFileIds:
+          type: array
+          maxItems: 20
+          uniqueItems: true
+          items:
+            type: string
+            pattern: ^[1-9][0-9]*$
+    DispatchExceptionRecord:
+      type: object
+      x-java-record: DispatchViews.ExceptionRecord
+      required: [exceptionType, returnDirection, description, imageFileIds, occurredAt]
+      properties:
+        exceptionType:
+          $ref: '#/components/schemas/DispatchExceptionType'
+        returnDirection:
+          allOf:
+          - $ref: '#/components/schemas/DispatchReturnDirection'
+          nullable: true
+        description:
+          type: string
+          nullable: true
+        imageFileIds:
+          type: array
+          items:
+            type: string
+        occurredAt:
+          type: string
+          format: date-time
+
  securitySchemes:
    bearerAuth: { type: http, scheme: bearer, bearerFormat: JWT }