informe-comercial-alfa/CLAUDE.md

59 lines
4.9 KiB
Markdown
Raw Normal View 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.