Merge branch 'dev-lyhfive' of http://git.buggoglobal.com/java-project/baiyue-firstleg into dev

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

@@ -167,6 +167,89 @@ paths:
         - { name: createdFrom, in: query, schema: { type: string, format: date-time } }
         - { name: createdTo, in: query, schema: { type: string, format: date-time } }
       responses: { '200': { description: 统一 ApiResponse 包装的尾程订单分页；列表行 destinationType 为 FBA 或 OVERSEAS } }
+  /api/platform/v1/last-leg/orders/{id}:
+    get:
+      summary: 查询尾程订单详情
+      description: 权限 platform:overseas-warehouse:last-mile-order:list；返回订单、货物、状态历史、费用明细和操作记录。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: integer, format: int64 } }
+        - { name: customerId, in: query, required: false, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
+      responses:
+        '200': { description: 统一 ApiResponse 包装的尾程订单详情 }
+        '404': { description: 尾程订单不存在或不属于查询客户 }
+  /api/platform/v1/last-leg/orders/{id}/fees:
+    post:
+      summary: 新增尾程订单费用
+      description: 权限 platform:overseas-warehouse:last-mile-order:edit；在订单客户范围内新增费用并记录操作人和处理结果。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: integer, format: int64 } }
+        - { name: customerId, in: query, required: false, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
+      requestBody:
+        required: true
+        content: { application/json: { schema: { $ref: '#/components/schemas/LastMileFeeCreate' } } }
+      responses:
+        '200': { description: 新增后的费用明细, content: { application/json: { schema: { $ref: '#/components/schemas/LastMileFeeApiResponse' } } } }
+        '404': { description: 尾程订单不存在或不属于操作客户 }
+  /api/platform/v1/last-leg/orders/{id}/detained:
+    put:
+      summary: 设置或解除尾程订单暂扣
+      description: 权限 platform:overseas-warehouse:last-mile-order:edit；库存同步转入或释放暂扣，并通过跨区事件回写国内入仓单。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: integer, format: int64 } }
+        - { name: customerId, in: query, required: false, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [detained, remark]
+              properties:
+                detained: { type: boolean }
+                remark: { type: string, minLength: 1, maxLength: 500 }
+      responses: { '200': { description: 暂扣状态已更新 } }
+  /api/platform/v1/last-leg/orders/{id}/pallet-merge-required:
+    put:
+      summary: 设置尾程订单合托标记
+      description: 权限 platform:overseas-warehouse:last-mile-order:edit；标记后 PDA 扫描本单箱唛时返回合托提示；实际完成合托后不可取消。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: integer, format: int64 } }
+        - { name: customerId, in: query, required: false, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [palletMergeRequired]
+              properties: { palletMergeRequired: { type: boolean } }
+      responses: { '200': { description: 合托标记已更新 }, '409': { description: 已完成实际合托，不能修改标记 } }
+  /api/platform/v1/last-leg/orders/pallet-merge-required/batch:
+    put:
+      summary: 批量设置同组合托标记
+      description: 权限 platform:overseas-warehouse:last-mile-order:edit；所选订单按同一合托批次原子标记或取消。
+      security: [{ bearerAuth: [] }]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [orderIds, palletMergeRequired]
+              properties:
+                orderIds: { type: array, minItems: 1, uniqueItems: true, items: { type: integer, format: int64 } }
+                palletMergeRequired: { type: boolean }
+      responses: { '200': { description: 批量合托标记已更新 } }
+  /api/platform/v1/last-leg/orders/export:
+    get:
+      summary: 导出筛选后的尾程订单
+      description: 权限 platform:overseas-warehouse:last-mile-order:export；筛选参数与列表一致，返回 UTF-8 CSV。
+      security: [{ bearerAuth: [] }]
+      responses: { '200': { description: CSV 文件, content: { text/csv: { schema: { type: string, format: binary } } } } }
   /api/platform/v1/last-leg/orders/container-summaries:
     get:
       summary: 分页查询柜级入库计划进度
@@ -762,6 +845,37 @@ components:
         planStatus: { type: string, nullable: true }
         planValid: { type: boolean }
         plannedArrivalAt: { type: string, format: date-time, nullable: true, description: ll_order.estimated_warehouse_at }
+    LastMileFeeCreate:
+      type: object
+      required: [feeItem, currency, amount, status]
+      properties:
+        feeItem: { type: string, minLength: 1, maxLength: 128 }
+        currency: { type: string, pattern: '^[A-Z]{3}$', example: USD }
+        amount: { type: number, format: decimal, minimum: 0.01 }
+        status: { type: string, enum: [PENDING_REVIEW, APPROVED, REJECTED] }
+        supplierDescription: { type: string, maxLength: 500 }
+    LastMileFee:
+      type: object
+      required: [id, customerId, orderId, feeItem, currency, amount, status, createdBy, createdAt, updatedAt]
+      properties:
+        id: { type: integer, format: int64 }
+        customerId: { type: string }
+        orderId: { type: integer, format: int64 }
+        feeItem: { type: string }
+        currency: { type: string }
+        amount: { type: number, format: decimal }
+        status: { type: string }
+        supplierDescription: { type: string, nullable: true }
+        createdBy: { type: string }
+        createdAt: { type: string, format: date-time }
+        updatedAt: { type: string, format: date-time }
+    LastMileFeeApiResponse:
+      type: object
+      required: [code, message, data]
+      properties:
+        code: { type: string }
+        message: { type: string }
+        data: { $ref: '#/components/schemas/LastMileFee' }
     PdaWarehouseScan:
       type: object
       required: [code]
@@ -906,7 +1020,7 @@ components:
         timestamp: { type: string, format: date-time }
     ReceivingInbound:
       type: object
-      required: [inboundCode, destinationType, plannedPalletCount, totalPackages, receivedPackages, pendingPackages]
+      required: [inboundCode, destinationType, plannedPalletCount, totalPackages, receivedPackages, pendingPackages, palletMergeRequired]
       properties:
         inboundCode: { type: string }
         destinationType: { type: string, enum: [FBA, OVERSEAS] }
@@ -920,6 +1034,8 @@ components:
         totalPackages: { type: integer }
         receivedPackages: { type: integer }
         pendingPackages: { type: integer }
+        palletMergeRequired: { type: boolean, description: 尾程订单是否要求PDA合托提醒 }
+        palletMergeHint: { type: string, nullable: true, description: 标记合托时供PDA直接展示的中文提示 }
     ReceivingWarehouseProfile:
       type: object
       required: [warehouseId, warehouseCode, warehouseName]
@@ -996,7 +1112,7 @@ components:
         compatible: { type: boolean }
     ReceivingReceipt:
       type: object
-      required: [result, containerNo, inboundCode, destinationType, palletCode, acceptedPackages, receivedPackages, pendingPackages, sessionStatus]
+      required: [result, containerNo, inboundCode, destinationType, palletCode, acceptedPackages, receivedPackages, pendingPackages, sessionStatus, palletMergeRequired]
       properties:
         result: { type: string }
         containerNo: { type: string }
@@ -1007,6 +1123,8 @@ components:
         receivedPackages: { type: integer }
         pendingPackages: { type: integer }
         sessionStatus: { type: string, enum: [SIGNED, RECEIVING] }
+        palletMergeRequired: { type: boolean }
+        palletMergeHint: { type: string, nullable: true }
     ReceivingCandidateListApiResponse:
       allOf:
         - { $ref: '#/components/schemas/ReceivingApiResponseBase' }
@@ -1256,6 +1374,19 @@ components:
         overseasTrackingNo: { $ref: '#/components/schemas/NullableTextPatch' }
         estimatedArrivalAt: { type: string, format: date-time, nullable: true, description: 缺失不修改；null 或空串清空 }
         remark: { $ref: '#/components/schemas/NullableTextPatch' }
+        outboundDetails:
+          type: array
+          description: 出库明细，可一次提交多条；总出库量不得超过入库量
+          items:
+            type: object
+            required: [quantity]
+            properties:
+              id: { type: string }
+              quantity: { type: integer, format: int64, minimum: 0 }
+              carrier: { type: string, nullable: true, maxLength: 128 }
+              trackingNo: { type: string, nullable: true, maxLength: 128 }
+              shippedAt: { type: string, format: date-time, nullable: true }
+              remark: { type: string, nullable: true, maxLength: 500 }
     CustomerOptionResponse:
       type: object
       properties: