提交

lastleg-service/src/main/resources/openapi/fleet-operations-v1.yaml

@@ -13,7 +13,7 @@
   "paths": {
     "/api/platform/v1/last-leg/fleet/operations": {
       "get": {
-        "description": "platform:fleet:operations:list；一次查询返回分页与全范围汇总",
+        "description": "platform:fleet:operations:list；一次查询返回分页与全范围汇总。纯散板照片直送按LOOSEBOARD_DELIVERING不可变历史的实际发运箱数统计，要求已有实际发车时间且未发生仓内拣货或装车；实托和标准托位保持null，不以申报托数补齐。普通仓内出车仍要求DEPART实载快照。",
         "parameters": [
           {
             "name": "page",

lastleg-service/src/main/resources/openapi/order-budgets-v1.yaml

@@ -2,17 +2,17 @@ openapi: 3.0.3
 info:
   title: 海外客户下单预估资金校验
   version: 1.0.0
-  description: 客户订单先原子落库并进入资金处理中，资金冻结通过Outbox异步执行。冻结成功后进入待审核，失败进入资金失败并可在原订单上重试；平台仅可审核待审核订单。余额优先、授信补足及不足判断由Finance原子执行；本服务不自行修改钱包。预算预占、订单和冻结指令在同一事务内写入，订单终态释放。
+  description: 客户订单先原子落库并进入资金处理中，资金冻结通过Outbox异步执行。冻结成功后进入待审核，失败进入资金失败并可在原订单上重试；平台仅可审核待审核订单。余额优先、授信补足及不足判断由Finance原子执行；本服务不自行修改钱包。预算预占、订单和冻结指令在同一事务内写入，审核通过立即申请释放原预算，取消、驳回或终态同样释放；释放失败自动重试。散板冻结成功进入PENDING_ACCEPTANCE，失败进入FUNDING_FAILED。
 security:
   - bearerAuth: []
 paths:
   /api/merchant/v1/last-leg/order-budgets/{kind}/{key}:
     parameters:
-      - {name: kind, in: path, required: true, schema: {type: string, enum: [procurement, trucking]}}
+      - {name: kind, in: path, required: true, schema: {type: string, enum: [procurement, trucking, looseboard]}}
       - {name: key, in: path, required: true, schema: {type: string, minLength: 1, maxLength: 128}}
     post:
       summary: 兼容接口：发起或读取预算冻结请求
-      description: 客户身份仅来自认证。procurement需要merchant:cross-border:procurement:create，trucking需要merchant:cross-border:domestic-trucking:create；权限不能交叉使用。采购金额是预算单价乘采购数量，免费样品零金额不发资金指令；卡车金额必须大于0。重试禁止更改金额或币种。
+      description: 客户身份仅来自认证。procurement需要merchant:cross-border:procurement:create，trucking需要merchant:cross-border:domestic-trucking:create，looseboard需要merchant:cross-border:pallet-shipping:create；权限不能交叉使用。采购金额是预算单价乘采购数量，免费样品零金额不发资金指令；卡车金额必须大于0。重试禁止更改金额或币种。
       requestBody:
         required: true
         content:
@@ -34,16 +34,16 @@ paths:
         '403': {description: 身份或业务创建权限不足}
   /api/merchant/v1/last-leg/order-budgets/{kind}/orders/{orderNo}:
     parameters:
-      - {name: kind, in: path, required: true, schema: {type: string, enum: [procurement, trucking]}}
+      - {name: kind, in: path, required: true, schema: {type: string, enum: [procurement, trucking, looseboard]}}
       - {name: orderNo, in: path, required: true, schema: {type: string, minLength: 1, maxLength: 128}}
     get:
       summary: 读取订单资金状态
-      description: 仅当前客户可读。FUNDING_PENDING期间客户端可短暂轮询；FUNDING_FAILED展示失败原因并允许重试。只有PENDING_REVIEW允许平台审核。
+      description: 仅当前客户可读。FUNDING_PENDING期间客户端可短暂轮询；FUNDING_FAILED展示失败原因并允许重试。采购和卡车只有PENDING_REVIEW、散板只有PENDING_ACCEPTANCE且资金已冻结才允许平台审核。读取订单资金状态分别要求对应业务list权限，重试要求对应create权限。
       responses:
         '200': {$ref: '#/components/responses/Result'}
   /api/merchant/v1/last-leg/order-budgets/{kind}/orders/{orderNo}/retry:
     parameters:
-      - {name: kind, in: path, required: true, schema: {type: string, enum: [procurement, trucking]}}
+      - {name: kind, in: path, required: true, schema: {type: string, enum: [procurement, trucking, looseboard]}}
       - {name: orderNo, in: path, required: true, schema: {type: string, minLength: 1, maxLength: 128}}
     post:
       summary: 重试订单资金冻结

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

@@ -28,7 +28,7 @@ paths:
   /api/platform/v1/last-leg/local-looseboard-orders/{orderNo}/review:
     post:
       summary: 审核散板并创建唯一入仓履约单
-      description: 权限platform:overseas-business:looseboard:status；通过后送货到仓进入PDA收货，仓库上门取货进入取货排车；审核后即可从散板需求添加申报货物；上门取货沿取货排车上传取货与到仓凭证，实收到仓后原单进入PENDING_DISPATCH并交接原排车货量。客户及幂等键严格校验。
+      description: 权限platform:overseas-business:looseboard:status；仅冻结成功可通过审核，通过和驳回均释放原预算预占；通过后送货到仓进入PDA收货，仓库上门取货进入取货排车；审核后即可从散板需求添加申报货物；上门取货沿取货排车上传取货与到仓凭证，实收到仓后原单进入PENDING_DISPATCH并交接原排车货量。客户及幂等键严格校验。
       security: [{ bearerAuth: [] }]
       parameters:
         - { name: orderNo, in: path, required: true, schema: { type: string } }
@@ -2754,20 +2754,20 @@ paths:
   /api/merchant/v1/last-leg/local-looseboard-orders:
     get:
       summary: 客户分页查询自己的本土散板订单
-      description: 权限 merchant:cross-border:pallet-shipping:list；客户范围只取认证 Token，不接收 customerId。
+      description: 权限 merchant:cross-border:pallet-shipping:list；客户范围只取认证 Token，不接收 customerId；状态筛选、分页计数和显示共用真实运输进度。PENDING_ACCEPTANCE 为待审核，审核通过尚未排车为 PENDING_DISPATCH（待排车）；已排车待取货为 DISPATCHED；取货到仓车次出发或已取货未到仓为 PICKING_UP（取货中），到仓后等待后续排车；直接取货送货取货完成后为 IN_TRANSIT（派送中）。内部收货与合托状态不作为客户筛选项。
       security: [{ bearerAuth: [] }]
       parameters:
         - { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
         - { name: size, in: query, schema: { type: integer, minimum: 1, maximum: 200, default: 20 } }
         - { name: orderNo, in: query, schema: { type: string } }
         - { name: routeKeyword, in: query, schema: { type: string } }
-        - { name: status, in: query, schema: { $ref: '#/components/schemas/LooseboardStatus' } }
+        - { name: status, in: query, schema: { $ref: '#/components/schemas/MerchantLooseboardStatus' } }
         - { name: requestedFrom, in: query, schema: { type: string, format: date } }
         - { name: requestedTo, in: query, schema: { type: string, format: date } }
       responses: { '200': { description: 当前客户本土散板订单分页, content: { application/json: { schema: { $ref: '#/components/schemas/LooseboardPageResponse' } } } } }
     post:
       summary: 客户创建本土散板订单
-      description: 权限 merchant:cross-border:pallet-shipping:create；新单固定进入 PENDING_ACCEPTANCE，客户不能调用平台状态推进端点。
+      description: 权限 merchant:cross-border:pallet-shipping:create；散板金额必填，预算与订单和冻结指令同事务保存；新单进入 FUNDING_PENDING，Finance按余额优先、授信补足冻结，成功进入 PENDING_ACCEPTANCE，失败进入 FUNDING_FAILED，支持原单重试。审核通过、取消或驳回申请释放预占，不自动扣款；客户不能调用平台状态推进端点。
       security: [{ bearerAuth: [] }]
       requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/LooseboardCreate' } } } }
       responses: { '200': { description: 本土散板订单详情, content: { application/json: { schema: { $ref: '#/components/schemas/LooseboardDetailResponse' } } } }, '409': { description: 幂等冲突 } }
@@ -2775,12 +2775,12 @@ paths:
     parameters: [{ name: orderNo, in: path, required: true, schema: { type: string } }]
     get:
       summary: 客户查询自己的本土散板订单详情
-      description: 权限 merchant:cross-border:pallet-shipping:list；不泄露其他客户订单。
+      description: 权限 merchant:cross-border:pallet-shipping:list；不泄露其他客户订单；summary.status 使用 MerchantLooseboardStatus，与列表运输状态及筛选一致。
       security: [{ bearerAuth: [] }]
       responses: { '200': { description: 当前客户本土散板订单详情, content: { application/json: { schema: { $ref: '#/components/schemas/LooseboardDetailResponse' } } } }, '404': { description: 当前客户下订单不存在 } }
     put:
-      summary: 客户编辑待接单的本土散板订单
-      description: 权限 merchant:cross-border:pallet-shipping:edit；仅 PENDING_ACCEPTANCE 可编辑，version 必填；不能修改状态。
+      summary: 客户编辑待审核的本土散板订单
+      description: 权限 merchant:cross-border:pallet-shipping:edit；仅 PENDING_ACCEPTANCE 可编辑，version 必填；已冻结的预算金额与币种不能通过编辑更改；不能修改状态。
       security: [{ bearerAuth: [] }]
       requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/LooseboardUpdate' } } } }
       responses: { '200': { description: 更新后的订单详情, content: { application/json: { schema: { $ref: '#/components/schemas/LooseboardDetailResponse' } } } }, '409': { description: 版本或状态冲突 } }
@@ -4897,7 +4897,11 @@ components:
         destinationContactPhone: { type: string, nullable: true }
         pickupAt: { type: string, format: date-time, nullable: true, description: 当地日期时间不带时区；按分钟输入 }
         deliveryAt: { type: string, format: date-time, nullable: true, description: 当地日期时间，不能早于取货时间 }
-        status: { $ref: '#/components/schemas/LooseboardStatus' }
+        status:
+          description: 客户读取为运输状态 MerchantLooseboardStatus，平台读取保留内部作业状态 LooseboardStatus。
+          anyOf:
+            - { $ref: '#/components/schemas/LooseboardStatus' }
+            - { $ref: '#/components/schemas/MerchantLooseboardStatus' }
         version: { type: integer, format: int64 }
         createdAt: { type: string, format: date-time }
         updatedAt: { type: string, format: date-time }
@@ -5292,7 +5296,11 @@ components:
         pickupAt: { type: string, format: date-time, description: '取货日期时分，使用无偏移量的本地时间，不转换时区' }
         deliveryAt: { type: string, format: date-time, description: '送货日期时分，不能早于取货时间，不转换时区' }
         remark: { type: string, nullable: true, maxLength: 1000 }
-    LooseboardStatus: { type: string, enum: [PENDING_ACCEPTANCE, WAITING_INBOUND, RECEIVING, WAITING_CONSOLIDATION, PENDING_DISPATCH, DISPATCHED, IN_TRANSIT, COMPLETED, CANCELLED] }
+    LooseboardStatus: { type: string, enum: [FUNDING_PENDING, FUNDING_FAILED, PENDING_ACCEPTANCE, WAITING_INBOUND, RECEIVING, WAITING_CONSOLIDATION, PENDING_DISPATCH, DISPATCHED, IN_TRANSIT, COMPLETED, CANCELLED] }
+    MerchantLooseboardStatus:
+      type: string
+      description: 订单受理中、订单处理失败、待审核、待排车、待取货、取货中、派送中、已完成、已取消；只读运输进度，不作为平台状态推进命令。
+      enum: [FUNDING_PENDING, FUNDING_FAILED, PENDING_ACCEPTANCE, PENDING_DISPATCH, DISPATCHED, PICKING_UP, IN_TRANSIT, COMPLETED, CANCELLED]
     LooseboardStatusChange:
       type: object
       required: [version, status, idempotencyKey]
@@ -5303,7 +5311,7 @@ components:
         remark: { type: string, nullable: true, maxLength: 1000 }
     LooseboardCreate:
       type: object
-      required: [operatingWarehouseId, deliveryMode, destinationContactName, destinationContactPhone, pickupAt, deliveryAt, destination, estimatedPalletCount, packageCount, totalWeightKg, totalVolumeCbm, idempotencyKey]
+      required: [operatingWarehouseId, deliveryMode, destinationContactName, destinationContactPhone, pickupAt, deliveryAt, destination, estimatedPalletCount, packageCount, totalWeightKg, totalVolumeCbm, budgetAmount, idempotencyKey]
       properties:
         deliveryMode: { type: string, enum: [DELIVERY_TO_WAREHOUSE, WAREHOUSE_PICKUP], description: 送货到仓或仓库上门取货 }
         operatingWarehouseId: { type: string, description: 实际收货海外仓ID }
@@ -5322,7 +5330,7 @@ components:
         packageCount: { type: integer, minimum: 0 }
         totalWeightKg: { type: number, minimum: 0 }
         totalVolumeCbm: { type: number, minimum: 0 }
-        budgetAmount: { type: number, nullable: true, minimum: 0 }
+        budgetAmount: { type: number, minimum: 0, multipleOf: 0.01 }
         currency: { type: string, minLength: 3, maxLength: 3, default: USD }
         originContactName: { type: string, minLength: 1, maxLength: 128 }
         originContactPhone: { type: string, minLength: 1, maxLength: 128 }