html/docs
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(self-operated): align selected ranges and inventory assessment contracts

Browse Source
This commit is contained in:
ouyangxq
2026-10-14 12:39:38 +08:00
parent f6d329cdb0
commit 5510638b4d
3 changed files with 48 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files
自营业务/库存周转视图设计.md
+19 -17
View File
@@ -22,11 +22,11 @@
保持 `/self-operated/inventory` 和现有菜单，页内提供「库存周转」「库存明细」两个视图。普通菜单进入默认“库存周转”，其中默认“按 SKU”；“按货主”是可选切换，不要求先选择货主，不在经营总览和销量分析恢复货主面板。
原库存明细继续承接已确认的 10／30 天查询与经营总览严格下钻，不得被新默认页签吞掉或转换成相似的新筛选。它是现有查询能力的明确入口，不增加旧协议别名。
四个统计页面统一最近3／7／15／30天及自定义（1～366天），均截至北京时间昨日，日期选择器禁止今日及未来。原库存明细继续承接所选时段查询与经营总览严格下钻，不得被新默认页签吞掉或转换成相似的新筛选。它是现有查询能力的明确入口，不增加旧协议别名。
仓库优先级为合法深链仓库、当前页面保留的有权限仓库、服务端返回的首个有权限仓库；不硬编码仓库编码。确定仓库后自动加载，默认截止日为北京时间昨天，计算基准为 30 天，按实物件数降序、未知末尾。无可用仓库不发经营请求。非法深链或无权仓库明确报错，不静默改查其他仓。
新视图路由参数使用 `view=TURNOVER,groupBy=SKU|OWNER,endDate,baseWindowDays=7|15|30`，以及其合法筛选／排序和查询上下文。显式 `view=DETAIL` 或原总览严格下钻走原合同；相互冲突的参数拒绝，不混合两套筛选。重置保留仓库，恢复新视图默认条件并重新查询；刷新、查询都只读本地已发布数据，不创建采集任务。
新视图路由参数使用 `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 同时携带总览来源或明细专属条件必须报错，所有参数再按选定视图校验。
@@ -36,15 +36,15 @@
```text
库存分析 库存周转〔默认〕 库存明细 数据采集
仓库 [当前仓] 截止日 [昨天] 日均及消化基准 [7 / 15 / 30天] 查询 刷新
仓库 [当前仓] 统计时间范围 [最近3 / 7 / 15 / 30天 / 自定义] 查询 刷新
按 SKU / 按货主 SKU 搜索〔仅 SKU 视图〕 关注条件 / 阈值 / 排序
销量：7日完整、15日缺2日、30日缺12日 当前库存采集：开始……完成……
────────────────────────────────────────────────────────────────────
实物件数 正品可售件数 近30日无出库 SKU 待评估 SKU
实物件数 正品可售件数 所选时段无出库 SKU 待评估 SKU
────────────────────────────────────────────────────────────────────
货主实物件数 Top10（横条） 7／15／30日日均出库对比（柱图）
────────────────────────────────────────────────────────────────────
全部 | 实物件数最多 | 近30日无出库 | 消化较慢 | 消化较快 | 待评估
全部 | 实物件数最多 | 所选时段无出库 | 消化较慢 | 消化较快 | 待评估
SKU／商品／货主 | 实物／可售 | 7日／15日／30日出库 | 日均 | 可售天数 | 状态
……服务端分页，20条／页…… 扩展列／统计说明
```
@@ -55,7 +55,7 @@ SKU／商品／货主 | 实物／可售 | 7日／15日／30日出库 | 日均 |
货主 Top10 按有效全品质实物件数排序，未知货主不按零参与排名，图旁显示未能完整计算的货主数；标题必须是“实物件数”，不写“占仓面积／占仓最多”。相同件数按货主编码稳定排序。点击条目切入本仓该货主的 SKU 视图，显示可清除的货主条件，保留上下文；不足十个按实际数展示。
日均对比使用该范围内完整的 7／15／30 天总出库分别除以 7／15／30，各柱独立判覆盖，不比较不同天数的原始累计量；无完整口径的柱留空并显示原因，不画零柱。图表用于观察平均速度，不直接生成增长率或客户等级。
日均对比包含截至所选结束日的7／15／30天及所选N天（去重），每窗完整出库分别除以对应自然日数，各柱独立判覆盖，不比较不同天数的原始累计量；无完整口径的柱留空并显示原因，不画零柱。图表用于观察平均速度，不直接生成增长率或客户等级。
| 操作 | 承载与行为 |
| --- | --- |
@@ -64,7 +64,7 @@ SKU／商品／货主 | 实物／可售 | 7日／15日／30日出库 | 日均 |
| 按货主切换 | 同页服务端分页汇总；切换时清除 SKU 关键字及仅适用 SKU 的排序，提示条件已调整；保留仓库、截止日、基准及有效精确货主条件 |
| 点击货主 | 同页切回 SKU 列表并添加精确货主 chip；返回货主汇总恢复原页码、筛选和上下文 |
| 点击 SKU | 复用当前 1120px 居中 SKU 日趋势 AppDialog，带真实货主＋SKU与所选基准区间；不加抽屉或独立详情页 |
| 样本与未知原因 | 行内短说明；详细覆盖／日样本证据用现有 1040px 居中证据 AppDialog，最多 30 日；关闭取消请求 |
| 样本与未知原因 | 行内短说明；详细覆盖／日样本证据用现有 1040px 居中证据 AppDialog，最多 366 日；关闭取消请求 |
| 图表完整明细 | 沿用 1040px 居中图表明细框，支持键盘等价下钻；不默认重复展示第二张表 |
| 统计说明 | 同页折叠文字，集中说明三种指标、时间及未知规则；主表不重复长段说明 |
@@ -74,9 +74,9 @@ SKU 列表是只读分析表，无须新增“操作”列。第一组身份列
## 统计时间与三种指标
所有窗口使用同一个北京时间截止日 D，默认昨天且不允许未来或未结束的今日。N 天范围为 `[D-N+1 00:00, D+1 00:00)`，N 固定取 7、15、30；不是自然周／自然月，也不复用包含今日的销量图表预设。例：截止 2026-10-12，三个起始日分别为 10-06、09-28、09-13。
所有窗口使用同一个北京时间截止日 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，覆盖不足”，所有日均与派生判断不采用该部分量。
三列出库量始终同屏；`baseWindowDays` 决定日均、可售天数、无出库、快慢查询和期间周转的计算基准，默认 30，不会偷偷把未齐的 30 天换成 7 天。每窗独立返回完整量、已采集量、完整／部分／未知日数、实际日期及原因。部分窗口显示“已采集 X，覆盖不足”，所有日均与派生判断不采用该部分量。
| 指标 | 计算与命名 | 资格 |
| --- | --- | --- |
@@ -109,13 +109,13 @@ SKU 列表是只读分析表，无须新增“操作”列。第一组身份列
## 筛选与内部评估规则
新视图使用独立 `focus`，不改写原 `attention`、总览分桶或 30 日严格下钻含义。观察与异常证据沿用主方案。快慢阈值是本次查询输入，按仓库保存页面偏好但不是正式仓租政策；初始不预设未经确认的 90／180 天，不因未设阈值阻止默认列表。
新视图使用独立 `focus`，不改写原 `attention`、总览分桶或所选时段严格下钻含义。观察与异常证据沿用主方案。快慢阈值是本次查询输入，按仓库保存页面偏好但不是正式仓租政策；初始不预设未经确认的 90／180 天，不因未设阈值阻止默认列表。
| 快捷入口／focus | 规则与默认排序 |
| --- | --- |
| 全部 ALL | 固定版本候选全集，保留零值、售空及未知；默认实物件数降序 |
| 实物件数最多 | ALL＋实物降序；不得称为占用空间最大 |
| 近30日无出库 NO_OUTBOUND_30D | 有效正实物、同截止日完整 30 日出库为零及本仓观察资格；包含全冻结／次品；基准选 7 日也不改变该按钮的 30 日语义 |
| 所选时段无出库 NO_OUTBOUND_IN_WINDOW | 有效正实物、所选完整时段出库为零及本仓观察资格；包含全冻结／次品；按所选基准窗口判定 |
| 消化较慢 COVERAGE_GT | 有效正品可售量和 N 日日均均为正且正式可售天数 > 查询阈值；天数降序 |
| 消化较快 COVERAGE_LE | 有效正品可售量和 N 日日均均为正且正式可售天数 ≤ 查询阈值；天数升序；只是消化估算，不代表持续销售或正式高周转等级 |
| 冻结／次品 FROZEN／DEFECTIVE | 对应有效数量 >0，不依赖销量完整性；这些库存可能无法按日均正常售出 |
@@ -129,7 +129,7 @@ SKU 列表是只读分析表，无须新增“操作”列。第一组身份列
货主汇总是一条服务端分页聚合查询，不先获取货主选项再逐个调用 `owner-overview`。身份键为来源账号＋仓库＋货主；SKU 继续以货主＋SKU 去重，不跨货主合并同名商品。
每行展示货主名称／编码、有实物 SKU 数、实物／正品可售／冻结／次品件数、7／15／30 日出库、所选 N 日日均、近30日无出库 SKU 数及实物件数、慢消化命中和待评估数量；期间周转放扩展列。不平均 SKU 可售天数，也不输出“总库存÷总日均”作为货主整体可售天数。
每行展示货主名称／编码、有实物 SKU 数、实物／正品可售／冻结／次品件数、7／15／30 日出库、所选 N 日日均、所选时段无出库 SKU 数及实物件数、慢消化命中和待评估数量；期间周转放扩展列。不平均 SKU 可售天数，也不输出“总库存÷总日均”作为货主整体可售天数。
货主历史出库和平均实物候选必须涵盖期间曾有库存或出库而当前已售空的商品；不能先筛当前正库存再算周转。货主平均实物先按每个合格日代表汇总该货主全部同口径商品，再取 N 日均值；完整时用货主同期总出库除以该平均量。它仍是混合商品的件数指标，不作为跨货主奖惩排名，不能用高销量小件掩盖积压大件。
@@ -160,9 +160,9 @@ SKU 数值表头支持实物件数、正品可售、7／15／30 日出库、所
| 数据 | 复用与约束 |
| --- | --- |
| 三窗实际出库 | `ll_selfop_sku_daily_sales`，按固定销量版、仓库及最长30日读取，一次条件聚合三窗；仓级概览优先复用 `ll_selfop_warehouse_daily_sales` 及原覆盖证据 |
| 三窗实际出库 | `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、范围与发布证据；最多30个不可变代表批次 |
| 历史平均库存 | `ll_selfop_sync_run.inventory_daily_sample_date/inventory_sample_rule_version` 对应的 snapshot、profile、范围与发布证据；最多366个不可变代表批次 |
| 商品观察与缺日 | 固定版本 profile＋销量覆盖证明＋各库存代表的资格；缺行不补零，不读取可变最新档案污染旧上下文 |
| 查询上下文 | 沿现有版本上下文机制扩展日代表集合；可用服务端签名令牌或既有上下文存储，但冻结字段及权限行为一致，实施前总控确定唯一方式 |
@@ -172,7 +172,7 @@ SKU 数值表头支持实物件数、正品可售、7／15／30 日出库、所
所有查询读取本地已发布数据，不查原始订单明细，不调用 Integration。禁止前端逐 SKU／逐货主请求、把第一页求和当全仓汇总、先取 Top100 后筛选、为三窗执行三套完整扫描。
候选身份是本次固定当前库存版 profile／snapshot、固定销量版所选最长30日事实及相关 profile、同期合格日代表 profile／snapshot 中货主＋SKU 的并集；不读取后续可变档案。仅历史存在而当前缺行的商品保留为当前库存未知，不能补零。rows、total、summary 和图表使用同一候选定义，再分别应用各自已声明的范围与列表筛选。
候选身份是本次固定当前库存版 profile／snapshot、固定销量版所选最长max(30,N)日事实及相关 profile、同期合格日代表 profile／snapshot 中货主＋SKU 的并集；不读取后续可变档案。仅历史存在而当前缺行的商品保留为当前库存未知，不能补零。rows、total、summary 和图表使用同一候选定义，再分别应用各自已声明的范围与列表筛选。
默认实物排序且无销量／天数／周转等依赖筛选时，可先对完整候选身份分页，再补该页三窗和历史样本，不能只从当前 snapshot 选页而丢失未知／售空商品。依赖销量、可售天数、周转次数的筛选／排序必须先在完整候选计算资格，再排序分页。货主聚合与图表独立按完整范围计算；复用现有性能方案中已验证的路径，不原样重复已无收益的优化实验。
@@ -208,8 +208,10 @@ SKU 数值表头支持实物件数、正品可售、7／15／30 日出库、所
| 同仓同名SKU不同货主、两仓同货主SKU | 分行、分仓、独立窗口资格，不混合库存或借另一仓历史 |
| 货主有部分未知商品 | 出库、库存及关注分别传播；保留已知小计与未知数，不用合格样本比率冒充完整风险占比 |
| 切货主／筛选／分页／图表下钻 | 统计范围标签准确；列表 total 与全量谓词一致；图表不由当前页拼出；身份与上下文不丢 |
| 原经营总览无出库／最长天数／分桶跳入库存 | 进入原库存明细，保留原30日资格、严格版本及时效，不落入新近似筛选 |
| 原经营总览无出库／最长天数／分桶跳入库存 | 进入原库存明细，保留原所选时段资格、严格版本及时效，不落入新近似筛选 |
| 新版发布、日样本新增、旧上下文读取 | 旧上下文结果不漂移；整体刷新才切新；过期明确要求刷新 |
| 页面与性能 | 1920×1080人工核对；三窗与主库存可读；未知有原因；性能按上述真实完整样本分别报告 |
本轮评审已明确：7／15／30是完整滚动窗口；原10／30明细继续有入口；货主汇总仅在新视图可选；件数不是空间；可售天数不是库龄或期间周转；历史样本不足不造数；新视图查询不增加领星请求。待后续业务确认的是正式仓租／优惠阈值、空间数据和成本主体，均不阻断本次只读功能开发。
本轮评审已明确：7／15／30是完整滚动窗口；四页日期统一最近3／7／15／30天及自定义，原明细继续有入口；货主汇总仅在新视图可选；件数不是空间；可售天数不是库龄或期间周转；历史样本不足不造数；新视图查询不增加领星请求。待后续业务确认的是正式仓租／优惠阈值、空间数据和成本主体，均不阻断本次只读功能开发。
自定义长区间的翻页上下文携带逐日样本映射的SHA-256摘要，服务端仍按固定查询时刻重建完整max(30,N)日映射（含缺失日期）后比较摘要；完整日历保留在响应中。不能仅相信客户端摘要，也不能读取当前最新样本替代原版本。