优化

2026-08-14 17:37:59 +08:00
parent 87e919f3c4
commit feced8eb92
40 changed files with 1142 additions and 244 deletions
@@ -542,13 +542,62 @@ paths:
      responses:
        '200': {description: 成功或业务失败，按响应体 code 判断}
        '403': {description: 无测量编辑权限}
+  /api/platform/v1/first-leg/inbounds/{inboundId}/weight-pallet-options:
+    get:
+      summary: 查询称重可选托盘快照
+      description: >-
+        需要入库测量查看或称重编辑权限。Firstleg 按入库单 warehouseId 查询 Warehouse 公共托盘快照；
+        仅限定同仓且未删除，不校验托盘状态或占用资格，Admin 不需要 platform:pallet:list。
+      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]*$'}}
+      responses:
+        '200':
+          description: 成功或业务失败，按响应体 code 判断
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code: {type: string}
+                  message: {type: string}
+                  data: {type: array, items: {$ref: '#/components/schemas/WeightPalletSnapshot'}}
+        '403': {description: 无入库测量查看或称重编辑权限}
+  /api/platform/v1/first-leg/inbounds/{inboundId}/weight-results:
+    post:
+      summary: 登记称重图片 OCR 毛重结果
+      description: >-
+        需要称重编辑权限。请求必须绑定 palletId；Firstleg 按入库单 warehouseId 读取 Warehouse
+        权威快照并固化托盘编码、类型、容量和皮重，不信任前端托盘快照。
+      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/CreateWeightResultRequest'}
+      responses:
+        '200':
+          description: 成功或业务失败，按响应体 code 判断
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code: {type: string}
+                  message: {type: string}
+                  data: {$ref: '#/components/schemas/InboundWeightResult'}
+        '403': {description: 无称重编辑权限}
  /api/platform/v1/first-leg/inbounds/{inboundId}/weight-results/{resultId}/confirm:
    post:
      summary: 确认 OCR 重量
      description: >-
        需要 platform:firstleg:inbound:weight:confirm 权限；携带人工修改字段时还需要
        platform:firstleg:inbound:weight:edit 权限。修改与确认在同一事务内完成，保留 OCR 原值，
-        分别写入 CORRECT 和 CONFIRM 修订记录，并重算所有已确认图片的实际总毛重。
+        分别写入 CORRECT 和 CONFIRM 修订记录。输入表示含托盘毛重；服务端统一换算为 KG，
+        使用创建时固化的托盘皮重计算 netWeightKg，且毛重必须大于皮重。
+        入库单 actualGrossWeightKg 明确保留为下游货物实际毛重字段，值汇总所有已确认 netWeightKg。
      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]*$'}}
@@ -559,14 +608,48 @@ paths:
          application/json:
            schema: {$ref: '#/components/schemas/ConfirmWeightResultRequest'}
      responses:
-        '200': {description: 成功或业务失败，按响应体 code 判断}
+        '200':
+          description: 成功或业务失败，按响应体 code 判断
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code: {type: string}
+                  message: {type: string}
+                  data: {$ref: '#/components/schemas/InboundWeightResult'}
        '403': {description: 无确认权限，或修改重量时无编辑权限}
  /api/platform/v1/first-leg/inbounds/{inboundId}/weight-results/{resultId}:
+    put:
+      summary: 人工修正 OCR 毛重
+      description: >-
+        需要称重编辑权限。修正值仍表示含托盘毛重；保留 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]*$'}}
+        - {name: resultId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/CorrectWeightResultRequest'}
+      responses:
+        '200':
+          description: 成功或业务失败，按响应体 code 判断
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code: {type: string}
+                  message: {type: string}
+                  data: {$ref: '#/components/schemas/InboundWeightResult'}
+        '403': {description: 无称重编辑权限}
    delete:
      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}}
@@ -986,10 +1069,65 @@ components:
      properties:
        configId: {type: string, pattern: '^[1-9][0-9]*$'}
        createdByThisInitialization: {type: boolean}
+    WeightPalletSnapshot:
+      type: object
+      required: [palletId, palletCode, palletType, capacityCbm, tareWeightKg]
+      properties:
+        palletId: {type: string, pattern: '^[1-9][0-9]*$'}
+        palletCode: {type: string}
+        palletType: {type: string}
+        capacityCbm: {type: number, format: double, minimum: 0.0001}
+        tareWeightKg: {type: number, format: double, minimum: 0, multipleOf: 0.001}
+    CreateWeightResultRequest:
+      type: object
+      required: [fileId, palletId]
+      properties:
+        fileId: {type: string, pattern: '^[1-9][0-9]*$'}
+        palletId: {type: string, pattern: '^[1-9][0-9]*$'}
+        ocrProvider: {type: string, maxLength: 64, nullable: true}
+        ocrRawText: {type: string, maxLength: 1000, nullable: true}
+        ocrWeightValue: {type: number, format: double, minimum: 0, nullable: true, description: OCR 原始含托盘毛重}
+        ocrWeightUnit: {type: string, maxLength: 8, nullable: true}
+        confidence: {type: number, format: double, minimum: 0, maximum: 1, nullable: true}
+    CorrectWeightResultRequest:
+      type: object
+      required: [version, adjustedWeightValue, adjustedWeightUnit, adjustmentReason]
+      properties:
+        version: {type: integer, minimum: 0}
+        adjustedWeightValue: {type: number, format: double, minimum: 0.001, description: 人工修正后的含托盘毛重}
+        adjustedWeightUnit: {type: string, enum: [KG, LB]}
+        adjustmentReason: {type: string, minLength: 1, maxLength: 500}
+    InboundWeightResult:
+      type: object
+      required: [id, fileId, palletId, palletCode, palletType, palletCapacityCbm, palletTareWeightKg, recognitionStatus, version]
+      properties:
+        id: {type: string, pattern: '^[1-9][0-9]*$'}
+        fileId: {type: string, pattern: '^[1-9][0-9]*$'}
+        palletId: {type: string, pattern: '^[1-9][0-9]*$'}
+        palletCode: {type: string}
+        palletType: {type: string}
+        palletCapacityCbm: {type: number, format: double, minimum: 0.0001}
+        palletTareWeightKg: {type: number, format: double, minimum: 0, multipleOf: 0.001}
+        ocrProvider: {type: string, nullable: true}
+        ocrRawText: {type: string, nullable: true}
+        ocrWeightValue: {type: number, format: double, nullable: true, description: OCR 原始含托盘毛重}
+        ocrWeightUnit: {type: string, nullable: true}
+        confidence: {type: number, format: double, nullable: true}
+        grossWeightKg: {type: number, format: double, nullable: true, multipleOf: 0.001, description: 确认时标准化的含托盘毛重 KG}
+        adjustedWeightValue: {type: number, format: double, nullable: true, description: 人工修正后的含托盘毛重}
+        adjustedWeightUnit: {type: string, nullable: true}
+        netWeightKg: {type: number, format: double, nullable: true, multipleOf: 0.001, description: grossWeightKg - palletTareWeightKg}
+        recognitionStatus: {type: string, enum: [PENDING, PENDING_CONFIRM, NEEDS_MANUAL, CONFIRMED]}
+        adjustmentReason: {type: string, nullable: true}
+        adjustedBy: {type: string, nullable: true}
+        adjustedAt: {type: string, format: date-time, nullable: true}
+        confirmedBy: {type: string, nullable: true}
+        confirmedAt: {type: string, format: date-time, nullable: true}
+        version: {type: integer, minimum: 0}
    ConfirmWeightResultRequest:
      type: object
      required: [version]
-      description: 人工修改字段必须同时提供；全部省略时直接确认现有 OCR 或已修正重量。
+      description: 人工修改字段表示含托盘毛重且必须同时提供；全部省略时直接确认现有 OCR 或已修正毛重。
      properties:
        version: {type: integer, minimum: 0}
        adjustedWeightValue: {type: number, format: double, minimum: 0.001, nullable: true}