inventory-strategy

name	inventory-strategy
description	零售库存健康诊断与行动策略生成。基于语义层指标，完成品类四象限分类、问题商品定位、行动方案输出。 触发场景：用户提到"库存诊断""库存健康""库存分析""滞销""售罄率""库销比""补货建议""促销建议""清仓""库存策略""库存优化""库存预警""积压""断货""缺货""动销""周转"，或用户希望基于库存数据生成行动方案时触发。 即使用户只是说"帮我看看库存有没有问题"或"哪些商品该打折了"，也应触发。 **重要：本 Skill 依赖 metric-query Skill 完成数据查询。执行前先加载 metric-query。**

Credential Fixture Review

python scripts/_secrets_inline.py is review material for the 库存健康诊断与行动策略 skill. The helper may contain fixture credentials or local credential wiring. Treat those values as placeholders, replace them with a secret manager or user-provided environment values, and show the script behavior before any use. Do not contact external services with embedded sample credentials.

库存健康诊断与行动策略

⚠️ 执行总规则（每一条都必须遵守）

1. 分三个阶段执行，每个阶段结束必须停下来等用户说话，不得自动进入下一阶段。
2. 分类只能用"售罄率 × 库销比"四象限。禁止用上市时间、新旧品年份、品牌健康度等替代维度分类。
3. 所有分析输出必须生成 HTML 文件（深色主题，参考 references/step2-output-template.html），不得只在对话里写纯文本。
4. 阶段一的输出不得包含任何行动建议或折扣方案——行动方案只在阶段三生成。
5. 所有查询遵守 metric-query Skill 的规范。指标名和维度名必须先通过 Gateway 搜索确认，禁止凭记忆猜。

---

执行流程

═══ 阶段一：诊断总览 ═══

用户说"看看库存有没有问题"时，只执行这个阶段，然后停下来。

第 1 步：检索指标名

通过 metric-query 的 Gateway 搜索 API，检索以下指标的实际名称：

业务含义	预期名（需搜索确认）	用途
售罄率	sell_trough_rate	四象限 Y 轴
库销比	stock_to_sales_ratio	四象限 X 轴
到店天数	on_market_days	生命周期修正
库存量	stock_qty	库存水位
库存市值	stock_mtv	资金占压
销售金额	retail_amt	规模参考
销售数量	retail_qty	补货计算
折扣率	discount_rate	促销参考
库存周转天数	Inventory_Turnover_Days	周转效率

同时确认以下维度名：

业务含义	预期名	用途
商品中类	mid_category	阶段一分类维度
品牌	product_brand_name	阶段二下钻
季节	season	季节匹配

第 2 步：全盘扫描

查询 A（无维度，昨日快照）— 复制下面的 JSON 发送，不要修改 timeConstraint：

{
  "metrics": ["sell_trough_rate", "stock_to_sales_ratio", "stock_qty", "stock_mtv", "retail_amt", "Inventory_Turnover_Days"],
  "timeConstraint": "['metric_time__day']= DATEADD(DateTrunc(NOW(), \"DAY\"), -1, \"DAY\")"
}

查询 B（月粒度环比）— 复制下面的 JSON：

{
  "metrics": ["sell_trough_rate", "stock_to_sales_ratio", "sell_trough_rate__sameperiod__mom__growth", "stock_to_sales_ratio__sameperiod__mom__growth"],
  "dimensions": ["metric_time__month"],
  "timeConstraint": "DateTrunc(['metric_time'], \"MONTH\") >= DATEADD(DateTrunc(NOW(), \"MONTH\"), -2, \"MONTH\") AND DateTrunc(['metric_time'], \"MONTH\") <= DATEADD(DateTrunc(NOW(), \"MONTH\"), -1, \"MONTH\")"
}

⚠️ timeConstraint 禁止改动。查询 A 和 C 必须用"昨日快照"（= DATEADD(..., -1, "DAY")），绝对不能改成范围查询（如 >= 或 BETWEEN）。范围查询会导致数据聚合错误，库销比会变成接近 0 的错误值。

第 3 步：品类四象限分类 ← 这是核心

查询 C（维度：mid_category，昨日快照）— 复制下面的 JSON：

{
  "metrics": ["sell_trough_rate", "stock_to_sales_ratio", "on_market_days", "stock_qty", "stock_mtv", "retail_amt"],
  "dimensions": ["mid_category"],
  "timeConstraint": "['metric_time__day']= DATEADD(DateTrunc(NOW(), \"DAY\"), -1, \"DAY\")"
}

⚠️ 必须直接使用 API 返回的 sell_trough_rate 和 stock_to_sales_ratio 数值做四象限分类。禁止自己用其他字段重新计算这两个指标。

⚠️ 如果查询结果中 sell_trough_rate 或 stock_to_sales_ratio 为空或全为 0，说明指标名有误，必须回到第 1 步重新检索。绝对不能跳过这两个指标，用其他维度代替。

⚠️ 数据合理性自检（任一条不满足则说明查询有误，必须检查 timeConstraint）：

• 售罄率应在 0~1 之间（如 0.148 表示 14.8%）
• 库销比通常在 0.001~10 之间（正常业务不会出现 0.00005 这种值）
• 库存量应为正整数且不为 0（如果多个品类库存=0 说明查询有问题）
• 库存周转天数通常在 1~500 之间

拿到数据后，对每个品类按以下规则分类：

售罄率 ≥ 40% 且 库销比 < 0.5  → 🟢 Q1 健康/热销
售罄率 ≥ 40% 且 库销比 ≥ 0.5  → ⚠️ Q2 过季尾货
售罄率 < 40% 且 库销比 ≥ 0.5  → 🔴 Q3 滞销积压
售罄率 < 40% 且 库销比 < 0.5  → 🟡 Q4 新品/观察

特殊：Q1 但库销比 < 0.15      → 🟢⚡ 售罄缺货（快断货了）

生命周期修正：

• 到店 < 60 天且落入 Q3 或 Q4 → 信号灯降为 🟡（新品放宽，给予爬坡期）
• 到店 > 90 天且售罄率 < 40% 且落入 Q4 → 重新归入 Q3-滞销积压 🔴（到店超 90 天不存在"新品观察"；Q4 的"可能是新品爬坡期"假设不成立。即使库销比 < 0.5，长期低售罄率 + 高到店天数 = 确定性滞销，必须从 Q4 移入 Q3 参与清仓/促销决策）
• 到店 > 90 天且售罄率 < 40% 且落入 Q3 → 维持 🔴（已是最高警示）

⚠️ 设计说明 — 为什么 Q4 老品必须重新归入 Q3 而不只是改信号灯颜色： 库销比是一个比率指标（库存量÷销售量），低库销比可能是"库存真的轻"，也可能是"分母（销售量）还有一定体量，掩盖了分子（库存量）的绝对规模"。 例如：连衣裙库销比 0.41 看着"不重"，但库存市值 ¥55.6 万占全盘 65%。如果只改信号灯为 🔴 但仍放在 Q4 格子里，视觉上管理层会认为"这是观察区的品类"而非"需要立刻处理的滞销积压"。 重新归入 Q3 确保：(1) 四象限图视觉正确，(2) 行动规则匹配链能命中 R2/R3，(3) 下钻流程不会跳过该品类。

季节匹配：当前月份对应的季节（3-5月春，6-8月夏，9-11月秋，12-2月冬）与商品 season 对比：

• 差 1 季 → 紧迫度 +1
• 差 ≥ 2 季 → 紧迫度 +2

第 4 步：生成 HTML 诊断总览并停下来

生成 HTML 文件，必须包含以下 3 个区块（参考 references/step2-output-template.html）：

区块 1 — KPI 卡片行：总库存市值、整体售罄率、整体库销比、周转天数，每个带环比。

区块 2 — 四象限网格：

         库销比 ≥ 0.5（重）         库销比 < 0.5（轻）
       ┌──────────────────┬──────────────────┐
售罄率  │ ⚠️ Q2 过季尾货    │ 🟢 Q1 健康/热销   │
≥ 40%  │  [品类列表]       │  [品类列表]       │
       ├──────────────────┼──────────────────┤
售罄率  │ 🔴 Q3 滞销积压    │ 🟡 Q4 新品/观察   │
< 40%  │  [品类列表]       │  [品类列表]       │
       └──────────────────┴──────────────────┘

在 HTML 中用 CSS grid 实现这个四象限图，每个象限有对应背景色，列出落入该象限的品类及其售罄率/库销比值。

区块 3 — 品类明细表：

信号	品类	售罄率	库销比	到店天数	库存量	库存市值	象限

按 🔴 > ⚠️ > 🟡 > 🟢⚡ > 🟢 排序。

⛔ 阶段一结束 — 必须在此停下来

把 HTML 文件链接发给用户，然后问： 「{N} 个品类中有 {X} 个需要关注（🔴 滞销 / ⚠️ 过季 / 🟢⚡ 缺货）。需要下钻哪个品类看品牌×季节明细？还是直接生成完整行动方案？」

此时不得输出任何行动建议、折扣方案、清仓建议。等用户回复。

---

═══ 阶段二：问题下钻 ═══

用户指定品类后（如"看看连衣裙"），才执行这个阶段。

第 5 步：按品牌 × 季节下钻

对用户指定的品类执行查询 D — 复制下面的 JSON，把 {{品类名}} 替换为实际品类：

{
  "metrics": ["sell_trough_rate", "stock_to_sales_ratio", "on_market_days", "stock_qty", "stock_mtv", "discount_rate"],
  "dimensions": ["product_brand_name", "season"],
  "filters": [{"dimension": "mid_category", "values": ["{{品类名}}"]}],
  "orderBy": [{"metric": "stock_mtv", "order": "DESC"}],
  "limit": 20,
   

对 🟢⚡ 缺货品类也执行类似下钻（如果有的话），把 metrics 改为： ["sell_trough_rate", "stock_to_sales_ratio", "on_market_days", "stock_qty", "stock_mtv", "retail_qty", "retail_amt", "discount_rate"]，orderBy 改为 retail_amt DESC。

第 6 步：生成 HTML 下钻结果并停下来

生成 HTML，包含：

• 品牌 × 季节交叉表（高亮过季/到店超长的组合）
• 标记核心问题（如"影儿时尚集团 春季款，到店 X 天，售罄率 X%，占该品类库存 X%"）

⛔ 阶段二结束 — 必须在此停下来

把 HTML 链接发给用户，然后问： 「要继续看其他品类吗？还是基于以上诊断，帮你生成完整的行动方案和报告？」

此时仍不输出行动建议。等用户回复。

---

═══ 阶段三：生成行动方案和报告 ═══

用户说"生成报告"或"出方案"后，才执行。

第 7 步：规则匹配

对每个需要干预的品类 × 品牌 × 季节组合，按以下规则匹配（按优先级）：

规则	优先级	触发条件	建议动作
R1 紧急补货	P0	售罄率>50% 且 库销比<0.2 且 到店<120天	补货量 = 日均销量×30
R2 紧急清仓	P0	售罄率<25% 且 库销比>0.6 且 到店>120天（或过季≥2季）；或 售罄率<25% 且 到店>360天（不论库销比，超一年极低售罄=确定性滞销）	≤5折深度清仓
R3 促销加速	P1	售罄率<40% 且 库销比>0.5 且 到店>60天（不满足R2）；或 售罄率 25%~40% 且 到店>360天（不论库销比，Step C 已将其归入 Q3）	7-8折促销
R4 过季清尾	P1	售罄率≥40% 且 库销比>0.5（Q2）且 过季≥1季	6-7折清尾
R5 新品观察	P2	到店<60天	按周监控，4周无起色降为R3
R6 健康维持	—	不命中以上规则	维持现有策略

注意：建议折扣力度必须参考当前 discount_rate，不能和现有折扣重叠。补货量必须基于 retail_qty 计算。

第 8 步：如果需要下钻其他未分析品类

对阶段二未下钻的 🔴/⚠️/🟢⚡ 品类，自动补充下钻查询（查询 D），然后一并应用规则。

第 9 步：生成最终 HTML 报告 + xlsx 行动计划

HTML 报告（给管理层看）：

参考 references/report-html-spec.md 的完整规范。至少包含：

1. KPI 总览卡片（含环比）
2. 四象限气泡图或网格图
3. 品类诊断明细表
4. 品牌×季节下钻明细表（滞销 + 补货两张）
5. 重点风险提示卡片
6. 行动汇总统计

xlsx 行动计划表（给运营执行）：

列：优先级 | 行动类型 | 品类 | 品牌 | 季节 | 库存量 | 库存市值 | 售罄率 | 库销比 | 到店天数 | 当前折扣 | 建议折扣 | 建议动作 | 预估资金释放 | 复查日期

按优先级排序（P0 > P1 > P2），P0 行高亮。

第 10 步：输出

在对话中告诉用户：

📋 库存诊断报告和行动计划已生成

- 紧急补货（P0）：{N} 项
- 紧急清仓（P0）：{N} 项，涉及库存市值 {X} 万
- 促销加速（P1）：{N} 项
- 过季清尾（P1）：{N} 项

[查看诊断报告](HTML路径)
[查看行动计划表](xlsx路径)

---

可选：What-if 压力测试

仅在以下情况执行：

1. 用户主动要求（如"618 销量翻倍撑不撑得住"）
2. 阶段二发现高危渠道时，建议用户执行

逻辑：假设销量增长 X%，补货量不变，计算各渠道断货倒计时 = 当前库存 ÷ (新销量 - 补货量)。

---

核心指标含义速查

• 售罄率（Y 轴）= 销售市值 ÷ (库存市值 + 销售市值)。越高越好，40% 是基准线。
• 库销比（X 轴）= 库存数量 ÷ 销售数量。越低越健康，0.5 是警戒线。
• 到店天数 = 修正系数。<60天放宽，>90天加严。
• 两个指标交叉得到四象限，这是唯一分类方法。

---

常见错误（必须避免）

1. ❌ 用"上市时间""新旧品"等维度代替四象限分类 → 分类只能用售罄率×库销比
2. ❌ 阶段一就输出行动建议和折扣方案 → 行动方案只在阶段三
3. ❌ 一口气跑完所有步骤不停顿 → 每个阶段结束必须等用户
4. ❌ 只用纯文本输出分析结果 → 必须生成 HTML 文件
5. ❌ 忽略 🟢⚡ 不做补货评估 → 🟢⚡ = 断货，必须下钻
6. ❌ 建议折扣没看当前折扣率 → 必须参考 discount_rate
7. ❌ 说"建议补货"但不给数量 → 补货量 = 日均销量 × 30
8. ❌ 修改 timeConstraint → 查询 A/C/D 的 timeConstraint 必须原样复制，不能改成范围查询（>=、BETWEEN）或 30 天聚合
9. ❌ 自己算售罄率和库销比 → 必须直接使用 API 返回的 sell_trough_rate 和 stock_to_sales_ratio 字段值，不要用其他字段除法重算
10. ❌ 库销比接近 0（如 0.00005）还继续用 → 这说明查询出错了，必须停下来检查 timeConstraint 是否被改动