94 lines
12 KiB
Markdown
94 lines
12 KiB
Markdown
|
|
@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.
|