Business Metric-Aware Forecasting for Inventory Management

1. 解决的问题

核心思想：库存健康诊断不是"某个 SKU 库存多少"，而是回答三个问题：① 这批货还能动吗（FSN分级）？② 过多还是过少（Over/Under stock 三态）？③ 为什么和计划不一样（供应计划方差归因到4类根因）。同时严格区分「预测准确率（Forecast Accuracy）」和「计划准确率（Plan Accuracy）」——两者可以完全脱钩。

2. 核心算法逻辑

核心思想：库存健康诊断不是"某个 SKU 库存多少"，而是回答三个问题：① 这批货还能动吗（FSN分级）？② 过多还是过少（Over/Under stock 三态）？③ 为什么和计划不一样（供应计划方差归因到4类根因）。同时严格区分「预测准确率（Forecast Accuracy）」和「计划准确率（Plan Accuracy）」——两者可以完全脱钩。

3. 业务应用场景

- 业务问题：10 个在售 SKU，哪些是死库高风险？哪些已经过库？ - 预期产出：

- 业务问题：618 大促结束后，某 SKU 实际期末库存比计划低 800 件，导致大促期间断货 3 天。是需求预测问题、还是供应商没按时交货？ - 归因输出：

4. 输入数据要求

请查看原始代码模板获取输入规格。

5. 输出结果

请查看原始代码模板获取输出规格。

6. 业务价值 / ROI

• ROI 预估：
• FBA 库龄费优化：识别 Steam-Old 类高价值死库，提前 60 天清仓可节省 $890/月×3 月 = $2,670
• 供应计划归因精度提升：快速定位主因后，下次大促的缺口可减少约 50%，对应保护 BSR 排名价值约 $20,000-$50,000
• Forecast vs Plan Accuracy 对齐：将 MAPE 优化改为 TC 优化，按 Google Research 实测可降低库存成本 30-54%
• 实施难度：⭐⭐☆☆☆（2/5）— 规则+统计，可接入现有 ERP/数据仓库
• 优先级评分：⭐⭐⭐⭐⭐（5/5）— 每月必做的运营诊断，且是供应计划优化的起点

7. 代码模板

代码块数量：9 · 路径：paper2skills-code/supply_chain/inventory_health_aging_attribution

"""
Skill-Inventory-Health-Aging-Attribution
基于 JSCDM 2024 (FSN+ML) + OSCM Forum 2023 (Gradient Boosting) +
    ACM ICGAIB 2025 (慢动库+库龄) + arXiv:2404.07523 (供应计划归因) +
    arXiv:2308.13118 Google Research (Forecast vs Plan Accuracy)
母婴跨境 DTC 库存健康诊断 + 库龄分析 + 供应计划方差归因
"""

import numpy as np
import pandas as pd
from dataclasses import dataclass, field
from enum import Enum


class FSNCategory(Enum):
    FAST    = "F-快动"
    SLOW    = "S-慢动"
    NONMOVE = "N-死库"


class StockStatus(Enum):
    UNDERSTOCK = "欠库"
    NORMAL     = "正常"
    OVERSTOCK  = "过库"


FBA_AGING_RATES = {
    (0, 90):   0.87,
    (91, 180):  1.58,
    (181, 270): 4.78,
    (271, 999): 7.95,
}


@dataclass
class SKUInventory:
    sku_id: str
    current_qty: int
    unit_cost: float
    cubic_feet_per_unit: float
    avg_daily_sales: float
    demand_forecast_30d: float
    days_in_fba: int
    planned_qty: int = 0
    actual_received_qty: int = 0
    planned_receive_date: str = ""
    actual_receive_date: str = ""

    @property
    def cover_days(self) -> float:
        return self.current_qty / max(self.avg_daily_sales, 0.1)

    @property
    def inventory_value(self) -> float:
        return self.current_qty * self.unit_cost

    @property
    def fsn_category(self) -> FSNCategory:
        if self.cover_days < 30:
            return FSNCategory.FAST

8. 论文来源

• 2308.13118
• 2404.07523