TMEX Dashboard - Handoff Context

Este README esta pensado para mover esta carpeta a otro workspace y continuar el trabajo sin perder contexto.

1) Estado Actual Del Proyecto

• Dashboard enfocado en usuarios (no en un solo pipeline).
• UI en light mode, estilo tipo shadcn (tokens, cards, tabla principal de usuarios).
• Dominio productivo correcto:
  • https://tmex-dashboard.nqbqlu.easypanel.host
• Dominio anterior no deseado:

2) Objetivo Funcional

El enfoque principal del dashboard es medir rendimiento de usuarios:

• cartera por usuario
• win rate por usuario
• cumplimiento de tareas
• actividad comercial (llamadas, reuniones, mensajes)
• cambios de etapa

Pipelines siguen presentes como contexto operativo secundario.

3) Estructura Relevante

• src/App.jsx: layout principal (users-first) y render de charts/tablas.
• src/index.css: tema claro, tokens y estilos base.
• src/index.html: entrada de Vite para la app React.
• server/index.js: servidor Express para healthcheck, datos y fallback SPA.
• dockerizer/Dockerfile: build/deploy container para EasyPanel.
• scripts/fetch_kommo_performance_snapshot.js: sync incremental de Kommo con estado persistido.
• scripts/build_performance_dashboard_data.js: agregacion y dataset final para el frontend.
• public/data/kommo_performance_snapshot.json: snapshot consolidado para trabajo local.
• public/data/kommo_performance_sync_state.json: cursores persistidos para backfill diario.
• public/data/dashboard-data.json: dataset listo para frontend.
• scripts/deploy_target_easypanel.js: deploy al servicio de EasyPanel.

4) Regla Critica De Kommo (Rate Limit)

Se debe respetar maximo 1 request por segundo.

Implementado en scripts/fetch_kommo_snapshot.js con:

• RATE_LIMIT_MS = 1000
• bloqueo por timestamp (lastRequestAt) antes de cada request.

Implementado hoy en scripts/fetch_kommo_performance_snapshot.js con la misma regla y con sync incremental para eventos y notas.

No bajar ese limite.

5) Comandos De Trabajo

Instalacion:

npm install

Extraccion Kommo (read-only):

npm run fetch:kommo

La extraccion principal ahora usa sync incremental para eventos y notas, con estado persistido en public/data/kommo_performance_sync_state.json.

Para eventos, el sync por defecto ahora trae todo sin filter[type] desde 2026-01-01 y mantiene el limite de 1 request por segundo.

Sync diario recomendado:

npm run sync:daily

Opciones utiles:

node scripts/fetch_kommo_performance_snapshot.js --events-from=2026-01-01 --notes-days=180
node scripts/fetch_kommo_performance_snapshot.js --event-chunk-days=3 --event-max-pages=40

Exploracion Kommo para dashboard de rendimiento de usuarios:

npm run explore:kommo

Solo extraccion exploratoria, con ventanas configurables para eventos y notas:

node scripts/fetch_kommo_performance_exploration.js --events-days=90 --notes-days=90
node scripts/summarize_kommo_performance_exploration.js

Generar dataset:

npm run build:data

Flujo completo:

npm run build

Levantar app local:

npm start

6) Variables De Entorno Necesarias

Minimo requerido:

• KOMMO_JOSELUISTOLEDOVARGAS_BEARER_TOKEN

Importante al mover carpeta:

• scripts/kommo_client.js ya busca .env en varias ubicaciones portables.
• Si cambias la jerarquia, revisa solo esa busqueda si deja de encontrar el archivo.

7) Deploy (EasyPanel)

El deploy no sube tu carpeta local automaticamente. EasyPanel usa el repo Git remoto configurado.

Flujo correcto para publicar cambios:

1. git add ...
2. git commit -m "..."
3. git push origin main
4. npm run deploy

Detalles:

• Proyecto EasyPanel: tmex
• Servicio: tmex-dashboard
• Repo fuente: devs_ac/tmex-pautas-kpis-dashboard
• Build: dockerizer/Dockerfile
• Script de deploy ya evita forzar dominios custom y mantiene comportamiento default de EasyPanel.

8) Validacion Rapida Post-Deploy

Debug local o productivo del ultimo sync:

curl -s http://localhost:3000/api/debug/sync | jq
curl -sk https://tmex-dashboard.nqbqlu.easypanel.host/api/debug/sync | jq

Archivos relevantes del debug:

• public/data/kommo_performance_debug.json: estado de la ultima corrida, warnings y errores.
• public/data/kommo_performance_snapshot.json: snapshot consolidado con errors y warnings.
• public/data/kommo_performance_sync_state.json: cursores persistidos.

Si el dashboard muestra una inconsistencia de datos:

1. revisar /api/debug/sync
2. confirmar eventSyncMode = all-events-unfiltered-v1
3. confirmar que events.nextFrom este avanzando
4. volver a correr npm run fetch:kommo && npm run build:data

Verificar dominio correcto:

curl -sk -o /tmp/tmex_nqbqlu.html -w "nqbqlu:%{http_code}\n" https://tmex-dashboard.nqbqlu.easypanel.host/

Verificar que sslip no sea valido:

curl -sk -o /tmp/tmex_sslip.html -w "sslip:%{http_code}\n" https://tmex-dashboard.31.97.13.63.sslip.io/

Esperado:

• nqbqlu:200
• sslip:404

9) Commits Clave Recientes

• 2eab0ca Redesign dashboard to light users-first layout
• 6885da6 redesign as general tmex dashboard
• 83139b1 initial TMEX pautas KPI dashboard

10) Estado Local Pendiente (No Publicado)

Al momento de este handoff, habia cambios locales fuera del commit principal:

• modificado: scripts/deploy_target_easypanel.js
• nuevo: SKILL.md
• nuevo: scripts/inspect_tmex_dashboard_domains.js

Si estos archivos importan para tu nuevo workspace, revisalos y decide si:

• se versionan, o
• se descartan.

11) Checklist Para Retomar En Nuevo Workspace

1. Clonar/mover carpeta del proyecto.
2. Confirmar npm install.
3. Confirmar que scripts/kommo_client.js encuentre .env.
4. Ejecutar npm run fetch:kommo y validar que respeta 1 rps.
5. Ejecutar npm run build:data.
6. Ejecutar npm start y revisar UI users-first.
7. Commit + push de cambios.
8. Ejecutar npm run deploy.
9. Verificar dominio nqbqlu.easypanel.host en 200 y sslip.io en 404.