提交

lastleg-service/src/main/resources/db/lastleg.sql

@@ -3048,6 +3048,15 @@ CREATE TABLE IF NOT EXISTS ll_us_truck_order_status_history (
 CREATE TABLE IF NOT EXISTS ll_local_looseboard_order (
   id BIGINT NOT NULL COMMENT '主键ID', customer_id VARCHAR(128) NOT NULL COMMENT '客户租户ID',
   lastleg_order_id BIGINT NULL COMMENT '关联尾程主订单ID',
+  delivery_mode VARCHAR(32) NULL COMMENT '入仓方式：送货到仓或仓库上门取货',
+  operating_warehouse_id VARCHAR(128) NULL COMMENT '实际收货海外仓ID',
+  destination_type VARCHAR(16) NULL COMMENT '目的地类型：FBA或私人地址',
+  destination_postal_code VARCHAR(32) NULL COMMENT '私人目的地邮编',
+  delivery_contact_name VARCHAR(128) NULL COMMENT '送货到仓联系人',
+  delivery_contact_phone VARCHAR(64) NULL COMMENT '送货到仓联系电话',
+  estimated_arrival_at DATETIME(3) NULL COMMENT '预计到仓时间',
+  tracking_no VARCHAR(255) NULL COMMENT '物流跟踪号',
+  transfer_no VARCHAR(64) NULL COMMENT '关联的仓储转运收货单号',
   order_no VARCHAR(64) NOT NULL COMMENT '本土散板订单号',
   pallet_required VARCHAR(8) NULL DEFAULT NULL COMMENT '是否需要打盘：YES或NO；拼车来源未提供时为空', transport_type VARCHAR(32) NULL DEFAULT NULL COMMENT '接单运输安排；下单不预设',
   origin VARCHAR(255) NOT NULL COMMENT '起运地', origin_address VARCHAR(500) NULL COMMENT '起运详细地址',

lastleg-service/src/main/resources/openapi/dispatch-looseboard-execution-v1.yaml

@@ -0,0 +1,68 @@
+openapi: 3.0.3
+info:
+  title: 本土散板排车照片履约
+  version: 1.0.0
+  description: >-
+    仅同客户权威关联的本土散板明细进入照片节点。全车为散板且尚无真实扫码时，审核通过后逐票保存取货照片，
+    自动从LOADING进入DELIVERING；不生成库存、PDA拣货或仓库出库事实。逐票保存送达照片后自动DELIVERED并结案释放车辆司机。
+    混排从AFTER_LOADING或DELIVERING可逐票保存取货及送达照片；同票须先取货再送达，不同票不限制取送顺序。
+    装车后保存照片保持原阶段，保留原PDA出库及装车资料齐全后进入派送的链路；全部仓内货签收且散板照片齐全才可整车完结。既有真实扫码不可抹除或倒改。
+    图片只接受10MiB以内JPG或PNG，每票每节点最多20张。保存提交该节点完整保留列表，支持追加和逐张删除；空列表代表删除最后一张。
+    整车已完结的节点及已有送达照片的取货节点至少保留一张凭证，可先追加再删除；修改照片不撤销已执行的取货、发运或送达，不重复累计货量。
+    上传不等于保存，保存用公共版本和幂等键，失败同事务回滚。历史照片列表保留审计，仅最新列表授权预览。
+    本土散板号只用LB原单，不生成入仓码、柜号或虚构派送单号。分车运输按已保存送达照片的明细去重累计箱数，整票送达后才完成原单。
+paths:
+  /api/platform/v1/last-leg/dispatches/{number}/looseboard-execution:
+    parameters:
+      - { name: number, in: path, required: true, schema: { type: string } }
+    get:
+      summary: 读取散板逐票照片与节点资格
+      description: 需要platform:overseas-warehouse:dispatch:list。data包含dispatchNo、recordVersion、stage、direct和items；items包含itemId、customerId、orderNo、destination、packages、pickupPhotos、arrivalPhotos、canPickup、canArrive。
+      responses: { '200': { description: 统一ApiResponse } }
+  /api/platform/v1/last-leg/dispatches/{number}/looseboard-execution/{itemId}/{phase}/uploads:
+    parameters:
+      - { name: number, in: path, required: true, schema: { type: string } }
+      - { name: itemId, in: path, required: true, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
+      - { name: phase, in: path, required: true, schema: { type: string, enum: [PICKUP, ARRIVAL] } }
+    post:
+      summary: 上传本车本节点照片，尚不作为保存或发运事实
+      description: 需要platform:overseas-warehouse:dispatch:edit。文件业务归属为平台、本车ID、独立节点类别。
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              required: [file]
+              properties: { file: { type: string, format: binary } }
+      responses: { '200': { description: data为fileId、fileName、contentType、sizeBytes } }
+  /api/platform/v1/last-leg/dispatches/{number}/looseboard-execution/{itemId}/{phase}:
+    parameters:
+      - { name: number, in: path, required: true, schema: { type: string } }
+      - { name: itemId, in: path, required: true, schema: { type: string } }
+      - { name: phase, in: path, required: true, schema: { type: string, enum: [PICKUP, ARRIVAL] } }
+    put:
+      summary: 保存逐票节点照片并原子核对运输进度
+      description: 需要platform:overseas-warehouse:dispatch:edit；不得跨车、跨节点或在不同票之间重复绑定照片。重审轮次变化后旧照片保留历史但不代替本轮履约。
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [recordVersion, idempotencyKey, fileIds]
+              properties:
+                recordVersion: { type: integer, format: int64, minimum: 0 }
+                idempotencyKey: { type: string, minLength: 8, maxLength: 128 }
+                fileIds: { type: array, maxItems: 20, uniqueItems: true, description: 本节点完整保留照片列表，空列表用于删除最后一张且受已履约凭证约束, items: { type: string, pattern: '^[1-9][0-9]*$' } }
+      responses: { '200': { description: 返回当前整车照片状态；重复原命令不重复推进运输或生成作业事实 } }
+  /api/platform/v1/last-leg/dispatches/{number}/looseboard-execution/{itemId}/{phase}/files/{fileId}/content:
+    parameters:
+      - { name: number, in: path, required: true, schema: { type: string } }
+      - { name: itemId, in: path, required: true, schema: { type: string } }
+      - { name: phase, in: path, required: true, schema: { type: string, enum: [PICKUP, ARRIVAL] } }
+      - { name: fileId, in: path, required: true, schema: { type: string } }
+    get:
+      summary: 读取当前明细节点已保存照片
+      description: 需要platform:overseas-warehouse:dispatch:list；未保存上传和其他票照片不可读取。
+      responses: { '200': { description: JPG或PNG，Cache-Control no-store } }

lastleg-service/src/main/resources/openapi/exception-return-inbound-v1.yaml

@@ -4,6 +4,36 @@ info:
   version: 1.0.0
   description: 排车异常冻结原出库货物，异常单生成退回尾程单后进入PDA退货入库列表。现场展示异常单号、车牌和待收箱数，点击开始作业，不需要回单号或扫码找单。建单不增加库存，分批实收调用原来源RETURN_STOCK_IN或原箱恢复，异常和退回尾程单收齐后完成。
 paths:
+  /api/platform/v1/last-leg/exception-orders/return-inbound-plans:
+    post:
+      summary: 异常退回尾程单生成入库计划
+      description: 仅平台账号，权限platform:overseas-warehouse:inbound-order:create。无来源柜，必须填写本次预计到仓时间。服务端核验客户、尾程版本、异常状态及冻结退回仓；当前尾程单号作为新入仓码，保留来源尾程关联。建计划不入账，后续通过异常退回验收恢复原库存并同步计划完成状态，不可走普通PDA入库重复入账。同键同载荷返回首次响应，异载荷拒绝。
+      parameters:
+        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, maxLength: 128 } }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [plan, expectedArrivalAt]
+              properties:
+                expectedArrivalAt: { type: string, format: date-time, description: 本次退回预计到仓当地时间，不带时区 }
+                plan:
+                  type: object
+                  required: [customerId, orderId, expectedOrderVersion, palletCount, palletType, assigned, mergeRequired, urgent]
+                  properties:
+                    customerId: { type: string, maxLength: 128 }
+                    orderId: { type: string, description: 当前异常退回尾程订单ID }
+                    expectedOrderVersion: { type: integer, minimum: 0 }
+                    palletCount: { type: integer, minimum: 1, maximum: 999 }
+                    palletType: { type: string, maxLength: 32 }
+                    assigned: { type: boolean }
+                    mergeRequired: { type: boolean }
+                    urgent: { type: boolean }
+                    remark: { type: string, maxLength: 1000 }
+      responses:
+        '200': { description: ApiResponse，data为InboundPlanResponse；creationMode为EXCEPTION_RETURN。 }
   /api/platform/v1/last-leg/dispatches/{dispatchNo}/exception-return-options:
     get:
       summary: 当前排车的原派送货物候选

lastleg-service/src/main/resources/openapi/overseas-business-v1.yaml

@@ -1,9 +1,51 @@
 openapi: 3.0.3
 info:
   title: Lastleg Overseas Business API
-  description: 派送资料完整契约见同目录 delivery-documents-v1.yaml；派送列表/详情行返回 bolNo、documentSummary（三类状态与x/3），状态仍使用 version 和 allowedActions。
+  description: 派送资料完整契约见同目录 delivery-documents-v1.yaml；散板取货和送达照片履约见 dispatch-looseboard-execution-v1.yaml。派送列表/详情行返回 bolNo、documentSummary（三类状态与x/3），状态仍使用 version 和 allowedActions。
   version: 1.0.0
 paths:
+  /api/platform/v1/last-leg/dispatches/capacity-demands/{dispatchNo}/cargo:
+    parameters:
+      - { name: dispatchNo, in: path, required: true, schema: { type: string } }
+    get:
+      summary: 读取同仓已审核散板的申报与实收候选
+      description: 需capacity-offer:list或manage以及dispatch:list权限；仅已发布且未发车的有效派送排车，候选展示真实本土散板原单号，本土散板无入仓码和集装箱号时均返回空，不以履约单号代填。审核后申报货物可先排车，无需以PDA打托为前置；不生成实收库存，实际到仓后核对实托和货量，按仓库及真实客户来源隔离。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
+        - { name: size, in: query, schema: { type: integer, minimum: 1, maximum: 50, default: 20 } }
+      responses: { '200': { description: 统一ApiResponse；data为正式排车CandidateList，含候选来源版本、目的地及资格原因 } }
+    post:
+      summary: 将已收货散板加入需求排车
+      description: 需capacity-offer:cargo-add或manage以及dispatch:edit、dispatch:list权限；复用正式AddCargo命令，校验版本、幂等、同仓及整托占用，自动刷新目的站和货量并失效审核，不执行出库拣货。
+      security: [{ bearerAuth: [] }]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/DispatchAddCargo' }
+      responses: { '200': { description: 统一ApiResponse；data为正式排车CommandResult，冲突返回业务码A0409 } }
+  /api/platform/v1/last-leg/local-looseboard-orders/{orderNo}/review:
+    post:
+      summary: 审核散板并创建唯一入仓履约单
+      description: 权限platform:overseas-business:looseboard:status；通过后送货到仓进入PDA收货，仓库上门取货进入取货排车；审核后即可从散板需求添加申报货物；上门取货沿取货排车上传取货与到仓凭证，实收到仓后原单进入PENDING_DISPATCH并交接原排车货量。客户及幂等键严格校验。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: orderNo, in: path, required: true, schema: { type: string } }
+        - { name: customerId, in: query, required: true, schema: { type: string } }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [version, decision, idempotencyKey]
+              properties:
+                version: { type: integer, minimum: 0 }
+                decision: { type: string, enum: [APPROVE, REJECT] }
+                idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+                remark: { type: string, maxLength: 1000 }
+      responses: { '200': { description: 统一ApiResponse包装的散板详情，summary.transferNo关联转运履约 } }
   /api/platform/v1/last-leg/dispatches/capacity-demands:
     get:
       summary: 读取有效派送排车的内部散板余位需求
@@ -4817,6 +4859,15 @@ components:
       description: 散板商业主单摘要；池来源附带同客户fleetArrangement，独立订单该字段为null。池来源不创建第二张占位尾程来源。
       required: [id, customerId, orderNo, origin, destination, estimatedPalletCount, packageCount, totalWeightKg, totalVolumeCbm, status, version, createdAt, updatedAt]
       properties:
+        deliveryMode: { type: string, enum: [DELIVERY_TO_WAREHOUSE, WAREHOUSE_PICKUP], description: 送货到仓或仓库上门取货 }
+        operatingWarehouseId: { type: string, description: 实际收货海外仓ID }
+        destinationType: { type: string, enum: [FBA, PRIVATE] }
+        destinationPostalCode: { type: string, maxLength: 32, nullable: true }
+        deliveryContactName: { type: string, maxLength: 128, nullable: true, description: 送货到仓必填 }
+        deliveryContactPhone: { type: string, maxLength: 64, nullable: true, description: 送货到仓必填 }
+        estimatedArrivalAt: { type: string, format: date-time, nullable: true, description: 送货到仓必填 }
+        trackingNo: { type: string, maxLength: 255, nullable: true, description: 可选物流跟踪号 }
+        transferNo: { type: string, nullable: true, description: 审核后生成的仓储转运履约单号 }
         id: { type: string, pattern: '^[0-9]+$' }
         customerId: { type: string }
         orderNo: { type: string }
@@ -5242,8 +5293,16 @@ components:
         remark: { type: string, nullable: true, maxLength: 1000 }
     LooseboardCreate:
       type: object
-      required: [originContactName, originContactPhone, destinationContactName, destinationContactPhone, pickupAt, deliveryAt, origin, destination, estimatedPalletCount, packageCount, totalWeightKg, totalVolumeCbm, idempotencyKey]
+      required: [operatingWarehouseId, deliveryMode, destinationContactName, destinationContactPhone, pickupAt, deliveryAt, destination, estimatedPalletCount, packageCount, totalWeightKg, totalVolumeCbm, idempotencyKey]
       properties:
+        deliveryMode: { type: string, enum: [DELIVERY_TO_WAREHOUSE, WAREHOUSE_PICKUP], description: 送货到仓或仓库上门取货 }
+        operatingWarehouseId: { type: string, description: 实际收货海外仓ID }
+        destinationType: { type: string, enum: [FBA, PRIVATE] }
+        destinationPostalCode: { type: string, maxLength: 32, nullable: true }
+        deliveryContactName: { type: string, maxLength: 128, nullable: true, description: 送货到仓必填 }
+        deliveryContactPhone: { type: string, maxLength: 64, nullable: true, description: 送货到仓必填 }
+        estimatedArrivalAt: { type: string, format: date-time, nullable: true, description: 送货到仓必填 }
+        trackingNo: { type: string, maxLength: 255, nullable: true, description: 可选物流跟踪号 }
         origin: { type: string, maxLength: 255 }
         originAddress: { type: string, nullable: true, maxLength: 500 }
         destination: { type: string, maxLength: 255 }
@@ -5265,8 +5324,16 @@ components:
         idempotencyKey: { type: string, maxLength: 255 }
     LooseboardUpdate:
       type: object
-      required: [originContactName, originContactPhone, destinationContactName, destinationContactPhone, pickupAt, deliveryAt, version, origin, destination, estimatedPalletCount, packageCount, totalWeightKg, totalVolumeCbm]
+      required: [operatingWarehouseId, deliveryMode, destinationContactName, destinationContactPhone, pickupAt, deliveryAt, version, destination, estimatedPalletCount, packageCount, totalWeightKg, totalVolumeCbm]
       properties:
+        deliveryMode: { type: string, enum: [DELIVERY_TO_WAREHOUSE, WAREHOUSE_PICKUP], description: 送货到仓或仓库上门取货 }
+        operatingWarehouseId: { type: string, description: 实际收货海外仓ID }
+        destinationType: { type: string, enum: [FBA, PRIVATE] }
+        destinationPostalCode: { type: string, maxLength: 32, nullable: true }
+        deliveryContactName: { type: string, maxLength: 128, nullable: true, description: 送货到仓必填 }
+        deliveryContactPhone: { type: string, maxLength: 64, nullable: true, description: 送货到仓必填 }
+        estimatedArrivalAt: { type: string, format: date-time, nullable: true, description: 送货到仓必填 }
+        trackingNo: { type: string, maxLength: 255, nullable: true, description: 可选物流跟踪号 }
         version: { type: integer, format: int64, minimum: 0 }
         origin: { type: string, maxLength: 255 }
         originAddress: { type: string, nullable: true, maxLength: 500 }