1. 手册定位

这份手册不是开发文档，也不是算法说明，而是给运营、采购、测试、业务负责人看的实际使用说明。

如果你现在的感觉是：

  • 不知道从哪个页面开始看
  • 不知道每个页面在看什么
  • 不知道哪些结果能信，哪些只能观察
  • 不知道什么时候可以进入审批或试点发布

就按这份手册使用。

2. 先记住系统边界

当前智能补货模块的真实定位是：

  • ` 影子预测 `
  • ` 质量评估 `
  • ` 人工复核 `
  • ` 受控试点发布 `

它 不是：

  • 自动下采购单系统
  • 默认替代旧 Dashboard 的正式补货系统
  • 无人审批自动发布系统

当前固定边界：

  • 默认不替代旧 Dashboard
  • 默认不自动写正式备货结果
  • 默认不允许批量正式发布
  • 默认不允许无人审批自动 apply
  • 离线 Benchmark 结果不能直接替代正式规则

如果你看到页面里有“智能建议”“影子预测”“Benchmark 更优”，也不能直接理解成“现在就可以用它替换旧备货结果”。

3. 进入方式与权限

3.1 页面入口

智能补货独立模块入口统一在：

  • `/smart-replenishment/*`

3.2 权限说明

当前页面路由默认只对 admin 开放。

如果你能登录系统，但打不开这些页面，先确认：

  1. 当前账号是否有 `admin` 权限
  2. 是否已经正常登录
  3. 是否是从旧 Dashboard 误以为会自动跳转进智能补货模块

4. 页面成熟度说明

不是所有页面都代表“已经可以实际操作”。当前建议按下面理解：

4.1 已可实际使用页面

  • `/smart-replenishment/overview`
  • `/smart-replenishment/runs`
  • `/smart-replenishment/compare`
  • `/smart-replenishment/evaluation`
  • `/smart-replenishment/benchmark`
  • `/smart-replenishment/review`
  • `/smart-replenishment/publish-gate`
  • `/smart-replenishment/publish-audits`
  • `/smart-replenishment/publish-precheck`
  • `/smart-replenishment/approval-requests`

4.2 当前仍是占位 / 页面壳

  • `/smart-replenishment/settings`

当前不要把 settings 当作正式运营配置后台使用。

5. 运营正确使用顺序

如果你是第一次用，或者每天只想知道“今天该先看什么”，固定按下面顺序：

  1. 先看 `overview`
  2. 再看 `compare`
  3. 再看 `evaluation`
  4. 再看 `review`
  5. 最后看 `publish-gate`

如果涉及正式试点审批，再继续：

  1. 看 `publish-audits`
  2. 进 `publish-precheck`
  3. 看 `approval-requests`

不要一上来就进审批页，也不要一上来就讨论 apply / rollback。

6. 页面逐页说明

6.1 总览页

页面：

  • `/smart-replenishment/overview`

作用：

  • 快速确认系统今天有没有跑
  • 看最新运行情况
  • 看当前 compare 数据覆盖范围

重点看：

  • ` 最新 Run`
  • ` 覆盖 SKU`
  • ` 高差异条目 `
  • ` 只读状态 `

业务理解：

  • ` 最新 Run` 有值，说明今天链路有结果
  • ` 覆盖 SKU` 越低，说明今天可观察范围越小
  • ` 高差异条目 ` 多，不代表一定错，只代表需要优先人工看
  • ` 只读状态 = read only`，说明本页不会改正式补货数据

适合回答的问题：

  • 今天系统有没有跑
  • 今天有没有新的影子结果
  • 大概有多少 SKU 值得优先看

6.2 运行记录页

页面：

  • `/smart-replenishment/runs`

作用：

  • 查看每次智能补货运行记录
  • 判断有没有运行失败
  • 判断当前结果覆盖了哪些市场和日期

重点看：

  • `run_key`
  • `status`
  • `run_type`
  • ` 评估状态 `
  • ` 作用范围 `
  • ` 失败原因 `

业务理解：

  • `status = success`：本轮运行成功结束
  • `status = failed`：这一轮结果不能直接参考，先查失败原因
  • ` 评估状态 ` 里的 `evaluated / data_insufficient` 很重要
  • ` 作用范围 ` 能告诉你这轮是哪些市场、哪些锚点日期

适合回答的问题：

  • 今天 EU/UK 有没有跑
  • 当前 compare 对应的是哪一轮 run
  • 为什么今天没有新结果

6.3 影子对比页

页面：

  • `/smart-replenishment/compare`

作用：

  • 对比“当前正式建议量”和“智能影子预测量”
  • 帮运营先看差异和原因

这是运营最重要的页面之一。

重点看：

  • `SKU`
  • ` 站点 `
  • ` 画像 / Provider`
  • ` 正式建议 `
  • ` 智能预测 `
  • ` 差异 `
  • ` 可信度 `
  • `AWD 供给 `
  • ` 原因标签 `
  • ` 解释 `

字段怎么理解：

  • ` 正式建议 `：当前旧系统正式补货链路的建议值
  • ` 智能预测 `：智能补货影子链路给出的预测值
  • ` 差异 > 0`：智能建议更激进
  • ` 差异 <0`：智能建议更保守
  • ` 可信度 `：当前数据口径是否足够可靠
  • ` 原因标签 / 解释 `：系统给出的可解释原因，不是最终业务结论

正确看法：

  • 先按 ` 站点 + 最小差异 ` 筛出高差异 SKU
  • 再结合 ` 可信度 ` 判断值不值得花时间复核
  • 不要只看差异量，要同时看解释

特别注意：

  • EU/UK 在这里是诊断视图
  • 共享池分摊仍以旧正式补货逻辑为准
  • 单行差异不能直接当成最终采购量

推荐操作：

  1. 先筛 `Provider = rule_baseline`
  2. 再筛 `min_abs_diff >= 10`
  3. 优先看高差异 + 高可信度样本

6.4 预测质量评估页

页面：

  • `/smart-replenishment/evaluation`

作用：

  • 回答“智能结果到底准不准”
  • 这是放大试点、引入 AI provider、放宽门禁的前置质量门

重点看：

  • ` 样本数 `
  • `WAPE`
  • `Bias`
  • `wQL@P50 / P75 / P90`
  • `A 类 SKU 独立指标 `
  • ` 数据不足原因 `
  • ` 分组评估 `

字段怎么理解：

  • `WAPE`：越低越好
  • `Bias`：越接近 0 越好
  • `wQL`：分位预测质量指标，越低越好
  • `A 类 SKU`：高销量 / 核心 SKU，优先级最高
  • `data_insufficient`：样本不足，不能据此扩大白名单

正确看法：

先看这三层：

  1. `T+7` 总体指标
  2. `A 类 SKU` 指标
  3. ` 数据不足原因 `

如果 A 类 SKU 还不稳定，或者 data_insufficient 很多，这一轮结果就只能继续 shadow 观察，不能据此推进发布。

6.5 离线 Benchmark 页

页面：

  • `/smart-replenishment/benchmark`

作用：

  • 对比离线 AI 模型和 `rule_baseline`
  • 证明“AI 模型是否真的比当前规则更好”

它不是日常运营必须先看的页面。

重点看：

  • `Benchmark WAPE`
  • `Baseline WAPE`
  • `WAPE Delta`
  • ` 按窗口对比 `
  • ` 按分组对比 `

字段怎么理解：

  • `WAPE Delta <0`：Benchmark 优于 Baseline
  • `WAPE Delta > 0`：Benchmark 差于 Baseline

特别注意：

  • 这里的结果是离线导出、离线推理、结果回灌后的对比
  • 结果不能直接进入正式发布
  • 结果也不能自动替代当前正式补货规则

6.6 人工复核页

页面：

  • `/smart-replenishment/review`

作用：

  • 把影子预测解释成运营能理解的业务原因
  • 记录人工确认、驳回、调整
  • 沉淀结构化反馈

这是运营真正参与业务判断的核心页面。

页面分成三块：

  1. 左边 ` 复核队列 `
  2. 中间解释面板
  3. 右边复核表单

你要怎么用：

  1. 在左边选一个高差异 SKU
  2. 看正式建议、智能建议、差异、可信度
  3. 看解释面板里的原因
  4. 决定：

– 确认

– 驳回

– 调整

  1. 提交结构化原因和备注

这里还有两个附加区域：

  • ` 需求驱动事件 `
  • ` 商品关系候选审核 `

这两个区域的用法：

  • ` 需求驱动事件 `：查看当前 SKU 是否存在促销、价格变化、广告等驱动
  • ` 商品关系候选审核 `：把 suggested 候选人工通过或驳回

特别注意：

  • 本页不会改正式 Dashboard 建议量
  • 本页不会触发正式采购发布
  • 本页的意义是“沉淀人工反馈”，不是“立即改正式结果”

6.7 发布门禁页

页面：

  • `/smart-replenishment/publish-gate`

作用：

  • 判断哪些影子预测具备进入试点条件
  • 展示阻断原因

它不是发布按钮页面，而是门禁判断页面。

重点看：

  • ` 模型状态 `
  • ` 发布状态 `
  • ` 白名单 `
  • ` 评估窗口 `
  • ` 阻断原因 `
  • ` 建议动作 `

字段怎么理解：

  • ` 模型状态 = 可试点 `：模型质量侧基本过关
  • ` 发布状态 = 门禁放行 `：具备进入下一步流程资格
  • ` 白名单 = 已启用 `：当前 SKU 在试点范围内
  • ` 阻断原因 `：为什么现在不能继续往前

正确看法：

  • `model_ready = true` 不代表现在就能正式发布
  • `can_publish = true` 才表示门禁层面允许进入下一步
  • 有 blocker 时，先解决 blocker，不要直接找技术说“帮我发一下”

6.8 发布审计页

页面：

  • `/smart-replenishment/publish-audits`

作用：

  • 查看 controlled publish 历史动作
  • 查 dry-run、apply、rollback 记录

重点看：

  • `action_type`
  • `status`
  • `run_id`
  • `SKU`
  • `Rollback`
  • `reason_code`

动作怎么理解：

  • `dry_run`：发布前预演
  • `publish_apply`：试点正式写入
  • `rollback_apply`：回滚执行

这个页面主要用来：

  • 查历史记录
  • 找某次预演对应的 `rollback point`
  • 追踪谁做过什么动作

6.9 审批预检页

页面：

  • `/smart-replenishment/publish-precheck`

作用：

  • 对某一个 dry-run 包做正式审批前预检

重点注意：

这个页面不是自动给你列表，它需要你先输入：

  • `rollback_point_id`

正确顺序是：

  1. 先去 `publish-audits` 找 dry-run 记录
  2. 找到对应的 `rollback point`
  3. 再把 `rollback_point_id` 带到本页做预检

本页重点看：

  • `pilot_precheck`
  • `blockers`
  • `quality_risk_summary`
  • `evaluation_requirement`
  • `benchmark_requirement`
  • `publish_limits`

正确看法：

  • 通过预检，不等于已经发布
  • 通过预检，只代表你可以进入审批申请阶段

6.10 审批申请页

页面：

  • `/smart-replenishment/approval-requests`

作用：

  • 查看审批申请
  • 记录人工通过 / 驳回决策

重点看：

  • `status`
  • `rollback_point_id`
  • `run_id`
  • `sku`
  • `market_name`
  • `diff_qty`
  • `restore_target`
  • ` 申请原因 `
  • ` 决策原因 `

状态怎么理解：

  • `pending`：待审批
  • `approved`：审批通过
  • `rejected`：审批驳回

特别注意：

  • 审批通过不等于已经发布
  • 审批通过只是获得了下一步 apply 资格
  • 当前链路要求双人审批，提交人和审批人不能是同一人

6.11 设置页

页面：

  • `/smart-replenishment/settings`

当前状态：

  • 页面壳
  • 只适合验证入口和连通性

运营建议：

  • 暂时不要把它当作正式配置中心使用

7. 运营最常见的 3 种使用场景

7.1 场景一：我只想知道今天哪些 SKU 值得看

操作顺序：

  1. 进 `overview`
  2. 看 ` 高差异条目 `
  3. 进 `compare`
  4. 用 `min_abs_diff >= 10`
  5. 优先处理高差异 + 高可信度 SKU

7.2 场景二：我想判断智能建议值不值得信

操作顺序：

  1. 进 `evaluation`
  2. 先看 `T+7`
  3. 再看 `A 类 SKU`
  4. 再看 ` 数据不足原因 `
  5. 有需要时再看 `benchmark`

判断原则：

  • 指标稳定，才值得继续推进
  • 样本不足，就继续 shadow

7.3 场景三：我想推进某个样本进入试点发布

操作顺序：

  1. 进 `publish-gate`
  2. 确认不是 blocked
  3. 去 `publish-audits` 找 dry-run 记录
  4. 拿到 `rollback_point_id`
  5. 进 `publish-precheck`
  6. 预检通过后，进入 `approval-requests`
  7. 完成双人审批

注意：

  • 当前不是全量开放发布
  • 只有受控试点才允许进入正式 apply / rollback

8. 哪些情况应该立刻停下来

出现下面情况，不要继续推进发布：

  • `evaluation` 中样本明显不足
  • `A 类 SKU` 指标恶化
  • `publish-gate` 中 blocker 很多
  • `publish-precheck` 中质量风险高
  • `compare` 中 EU/UK 差异看起来异常但无法解释
  • `review` 中业务大量驳回且原因集中在数据问题

这时正确动作是：

  1. 保持 shadow
  2. 记录问题
  3. 让技术或产品继续修口径 / 修数据 / 修规则

9. 当前最推荐的运营使用方法

如果你现在刚开始接手，最简单有效的方式就是：

每天固定看 4 个页面：

  1. `compare`
  2. `evaluation`
  3. `review`
  4. `publish-gate`

一句话理解：

  • `compare`：看差在哪
  • `evaluation`：看准不准
  • `review`：留业务判断
  • `publish-gate`：看能不能进试点

只要先把这 4 个页面用顺了，这套系统就已经能支撑日常观察、人工复核和试点推进。

10. 最后再记一次：不要误解系统阶段

当前智能补货模块已经能用，但它的“能用”是：

  • 能观察
  • 能对比
  • 能评估
  • 能复核
  • 能受控试点

不是：

  • 全量自动替代旧系统
  • 自动正式发布
  • 无人值守采购决策

运营在当前阶段最重要的职责不是“直接拿智能结果替代旧结果”，而是：

  • 帮系统筛高价值样本
  • 把业务判断结构化沉淀下来
  • 协助识别哪些结果可以进入试点
  • 协助识别哪些结果还必须继续 shadow