informe-comercial-alfa/CLAUDE.md

93 lines
12 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

@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.