Cross-Platform Brand Search Volume — 品牌搜索量作为营销效果领先指标

"""
Cross-Platform Brand Search Volume — 品牌搜索量监测与因果效应分析
基于 Prophet (arXiv:1707.03264) + Causal Impact (arXiv:1409.3119) 原理

依赖: numpy, statistics, dataclasses (标准库)
生产环境: 替换 MockBSVData 为 Google Trends API + Amazon Brand Analytics API
"""

from dataclasses import dataclass, field
import numpy as np
from statistics import mean, stdev


@dataclass
class BSVDataPoint:
    """品牌搜索量数据点"""
    date: str
    google_bsv: int             # Google Trends 相对值（0-100）
    amazon_bsv: int             # Amazon Brand Analytics 搜索量
    tiktok_bsv: int             # TikTok 站内搜索量（若有）
    ad_spend: float             # 当日广告花费
    gmv: float                  # 当日 GMV
    has_marketing_event: bool = False  # 是否有营销事件（KOL发帖/大促）


@dataclass
class BSVAnalysisResult:
    """BSV 分析结果"""
    period: str
    avg_bsv_google: float
    avg_bsv_amazon: float
    bsv_growth_wow: float       # 周同比增长率
    bsv_gmv_correlation: float  # BSV → GMV 相关性
    lead_lag_days: int          # BSV 领先 GMV 的天数
    causal_lift_pct: float      # 营销事件带来的增量 BSV %
    recommendation: str


class BrandSearchVolumeTracker:
    """
    品牌搜索量追踪与分析器

    核心功能：
    1. 跨平台 BSV 趋势监测
    2. BSV → GMV 领先指标验证
    3. 营销事件的 Causal Impact 估计
    4. 季节性分解（Prophet 简化版）
    """

    def normalize_bsv(self, values: list) -> list:
        """将 BSV 标准化为 0-100 的相对指数"""
        max_v = max(values) if values else 1
        return [round(v / max_v * 100, 1) for v in values]

    def compute_lead_lag(self, bsv_series: list, gmv_series: list,
                         max_lag: int = 14) -> int:
        """计算 BSV 领先 GMV 的天数（互相关）"""
        if len(bsv_series) < max_lag + 5:
            return 7  # 默认7天
        best_corr, best_lag = -1, 0