informe-comercial-alfa/CLAUDE.md

12 KiB
Raw Blame History

@AGENTS.md

Informe Comercial ALFA+ — app Next.js (Dataverse en vivo)

Dashboard comercial de ALFA+ (Alfanumeric Nicaragua), consulta Dynamics 365 en vivo por OAuth de vendedor (dynamic = "force-dynamic", sin caché) — reemplaza al sitio HTML estático que vive en Proyectos/Análisis e Informes/Analitica de CRM/App Informe/ (archivado, solo referencia; los comentarios del código que citan herramientas/… o App Informe/… apuntan a ese material). Publicado en https://informe-comercial.apps.online.com.ni.

⚠️ Esta es la carpeta que corre en producción

C:\dev\informe-comercial es la única carpeta de trabajo y la fuente real de lo publicado. Es un repo git (rama main) sincronizado con Forgejo (MarcoMontenegro/informe-comercial-alfa). La copia anterior en C:\Mis Aplicaciones\informe-comercial se eliminó el 2026-09-28. Historial del tema en Proyectos/Análisis e Informes/Analitica de CRM/sesion.md, entrada "2026-09-28".

⚠️ Publicar y git — leer antes de tocar el repo local (2026-10-27)

  • publish_changes publica lo que hay en esta carpeta y sube su propio commit a Forgejo (fuerza el push). El git local de esta carpeta queda desfasado (rama «adelante 1, atrás 1») y con cambios sin commit: es normal. No hacer git pull, git reset ni git checkout . sin revisar: perderías trabajo que ya está en producción.
  • Rutina después de cada publicación (acordada con Marco el 2026-11-06): correr git fetch origin y luego git reset origin/main (sin --hard). Mueve solo el historial local al de Forgejo y no toca ningún archivo, así el git no queda «adelante/atrás». Antes, comprobar que la carpeta coincide con origin/main (ignorando fin de línea: git archive origin/main a una carpeta temporal y diff -rq --strip-trailing-cr). Solo git reset sin --hard; git pull y git checkout . siguen prohibidos sin revisar.
  • Para saber si algo está publicado, no fiarse de git status: comparar los archivos con origin/main (git fetch y comparar hashes) o leer el commit desplegado en get_logs. El 2026-10-27 se comprobó así que los 104 archivos coinciden con el commit 0a51fac.
  • Dos sesiones pueden trabajar en paralelo en esta misma carpeta (el 2026-10-27: una en Previsión de Ventas, otra en Plan del Día / enlaces). Como comparten el árbol de trabajo, lo que publique una incluye lo de la otra: avisar antes de publicar y revisar git status para no subir trabajo a medias.
  • Enlaces para crear actividades en Dynamics (nuevaActividadUrl en app/lib/constants.js): el tipo del «Referente a» va en regardingobjectidtype=opportunity. Con regardingobjecttypecode el formulario se ve bien pero al guardar falla con 0x80040217. Los correos de Power Automate usan el mismo enlace (corregidos el 2026-10-27).

Filtro de propietario persistente y Plan del Día (2026-10-26)

Cómo quedaron hechos (archivos, reglas de clasificación, PDF Carta horizontal, decisiones) y cómo reutilizarlos: Proyectos/Análisis e Informes/Analitica de CRM/referencia-implementacion-plan-del-dia.md — la especificación funcional está en requerimientos-plan-del-dia.md de esa misma carpeta. Código: app/plan/, app/lib/plan.js, app/components/plan/, app/components/OwnerControl.js.

Reglas de negocio — viven en el proyecto de análisis, no acá

No duplicar aquí la definición de tipos de oportunidad, tuberías, forecast category, motivos de cierre, ejecutivos de venta, ni las lecciones aprendidas de interpretación de datos. Esa es la fuente de verdad y cambia con el negocio — leerla ahí:

📘 C:\Users\marco.montenegro\OneDrive - Alfanumeric\Claude\Proyectos\Análisis e Informes\Analitica de CRM\CLAUDE.md

De ahí en particular:

  • Estructura de tuberías y tipos de oportunidad (alfa_typeopportunity)
  • Cumplimiento de meta — qué cuenta: solo Venta - Cliente Nuevo, Up-Selling, Cross-Selling, Plan de Cuenta (TIPOS_META en app/lib/derive.js es el espejo en código de esa lista)
  • Ejecutivos de venta reales — Gabriela Sánchez y Ashley Bermúdez aparecen en los datos pero no son ejecutivas de venta (EJECUTIVOS_VENTA en app/lib/derive.js)
  • Forecast category con escala propia de ALFA+ (no la estándar de Dynamics)
  • El mapa de motivos de cierre (MOTIVO_MAP) — Dynamics reetiquetó el optionset en sep-2026
  • Las advertencias de interpretación (WhatsApp no está en el CRM, promedio ≠ techo, etc.)

Si una regla de negocio de código acá (app/lib/derive.js, app/lib/queries.js) no cuadra con lo que dice ese CLAUDE.md, ese archivo manda — el código se ajusta a él, no al revés.

Entorno técnico (ALFA+, común a todos los proyectos)

Ver también el CLAUDE.md raíz de ALFA+ (Claude/CLAUDE.md) para Dynamics (alfanumeric.crm.dynamics.com), convenciones de trabajo (todo en español, no inventar números, cambios acotados) y marca.

Gestionar actividades desde la app (2026-11-06)

Ventana emergente para completar, reprogramar, cancelar y deshacer citas, llamadas y tareas sin ir a Dynamics. Diseño y revisión EGM: Proyectos/Análisis e Informes/Analitica de CRM/egm/concepts_brief.md.

  • Código: app/components/actividades/GestionarActividad.js (ventana; se abre desde la Agenda / y el Detalle de Plan de Actividades), app/actividades/gestionActions.js (acciones de servidor: abrir, ejecutar, deshacer, refrescar), app/lib/actividadesServer.js (Dynamics), app/lib/actividadAcciones.js (bitácora SQLite actividad_accion: actor, previo, nuevo).
  • Estados (statecode/statuscode), verificados con escritura real: llamada completada 1/2, cancelada 2/3; cita 1/3 y 2/4; tarea 1/5 y 2/6 (con percentcomplete 100). Deshacer reabre al estado previo y devuelve nota, fecha real y avance.
  • Notas: cita → alfa_resultadodelavisita (HTML, antepuesta). Nunca la descripción de la cita (es la invitación). Llamada y tarea → description (antepuesta).
  • Reglas: If-Match (etag) al escribir datos; citas con invitados (máscara 5 o 6) no se reprograman ni cancelan desde la app; cada ejecutivo solo toca lo suyo, el administrador y la asistente pueden actuar a nombre de otros (la ventana lo avisa).
  • Refresco: las pantallas se refrescan al cerrar la ventana (refrescarPantallasAction). Refrescar antes desmonta la ventana y se pierde «Deshacer». La Agenda es la ruta /.
  • Interruptores de emergencia (variables de entorno en Coolify, sin publicar de nuevo): ACTIVIDADES_ACCIONES=off deja la app solo de lectura; PARTICIPANTES_OPP=off completa igual pero no toca la oportunidad.
  • Participantes: al completar se marcan chips (lib/participantes.js: 100000000 Gerencia Comercial, …01 Preventa SmartWeb, …02 Preventa Seguridad, …03 Gerencia Operaciones, …04 Gerencia General). Se guardan en la cita (alfa_participantes, antes de cerrarla: una actividad cerrada es de solo lectura) y se suman a la oportunidad: Gerencia Comercial → Sí/No alfa_participaciondegv (alimenta la puntuación +5), los demás → alfa_participantes. Nunca quita ni baja un Sí a No. Si falla la oportunidad, la actividad queda completada y se avisa. Indicador en /participacion.
  • Pruebas: oportunidad «Oportunidad de prueba 2 - stageid» (cuenta EMPRESA ABC, propietario Marco). Crear actividades de prueba es seguro; Marco entra al Agendador por URL (?owner=marco.montenegro@alfa.com.ni) pero no aparece en la lista del filtro (solo los 5 ejecutivos); para ver sus actividades en local se agregó temporalmente su nombre a EJECUTIVOS_VENTA en derive.js (quitarlo antes de publicar).
  • Lección: al escribir regex con scripts de shell se pueden perder las \ (el Agendador rechazó toda fecha por /^d{4}-d{2}-d{2}$/). Revisar el archivo después de escribirlo.

Agendador: reglas y GV (2026-11-11)

  • Reglas en AGENDADOR (app/lib/agendador.js): franjas 8:30–12:00 y 13:30–17:00; llamada 10 min (horas cada 10), visita 60 min (cada 30); máximos por día 10 llamadas, 4 visitas, 6 tareas; tareas vencen 16:00. También rigen el seguimiento al completar.
  • «Con GV»: ver crearActividad (agendadorServer.js) y agendadorActions.js. Cita con GV: appointment_activity_parties con organizador (7) y Marco (5, GV_USUARIO en participantes.js). Esas citas cuentan a Marco como «invitado», así que la ventana de gestión no las reprograma ni cancela (se hace en Dynamics).
  • Seguimiento al completar: un solo botón «Guardar, completar y programar seguimiento»; objetivo validado contra OBJETIVOS_LIBRES; el servidor rechaza sábados y domingos.

Campanita y seguimiento del mismo día (2026-11-13)

  • Campanita (barra superior, app/components/Campanita.js; datos en app/api/campanita/route.js + app/lib/campanita.js, que reutiliza armarPlanPeriodo/listaPlana): número rojo = vencidas del mes en curso (abiertas de días anteriores o de hoy con hora pasada) + llamadas/visitas que empiezan en ≤30 min. Ejecutivo: sus actividades. Administrador sin ?owner: solo actividades con Gerencia Comercial, sin vencidas. El administrador puede pasar ?owner=correo al endpoint para ver lo que vería ese ejecutivo (así se validó). fresh=1 salta la caché de 4 min (se usa tras gestionar). Sin avisos push (va en la PWA, etapa 2).
  • Seguimiento mismo día: botón «Hoy, más tarde» en GestionarActividad; horasLibres (agendador.js) quita horas pasadas (margen 5 min) y las que chocan con lo ya agendado hoy (hoyAgenda de abrirActividadAction). El servidor sigue validando igual.

App de campo (PWA) — rutas /m/... (2026-11-14)

Versión de teléfono de la misma app (mismo login, mismos permisos: ownerFilter/authz). Las páginas web no cambian (solo: AppShell cede el marco a CampoShell cuando la ruta empieza por /m, y muestra el aviso «Usar la versión de campo →» en ≤ 600 px).

  • Pantallas: /m/hoy, /m/calendario, /m/semana, /m/tuberia, /m/cuentas, /m/cuentas/[id], /m/oportunidad/[id]. Marco/asistente eligen propietario con OwnerM (?owner=).
  • Código: app/m/ (páginas, components/: CampoShell, HojaActividad = hoja de acciones, NuevaMovil = botón +, BotonesContacto, WhatsAppRegistro, OppAcciones = ✎ Editar y 📝 Nota), lib/campo.js (puro: WhatsApp/teléfono/mapas, categorías, opciones de campos), lib/campoServer.js (Dynamics), lib/campoPagina.js, m/campoActions.js. CSS propio: public/assets/css/campo.css (solo se carga en /m).
  • Reutiliza, sin duplicar reglas: plan.js, agendaDia.js, agendador.js, participantes.js, queries.js, acciones de gestionActions.js (completar/reprogramar/cancelar/seguimiento/editar/deshacer) y cuentasActions.js (alta con «Ya la realicé»; se le añadió el parámetro canal: whatsapp pone «WhatsApp – …» en el asunto).
  • PWA: public/campo/manifest.webmanifest (+ iconos a partir de Logos A+ -01.png), public/campo-sw.js (alcance solo /m/: copia de /m/hoy con sesión → «Sin conexión · actualizado HH:MM»; estáticos de Next; no guarda auth ni otras rutas; sin push). Cerrar sesión borra esa copia.
  • Edición de oportunidad (✎): PATCH con If-Match, solo lo que cambió; «Deshacer» 10 min (bitácora actividad_accion, acciones edicion_opp/nota_opp, canal movil). Editable: previsión, tipo (alfa_typeopportunity, es un Choice, no un lookup: no existe otro campo «tipo de oportunidad»), nivel de probabilidad (alfa_niveldeprobabilidad: Alta/Mediana/Se desconoce, no hay «Baja»), cierre, MRR, competidor (lookup alfa_competidorid → competitors), luz amarilla, participantes (GC → alfa_participaciondegv), estado de la negociación (memo ≤ 2000) + nota nativa opcional. Solo lectura: plan de cierre, clasificación (alfa_clasificaciondeoportunidad, el termómetro), línea de negocio. No se gana/pierde. Interruptor: OPORTUNIDAD_EDICION=off.
  • Pendiente: avisos push; probar el service worker en un teléfono real (el navegador integrado no registra SW); probar WhatsApp real.