243 lines
35 KiB
Markdown
243 lines
35 KiB
Markdown
# 库存周转视图设计
|
||
|
||
在 Admin「自营业务 → 库存分析」增加默认打开的“库存周转”视图，让运营在同一处比较各 SKU 的 7／15／30 天出库、当前库存和消化速度，并按货主汇总，筛选需要复核库存安排及内部仓储成本的对象。
|
||
|
||
本设计整理自 2026-10-13 [优化数据采集页面状态提示中的业务讨论](codex://threads/01a134a1-0ccd-7b61-add0-945d47eec5de)。用户已要求整理方案并交开发总控安排。本文件是新增视图、指标扩展、查询合同与验收的维护入口；基础数据、采集及权限沿用[一期方案](领星一件代发数据统计一期方案.md)，总览原有下钻沿用[经营总览图表设计](经营总览图表设计.md)。设计交付不表示功能已实现、部署或通过验收。
|
||
|
||
## 业务目标与本次边界
|
||
|
||
业务需要回答四个问题：哪些货现在存得多；哪些 SKU 近期不动或消化慢；哪些货主的库存需要优先复核；哪些商品持续流转，可以进一步评估仓储支持或成本优惠。
|
||
|
||
继续按仓库独立查看全部授权货主，当前仍是自营业务的内部评估与成本分摊准备。领星货主不是平台收费客户，不自动绑定财务账户。件数、出库速度与当前可售天数是经营依据，不直接给出“加价”“优惠”“优级客户”或费率结论。
|
||
|
||
| 本次交付 | 后续另行核验 |
|
||
| --- | --- |
|
||
| 默认进入即查；SKU 与货主两种视图；7／15／30 天出库同屏；按所选窗口的日均及可售天数；无出库、消化较慢／较快、冻结／次品及待评估筛选 | 真实批次库龄、占用体积、托盘／库位及占用时间、货主与内部成本中心映射 |
|
||
| 有完整日库存样本时计算期间件数周转次数；不足时展示样本数与缺口，不阻断其他指标 | 正式内部评级、仓租加价／优惠规则、生效期、例外、审批及财务联动 |
|
||
| 库存与销量时间分别展示；同版本分页、汇总、图表及趋势下钻 | 新外部接口、提高领星并发、补造历史库存、任意历史时点库存重建 |
|
||
|
||
本轮扩展了早前“期间周转留待后续”的范围：实现有资格才计算的查询与展示，但不放宽日样本标准。新品、战略备货、季节性、断货与促销尚未建模，所有关注标签都供人工复核。
|
||
|
||
## 菜单与首次进入
|
||
|
||
### 库存与出库立方数（2026-10-14 确认）
|
||
|
||
库存周转增加库存立方数、所选区间出库立方数及 SKU 单件体积，单位统一为 m³。沿现有 SKU／货主分组、客户筛选、时间范围及客户下钻查看；本仓／本客户概览增加两项体积汇总，汇总范围与原概览相同，不随分页、SKU 或关注筛选缩小。
|
||
|
||
- 尺寸使用查询时刻 `queryAsOf` 之前最近完整已发布的资料批次，按来源账号＋货主编码＋SKU 精确关联。后续翻页和下钻保持原时刻，整体刷新才取得新尺寸。
|
||
- 优先完整、正值且单位有效的仓库实测长宽高；否则使用完整商品申报尺寸，并标明估算。不混用两套长宽高。支持 mm、cm、m、in、ft，英寸严格按 0.0254 米换算；未知单位不猜测。
|
||
- 库存立方数＝当前全品质实物件数×单件体积。不叠加冻结、次品或在途，不代表托盘／库位占用或含空隙的仓储空间。过期、缺失或异常库存保持未知。
|
||
- 出库立方数＝对应完整出库窗口件数×当前商品单件体积。所有历史出库体积均明确标为估算，不冒充历史包裹实测体积；7／15／30 天及所选 N 天独立判断覆盖，不以部分销量冒充完整体积。
|
||
- 先按 SKU 计算再聚合货主与本仓，不平均尺寸、不按当前页求和、不把同名 SKU 跨客户合并。已知零件数可得零体积；正件数缺尺寸及数量未知分开统计。正式总量未知显示“—”，保留已知体积小计、缺尺寸件数／SKU 数、数量待确认 SKU 数及商品尺寸估算件数。
|
||
- 表格体积列的m³放在有效数值后，未知值只显示“—”，估算及缺尺寸说明保留；库存立方数、所选窗口出库立方数支持SKU／货主全量升降序，单件体积仅SKU支持排序。排序取正式未舍入值，未知末尾，不以已知小计代替；切换排序保持上下文并回第一页。
|
||
- 不增加领星请求、重新采集或改动采集节奏。当前扩展仅在库存周转视图展示体积，原库存明细及销量分析保持现有指标。
|
||
|
||
保持 `/self-operated/inventory` 和现有菜单，页内提供「库存周转」「库存明细」两个视图。普通菜单进入默认“库存周转”，其中默认“按 SKU”；“按货主”是可选切换，不要求先选择货主，不在经营总览和销量分析恢复货主面板。
|
||
|
||
四个统计页面统一最近3／7／15／30天及自定义（1～366天），均截至北京时间昨日，日期选择器禁止今日及未来。原库存明细继续承接所选时段查询与经营总览严格下钻，不得被新默认页签吞掉或转换成相似的新筛选。它是现有查询能力的明确入口，不增加旧协议别名。
|
||
|
||
仓库优先级为合法深链仓库、当前页面保留的有权限仓库、服务端返回的首个有权限仓库；不硬编码仓库编码。确定仓库后自动加载，默认截止日为北京时间昨天，计算基准为 30 天，按实物件数降序、未知末尾。无可用仓库不发经营请求。非法深链或无权仓库明确报错，不静默改查其他仓。
|
||
|
||
新视图路由参数使用 `view=TURNOVER,groupBy=SKU|OWNER,endDate,baseWindowDays=1..366`，以及其合法筛选／排序和查询上下文。显式 `view=DETAIL` 或原总览严格下钻走原合同；相互冲突的参数拒绝，不混合两套筛选。重置保留仓库，恢复新视图默认条件并重新查询；刷新、查询都只读本地已发布数据，不创建采集任务。
|
||
|
||
页签判定按以下顺序执行：总览严格下钻（`from=overview`／`drilldownFrom=DASHBOARD`）进入 DETAIL；其次采用合法显式 view；未指定 view 但有明细专属 `salesWindowDays,attention,coverageSelection,coverageBucket,bucketRuleVersion` 时进入 DETAIL；其余默认 TURNOVER。`warehouseCode,sku,customerCode,endDate` 和公共版本字段本身不决定页签。优先级不吞掉冲突：显式 TURNOVER 同时携带总览来源或明细专属条件必须报错，所有参数再按选定视图校验。
|
||
|
||
## 页面示意与交互
|
||
|
||
以下是布局与承载设计，不是实际数据或已验收截图。沿用模块 ECharts、蓝紫主色及浅色指标卡，数量、异常和数据状态同时有文字，不只靠颜色。
|
||
|
||
```text
|
||
库存分析 库存周转〔默认〕 库存明细 数据采集
|
||
仓库 [当前仓] 统计时间范围 [最近3 / 7 / 15 / 30天 / 自定义] 查询 刷新
|
||
按 SKU / 按货主 SKU 搜索〔仅 SKU 视图〕 关注条件 / 阈值 / 排序
|
||
销量：7日完整、15日缺2日、30日缺12日 当前库存采集：开始……完成……
|
||
────────────────────────────────────────────────────────────────────
|
||
实物件数 正品可售件数 所选时段无出库 SKU 待评估 SKU
|
||
────────────────────────────────────────────────────────────────────
|
||
货主实物件数 Top10（横条） 货主库存立方数 Top10／日均出库对比
|
||
────────────────────────────────────────────────────────────────────
|
||
全部 | 实物件数最多 | 所选时段无出库 | 消化较慢 | 消化较快 | 待评估
|
||
SKU／商品／货主 | 实物／可售 | 7日／15日／30日出库 | 日均 | 可售天数 | 状态
|
||
……服务端分页，20条／页…… 扩展列／统计说明
|
||
```
|
||
|
||
图表约 220～260px 高，可折叠且记住本页偏好，表格仍是比较明细的主区。四张指标卡和两图显示当前仓库及精确货主范围的整体情况，不随 SKU 关键字、关注筛选及翻页改变；区块标明“本仓概览”或“本货主概览”。列表上方单独显示筛选结果条数，不能让全仓卡片被误读为当前页合计。
|
||
|
||
指标卡主数值只展示正式总量，未知总量显示“—”；已知小计（含0）与待核验SKU数放辅助说明，不用已知小计冒充完整总量。库存过期须明确显示最近观测完成时间及受影响指标；同仓采集失败独立显示原因、真实任务号与状态观测时间，沿现有数据采集入口查看。整体刷新同时更新只读采集状态，状态请求失败须说明，不能继续把旧失败当最新状态或影响已成功返回的经营数据。样本证据明确区分出库历史和每日库存观测，补采／验证不计日代表，截止日只允许已结束的北京时间日期，因此今天采集成功的合格计划库存样本最早次日查询时才能纳入窗口；当天样本数仍为0不代表采集未成功。
|
||
|
||
货主 Top10 按有效全品质实物件数排序，未知货主不按零参与排名，图旁显示未能完整计算的货主数；标题必须是“实物件数”，不写“占仓面积／占仓最多”。相同件数按货主编码稳定排序。点击条目切入本仓该货主的 SKU 视图，显示可清除的货主条件，保留上下文；不足十个按实际数展示。
|
||
|
||
右侧默认显示“货主库存立方数 Top10”，标题处切换“日均出库对比”，切换不发新请求、不改变筛选和查询上下文。体积榜复用当前全品质库存体积口径，按完整未舍入值降序、同值按货主编码稳定排序，最多十个；缺尺寸或数量未知的货主不按零或已知小计排名，展示未参与的货主数。条末显示最多两位小数及 m³，明细保留尺寸来源及估算说明，点击条目及明细货主沿用同版本 SKU 下钻。库存体积排名不受统计时段影响，不代表库位空间或占仓面积。
|
||
|
||
日均对比包含截至所选结束日的7／15／30天及所选N天（去重），每窗完整出库分别除以对应自然日数，各柱独立判覆盖，不比较不同天数的原始累计量；无完整口径的柱留空并显示原因，不画零柱。图表用于观察平均速度，不直接生成增长率或客户等级。
|
||
|
||
| 操作 | 承载与行为 |
|
||
| --- | --- |
|
||
| 切仓／截止日／计算基准／分组 | 同页 QueryToolbar；更新条件并回到第一页；切仓清旧数据，取消旧请求并校验请求世代 |
|
||
| 关注与阈值 | 同页紧凑控件；选择消化较慢／较快时展开整数天阈值，输入有效后查询；不新增确认弹框 |
|
||
| 按货主切换 | 同页服务端分页汇总；切换时清除 SKU 关键字及仅适用 SKU 的排序，提示条件已调整；保留仓库、截止日、基准及有效精确货主条件 |
|
||
| 点击货主 | 同页切回 SKU 列表并添加精确货主 chip；返回货主汇总恢复原页码、筛选和上下文 |
|
||
| 点击 SKU | 复用当前 1120px 居中 SKU 日趋势 AppDialog，带真实货主＋SKU与所选基准区间；不加抽屉或独立详情页 |
|
||
| 历史库存记录与未知原因 | 主表隐藏“状态与样本”列，不逐行显示日样本进度；期间平均实物／期间件数周转未知时显示“—”，悬停说明原因。在现有“统计说明”中选择本页商品或货主，打开现有 1040px 居中证据 AppDialog 查看历史库存记录及销量覆盖，最多 366 日 |
|
||
|
||
列表快捷筛选右侧提供默认选中的带边框复选框“隐藏 0 库存”（`hideZeroInventory`，省略时为true）。按当前全品质实物件数筛选：SKU视图隐藏明确零实物SKU，货主视图隐藏汇总实物明确为零的货主；未知、过期库存不当作零，可售为零但仍有实物的记录保留。服务端在完整候选上筛选后计数、排序、分页；不改变概览、图表及货主内部销量的汇总范围。取消勾选显示全部，切换立即回第一页并保留查询快照，分组／货主下钻保持选择，重置恢复默认选中。
|
||
| 图表完整明细 | 沿用 1040px 居中图表明细框，支持键盘等价下钻；不默认重复展示第二张表 |
|
||
| 统计说明 | 同页折叠文字，集中说明三种指标、时间及未知规则；主表不重复长段说明 |
|
||
|
||
SKU 列表是只读分析表，无须新增“操作”列。第一组身份列为 SKU、商品名称、所属货主；长名称可换行，不以内部 ID 回退。首屏保留三窗出库及主要库存／速度指标；在正品可售后默认展示“在途”列，SKU及货主视图均支持全量升降序排序，未知末尾；冻结、次品、期间平均库存、周转次数、最近已观测出库日放扩展列。历史库存记录明细收进统计说明，不单设状态与样本列。允许表格内部横向滚动，不挤小全页字体。
|
||
|
||
本节是新视图的逐操作设计依据，总控实施时并入模块 `operation-matrix.md`；原明细和总览承载继续沿用既有矩阵。视觉验收为人工 1920×1080、100% 截图，缺证据记“待人工截图确认”。
|
||
|
||
## 统计时间与三种指标
|
||
|
||
所有窗口使用同一个北京时间截止日 D，默认昨天且不允许未来或未结束的今日。N 天范围为 `[D-N+1 00:00, D+1 00:00)`，N 为所选日期数（1～366）；保留7、15、30天辅助对比，非这些天数的所选窗口另行返回；不是自然周／自然月。例：截止 2026-10-12，三个起始日分别为 10-06、09-28、09-13。
|
||
|
||
三列出库量始终同屏；`baseWindowDays` 决定日均、可售天数、无出库、快慢查询和期间周转的计算基准，默认 30，不会偷偷把未齐的 30 天换成 7 天。每窗独立返回完整量、已采集量、完整／部分／未知日数、实际日期及原因。部分窗口显示“已采集 X，覆盖不足”，所有日均与派生判断不采用该部分量。
|
||
|
||
SKU 窗口出库、日均、可售天数及无出库判断与库存明细使用相同资格：仓库固定销量版可信且日期覆盖完整、商品及实际出库数量单位有效时，缺销量行可确认为窗口内零出库，不再要求商品首次观察早于窗口起点。单日存在无效单位或异常出库数量时必须撤销该日资格，不能由缺行补零掩盖。首次观察时间继续服务于历史件数周转等证据判断，历史库存代表缺口仍不得补零。卡片汇总与列表筛选使用同一结果，真正未知的库存或出库继续保留已知小计和待核验数。
|
||
|
||
| 指标 | 计算与命名 | 资格 |
|
||
| --- | --- | --- |
|
||
| N 日日均出库 | 同期完整实际出库件数 ÷ N，含真实零出库日 | 使用固定销量版日事实及完整日规则；不只除以有出库的天数 |
|
||
| 预计可售天数 | 当前正品可售量 ÷ N 日日均出库 | 沿用库存有效性、可信窗口完整性及数量单位资格，不以 SKU 首次观察时间阻断；描述正品可售库存，不代表全部实物消化时间 |
|
||
| N 日件数周转次数 | 同期完整实际出库件数 ÷ 同期每日全品质实物观测均值 | N 个合格同口径日代表、范围／单位／商品身份可靠、同期销量完整；显示“次／N日”，不叫财务周转率 |
|
||
|
||
期间平均库存为 `N 个每日代表的实物量之和 ÷ N`，沿用主方案 `DAILY_SCHEDULED_FIRST_V1`：每天指定的首次合格计划采集，不改用每天最新快照，不使用期初／期末二点平均，不是日终或时间加权平均。每个日代表的商品库存先按品质聚合一次，冻结和次品是实物子集，在途不加入。出库分子为同商品同单位全部实际出库，不以某个库存品质过滤重复累加订单。
|
||
|
||
当前库存和历史期间独立：更改截止日只改变销量及平均库存的历史区间，预计可售天数仍使用查询时固定的当前库存，页面必须保留库存观测时间。历史周转有完整样本时，不因当前库存过期而抹去历史结果；当前可售天数仍须失效。不同 N 的周转次数不是同一期间，不能直接比较次数得出速度变快。
|
||
|
||
计算保留原六位小数精度；日均显示两位、天数一位、周转次数两位，筛选和排序使用未舍入值。很小的正数按显示精度显示“<0.01／<0.1”，不伪装为真实零；前端不重新推算业务指标。
|
||
|
||
仓库／货主的 7／15／30 日日均出库图按固定已发布销量版的实际覆盖与单位资格独立计算。后台补采或归并触发 `rebuildRequired` 时，不抹去该版已经完整覆盖的日期；图表显示销量发布时间和新版待重算提示，未发布的事实及其他版本均不混入。30 日未齐不能用已覆盖天数缩小分母。SKU当前库存评估继续受待重算保护，图表旧版可读不代表可作为最新补货或告警依据。
|
||
|
||
### 零值与数据不足
|
||
|
||
| 条件 | 结果 |
|
||
| --- | --- |
|
||
| 窗口完整，当前正可售，但出库为零 | 日均 0，可售天数为空，显示“所选窗口无出库”；不填无限大 |
|
||
| 当前库存有效且可售为 0 | 可售天数 0 并标“无可售库存”；不进入消化较快，不代表库存健康或货主优秀 |
|
||
| 当前库存未知／异常／过期 | 可售天数为空并说明；可靠历史出库及历史周转独立展示 |
|
||
| 7 天完整、15／30 天缺失 | 7 天可独立输出正式值，其他窗口显示已采集量／缺口；默认 30 日基准的日均及天数仍为空 |
|
||
| N 日日代表齐全且平均实物大于零、出库为零 | 件数周转次数为 0；仍要满足商品观察与销量完整性 |
|
||
| 平均实物为零 | 周转次数为空；有出库时说明“每日观测未捕获存量”，不输出无穷大或直接认定数据造假 |
|
||
| 有 30 天出库，但库存只有 2 个合格日样本 | 显示 2／30、缺口和积累起点；周转次数为空，不缩小分母、不用当前库存倒推历史 |
|
||
| 首采以前、人工 TEST 库存、日代表缺商品行或品质／单位异常 | 沿原规则保留未知／缺口；不补零，不把人工批次事后标成计划日代表 |
|
||
|
||
最近已观测出库日期取固定销量版的有效正出库最大日期，不以任意首采日充当。没有可靠日期显示“已采集历史内未见出库”；只有该日期至截止日连续覆盖且商品存在证据可靠时，才可显示“距最近出库 N 天”。不得将有限观察窗口内未见出库写成“从未售出”或真实库龄。
|
||
|
||
## 筛选与内部评估规则
|
||
|
||
新视图使用独立 `focus`，不改写原 `attention`、总览分桶或所选时段严格下钻含义。观察与异常证据沿用主方案。快慢阈值是本次查询输入，按仓库保存页面偏好但不是正式仓租政策；初始不预设未经确认的 90／180 天，不因未设阈值阻止默认列表。
|
||
|
||
| 快捷入口／focus | 规则与默认排序 |
|
||
| --- | --- |
|
||
| 全部 ALL | 固定版本候选全集，保留零值、售空及未知；默认实物件数降序 |
|
||
| 实物件数最多 | ALL＋实物降序；不得称为占用空间最大 |
|
||
| 所选时段无出库 NO_OUTBOUND_IN_WINDOW | 有效正实物、所选可信完整时段出库为零及有效数量单位；包含全冻结／次品；按所选基准窗口判定 |
|
||
| 消化较慢 COVERAGE_GT | 有效正品可售量和 N 日日均均为正且正式可售天数 > 查询阈值；天数降序 |
|
||
| 消化较快 COVERAGE_LE | 有效正品可售量和 N 日日均均为正且正式可售天数 ≤ 查询阈值；天数升序；只是消化估算，不代表持续销售或正式高周转等级 |
|
||
| 冻结／次品 FROZEN／DEFECTIVE | 对应有效数量 >0，不依赖销量完整性；这些库存可能无法按日均正常售出 |
|
||
| 待评估 UNASSESSABLE | 当前库存、所选 N 日可信窗口或数量单位资格不足，无法完整评估流转表现；有效零可售仍按优先规则显示0天，窗口不足时可同时标“待评估：销量覆盖不足”；完整零出库不属于此类 |
|
||
|
||
可售天数判定固定为库存有效性 → 明确零可售 → 正可售的窗口／单位资格 → 分母是否为零；待评估标签不覆盖这一数值顺序，也不等同“可售天数必为空”。另提供“周转样本不足”状态／筛选 `turnoverStatus=INSUFFICIENT`，它与经营待评估独立：已有完整出库和可售天数的 SKU 可以仅缺历史库存样本。无出库与慢消化是不同集合，不将空天数伪装为超大数；冻结／次品与其他关注可重叠，不把标签命中数相加当总 SKU 数。
|
||
|
||
货主视图不把整个货主简单分为快／慢：使用“含此类 SKU 的货主”筛选，行内同时显示该类已确认 SKU 数、实物件数和待判断数；未输入阈值时快慢相关值为空并显示“未设查询阈值”。
|
||
|
||
## 货主汇总
|
||
|
||
货主汇总是一条服务端分页聚合查询，不先获取货主选项再逐个调用 `owner-overview`。身份键为来源账号＋仓库＋货主；SKU 继续以货主＋SKU 去重，不跨货主合并同名商品。
|
||
|
||
每行展示货主名称／编码、有实物 SKU 数、实物／正品可售／在途／冻结／次品件数、7／15／30 日出库、所选 N 日日均、所选时段无出库 SKU 数及实物件数、慢消化命中和待评估数量；期间周转放扩展列。不平均 SKU 可售天数，也不输出“总库存÷总日均”作为货主整体可售天数。
|
||
|
||
货主历史出库和平均实物候选必须涵盖期间曾有库存或出库而当前已售空的商品；不能先筛当前正库存再算周转。货主平均实物先按每个合格日代表汇总该货主全部同口径商品，再取 N 日均值；完整时用货主同期总出库除以该平均量。它仍是混合商品的件数指标，不作为跨货主奖惩排名，不能用高销量小件掩盖积压大件。
|
||
|
||
每项总量分别提供正式总量、已知小计和未知数量。销售窗口完整即可展示货主真实出库总量；单个 SKU 库存观察不足不抹掉已可靠的出库事实。无出库等正式命中件数占比，只有整个候选范围及判断均可靠才输出；否则仅给已确认小计与待判断数。比例为实物件数比例，不是空间占比；分母零时比例为空。
|
||
|
||
## 服务端合同与数据结构
|
||
|
||
新增 Lastleg 只读 `GET /api/platform/v1/last-leg/self-operated-analytics/inventory-turnover`，供新视图使用；原 `/inventory-coverage`、`owner-overview`、经营总览及其严格下钻合同保留各自用途，不把原单窗口接口改成三次调用。复用平台 list 权限、仓库范围检查和既有异常响应。最终 Controller、DTO、OpenAPI、前端类型必须一起收口，以下是开发目标，不宣称接口已经存在。
|
||
|
||
| 入参 | 约束 |
|
||
| --- | --- |
|
||
| sourceAccount、warehouseCode | 沿现有受控配置及服务端范围检查；只查单仓 |
|
||
| endDate、baseWindowDays | 截止日含当天且必须为已结束日期；基准 7／15／30，默认昨天／30；三窗固定返回，不传任意窗口数组 |
|
||
| groupBy、customerCodes、sku | SKU／OWNER；customerCodes 为可选货主编码集合，重复query键传输，最多100个，省略或空集合查询全部，列表／概览／图表统一按集合筛选，不合并不同货主的同名SKU；下钻传单元素集合；sku 只适用 SKU 分组，OWNER 携带则拒绝 |
|
||
| focus、coverageDaysThreshold、turnoverStatus | 按上节枚举；GT／LE 必须有正整数阈值，其他关注可带阈值展示标签；拒绝原 attention／coverageBucket 等混入 |
|
||
| sortBy、current、size | 按分组白名单排序；默认 PHYSICAL_DESC，1／20，size≤100；同值以 SKU＋货主或货主编码稳定排序，未知末尾 |
|
||
| 查询上下文 | 复用固定版本、queryAsOf 和有效期；新增历史日代表集合的固定证据，不能由客户端任填 run ID 绕过检查 |
|
||
|
||
SKU 数值表头支持实物件数、正品可售、7／15／30 日出库、所选基准日均出库、预计可售天数，以及扩展列冻结件数、次品实物、期间平均实物、期间件数周转的升降序。首次点击未选中的列使用降序，再次点击切换升序；箭头表示成功查询的顺序，与排序下拉框共用同一合同。切换排序回到第一页，保持有效的查询上下文；按全部筛选结果排序后分页，不在当前页重排。日均排序随 `baseWindowDays` 使用对应窗口。未知或覆盖不足的正式值始终排在末尾，不按已采集小计或零参与；同值按 SKU＋货主稳定排序。OWNER 支持相同指标（预计可售天数除外）及已确认无出库实物小计排序，同值按货主编码稳定排序，未知状态随值返回。
|
||
|
||
一次响应返回 `context,summary,charts,rows,total`。首次／整体刷新返回概览与两图，普通列表翻页用同一上下文及 `includeOverview=false` 省去重复汇总；筛选 SKU 或关注不改变概览范围。切仓、截止日、基准、精确货主或分组变化时，重新请求对应概览；不得把新上下文的行与旧图拼屏。
|
||
|
||
`context` 固定账号、仓库、销量版、当前库存版、queryAsOf、有效期、三个真实窗口、当前库存观测起止、历史日样本规则与最多30个日期到代表批次的映射摘要。历史样本只纳入首次上下文时已经发布且合格的代表；后续样本补齐不能悄悄改变旧查询。实际代表映射须可由服务端验证／重建，缺失日期也冻结，不只是返回一个不可校验的哈希。受引用版本按现有保留策略保护，到期或无法重建时明确要求整体刷新。
|
||
|
||
每窗指标至少返回 `days,startDate,endDateExclusive,outboundQuantity,observedQuantity,averageDailyOutboundQuantity,completeDayCount,partialDayCount,unknownDayCount,dataStatus,reasonCodes`；行另外返回 `inventoryCoverageDays,averagePhysicalQuantity,quantityTurnoverCount,qualifiedSampleDays,requiredSampleDays,attentionReasons` 及各自状态。不能用一个行级 COMPLETE 掩盖部分指标未知。内部版本标识用于程序，不作为用户可见业务编号。
|
||
|
||
### 复用表与最小结构要求
|
||
|
||
| 数据 | 复用与约束 |
|
||
| --- | --- |
|
||
| 三窗实际出库 | `ll_selfop_sku_daily_sales`，按固定销量版、仓库及最长max(30,N)日读取，一次条件聚合三窗；仓级概览优先复用 `ll_selfop_warehouse_daily_sales` 及原覆盖证据 |
|
||
| 当前实物／可售／在途库存 | `ll_selfop_inventory_snapshot`＋其固定 profile，同 SKU 全品质先聚合，避免与日销量多行连接后乘倍 |
|
||
| 历史平均库存 | `ll_selfop_sync_run.inventory_daily_sample_date/inventory_sample_rule_version` 对应的 snapshot、profile、范围与发布证据；最多366个不可变代表批次 |
|
||
| 商品观察与缺日 | 固定版本 profile＋销量覆盖证明＋各库存代表的资格；可信完整销量覆盖内缺销量行可计零，缺库存代表行仍不得补零，不读取可变最新档案污染旧上下文 |
|
||
| 查询上下文 | 沿现有版本上下文机制扩展日代表集合；可用服务端签名令牌或既有上下文存储，但冻结字段及权限行为一致，实施前总控确定唯一方式 |
|
||
|
||
本轮不新增 7／15／30 天销量表、不复制库存日明细、不存一张会被实时覆盖的“SKU 周转结果表”，也不新增采集调度。若实际执行计划证明需要索引或有界聚合缓存，由总控在唯一 SQL 基线中评审；不凭设计先引入缓存平台。没有历史代表时，周转值为空即可交付页面，不能为得到数值额外扫描领星或修改原样本标记。
|
||
|
||
## 查询性能与一致性
|
||
|
||
所有查询读取本地已发布数据，不查原始订单明细，不调用 Integration。禁止前端逐 SKU／逐货主请求、把第一页求和当全仓汇总、先取 Top100 后筛选、为三窗执行三套完整扫描。
|
||
|
||
候选身份是本次固定当前库存版 profile／snapshot、固定销量版所选最长max(30,N)日事实及相关 profile、同期合格日代表 profile／snapshot 中货主＋SKU 的并集；不读取后续可变档案。仅历史存在而当前缺行的商品保留为当前库存未知，不能补零。rows、total、summary 和图表使用同一候选定义，再分别应用各自已声明的范围与列表筛选。
|
||
|
||
默认实物排序且无销量／天数／周转等依赖筛选时，可先对完整候选身份分页，再补该页三窗和历史样本，不能只从当前 snapshot 选页而丢失未知／售空商品。依赖销量、可售天数、周转次数的筛选／排序必须先在完整候选计算资格，再排序分页。货主聚合与图表独立按完整范围计算；复用现有性能方案中已验证的路径，不原样重复已无收益的优化实验。
|
||
|
||
验收采用单仓至少1万货主＋SKU、最多30日代表、多历史销量版、10并发只读用户及后台构建场景。新增目标：首屏含概览 HTTP P95≤1.5s；默认列表翻页 P95≤1s。复杂筛选、货主汇总和完整30日周转排序分别报告，不用缺样本快速返回证明达标；未达目标记录瓶颈交总控安排，不能伪报通过。保留 P50／P95／P99、SQL 数、扫描行、响应大小及结果对照，压测不请求领星。
|
||
|
||
相同条件刷新失败可以保留旧结果并明确时间；切仓清旧结果。当前库存过期时只失效依赖当前库存的判断，历史销量／历史周转仍按各自证据展示。页面刷新不会改变采集状态，开发与发布不得为本视图重置采集任务。
|
||
|
||
## 开发顺序与职责
|
||
|
||
1. 总控冻结新增接口、窗口／零值规则、历史样本上下文和文件写权；明确 SKU 默认与货主可选视图是本轮新增例外，同步最近模块指引及操作矩阵，不恢复其他页面货主控件。
|
||
2. 指标查询工作包实现一次三窗聚合、库存资格、分页排序、全范围汇总与有资格的期间周转；样本不足作为正常业务状态，补定向公式／覆盖／版本测试。
|
||
3. 前端工作包实现默认打开、表格两视图、紧凑图表、筛选与既有趋势／证据弹框；先按冻结 DTO 并行，随后联调。共享类型与导航由总控协调唯一写者。
|
||
4. 采集工作包只核对已有日代表选择、保留及查询证据是否满足合同，不默认改采集或放大请求；必要缺口另交总控精确派工。
|
||
5. 总控完成接口、SQL 基线、权限及受影响门禁，安排人工页面验收。实现、自动测试、部署、人工验收分别记录；运行状态仍只维护正式工程契约。
|
||
|
||
优先交付能立即使用的默认查询、三窗出库、日均／可售天数、关注筛选与货主汇总；期间周转的合成样本测试同期完成，真实数值等待合格日样本自然积累，不让积累期阻断功能开发。不得以“已有可售天数”宣称正式周转已完成。
|
||
|
||
## 验收清单
|
||
|
||
| 场景 | 必须结果 |
|
||
| --- | --- |
|
||
| 普通菜单进入／有效深链／无仓库 | 自动选合法仓并查询；深链优先；无仓不查；不要求先选货主 |
|
||
| 截止2026-10-12 | 三窗起止分别为10-06／09-28／09-13至10-13不含，均不包含今日 |
|
||
| 示例 SKU：7／15／30日出库70／150／300，当前可售600；选30日 | 三列各自真实显示；日均10，可售60.0天；切7日仍日均10，不改三窗累计 |
|
||
| 同一SKU同期30个日代表实物均值500，30日出库300 | 30日件数周转0.60次；不能用当前可售600算成0.50次 |
|
||
| 7日齐、15／30日未齐 | 7日正式值可用；其他显示已采集量与不足；30日基准天数空，不自动缩短窗口 |
|
||
| 30日出库齐、仅2个日代表／只有人工TEST库存 | 显示真实样本缺口，正式周转空；销量和符合资格的可售天数继续展示 |
|
||
| 全冻结／次品正实物且完整30日零出库 | 可命中无出库和库存品质关注；可售为零不判消化较快，不重复累加实物 |
|
||
| 新品／首次观察晚于窗口起点 | 可信完整销量窗口按实际出库计算日均、天数及无出库判断，不因观察时间变成覆盖不足；期间件数周转仍核对历史库存样本与观察证据 |
|
||
| 来源库存缺行／负数／过期或销量未覆盖 | 对依赖指标逐项传播未知；不得把真正未知数量补零，负数不取绝对值 |
|
||
| 库存有效且可售0，但销量窗口不足 | 可售天数0并标无可售库存，同时保留销量覆盖不足及待评估；不因0天进入消化较快 |
|
||
| 平均库存正且零出库／平均库存零且有出库 | 前者周转0；后者为空并说明单日观测局限，不显示无限大 |
|
||
| 当前售空但期间有出库与历史库存 | 仍计入货主期间出库及平均库存；不因当前零库存丢失历史贡献 |
|
||
| 同仓同名SKU不同货主、两仓同货主SKU | 分行、分仓、独立窗口资格，不混合库存或借另一仓历史 |
|
||
| 货主有部分未知商品 | 出库、库存及关注分别传播；保留已知小计与未知数，不用合格样本比率冒充完整风险占比 |
|
||
| 切货主／筛选／分页／图表下钻 | 统计范围标签准确；列表 total 与全量谓词一致；图表不由当前页拼出；身份与上下文不丢 |
|
||
| 原经营总览无出库／最长天数／分桶跳入库存 | 进入原库存明细，保留原所选时段资格、严格版本及时效，不落入新近似筛选 |
|
||
| 新版发布、日样本新增、旧上下文读取 | 旧上下文结果不漂移；整体刷新才切新；过期明确要求刷新 |
|
||
| 页面与性能 | 1920×1080人工核对；三窗与主库存可读；未知有原因；性能按上述真实完整样本分别报告 |
|
||
|
||
本轮评审已明确：7／15／30是完整滚动窗口；四页日期统一最近3／7／15／30天及自定义，原明细继续有入口；货主汇总仅在新视图可选；件数不是空间；可售天数不是库龄或期间周转；历史样本不足不造数；新视图查询不增加领星请求。待后续业务确认的是正式仓租／优惠阈值、空间数据和成本主体，均不阻断本次只读功能开发。
|
||
|
||
自定义长区间的翻页上下文携带逐日样本映射的SHA-256摘要，服务端仍按固定查询时刻重建完整max(30,N)日映射（含缺失日期）后比较摘要；完整日历保留在响应中。不能仅相信客户端摘要，也不能读取当前最新样本替代原版本。
|
||
|
||
### 货主多选、导出与期间周转率（2026-10-15确认）
|
||
|
||
货主筛选支持可搜索多选，清空恢复全部，变化回到第一页；概览及图表标注“所选货主”。期间周转率默认显示，沿用期间件数周转次数×100%，历史库存样本不足或分母不可计算时保留—，不以当前库存替代。
|
||
|
||
顶部“导出”按当前已查询的筛选、排序及快照逐页读取全部匹配记录，导出CSV（Excel可打开），列顺序与当前显示列一致，扩展列打开时一并导出；保留未知与估算说明、周转率，提供进度及取消。查询变化或离开页面取消导出，版本失效或分页异常不下载部分文件。
|