@badgie/crm-cli 0.8.0 → 0.9.0

package/AGENTS.md

@@ -4,7 +4,7 @@ Este archivo es la guía canónica para que un agente (openclaw, Claude, Cursor,
 
 ## Qué es
 
-CLI oficial del Badgie CRM. La versión publicada `0.8.0` expone 120 comandos sobre Supabase y endpoints de la app Next, e incluye flujo completo para investigar y mantener federaciones (nacionales + regionales). Instalación: ver `cli/README.md`.
+CLI oficial del Badgie CRM. La versión publicada `0.9.0` expone ~145 comandos sobre Supabase y endpoints de la app Next, e incluye flujo completo para federaciones (nacionales + regionales) y para el **Marketing Planner** (campañas, posts, canales, assets, publicaciones, reviews, métricas). Instalación: ver `cli/README.md`.
 
 ## Fuente de verdad (machine-readable)
 
@@ -144,6 +144,92 @@ Reglas para el agente:
 - Para investigar contactos: usa `federations contacts list --federation <numero>`
   (donde `<numero>` puede ser `"12"` o `reg-<uuid>` indistintamente).
 
+## Marketing Planner para agentes (operación diaria + memoria histórica)
+
+El módulo `marketing` cubre el flujo completo del **Marketing Planner** dentro de `crm.badgie.es/marketing-planner`: planificar la semana, generar/actualizar copy, asociar assets, mover estados, registrar publicaciones con su URL final + evidencia y guardar histórico. Tablas: `marketing_campaigns`, `marketing_channels` (LinkedIn/Instagram/TikTok/X/Blog/Email/WhatsApp/YouTube/Pinterest), `marketing_posts`, `marketing_assets`, `marketing_post_assets`, `marketing_publications`, `marketing_status_events`, `marketing_reviews`, `marketing_metrics`.
+
+### Workflow diario recomendado para Coach/OpenClaw
+
+```bash
+# 1. ¿Qué toca hoy? Output cronológico con canal, owner, estado.
+badgie-crm marketing planner today --pretty
+
+# 2. ¿Qué está bloqueado? Detecta falta de copy, canal, fecha, manual_required, failed.
+badgie-crm marketing planner blockers --pretty
+
+# 3. Para cada blocker, decidir:
+
+# 3a. Falta copy → genera y actualiza
+badgie-crm marketing posts update vid-testimonio-fmg \
+  --copy "Texto generado con CTA y datos del estudio…" \
+  --hashtags "BadgieGolf,FederacionMadridGolf,GolfJunior"
+
+# 3b. Falta asset → enlaza URL externa o sube uuid existente
+badgie-crm marketing posts assets add vid-testimonio-fmg \
+  --asset-id-or-url https://res.cloudinary.com/dzsrcaaas/badgie/test.mp4 \
+  --role primary
+
+# 3c. Lista para revisión humana
+badgie-crm marketing posts status set vid-testimonio-fmg needs_review \
+  --reason "Asset y copy listos; falta validación de Greg"
+
+# 4. Cuando el humano publica manualmente, registra evidencia:
+badgie-crm marketing posts publications create vid-testimonio-fmg --channel linkedin
+# (esto crea una marketing_publication con status=pending)
+
+badgie-crm marketing publications mark-published <publication-uuid> \
+  --external-url "https://www.linkedin.com/posts/badgie_…" \
+  --evidence-url "https://res.cloudinary.com/dzsrcaaas/screenshot.png"
+
+# 5. Reporte semanal
+badgie-crm marketing planner reports weekly --pretty
+```
+
+### Workflow semanal de planning
+
+```bash
+# 1. Listar campañas activas
+badgie-crm marketing campaigns list --status active --pretty
+
+# 2. Crear campaña nueva
+badgie-crm marketing campaigns create \
+  --name "Profes Informes Deportivos" \
+  --slug profes-informes-q2 \
+  --objective "30 demos cualificadas en Q2" \
+  --start-date 2026-05-01 --end-date 2026-06-30 \
+  --landing-url "https://www.badgie.com/profes-informes-deportivos" \
+  --owner-email gregorio@badgie.com --pretty
+
+# 3. Crear pieza editorial atada a la campaña
+badgie-crm marketing posts create \
+  --title "Reel testimonio profesor tenis" \
+  --slug reel-testimonio-tenis-1 \
+  --campaign profes-informes-q2 \
+  --channel instagram \
+  --scheduled-at "2026-05-15T11:00:00+02:00" \
+  --copy "Antes lo escribía a mano. Hoy con Badgie…" \
+  --cta-label "Solicita demo" \
+  --cta-url "https://www.badgie.com/profes-informes-deportivos" \
+  --hashtags "BadgieTenis,InformesDeportivos,EscuelaTenis" \
+  --owner-email coach@badgie.com --pretty
+# Devuelve la pieza y crea marketing_status_events automático (∅ → draft).
+
+# 4. Una pieza, varios canales: cross-post LinkedIn + Instagram
+badgie-crm marketing posts publications create reel-testimonio-tenis-1 --channel linkedin
+badgie-crm marketing posts publications create reel-testimonio-tenis-1 --channel instagram
+```
+
+### Reglas para el agente
+
+- **No publiques nunca automáticamente** sin `--confirm` humano. La V1 NO tiene publicación automática real — `mark-published` solo persiste evidencia de algo ya publicado fuera.
+- **Estados válidos**: `idea | draft | needs_review | approved | scheduled | published | failed | manual_required | cancelled`. Cada cambio se registra solo en `marketing_status_events`.
+- **Slug** se autogenera desde el título si no se pasa. Reusa el slug del post como `utm_content`; el slug de la campaña como `utm_campaign`.
+- **`marketing posts assets add --asset-id-or-url`** acepta UUID (asset existente) o URL externa (auto-crea `marketing_assets` con `storage_provider='external'`). Para upload binario real usa la UI: el CLI no sube archivos.
+- **`marketing publications mark-published`** es idempotente y registra `published_by` con tu user. Antes de marcar, verifica que `external_url` sea pública.
+- **Métricas**: V1 entrada manual con `marketing metrics record --publication-id <uuid> --impressions ... --clicks ...`. No las inventes.
+- **Borrados**: `marketing posts delete --confirm` hace cascade en assets, publications, events, reviews. **Pide confirmación humana**.
+- **Filtros agregados**: `marketing planner reports weekly --week 2026-05-12` te da counts por estado/canal/campaña + publicaciones registradas en esa semana.
+
 ## Finance OS para agentes
 
 Usa estos comandos nuevos antes de hacer queries manuales:

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## 0.9.0 — 2026-05-08
+
+### Added — Marketing Planner workflow completo
+
+Reescritura del módulo `marketing` para soportar el nuevo Marketing Planner
+(`crm.badgie.es/marketing-planner`). Pensado para que Coach/OpenClaw planifique
+la semana, mantenga copy/assets, mueva estados y registre evidencia de cada
+publicación. ~30 comandos nuevos sustituyen los 5 antiguos read-only.
+
+- **Planner reads**:
+  - `marketing planner today` — piezas programadas para hoy con canal/owner/CTA.
+  - `marketing planner week [--week YYYY-MM-DD]` — agrupado por día.
+  - `marketing planner blockers` — detecta `falta_copy`, `falta_canal`,
+    `falta_fecha`, `manual_required`, `failed`, `needs_review`.
+  - `marketing planner reports weekly [--week YYYY-MM-DD]` — counts por estado,
+    canal, campaña + publicaciones registradas.
+- **Campañas**: `campaigns list|get|create|update|delete`. UTM canónico
+  derivado de `slug` por defecto.
+- **Canales**: `channels list|create|update`. Seed inicial con LinkedIn,
+  Instagram, TikTok, X, Blog, Email, WhatsApp, YouTube, Pinterest.
+- **Posts**: `posts list|get|create|update|delete` + `posts status set` con
+  histórico append-only en `marketing_status_events`.
+- **Post-assets**: `posts assets list|add|remove`. `add --asset-id-or-url`
+  acepta UUID o URL externa (auto-crea `marketing_assets` con
+  `storage_provider='external'`).
+- **Publicaciones** (una pieza × N canales):
+  - `publications list`, `posts publications list|create`,
+    `publications update`, `publications mark-published` (atajo con
+    `--external-url` y `--evidence-url` que setea `published_at` y
+    `published_by` automáticamente).
+- **Reviews**: `reviews request|resolve` con estados `requested|approved|
+  changes_requested|rejected`.
+- **Histórico**: `posts events list <post-id>` ordenado descendente.
+- **Métricas**: `metrics list`, `metrics record --publication-id …
+  --impressions … --clicks … --source manual|api|zapier`.
+
+### Migration required
+
+Aplicar `supabase-marketing-planner-migration.sql` en Supabase. **Es destructiva**:
+hace `DROP TABLE CASCADE` de las 5 tablas legacy del módulo marketing antiguo
+(`marketing_campaigns`, `social_media_posts`, `marketing_assets`,
+`marketing_metrics`, `marketing_leads`) y crea 9 nuevas. La página `/marketing`
+y sus componentes/modales han sido eliminados — usar `/marketing-planner`.
+
+### Removed
+
+- `marketing leads list` (la tabla `marketing_leads` ya no existe; la
+  atribución de leads se rehará en otra iteración).
+- 4 comandos read-only originales sustituidos por la nueva familia completa.
+
 ## 0.8.0 — 2026-05-06
 
 ### Added — Federations workflow para agentes

package/README.md

@@ -153,6 +153,51 @@ badgie-crm docs finance --json
 badgie-crm docs finance
 ```
 
+## Marketing Planner
+
+`marketing` cubre el flujo completo del Marketing Planner (`crm.badgie.es/marketing-planner`): planificar la semana, generar copy, asociar assets, mover estados, registrar publicaciones y medir.
+
+```bash
+# Operación diaria
+badgie-crm marketing planner today --pretty
+badgie-crm marketing planner blockers --pretty
+badgie-crm marketing planner reports weekly --pretty
+
+# Planning semanal
+badgie-crm marketing campaigns create \
+  --name "Profes Informes Q2" --slug profes-informes-q2 \
+  --objective "30 demos cualificadas" --start-date 2026-05-01 --end-date 2026-06-30 \
+  --landing-url "https://www.badgie.com/profes-informes-deportivos" --pretty
+
+badgie-crm marketing posts create \
+  --title "Reel testimonio profesor tenis" \
+  --campaign profes-informes-q2 --channel instagram \
+  --scheduled-at "2026-05-15T11:00:00+02:00" \
+  --copy "Antes lo escribía a mano. Hoy con Badgie…" \
+  --cta-label "Solicita demo" --cta-url "https://www.badgie.com/profes-informes-deportivos" \
+  --hashtags "BadgieTenis,InformesDeportivos" --owner-email coach@badgie.com --pretty
+
+# Cross-post: una pieza, dos canales
+badgie-crm marketing posts publications create reel-testimonio-profesor-tenis --channel linkedin
+badgie-crm marketing posts publications create reel-testimonio-profesor-tenis --channel instagram
+
+# Estado y assets
+badgie-crm marketing posts status set reel-testimonio-profesor-tenis needs_review --reason "Listo para Greg"
+badgie-crm marketing posts assets add reel-testimonio-profesor-tenis \
+  --asset-id-or-url https://res.cloudinary.com/dzsrcaaas/test.mp4 --role primary
+
+# Tras publicar manualmente: registrar evidencia
+badgie-crm marketing publications mark-published <publication-uuid> \
+  --external-url "https://www.linkedin.com/posts/badgie_..." \
+  --evidence-url "https://res.cloudinary.com/dzsrcaaas/screenshot.png"
+
+# Métricas (V1 manual)
+badgie-crm marketing metrics record --publication-id <uuid> \
+  --impressions 5400 --clicks 120 --ctr 0.022 --likes 87 --source manual --pretty
+```
+
+Workflow Coach completo en `cli/AGENTS.md` → sección "Marketing Planner para agentes".
+
 ## Top Clients
 
 Top Clients usa `client_monthly_reviews` para las revisiones mensuales. La pantalla actual no tiene una tabla separada de preguntas/configuración: las preguntas del modal son columnas de esa tabla (`notes`, `needs`, `testimonials`, `risk_level`, `next_actions`, `status`, `reviewed_at`) y el contacto semanal vive en `metadata.contact_log`.