促销活动供应侧ROI归因 — 备货成本+促销库存持有成本+尾货损失的全成本核算

"""
促销活动供应侧 ROI 归因模型
功能：备货成本 / 持有成本 / 尾货损失 / 退货增量成本 / 真实促销ROI计算
输入：大促备货数据 + 销售结果 + 退货数据
输出：供应侧成本拆解 + 真实ROI + 改善建议
"""
import numpy as np
import pandas as pd
import warnings
warnings.filterwarnings('ignore')


def compute_promo_supply_cost(
    backup_gmv_value: float,          # 备货货值（元）
    backup_lead_days: int,            # 提前备货天数（vs正常）
    capital_rate: float = 0.06,       # 年资金成本
    remaining_inventory_pct: float = 0.25,  # 大促后剩余库存比例
    clearance_discount: float = 0.30, # 清仓折扣率（30%=七折）
    promo_return_rate: float = 0.06,  # 大促期间退货率（高于平时）
    normal_return_rate: float = 0.03, # 正常退货率
    promo_gmv: float = 3_000_000,     # 大促GMV
    handling_cost_per_return: float = 80,  # 每次退货处理成本
):
    """计算促销供应侧全成本"""
    
    # 1. 备货持有成本（提前备货的资金占用）
    holding_cost = backup_gmv_value * capital_rate * backup_lead_days / 365
    
    # 2. 尾货折价损失
    remaining_value = backup_gmv_value * remaining_inventory_pct
    clearance_loss = remaining_value * clearance_discount  # 按折扣计算损失
    
    # 3. 大促退货增量成本
    promo_orders = promo_gmv / 150  # 假设均单价150
    incremental_returns = promo_orders * (promo_return_rate - normal_return_rate)
    return_cost = incremental_returns * handling_cost_per_return
    
    # 4. 汇总
    total_supply_cost = holding_cost + clearance_loss + return_cost
    
    return {
        'holding_cost': round(holding_cost),
        'clearance_loss': round(clearance_loss),
        'return_cost': round(return_cost),
        'total_supply_cost': round(total_supply_cost),
        'supply_cost_rate': round(total_supply_cost / promo_gmv * 100, 2),
    }


def compute_true_promo_roi(
    promo_gmv: float,
    gross_margin_rate: float,
    ad_spend: float,
    supply_cost: float,
    baseline_gmv_daily: float,
    promo_days: int = 5,
):
    """计算促销真实ROI（含供应侧成本）"""
    # 增量GMV（大促GMV - 正常同期GMV）
    normal_period_gmv = baseline_gmv_daily * promo_days