大促前盘货量化KPI与补货触发阈值 — 盘货差距分析/补货优先级/紧急空运决策框架

"""
大促前盘货量化KPI与补货触发阈值
基于《全链路管理》陈凤霞 第六章第二节
差距分析 + 空运ROI决策 + 补货优先级排序
"""
import numpy as np
import pandas as pd
from dataclasses import dataclass, field
from typing import Dict, List, Optional
import warnings
warnings.filterwarnings('ignore')


@dataclass
class PromoSKUProfile:
    """大促SKU档案"""
    sku_id: str
    sku_name: str
    abc_class: str
    unit_margin: float              # 单品毛利
    promo_price_premium: float      # 大促期间相对日常的价格溢价系数（通常>1因为大促期间需求高）

    # 当前库存状态
    current_stock_fba: int
    current_stock_own_wh: int
    confirmed_inbound_units: int    # 已确认海运到货
    days_to_promo: int              # 距大促天数

    # 需求预测
    last_promo_actual_sales: int    # 上次大促实际销量
    yoy_growth_factor: float = 1.3  # 增长系数

    # 物流成本
    sea_freight_unit: float = 3.5   # 海运单件成本
    air_freight_unit: float = 15.0  # 空运单件成本


class PrePromoStocktakingAnalyzer:
    """大促前盘货分析器"""

    def forecast_promo_demand(self, sku: PromoSKUProfile) -> int:
        """预测大促需求件数"""
        return int(sku.last_promo_actual_sales * sku.yoy_growth_factor)

    def compute_inventory_gap(self, sku: PromoSKUProfile) -> Dict:
        """计算库存缺口"""
        total_available = (sku.current_stock_fba + sku.current_stock_own_wh
                           + sku.confirmed_inbound_units)
        forecast = self.forecast_promo_demand(sku)
        gap_units = max(forecast - total_available, 0)
        gap_ratio = gap_units / max(forecast, 1)

        return {
            'sku_id': sku.sku_id,
            'total_available': total_available,
            'forecast_demand': forecast,
            'gap_units': gap_units,
            'gap_ratio': gap_ratio,
            'gap_ratio_pct': f"{gap_ratio:.0%}",
            'has_gap': gap_units > 0,