feat(selfop): calculate inventory and outbound volume by owner and SKU

lastleg-service/src/main/resources/openapi/self-operated-inventory-turnover-v1.yaml

@@ -89,6 +89,30 @@ components:
         knownPhysicalQuantity: {$ref: '#/components/schemas/Quantity'}
         unknownSkuCount: {type: integer, minimum: 0}
         physicalQuantityRatio: {$ref: '#/components/schemas/Quantity'}
+    Volume:
+      type: object
+      description: >-
+        m³，按SKU先计算再汇总，不对分页行求和。优先完整有效的仓库实测尺寸，否则完整商品申报尺寸；不混搭长宽高。
+        支持mm/cm/m/in/ft，未知单位及非正尺寸无效。商品资料固定为queryAsOf之前最近完整已发布批次，按账号+货主+SKU关联。
+        库存按全品质实物件数，不计在途，不代表库位占用；历史出库按当前商品尺寸估算，不代表历史包裹实测体积。
+        数量已知为0可得0，无需尺寸；数量未知或正数量缺有效尺寸时正式值null，已知小计单独返回。
+      required: [value, knownSubtotal, missingDimensionQuantity, missingDimensionSkuCount, unknownQuantitySkuCount, declaredDimensionQuantity, reasonCodes]
+      properties:
+        value: {type: number, nullable: true, description: 全部数量和所需尺寸可确认时的体积，m³}
+        knownSubtotal: {type: number, nullable: true, description: 可计算部分的体积小计，m³，不冒充总量}
+        missingDimensionQuantity: {$ref: '#/components/schemas/Quantity'}
+        missingDimensionSkuCount: {type: integer, minimum: 0}
+        unknownQuantitySkuCount: {type: integer, minimum: 0}
+        declaredDimensionQuantity: {allOf: [{$ref: '#/components/schemas/Quantity'}], description: 使用商品申报尺寸估算的件数}
+        reasonCodes: {type: array, items: {type: string, enum: [DIMENSIONS_MISSING_OR_INVALID, QUANTITY_UNAVAILABLE, DECLARED_DIMENSIONS_ESTIMATE]}}
+    VolumeWindow:
+      type: object
+      required: [days, startDate, endDateExclusive, volume]
+      properties:
+        days: {type: integer, minimum: 1, maximum: 366}
+        startDate: {type: string, format: date}
+        endDateExclusive: {type: string, format: date}
+        volume: {$ref: '#/components/schemas/Volume'}
     Window:
       type: object
       required: [days, startDate, endDateExclusive, outboundQuantity, observedQuantity, averageDailyOutboundQuantity, completeDayCount, partialDayCount, unknownDayCount, dataStatus, reasonCodes]
@@ -133,7 +157,7 @@ components:
         accumulationStartedOn: {type: string, format: date, nullable: true}
     Row:
       type: object
-      required: [customerCode, customerName, sku, productName, physicalQuantity, availableQuantity, frozenQuantity, defectiveQuantity, transitQuantity, physicalSkuCount, windows, averageDailyOutboundQuantity, inventoryCoverageDays, coverageStatus, averagePhysicalQuantity, quantityTurnoverCount, turnoverStatus, qualifiedSampleDays, requiredSampleDays, missingSampleDates, sampleReasonCodes, lastObservedOutboundDate, attentionReasons, noOutboundInWindow, slowCoverage, unassessableSkuCount]
+      required: [customerCode, customerName, sku, productName, physicalQuantity, availableQuantity, frozenQuantity, defectiveQuantity, transitQuantity, physicalSkuCount, windows, averageDailyOutboundQuantity, inventoryCoverageDays, coverageStatus, averagePhysicalQuantity, quantityTurnoverCount, turnoverStatus, qualifiedSampleDays, requiredSampleDays, missingSampleDates, sampleReasonCodes, lastObservedOutboundDate, attentionReasons, noOutboundInWindow, slowCoverage, unassessableSkuCount, unitVolumeM3, dimensionSource, inventoryVolumeM3, outboundVolumesM3]
       properties:
         customerCode: {type: string}
         customerName: {type: string, nullable: true}
@@ -163,15 +187,21 @@ components:
         noOutboundInWindow: {$ref: '#/components/schemas/Risk'}
         slowCoverage: {$ref: '#/components/schemas/Risk'}
         unassessableSkuCount: {type: integer, minimum: 0}
+        unitVolumeM3: {type: number, nullable: true, description: SKU单件体积m³，货主汇总不提供}
+        dimensionSource: {type: string, nullable: true, enum: [WAREHOUSE_MEASURED, PRODUCT_DECLARED, MISSING], description: SKU尺寸来源，货主汇总不提供}
+        inventoryVolumeM3: {$ref: '#/components/schemas/Volume'}
+        outboundVolumesM3: {type: array, minItems: 3, maxItems: 4, items: {$ref: '#/components/schemas/VolumeWindow'}}
     Overview:
       type: object
       nullable: true
-      required: [physicalQuantity, availableQuantity, noOutboundSkuCount, unassessableSkuCount]
+      required: [physicalQuantity, availableQuantity, noOutboundSkuCount, unassessableSkuCount, inventoryVolumeM3, outboundVolumesM3]
       properties:
         physicalQuantity: {$ref: '#/components/schemas/Total'}
         availableQuantity: {$ref: '#/components/schemas/Total'}
         noOutboundSkuCount: {$ref: '#/components/schemas/Total'}
         unassessableSkuCount: {$ref: '#/components/schemas/Total'}
+        inventoryVolumeM3: {$ref: '#/components/schemas/Volume'}
+        outboundVolumesM3: {type: array, minItems: 3, maxItems: 4, items: {$ref: '#/components/schemas/VolumeWindow'}}
     Charts:
       type: object
       nullable: true