# Reportes WooCommerce: UTM, campanas y Krax

Este proyecto ya tiene tres familias de reportes HTML construidos desde exports de WooCommerce:

- reportes completos: mezclan `UTM + Krax + sin UTM`;
- reportes solo de campañas UTM: se enfocan en campañas, productos y vida comercial de cada campaña.
- reportes de impacto Krax: comparan antes vs después entre 2025 y 2026.

## Mapa rápido de archivos nuevos

Si lo que quieres ubicar rápidamente es la nueva familia completa, estos son los cuatro archivos clave:

- CSV fuente completo:
  [krax-orders-instance-7-2026-01-01-to-2026-06-26-product-match.csv](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/como-construir/krax-orders-instance-7-2026-01-01-to-2026-06-26-product-match.csv)
- Reporte final completo estilo tipouno:
  [reporte-general-tipouno.html](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/reporte-general-tipouno.html)
- Reporte final completo estilo tipodos:
  [reporte-general-tipodos.html](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/reporte-general-tipodos.html)
- Guía base tipodos para reconstrucción:
  [tipodos-guia_reconstruir_reporte_final_utm_krax.md](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/como-construir/tipodos-guia_reconstruir_reporte_final_utm_krax.md)
- Guía creada para reconstruir el reporte completo tipouno:
  [tipouno-guia_reconstruir_reporte_general_final.md](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/como-construir/tipouno-guia_reconstruir_reporte_general_final.md)

Resumen de relación:

- El CSV `krax-orders-instance-7-2026-01-01-to-2026-06-26-product-match.csv` alimenta la familia completa.
- `reporte-general-tipodos.html` corresponde a la guía `tipodos-guia_reconstruir_reporte_final_utm_krax.md`.
- `reporte-general-tipouno.html` corresponde a la guía `tipouno-guia_reconstruir_reporte_general_final.md`.

Si lo que quieres ubicar rápidamente es el nuevo reporte de impacto, estos son los archivos clave:

- CSV longitudinal:
  [ALL-krax-orders-instance-7-2025-01-01-to-2026-06-26-product-match.csv](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/como-construir/ALL-krax-orders-instance-7-2025-01-01-to-2026-06-26-product-match.csv)
- Reporte HTML:
  [reporte_impacto_krax_antes_despues-2025-vs-2026.html](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/como-construir/reporte_impacto_krax_antes_despues-2025-vs-2026.html)
- Guía de reconstrucción:
  [reporte-largo-2025-vs-2026-guia_generar_reporte_impacto_krax_antes_despues.md](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/como-construir/reporte-largo-2025-vs-2026-guia_generar_reporte_impacto_krax_antes_despues.md)

## Familias de reportes

### Reporte de impacto Krax

- [reporte_impacto_krax_antes_despues-2025-vs-2026.html](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/como-construir/reporte_impacto_krax_antes_despues-2025-vs-2026.html)

Sirve para responder:

- si Feb-Jun 2026 mejoró contra Feb-Jun 2025;
- si el periodo post-Krax mejoró contra el periodo previo inmediato;
- cuánto del periodo post fue asistido por Krax;
- cómo evolucionaron ingresos, órdenes, UTM y Krax entre 2025 y 2026;
- qué productos crecieron más y cuáles fueron asistidos por Krax.

### Reportes completos

- [reporte-general-tipouno.html](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/reporte-general-tipouno.html)
- [reporte-general-tipodos.html](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/reporte-general-tipodos.html)

Sirven para responder:

- cuánto vendió la tienda en el periodo;
- cuánto vino con UTM y cuánto sin UTM;
- cuánto fue asistido por Krax;
- cómo se cruza Krax con UTM;
- cuáles campañas UTM ganaron o rindieron poco;
- qué productos vendieron las campañas UTM;
- qué productos fueron más asistidos por Krax;
- cómo evolucionó el negocio por mes.

### Reportes solo de campañas UTM

- [reporte-utm-tipouno.html](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/reporte-utm-tipouno.html)
- [reporte_campanas_woocommerce-tipodos.html](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/reporte_campanas_woocommerce-tipodos.html)

Sirven para responder:

- qué campañas generaron más ingresos;
- cuáles tuvieron menos resultados registrados;
- qué productos se vendieron por campaña;
- cómo fue la ventana de vida de cada campaña;
- cómo evolucionaron ingresos, órdenes y clientes por mes.

## Cómo se construyen

### Guías de reconstrucción

#### Familia completa

- [tipodos-guia_reconstruir_reporte_final_utm_krax.md](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/como-construir/tipodos-guia_reconstruir_reporte_final_utm_krax.md)
- [tipouno-guia_reconstruir_reporte_general_final.md](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/como-construir/tipouno-guia_reconstruir_reporte_general_final.md)

Correspondencia directa:

- `tipodos-guia_reconstruir_reporte_final_utm_krax.md` explica cómo reconstruir `reporte-general-tipodos.html`.
- `tipouno-guia_reconstruir_reporte_general_final.md` explica cómo reconstruir `reporte-general-tipouno.html`.

#### Familia solo campañas UTM

- [tipodos-prompt_regenerar_reporte_campanas_woocommerce.md](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/como-construir/tipodos-prompt_regenerar_reporte_campanas_woocommerce.md)
- [tipouno-prompt-regenerar-reporte-campanas.md](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/como-construir/tipouno-prompt-regenerar-reporte-campanas.md)

#### Reporte impacto Krax antes vs después

- [reporte-largo-2025-vs-2026-guia_generar_reporte_impacto_krax_antes_despues.md](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/como-construir/reporte-largo-2025-vs-2026-guia_generar_reporte_impacto_krax_antes_despues.md)

## CSV disponibles

### CSV para reportes completos

- [krax-orders-instance-7-2026-01-01-to-2026-06-26-product-match.csv](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/como-construir/krax-orders-instance-7-2026-01-01-to-2026-06-26-product-match.csv)

Este CSV es la fuente de datos de:

- [reporte-general-tipouno.html](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/reporte-general-tipouno.html)
- [reporte-general-tipodos.html](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/reporte-general-tipodos.html)

Columnas esperadas:

- `query_range_from`
- `query_range_to`
- `order_id`
- `order_number`
- `order_date`
- `customer`
- `email`
- `currency`
- `net_total`
- `resolved_utm_campaign`
- `has_krax_attribution`
- `krax_purchase_classification`
- `krax_assisted_products`
- `other_products`

### CSV para reporte de impacto Krax

- [ALL-krax-orders-instance-7-2025-01-01-to-2026-06-26-product-match.csv](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/como-construir/ALL-krax-orders-instance-7-2025-01-01-to-2026-06-26-product-match.csv)

Este CSV es la fuente de datos de:

- [reporte_impacto_krax_antes_despues-2025-vs-2026.html](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/como-construir/reporte_impacto_krax_antes_despues-2025-vs-2026.html)

Columnas esperadas:

- `query_range_from`
- `query_range_to`
- `order_id`
- `order_number`
- `order_date`
- `customer`
- `email`
- `currency`
- `net_total`
- `resolved_utm_campaign`
- `has_krax_attribution`
- `krax_purchase_classification`
- `krax_assisted_products`
- `other_products`

### CSV para reportes solo campañas UTM

- [wa-reporte-demo.csv](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/como-construir/wa-reporte-demo.csv)

Columnas esperadas:

- `query_range_from`
- `query_range_to`
- `campaign_key`
- `campaign_name`
- `target_category`
- `order_id`
- `order_number`
- `order_date`
- `order_month`
- `email`
- `order_total`
- `currency`
- `matched_products`
- `non_matched_products`

## Script Python reutilizable

El parser/base común es:

- [build_campaign_report_context.py](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/scripts/build_campaign_report_context.py)

Ahora soporta dos schemas:

- `campaign`
- `full`
- `impact`

Y también soporta autodetección:

```bash
python3 /Users/joserrivas/Documents/proyectos/siores/reportes-kahos/scripts/build_campaign_report_context.py RUTA_CSV --schema auto
```

## Anonimizar emails para compartir el CSV con un LLM

Si necesitas subir el CSV a un LLM sin exponer los emails reales de clientes, puedes usar este script:

- [anonymize_csv_emails.py](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/scripts/anonymize_csv_emails.py)

Qué hace:

- recorre la columna `email` del CSV;
- reemplaza cada email real por un email falso aleatorio;
- mantiene el reemplazo de forma consistente en todo el archivo.

Ejemplo:

- si `joser@keylimetec.com` se reemplaza por `abc123def456@masked.example`, cada vez que vuelva a aparecer ese mismo email original se usará exactamente el mismo valor anonimizado.

Cómo se ejecuta:

```bash
python3 /Users/joserrivas/Documents/proyectos/siores/reportes-kahos/scripts/anonymize_csv_emails.py \
  /Users/joserrivas/Documents/proyectos/siores/reportes-kahos/como-construir/krax-orders-instance-7-2026-01-01-to-2026-06-26-product-match.csv
```

Archivo de salida:

- [copia-krax-orders-instance-7-2026-01-01-to-2026-06-26-product-match.csv](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/como-construir/copia-krax-orders-instance-7-2026-01-01-to-2026-06-26-product-match.csv)

Regla de nombre:

- el script no modifica el CSV original;
- crea un archivo nuevo en la misma carpeta;
- al nombre original le agrega el prefijo `copia-`.

Uso general con cualquier CSV que tenga columna `email`:

```bash
python3 /Users/joserrivas/Documents/proyectos/siores/reportes-kahos/scripts/anonymize_csv_emails.py /ruta/al/archivo.csv
```

## Exportar HTML portable para hosting

Si quieres subir el centro de reportes a una plataforma estática y que el cliente lo vea online desde una sola carpeta portable, ahora existe este comando:

```bash
./scripts/export_portable_site.sh
```

Qué hace:

- toma `index.html` como entrypoint;
- sigue los enlaces locales y copia los HTML necesarios manteniendo la estructura relativa;
- descarga dependencias remotas usadas por los reportes, como Google Fonts y `Chart.js`;
- reescribe los HTML exportados para que apunten a assets locales;
- genera una carpeta lista para publicar y un ZIP.

Salida por defecto:

- carpeta: [dist/portable-html](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/dist/portable-html)
- zip: [dist/portable-html.zip](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/dist/portable-html.zip)

Ejemplo completo:

```bash
cd /Users/joserrivas/Documents/proyectos/siores/reportes-kahos
./scripts/export_portable_site.sh
```

Opciones útiles:

- cambiar entrypoint:

```bash
./scripts/export_portable_site.sh --entry index.html
```

- cambiar carpeta de salida:

```bash
./scripts/export_portable_site.sh --output-dir dist/cliente-demo --zip-name dist/cliente-demo.zip
```

Nota:

- el comando necesita conexión a internet al momento de exportar si quieres incluir localmente `Google Fonts` y `Chart.js`, porque esas dependencias hoy viven fuera del repo.

## Comandos exactos por reporte

Importante:

- Hoy el script Python existente genera el `JSON` estructurado para cada familia.
- Hoy no existe todavía un renderer Python que escriba directamente los 5 HTML finales.
- Entonces, con Python ya puedes producir la base exacta de datos para cada reporte.
- La etapa final de `HTML` sigue dependiendo del formato/prompt/skill correspondiente.

### 1. `reporte-general-tipouno.html`

Fuente:

- CSV: [krax-orders-instance-7-2026-01-01-to-2026-06-26-product-match.csv](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/como-construir/krax-orders-instance-7-2026-01-01-to-2026-06-26-product-match.csv)
- Guía: [tipouno-guia_reconstruir_reporte_general_final.md](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/como-construir/tipouno-guia_reconstruir_reporte_general_final.md)

Comando exacto para generar la base JSON:

```bash
python3 /Users/joserrivas/Documents/proyectos/siores/reportes-kahos/scripts/build_campaign_report_context.py \
  /Users/joserrivas/Documents/proyectos/siores/reportes-kahos/como-construir/krax-orders-instance-7-2026-01-01-to-2026-06-26-product-match.csv \
  --schema full \
  --output /private/tmp/reporte-general-tipouno-context.json
```

Salida esperada:

- `/private/tmp/reporte-general-tipouno-context.json`

### 2. `reporte-general-tipodos.html`

Fuente:

- CSV: [krax-orders-instance-7-2026-01-01-to-2026-06-26-product-match.csv](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/como-construir/krax-orders-instance-7-2026-01-01-to-2026-06-26-product-match.csv)
- Guía: [tipodos-guia_reconstruir_reporte_final_utm_krax.md](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/como-construir/tipodos-guia_reconstruir_reporte_final_utm_krax.md)

Comando exacto para generar la base JSON:

```bash
python3 /Users/joserrivas/Documents/proyectos/siores/reportes-kahos/scripts/build_campaign_report_context.py \
  /Users/joserrivas/Documents/proyectos/siores/reportes-kahos/como-construir/krax-orders-instance-7-2026-01-01-to-2026-06-26-product-match.csv \
  --schema full \
  --output /private/tmp/reporte-general-tipodos-context.json
```

Salida esperada:

- `/private/tmp/reporte-general-tipodos-context.json`

### 3. `reporte_impacto_krax_antes_despues-2025-vs-2026.html`

Fuente:

- CSV: [ALL-krax-orders-instance-7-2025-01-01-to-2026-06-26-product-match.csv](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/como-construir/ALL-krax-orders-instance-7-2025-01-01-to-2026-06-26-product-match.csv)
- Guía: [reporte-largo-2025-vs-2026-guia_generar_reporte_impacto_krax_antes_despues.md](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/como-construir/reporte-largo-2025-vs-2026-guia_generar_reporte_impacto_krax_antes_despues.md)

Comando exacto para generar la base JSON:

```bash
python3 /Users/joserrivas/Documents/proyectos/siores/reportes-kahos/scripts/build_campaign_report_context.py \
  /Users/joserrivas/Documents/proyectos/siores/reportes-kahos/como-construir/ALL-krax-orders-instance-7-2025-01-01-to-2026-06-26-product-match.csv \
  --schema impact \
  --output /private/tmp/reporte-impacto-krax-context.json
```

Salida esperada:

- `/private/tmp/reporte-impacto-krax-context.json`

### 4. `reporte-utm-tipouno.html`

Fuente:

- CSV: [wa-reporte-demo.csv](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/como-construir/wa-reporte-demo.csv)
- Guía: [tipouno-prompt-regenerar-reporte-campanas.md](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/como-construir/tipouno-prompt-regenerar-reporte-campanas.md)

Comando exacto para generar la base JSON:

```bash
python3 /Users/joserrivas/Documents/proyectos/siores/reportes-kahos/scripts/build_campaign_report_context.py \
  /Users/joserrivas/Documents/proyectos/siores/reportes-kahos/como-construir/wa-reporte-demo.csv \
  --schema campaign \
  --output /private/tmp/reporte-utm-tipouno-context.json
```

Salida esperada:

- `/private/tmp/reporte-utm-tipouno-context.json`

### 5. `reporte_campanas_woocommerce-tipodos.html`

Fuente:

- CSV: [wa-reporte-demo.csv](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/como-construir/wa-reporte-demo.csv)
- Guía: [tipodos-prompt_regenerar_reporte_campanas_woocommerce.md](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/como-construir/tipodos-prompt_regenerar_reporte_campanas_woocommerce.md)

Comando exacto para generar la base JSON:

```bash
python3 /Users/joserrivas/Documents/proyectos/siores/reportes-kahos/scripts/build_campaign_report_context.py \
  /Users/joserrivas/Documents/proyectos/siores/reportes-kahos/como-construir/wa-reporte-demo.csv \
  --schema campaign \
  --output /private/tmp/reporte-campanas-woocommerce-tipodos-context.json
```

Salida esperada:

- `/private/tmp/reporte-campanas-woocommerce-tipodos-context.json`

### Opción auto-detect

Si no quieres pensar en el schema y solo quieres validar que el CSV produce contexto:

```bash
python3 /Users/joserrivas/Documents/proyectos/siores/reportes-kahos/scripts/build_campaign_report_context.py RUTA_CSV --schema auto
```

## Estado actual del flujo Python

### Lo que sí hace hoy

- valida el CSV;
- detecta `campaign`, `full` o `impact`;
- normaliza datos;
- calcula KPIs y agregados;
- genera el JSON base para cada reporte.

### Lo que no hace todavía

- escribir automáticamente `reporte-general-tipouno.html`;
- escribir automáticamente `reporte-general-tipodos.html`;
- escribir automáticamente `reporte_impacto_krax_antes_despues-2025-vs-2026.html`;
- escribir automáticamente `reporte-utm-tipouno.html`;
- escribir automáticamente `reporte_campanas_woocommerce-tipodos.html`.

Para eso todavía se usa:

- la guía/prompt correspondiente;
- o el skill correspondiente;
- o un futuro renderer HTML fijo que todavía no existe en este repo.

### Ejemplos

#### Contexto para campañas UTM

```bash
python3 /Users/joserrivas/Documents/proyectos/siores/reportes-kahos/scripts/build_campaign_report_context.py \
  /Users/joserrivas/Documents/proyectos/siores/reportes-kahos/como-construir/wa-reporte-demo.csv \
  --schema campaign \
  --output /private/tmp/campaign-context.json
```

#### Contexto para reporte completo UTM + Krax

```bash
python3 /Users/joserrivas/Documents/proyectos/siores/reportes-kahos/scripts/build_campaign_report_context.py \
  /Users/joserrivas/Documents/proyectos/siores/reportes-kahos/como-construir/krax-orders-instance-7-2026-01-01-to-2026-06-26-product-match.csv \
  --schema full \
  --output /private/tmp/full-context.json
```

## Qué genera el script

### Schema `campaign`

Entrega un JSON con:

- `meta`
- `global`
- `campaigns`
- `monthly`

Uso principal:

- `reporte-utm-tipouno.html`
- `reporte_campanas_woocommerce-tipodos.html`

### Schema `full`

Entrega un JSON con:

- `meta`
- `campaigns`
- `bucket_summary`
- `utm_cmp`
- `no_utm_split`
- `monthly`
- `monthly_bucket`
- `krax_class`
- `top_krax_products`
- `kpi_meta`

Uso principal:

- `reporte-general-tipouno.html`
- `reporte-general-tipodos.html`

### Schema `impact`

Entrega un JSON con:

- `meta`
- `kpi_meta`
- `periods`
- `comparisons`
- `monthly`
- `krax_summary`
- `post_utm_cmp`
- `post_source_buckets`
- `campaigns`
- `top_products_post`
- `top_krax_products_post`
- `top_utm_products_post`
- `yoy_product_increase`
- `signal_counts_post`

Uso principal:

- `reporte_impacto_krax_antes_despues-2025-vs-2026.html`

## Skills disponibles

### Skill general

- [skills/generar-reportes-campanas/SKILL.md](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/skills/generar-reportes-campanas/SKILL.md)

Se usa cuando el usuario entrega un CSV y quiere regenerar la familia correcta de reportes sin tener que especificar todo el flujo.

### Skills por reporte

- [skills/generar-reporte-general-tipouno/SKILL.md](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/skills/generar-reporte-general-tipouno/SKILL.md)
- [skills/generar-reporte-general-tipodos/SKILL.md](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/skills/generar-reporte-general-tipodos/SKILL.md)
- [skills/generar-reporte-impacto-krax-antes-despues/SKILL.md](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/skills/generar-reporte-impacto-krax-antes-despues/SKILL.md)
- [skills/generar-reporte-utm-tipouno/SKILL.md](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/skills/generar-reporte-utm-tipouno/SKILL.md)
- [skills/generar-reporte-woocommerce-tipodos/SKILL.md](/Users/joserrivas/Documents/proyectos/siores/reportes-kahos/skills/generar-reporte-woocommerce-tipodos/SKILL.md)

## Convención de nombres

### Reportes completos

- `NOMBREBASE-reporte-general-tipouno.html`
- `NOMBREBASE-reporte-general-tipodos.html`

### Reporte impacto Krax

- `NOMBREBASE-reporte_impacto_krax_antes_despues-2025-vs-2026.html`

### Reportes solo campañas UTM

- `NOMBREBASE-reporte-utm-tipouno.html`
- `NOMBREBASE-reporte_campanas_woocommerce-tipodos.html`

Si se quiere sobrescribir los ejemplos del repo, usar exactamente:

- `reporte-general-tipouno.html`
- `reporte-general-tipodos.html`
- `reporte_impacto_krax_antes_despues-2025-vs-2026.html`
- `reporte-utm-tipouno.html`
- `reporte_campanas_woocommerce-tipodos.html`

## Diferencias reales entre estilos

### tipouno

- Más reusable.
- Mejor separación entre datos y presentación.
- Mejor para plantillas regenerables.
- Más fuerte en naming legible, buckets y narrativa ejecutiva.

### tipodos

- Más directo y literal.
- Más cercano a tablas, bloques y lecturas rápidas explícitas.
- Más simple de automatizar cuando se quiere reducir la capa editorial.

## Qué puede automatizarse sin LLM

Sí se puede automatizar sin LLM:

- validar ambos tipos de CSV;
- normalizar datos;
- calcular KPIs;
- construir buckets UTM/Krax;
- ranking de campañas;
- nuevos vs recurrentes;
- top productos;
- series mensuales;
- renderizar HTML fijo.

## Qué mejora con LLM

Un LLM sigue ayudando en:

- renombrar campañas técnicas a nombres más humanos;
- redactar insights ejecutivos;
- redactar causas probables de bajo rendimiento;
- adaptar el tono del reporte según audiencia;
- reconstruir formatos visuales complejos sin escribir reglas manuales para cada texto.

## Recomendación técnica

La arquitectura recomendada sigue siendo híbrida:

1. Python o Laravel procesa el CSV y genera JSON estructurado.
2. Una plantilla HTML fija renderiza lo determinístico.
3. Un LLM opcional redacta insights, naming y comentarios editoriales.

Eso aplica tanto a la familia completa como a la familia solo UTM.