提交

firstleg/src/main/resources/openapi/firstleg-v1.yaml

@@ -355,7 +355,7 @@ paths:
   /internal/firstleg/v1/inbounds/unified-orders/workbench-filters:
     post:
       summary: 查询单一客户工作台履约筛选标识（Order内部）
-      description: 只读返回命中状态、最新待确认费用及待上传资料的订单标识。客户必须明确且为正数；不创建报关聚合，不跨Schema读取。传入orderIds为精确进度模式，仅计算progress，matchingStatusOrderIds为null，feeOrderIds和customsOrderIds为空；mainStatus在该模式不参与查询。
+      description: 只读返回命中状态、待独立确认计费重及待上传报关资料的订单标识。feeOrderIds沿用既有字段名，值为尚未确认当前计费重的订单，不代表金额确认。客户必须明确且为正数；不创建报关聚合，不跨Schema读取。传入orderIds为精确进度模式，仅计算progress，matchingStatusOrderIds为null，feeOrderIds和customsOrderIds为空；mainStatus在该模式不参与查询。
       security: [{internalServiceToken: []}]
       requestBody:
         required: true
@@ -366,7 +366,7 @@ paths:
               required: [tenantId]
               properties:
                 tenantId: {type: integer, format: int64, minimum: 1}
-                mainStatus: {type: string, nullable: true, enum: [WAIT_MEASURE, WAIT_PALLETIZE, WAIT_SPLIT, LOADING, LOADED, DELIVERED]}
+                mainStatus: {type: string, nullable: true, enum: [WAIT_MEASURE, WAIT_PALLETIZE, WAIT_SPLIT, LOADING, LOADED, DELIVERED, WAIT_WEIGHT_CONFIRM, WEIGHT_CONFIRMED, WAIT_CUSTOMS_DOCS, EXPORT_CUSTOMS, SAILING_CLEARANCE, WAIT_UNLOAD, WAIT_DISPATCH, OUTBOUND_DOCUMENT, DELIVERING, SIGNED, MEASUREMENT_REVIEW]}
                 orderIds:
                   type: array
                   nullable: true
@@ -388,7 +388,7 @@ paths:
                     required: [feeOrderIds, customsOrderIds, progress]
                     properties:
                       matchingStatusOrderIds: {type: array, nullable: true, items: {type: integer, format: int64}}
-                      feeOrderIds: {type: array, items: {type: integer, format: int64}}
+                      feeOrderIds: {type: array, description: 待客户独立确认当前计费重的订单ID, items: {type: integer, format: int64}}
                       customsOrderIds: {type: array, items: {type: integer, format: int64}}
                       progress:
                         type: array
@@ -401,6 +401,47 @@ paths:
                             stage: {type: string, enum: [loaded, declared, cleared]}
                             partial: {type: boolean}
 
+  /internal/firstleg/v1/inbounds/unified-orders/status-summaries:
+    post:
+      summary: 当前页订单按原筛选读取履约摘要（Order 内部）
+      description: candidateOrderIds 必须提供且最多200项；保留统一筛选，避免读到不匹配的其他入库分片。
+      security: [{internalServiceToken: []}]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/UnifiedInboundQuery'}
+      responses:
+        '200':
+          description: 标准 ApiResponse，data 为 UnifiedInboundSummary 数组
+  /internal/firstleg/v1/inbounds/unified-orders/status-rows:
+    post:
+      summary: 统一订单筛选后的轻量状态投影（Order 内部）
+      description: 非分页查询，共享统一履约筛选；按创建时间和ID降序排列，同一订单同一主状态去重，保留不同分片主状态，不查询逐票详情。调用方不传mainStatus。
+      security: [{internalServiceToken: []}]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/UnifiedInboundQuery'}
+      responses:
+        '200':
+          description: 标准 ApiResponse；依赖失败不能返回空成功
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code: {type: string}
+                  data:
+                    type: array
+                    items:
+                      type: object
+                      required: [tenantId, orderId]
+                      properties:
+                        tenantId: {type: string}
+                        orderId: {type: string}
+                        mainStatus: {type: string, nullable: true}
   /internal/firstleg/v1/inbounds/unified-orders/query:
     post:
       summary: 按统一订单条件分页查询履约摘要（Order 内部）
@@ -594,13 +635,13 @@ paths:
   /api/platform/v1/containers/{id}/clearance:
     get:
       summary: 查询货柜目的港清关资料
-      description: 需要 platform:firstleg:terminal-drayage:list 权限；仅国外工作台货柜
+      description: 需要 platform:firstleg:terminal-drayage:list 权限；有效货柜已确认国内离仓，或已记录 DEPARTED_ORIGIN_PORT 且 actual_at 非空时可读取；人工与拉取节点使用相同事实
       parameters: [{$ref: '#/components/parameters/ContainerBookingId'}]
       responses: {'200': {description: 成功或货柜不存在}}
   /api/platform/v1/containers/{id}/clearance/document:
     post:
       summary: 上传或替换货柜目的港清关资料
-      description: 需要 platform:firstleg:terminal-drayage:document:edit 权限，fileId 必须严格绑定当前货柜
+      description: 需要 platform:firstleg:terminal-drayage:document:edit 权限；有效货柜已离仓或已实际开船，fileId 必须严格绑定当前货柜
       parameters: [{$ref: '#/components/parameters/ContainerBookingId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
       requestBody:
         required: true
@@ -609,7 +650,7 @@ paths:
   /api/platform/v1/containers/{id}/clearance/document/{fileId}/download:
     get:
       summary: 下载货柜目的港清关附件
-      description: 需要 platform:firstleg:terminal-drayage:list 权限；服务端校验当前 DESTINATION_CLEARANCE fileId 及 File 业务归属，完成态仍可下载，响应禁止缓存
+      description: 需要 platform:firstleg:terminal-drayage:list 权限；有效货柜已离仓或已实际开船；服务端校验当前 DESTINATION_CLEARANCE fileId 及 File 业务归属，完成态仍可下载，响应禁止缓存
       parameters:
         - {$ref: '#/components/parameters/ContainerBookingId'}
         - {name: fileId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
@@ -619,7 +660,7 @@ paths:
   /api/platform/v1/containers/{id}/clearance/document/upload:
     post:
       summary: 直接选择文件上传或替换货柜目的港清关资料
-      description: 需要 platform:firstleg:terminal-drayage:document:edit；Firstleg 使用内部服务令牌上传 File，浏览器不得传递 fileId 或内部令牌。
+      description: 需要 platform:firstleg:terminal-drayage:document:edit；有效货柜已离仓或已实际开船；Firstleg 使用内部服务令牌上传 File，浏览器不得传递 fileId 或内部令牌。上传成功即作为待拆柜的资料事实，不要求另行确认清关完成。
       parameters: [{$ref: '#/components/parameters/ContainerBookingId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
       requestBody:
         required: true
@@ -630,7 +671,7 @@ paths:
   /api/platform/v1/containers/{id}/clearance/complete:
     post:
       summary: 点击完成目的港清关
-      description: 需要 platform:firstleg:terminal-drayage:document:edit 权限
+      description: 需要 platform:firstleg:terminal-drayage:document:edit 权限；有效货柜已离仓或已实际开船；此完成动作不作为上传后进入待拆柜的附加条件
       parameters: [{$ref: '#/components/parameters/ContainerBookingId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
       requestBody:
         required: true
@@ -1631,9 +1672,9 @@ components:
         orderNo: {type: string, maxLength: 64, nullable: true}
         mainStatus:
           type: string
-          enum: [PENDING_REVIEW, WAIT_MEASURE, WAIT_PALLETIZE, WAIT_SPLIT, LOADING, LOADED, DELIVERED]
+          enum: [PENDING_REVIEW, WAIT_MEASURE, WAIT_PALLETIZE, WAIT_SPLIT, LOADING, LOADED, DELIVERED, WAIT_WEIGHT_CONFIRM, WEIGHT_CONFIRMED, WAIT_CUSTOMS_DOCS, EXPORT_CUSTOMS, SAILING_CLEARANCE, WAIT_UNLOAD, WAIT_DISPATCH, OUTBOUND_DOCUMENT, DELIVERING, SIGNED, MEASUREMENT_REVIEW]
           nullable: true
-          description: WAIT_SPLIT 为唯一待分柜筛选值
+          description: WAIT_SPLIT 为唯一待分柜筛选值；WAIT_CUSTOMS_DOCS 为实际装柜后缺少本票客户报关资料；EXPORT_CUSTOMS 按本票资料已上传且实际装柜完成汇总，买单无需客户退税资料，不依赖点击开始报关，实际开船后移出；SAILING_CLEARANCE 按手动或拉取的实际离港节点进入，清关资料上传后进入 WAIT_UNLOAD，实际卸柜完成后移出。
         customerId: {type: integer, format: int64, nullable: true}
         receivingWarehouseId: {type: integer, format: int64, nullable: true}
         destinationWarehouseId: {type: integer, format: int64, nullable: true}

firstleg/src/main/resources/openapi/order-workflow-v1.yaml

@@ -0,0 +1,64 @@
+openapi: 3.0.3
+info: {title: 客户独立计费重确认, version: 1.0.0}
+security: [{bearerAuth: []}]
+paths:
+  /api/merchant/v1/first-leg/orders/{orderId}/chargeable-weights:
+    get:
+      summary: 客户读取本票全部独立入仓计费重
+      description: 认证客户隔离，要求merchant:order:view；仅返回测量审核通过且计费重为正的分片。
+      parameters:
+        - {name: orderId, in: path, required: true, schema: {type: integer, format: int64}}
+      responses:
+        '200':
+          description: 标准ApiResponse，认证客户无可确认来源时返回空数组
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code: {type: string, example: '200'}
+                  message: {type: string}
+                  data:
+                    type: array
+                    items: {$ref: '#/components/schemas/Weight'}
+  /api/merchant/v1/first-leg/chargeable-weights/{inboundId}/confirm:
+    post:
+      summary: 客户独立确认当前计费重
+      description: 要求merchant:order:edit。与费用金额确认独立；值或测量轮次变化后旧确认失效。客户范围取认证主体。
+      parameters:
+        - {name: inboundId, in: path, required: true, schema: {type: integer, format: int64}}
+        - {name: Idempotency-Key, in: header, required: true, schema: {type: string, maxLength: 128}}
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [expectedFingerprint]
+              properties:
+                expectedFingerprint: {type: string, pattern: '^[a-f0-9]{64}$'}
+      responses:
+        '200':
+          description: 标准ApiResponse；版本或异参冲突返回业务冲突码，不改变费用状态
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code: {type: string, example: '200'}
+                  message: {type: string}
+                  data: {$ref: '#/components/schemas/Weight'}
+components:
+  securitySchemes:
+    bearerAuth: {type: http, scheme: bearer, bearerFormat: JWT}
+  schemas:
+    Weight:
+      type: object
+      required: [inboundId, orderId, chargeableWeightKg, fingerprint, confirmed]
+      properties:
+        inboundId: {type: string, description: 独立来源入仓单ID}
+        orderId: {type: string, description: 独立订单ID}
+        chargeableWeightKg: {type: number}
+        fingerprint: {type: string}
+        confirmed: {type: boolean}
+        confirmedAt: {type: string, format: date-time, nullable: true}