优化

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

@@ -566,8 +566,8 @@ paths:
         由稳定的 item.id（measurementItemId）与 intelligentImageFileId 关联；称重图片只随
         weightResults 返回，由稳定的 weightResult.id 与 fileId 关联，并携带确认状态及服务端确认的
         grossWeightKg/netWeightKg。两类证据不得合并为无明细归属的统一图片列表。
-        actualGrossWeightKg 是服务端权威的货物总重量；存在已确认称重结果时为所有已确认
-        netWeightKg 之和，消费者不得根据图片或 OCR 值自行重算。
+        actualGrossWeightKg 是服务端确认后的实测毛重，actualNetWeightKg 是扣除托盘皮重后的货物净重；
+        两者语义独立，消费者不得互相回退，也不得根据图片或 OCR 值自行重算。
       parameters:
         - {name: tenantId, in: query, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
         - {name: inboundId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
@@ -578,6 +578,23 @@ paths:
             application/json:
               schema: {$ref: '#/components/schemas/InboundMeasurementDetailEnvelope'}
         '403': {description: 无入库测量查看权限}
+  /api/platform/v1/first-leg/inbounds/{inboundId}/measurement/draft:
+    put:
+      summary: 保存测量草稿
+      description: >-
+        原单据号码、申报毛重和申报体积由服务端从客户订单生成快照，客户端不得提交覆盖；
+        actualGoodsName 默认使用客户货物品名汇总，但允许测量人员修正。
+      parameters:
+        - {name: tenantId, in: query, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+        - {name: inboundId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/InboundMeasurementSaveDraftRequest'}
+      responses:
+        '200': {description: 成功或业务失败，按响应体 code 判断}
+        '403': {description: 无测量编辑权限}
   /api/platform/v1/first-leg/inbounds/{inboundId}/measurement/carton-scans:
     post:
       summary: 平台模拟单箱设备扫描
@@ -697,7 +714,7 @@ paths:
         platform:firstleg:inbound:weight:edit 权限。修改与确认在同一事务内完成，保留 OCR 原值，
         分别写入 CORRECT 和 CONFIRM 修订记录。输入表示含托盘毛重；服务端统一换算为 KG，
         使用创建时固化的托盘皮重计算 netWeightKg，且毛重必须大于皮重。
-        入库单 actualGrossWeightKg 明确保留为下游货物实际毛重字段，值汇总所有已确认 netWeightKg。
+        入库单 actualGrossWeightKg 为实测毛重；actualNetWeightKg 为扣除托盘皮重后的货物净重，两者不得混用。
       parameters:
         - {name: tenantId, in: query, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
         - {name: inboundId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
@@ -749,7 +766,7 @@ paths:
       summary: 删除称重图片及重量结果
       description: >-
         需要 platform:firstleg:inbound:weight:edit 权限；仅允许在可编辑的测量状态删除。
-        删除已确认图片后重新汇总剩余已确认图片的净重，删除最后一张时 actualGrossWeightKg 恢复为空。
+        删除已确认图片后由生产者分别重算剩余确认称重的毛重、净重；消费端不得用净重填充毛重。
       parameters:
         - {name: tenantId, in: query, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
         - {name: version, in: query, required: true, schema: {type: integer, format: int32, minimum: 0}}
@@ -779,15 +796,6 @@ paths:
                 reason: {type: string, maxLength: 1000}
       responses:
         '200': {description: 成功或业务失败，按响应体 code 判断；审核成功 data.processStatus 固定为 WAIT_SPLIT，initialPricingSucceeded 表示是否同时生成初算费用，初算失败时 feeStatus=UNPRICED 且主流程仍成功}
-  /api/platform/v1/inbounds/{inboundId}/measurements/reject:
-    post:
-      summary: 驳回测量
-      description: 需要 firstleg:inbound:measurement-review 权限；只退回测量数据修改，已确认托盘和库位占用保持不动。
-      parameters:
-        - {name: inboundId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
-        - {name: Idempotency-Key, in: header, required: true, schema: {type: string}}
-      responses:
-        '200': {description: 成功或业务失败}
   /api/platform/v1/inbounds/{inboundId}/measurements/submit:
     post:
       summary: 提交测量完成
@@ -811,15 +819,6 @@ paths:
             application/json:
               schema: {$ref: '#/components/schemas/MerchantInboundBillingEnvelope'}
         '403': {description: 非当前客户或无订单查看权限}
-  /api/platform/v1/inbounds/{inboundId}/measurements/exception-release:
-    post:
-      summary: 测量异常放行
-      description: 需要 firstleg:inbound:exception-release 权限
-      parameters:
-        - {name: inboundId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
-        - {name: Idempotency-Key, in: header, required: true, schema: {type: string}}
-      responses:
-        '200': {description: 成功或业务失败}
 components:
   securitySchemes:
     bearerAuth:
@@ -1035,8 +1034,8 @@ components:
         currentHoldReason: {type: string, nullable: true}
         totalPackageCount: {type: integer, nullable: true}
         locationCodes: {type: string, nullable: true}
-        actualGrossWeightKg: {type: number, nullable: true, multipleOf: 0.001, description: 服务端权威货物总重量 KG；存在已确认称重图片时为全部 CONFIRMED netWeightKg 之和，消费者不得从图片重算}
-        actualNetWeightKg: {type: number, nullable: true}
+        actualGrossWeightKg: {type: number, nullable: true, multipleOf: 0.001, description: 服务端确认后的实测毛重 KG；只读取 fl_inbound_order.actual_gross_weight_kg，不以净重回退}
+        actualNetWeightKg: {type: number, nullable: true, multipleOf: 0.001, description: 服务端确认后的货物净重 KG；只读取 fl_inbound_order.actual_net_weight_kg，不以毛重回退}
         actualVolumeCbm: {type: number, nullable: true}
         volumeWeightKg: {type: number, nullable: true}
         chargeableWeightKg: {type: number, nullable: true}
@@ -1050,8 +1049,10 @@ components:
         cabinetNo: {type: string, nullable: true}
         vesselName: {type: string, nullable: true}
         voyageNo: {type: string, nullable: true}
-        sailingAt: {type: string, format: date-time, nullable: true}
-        portArrivalAt: {type: string, format: date-time, nullable: true}
+        estimatedSailingAt: {type: string, format: date-time, nullable: true, description: 当前关联柜次预计开船时间}
+        actualSailingAt: {type: string, format: date-time, nullable: true, description: 当前关联柜次实际开船时间}
+        estimatedPortArrivalAt: {type: string, format: date-time, nullable: true, description: 当前关联柜次预计到港时间}
+        actualPortArrivalAt: {type: string, format: date-time, nullable: true, description: 当前关联柜次实际到港时间}
         expressTrackingNo: {type: string, nullable: true}
         pickupMethod: {type: string, enum: [SELF_EXPRESS, PICKUP, SELF_TRUCK], nullable: true}
         requestedPickupAt: {type: string, format: date-time, nullable: true, description: 客户要求平台上门提货的预约时间}
@@ -1286,9 +1287,9 @@ components:
         measurementStatus: {type: string, nullable: true}
         inboundVersion: {type: integer, minimum: 0}
         version: {type: integer, minimum: 0, nullable: true}
-        originalDocumentNo: {type: string, nullable: true}
-        originalGrossWeightKg: {type: number, format: double, nullable: true}
-        originalVolumeCbm: {type: number, format: double, nullable: true}
+        originalDocumentNo: {type: string, nullable: true, description: 客户订单 referenceId 的服务端快照；旧空快照按订单事实回退}
+        originalGrossWeightKg: {type: number, format: double, nullable: true, description: 客户订单有效货物行 grossWeightKg 合计的服务端快照}
+        originalVolumeCbm: {type: number, format: double, nullable: true, description: 客户订单有效货物行 volumeCbm 合计的服务端快照}
         originalPackageCount: {type: integer, nullable: true}
         actualPackageCount: {type: integer, nullable: true}
         actualGrossWeightKg:
@@ -1296,10 +1297,16 @@ components:
           format: double
           nullable: true
           multipleOf: 0.001
-          description: 服务端权威货物总重量 KG；存在已确认称重结果时为所有 CONFIRMED netWeightKg 之和
+          description: 全部 CONFIRMED 称重结果 grossWeightKg 之和，含托盘毛重 KG；无确认结果时为空
+        actualNetWeightKg:
+          type: number
+          format: double
+          nullable: true
+          multipleOf: 0.001
+          description: 全部 CONFIRMED 称重结果 netWeightKg 之和，扣除托盘皮重后的货物净重 KG；无确认结果时为空，审核与计费以此为准
         actualVolumeCbm: {type: number, format: double, nullable: true}
         volumeWeightKg: {type: number, format: double, nullable: true}
-        actualGoodsName: {type: string, nullable: true}
+        actualGoodsName: {type: string, nullable: true, description: 默认由客户货物品名去重汇总，测量阶段允许人工修正}
         items:
           type: array
           description: DIMENSION 尺寸测量明细及其图片证据
@@ -1308,6 +1315,38 @@ components:
           type: array
           description: WEIGHT 称重结果及其图片、确认状态和服务端重量事实
           items: {$ref: '#/components/schemas/InboundWeightResult'}
+    InboundMeasurementSaveDraftRequest:
+      type: object
+      required: [version, items]
+      additionalProperties: false
+      properties:
+        measurementId: {type: string, pattern: '^[1-9][0-9]*$', nullable: true}
+        version: {type: integer, minimum: 0}
+        actualGoodsName: {type: string, maxLength: 255, nullable: true}
+        items:
+          type: array
+          minItems: 1
+          maxItems: 500
+          items: {$ref: '#/components/schemas/InboundMeasurementItemRequest'}
+    InboundMeasurementItemRequest:
+      type: object
+      required: [inboundDetailId, itemNo, boxSpecification, packageCount, lengthCm, widthCm, heightCm, unitWeightKg]
+      additionalProperties: false
+      properties:
+        inboundDetailId: {type: string, pattern: '^[1-9][0-9]*$'}
+        itemNo: {type: string, minLength: 1, maxLength: 32}
+        boxSpecification: {type: string, minLength: 1, maxLength: 64}
+        packageCount: {type: integer, minimum: 1, maximum: 1000000}
+        lengthCm: {type: number, minimum: 0.001}
+        widthCm: {type: number, minimum: 0.001}
+        heightCm: {type: number, minimum: 0.001}
+        unitWeightKg: {type: number, minimum: 0.001}
+        intelligentImageFileId: {type: string, pattern: '^[1-9][0-9]*$', nullable: true}
+        overLimitWarning: {type: string, maxLength: 500, nullable: true}
+        outerLengthCm: {type: number, minimum: 0, nullable: true}
+        outerWidthCm: {type: number, minimum: 0, nullable: true}
+        outerHeightCm: {type: number, minimum: 0, nullable: true}
+        remark: {type: string, maxLength: 500, nullable: true}
     InboundMeasurementDetailEnvelope:
       type: object
       required: [code, message]