优化

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

@@ -13,7 +13,7 @@ info:
     默认maxQueryDays366，粒度DAY。正式outboundQuantity与observedQuantity独立，全部未知仍为空。
     每日COMPLETE仅证明全天覆盖及有效日行或可靠SKU存在；今日/部分日正式量空，观察量可用，未知日期保持空。
     SKU区间正式量仅全部日完整才输出；observedQuantity为可靠点合计，完整/部分/未知日数独立。
-    热销榜跟随图表所选日期，以已采集有效出库量排序；覆盖不足标记PARTIAL，不改变30日日均分母；不触发领星请求。
+    热销榜跟随图表所选日期，以已采集有效出库量排序；覆盖不足标记PARTIAL，日均、库存分布及两库存榜使用同一所选区间的完整销量与自然日数；不触发领星请求。
     运行接口不受经营context限制。动态库存时效、重建和修订待核对独立返回。
     阶段进度区分ACCOUNT_SHARED/WAREHOUSE及TASK_CUMULATIVE/ATTEMPT_ONLY，不伪造总百分比。
     total未知为空、计数不能跨PAGE/ORDER/INVENTORY_ROW/BUSINESS_KEY/SKU/BATCH单位求和，NONE为非计数阶段且completed/total为空、totalKnown=false；阶段检查点与心跳分开。
@@ -26,7 +26,7 @@ paths:
       summary: 单仓固定版本经营总览
       description: >-
         平台独立只读权限platform:self-operated-analytics:list。一次一致快照固定销量和库存版本。
-        默认LAST_15_DAYS同时用于趋势、区间出库和热销Top10；热销按已采集有效量排序并标记覆盖状态。日均、互斥分桶及两个库存Top10固定至昨日30完整日。
+        默认LAST_15_DAYS统一用于趋势、区间出库、日均、互斥分桶及三个Top10；热销按已采集有效量排序并标记覆盖状态，库存评估要求所选区间完整销量及观察资格。
         不接受货主、SKU、分页、windowDays、topN或其他额外筛选。仓级趋势不套单SKU观察期。
         库存严格下钻须携带原版本和drilldownFrom=DASHBOARD；截止时间由服务端根据库存真实观测重算。
       parameters:
@@ -182,9 +182,12 @@ paths:
         '403': {description: 非平台身份或缺少独立只读权限}
   /api/platform/v1/last-leg/self-operated-analytics/inventory-coverage:
     get:
-      summary: 正品库存与固定10或30日可售天数
-      description: '固定10或30天，不接受图表周期。可售仅品质0可用量，不扣冻结或加在途次品。先UNKNOWN/INVALID/STALE，再有效零库存为0，再校验正库存单位、窗口、观察期；零销量天数为空。 权限platform:self-operated-analytics:list。'
+      summary: 正品库存与所选窗口可售天数
+      description: '普通库存明细使用10或30天；总览严格下钻须携带drilldownFrom=DASHBOARD及原图CUSTOM起止日期，不得同时携带salesWindowDays/salesWindowEndDate。可售仅品质0可用量，不扣冻结或加在途次品。先UNKNOWN/INVALID/STALE，再有效零库存为0，再校验正库存单位、窗口、观察期；零销量天数为空。 权限platform:self-operated-analytics:list。'
       parameters:
+        - {$ref: '#/components/parameters/rangePreset'}
+        - {$ref: '#/components/parameters/startDate'}
+        - {$ref: '#/components/parameters/endDate'}
         - {$ref: '#/components/parameters/coverageBucket'}
         - {$ref: '#/components/parameters/bucketRuleVersion'}
         - {$ref: '#/components/parameters/coverageSelection'}
@@ -384,13 +387,13 @@ components:
       name: coverageBucket
       in: query
       description: 与非ALL attention和coverageSelection互斥，须配套固定规则版本；SQL分页前采用与总览相同互斥谓词。
-      schema: {type: string, enum: [DAYS_0_30, DAYS_30_60, DAYS_60_90, DAYS_GT_90, NO_OUTBOUND_30D, NO_AVAILABLE, UNKNOWN]}
+      schema: {type: string, enum: [DAYS_0_30, DAYS_30_60, DAYS_60_90, DAYS_GT_90, NO_OUTBOUND_IN_WINDOW, NO_AVAILABLE, UNKNOWN]}
     bucketRuleVersion: {name: bucketRuleVersion, in: query, description: 不带coverageBucket时禁止单独传入, schema: {type: string, enum: [COVERAGE_DISTRIBUTION_V1]}}
     coverageSelection: {name: coverageSelection, in: query, description: 正式有限正可售天数候选，在SQL分页前过滤，与非ALL attention及coverageBucket互斥, schema: {type: string, enum: [FINITE_POSITIVE]}}
     drilldownFrom: {name: drilldownFrom, in: query, description: 必须固定原版本，服务端在真实库存有效期与查询到期较早者阻断并要求刷新总览；不增加权限, schema: {type: string, enum: [DASHBOARD]}}
     keyword: {name: keyword, in: query, schema: {type: string, minLength: 1, maxLength: 64}, description: 区分大小写的货主编码字面前缀，先过滤去重再分页}
-    attention: {name: attention, in: query, schema: {type: string, default: ALL, enum: [ALL, NO_OUTBOUND_30D, COVERAGE_GT_THRESHOLD, FROZEN_STOCK, DEFECTIVE_STOCK, UNASSESSABLE]}}
-    sortBy: {name: sortBy, in: query, schema: {type: string, default: AVAILABLE_DESC, enum: [AVAILABLE_DESC, COVERAGE_DAYS_DESC, PHYSICAL_DESC, OUTBOUND_30D_ASC]}, description: 完整候选先筛选后按未舍入值排序分页，未知末尾，同值SKU和货主升序}
+    attention: {name: attention, in: query, schema: {type: string, default: ALL, enum: [ALL, NO_OUTBOUND_IN_WINDOW, COVERAGE_GT_THRESHOLD, FROZEN_STOCK, DEFECTIVE_STOCK, UNASSESSABLE]}}
+    sortBy: {name: sortBy, in: query, schema: {type: string, default: AVAILABLE_DESC, enum: [AVAILABLE_DESC, COVERAGE_DAYS_DESC, PHYSICAL_DESC, OUTBOUND_ASC]}, description: 完整候选先筛选后按未舍入值排序分页，未知末尾，同值SKU和货主升序}
     coverageDaysThreshold: {name: coverageDaysThreshold, in: query, schema: {type: integer, minimum: 1}, description: COVERAGE_GT_THRESHOLD必填，严格大于且未舍入比较，不设置默认经营政策}
     sourceAccount: {name: sourceAccount, in: query, required: true, schema: {type: string, minLength: 1, maxLength: 64}}
     warehouseCode: {name: warehouseCode, in: query, required: true, schema: {type: string, minLength: 1, maxLength: 64}}
@@ -425,9 +428,6 @@ components:
         - {$ref: '#/components/schemas/Context'}
         - type: object
           properties:
-            fixedWindowStartDate: {type: string, format: date}
-            fixedWindowEndDateExclusive: {type: string, format: date}
-            fixedWindowDays: {type: integer, enum: [30]}
             inventoryFreshUntil: {type: string, format: date-time, nullable: true}
             inventoryDrilldownExpiresAt: {type: string, format: date-time, nullable: true}
     DashboardMetric:
@@ -445,11 +445,11 @@ components:
       type: object
       properties:
         intervalOutboundQuantity: {$ref: '#/components/schemas/DashboardMetric'}
-        averageDailyOutboundQuantity30d: {$ref: '#/components/schemas/DashboardMetric'}
+        averageDailyOutboundQuantity: {$ref: '#/components/schemas/DashboardMetric'}
         physicalQuantity: {$ref: '#/components/schemas/DashboardMetric'}
         availableQuantity: {$ref: '#/components/schemas/DashboardMetric'}
         physicalSkuCount: {$ref: '#/components/schemas/DashboardMetric'}
-        noOutboundSkuCount30d: {$ref: '#/components/schemas/DashboardMetric'}
+        noOutboundSkuCount: {$ref: '#/components/schemas/DashboardMetric'}
     CoverageDistribution:
       type: object
       description: 数值桶按未舍入交叉乘积判断；七桶互斥守恒。库存版未发布时计数为空，不把销量候选伪造成库存总量。
@@ -467,7 +467,7 @@ components:
           items:
             type: object
             properties:
-              bucketCode: {type: string, enum: [DAYS_0_30, DAYS_30_60, DAYS_60_90, DAYS_GT_90, NO_OUTBOUND_30D, NO_AVAILABLE, UNKNOWN]}
+              bucketCode: {type: string, enum: [DAYS_0_30, DAYS_30_60, DAYS_60_90, DAYS_GT_90, NO_OUTBOUND_IN_WINDOW, NO_AVAILABLE, UNKNOWN]}
               skuCount: {type: string, nullable: true}
               knownPhysicalQuantity: {type: number, nullable: true}
               unknownPhysicalSkuCount: {type: string, nullable: true}
@@ -493,7 +493,7 @@ components:
       properties:
         windowStartDate: {type: string, format: date}
         windowEndDateExclusive: {type: string, format: date}
-        calculationWindowDays: {type: integer, minimum: 1, description: 热销为所选日期天数；库存榜固定30}
+        calculationWindowDays: {type: integer, minimum: 1, description: 三个榜单均为所选日期区间的自然日数}
         eligibleCount: {type: string, nullable: true}
         unassessableCount: {type: string, nullable: true}
         items: {type: array, maxItems: 10, items: {$ref: '#/components/schemas/DashboardRankingItem'}}
@@ -658,7 +658,7 @@ components:
         status: {type: string, nullable: true}
         reasonCodes: {type: array, items: {type: string}}
     InventoryMetric:
-      description: 库存独立窗口响应。windowOutboundQuantity为所选完整10或30日销量；未知保持null，零销量状态NO_OUTBOUND_IN_WINDOW不除零。30日专属筛选及总览下钻不能用于10日或历史截止窗口。
+      description: 库存窗口响应。windowOutboundQuantity为所选完整窗口销量：普通明细10或30日，总览严格下钻使用原图CUSTOM区间；未知保持null，零销量状态NO_OUTBOUND_IN_WINDOW不除零。无出库关注、出库排序及分组均使用实际窗口。
       type: object
       properties:
         customerName: {type: string, nullable: true}

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

@@ -39,8 +39,8 @@ paths:
         - {name: turnoverStatus, in: query, schema: {type: string, enum: [INSUFFICIENT]}}
         - name: sortBy
           in: query
-          description: 'OWNER禁止COVERAGE_ASC/DESC，SKU禁止NO_OUTBOUND_PHYSICAL_DESC。使用正式值及未舍入值排序。'
-          schema: {type: string, default: PHYSICAL_DESC, enum: [PHYSICAL_DESC, AVAILABLE_DESC, OUTBOUND_7_DESC, OUTBOUND_15_DESC, OUTBOUND_30_DESC, COVERAGE_ASC, COVERAGE_DESC, TURNOVER_DESC, NO_OUTBOUND_PHYSICAL_DESC]}
+          description: 'OWNER禁止COVERAGE_ASC/DESC，SKU禁止NO_OUTBOUND_PHYSICAL_DESC。全量筛选后按正式未舍入值排序再分页，未知值始终末尾，同值按SKU及货主升序。AVERAGE_DAILY使用baseWindowDays指定的日均窗口。'
+          schema: {type: string, default: PHYSICAL_DESC, enum: [PHYSICAL_ASC, PHYSICAL_DESC, AVAILABLE_ASC, AVAILABLE_DESC, OUTBOUND_7_ASC, OUTBOUND_7_DESC, OUTBOUND_15_ASC, OUTBOUND_15_DESC, OUTBOUND_30_ASC, OUTBOUND_30_DESC, AVERAGE_DAILY_ASC, AVERAGE_DAILY_DESC, COVERAGE_ASC, COVERAGE_DESC, FROZEN_ASC, FROZEN_DESC, DEFECTIVE_ASC, DEFECTIVE_DESC, AVERAGE_PHYSICAL_ASC, AVERAGE_PHYSICAL_DESC, TURNOVER_ASC, TURNOVER_DESC, NO_OUTBOUND_PHYSICAL_DESC]}
         - {name: current, in: query, schema: {type: integer, minimum: 1, default: 1}}
         - {name: size, in: query, schema: {type: integer, minimum: 1, maximum: 100, default: 20}}
         - {name: includeOverview, in: query, schema: {type: boolean, default: true}}