Sumijal Dashboard

Dashboard de ventas y métricas comerciales para Sumijal (distribuidores de transformadores eléctricos), alimentado por datos de Kommo CRM.

Stack

• Backend: Node.js + Express
• Frontend: Chart.js (dark theme, single-page)
• Datos: Kommo CRM API v4 (account ventassumijalcom)
• Base de datos: PostgreSQL como fuente primaria del dashboard
• Deploy: Docker en Easypanel vía Forgejo usando dockerizer/Dockerfile

Estructura del Proyecto

├── server.js             # Entry point mínimo, delega a src/server.js
├── dockerizer/
│   └── Dockerfile        # Docker build para Easypanel
├── package.json
├── src/
│   ├── config.js         # Config/env/paths
│   ├── db.js             # Postgres schema + queries
│   ├── kommo-client.js   # Cliente rate-limited de Kommo
│   ├── kommo.js          # Helpers de mapeo y hashing
│   ├── sync-service.js   # Sync scheduler + SSE status
│   ├── server.js         # Bootstrap del servidor Express
│   └── routes/
│       └── registerRoutes.js
├── scripts/
│   └── update_data.js        # Ejecuta una sincronización completa a Postgres
└── docs/
    ├── ARCHITECTURE.md
    ├── KOMMO_STRUCTURE.md
    └── politicas_gestion_comercial.md

Scripts NPM

Comando	Qué hace
npm start	Inicia el servidor Express (puerto 80 por defecto)
npm run update	Ejecuta una sincronización completa de Kommo a PostgreSQL
node scripts/inspect_webhooks.js	Muestra resumen y ejemplos recientes de webhooks guardados en Postgres
npm run deploy	Push a Forgejo + trigger de build en Easypanel
npm run refresh	update + deploy en un solo comando

Variables de Entorno

• KOMMO_VENTASSUMIJALCOM_BEARER_TOKEN — Token de Kommo API
• POSTGRES_VENTASSUMIJALCOM_DATABASE_URL — URL de PostgreSQL
• KOMMO_WEBHOOK_SECRET — Secreto compartido para aceptar webhooks públicos de Kommo
• PORT — Puerto del servidor (default: 80)
• PERSISTENT_ROOT — Carpeta persistente base en el contenedor (default: /app/storage)
• POSTGRES_HOST / POSTGRES_PORT / POSTGRES_USER / POSTGRES_PASSWORD / POSTGRES_DATABASE — Alternativa por componentes
• AUTO_SYNC_ENABLED — true/false para activar sincronización programada (default: true)
• AUTO_SYNC_ON_START — Ejecuta sincronización al iniciar contenedor (default: true)
• SYNC_SCHEDULE_HOURS_MX — Horas de ejecución en America/Mexico_City (default: 3)
• KOMMO_REQUEST_INTERVAL_MS — Tiempo mínimo entre requests a Kommo (default: 2000)
• KOMMO_EVENTS_FROM — Fecha inicial para la ventana de eventos
• AUTH_ENABLED — Habilita autenticación (true/false, default: true)
• AUTH_STORE_PATH — Archivo persistente con usuario/hash/salt (default: ${PERSISTENT_ROOT}/auth.json)
• AUTH_SESSION_SECRET — Secreto para firma de cookie de sesión
• AUTH_SESSION_TTL_HOURS — Duración de sesión en horas (default: 12)

Autenticación del Dashboard

• El dashboard y todos los endpoints /api/* están protegidos por login.
• Credenciales por defecto al primer arranque: admin / admin.
• La contraseña no se guarda en texto plano: se guarda passwordHash + passwordSalt en AUTH_STORE_PATH.
• Para cambiar usuario/contraseña, iniciar sesión y entrar a /account.

Persistencia de credenciales

• Si PERSISTENT_ROOT está montado en volumen (por ejemplo /app/storage en Easypanel), el archivo auth.json persiste entre redeploys/restarts.
• Si no hay auth.json, el sistema crea uno nuevo usando las credenciales hard-coded por defecto.

Modo Postgres

• El dashboard ya no depende de snapshots JSON para servir la UI.
• La sincronización escribe a Postgres y expone progreso en vivo vía SSE.
• El almacenamiento histórico usa hashes para guardar sólo nuevas versiones cuando el payload cambia.

Persistencia en Easypanel

Para que no se pierdan ni datos ni logs al redeploy/restart, monta un volumen persistente en:

• /app/storage

Dentro de esa carpeta el sistema usa auth.json para persistir las credenciales del dashboard.

Workflow típico

# 1. Sincronizar datos desde Kommo a Postgres
npm run update

# 2. Probar local
PORT=3456 npm start

# 3. Deploy
npm run deploy

# O todo junto:
npm run refresh

Webhook de Kommo

• Ruta pública recomendada: POST https://<tu-dominio-dashboard>/api/webhooks/kommo/ventassumijalcom/<KOMMO_WEBHOOK_SECRET>
• Ruta protegida existente: POST /api/webhooks/kommo/:subdomain requiere sesión del dashboard y no sirve para Kommo directo.
• El webhook actual guarda el evento crudo en Postgres para procesamiento posterior. No ejecuta todavía la lógica de duplicación y sincronización de contactos por sí solo.
• Endpoints de inspección:
  • GET /api/webhooks/summary
  • GET /api/webhooks/recent?limit=20