@miraiva_test/miravia-order-report 0.1.13

package/dist/scripts/report_v4.py

@@ -0,0 +1,1694 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""V4 Unified Dashboard Renderer.
+
+Receives sub-order granularity rows, computes all dashboard metrics
+and outputs as JSON-injected HTML via Jinja2 template.
+
+Data injection: window.DATA = {...}
+Frontend JS handles time-range filtering (slice dailyData) and chart rendering.
+"""
+from __future__ import annotations
+
+import json
+import re
+import base64
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List
+
+from i18n import get_translations, TRANSLATIONS, SUPPORTED_LANGS
+
+
+# -------- utilities --------
+
+def _safe_num(series, fillna=0):
+    import pandas as pd
+    return pd.to_numeric(series, errors="coerce").fillna(fillna)
+
+
+# Refund statuses that are inactive/cancelled (should NOT count toward refund amount/rate)
+_CANCELLED_REFUND_STATUSES = {
+    "REQUEST_CANCEL", "CANCEL", "CANCELLED", "REJECTED",
+    "BUYER_CANCEL", "SELLER_REJECT", "CLOSE", "CLOSED",
+}
+
+
+def _dedup_items(df):
+    """Deduplicate one-to-many refund expansion back to item granularity.
+
+    After the refund expansion in export_orders._flatten(), a single item with
+    N refund records produces N rows. For item-level metrics (GMV, item count,
+    cancel rate, AOV), we must count each item only ONCE.
+
+    Strategy: drop_duplicates by (order_id, order_item_id), keeping first row.
+    """
+    if df.empty:
+        return df
+    return df.drop_duplicates(subset=["order_id", "order_item_id"], keep="first")
+
+
+def _active_refund_rows(df):
+    """Get active (non-cancelled) refund rows, deduplicated by refund_id.
+
+    Used for refund amount and refund count calculations to avoid:
+    1. Double-counting the same refund_id (shouldn't happen but defensive)
+    2. Counting cancelled/rejected refund requests toward loss metrics
+    """
+    if df.empty:
+        return df
+    rmask = df["refund_id"].notna() & (df["refund_id"] != "")
+    rdf = df[rmask].copy()
+    if rdf.empty:
+        return rdf
+    # Filter out cancelled refund statuses
+    if "refund_status" in rdf.columns:
+        rdf = rdf[~rdf["refund_status"].fillna("").str.upper().isin(_CANCELLED_REFUND_STATUSES)]
+    # Deduplicate by refund_id
+    if not rdf.empty:
+        rdf = rdf.drop_duplicates(subset=["refund_id"], keep="first")
+    return rdf
+
+
+def _normalize_mp(val) -> str:
+    """Normalize marketplace to 'miravia' or 'ae'."""
+    if not val:
+        return "unknown"
+    s = str(val).lower()
+    if "miravia" in s:
+        return "miravia"
+    if "ae" in s or "m2a" in s or "aliexpress" in s:
+        return "ae"
+    return s
+
+
+def _common_currency(df) -> str:
+    return (df["currency"].dropna().iloc[0]
+            if not df.empty and not df["currency"].dropna().empty
+            else "EUR")
+
+
+# -------- country name normalization --------
+# Miravia API applies GDPR masking to ship_country, producing garbled names
+# like "E****a", "S***n", "P******|", "|***y" alongside original names
+# like "España", "Spain", "Portugal", "Italy". This mapping merges all
+# variants of the same country into one canonical name.
+
+_KNOWN_COUNTRIES: Dict[str, List[str]] = {
+    "Spain":           ["spain", "españa", "espana", "espanha"],
+    "Portugal":        ["portugal"],
+    "Italy":           ["italy", "italia"],
+    "France":          ["france", "francia"],
+    "Germany":         ["germany", "deutschland", "alemania"],
+    "United Kingdom":  ["united kingdom", "uk", "gran bretaña"],
+    "Poland":          ["poland", "polonia"],
+    "Netherlands":     ["netherlands", "países bajos", "holanda", "paesi bassi"],
+    "Belgium":         ["belgium", "bélgica", "belgio", "belgien"],
+    "Ireland":         ["ireland", "irlanda"],
+    "Austria":         ["austria"],
+    "Sweden":          ["sweden", "suecia", "svezia", "schweden"],
+    "Denmark":         ["denmark", "dinamarca", "danimarca", "dänemark"],
+    "Finland":         ["finland", "finlandia"],
+    "Norway":          ["norway", "noruega", "norvegia", "norwegen"],
+    "Switzerland":     ["switzerland", "suiza", "svizzera", "schweiz"],
+    "Greece":          ["greece", "grecia"],
+    "Czech Republic":  ["czech republic", "chequia", "repubblica ceca"],
+    "Romania":         ["romania", "rumanía"],
+    "Hungary":         ["hungary", "hungría", "ungheria", "ungarn"],
+    "Bulgaria":        ["bulgaria"],
+    "Croatia":         ["croatia", "croacia", "croazia"],
+    "Slovakia":        ["slovakia", "eslovaquia", "slovacchia"],
+    "Slovenia":        ["slovenia", "eslovenia"],
+    "Luxembourg":      ["luxembourg", "luxemburgo", "lussemburgo"],
+    "Latvia":          ["latvia", "letonia"],
+    "Estonia":         ["estonia"],
+    "Lithuania":       ["lithuania", "lituania"],
+}
+
+# Pre-build reverse lookup: lowercase variant -> canonical name
+_COUNTRY_LOOKUP: Dict[str, str] = {}
+for _canon, _variants in _KNOWN_COUNTRIES.items():
+    for _v in _variants:
+        _COUNTRY_LOOKUP[_v.lower()] = _canon
+    _COUNTRY_LOOKUP[_canon.lower()] = _canon
+
+
+def _normalize_country(val) -> str:
+    """Normalize country names including GDPR masked variants and language variants.
+
+    Miravia API applies GDPR masking using * and | as mask characters:
+      'E****a'   -> 'Spain'    (middle chars masked with *)
+      'p******|' -> 'Portugal' (last char masked with |)
+      '|***y'    -> 'Italy'    (first char masked with |)
+      'S***n'    -> 'Spain'    (middle chars masked with *)
+
+    Both mask characters are replaced with regex wildcards for matching.
+    """
+    if not val or not str(val).strip():
+        return "Unknown"
+    raw = str(val).strip()
+    key = raw.lower()
+
+    # 1. Direct lookup (handles plain names in EN/ES/IT/DE/PT)
+    if key in _COUNTRY_LOOKUP:
+        return _COUNTRY_LOOKUP[key]
+
+    # 2. De-mask: if contains * or |, build regex and match against known names
+    if "*" in raw or "|" in raw:
+        escaped = re.escape(raw)
+        # Replace escaped asterisks and pipes with wildcard dots
+        pattern_str = escaped.replace(r"\*", ".").replace(r"\|", ".")
+        pattern = re.compile(f"^{pattern_str}$", re.IGNORECASE)
+        for variants in _KNOWN_COUNTRIES.values():
+            for variant in variants:
+                if pattern.match(variant):
+                    return _COUNTRY_LOOKUP[variant.lower()]
+
+    return raw
+
+
+# -------- category classification --------
+
+_CATEGORY_KEYWORDS = [
+    ("Home & Living", ["lamp", "led", "alfombra", "cortina",
+                "cojín", "mueble", "organiza", "decoración"]),
+    ("Electronics", ["auriculares", "bluetooth", "altavoz",
+                "reloj inteligente", "cargador", "móvil",
+                "tablet", "electrónic"]),
+    ("Kitchen", ["sartén", "cookware", "cuchillo", "cafetera",
+                "cocina", "kitchen", "kitchenware"]),
+    ("Sports & Outdoors", ["mochila", "bicicleta", "patinete",
+                "deporte", "fitness", "outdoor", "balón"]),
+    ("Beauty & Personal Care", ["crema", "maquillaje", "champú",
+                "perfume", "uña", "cuidado"]),
+    ("Fashion & Accessories", ["ropa", "camiseta", "pantalón", "vestido",
+                "chaqueta", "zapato", "bolso"]),
+    ("Baby & Toys", ["bebé", "niño", "juguetes", "embarazo"]),
+    ("Auto Parts", ["coche", "car ", "auto", "moto"]),
+]
+
+
+# Category internal label -> i18n key mapping
+_CATEGORY_KEY_MAP = {
+    "Home & Living": "cat_home", "Electronics": "cat_digital", "Kitchen": "cat_kitchen",
+    "Sports & Outdoors": "cat_sports", "Beauty & Personal Care": "cat_beauty", "Fashion & Accessories": "cat_fashion",
+    "Baby & Toys": "cat_baby", "Auto Parts": "cat_auto",
+}
+
+
+def _classify_category(name, t=None) -> str:
+    if not name:
+        return t["cat_other"] if t else "Other"
+    s = str(name).lower()
+    for cat, keywords in _CATEGORY_KEYWORDS:
+        for kw in keywords:
+            if kw.lower() in s:
+                if t:
+                    return t.get(_CATEGORY_KEY_MAP.get(cat, "cat_other"), cat)
+                return cat
+    return t["cat_other"] if t else "Other"
+
+
+def _check_buyer_id_available(df) -> bool:
+    """Check if buyer_id field has any non-empty values in the dataframe.
+
+    When buyer_id is unavailable (e.g., invite-test token), the 'bu' metric
+    is set to 0 (no reliable buyer data). This flag lets the frontend
+    display 'N/A' or hide the buyer count section to avoid misleading users.
+    """
+    if df.empty:
+        return True  # Default: assume available (no data to check)
+    buyer_ids = df["buyer_id"].dropna()
+    buyer_ids = buyer_ids[buyer_ids != ""]
+    return len(buyer_ids) > 0
+
+
+# -------- daily data --------
+
+def _build_daily_data(df, range_start: str = None, range_end: str = None) -> List[Dict]:
+    """Build dailyData array with per-platform breakdown.
+
+    Each entry: {ds, mO, aO, mI, aI, mG, aG, mR, aR, mC, aC, bu, rAmt, mRA, aRA}
+
+    - mO/aO: unique order count (for AOV denominator)
+    - mI/aI: item (sub-order) count (for cancel/refund rate denominator)
+    - mR/aR, mC/aC: item-level refund/cancel counts
+    - mRA/aRA: per-platform refund amounts
+
+    Deduplication: item-level metrics use deduplicated rows (one per item);
+    refund metrics use active refunds only (deduplicated by refund_id).
+
+    Generates entries for ALL calendar days in the query range (including
+    days with zero orders) so that DAYS = dailyData.length always matches
+    the actual calendar span.
+    """
+    import pandas as pd
+    if df.empty:
+        # Even with no data, fill the full date range with zeros
+        if range_start and range_end:
+            start = pd.to_datetime(range_start, errors="coerce")
+            end = pd.to_datetime(range_end, errors="coerce")
+            if pd.notna(start) and pd.notna(end):
+                all_dates = pd.date_range(start.normalize(), end.normalize(), freq="D")
+                return [{"ds": str(d.date()), "mO": 0, "aO": 0, "mI": 0, "aI": 0,
+                         "mG": 0, "aG": 0, "mR": 0, "aR": 0, "mC": 0, "aC": 0,
+                         "bu": 0, "rAmt": 0, "mRA": 0, "aRA": 0}
+                        for d in all_dates]
+        return []
+
+    # Deduplicate for item-level metrics (GMV, item count, cancel)
+    df_items = _dedup_items(df)
+    s = df_items.copy()
+    s["_d"] = pd.to_datetime(s["created_at"], errors="coerce").dt.date
+    s["_paid"] = _safe_num(s["buyer_paid"])
+    s["_mp"] = s["marketplace"].apply(_normalize_mp)
+    s["_is_cancel"] = s["is_canceled"].fillna(False).astype(bool)
+    s = s.dropna(subset=["_d"])
+    if s.empty:
+        return []
+
+    # Active refunds for refund metrics (deduplicated by refund_id, exclude cancelled)
+    df_refunds = _active_refund_rows(df)
+    r = df_refunds.copy() if not df_refunds.empty else pd.DataFrame()
+    if not r.empty:
+        r["_d"] = pd.to_datetime(r["created_at"], errors="coerce").dt.date
+        r["_mp"] = r["marketplace"].apply(_normalize_mp)
+        r["_refund_amt"] = _safe_num(r["refund_amount"])
+        r = r.dropna(subset=["_d"])
+
+    # Build lookup of per-day stats
+    day_map: Dict[str, Dict] = {}
+    for d, dg in s.groupby("_d"):
+        mir = dg[dg["_mp"] == "miravia"]
+        ae = dg[dg["_mp"] == "ae"]
+        buyer_ids = dg["buyer_id"].dropna()
+        buyer_ids = buyer_ids[buyer_ids != ""]
+        bu = int(buyer_ids.nunique()) if len(buyer_ids) > 0 else 0
+        # Refund stats for this day from active refunds
+        if not r.empty:
+            r_day = r[r["_d"] == d]
+            r_mir = r_day[r_day["_mp"] == "miravia"]
+            r_ae = r_day[r_day["_mp"] == "ae"]
+            mR = len(r_mir)
+            aR = len(r_ae)
+            rAmt = round(float(r_day["_refund_amt"].sum()), 2)
+            mRA = round(float(r_mir["_refund_amt"].sum()), 2)
+            aRA = round(float(r_ae["_refund_amt"].sum()), 2)
+        else:
+            mR = aR = 0
+            rAmt = mRA = aRA = 0
+        day_map[str(d)] = {
+            "ds": str(d),
+            "mO": int(mir["order_id"].nunique()),
+            "aO": int(ae["order_id"].nunique()),
+            "mI": len(mir),
+            "aI": len(ae),
+            "mG": round(float(_safe_num(mir["buyer_paid"]).sum()), 2),
+            "aG": round(float(_safe_num(ae["buyer_paid"]).sum()), 2),
+            "mR": mR,
+            "aR": aR,
+            "mC": int(mir["_is_cancel"].sum()),
+            "aC": int(ae["_is_cancel"].sum()),
+            "bu": bu,
+            "rAmt": rAmt,
+            "mRA": mRA,
+            "aRA": aRA,
+        }
+
+    # Determine full date range (prefer explicit range params, fallback to data min/max)
+    if range_start and range_end:
+        start = pd.to_datetime(range_start, errors="coerce").normalize()
+        end = pd.to_datetime(range_end, errors="coerce").normalize()
+    else:
+        dates = pd.to_datetime(s["created_at"], errors="coerce")
+        start = dates.min().normalize()
+        end = dates.max().normalize()
+
+    all_dates = pd.date_range(start, end, freq="D")
+    zero_entry = {"mO": 0, "aO": 0, "mI": 0, "aI": 0, "mG": 0, "aG": 0,
+                  "mR": 0, "aR": 0, "mC": 0, "aC": 0, "bu": 0, "rAmt": 0,
+                  "mRA": 0, "aRA": 0}
+
+    daily = []
+    for d in all_dates:
+        ds = str(d.date())
+        if ds in day_map:
+            daily.append(day_map[ds])
+        else:
+            daily.append({"ds": ds, **zero_entry})
+
+    return daily
+
+
+# -------- static distributions --------
+
+def _build_skus(df, n=20, t=None) -> List[Dict]:
+    """Top SKUs with per-platform sales and refund rates.
+
+    Uses deduplicated item rows for quantity/price, and active refunds for refund metrics.
+    """
+    if df.empty:
+        return []
+    # Item-level: deduplicate to avoid counting same item multiple times
+    s = _dedup_items(df).copy()
+    s["_mp"] = s["marketplace"].apply(_normalize_mp)
+    s["quantity"] = _safe_num(s["quantity"])
+    s["_paid"] = _safe_num(s["buyer_paid"])
+    # Mark items that have at least one active refund
+    active_refund_items = set()
+    df_refunds = _active_refund_rows(df)
+    if not df_refunds.empty:
+        active_refund_items = set(df_refunds["order_item_id"].dropna().unique())
+    s["_has_active_refund"] = s["order_item_id"].isin(active_refund_items).astype(int)
+
+    # Active refund amounts per item (summed if multiple active refunds)
+    refund_amt_by_item: Dict[str, float] = {}
+    if not df_refunds.empty:
+        for iid, g in df_refunds.groupby("order_item_id"):
+            refund_amt_by_item[str(iid)] = float(_safe_num(g["refund_amount"]).sum())
+    s["_refund_amt"] = s["order_item_id"].map(lambda x: refund_amt_by_item.get(str(x), 0))
+
+    results = []
+    for (sku, name), g in s.groupby(["sku", "product_name"], dropna=False):
+        mir = g[g["_mp"] == "miravia"]
+        ae = g[g["_mp"] == "ae"]
+        mq = int(mir["quantity"].sum())
+        aq = int(ae["quantity"].sum())
+        ip_vals = _safe_num(g["unit_price"])
+        pp_vals = _safe_num(g["buyer_paid"])
+        refund_count = int(g["_has_active_refund"].sum())
+        rr = refund_count / len(g) if len(g) > 0 else 0
+        mRA = round(float(mir["_refund_amt"].sum()), 2) if not mir.empty else 0
+        aRA = round(float(ae["_refund_amt"].sum()), 2) if not ae.empty else 0
+        results.append({
+            "s": str(sku) if sku else "-",
+            "nm": str(name) if name else "-",
+            "mq": mq, "aq": aq,
+            "ip": round(float(ip_vals.iloc[0]) if len(ip_vals) > 0 else 0, 2),
+            "pp": round(float(pp_vals.iloc[0]) if len(pp_vals) > 0 else 0, 2),
+            "rr": round(rr, 4),
+            "mRA": mRA, "aRA": aRA,
+            "cat": _classify_category(name, t=t),
+        })
+    results.sort(key=lambda x: -(x["mq"] + x["aq"]))
+    return results[:n]
+
+
+def _normalize_city_series(series):
+    """Normalize GDPR-masked city names by matching against clean values in the same dataset.
+
+    Strategy: collect all non-masked city names, then for each masked city build a regex
+    from its visible chars (treating * and | as wildcards) and try to match a clean
+    counterpart. If matched → merge into the clean name; if not → keep the masked
+    value as-is so it still participates in statistics.
+
+    Examples (given 'Madrid' also exists in the dataset):
+      'M****d'       -> 'Madrid'    (regex ^M....d$ matches)
+      '**********|'  -> unchanged   (no 11-char clean city matches)
+      'A**a Abla'    -> unchanged   (no match found)
+    """
+    # Collect all clean (non-masked) city names from this dataset
+    clean_names = set()
+    for val in series:
+        v = str(val).strip() if val else ""
+        if v and not re.search(r'[*|]', v):
+            clean_names.add(v)
+
+    if not clean_names:
+        return series  # No clean names to match against
+
+    # Build a cache for masked -> clean mappings to avoid repeated regex work
+    cache: Dict[str, str] = {}
+
+    def _normalize_one(val):
+        if not val or not str(val).strip():
+            return val
+        raw = str(val).strip()
+
+        # Not masked -> return as-is
+        if not re.search(r'[*|]', raw):
+            return raw
+
+        # Check cache
+        if raw in cache:
+            return cache[raw]
+
+        # Build regex from masked value
+        escaped = re.escape(raw)
+        pattern_str = escaped.replace(r"\*", ".").replace(r"\|", ".")
+        try:
+            pattern = re.compile(f"^{pattern_str}$", re.IGNORECASE)
+        except re.error:
+            cache[raw] = raw
+            return raw
+
+        # Try to match against clean city names in the same dataset
+        for clean in clean_names:
+            if pattern.match(clean):
+                cache[raw] = clean
+                return clean
+
+        # No match found - keep masked value (still participates in stats)
+        cache[raw] = raw
+        return raw
+
+    return series.apply(_normalize_one)
+
+
+def _build_cities(df, n=10) -> List[Dict]:
+    """City distribution with deduplication."""
+    if df.empty:
+        return []
+    s = _dedup_items(df).copy()
+    s["city"] = s["city"].fillna("")
+    s = s[s["city"] != ""]
+    if s.empty:
+        return []
+    # Normalize GDPR-masked cities: merge with clean counterparts where possible
+    s["city"] = _normalize_city_series(s["city"])
+    g = s.groupby("city").size().reset_index(name="o")
+    g = g.sort_values("o", ascending=False).head(n)
+    return [{"n": r["city"], "o": int(r["o"])} for _, r in g.iterrows()]
+
+
+def _build_carriers(df, n=15) -> List[Dict]:
+    """Carrier stats with deduplication for accurate refund/cancel rates."""
+    if df.empty:
+        return []
+    # Deduplicate for item-level counts
+    s = _dedup_items(df).copy()
+    s["_mp"] = s["marketplace"].apply(_normalize_mp)
+    s["shipping_provider"] = s["shipping_provider"].fillna("Unknown")
+    s["_is_cancel"] = s["is_canceled"].fillna(False).astype(bool)
+    # Mark items with active refund
+    active_refund_items = set()
+    df_refunds = _active_refund_rows(df)
+    if not df_refunds.empty:
+        active_refund_items = set(df_refunds["order_item_id"].dropna().unique())
+    s["_has_refund"] = s["order_item_id"].isin(active_refund_items)
+
+    results = []
+    for carrier, g in s.groupby("shipping_provider"):
+        mir = g[g["_mp"] == "miravia"]
+        ae = g[g["_mp"] == "ae"]
+        total = len(g)
+        cr = float(g["_is_cancel"].sum()) / total if total else 0
+        rr = float(g["_has_refund"].sum()) / total if total else 0
+        results.append({
+            "nm": carrier, "mo": len(mir), "ao": len(ae),
+            "cr": round(cr, 4), "rr": round(rr, 4),
+        })
+    results.sort(key=lambda x: -(x["mo"] + x["ao"]))
+    return results[:n]
+
+
+# -------- refund reason classification --------
+
+_REASON_CATEGORIES = {
+    "system_error": [
+        "fallo en el sistema", "system error", "system failure",
+        "errore di sistema", "errore del sistema", "guasto del sistema",
+    ],
+    "out_of_stock": [
+        "no hay stock", "out of stock", "out_of_stock", "fuera de stock",
+        "sin stock", "esaurito", "non disponibile", "overtime_close_order",
+    ],
+    "preparation_delay": [
+        "demora", "preparación del pedido", "preparation delay",
+        "ritardo preparazione", "ritardo nella preparazione",
+    ],
+    "seller_unresponsive": [
+        "seller did not respond", "vendedor no respondió", "no respond",
+        "venditore non ha risposto", "sin respuesta del vendedor",
+    ],
+    "shipping_delay": [
+        "no llegará tan rápido", "delivery too slow", "shipping delay", "tarda",
+        "slow delivery", "late", "retraso", "ritardo consegna", "consegna lenta",
+        "llegará tarde", "tiempo de entrega", "envío lento", "not arrive",
+        "didn't arrive", "not received", "no recibido", "non ricevuto",
+        "no he recibido", "non ho ricevuto",
+    ],
+    "wrong_item": [
+        "wrong item", "artículo incorrecto", "recibido no es correcto",
+        "producto equivocado", "prodotto sbagliato", "sent wrong",
+        "articolo errato", "item received is not",
+    ],
+    "missing_parts": [
+        "faltan partes", "missing parts", "accesorios", "accessories",
+        "parti mancanti", "incompleto",
+    ],
+    "quantity_mismatch": [
+        "más o menos artículos", "más/menos", "más o menos",
+        "quantity", "missing item",
+        "più o meno articoli", "received more or less", "cantidad incorrecta",
+        "pezzi mancanti", "fewer items", "more items",
+    ],
+    "quality_issue": [
+        "damaged", "dañado", "roto", "broken", "defect", "quality",
+        "danneggiato", "paquete dañ", "artículo y paquete dañ",
+        "daños", "defectuoso", "difettoso", "calidad",
+    ],
+    "description_mismatch": [
+        "description", "no coincide", "not as described", "inaccurate",
+        "descripción", "non corrisponde", "foto", "imagen", "tamaño",
+        "size", "color", "different from", "not match",
+        "precio del artículo", "error en el precio",
+        "not as expected", "no es lo esperado",
+    ],
+    "buyer_regret": [
+        "no longer need", "don't need", "ya no necesito", "changed mind",
+        "no need", "no lo necesito", "i don't need",
+        "non ho più bisogno", "cambio idea", "found cheaper",
+        "encontrado más barato", "barato en otro sitio",
+        "do not need", "don't want", "no lo quiero",
+        "no necesito", "precio mejor", "solicitud de cancelación",
+        "método de pago", "payment method",
+    ],
+    "customs_issue": [
+        "customs", "aduana", "held at customs", "retenido", "dogana",
+    ],
+    "logistics_issue": [
+        "lost", "tracking", "returned", "lost in transit", "carrier",
+        "devuelto", "perdido", "tracking shows", "paquete perdido",
+        "smarrito", "reso", "pérdida", "punto de recogida",
+        "empresa de mensajería", "accidente",
+    ],
+    "shipping_method": [
+        "cambiar el método de envío", "change shipping", "metodo di spedizione",
+        "cambiar la dirección", "change address", "indirizzo",
+        "problema con la dirección", "dirección de entrega",
+    ],
+    "refund_agreement": [
+        "reembolso acordado", "acordado con el vendedor", "agreement",
+        "accordo", "refund agreed", "acordado", "acordado con la tienda",
+    ],
+}
+
+
+def _classify_refund_reason(reason_text: str) -> str:
+    """Classify refund reason text into a category for differentiated advice."""
+    if not reason_text:
+        return "unknown"
+    lower = reason_text.lower()
+    for category, keywords in _REASON_CATEGORIES.items():
+        for kw in keywords:
+            if kw in lower:
+                return category
+    return "unknown"
+
+
+def _generate_smart_rec(label: str, category: str, top_skus: List[str],
+                        carrier_str: str, dp: str, pc: float, amt: float,
+                        currency: str, t=None) -> str:
+    """Generate data-driven, contextual recommendation for a refund reason."""
+    pct_str = f"{pc * 100:.1f}%"
+    amt_str = f"{amt:.2f} {currency}"
+    sku_mention = top_skus[0] if top_skus else ""
+    carrier_mention = carrier_str if carrier_str != "N/A" else ""
+
+    # Use i18n templates if available
+    if t:
+        tpl_key = f"rec_{category}"
+        tpl = t.get(tpl_key)
+        if tpl:
+            return tpl.format(
+                reason=label, pct=pct_str, amt=amt_str,
+                sku=sku_mention, carrier=carrier_mention, duty=dp,
+            )
+        # Fallback to generic with data
+        return t.get("rec_unknown", "").format(
+            reason=label, pct=pct_str, amt=amt_str,
+            sku=sku_mention, carrier=carrier_mention, duty=dp,
+        ) or f"For '{label}' refunds ({pct_str}, total {amt_str}), recommend checking related SKUs and logistics providers to optimize after-sales process."
+
+    # No i18n fallback (should not happen in practice)
+    return f"For '{label}' refunds ({pct_str}, total {amt_str}), recommend checking related SKUs and logistics providers to optimize after-sales process."
+
+
+def _build_ref_reasons(df, currency, t=None) -> List[Dict]:
+    """Refund reason breakdown using active refunds only."""
+    if df.empty:
+        return []
+    # Use active refunds only (exclude cancelled)
+    rdf = _active_refund_rows(df)
+    if rdf.empty:
+        return []
+    rdf = rdf.copy()
+    rdf["_amt"] = _safe_num(rdf["refund_amount"])
+    total = len(rdf)
+
+    results = []
+    for reason, g in rdf.groupby("refund_reason", dropna=False):
+        label = reason if reason else (t["ref_unspecified"] if t else "Unspecified")
+        pc = len(g) / total if total else 0
+        amt = float(g["_amt"].sum())
+        dp_counts = g["duty_party"].fillna("pending").value_counts()
+        dp = str(dp_counts.index[0]) if len(dp_counts) > 0 else "pending"
+        top_skus = [str(x) for x in g["sku"].dropna().unique()[:3]]
+        carriers = g["shipping_provider"].dropna().unique()
+        carrier_str = ", ".join(str(c) for c in carriers[:3]) if len(carriers) > 0 else "N/A"
+        ft = ", ".join(top_skus[:2]) if top_skus else "-"
+        category = _classify_refund_reason(str(label))
+        rec = _generate_smart_rec(
+            label, category, top_skus, carrier_str, dp, pc, amt,
+            currency if currency else "EUR", t=t,
+        )
+        results.append({
+            "r": str(label),
+            "pc": round(pc, 4),
+            "amt": round(amt, 2),
+            "dp": dp,
+            "ft": ft,
+            "detail": {
+                "skus": top_skus,
+                "trend": t["ref_detail_trend"] if t else "Statistics within data period",
+                "carriers": carrier_str,
+                "rec": rec,
+            },
+        })
+    results.sort(key=lambda x: -x["pc"])
+    return results
+
+
+def _build_ab_buyers(df) -> List[Dict]:
+    if df.empty:
+        return []
+    rmask = df["refund_id"].notna() & (df["refund_id"] != "")
+    rdf = df[rmask].copy()
+    if rdf.empty:
+        return []
+    rdf["_buyer"] = rdf["buyer_id"].fillna("").astype(str)
+    rdf.loc[rdf["_buyer"] == "", "_buyer"] = rdf["buyer_name"].fillna("").astype(str)
+    rdf = rdf[rdf["_buyer"] != ""]
+    if rdf.empty:
+        return []
+
+    df2 = df.copy()
+    df2["_buyer"] = df2["buyer_id"].fillna("").astype(str)
+    df2.loc[df2["_buyer"] == "", "_buyer"] = df2["buyer_name"].fillna("").astype(str)
+    df2 = df2[df2["_buyer"] != ""]
+    if df2.empty:
+        return []
+
+    total_orders = df2.groupby("_buyer")["order_id"].nunique()
+    refund_orders = rdf.groupby("_buyer")["order_id"].nunique()
+
+    results = []
+    for buyer in refund_orders.index:
+        o = int(total_orders.get(buyer, 0))
+        rf = int(refund_orders[buyer])
+        if o < 3:
+            continue
+        rt = rf / o if o > 0 else 0
+        risk = "high" if rt > 0.30 else "mid" if rt > 0.20 else "low"
+        results.append({"id": buyer, "o": o, "rf": rf, "rt": round(rt, 4), "risk": risk})
+    results.sort(key=lambda x: -x["rt"])
+    return results[:20]
+
+
+def _build_countries(df) -> List[Dict]:
+    """Country breakdown with deduplication for accurate GMV and refund rates."""
+    if df.empty:
+        return []
+    # Deduplicate for item-level GMV
+    s = _dedup_items(df).copy()
+    s["_mp"] = s["marketplace"].apply(_normalize_mp)
+    s["_paid"] = _safe_num(s["buyer_paid"])
+    s["ship_country"] = s["ship_country"].fillna("Unknown").apply(_normalize_country)
+    # Mark items with active refund
+    active_refund_items = set()
+    df_refunds = _active_refund_rows(df)
+    if not df_refunds.empty:
+        active_refund_items = set(df_refunds["order_item_id"].dropna().unique())
+    s["_has_refund"] = s["order_item_id"].isin(active_refund_items)
+
+    results = []
+    for country, g in s.groupby("ship_country"):
+        mir = g[g["_mp"] == "miravia"]
+        ae = g[g["_mp"] == "ae"]
+        refund_count = int(g["_has_refund"].sum())
+        rr = refund_count / len(g) if len(g) > 0 else 0
+        results.append({
+            "nm": country, "cd": country,
+            "all_gmv": round(float(g["_paid"].sum()), 2),
+            "miravia_gmv": round(float(mir["_paid"].sum()), 2),
+            "ae_gmv": round(float(ae["_paid"].sum()), 2),
+            "all_orders": int(g["order_id"].nunique()),
+            "miravia_orders": int(mir["order_id"].nunique()),
+            "ae_orders": int(ae["order_id"].nunique()),
+            "rr": round(rr, 4),
+        })
+    results.sort(key=lambda x: -x["all_gmv"])
+    return results
+
+
+def _build_pay_country(df) -> Dict:
+    import pandas as pd
+    if df.empty:
+        return {"countries": [], "payments": [], "data": []}
+    unique = df.drop_duplicates("order_id").copy()
+    unique["ship_country"] = unique["ship_country"].fillna("Unknown").apply(_normalize_country)
+    unique["payment_method"] = unique["payment_method"].fillna("Unknown")
+    top_countries = unique["ship_country"].value_counts().head(5).index.tolist()
+    top_payments = unique["payment_method"].value_counts().head(5).index.tolist()
+    pivot = pd.crosstab(
+        unique["ship_country"], unique["payment_method"], normalize="index"
+    ) * 100
+    data = []
+    for country in top_countries:
+        row = {"country": country}
+        for pm in top_payments:
+            row[pm] = round(float(pivot.loc[country, pm]), 1) if country in pivot.index and pm in pivot.columns else 0
+        data.append(row)
+    return {"countries": top_countries, "payments": top_payments, "data": data}
+
+
+# -------- platform-split distributions --------
+
+def _build_dist_by_platform(df, column, fillna="Unknown", n=10) -> Dict:
+    """Generic distribution by platform for a given column."""
+    if df.empty:
+        return {"all": [], "miravia": [], "ae": []}
+    s = df.copy()
+    s["_mp"] = s["marketplace"].apply(_normalize_mp)
+    s[column] = s[column].fillna(fillna)
+
+    def _dist(sub):
+        if sub.empty:
+            return []
+        counts = sub[column].value_counts().head(n)
+        total = int(counts.sum()) or 1
+        return [{"name": str(k), "count": int(v), "pct": round(v / total * 100, 1)}
+                for k, v in counts.items()]
+
+    return {
+        "all": _dist(s),
+        "miravia": _dist(s[s["_mp"] == "miravia"]),
+        "ae": _dist(s[s["_mp"] == "ae"]),
+    }
+
+
+def _build_cancel_initiator(df) -> Dict:
+    if df.empty:
+        return {"all": [], "miravia": [], "ae": []}
+    s = df.copy()
+    s["_mp"] = s["marketplace"].apply(_normalize_mp)
+    cdf = s[s["is_canceled"].fillna(False).astype(bool)]
+
+    def _dist(sub):
+        if sub.empty:
+            return []
+        counts = sub["cancel_initiator"].fillna("Unknown").value_counts()
+        total = int(counts.sum()) or 1
+        return [{"name": str(k), "count": int(v), "pct": round(v / total * 100, 1)}
+                for k, v in counts.items()]
+
+    return {
+        "all": _dist(cdf),
+        "miravia": _dist(cdf[cdf["_mp"] == "miravia"]),
+        "ae": _dist(cdf[cdf["_mp"] == "ae"]),
+    }
+
+
+def _build_cancel_agree(df) -> Dict:
+    if df.empty:
+        return {"all": {"agreed": 0, "rejected": 0},
+                "miravia": {"agreed": 0, "rejected": 0},
+                "ae": {"agreed": 0, "rejected": 0}}
+    s = df.copy()
+    s["_mp"] = s["marketplace"].apply(_normalize_mp)
+
+    def _rate(sub):
+        has_data = sub["seller_agreed"].notna()
+        if not has_data.any():
+            return {"agreed": 0, "rejected": 0}
+        agreed = int((has_data & sub["seller_agreed"].astype(bool)).sum())
+        rejected = int((has_data & ~sub["seller_agreed"].astype(bool)).sum())
+        total = agreed + rejected
+        if total == 0:
+            return {"agreed": 0, "rejected": 0}
+        return {"agreed": round(agreed / total * 100), "rejected": round(rejected / total * 100)}
+
+    return {
+        "all": _rate(s),
+        "miravia": _rate(s[s["_mp"] == "miravia"]),
+        "ae": _rate(s[s["_mp"] == "ae"]),
+    }
+
+
+def _build_refund_types(df) -> Dict:
+    if df.empty:
+        return {"all": [], "miravia": [], "ae": []}
+    rmask = df["refund_id"].notna() & (df["refund_id"] != "")
+    rdf = df[rmask].copy()
+    if rdf.empty:
+        return {"all": [], "miravia": [], "ae": []}
+    rdf["_mp"] = rdf["marketplace"].apply(_normalize_mp)
+    rdf["request_type"] = rdf["request_type"].fillna("UNKNOWN")
+    return _build_dist_by_platform(rdf, "request_type", "UNKNOWN")
+
+
+def _build_duty_party(df) -> Dict:
+    if df.empty:
+        return {"all": [], "miravia": [], "ae": []}
+    rmask = df["refund_id"].notna() & (df["refund_id"] != "")
+    rdf = df[rmask].copy()
+    if rdf.empty:
+        return {"all": [], "miravia": [], "ae": []}
+    rdf["duty_party"] = rdf["duty_party"].fillna("pending")
+    return _build_dist_by_platform(rdf, "duty_party", "pending")
+
+
+def _build_fast_refund(df) -> Dict:
+    if df.empty:
+        return {"all": [], "miravia": [], "ae": []}
+    rmask = df["refund_id"].notna() & (df["refund_id"] != "")
+    rdf = df[rmask].copy()
+    if rdf.empty:
+        return {"all": [], "miravia": [], "ae": []}
+    rdf["_mp"] = rdf["marketplace"].apply(_normalize_mp)
+    rdf["_amt"] = _safe_num(rdf["refund_amount"])
+
+    def _stats(sub):
+        if sub.empty:
+            return []
+        t = len(sub) or 1
+        fast = int(sub["is_fast_refund"].fillna(False).astype(bool).sum())
+        instant = int(sub["is_instant_refund"].fillna(False).astype(bool).sum())
+        small = int((sub["_amt"] < 50).sum())
+        large = int((sub["_amt"] >= 200).sum())
+        return [
+            {"name": "Fast Refund", "count": fast, "pct": round(fast / t * 100, 1)},
+            {"name": "Instant Refund", "count": instant, "pct": round(instant / t * 100, 1)},
+            {"name": "Small Refund(<50)", "count": small, "pct": round(small / t * 100, 1)},
+            {"name": "Large Refund(>=200)", "count": large, "pct": round(large / t * 100, 1)},
+        ]
+
+    return {
+        "all": _stats(rdf),
+        "miravia": _stats(rdf[rdf["_mp"] == "miravia"]),
+        "ae": _stats(rdf[rdf["_mp"] == "ae"]),
+    }
+
+
+def _build_fbm_dist(df) -> Dict:
+    if df.empty:
+        return {"all": [0, 0], "miravia": [0, 0], "ae": [0, 0]}
+    s = df.copy()
+    s["_mp"] = s["marketplace"].apply(_normalize_mp)
+    s["is_fbl"] = _safe_num(s["is_fbl"])
+
+    def _dist(sub):
+        if sub.empty:
+            return [0, 0]
+        fbm = int((sub["is_fbl"] == 1).sum())
+        return [fbm, len(sub) - fbm]
+
+    return {
+        "all": _dist(s),
+        "miravia": _dist(s[s["_mp"] == "miravia"]),
+        "ae": _dist(s[s["_mp"] == "ae"]),
+    }
+
+
+def _build_digital_dist(df) -> Dict:
+    if df.empty:
+        return {"all": [100, 0], "miravia": [100, 0], "ae": [100, 0]}
+    s = df.copy()
+    s["_mp"] = s["marketplace"].apply(_normalize_mp)
+    s["is_digital"] = _safe_num(s["is_digital"])
+
+    def _dist(sub):
+        if sub.empty:
+            return [100, 0]
+        digital = int((sub["is_digital"] == 1).sum())
+        physical = len(sub) - digital
+        total = len(sub) or 1
+        return [round(physical / total * 100, 1), round(digital / total * 100, 1)]
+
+    return {
+        "all": _dist(s),
+        "miravia": _dist(s[s["_mp"] == "miravia"]),
+        "ae": _dist(s[s["_mp"] == "ae"]),
+    }
+
+
+def _build_aov_buckets(df) -> Dict:
+    """AOV distribution with deduplication."""
+    import pandas as pd
+    if df.empty:
+        return {"all": [], "miravia": [], "ae": []}
+    # Deduplicate to avoid inflated buyer_paid per order
+    s = _dedup_items(df).copy()
+    s["_mp"] = s["marketplace"].apply(_normalize_mp)
+    s["_paid"] = _safe_num(s["buyer_paid"])
+    bins = [0, 10, 20, 30, 50, 1e9]
+    labels = ["<10", "10-20", "20-30", "30-50", ">=50"]
+
+    def _buckets(sub):
+        if sub.empty:
+            return []
+        per_order = sub.groupby("order_id")["_paid"].sum()
+        if per_order.empty:
+            return []
+        cuts = pd.cut(per_order, bins=bins, labels=labels, include_lowest=True)
+        c = cuts.value_counts().reindex(labels, fill_value=0)
+        total = int(c.sum()) or 1
+        return [{"range": lbl, "count": int(c[lbl]), "pct": round(c[lbl] / total * 100, 1)}
+                for lbl in labels]
+
+    return {
+        "all": _buckets(s),
+        "miravia": _buckets(s[s["_mp"] == "miravia"]),
+        "ae": _buckets(s[s["_mp"] == "ae"]),
+    }
+
+
+def _build_voucher_stats(df) -> Dict:
+    if df.empty:
+        return {"usage_rate": {"all": 0, "miravia": 0, "ae": 0},
+                "avg_amount": {"all": 0, "miravia": 0, "ae": 0}}
+    s = df.copy()
+    s["_mp"] = s["marketplace"].apply(_normalize_mp)
+    s["_disc"] = _safe_num(s["discount_seller"])
+
+    def _stats(sub):
+        if sub.empty:
+            return 0, 0
+        has_disc = int((sub["_disc"] > 0).sum())
+        rate = has_disc / len(sub) * 100 if len(sub) > 0 else 0
+        avg = float(sub.loc[sub["_disc"] > 0, "_disc"].mean()) if has_disc > 0 else 0
+        return round(rate, 1), round(avg, 2)
+
+    ra, aa = _stats(s)
+    rm, am = _stats(s[s["_mp"] == "miravia"])
+    re_, ae_ = _stats(s[s["_mp"] == "ae"])
+    return {
+        "usage_rate": {"all": ra, "miravia": rm, "ae": re_},
+        "avg_amount": {"all": aa, "miravia": am, "ae": ae_},
+    }
+
+
+def _build_shipping_stats(df) -> Dict:
+    if df.empty:
+        return {"all": {}, "miravia": {}, "ae": {}}
+    s = df.copy()
+    s["_mp"] = s["marketplace"].apply(_normalize_mp)
+    s["_ship"] = _safe_num(s["shipping_paid"])
+    s["_disc"] = _safe_num(s["shipping_fee_disc_seller"])
+
+    def _stats(sub):
+        if sub.empty:
+            return {}
+        total = float(sub["_ship"].sum())
+        avg = float(sub["_ship"].mean())
+        disc = float(sub["_disc"].sum())
+        disc_pct = disc / (total + disc) * 100 if (total + disc) > 0 else 0
+        free = int((sub["_ship"] == 0).sum())
+        free_pct = free / len(sub) * 100 if len(sub) > 0 else 0
+        return {
+            "total": round(total, 2),
+            "avg": round(avg, 2),
+            "disc": round(disc, 2),
+            "disc_pct": round(disc_pct, 1),
+            "free_pct": round(free_pct, 1),
+        }
+
+    return {
+        "all": _stats(s),
+        "miravia": _stats(s[s["_mp"] == "miravia"]),
+        "ae": _stats(s[s["_mp"] == "ae"]),
+    }
+
+
+def _build_discount_depth(df) -> Dict:
+    import pandas as pd
+    if df.empty:
+        return {"all": [], "miravia": [], "ae": []}
+    s = df.copy()
+    s["_mp"] = s["marketplace"].apply(_normalize_mp)
+    s["_paid"] = _safe_num(s["buyer_paid"])
+    s["_price"] = _safe_num(s["unit_price"])
+    bins = [-1, 0, 5, 10, 20, 1e9]
+    labels = ["0%", "1-5%", "6-10%", "11-20%", ">20%"]
+
+    def _depth(sub):
+        if sub.empty:
+            return []
+        sub = sub.copy()
+        sub["_pct"] = ((sub["_price"] - sub["_paid"]) / sub["_price"] * 100).where(sub["_price"] > 0, 0)
+        cuts = pd.cut(sub["_pct"], bins=bins, labels=labels, include_lowest=True)
+        c = cuts.value_counts().reindex(labels, fill_value=0)
+        total = int(c.sum()) or 1
+        return [{"range": lbl, "count": int(c[lbl]), "pct": round(c[lbl] / total * 100, 1)}
+                for lbl in labels]
+
+    return {
+        "all": _depth(s),
+        "miravia": _depth(s[s["_mp"] == "miravia"]),
+        "ae": _depth(s[s["_mp"] == "ae"]),
+    }
+
+
+def _build_cat_dist(df, t=None) -> Dict:
+    """Category distribution with deduplication for accurate GMV and refund rates."""
+    if df.empty:
+        return {"all": [], "miravia": [], "ae": []}
+    # Deduplicate for item-level GMV
+    s = _dedup_items(df).copy()
+    s["_mp"] = s["marketplace"].apply(_normalize_mp)
+    s["_paid"] = _safe_num(s["buyer_paid"])
+    s["_cat"] = s["product_name"].apply(lambda x: _classify_category(x, t=t))
+    # Mark items with active refund
+    active_refund_items = set()
+    df_refunds = _active_refund_rows(df)
+    if not df_refunds.empty:
+        active_refund_items = set(df_refunds["order_item_id"].dropna().unique())
+    s["_has_refund"] = s["order_item_id"].isin(active_refund_items).astype(int)
+
+    def _dist(sub):
+        if sub.empty:
+            return []
+        g = sub.groupby("_cat").agg(
+            gmv=("_paid", "sum"),
+            count=("order_item_id", "count"),
+            refunds=("_has_refund", "sum"),
+        ).reset_index()
+        g["rr"] = (g["refunds"] / g["count"]).fillna(0)
+        g = g.sort_values("gmv", ascending=False)
+        return [{"name": r["_cat"], "gmv": round(float(r["gmv"]), 2),
+                 "rr": round(float(r["rr"]), 4)} for _, r in g.iterrows()]
+
+    return {
+        "all": _dist(s),
+        "miravia": _dist(s[s["_mp"] == "miravia"]),
+        "ae": _dist(s[s["_mp"] == "ae"]),
+    }
+
+
+def _build_buyer_stats(df) -> Dict:
+    if df.empty:
+        return {"all": {"buyer_count": 0, "repurchase_rate": 0, "top5_share": 0},
+                "miravia": {"buyer_count": 0, "repurchase_rate": 0, "top5_share": 0},
+                "ae": {"buyer_count": 0, "repurchase_rate": 0, "top5_share": 0}}
+    s = df.copy()
+    s["_mp"] = s["marketplace"].apply(_normalize_mp)
+    s["_buyer"] = s["buyer_id"].fillna("").astype(str)
+    s.loc[s["_buyer"] == "", "_buyer"] = s["buyer_name"].fillna("").astype(str)
+    s["_paid"] = _safe_num(s["buyer_paid"])
+
+    def _stats(sub):
+        named = sub[sub["_buyer"] != ""]
+        if named.empty:
+            return {"buyer_count": 0, "repurchase_rate": 0, "top5_share": 0}
+        per_buyer = named.groupby("_buyer")["order_id"].nunique()
+        bcount = int(len(per_buyer))
+        if bcount == 0:
+            return {"buyer_count": 0, "repurchase_rate": 0, "top5_share": 0}
+        returning = int((per_buyer > 1).sum())
+        repurchase = round(returning / bcount * 100, 1)
+        per_buyer_gmv = named.groupby("_buyer")["_paid"].sum().sort_values(ascending=False)
+        total_gmv = float(per_buyer_gmv.sum()) or 1.0
+        top5 = round(float(per_buyer_gmv.head(5).sum()) / total_gmv * 100, 1)
+        return {"buyer_count": bcount, "repurchase_rate": repurchase, "top5_share": top5}
+
+    return {
+        "all": _stats(s),
+        "miravia": _stats(s[s["_mp"] == "miravia"]),
+        "ae": _stats(s[s["_mp"] == "ae"]),
+    }
+
+
+# -------- overall metrics --------
+
+def _compute_overall(df) -> Dict:
+    """Compute overall KPI metrics with correct deduplication.
+
+    After one-to-many refund expansion, the same item may appear in multiple rows.
+    - Item-level metrics (GMV, items, cancel): use deduplicated df (one row per item)
+    - Refund metrics: use active refunds only, deduplicated by refund_id
+    - Refund rate: fraction of unique items that have at least one active refund
+    """
+    if df.empty:
+        return {"orders": 0, "items": 0, "gmv": 0, "aov": 0,
+                "cancel_count": 0, "cancel_rate": 0,
+                "refund_count": 0, "refund_rate": 0,
+                "refund_amount": 0, "net_revenue": 0}
+    # Item-level: deduplicate to avoid inflation from refund expansion
+    df_items = _dedup_items(df)
+    paid = _safe_num(df_items["buyer_paid"])
+    gmv = float(paid.sum())
+    orders_n = int(df_items["order_id"].nunique())
+    items_n = len(df_items)
+    aov = gmv / orders_n if orders_n else 0
+    cancel_count = int(df_items["is_canceled"].fillna(False).astype(bool).sum())
+    cancel_rate = cancel_count / items_n if items_n else 0
+    # Refund: active refunds only, deduplicated by refund_id
+    df_refunds = _active_refund_rows(df)
+    refund_count = len(df_refunds)
+    # Refund rate: unique items with active refund / total unique items
+    items_with_refund = int(df_refunds["order_item_id"].nunique()) if not df_refunds.empty else 0
+    refund_rate = items_with_refund / items_n if items_n else 0
+    refund_amount = float(_safe_num(df_refunds["refund_amount"]).sum()) if not df_refunds.empty else 0
+    net_revenue = gmv - refund_amount
+    return {
+        "orders": orders_n, "items": items_n,
+        "gmv": round(gmv, 2), "aov": round(aov, 2),
+        "cancel_count": cancel_count, "cancel_rate": round(cancel_rate, 4),
+        "refund_count": refund_count, "refund_rate": round(refund_rate, 4),
+        "refund_amount": round(refund_amount, 2),
+        "net_revenue": round(net_revenue, 2),
+    }
+
+
+# -------- metrics export (for Agent analysis) --------
+
+def _build_metrics_for_preset(df, currency: str) -> Dict:
+    """Build a compact metrics dict for a single preset window.
+
+    Used by export_metrics() to give Agent LLM structured data
+    for generating dynamic executive summaries.
+    """
+    overall = _compute_overall(df)
+
+    # Top refund reasons (compact)
+    top_refund_reasons = []
+    rmask = df["refund_id"].notna() & (df["refund_id"] != "") if not df.empty else []
+    if not df.empty and any(rmask):
+        rdf = df[rmask].copy()
+        rdf["_amt"] = _safe_num(rdf["refund_amount"])
+        total_refunds = len(rdf)
+        for reason, g in rdf.groupby("refund_reason", dropna=False):
+            label = reason if reason else "Not specified"
+            top_refund_reasons.append({
+                "reason": str(label),
+                "count": len(g),
+                "pct": round(len(g) / total_refunds, 4) if total_refunds else 0,
+                "amount": round(float(g["_amt"].sum()), 2),
+            })
+        top_refund_reasons.sort(key=lambda x: -x["count"])
+        top_refund_reasons = top_refund_reasons[:5]
+
+    # Top SKUs (compact)
+    top_skus = []
+    if not df.empty:
+        s = df.copy()
+        s["quantity"] = _safe_num(s["quantity"])
+        rmask2 = s["refund_id"].notna() & (s["refund_id"] != "")
+        for (sku, name), g in s.groupby(["sku", "product_name"], dropna=False):
+            qty = int(g["quantity"].sum())
+            refund_count = int(rmask2[g.index].sum())
+            rr = refund_count / len(g) if len(g) else 0
+            top_skus.append({
+                "sku": str(sku) if sku else "-",
+                "name": str(name) if name else "-",
+                "qty": qty,
+                "refund_rate": round(rr, 4),
+            })
+        top_skus.sort(key=lambda x: -x["qty"])
+        top_skus = top_skus[:10]
+
+    # Top carriers (compact)
+    top_carriers = []
+    if not df.empty:
+        s = df.copy()
+        s["shipping_provider"] = s["shipping_provider"].fillna("Unknown")
+        s["_is_cancel"] = s["is_canceled"].fillna(False).astype(bool)
+        rmask3 = s["refund_id"].notna() & (s["refund_id"] != "")
+        for carrier, g in s.groupby("shipping_provider"):
+            total = len(g)
+            cr = float(g["_is_cancel"].sum()) / total if total else 0
+            rr = float(rmask3[g.index].sum()) / total if total else 0
+            top_carriers.append({
+                "name": carrier,
+                "orders": total,
+                "cancel_rate": round(cr, 4),
+                "refund_rate": round(rr, 4),
+            })
+        top_carriers.sort(key=lambda x: -x["orders"])
+        top_carriers = top_carriers[:5]
+
+    # Platform split
+    platform_split = {"miravia": 0, "ae": 0, "other": 0}
+    if not df.empty:
+        mp = df["marketplace"].apply(_normalize_mp)
+        for p, cnt in mp.value_counts().items():
+            if p in platform_split:
+                platform_split[p] = int(cnt)
+            else:
+                platform_split["other"] += int(cnt)
+
+    return {
+        "overall": overall,
+        "topRefundReasons": top_refund_reasons,
+        "topSkus": top_skus,
+        "topCarriers": top_carriers,
+        "platformSplit": platform_split,
+    }
+
+
+def export_metrics(rows: List[Dict[str, Any]], export_columns,
+                   range_start: str = "", range_end: str = "") -> Dict:
+    """Export structured metrics for Agent LLM analysis.
+
+    Returns a dict with metrics for each preset time window,
+    suitable for JSON serialization. The Agent reads this to
+    generate dynamic executive summaries.
+    """
+    import pandas as pd
+
+    df = (pd.DataFrame(rows, columns=export_columns)
+          if rows else pd.DataFrame(columns=export_columns))
+    currency = _common_currency(df)
+
+    # Full range
+    presets: Dict[str, Any] = {
+        "0": {
+            **_build_metrics_for_preset(df, currency),
+            "dateRange": {"start": range_start, "end": range_end},
+        }
+    }
+
+    # Per-preset windows
+    # IMPORTANT: Use normalize() to align with dailyData calendar-day boundaries.
+    # Without this, the cutoff would use the exact max_date timestamp (e.g.,
+    # 14:43:35), excluding orders on the boundary day that were created before
+    # that time — causing metrics.json to disagree with HTML KPI cards which
+    # aggregate from dailyData using full calendar days.
+    if not df.empty:
+        dates = pd.to_datetime(df["created_at"], errors="coerce")
+        max_date = dates.max()
+        for days in _PRESET_DAYS:
+            cutoff = max_date.normalize() - pd.Timedelta(days=days - 1)
+            subset = df[dates >= cutoff]
+            if len(subset) < len(df):
+                min_d = subset["created_at"].min() if not subset.empty else ""
+                presets[str(days)] = {
+                    **_build_metrics_for_preset(subset, currency),
+                    "dateRange": {"start": str(min_d), "end": range_end},
+                }
+            else:
+                presets[str(days)] = presets["0"]
+
+    return {
+        "currency": currency,
+        "presets": presets,
+    }
+
+
+# -------- dimensional data helper --------
+
+def _compute_dims(df, currency: str, t=None) -> Dict:
+    """Compute all dimensional breakdowns for a given DataFrame subset."""
+    cancel_df = df[df["is_canceled"].fillna(False).astype(bool)] if not df.empty else df
+    overall = _compute_overall(df)
+    return {
+        "skus": _build_skus(df, t=t),
+        "cities": _build_cities(df),
+        "carriers": _build_carriers(df),
+        "refReasons": _build_ref_reasons(df, currency, t=t),
+        "abBuyers": _build_ab_buyers(df),
+        "countries": _build_countries(df),
+        "payCountry": _build_pay_country(df),
+        "payMethods": _build_dist_by_platform(
+            df.drop_duplicates("order_id") if not df.empty else df,
+            "payment_method", "Unknown"),
+        "cancelReasons": _build_dist_by_platform(
+            cancel_df, "cancel_reason", "Not specified"),
+        "cancelInitiator": _build_cancel_initiator(df),
+        "cancelAgree": _build_cancel_agree(df),
+        "refundTypes": _build_refund_types(df),
+        "dutyPartyDist": _build_duty_party(df),
+        "fastRefund": _build_fast_refund(df),
+        "fbmDist": _build_fbm_dist(df),
+        "digitalDist": _build_digital_dist(df),
+        "aovBuckets": _build_aov_buckets(df),
+        "statusDist": _build_dist_by_platform(df, "item_status", "Unknown"),
+        "shipTypeDist": _build_dist_by_platform(df, "shipment_type", "Unknown"),
+        "voucherStats": _build_voucher_stats(df),
+        "shippingStats": _build_shipping_stats(df),
+        "discountDepth": _build_discount_depth(df),
+        "catDist": _build_cat_dist(df, t=t),
+        "buyerStats": _build_buyer_stats(df),
+        "overall": overall,
+    }
+
+
+# -------- AI insights generation (rule-based) --------
+
+_INSIGHT_TEMPLATES = {
+    "zh": {
+        "summary_annual": '<p>Past {days} days: <b>{orders:,}</b> orders, GMV <b>{currency}{gmv:,.0f}</b>, net revenue <b>{currency}{net:,.0f}</b>. Cancel rate {cr:.1%}, refund rate {rr:.1%}. {trend}</p>',
+        "summary_short": '<p>Last {days} days: <b>{orders:,}</b> orders, GMV <b>{currency}{gmv:,.0f}</b>, AOV <b>{currency}{aov:,.2f}</b>. Refund rate <b>{rr:.1%}</b>, cancel rate {cr:.1%}. Net revenue {currency}{net:,.0f}. {trend}</p>',
+        "summary_nodata": '<p>Insufficient data in this time window for meaningful insights.</p>',
+        "alert_high_refund": 'Refund rate {rr:.1%} exceeds {threshold:.0%} threshold',
+        "alert_high_cancel": 'Cancel rate {cr:.1%} is elevated',
+        "alert_top_reason": 'Top refund reason "{reason}" accounts for {pct:.1%}, involving {currency}{amt:,.0f} loss',
+        "alert_sku_anomaly": 'SKU "{name}" refund rate {rr:.1%} ({qty} orders), requires investigation',
+        "alert_trend_improve": 'Recent trend improving: refund rate dropped from {long_rr:.1%} to {short_rr:.1%}',
+        "alert_aov_change": 'AOV {direction}: last {days} days {currency}{aov:.2f} vs annual {currency}{base_aov:.2f}',
+        "action_fix_reason": 'Investigate root cause of "{reason}" refunds, reduce non-voluntary refunds',
+        "action_stock": 'Optimize inventory management, integrate real-time alerts to prevent overselling cancellations',
+        "action_sku_check": 'Investigate high-refund SKU "{name}", confirm if test data contamination',
+        "action_expand": 'Business trend is positive, consider scaling ad spend',
+        "action_monitor": 'Continue monitoring refund rate changes, consolidate recent improvements',
+    },
+    "en": {
+        "summary_annual": '<p>Past {days} days: <b>{orders:,}</b> orders, GMV <b>{currency}{gmv:,.0f}</b>, net revenue <b>{currency}{net:,.0f}</b>. Cancel rate {cr:.1%}, refund rate {rr:.1%}. {trend}</p>',
+        "summary_short": '<p>Last {days} days: <b>{orders:,}</b> orders, GMV <b>{currency}{gmv:,.0f}</b>, AOV <b>{currency}{aov:,.2f}</b>. Refund rate <b>{rr:.1%}</b>, cancel rate {cr:.1%}. Net revenue {currency}{net:,.0f}. {trend}</p>',
+        "summary_nodata": '<p>Insufficient data in this time window for meaningful insights.</p>',
+        "alert_high_refund": 'Refund rate {rr:.1%} exceeds {threshold:.0%} threshold',
+        "alert_high_cancel": 'Cancel rate {cr:.1%} is elevated',
+        "alert_top_reason": 'Top refund reason "{reason}" accounts for {pct:.1%}, {currency}{amt:,.0f} lost',
+        "alert_sku_anomaly": 'SKU "{name}" has {rr:.1%} refund rate ({qty} orders), requires investigation',
+        "alert_trend_improve": 'Positive trend: refund rate dropped from {long_rr:.1%} to {short_rr:.1%}',
+        "alert_aov_change": 'AOV {direction}: last {days}d {currency}{aov:.2f} vs annual {currency}{base_aov:.2f}',
+        "action_fix_reason": 'Investigate root cause of "{reason}" refunds to reduce involuntary returns',
+        "action_stock": 'Improve inventory management with real-time alerts to prevent overselling',
+        "action_sku_check": 'Audit high-refund SKU "{name}" — verify if test data is polluting metrics',
+        "action_expand": 'Business trending positively — consider scaling ad spend',
+        "action_monitor": 'Continue monitoring refund rate to consolidate recent improvements',
+    },
+    "es": {
+        "summary_annual": '<p>Últimos {days} días: <b>{orders:,}</b> pedidos, GMV <b>{currency}{gmv:,.0f}</b>, ingresos netos <b>{currency}{net:,.0f}</b>. Tasa cancelación {cr:.1%}, tasa devolución {rr:.1%}. {trend}</p>',
+        "summary_short": '<p>Últimos {days} días: <b>{orders:,}</b> pedidos, GMV <b>{currency}{gmv:,.0f}</b>, AOV <b>{currency}{aov:,.2f}</b>. Tasa devolución <b>{rr:.1%}</b>, tasa cancelación {cr:.1%}. Ingresos netos {currency}{net:,.0f}. {trend}</p>',
+        "summary_nodata": '<p>Datos insuficientes en esta ventana temporal para generar información útil.</p>',
+        "alert_high_refund": 'Tasa devolución {rr:.1%} supera umbral {threshold:.0%}',
+        "alert_high_cancel": 'Tasa cancelación {cr:.1%} elevada',
+        "alert_top_reason": 'Motivo principal "{reason}" supone {pct:.1%}, {currency}{amt:,.0f} perdidos',
+        "alert_sku_anomaly": 'SKU "{name}" tiene {rr:.1%} tasa devolución ({qty} pedidos)',
+        "alert_trend_improve": 'Tendencia positiva: devoluciones bajan de {long_rr:.1%} a {short_rr:.1%}',
+        "alert_aov_change": 'AOV {direction}: últimos {days}d {currency}{aov:.2f} vs anual {currency}{base_aov:.2f}',
+        "action_fix_reason": 'Investigar causa raíz de devoluciones por "{reason}"',
+        "action_stock": 'Mejorar gestión de inventario con alertas en tiempo real',
+        "action_sku_check": 'Auditar SKU "{name}" con alta tasa de devolución',
+        "action_expand": 'Negocio en tendencia positiva — considerar aumentar inversión',
+        "action_monitor": 'Seguir monitorizando tasa de devolución para consolidar mejoras',
+    },
+    "it": {
+        "summary_annual": '<p>Ultimi {days} giorni: <b>{orders:,}</b> ordini, GMV <b>{currency}{gmv:,.0f}</b>, ricavo netto <b>{currency}{net:,.0f}</b>. Tasso cancellazione {cr:.1%}, tasso rimborso {rr:.1%}. {trend}</p>',
+        "summary_short": '<p>Ultimi {days} giorni: <b>{orders:,}</b> ordini, GMV <b>{currency}{gmv:,.0f}</b>, AOV <b>{currency}{aov:,.2f}</b>. Tasso rimborso <b>{rr:.1%}</b>, tasso cancellazione {cr:.1%}. Ricavo netto {currency}{net:,.0f}. {trend}</p>',
+        "summary_nodata": '<p>Dati insufficienti in questa finestra temporale.</p>',
+        "alert_high_refund": 'Tasso rimborso {rr:.1%} supera soglia {threshold:.0%}',
+        "alert_high_cancel": 'Tasso cancellazione {cr:.1%} elevato',
+        "alert_top_reason": 'Motivo principale "{reason}" rappresenta {pct:.1%}, {currency}{amt:,.0f} persi',
+        "alert_sku_anomaly": 'SKU "{name}" ha {rr:.1%} tasso rimborso ({qty} ordini)',
+        "alert_trend_improve": 'Tendenza positiva: rimborsi scesi da {long_rr:.1%} a {short_rr:.1%}',
+        "alert_aov_change": 'AOV {direction}: ultimi {days}g {currency}{aov:.2f} vs annuale {currency}{base_aov:.2f}',
+        "action_fix_reason": 'Indagare causa principale dei rimborsi per "{reason}"',
+        "action_stock": 'Migliorare gestione inventario con avvisi in tempo reale',
+        "action_sku_check": 'Verificare SKU "{name}" con alto tasso rimborso',
+        "action_expand": 'Business in tendenza positiva — valutare aumento investimenti',
+        "action_monitor": 'Continuare a monitorare tasso rimborso per consolidare miglioramenti',
+    },
+}
+
+
+def _get_insight_tpl(lang: str) -> Dict[str, str]:
+    return _INSIGHT_TEMPLATES.get(lang, _INSIGHT_TEMPLATES["en"])
+
+
+def _generate_preset_insights(overall: Dict, top_reasons: List, top_skus: List,
+                              base_overall: Dict, days: int, currency: str,
+                              lang: str) -> Dict:
+    """Generate insights for a single preset time window.
+
+    Args:
+        overall: metrics for this preset window
+        top_reasons: top refund reasons for this window
+        top_skus: top SKUs for this window
+        base_overall: full-range overall metrics (for trend comparison)
+        days: the preset day count (7, 30, 90, 180, 365, or 0=all)
+        currency: currency symbol (e.g. '€')
+        lang: language code
+    """
+    tpl = _get_insight_tpl(lang)
+    cur_sym = "€" if currency.upper() == "EUR" else currency + " "
+
+    orders = overall.get("orders", 0)
+    items = overall.get("items", 0)
+    gmv = overall.get("gmv", 0)
+    aov = overall.get("aov", 0)
+    cr = overall.get("cancel_rate", 0)
+    rr = overall.get("refund_rate", 0)
+    net = overall.get("net_revenue", 0)
+    refund_amt = overall.get("refund_amount", 0)
+
+    base_rr = base_overall.get("refund_rate", 0)
+    base_cr = base_overall.get("cancel_rate", 0)
+    base_aov = base_overall.get("aov", 0)
+
+    if orders < 5:
+        return {"summary": tpl["summary_nodata"], "highlights": [], "actions": []}
+
+    # ---- Summary ----
+    trend_parts = []
+    if days > 0 and days < 365 and base_rr > 0:
+        if rr < base_rr * 0.7:
+            trend_parts.append("<b>" + ({"zh": "Strong positive trend", "en": "Strong positive trend",
+                                          "es": "Tendencia muy positiva", "it": "Tendenza molto positiva"}
+                                         .get(lang, "Strong positive trend")) + "</b>")
+        elif rr < base_rr * 0.9:
+            trend_parts.append({"zh": "Improving trend", "en": "Improving trend",
+                                "es": "Tendencia mejorando", "it": "Tendenza in miglioramento"}
+                               .get(lang, "Improving trend"))
+
+    trend_str = ". ".join(trend_parts)
+
+    if days >= 180:
+        summary = tpl["summary_annual"].format(
+            days=days, orders=orders, currency=cur_sym, gmv=gmv,
+            net=net, cr=cr, rr=rr, trend=trend_str)
+    else:
+        summary = tpl["summary_short"].format(
+            days=days, orders=orders, currency=cur_sym, gmv=gmv,
+            aov=aov, rr=rr, cr=cr, net=net, trend=trend_str)
+
+    # ---- Highlights ----
+    highlights = []
+
+    # High refund rate
+    if rr > 0.20:
+        highlights.append({"severity": "high",
+                           "title": tpl["alert_high_refund"].format(rr=rr, threshold=0.20),
+                           "detail": f"{cur_sym}{refund_amt:,.0f}"})
+    elif rr > 0.10:
+        highlights.append({"severity": "medium",
+                           "title": tpl["alert_high_refund"].format(rr=rr, threshold=0.10),
+                           "detail": f"{cur_sym}{refund_amt:,.0f}"})
+
+    # High cancel rate
+    if cr > 0.30:
+        highlights.append({"severity": "high" if cr > 0.40 else "medium",
+                           "title": tpl["alert_high_cancel"].format(cr=cr),
+                           "detail": ""})
+
+    # Top refund reason dominance
+    if top_reasons:
+        top1 = top_reasons[0]
+        if top1.get("pct", 0) > 0.30:
+            highlights.append({"severity": "high" if top1["pct"] > 0.50 else "medium",
+                               "title": tpl["alert_top_reason"].format(
+                                   reason=top1["reason"], pct=top1["pct"],
+                                   currency=cur_sym, amt=top1.get("amount", 0)),
+                               "detail": ""})
+
+    # Anomalous SKU refund rate
+    for sku in (top_skus or [])[:5]:
+        if sku.get("refund_rate", 0) > 0.50 and sku.get("qty", 0) > 20:
+            name = sku.get("name", sku.get("sku", "-"))
+            if len(name) > 30:
+                name = name[:27] + "..."
+            highlights.append({"severity": "high",
+                               "title": tpl["alert_sku_anomaly"].format(
+                                   name=name, rr=sku["refund_rate"], qty=sku["qty"]),
+                               "detail": ""})
+            break  # only report top-1 anomalous SKU
+
+    # Trend improvement (compare current window vs full range)
+    if days > 0 and days <= 90 and base_rr > 0.05 and rr < base_rr * 0.6:
+        highlights.append({"severity": "low",
+                           "title": tpl["alert_trend_improve"].format(
+                               long_rr=base_rr, short_rr=rr),
+                           "detail": ""})
+
+    # AOV significant change
+    if base_aov > 0 and days > 0 and days <= 90:
+        aov_ratio = aov / base_aov if base_aov else 1
+        if aov_ratio > 2.0 or aov_ratio < 0.5:
+            direction = {"zh": "significantly up" if aov_ratio > 1 else "significantly down",
+                         "en": "significantly up" if aov_ratio > 1 else "significantly down",
+                         "es": "sube significativamente" if aov_ratio > 1 else "baja significativamente",
+                         "it": "significativamente in aumento" if aov_ratio > 1 else "significativamente in calo",
+                         }.get(lang, "significant change")
+            highlights.append({"severity": "low",
+                               "title": tpl["alert_aov_change"].format(
+                                   direction=direction, days=days,
+                                   currency=cur_sym, aov=aov, base_aov=base_aov),
+                               "detail": ""})
+
+    # Cap at 5 highlights
+    highlights = highlights[:5]
+
+    # ---- Actions ----
+    actions = []
+
+    # P0: Fix top refund reason if dominant
+    if top_reasons and top_reasons[0].get("pct", 0) > 0.30:
+        actions.append({"priority": "P0",
+                        "text": tpl["action_fix_reason"].format(reason=top_reasons[0]["reason"])})
+
+    # P0: SKU anomaly
+    for sku in (top_skus or [])[:5]:
+        if sku.get("refund_rate", 0) > 0.50 and sku.get("qty", 0) > 20:
+            name = sku.get("name", sku.get("sku", "-"))
+            if len(name) > 30:
+                name = name[:27] + "..."
+            actions.append({"priority": "P0",
+                            "text": tpl["action_sku_check"].format(name=name)})
+            break
+
+    # P1: Stock management if "stock" reason is top-3
+    stock_keywords = ["stock", "out of stock", "no hay stock"]
+    for reason_obj in (top_reasons or [])[:3]:
+        reason_str = reason_obj.get("reason", "").lower()
+        if any(kw in reason_str for kw in stock_keywords):
+            actions.append({"priority": "P1", "text": tpl["action_stock"]})
+            break
+
+    # P2: Positive trend → expand
+    if rr < 0.10 and cr < 0.10:
+        actions.append({"priority": "P2", "text": tpl["action_expand"]})
+    elif days > 0 and days <= 90 and base_rr > 0.05 and rr < base_rr * 0.6:
+        actions.append({"priority": "P2", "text": tpl["action_monitor"]})
+
+    # Ensure at least one action
+    if not actions:
+        actions.append({"priority": "P2", "text": tpl["action_monitor"]})
+
+    return {"summary": summary, "highlights": highlights, "actions": actions}
+
+
+def generate_insights(metrics: Dict, lang: str = "en") -> Dict:
+    """[DEPRECATED] Rule-engine placeholder — no longer called by render().
+
+    Kept for reference only. LLM-generated insights via inject_insights.py
+    are the sole source of executive summary content.
+    """
+    currency = metrics.get("currency", "EUR")
+    presets_data = metrics.get("presets", {})
+
+    base_preset = presets_data.get("0", {})
+    base_overall = base_preset.get("overall", {})
+
+    result_presets = {}
+    for key, preset in presets_data.items():
+        overall = preset.get("overall", {})
+        top_reasons = preset.get("topRefundReasons", [])
+        top_skus = preset.get("topSkus", [])
+        days = int(key) if key != "0" else 0
+
+        result_presets[key] = _generate_preset_insights(
+            overall=overall,
+            top_reasons=top_reasons,
+            top_skus=top_skus,
+            base_overall=base_overall,
+            days=days,
+            currency=currency,
+            lang=lang,
+        )
+
+    return {"presets": result_presets}
+
+
+# -------- main render --------
+
+_PRESET_DAYS = [7, 30, 90, 180, 365]
+
+
+def render(rows: List[Dict[str, Any]], out_path: Path,
+           range_label: str, jinja_env, export_columns,
+           default_max_orders: int, lang: str = "en") -> Path:
+    """Render v4 unified dashboard HTML with embedded AI-generated insights."""
+    import pandas as pd
+
+    t = get_translations(lang)
+
+    df = pd.DataFrame(rows, columns=export_columns) if rows else pd.DataFrame(columns=export_columns)
+    currency = _common_currency(df)
+    overall = _compute_overall(df)
+
+    # ---- compute per-preset dimensional data ----
+    all_dims = _compute_dims(df, currency, t=t)
+    preset_data: Dict[str, Any] = {"0": all_dims}  # key "0" = full range
+
+    # IMPORTANT: Use normalize() to align with dailyData calendar-day boundaries.
+    # Without this, the cutoff would use the exact max_date timestamp (e.g.,
+    # 14:43:35), excluding orders on the boundary day that were created before
+    # that time — causing presetData to disagree with HTML KPI cards which
+    # aggregate from dailyData using full calendar days.
+    if not df.empty:
+        dates = pd.to_datetime(df["created_at"], errors="coerce")
+        max_date = dates.max()
+        for days in _PRESET_DAYS:
+            cutoff = max_date.normalize() - pd.Timedelta(days=days - 1)
+            subset = df[dates >= cutoff]
+            if len(subset) < len(df):  # only compute if subset differs from all
+                preset_data[str(days)] = _compute_dims(subset, currency, t=t)
+            else:
+                preset_data[str(days)] = all_dims  # same as all, share reference
+
+    # ---- agentInsights placeholder (LLM injects real content via inject_insights.py) ----
+    # The rule-engine generate_insights() has been retired — only LLM-generated
+    # multi-language insights are used. The empty placeholder ensures the HTML
+    # renders gracefully until inject_insights.py overwrites this field.
+    agent_insights = {"presets": {}}
+
+    # ---- assemble data payload ----
+    range_start = range_label.split(" ~ ")[0] if " ~ " in range_label else range_label
+    range_end = range_label.split(" ~ ")[1] if " ~ " in range_label else ""
+    data = {
+        "meta": {
+            "range_start": range_start,
+            "range_end": range_end,
+            "generated_at": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
+            "currency": currency,
+            "total_orders": overall["orders"],
+            "total_items": overall["items"],
+            "buyer_id_available": _check_buyer_id_available(df),
+        },
+        "dailyData": _build_daily_data(df, range_start=range_start, range_end=range_end),
+        "presetData": preset_data,
+        "agentInsights": agent_insights,
+        # Top-level dimensional fields (backward compat, points to "all")
+        **all_dims,
+    }
+
+    # ---- load static assets for inline embedding ----
+    _static_dir = Path(__file__).resolve().parent.parent / "static"
+    _chartjs_path = _static_dir / "chart.umd.min.js"
+    _datalabels_path = _static_dir / "chartjs-plugin-datalabels.min.js"
+    _logo_path = _static_dir / "miravia-logo.svg"
+
+    chartjs_inline = _chartjs_path.read_text(encoding="utf-8") if _chartjs_path.exists() else ""
+    chartjs_datalabels_inline = _datalabels_path.read_text(encoding="utf-8") if _datalabels_path.exists() else ""
+    logo_base64 = base64.b64encode(_logo_path.read_bytes()).decode("ascii") if _logo_path.exists() else ""
+
+    tpl = jinja_env.get_template("report_v4.html")
+    html = tpl.render(
+        data_json=json.dumps(data, ensure_ascii=False, default=str),
+        generated_at=data["meta"]["generated_at"],
+        range_label=range_label,
+        currency=currency,
+        t=t,
+        t_json=json.dumps(t, ensure_ascii=False),
+        all_t_json=json.dumps(TRANSLATIONS, ensure_ascii=False),
+        current_lang=lang,
+        supported_langs=SUPPORTED_LANGS,
+        chartjs_inline=chartjs_inline,
+        chartjs_datalabels_inline=chartjs_datalabels_inline,
+        logo_base64=logo_base64,
+    )
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_text(html, encoding="utf-8")
+    return out_path