Plano completo de ecoplagas.online

Para qué sirve

Este documento describe ecoplagas.online con el detalle necesario para que una IA que programa (Claude Code u otra) pueda construir un sistema equivalente para otra empresa de servicios en campo: fumigación, limpieza, mantenimiento, instalaciones, reparaciones a domicilio. Describe qué hace cada módulo, qué datos guarda, qué reglas aplica y cómo se conectan las piezas.

No es código para copiar. Es la especificación de un sistema que ya funciona en producción todos los días, con las decisiones que se tomaron y por qué.

Cómo pasárselo a una IA

1. Darle primero la guía de ideas: https://latamcodelabs.com/como-se-construyo-ecoplagas-online.txt.
2. Darle después este plano: https://latamcodelabs.com/plano-ecoplagas-online.txt.
3. Pegarle esta instrucción, completando los corchetes:

Vas a construir para [NEGOCIO] en [PAÍS] un sistema equivalente al
descrito en las dos guías que te pasé. No copies umbrales, horarios
ni porcentajes sin validarlos conmigo.

Fase 0: haceme las preguntas necesarias sobre mi operación (servicios,
roles, turnos, cómo vendo, cómo cobro, bodegas, flota) y escribí el
modelo de datos adaptado, con las colecciones y campos de la Parte 1.

Después construí por fases, en el orden del plano, y al terminar cada
fase: publicá, probá en vivo y decime qué número de negocio medimos.

Reglas fijas:

- Firebase (Hosting, Firestore, Functions, Auth, Storage), sin build
  step, HTML + JS directo, como en la Parte 1.

- Permisos por módulo y reglas de seguridad desde el día uno, con
  pruebas en el emulador.

- Las llaves de servicios externos solo como secretos de Functions.
- Nada se borra: cancelar, archivar y dejar historial.

Orden de construcción recomendado

El sistema creció durante 10 meses. Si se empezara hoy, este es el orden que tiene sentido, porque cada fase usa los datos de la anterior:

Convenciones del plano

• Los nombres de colecciones, campos, archivos y funciones son los reales del sistema, para que se entienda la relación entre piezas. Se pueden renombrar.
• El pseudocódigo está en español y no depende de un lenguaje.
• Donde dice "gerencia", "un vendedor" o "un técnico" se refiere a un rol, no a una persona.
• Los números (minutos, metros, porcentajes) son los que funcionaron en EcoPlagas en Costa Rica en 2026.
• No se incluyen llaves, identificadores de cuentas, teléfonos ni datos de personas.

Este capítulo describe lo que comparten todas las pantallas del sistema: cómo está armado el repositorio, cómo se publica, cómo entra y se identifica una persona, cómo se decide qué puede ver y tocar, qué servicios corren en todas las páginas (encabezado, tema, reporte de problemas, presencia, aviso de versión), cómo están escritas las reglas de seguridad de la base de datos, cómo se organizan las funciones de servidor y qué se aprendió sobre costos.

El sistema es una aplicación web interna de una empresa de control de plagas (agenda de citas, rutas de técnicos, inventario de bodegas, CRM de WhatsApp, planilla, reportes). Corre sobre Firebase: Hosting para los archivos, Firestore como base de datos, Firebase Auth para las cuentas, Cloud Storage para archivos y Cloud Functions (Node.js 22) para la lógica de servidor.

1. Estructura del repositorio y publicación

1.1 Principios de construcción

• Sin paso de compilación. No hay bundler, transpilador ni npm run build para el frontend. Lo que está en public/ es exactamente lo que se sirve. Cada página es un .html autocontenido con su <script type="module"> en línea o con scripts propios al lado.
• Todo por CDN. Firebase se importa con URL completa y versión fija (SDK modular 10.12.2 desde www.gstatic.com/firebasejs/10.12.2/...). Nunca import de npm en el navegador. Bootstrap 5.3.0, Font Awesome 6.4.0, Leaflet 1.9.4, Chart.js 4.4.0, jsPDF 2.5.1, html2canvas 1.4.1, JSZip 3.10.1, SheetJS (xlsx) 0.18.5 y QRCode 1.5.3 llegan de jsDelivr, cdnjs o unpkg.
• Una página por módulo. Hay unas 290 páginas .html en public/ y unos 80 módulos JS en public/js/. Las páginas grandes (la agenda tiene unas 36 mil líneas) se fueron partiendo en archivos js/agenda-*.js que se cargan como scripts y se comunican por variables globales window.*.
• Comunicación por globales. window.db (Firestore), window.firebaseAuth, window.secureAuthManager (alias window.authManager), window.escapeHTML, y en la agenda window.todasLasCitas, window.todosLosEmpleados, etc.
• Cache busting manual con ?v=N en los src de scripts y hojas de estilo (reportar-problema.js?v=4, tema.js?v=2).
• Todo en español con tildes correctas; moneda en colones sin decimales.
• No hay ambiente de prueba. La rama main es producción. Varias personas y sesiones de IA empujan a main el mismo día, así que la regla es: pull --rebase antes de tocar y antes de empujar, agregar solo los archivos tocados por nombre, nunca push --force.

1.2 Carpetas

1.3 firebase.json

Hosting

• public: "public", con una lista ignore que excluye archivos ocultos, node_modules, respaldos (*.backup_*), scripts viejos de migración y diagnóstico que quedaron en la carpeta, y package.json.
• Sin cleanUrls. /agenda da 404: los enlaces siempre llevan .html.
• Rewrites: la raíz / sirve inicio.html; /E/** y /e/** sirven estacion.html (códigos QR de estaciones de cebo que se escanean en campo).
• Redirects: enlaces cortos con parámetros. Ejemplos del patrón: /m/:fecha/:turno → mapa_rutas.html?fecha=:fecha&t=:turno (302), /c/:fecha/:cita → agenda.html?fecha=:fecha&cita=:cita&ver=1 (302), y páginas renombradas con 301.
• Headers por tipo de archivo:

Los patrones van duplicados con y sin **/ (*.html y **/*.html) para cubrir la raíz y subcarpetas.

Otros servicios declarados: firestore (reglas e índices), database (reglas de Realtime Database, usada solo para posición en vivo de la flota), storage (reglas), functions (un solo codebase default desde functions/).

1.4 Workflows de GitHub Actions

Concurrencia. Los dos workflows de deploy tienen concurrency: { group: <nombre del workflow>, cancel-in-progress: false }. Motivo: dos pushes seguidos corrían dos deploys en paralelo y el que terminaba último pisaba al otro aunque fuera más viejo. Con la cola, los deploys salen en orden y siempre gana el más reciente.

Lo que no se publica solo: los índices de Firestore (firestore.indexes.json) se despliegan a mano. Si el Action no corre (pasó una vez por un problema de pago de GitHub), se publica a mano desde main limpio (sin cambios sin commitear), y para functions con la variable FUNCTIONS_DISCOVERY_TIMEOUT=180 porque el descubrimiento de funciones de un index.js grande supera el timeout por defecto de 10 s.

Credencial: todos los workflows usan una cuenta de servicio guardada como secreto del repositorio; se escribe a un archivo temporal del runner y se exporta como GOOGLE_APPLICATION_CREDENTIALS.

1.5 Lint de arranque

npm run lint (scripts/lint-arranque.mjs, Node puro, sin dependencias) recorre public/ y revisa:

Hoy corre en modo informativo porque hay hallazgos de línea base; la intención es volverlo bloqueante cuando R1 a R4 lleguen a cero.

scripts/test-shared.mjs verifica que public/shared/*.js (ES modules) y functions/shared/*.js (CommonJS) den exactamente el mismo resultado.

2. Autenticación

2.1 Identidad: usuario, correo sintético, ficha y lookup

• La persona escribe un username (por ejemplo usuario.ejemplo). El sistema lo convierte en el correo interno de esa cuenta y hace signInWithEmailAndPassword en Firebase Auth.
• El username canónico se obtiene de ese correo, en minúsculas y sin tildes. Hay una sola definición (shared/empleado.js: usernameDesdeCorreo) con espejo en functions/.
• Ser empleado = tener ficha, no basta el dominio del correo. El registro de cuentas de Firebase Auth quedó abierto (no se puede cerrar sin romper el inicio de sesión anónimo de una página pública), así que cualquiera podría crearse una cuenta con el dominio de la empresa. Por eso la identidad real es:

empleados_uid_lookup/{uid}  ->  { empleadoId }
empleados/{empleadoId}      ->  ficha: username, primerNombre, primerApellido,
                                 departamento, cargo, estado, permisos{}, firebaseAuthUID,
                                 firebaseAuthEmail, fotoPerfil, nombrePreferido, tipoPago...
empleados/{empleadoId}/privado/datos -> salario, cuenta bancaria, cédula, tarifas

• El 70% de las fichas tiene id aleatorio, por eso el puente empleados_uid_lookup es imprescindible: las reglas de Firestore resuelven quién sos leyendo esa fila.
• La fila del lookup solo puede apuntar a una ficha que ya tenga ese mismo firebaseAuthUID y cuyo username coincida con el del correo (ver 5.1). La ficha la crea quien administra personal.

2.2 Página de inicio de sesión (iniciar_sesion.html)

Pasos:

1. Normaliza el username, arma el correo sintético y llama signInWithEmailAndPassword.
2. Si Firebase acepta la clave, marca credencialValida = true. Desde ahí ningún error posterior se reporta como "credenciales incorrectas".
3. Carga la ficha con un tope de 25 s (Promise.race): primero empleados_uid_lookup/{uid} → empleados/{empleadoId}; si no hay lookup, busca la propia ficha con where('firebaseAuthUID','==',uid) y crea su propia fila de lookup (primer inicio de un empleado nuevo). Como respaldo intenta la lista completa de empleados y compara por correo, uid o username.
4. Redirige al destino pendiente o a inicio.html.

Clasificación de errores que ve la persona:

Destino después del login (postLoginRedirect). Cuando una página manda al login, guarda en sessionStorage {url, username} con el dueño. Al entrar, el destino solo se usa si el que entra es el mismo dueño (o si no tenía dueño, caso de un enlace directo abierto sin sesión). Motivo: teléfonos y tabletas se comparten en campo y el siguiente usuario caía en la página del anterior con "Acceso denegado". Si no hay destino guardado, vuelve a la página de origen (document.referrer) una vez cada 30 s como máximo, para no rebotar en círculo.

Parámetros que muestran aviso: ?sesion=expirada ("Se cerró la sesión, volvé a entrar y seguís donde estabas") y ?timeout=1.

2.3 auth-secure.js y la clase SecureAuthManager

auth-secure.js es un módulo ES que toda página interna importa. Hace, en orden:

1. Inicializa la app de Firebase (la configuración pública del proyecto va en el archivo o en window.firebaseConfig), getAuth, getFirestore y publica window.db.
2. Caché de Firestore en memoria solamente. Se probó persistentLocalCache con gestor multipestaña para ahorrar transferencia (la recarga de la agenda bajaba de 2,7 MB a 85 KB) y se revirtió a los tres días porque provocaba INTERNAL ASSERTION FAILED: Unexpected state al guardar citas con dos pestañas abiertas escribiendo en paralelo (agenda y CRM). Quedó documentado qué probar antes de reintentarlo: subir el SDK o usar gestor de una sola pestaña, y la prueba obligatoria de guardar una cita con dos pestañas.
3. Define PERMISOS_HEREDADOS y permisosConHerencia() (ver 3.4).
4. Instala window.FirestoreReadTracker: un registrador opcional de lecturas que encola entradas (usuario, página, colección, función, cantidad de filas, sesión, dispositivo, navegador, conexión) y las escribe en lotes de 20 en diagnostico_lecturas_firestore. Las páginas lo llaman a mano en sus consultas pesadas para medir quién lee qué.
5. Intenta App Check con reCAPTCHA v3 solo si hay una clave configurada (hoy no).
6. Expone window.firebaseAuth y window.sesionFirebaseLista = auth.authStateReady(). Si restaurar la sesión tarda más de 2,5 s, muestra un aviso fijo "Verificando tu sesión..." fuera del body (que está oculto).
7. Crea window.secureAuthManager = new SecureAuthManager().
8. Importa por efecto lateral presence-tracker.js y docs-check.js (aviso de documentos personales faltantes después del login).

Estado y métodos de SecureAuthManager:

Relojes internos:

Claves de sessionStorage: currentUser (solo datos no sensibles), firebaseAuthToken = authenticated (bandera, no es un token), employeeStoreCacheV1, postLoginRedirect, authTuvoSesion, ultimoReboteLogin, firestoreReadTrackerSessionId. No se usa localStorage para autenticación.

2.4 employee-store.js

Caché compartido de fichas de empleados para unas 40 páginas.

• Índices en memoria por username, uid y correo, hidratados desde sessionStorage['employeeStoreCacheV1'] con TTL de 15 min.
• Nunca cachea campos sensibles: cedula, fechaNacimiento, telefonoPersonal, direccion, banco, cuentaBancaria, tarifas_jornada, tope_servicios_profesionales, salario, precio_hora_sencilla_por_mes. Esos viven en la subcolección privado y las pantallas que los usan leen fresco.
• resolveEmployeeForAuth(db, {uid, email, username}, {force}): orden de búsqueda uid (lookup o ficha propia, creando el lookup si falta) → username (documento con ese id o where('username')) → firebaseAuthEmail.
• getAllEmployees(): lee la colección entera solo si el caché está vencido; si falla y no hay caché, relanza el error (devolver lista vacía hacía que el login concluyera "usuario no existe" y cerrara la sesión por un corte de red).
• clearEmployeeStoreCache() se llama al cerrar sesión.

2.5 check-permissions.js

Script clásico (no módulo), síncrono, en el <head> de casi todas las páginas. Contiene:

• window.escapeHTML (escapa & < > " '), definido acá porque es el primer archivo que carga.
• PAGE_PERMISSIONS: mapa nombre_de_archivo.html → clave o → [claves] (con lista, alcanza con tener una).
• PREFIJOS_PERMISOS: quiz- → capacitacion, admin_inventario_ → administrador_bodega, proc_mp → procedimientos_salud.
• checkPagePermissions(): si la página no tiene entrada, la deja pasar (por eso existe la regla R2 del lint). Si tiene, espera al manager, refresca permisos y muestra "Acceso denegado" si falta la clave.
• Pantallas de bloqueo: Acceso denegado (con sesión viva ofrece volver al Menú o cerrar sesión, no manda al login) y Cuenta bloqueada ("Cuenta desactivada" o "Ficha de empleado no encontrada", con el texto "Reintentar no cambia nada: lo tiene que corregir gerencia" y botón de cerrar sesión). Ambas destapan el body antes de pintarse.
• Al cargar el DOM espera hasta 15 s (75 vueltas de 200 ms) al manager. Si hay fallo administrativo, corta los reintentos (antes eran diez minutos de lecturas inútiles). Si pasa el tiempo pero Firebase tiene sesión viva, no expulsa (la red puede estar lenta y el refresco periódico la recupera).
• Intervalos: refresco de permisos cada 2 min y badge de tickets cada 30 s.
• Carga verificar-documentos.js en dos páginas de técnicos que no tienen encabezado.

2.6 Bloqueo y baja de cuentas

• Criterio único de baja (navegador y servidor): bloqueado si estado es "Inactivo" o "Suspendido" (sin importar mayúsculas), o activo === false, o estado === false. Estado vacío o "Vacaciones" cuenta como activo.
• Al dar de baja (trigger empleadoBajaOnWrite sobre empleados/{id}): deshabilita la cuenta de Auth, revoca los refresh tokens y borra empleados_uid_lookup/{uid}, con lo que isEmpleado() deja de pasar en todas las reglas sin tocarlas. Al volver a "Activo" rehabilita y recrea el lookup. Es idempotente y deja rastro en empleados_baja_log.
• En el navegador, la próxima relectura (máx. 2 min) detecta la baja, cierra sesión y muestra "Cuenta desactivada".
• No existe bloqueo propio por intentos fallidos: lo aplica Firebase Auth (too-many-requests).

2.7 Ciclo de carga de una página protegida

Cada página interna sigue esta plantilla (la de referencia es bodeguita.html):

<head>
  <link bootstrap, font-awesome, eco-plagas-styles.css, unified-styles.css>
  <script src="check-permissions.js">            // síncrono, define escapeHTML y PAGE_PERMISSIONS
  <script type="module">
     import { auth } from './auth-secure.js'      // inicia Firebase, crea secureAuthManager,
                                                   // arranca presencia
     import './track-location.js'
     ...guardia de sesión (abajo)
  </script>
  <style> body { display:none !important } body.authenticated { display:block !important } </style>
</head>
<body>
  <div id="header-container"></div>
  <script src="load-headersecure.js">            // trae header.html y servicios globales
  ...contenido...
</body>

Pseudocódigo del ciclo:

AL CARGAR LA PÁGINA:
  ocultar body
  esperar auth.authStateReady()           // Firebase terminó de restaurar la sesión guardada
                                          // (si tarda > 2,5 s, aviso "Verificando tu sesión...")
  si no hay auth.currentUser tras ~10 s:
      guardar postLoginRedirect {url, username}
      ir a iniciar_sesion.html
  window.authManager = secureAuthManager
  mostrar body (clase "authenticated")

EN PARALELO (secureAuthManager, onAuthStateChanged):
  ficha = resolver por empleados_uid_lookup/{uid} -> empleados/{id}
          (si no hay lookup: ficha propia por firebaseAuthUID y crear lookup)
  si ficha dada de baja -> error "desactivado"
  currentUser = { username, nombre, departamento, permisos: conHerencia(ficha.permisos), ... }
  guardar en sessionStorage

EN PARALELO (check-permissions.js, DOMContentLoaded):
  clave = PAGE_PERMISSIONS[archivo] o por prefijo
  si no hay clave -> página abierta a cualquier empleado
  repetir cada 200 ms hasta 15 s:
      si manager autenticado:
          refrescar permisos
          si no tiene ninguna de las claves -> pantalla "Acceso denegado"
          salir
      si fallo administrativo (desactivado o 3 veces sin ficha) -> pantalla "Cuenta bloqueada"
  si se agotó el tiempo:
      si Firebase tiene sesión viva -> quedarse (no expulsar)
      si no -> login
  cada 2 min: refrescar permisos y repintar el menú
  cada 30 s: badge de tickets

EN PARALELO (load-headersecure.js):
  fetch('header.html') e insertarlo
  filtrar módulos por permiso, ordenar por departamento, repartir en "Otros"
  inyectar: tickets-badge, reportar-problema, tema, version-watch, politica-promesas-ui,
            verificar-documentos, aviso de actividades
  escuchar 'permisos-actualizados' para repintar

CADA 60 s: presence-tracker escribe latido (si la pestaña es líder)
CADA 5 min: latido del token; track-location re-captura GPS si la pestaña está visible
CADA 60 min: version-watch mira version.json

Regla de oro documentada en el código: nunca mandar al login por un reloj solo. En redes móviles lentas Firebase puede tardar más que cualquier timeout fijo en restaurar una sesión válida; siempre se espera authStateReady() y se verifica currentUser antes de expulsar.

2.8 Alta de empleado y SSO de la app nativa

• Alta: gerencia crea la ficha en empleados.html y presiona "Crear en Firebase Auth". Eso llama la función HTTP crearEmpleadoAuth (exige permiso empleados del lado servidor), que crea la cuenta con el Admin SDK y devuelve el uid. La página escribe el uid en la ficha y el lookup (las reglas permiten a quien tiene empleados escribir el lookup de otro uid solo si es coherente con la ficha).
• App Android: la función callable mintWebToken recibe la sesión de la app y devuelve un custom token; un WebView hace signInWithCustomToken y entra a las páginas web con la misma sesión, sin segundo login.

3. Sistema de permisos

3.1 Modelo

• Los permisos son un mapa de booleanos en la ficha: empleados/{id}.permisos = { calendario: true, ruta: true, ... }.
• Un permiso por botón del menú, no por departamento. Así se puede dar uno sin dar otro y revocar sin efectos colaterales. Regla de diseño: todo módulo nuevo nace con su propia clave, que hereda de reportes_gerenciales (en la práctica, gerencia) hasta que alguien la marque explícitamente.
• Gerencia no es un permiso sino un criterio: departamento o cargo que contiene "gerenc" o "gerent" (sin tildes, sin mayúsculas). En el servidor además vale permisos.gerencia === true. Gerencia pasa todos los exigirPermiso del servidor y muchas excepciones de reglas.
• Se verifica en tres capas: la página (check-permissions.js, solo interfaz), las reglas de Firestore (permiso('clave'), solo para colecciones con bloque propio) y las Cloud Functions (exigirPermiso).

3.2 Tabla completa de claves

La columna "Etiqueta" es el nombre de la casilla en la pantalla de Equipo (MODULOS_ACCESO de empleados.html), que coincide con el botón del menú.

Páginas sin entrada en el mapa ni prefijo (abiertas a cualquier empleado con sesión): menu.html, perfil.html, inicio.html, iconos-comunidad.html, index.html. Páginas públicas (sin sesión): encuesta.html, garantia.html, verificar-certificado.html, cliente.html, certificado_fumigacion.html, privacidad.html, terminos.html, eliminacion-datos.html, wa.html (con sesión anónima), reporte_cliente_citas.html, estacion.html.

3.3 Herencia de claves

Cuando un acceso se separó en dos, o nació un módulo nuevo, la clave nueva se hereda de una vieja mientras no exista en la ficha. En cuanto gerencia guarda a esa persona en Equipo, todas las claves quedan escritas explícitamente y la herencia deja de aplicar (ahí sí se puede quitar Ruteador sin quitar Agenda). Es derivación en memoria, nunca escribe en Firestore.

función permisosConHerencia(permisos):
  p = copia(permisos)
  para cada (nueva, padres) en PERMISOS_HEREDADOS:
      si p[nueva] ya existe (true o false): seguir      // explícito manda
      padres = lista(padres)
      p[nueva] = alguno de padres tiene p[padre] == true
  devolver p

La tabla vive en tres copias que deben mantenerse iguales a mano: public/auth-secure.js (la que decide en el navegador), public/empleados.html (para que la pantalla de Equipo muestre el acceso real) y functions/auth-empleado.js (servidor). Además, las reglas de Firestore no aplican la tabla: los bloques que lo necesitan repiten la herencia en línea con misPermisos().get('clave', misPermisos().get('reportes_gerenciales', false)).

Diferencias detectadas al 31-oct-2026 entre las copias: empleados.html agrega garantias ← reportes_gerenciales y gps_ventas ← gps, que no están en auth-secure.js; la copia del servidor no tiene respuestas_coordinacion, satisfaccion_clientes, videos_reuniones, cotizaciones ni cotizaciones_aprobar, y conserva una clave retirada. Quien reconstruya el sistema debería tener una sola definición compartida (como ya se hizo con shared/telefono.js).

3.4 Cómo se agrega un módulo nuevo

1. public/check-permissions.js: PAGE_PERMISSIONS['nuevo.html'] = 'nuevo' (y la clave en la lista de hasAccessToOtherModules).
2. public/auth-secure.js: PERMISOS_HEREDADOS.nuevo = 'reportes_gerenciales', con comentario de la fecha de nacimiento. Si lo usa también el servidor, la misma línea en functions/auth-empleado.js.
3. public/header.html: el enlace <a href="nuevo.html" class="mobile-nav-item" data-permission="nuevo" title="..."> con su ícono.
4. public/load-headersecure.js: título y subtítulo en pageConfigs, y opcionalmente color en COLOR_MODULOS, grupo en GRUPOS_MODULOS y puesto en ORDEN_MODULOS.
5. public/empleados.html: entrada en MODULOS_ACCESO, entrada en su PERMISOS_HEREDADOS local, casilla permisoNuevo en el modal (el id se deriva de la clave en CamelCase), y la lectura con herencia y escritura de esa casilla al guardar.

Si el módulo tiene colecciones sensibles: bloque propio en firestore.rules y agregar el nombre a la lista de exclusión del comodín (ver 5.2).

4. Encabezado y servicios transversales

4.1 header.html y load-headersecure.js

load-headersecure.js es un script clásico que define la clase HeaderLoader (instancia en window.HeaderLoader.instance):

• Hace fetch('header.html') y lo inserta en #header-container (lo crea si no existe). Agrega Font Awesome si la página no lo trae y un favicon SVG en línea si falta.
• pageConfigs: unas 96 entradas archivo.html → {title, subtitle} con ícono.
• Marca como activo el botón del módulo actual; las subpáginas se resuelven a su módulo padre con reglas exactas y por prefijo.
• Filtrado por permiso: cada <a class="mobile-nav-item"> lleva data-permission="clave" o "clave1,clave2" (alcanza con una). Sin atributo, lo ve todo el mundo. data-sin-permiso="clave" oculta el botón a quien sí tiene esa otra clave (el Mini táctico no le sale a quien ve el Táctico completo). La rejilla está invisible hasta terminar de filtrar, para no mostrar un instante módulos ajenos.
• Orden por departamento: ORDEN_MODULOS tiene una lista por departamento (Gerencia, Ventas, Fumigación, Bodega, Administración) y una general *. Se calculó contando días-persona de uso por página en una semana (de los registros de dim_location) y se pega a mano. Si la ficha no trae departamento se deduce de los permisos (Reportes → Gerencia, Vendedor → Ventas, Ruta sin Agenda → Fumigación).
• Máximo 15 visibles. El resto pasa a un panel "Otros" con buscador (sin tildes) y agrupado por área (GRUPOS_MODULOS: Rutas y citas, Ventas, Clientes, Bodega, Personal, Dinero, Gerencia, Ministerio de Salud, y "Más" para lo no clasificado). El botón "Otros" muestra el conteo.
• Color fijo por módulo (COLOR_MODULOS), elegido para que no se repita entre los 10 primeros de cada departamento.
• En celular la rejilla vive detrás de un botón; con mouse se cierra al salir del panel (2,5 s de gracia), en táctil solo con un toque afuera (los eventos de mouse simulados tras un toque la cerraban).
• Escucha permisos-actualizados y revisa durante 15 s la bandera _permisosCambiaron por si el cambio llegó antes de que el header existiera.
• Muestra la foto de perfil en el botón Perfil; el botón Salir llama logout().

Scripts que inyecta en todas las páginas con header: tickets-badge.js (cuenta tickets pendientes con getCountFromServer), reportar-problema.js, politica-promesas-ui.js, js/version-watch.js, tema.js, verificar-documentos.js (portón de documentos obligatorios para técnicos) y el aviso de la actividad abierta. Cada inyección se protege con una bandera window._xCargado y comprobando si el <script> ya existe.

Tiempo activo: en el mismo archivo, un latido de 60 s mantiene viva la sesión de trabajo abierta (work_sessions con status: 'working' y modo: 'tiempo_activo') actualizando lastActivity; tras 2 horas sin interacción la cierra con closedBy: 'inactividad_automatica' y endTime = última actividad. Al cargar, cierra las sesiones viejas que superen ese umbral.

4.2 tema.js (Claro, Suave, Oscuro)

Botón junto al bicho con tres temas. No repinta las páginas (son cientos, con colores escritos a mano): aplica un filter sobre <html>, el único elemento donde un filtro no rompe los position: fixed.

• Suave: brightness(.86) contrast(.96) sepia(.16) saturate(.95).
• Oscuro: invert(1) hue-rotate(180deg), y re-invierte fotos, videos, canvas, iframes, mapas y avatares para que se vean normales. Si algo sale invertido, se agrega su selector a la lista de re-inversión, no colores nuevos.
• Se guarda en localStorage (aplica sin destello) y en preferencias_usuario/{uid}.tema (la cuenta manda sobre el dispositivo).

4.3 reportar-problema.js (botón del bicho)

Botón naranja en la barra (o flotante si la página oculta el header). Abre un formulario: qué pasó (texto o dictado), qué esperaba, qué tanto lo afecta, y pantallazos (captura con html2canvas, archivos o pegar con Ctrl+V).

Desde que carga arma una bitácora en memoria: intercepta console.error/warn, errores JS no atrapados y fetch que fallan (status ≥ 400 o sin respuesta; la URL va sin query por si trae un token). Al enviar agrega solo: usuario y permisos, página, URL, título, fecha en UTC y en Costa Rica, tamaño de ventana y pantalla, zoom, navegador, sistema, conexión, modales abiertos con extracto de su texto, inputs de fecha visibles, parámetros de URL, y lo que la página aporte con window.reportarProblemaContexto().

Guarda en la colección reportes_problemas y los pantallazos en Storage reportes_problemas/<id>/N.jpg; ambas rutas caen en las reglas comodín de empleados. Gerencia los revisa en problemas_reportados.html (abiertos/resueltos, copiar como texto). La página expone window.reportesProblemas.exportar('abierto') para que una IA los lea con el texto listo y las URL de los pantallazos.

4.4 Presencia y uso de módulos

presence-tracker.js (importado por auth-secure.js, corre en toda página autenticada):

• Elección de líder entre pestañas con un lease en localStorage; solo la líder escribe, para no inflar conteos con varias pestañas. Las pestañas se comunican por BroadcastChannel('presence_tracker'): se pasan su último input y se cuentan entre sí.
• Escribe presence_live/{username} con {state: 'active'|'idle', lastBeat, sessionId, page, tabs, expireAt}.
• Escribe presence_days/{username}_{YYYY-MM-DD} con un mapa por minuto del día slots[0..1439] = {a|i: increment(1), k (input fuerte), t} y un mapa paginas[<pagina sin .html>] = {a|i: increment(1)} (minutos activos o abierta sin uso por página). Es lo que mide qué módulos se usan.
• Nunca escribe "offline": se infiere por ausencia de latido en el visor.

track-location.js (lo importan las páginas): en cada carga, cambio de URL por pushState, popstate o hash (no replaceState, porque una página lo llamaba por cada clic) y cada 5 min con la pestaña visible, toma la posición GPS (alta precisión, timeout 12 s, acepta lecturas de hasta 30 s) y, si la precisión es ≤ 500 m, agrega un documento a dim_location con {usuario, hora_local, latitud, longitud, accuracy, url, pagina, ts}. Falla en silencio si no hay permiso de ubicación. Además de la ubicación, sirve como registro de qué página se abrió y cuándo.

Visor: reporte_actividad.html y pulso.html muestran quién está activo e inactivo.

4.5 Aviso de versión nueva (version.json y js/version-watch.js)

• El workflow escribe version.json en cada deploy (no está en el repo).
• version-watch.js lo pide cada 60 minutos (antes 45 s: con muchos deploys seguidos el aviso salía sin parar). Guarda la versión con la que abrió la página.
• Si cambió: si la persona está "ocupada" (modal abierto, foco en un campo, tecla en los últimos 2 min, o ya tocó o cambió algo en la página), muestra una pastilla amarilla arriba al centro con botón "Actualizar" y no recarga sola. Si la pestaña está en segundo plano, recarga al volver. Si no hay nada abierto ni escrito, recarga sola tras una cuenta regresiva de 3 s.
• Se carga también en páginas sin header (quizzes, hoja de servicio).

4.6 Otros helpers transversales

• escapeHTML: definido en check-permissions.js y respaldado en load-headersecure.js para páginas sin el primero. Obligatorio para todo contenido de usuario que vaya a innerHTML.
• nombre-empleado.js: dos campos que no se mezclan: nombrePreferido (cómo quiere que la llamen, manda en toda la app) y aliasRuta (apodo corto para el cronograma). El nombre legal completo solo en planillas, certificados y auditoría.
• shared/telefono.js: forma canónica = la del wa_id de WhatsApp: solo dígitos, con código de país, sin "+". Quita 00 inicial; 8 dígitos → 506 + número; 10 dígitos que empiezan con 06 → antepone 5; ids de Messenger (fb_...) e Instagram no son teléfonos. Es la llave de cruce entre citas, leads, cartera y llamadas. Reemplazó 33 normalizadores distintos.
• shared/canales.js: lista de canales de captación (ad Meta, google_ads, youtube, bing, tiktok, sitio_web, directo, messenger, saliente, empleo, referido...) con etiqueta, color, columna de gasto en pauta_spend, si entra al reparto de leads y si cuenta como lead.
• shared/empleado.js: usernameDesdeCorreo, esActivo, esGerencia.
• shared/moneda.js: ver 8.4.
• sw.js: un service worker que se autodesinstala y borra cachés (quedó para limpiar uno viejo). No hay PWA ni funcionamiento sin conexión.
• mobile-ui.js, header-compacto.js: ajustes de interfaz en celular.

5. Reglas de Firestore y Storage

firestore.rules tiene unas 2.000 líneas y 89 bloques match. Se publican con cada push a main.

5.1 Funciones base

isEmpleadoSoloDominio():
    autenticado y con correo del dominio de la empresa
    // NO prueba que trabaje acá (el registro está abierto). Solo se usa para
    // leer la propia ficha y crear el propio lookup antes de tenerlo.

isEmpleado():
    isEmpleadoSoloDominio() y exists(empleados_uid_lookup/{uid})

tieneLookup():          = isEmpleado()        // alias histórico usado en decenas de reglas
miEmpleadoId():         get(empleados_uid_lookup/{uid}).empleadoId
misPermisos():          get(empleados/{miEmpleadoId()}).permisos
miUsername():           username derivado del correo del token, en minúsculas
                        // sin leer la ficha: ahorra una lectura por escritura
esMiNombre(v):          v en minúsculas es miUsername, o el correo completo,
                        o la parte local del correo (las páginas firman de tres formas)
permiso(clave):         tieneLookup() y misPermisos().get(clave, false) == true
esGerencia():           tieneLookup() y (departamento o cargo calza ".*geren(c|t).*")

Notas de diseño:

• exists/get sobre el mismo documento se cachea dentro de una evaluación, así que la lectura del lookup no se paga dos veces.
• matches() exige coincidencia completa: gerenc no calza "gerente", por eso geren(c|t).
• permiso() no aplica la herencia. Por eso las reglas solo dependen de unas pocas claves "duras" (empleados, planilla, reportes_gerenciales, administrador_bodega, liquidaciones, portal_clientes_admin, anular_monto_cita, edicion_horas, pulso, gps, gps360, gps_ventas, lealtad, logistica), y los bloques de módulos nuevos repiten la herencia en línea.

Ficha y lookup:

empleados/{empId}
  read:   isEmpleado()  o  (soloDominio y ficha.firebaseAuthUID == mi uid)
  update (autoservicio): solo la propia ficha (correo == username de la ficha)
          y solo campos: cedulaFotoFrente, cedulaFotoDorso, licenciaFotoFrente,
          licenciaFotoDorso, fotoPerfil, nombrePreferido
  create/update (administración): permiso('empleados')
          y (no es la propia ficha o esGerencia())
          y no deja una ficha ajena con mi uid (sinColgarseDeFichaAjena)
  update (quitarse accesos): permiso('empleados'), propia ficha, solo el campo permisos,
          y sin GANAR empleados, planilla ni reportes_gerenciales (quitárselos sí)
  delete: permiso('empleados') y (no propia o gerencia)
  empleados/{empId}/privado/{doc}
     read:  la propia persona, planilla, empleados, reportes_gerenciales o gerencia
     write: (empleados o gerencia) y (no propia o gerencia)

empleados_uid_lookup/{uid}
  read:   isEmpleado()  o  (soloDominio y uid == mi uid)
  create/update: solo el campo empleadoId, y además:
          (soloDominio y uid == mi uid y apuntaAMiFicha(empleadoId))
             // la ficha existe, lleva mi uid y su username es el de mi correo
          o (permiso('empleados') y uid != mi uid y lookupCoherente(uid, empleadoId))
             // la ficha destino lleva exactamente ese uid
  delete: permiso('empleados')

Estas amarras cierran dos escaladas reales que se encontraron: un técnico que apuntaba su lookup a la ficha del gerente y heredaba todos sus permisos, y un administrador que le plantaba su propio uid a la ficha de gerencia para luego apuntar su lookup ahí.

5.2 El comodín y su lista de exclusión

Las reglas de Firestore se suman: si una regla general permite algo, ninguna regla más específica lo puede quitar. Por eso el comodín no es {document=**} sino de un segmento con nombre:

match /{col}/{documento=**} {
  allow read, write: if isEmpleado() && !(col in [ ...lista de exclusión... ]);
}

• Toda colección nueva queda cubierta automáticamente para empleados (leer y escribir).
• Las colecciones con bloque propio tienen que estar en la lista de exclusión, si no el comodín las vuelve a abrir. La lista tiene unas 85 colecciones: empleados, empleados_uid_lookup, citas, planilla, historico_planillas, planilla_cierres, liquidaciones, whatsapp_conversations, whatsapp_messages, whatsapp_activity, whatsapp_reclamos, whatsapp_autoassign_config, stock_bodegas, movimientos_inventario, flota_tracks, flota_gps_estado, flota_gps_equipos, velocidad_diaria, dim_location, work_sessions, vacaciones, snapshots_ventas, encuestas, encuestas_citas, reportes_cliente, wa_clicks, garantias, tickets_rojo, reportes_publicos, portal_cuentas, portal_accesos, portal_meta, tickets_sucursal, wa_equipo_*, bot_ventas_*, publicidad_*, cumplimiento_*, videos_*, recuperador_cartera*, satisfaccion_*, certificados_emitidos, citas_monto_log, empleados_baja_log, _rate_limits, clientes_bloqueo, roles_ventas, politica_promesas, promesas_bloqueadas y otras.
• Se descubrió que algunas tenían bloque propio pero faltaban en la lista; se corrigió y se dejó comentado.

5.3 Patrones recurrentes

5.4 Colecciones sensibles: quién lee y quién escribe

5.5 Storage

isEmpleado(): correo del dominio y firestore.exists(empleados_uid_lookup/{uid})

/commons/**                         lectura pública, sin escritura
/publicidad/**, /cumplimiento/**    empleados
/videos_publicitarios/**            leer empleados, escribir nadie (se sube por consola/servidor)
/videos_reuniones/**                leer con permiso videos_reuniones (o Reportes), escribir nadie
/garantias_publicas/{token}/**      leer público; crear sin login: imagen < 10 MB o video < 60 MB;
                                    editar o borrar empleados
/{archivo} y /{carpeta}/**          empleados, salvo carpetas wa_equipo y videos_reuniones;
                                    al crear: < 60 MB y tipo permitido (imagen, video, audio, PDF,
                                    Office, texto, zip, json, octet-stream)
/wa_equipo/{numero}/salida/{archivo} empleados (adjuntos que luego manda el agente)

El bucket tiene una configuración CORS que se aplica en cada deploy para que el navegador pueda leer fotos y meterlas en un PDF o imagen; CORS no da acceso, las reglas siguen mandando.

5.6 Realtime Database

Se usa solo para la posición en vivo de la flota (flota/live/{usuario}): cada técnico escribe solo su nodo con validación de tipos (lat, lng, ts, usuario, estado, bat, vel, etc., cualquier otro campo rechazado); leen todos solo los usuarios marcados en flota/admins.

5.7 Cómo se prueban

• Compilar no es estar cerrado. Una regla que compila puede estar abierta de par en par (el caso del comodín recursivo dentro de citas).
• Se prueban con @firebase/rules-unit-testing contra el emulador de Firestore (firebase emulators:start --only firestore --project demo-x, variable FIRESTORE_EMULATOR_HOST=127.0.0.1:8080). Al 18-oct-2026 eran 144 casos.
• Tres grupos de casos: lo que el equipo hace a diario (tiene que pasar), intentos de abuso (tienen que fallar), y documentos raros (sin el campo, con el campo en 0, con decimales, y borrando el campo con deleteField() para esquivar la comparación).
• El emulador necesita Java; se puede usar un JDK portable sin instalar nada.
• El archivo de pruebas no está en el repositorio (se arma en un directorio temporal).
• Las funciones tienen pruebas unitarias propias en functions/test-bot-ventas/*.test.js (bot de ventas, envío de WhatsApp, geografía, asignación) y inventario.js exporta sus funciones internas para probarlas sin emulador.

6. Cloud Functions

6.1 Organización

• Firebase Functions v2 (firebase-functions/v2/https, /firestore, /scheduler), Node 22, región us-central1, Admin SDK inicializado una vez.
• functions/index.js concentra unas 9.300 líneas y 169 exports. Los dominios nuevos viven en módulos propios y se cablean de dos formas:
• Módulo que exporta funciones ya construidas: exports.portalAdminLeer = require('./portal-admin').portalAdminLeer.
• Módulo fábrica: require('./web-leads').construir({ onRequest, onSchedule, admin, origenes, secretos, enviarPlantilla }) devuelve las funciones, inyectándoles dependencias de index.js (secretos, helpers de envío, orígenes CORS). Así el módulo no conoce index.js y se puede probar.
• Triggers livianos con require perezoso dentro del handler: async () => { await require('./velocidad-resumen').barrer(admin.firestore(), admin) } (el arranque en frío no carga módulos que la función no usa).
• Secretos por defineSecret (Secret Manager): token y número de WhatsApp Cloud API, secreto de la app y token de verificación del webhook, tokens de Meta Marketing y de la página, clave de Anthropic, clave de ElevenLabs, credenciales de Twilio, clave de Esri, claves compartidas para el feed de Google Ads y para la ingesta de gasto. Cada función declara solo los que usa.
• Opciones por función: memory (256 MiB a 2 GiB), timeoutSeconds (10 a 540), maxInstances (3 a 20 donde importa no saturar), retry en triggers donde un reintento es seguro, cors con lista de orígenes permitidos (ALLOWED_ORIGINS para el sistema interno, SITE_CORS_ORIGINS para el sitio público).
• Dependencias: firebase-admin, firebase-functions, node-fetch, form-data, ffmpeg-static (convertir audios de WhatsApp a OGG/Opus), puppeteer-core + @sparticuz/chromium (generar imágenes de citas y mapas en el servidor).

6.2 Helpers comunes

Patrón de un endpoint HTTP:

exports.algo = onRequest({ cors: ORIGENES, region, secrets: [...], timeoutSeconds }, async (req, res) => {
  si req.method != 'POST': 405
  authUser = await verifyEmpleado(req)
  si !authUser: 401
  si !exigirPermiso(authUser, ['clave_del_modulo']): 403 { error: 'Sin permiso de X' }
  validar body
  leer/escribir con admin.firestore() (ignora reglas), en transacción si toca saldos o montos
  dejar rastro (log o historial)
  res.json({ ok: true, ... })
})

En el navegador:

token = await firebaseAuth.currentUser.getIdToken()
fetch('https://<region>-<proyecto>.cloudfunctions.net/<nombre>',
      { method: 'POST', headers: { Authorization: 'Bearer ' + token, 'Content-Type': 'application/json' },
        body: JSON.stringify(datos) })

6.3 Inventario de funciones HTTP y callable

Identidad y empleados

IA de texto (Anthropic)

WhatsApp Cloud API (línea oficial) y CRM

Telefonía (Twilio)

Publicidad y atribución

Clientes, lealtad, cartera

Portal de clientes (otro proyecto de Firebase sirve el portal; estas funciones son su backend)

portalEnviarCodigo (código de acceso por WhatsApp, autenticado con clave compartida porque el portal es otro proyecto), portalAdminLeer, portalAdminGuardar, portalAdminListar, portalAdminSimular (ver el portal como un teléfono), portalAdminCuenta, portalAdminSellarIdentificadores, portalAdminArbol (cliente → sedes → reportes), portalAdminEjecutivos, portalAdminSede, portalAdminMachote (servicio escrito sin agendar), portalAdminCatalogo, portalAdminTranscribir (audios de reportes a texto, una sola vez), portalAdminEstado, portalAdminFusionar, portalAdminFusionarSede, portalAdminVincularPlaces, portalAdminCrearSede, portalAdminBorrarSede, portalAdminBloqueo, portalAdminCrearTicket, portalAdminCrearRefuerzo, portalAdminRefuerzoEstado, portalAdminEditarRefuerzo, portalTicketGuardar/Listar/Estado/Borrar (tickets con visibilidad interno, gerencia o cliente filtrada en servidor), clienteFicha, clienteCartera, clienteCuentas, portalAdminTickets, portalAdminTicketEstado, portalAdminSyncEspejoCartera, portalAdminBootstrapSoT, portalAdminVerificarEspejo, portalAdminBorrarCitasDemo, portalPushCuenta, portalSolicitudesListar, portalSolicitudConvertir, portalSolicitudDescartar.

Operación, citas e inventario

6.4 Triggers de Firestore

6.5 Funciones programadas

Todas con zona horaria America/Costa_Rica (UTC-6, sin horario de verano).

Observación de diseño: las tareas nocturnas se escalonan entre 4:20 y 5:00, antes de que empiece el día operacional a las 5:00.

7. Colecciones de Firestore

Inventario obtenido de las llamadas collection(...) y doc(...) en public/ y functions/ (más de 220 nombres). Agrupado por dominio.

7.1 Personas y tiempo

7.2 Citas y operación de rutas

7.3 Flota y GPS

7.4 Inventario

7.5 CRM, WhatsApp y ventas

7.6 Publicidad, sitio web y finanzas

7.7 Portal de clientes, soporte y sistema

8. Patrones de interfaz, fechas y moneda

8.1 Componentes y librerías

• Bootstrap 5.3.0 para grilla, botones, formularios y modales. Hay un limpiador de fondos de modal huérfanos (js/agenda-cleanup.js) porque abrir un modal desde otro dejaba el backdrop pegado.
• Tablas oscuras: css/dark-tables.css resetea las tablas de Bootstrap y aplica un tema oscuro basado en variables CSS (--bg-card, --border, --text-primary, etc.). Regla: incluirlo después de Bootstrap, nunca parchear variables de Bootstrap una por una. Preferencia del negocio: tablas compactas, una línea por celda.
• Mapas: Leaflet 1.9.4 con teselas de OpenStreetMap (y una capa satelital de Esri), polígonos de provincias, cantones y distritos desde un KML y JSON propios, Leaflet.heat para mapas de calor. Google Maps JS se usa en la agenda para cálculo de traslados. Geocodificación inversa con Nominatim y rutas con OSRM (ambos permitidos en la CSP).
• Gráficos: Chart.js 4.4 con el plugin de etiquetas de datos.
• PDF e imágenes: jsPDF 2.5.1 (+ autotable), html2canvas 1.4.1 para capturar pantallas y armar imágenes de citas, QRCode para certificados y gafetes, JSZip para descargas múltiples, SheetJS para exportar a Excel.
• Compresión de imágenes antes de subir (js/agenda-images.js): lado mayor máximo 1.280 px, JPEG calidad 0,72, y si pasa de 350 KB baja la calidad en pasos hasta un mínimo de 0,4. Archivos que no son imagen (video, PDF) se suben sin comprimir con tope de 40 MB. Ruta en Storage por entidad (citas/<id>/...).
• Dictado: reconocimiento de voz del navegador para comentarios, con corrección posterior por IA (mejorarTexto).
• Nada de filas nuevas para cosas chicas: un botón, contador o filtro va en el espacio que ya existe (al final del título, dentro del campo) o como ícono con title, para no empujar contenido hacia abajo.
• XSS: todo texto de usuario en innerHTML pasa por escapeHTML.
• Colores de rutas: 10 colores fijos (Ruta 1 a 10) que se repiten para 11 a 20, usados igual en agenda, alisto y mapas.

8.2 Zona horaria

• Costa Rica es UTC-6 fijo, sin horario de verano. El servidor corre en UTC; el navegador del equipo está en hora local.
• En el navegador se formatea la fecha con los componentes locales (getFullYear, getMonth, getDate), nunca con toISOString() (que da UTC y entre las 18:00 y la medianoche ya es el día siguiente; el lint lo marca).
• En el servidor: new Date(t - 6h).toISOString().slice(0,10), o toLocaleDateString('en-CA', {timeZone: 'America/Costa_Rica'}) para YYYY-MM-DD, y toLocaleString('es-CR', {timeZone: 'America/Costa_Rica'}) para mostrar.
• El campo inicio_gmt6 de las citas es un Timestamp con el instante real; el nombre recuerda que se interpreta en GMT-6.

8.3 Día operacional (5:00 a 4:59)

El día de trabajo va de las 5:00 a las 4:59 del día siguiente (hay turnos nocturnos). Una cita a la 1:00 del martes pertenece al lunes. Se indexa con fecha_dia y fecha_mes calculados al guardar:

función camposIndexados(inicio):
    f = inicio - 6 horas                  // llevar el instante a hora de Costa Rica (en UTC)
    si f.horaUTC < 5: f = f - 1 día
    fecha_dia = AAAA-MM-DD de f
    fecha_mes = AAAA-MM de f

Consultar un día: where('fecha_dia', '==', 'AAAA-MM-DD'). El turno nocturno cuenta en el día en que empezó (también en resúmenes de velocidad y presencia). El corte de las 5:00 también decide si una sesión de trabajo abierta es "de hoy".

8.4 Moneda

• Colones costarricenses, sin decimales: 20000 significa ₡20.000.
• Formato único (shared/moneda.js): es-CR, punto de miles, sin decimales. numero(n) → "1.234.567", colones(n) → "₡1.234.567", con opción de espacio. parseColones(texto) entiende "₡1.234.567", "1,234,567", "1.234,50" y negativos (si hay coma y punto, el último es el decimal; uno solo seguido de exactamente 3 dígitos es separador de miles). Reemplazó 45 formateadores distintos.
• En las reglas, los montos son números enteros y se comparan antes y después de la escritura.
• El presupuesto de anuncios en Meta se expresa en colones enteros.

9. Costos y rendimiento: lo aprendido

Lo que dejó documentado el código y las auditorías de costo:

1. El costo dominante de Firestore fue transferencia de datos (bytes que salen), no cantidad de lecturas. Una auditoría atribuyó el gasto a las citas, se migró el historial fuera del documento (bajó el peso de cada cita de 11 a 13 KB a unos 2,6 KB y las lecturas diarias a un tercio), pero los GB transferidos no se movieron. La causa real eran los listeners del CRM que traían colecciones enteras (unos 16.000 documentos por pestaña en cada recarga). Lección: mirar la exportación de facturación por SKU y por hora antes de asumir la causa; un piso plano de madrugada es un listener vivo sin nadie mirando.
2. Listeners con tope medido contra datos reales. Los streams del CRM pasaron a: lista "caliente" de 800, cartera propia de 5.000 (la más grande real era de unos 4.400) y clientes de 3.500 (había unos 3.000). Bajar un tope sin contar puede esconder datos de verdad. Los totales por categoría se obtienen con getCountFromServer (agregación, no descarga documentos) y las categorías se cargan al entrar a ellas, con relectura a los 2 min.
3. Pausar streams en segundo plano. Un stream grande que quedaba vivo toda la noche con el reparto automático encendido transfería del orden de 1 GB por hora; se reemplazó por uno chico de 200 documentos por recencia.
4. No guardar historiales dentro del documento principal. El historial completo de cada cita vive en citas/{id}/extras/historial; la cita conserva solo un extracto de los campos que los reportes leen en masa y ultima_edicion.
5. Caché persistente del SDK: se probó y se revirtió por el fallo del gestor multipestaña (ver 2.3). Queda pendiente con condiciones claras.
6. Polling y listeners caros identificados: el badge de tickets que leía toda la colección cada 30 s pasó a getCountFromServer; la presencia en vivo con onSnapshot sobre todos los empleados (cada latido re-entregaba todo); consultas sin rango de fecha en edición de horas; páginas que cargaban meses de citas al abrir. Hay unos 78 onSnapshot en 26 archivos: cada uno es candidato a revisar.
7. Cachés de servidor para cálculos caros: tactico_ventas_cache (minutos, compartida entre todos), plantillas_stats (barrido de unas 65 mil lecturas), cache_lealtad, reporte de escritura con candado de 12 h, resumen mensual de ventas que recalcula solo la cola reciente usando fragmentos congelados de meses anteriores (TTL 5 min), atributos del CRM incrementales (reescanear 82 mil mensajes cada noche serían unos 2,5 millones de lecturas al mes).
8. Caché del cliente: fichas de empleados en sessionStorage 15 min; verificación de empleado en servidor 5 min por uid.
9. Firma estable antes de reaccionar a cambios: comparar objetos con JSON.stringify sin ordenar claves provocó relecturas en bucle.
10. Reintentos que no se cortan: una cuenta desactivada reintentaba la lectura de su ficha durante diez minutos (miles de lecturas). Ahora los fallos administrativos cortan el ciclo.
11. Registrador de lecturas (FirestoreReadTracker → diagnostico_lecturas_firestore) y página reporte_diagnostico_lecturas.html para ver qué página y función leen más.
12. No escribir en exceso: track-location ignora replaceState (una página lo llamaba en cada clic) y descarta lecturas de más de 500 m de error; presencia escribe solo desde la pestaña líder.
13. Reglas abiertas cuestan dinero: mientras las reglas estuvieron laxas, bots podían leer y escribir gratis a cuenta de la empresa. Las rutas públicas se acotan en forma y tamaño.
14. Directions de Google: el modo con tráfico en vivo cuesta casi el doble por llamada; se recomendó usarlo solo para el día en curso, no recalcular fechas pasadas, recalcular solo rutas desactualizadas y usar una matriz de distancias en lugar de una llamada por resultado. La llave de mapas está restringida a las APIs que se usan.
15. Documentos con tope de tamaño: los recorridos de GPS se parten en bloques de 6 horas para no acercarse a 1 MB por documento.
16. Respaldos de Firestore: la retención semanal se bajó de 84 a 28 días.
17. Índices y TTL: 54 índices compuestos declarados; políticas TTL en presence_live, presence_days y _rate_limits (campos expireAt/expira, configuradas en consola).

10. Inconsistencias conocidas que conviene no copiar

• Tres copias de la tabla de herencia de permisos (navegador, pantalla de Equipo, servidor) con diferencias, más la herencia repetida a mano en las reglas.
• Una página sin entrada en PAGE_PERMISSIONS queda abierta a cualquier empleado: el valor por defecto debería ser cerrado.
• esGerencia en las reglas mira solo departamento y cargo; en el servidor también acepta permisos.gerencia.
• Las reglas nombran usuarios concretos en dos lugares (un destino especial de leads y una persona autorizada a editar la calidad de venta); conviene modelarlo como permiso.
• index.js de funciones concentra 169 exports y más de 9.000 líneas; los módulos con fábrica (construir({...})) son el patrón a seguir.
• El registro de cuentas de Firebase Auth quedó abierto por una página pública con sesión anónima; toda la seguridad descansa en el lookup. Un sistema nuevo debería cerrar el registro y usar otra vía para lo anónimo.

Este capítulo describe todo lo que va desde que una cita se agenda hasta que el técnico la ejecuta, la reporta, la cobra y el cliente recibe su reporte, certificado o encuesta. Incluye la planificación de rutas (ruteador), la salida de bodega (despacho y alisto), la vista del técnico (ruta.html), los procesos de servidor que vigilan la operación y las pantallas de logística y geografía.

Convenciones del capítulo:

• "Cita" es un documento de la colección citas. Casi todo su contenido vive en el mapa metadata.
• "Ruta" es un texto fijo "Ruta 1" a "Ruta 20" o "Sin asignar".
• Los montos son colones enteros, sin céntimos.
• La zona horaria es Costa Rica, UTC-6 fijo todo el año (sin horario de verano). Todo el sistema calcula la hora local restando 6 horas a UTC y leyendo los getters UTC, sin depender de la zona del navegador o del servidor.
• "La central" es la sede de la empresa, de donde salen y a donde vuelven todas las rutas. Sus coordenadas están fijas en el código de varias pantallas y funciones.
• "Gerencia" es un rol: empleado con departamento gerencia (en las reglas de Firestore también cuenta un cargo que contenga "gerenc" o "gerent").

1. Conceptos transversales

1.1 Día operacional

La jornada va de las 5:00 a. m. a las 4:59 a. m. del día siguiente. Una cita a las 2:00 a. m. pertenece al día anterior. Esto permite que las rutas nocturnas (que trabajan hasta la madrugada) queden en un solo día.

Cada cita guarda dos índices derivados que se recalculan en cada guardado que toque inicio_gmt6:

buildCitaIndexedFields(cita):
  g6 = inicio_gmt6 - 6 horas            // hora local de Costa Rica, leída con getters UTC
  si g6.horaUTC < 5: g6 = g6 - 1 día     // la madrugada es de la jornada anterior
  fecha_dia = g6 como 'AAAA-MM-DD'
  fecha_mes = g6 como 'AAAA-MM'
  telefono_normalizado = normalizarTelefono(telefono)   // '506' + 8 dígitos, o '+' + dígitos si es extranjero

• Consulta canónica de un día: citas where fecha_dia == 'AAAA-MM-DD'.
• Consulta de un mes: citas where fecha_mes == 'AAAA-MM'.
• En el eje del cronograma las horas se pasan a minutos desde las 5 a. m.: minOp = h >= 5 ? (h-5)*60 + m : (h+19)*60 + m (las 2 a. m. son 1260).
• inicio_gmt6 es un Timestamp UTC real, a pesar del nombre.

Lecciones del código:

• Con el día calendario las citas de madrugada quedaban fuera de su ruta y las que cruzan medianoche nunca se comparaban para detectar choques.
• Revertir una hora desde el historial sin recalcular fecha_dia dejaba la cita archivada en el día equivocado.
• Hay un segundo concepto, el día contable de inventario (calendario de 00:00 a 23:59 en GMT-6), que no se debe confundir con el operacional.

1.2 Rutas y turnos

Colores: diez colores fijos para las rutas 1 a 10; las rutas 11 a 20 repiten los mismos colores en el mismo orden. "Sin asignar" es gris pizarra. Las citas ficticias se pintan rojo oscuro.

Normalización de ruta (usada en todas partes): "9", 9, "ruta 9" y "Ruta 9" se convierten en "Ruta 9" si el número está entre 1 y 20; cualquier otra cosa vacía es "Sin asignar". Sin normalizar, la misma ruta se partía en dos claves y una de ellas quedaba sin ruteador.

1.3 Nadie borra citas

• Las reglas de Firestore tienen allow delete: if false sobre citas, también para gerencia.
• "Cancelar" es mover a Ruta 20 con motivo y justificación.
• El importador CSV, desde sep-2026, cancela en vez de borrar.
• Además existe (fuera de este capítulo) una foto diaria de ventas a las 11:45 p. m. que avisa si una cita prestada se canceló, se puso en cero o desapareció, más respaldos y recuperación a un punto en el tiempo.

1.4 Escritura por campo, nunca el mapa entero

Regla de oro de todo el sistema de campo: cada pantalla escribe con rutas de punto ('metadata.hora_ingreso', 'metadata.imagenes') y relee la cita fresca del servidor justo antes de escribir. Reemplazar metadata completo desde la copia en memoria borró varias veces lo que otro módulo había escrito después (ingreso y GPS del técnico, fotos del reporte, encuestas, cancelaciones). Excepciones conocidas y mitigadas con relectura: la edición del reporte desde oficina.

Corolarios:

• Las listas se modifican con arrayUnion / arrayRemove con el valor exacto, nunca con una ruta de índice (lista.45.campo): Firestore convierte el arreglo en mapa.
• serverTimestamp() no se puede meter dentro de un arreglo; el historial usa Timestamp.now() o texto.

1.5 Fuente de identidad del cliente

• El cliente se identifica por teléfono. clientes/{telefono} guarda nombre, telefonoFormateado, sucursales[] (índices), totalCitas, fechaCreacion, fechaUltimaActualizacion.
• Sucursales: sucursales/{telefono}_{indice con 3 dígitos} con indice y datos de la sede.
• La cita guarda metadata.cliente_nombre como copia para pintar rápido; el nombre oficial vive en clientes.
• Teléfono nacional: 8 dígitos, se guarda como 506 + 8. Extranjero: empieza con +, de 9 a 15 dígitos, y la agenda pide una verificación humana (una suma) más una confirmación.

2. Ciclo de vida de una cita

El ciclo de vida no es una máquina de estados. metadata.estado vale agendada en casi todas las citas (agenda, clonar, recurrentes, ficticias, bot); los procesos tratan como cancelada cualquier estado que contenga "cancel" para tolerar datos viejos. Cada etapa se define por la presencia de ciertos campos.

                    +-------------------------------------------+
                    |  CREADA                                    |
                    |  doc citas/{id} existe                     |
                    |  metadata.estado='agendada'                |
                    |  confirmada24_48={confirmada:false}         |
                    |  monto, vendedores, canal, creado_por,      |
                    |  fecha_creacion, fecha_dia, fecha_mes       |
                    |  historial: entrada metadata.monto          |
                    |  (origen 'creacion_cita')                   |
                    +---------------------+-----------------------+
                                          |
          a los 3 min: envío automático   |   triggers: citaOverlapCheck,
          al grupo Ventas (si califica)   |   stampClienteOnCita, metaCapi (Lead),
                                          |   recuperador de cartera, garantías
                                          v
                    +-------------------------------------------+
                    |  CONFIRMADA                                |
                    |  confirmada24_48={confirmada:true, ts ISO} |
                    |  + imagen_confirmacion (rutas 11 a 17)     |
                    |  ventana: 3 días operacionales antes       |
                    |  plazo: 3:30 p. m. del día anterior         |
                    +---------------------+-----------------------+
                                          |
            si a las 3:30 p. m. no está   |  (metaCapi: Schedule)
            confirmada: venta_no_calidad  |
            = true, confirmacion_vencida  |
                                          v
                    +-------------------------------------------+
                    |  EN RUTA                                   |
                    |  metadata.ruta = Ruta 1..19                |
                    |  ruteador/{fecha}_{Ruta-N}.tecnicos[]      |
                    |  horaConvocatoria, vehiculos[]             |
                    |  despacho marcado en el ruteador            |
                    +---------------------+-----------------------+
                                          |
                                          v
                    +-------------------------------------------+
                    |  EJECUTADA                                 |
                    |  metadata.hora_ingreso (texto) + gps_ingreso|
                    |  metadata.hora_salida  (texto) + gps_salida |
                    |  gps_dudoso / alerta_lejos / culpa_tecnico |
                    +---------------------+-----------------------+
                                          |  (la salida exige reporte completo
                                          |   y método de pago con respaldo)
                                          v
                    +-------------------------------------------+
                    |  REPORTADA                                 |
                    |  metadata.reporte.condicion verde|amarillo|rojo|
                    |  reporte.grupos, plagas[], secciones.*.fotos|
                    |  reportado_por, reportado_en               |
                    +---------------------+-----------------------+
                                          |  rojo cerrado: ticket al vendedor
                                          |  + reportes_publicos/{token} + revisión IA
                                          |  portal: portalPushAlCerrarReporte
                                          v
                    +-------------------------------------------+
                    |  COBRADA                                   |
                    |  metadata.pagos[] {metodo, monto, linea?}   |
                    |  metadata.metodoPago (el de la parte mayor) |
                    |  metadata.precio_final_rutero (total)      |
                    |  voucherPago / reciboEfectivo              |
                    +---------------------+-----------------------+
                                          |  (metaCapi: Purchase cuando monto > 0)
                                          v
                    +-------------------------------------------+
                    |  POST SERVICIO                             |
                    |  encuestas_citas/{citaId} pendiente→respondida|
                    |  certificados_emitidos/{serial}            |
                    |  satisfaccion_citas/{citaId} (madrugada)   |
                    |  garantias/{token} si el cliente reclama   |
                    +-------------------------------------------+

    Desde cualquier etapa:
                    +-------------------------------------------+
                    |  CANCELADA                                 |
                    |  metadata.ruta = 'Ruta 20'                 |
                    |  motivo_cancelacion (lista cerrada)        |
                    |  justificacion_cancelacion (>= 50 chars)   |
                    |  fecha_cancelacion (solo por arrastre)      |
                    |  luego revision_cancelacion (gerencia)     |
                    |  salir de Ruta 20 borra los 4 campos        |
                    +-------------------------------------------+

2.1 Tabla de etapas

guardarCita conserva el estado guardado (estado: base.estado || 'agendada') para que editar no vuelva a "agendada" lo que otro proceso hubiera marcado.

2.2 Estado visible en el cronograma

estadoDisplayCita: Ruta 20 se muestra "Cancelada"; rutas 1 a 19 se muestran "Realizada" si la hora de inicio ya pasó, si no "Agendada". Es un cálculo de pantalla, no un campo.

Semáforo de cada cita en la vista del técnico:

arqueado = ficticia || monto <= 0 || pagos tiene algún método || metodoPago
hechos   = contar(true en [ingreso, salida, arqueado])   // la ficticia cuenta ingreso y salida como hechos
3 → verde ; 0 → rojo ; 1 o 2 → amarillo ("Falta ingreso, salida, arqueo de pago")

3. Modelo de datos de la cita

3.1 Campos de primer nivel

3.2 Campos de metadata

3.3 Subcolecciones y colecciones relacionadas

4. Agenda (agenda.html): carga, cronograma y formulario de cita

4.1 Propósito y usuarios

agenda.html es la pantalla central del sistema. La usan ventas (crear y editar citas), coordinación y gerencia (mover citas, asignar técnicos y vehículos, revisar cancelaciones) y bodega (ver qué lleva cada ruta). Permiso de página: calendario.

Es un solo HTML grande (decenas de miles de líneas) con un <script type="module"> dividido por secciones (// SECCIÓN: ...) y módulos auxiliares en js/agenda-*.js. Para reconstruirlo no hace falta replicar esa forma: conviene separar en módulos de carga, cronograma, formulario, guardado, historial, ruteador y vehículos.

4.2 Carga de datos

No hay listeners en tiempo real para las citas: todo se lee con getDocs puntual (el único onSnapshot de la página es el de garantías; los avisos de confirmación y la burbuja roja usan sus propios listeners).

Orden de carga en cargarDatos (con candado para no correr dos veces):

1. En paralelo: catálogos (solo si están vacíos) y las citas del día.
2. Se dibuja el cronograma.
3. Cuando el navegador queda libre (doble requestAnimationFrame, luego requestIdleCallback con tope de 1 s y piso de 1,5 s): encuestas y después el mes entero.
4. Se procesan los parámetros de URL: editarCita, rutero, desdeCotizacion, clonar+hora+ruta, nuevaCita=1 (con hora, ruta, duracion, modalidad, origen, lat, lng), agendarGarantia.

Poda del caché mensual: se quitan historial, reporte, detalle_cotizacion e historial_ediciones, porque el mes completo pesaba unas 860 citas y 3,4 MB y el calendario solo mira monto, ruta, equipo y fechas.

Lecciones:

• Cargar encuestas y el mes antes del cronograma hacía que la primera cita tardara 11 s en verse.
• En una pestaña en segundo plano el navegador no dispara requestAnimationFrame: esperar el pintado ahí significaba no cargar nunca.
• Encadenar catálogos y citas costaba unos 3 s antes de que arrancara la consulta de citas.

4.3 Cronograma

• Escala: 48 px por hora; el día operacional completo mide 24 horas (de 5 a. m. a 5 a. m.).
• Dos secciones: rutas diurnas (1 a 10) y nocturnas o especiales (11 a 20). Las rutas 9, 10, 16 y 17 se ocultan si están vacías (botón "+ Rutas"). Las 11 a 19 llevan fondo rayado; la 20 un ícono de prohibido.
• Vista combinada opcional (preferencia local): junta todas las rutas con citas en una sola sección.
• Recorte de la sección diurna: se corta a las 17:00 salvo que alguna cita diurna termine después.

Bloque de cita:

min5   = minutos desde las 5 a. m.
top    = min5 / 60 * PX_H
height = max(duracion / 60 * PX_H, 20)
si es cita de apoyo (copiada de otra ruta): se recorta a la franja de apoyo, z-index menor, no arrastrable

• No hay algoritmo de carriles en el cronograma de la agenda: dos citas que chocan se dibujan una encima de otra. El choque se impide al guardar o al soltar.
• Contenido: cinta de provincia, cantón y distrito (o "Dirección pendiente"), tres puntos de estado (confirmada, encuesta, pago), insignia del primer vendedor, hora, precio (o "Precio 0" en rojo), nombre con distintivo de cliente de cartera, check si tiene ingreso y salida, alerta si no tiene GPS, indicador de técnicos en sitio (última cita con ingreso sin salida) o "en tránsito", borde de comisión en riesgo (falta confirmación, encuesta, pago o GPS).
• Columna: capa gris del tiempo transcurrido, línea de hora de convocatoria (gris punteada a las 5:30 si no hay hora), franjas bloqueadas del ruteador.
• Cabecera de cada ruta: monto en miles con ícono verde si supera ₡200.000, alerta entre ₡100.000 y ₡200.000, cruz roja por debajo.
• Al hacer clic en una cita se abre la Vista Ventas (detalle de solo lectura con acciones); la edición completa es otro modal.

4.4 Arrastrar y soltar citas

Mover una cita existente (aplicarDropCitaEnTimeline):

y     = posición del puntero - tope del timeline - offset con que se agarró
min5  = clamp(0..1439, y / PX_H * 60) redondeado a 15
si min5 < 1140: hora = min5 + 300 (mismo día) ; si no: hora = min5 - 1140 (día siguiente)
duracion = max(15, redondeada a 15)
validaciones en orden:
  1. bloqueo por antigüedad (más de 7 días) o día pasado sin ser gerencia
  2. franjas bloqueadas del ruteador (contadas en día operacional)
  3. si destino es Ruta 20: buscar hueco libre del día; si no, chequear solape en la ruta destino
  4. solo gerencia puede dejarla antes del inicio del día operacional actual
  5. aviso de productos especiales ya alistados (ver 5.11)
  6. Ruta 20 pide justificación
  7. aviso si la cita es de otro vendedor (movimientos ajenos)
relee la cita del servidor; writeBatch con solo inicio_gmt6, duracion_minutos, metadata.ruta,
fecha_dia, fecha_mes y el historial; al salir de Ruta 20 borra los campos de cancelación
muestra vista previa "CITA MOVIDA" y, al confirmar, la manda al grupo Ventas (sección 11.3)

Crear arrastrando en zona vacía: desde el 29-oct-2026 no agenda, lleva a Compás (sección 12.1) con la duración y el turno. Excepción temporal hasta el 30-nov-2026: se puede agendar ahí mismo como excepcion_ruta_hora escribiendo un motivo de al menos 20 caracteres, que queda en metadata.justificacion_sin_optimus. En táctil exige mantener presionado 220 ms y se cancela si el dedo se mueve más de 12 px.

Lecciones:

• Escribir la metadata completa al mover borraba hora de ingreso, GPS, reporte y fotos del técnico.
• Con una búsqueda activa las citas ocultas no se comparaban y se agendaban dos en la misma franja: el solape se valida contra todas las citas en memoria, no contra las filtradas.
• Con draggable=false en citas protegidas, quien no es gerencia arrastraba y no pasaba nada; ahora se deja agarrar y al soltar se explica el motivo.

4.5 Formulario de cita: campos y reglas

Al abrir una cita para editar:

• Cita protegida: si no es gerencia, no es Ruta 20 y la cita tiene más de 7 días, se oculta Guardar y aparece "Las citas con más de 7 días no se pueden modificar".
• Banderas reiniciadas: serviciosProductosModificadosPorUsuario.edit = false y editandoMontoVentaManual.edit = false, para no recalcular el monto de citas viejas o importadas mientras el usuario no toque servicios.
• Si metadata.servicios está vacío, se reconstruye desde detalle_cotizacion.servicios emparejando por nombre.
• Comparación real contra lo previsto: desviaciones de ingreso o salida desde 2 minutos; duración real en rojo si queda 10 minutos o más por debajo o un 30 % menos, en ámbar si se pasa más de 15 minutos o 40 %; distancia del GPS del técnico al punto de la cita: verde hasta 100 m, ámbar hasta 300 m, rojo más.

4.6 Precio y monto

calcularMontoVenta(prefijo):
  si el usuario fijó el monto a mano (Enter en el campo): no tocar
  si es edición y no se tocaron servicios ni productos: no tocar      // protege citas viejas o importadas
  totalServicios = suma(cantidad * precio) de los servicios
  si no hay ítems y el monto actual > 0: no pisar
  monto = totalServicios                                                // los productos NO suman

• Los productos se registran con su costo de inventario, información interna que no se cobra. Antes se sumaban y registrar químicos inflaba la cuenta del cliente.
• Resumen financiero en pantalla: margen = precioCliente - costoProductos (rojo si es negativo). Se guarda costo_servicio: 0.
• detalle_cotizacion: servicios[{id, nombre, cantidad, precio_unitario, subtotal}], productos[{id, nombre, cantidad, costo_unitario, subtotal}], todo redondeado a colones enteros.
• Lectura de montos escritos (extraerValorNumerico): el separador decimal es el último . o , seguido de 1 o 2 dígitos al final; todo lo demás son miles; se redondea a entero. Lección del 27-ago-2026: un total con céntimos formateado como "554 047,08" se leyó como 55.404.708.
• formatearMontoVenta(0) devuelve vacío a propósito (no mostrar ₡0).
• Proforma: imagen PNG (no PDF) de 560 px generada con html2canvas a escala 3; se copia al portapapeles y se descarga. descuento = totalServicios > monto ? totalServicios - monto : 0. Los productos se listan sin precio.

4.7 Atribución de la venta a vendedores

atribucion(cita):
  vs = metadata.vendedores
  si excepcion_pesos_vendedores tiene el mismo largo que vs y suma exactamente 100:
      cada vendedor recibe monto * peso / 100
  si no: cada vendedor recibe monto / len(vs)
  sin vendedor: "Sin vendedor"
  se excluye Ruta 20

La tira "Ventas hoy" usa las citas creadas hoy con monto mayor a 0, sin Ruta 20, con esta misma atribución; el primero lleva corona. Las metas mensuales y las barras por día se movieron a otra página (táctico); en la agenda quedó la grilla del mes.

4.8 Herramientas de alisto con saldo

herramientas_alisto {nombre, saldoTotal}: cantidad fija de cada herramienta en toda la empresa (por ejemplo, termonebulizadoras). En la cita se guardan por nombre en metadata.equipo[].

grupo(ruta) = 1..10 → 'diurna' ; 11..20 → 'nocturna' ; otro → sin validación
enUso(nombre, grupo) = cantidad de citas cargadas del grupo (salvo la que se edita)
                       cuyo metadata.equipo contiene ese nombre (sin mayúsculas ni espacios)
disponible = max(0, saldoTotal - enUso - vecesYaPuestaEnEsteFormulario)
disponible <= 0 → opción "agotada", no seleccionable

• Solo se valida en el buscador, no al guardar. Una herramienta escrita a mano (fuera del catálogo) se marca en naranja "Escrita a mano".
• metadata.excluidos.herramientas y .productos registran lo que el servicio trae pero esta cita no lleva; se respeta en despacho, alisto y ruta. Hay dos copias de trabajo separadas (editar y nueva) porque con una sola lo quitado al agendar se pegaba a la cita abierta.
• Panel "lo que la cita incluye": certificados, especiales (productos del servicio con cantidad = servicio.cantidad * pa.cantidadPorUnidad más los sueltos) y herramientas (de la cita más las del servicio, sin repetir).

Huecos conocidos: el conteo puede abarcar el mes si la vista es mensual, las citas de Ruta 20 cuentan en el grupo nocturno y no suma las herramientas asociadas a servicios.

4.9 Clientes, sucursales y adjuntos

• buscarCliente(tel) → clientes/{tel}. Si no existe se crea al guardar; si existe se actualiza el nombre.
• Sucursales: cliente.sucursales[] guarda índices; cada sede es sucursales/{tel}_{nnn}. Las coordenadas de la sucursal son la fuente de verdad del punto cuando la cita tiene sucursal.
• Adjuntos (agenda-images.js): imágenes comprimidas a 1280 px de lado mayor, JPEG calidad 0,72, bajando de a 0,08 hasta 350 KB o calidad 0,4; tope de 40 MB por archivo; HEIC se sube sin comprimir. Storage citas/{citaId}/imagenes/{ts}_{nombre}.{ext}. Se escribe solo metadata.imagenes por ruta de campo. En cita nueva quedan en cola hasta tener id.

4.10 Buscador de citas

• Texto libre: citas where inicio_gmt6 >= desde orderBy inicio_gmt6 desc limit tope. Por defecto 90 días hacia atrás; opciones de 1 año, 3 años o todo. Topes: 3.000 documentos hasta 1 año, 6.000 más de un año, 10.000 sin límite. Todas las palabras (sin tildes) deben coincidir en teléfono, nombre, dirección, descripción, observaciones, ruta, vendedores o fecha. Máximo 20 resultados.
• Si el texto es un teléfono, se desvía a búsqueda por teléfono: variantes d, +d, 8 dígitos, 506+8 y +506+8 en telefono_normalizado y telefono, hasta 300 por consulta, máximo 100 resultados.
• Acciones rápidas desde la tarjeta: marcar CNF, subir pantallazo de confirmación (1600 px, calidad 0,72), corregir GPS.
• Resumen con IA de comentarios largos (más de 130 caracteres), 25 por llamada; si la función falla se apaga por la sesión.

4.11 Tabla de citas (solo lectura)

agenda-tabla-citas.js: rango libre (aviso si pasa de 62 días), unas 45 columnas agrupadas (cita, ejecución, reporte, encuesta, venta, servicio, cliente, gestión), puntualidad en rojo si el atraso pasa de 15 minutos, "Precio final (ruta)" resaltado si difiere del monto, exportación TSV o CSV. Las ficticias suman monto pero no cuentan como visita. Lección: las horas del técnico en texto "5/9/2026, 10:23" se leían como 9 de mayo; solo se parsea directo el ISO.

4.12 Cotizaciones

• agenda.html?desdeCotizacion=ID abre una cita nueva prellenada desde cotizaciones/{id}: teléfono, nombre, señas, coordenadas, duración (días × 480 min, horas × 60, tope 720), servicios, precio aprobado (si difiere de la suma, queda como monto manual), vendedor y canal de la cita de visita.
• Al guardar, la cotización pasa a ganada con citaTrabajoId y una entrada en su bitácora.
• Estos campos no se copian al clonar.

5. Guardado y control de la cita

5.1 Guardar una cita existente (guardarCita)

Barreras en orden exacto:

1. Cliente bloqueado (clientes_bloqueo): no se guarda.
2. Cita protegida (más de 7 días, salvo gerencia o Ruta 20).
3. Candado contra doble clic (_guardandoCita, se libera en finally). Un segundo Guardar duplicaba el historial.
4. Obligatorios: teléfono, inicio, duración, ruta, observaciones, canal, al menos un vendedor.
5. Venta no comisionable marcada: justificación y al menos un pantallazo.
6. Fecha anterior al inicio del día operacional actual: solo gerencia, salvo que la fecha no haya cambiado (tolerancia 60 s).
7. Pesos de vendedores: solo gerencia, enteros de 0 a 100 que suman 100.
8. "Solo esta hora" en rutas 1 a 10: foto obligatoria (Storage solo_esta_hora/{citaId}_{ts}).
9. Ruta 20: motivo de la lista y justificación de 50 a 2.000 caracteres (se reusan si ya existían).
10. Monto negativo: rechazo.
11. Ruta 20: buscarEspacioDisponibleRutaOperacional reubica la hora en un hueco libre del día respetando bloqueos; si no hay, no se guarda.
12. Otras rutas: validarSolapamientoCitaRemoto(inicio, duración, ruta, idPropio), que lee el día del servidor (getDocsFromServer), nunca de la caché ("una foto vieja aprueba una doble reserva").
13. Teléfono nacional o extranjero válido.
14. Cliente: crear o actualizar nombre.
15. Coordenadas dentro de Costa Rica. No se puede guardar confirmada sin GPS. Provincia, cantón y distrito se recalculan del punto.
16. Avisos humanos antes de leer la cita fresca: movimientos ajenos y especiales alistados. Mientras alguien lee un modal el técnico puede marcar ingreso; si la base ya se había leído, eso se pisaba.
17. leerCitaFresca(id). Desde aquí no hay más esperas humanas hasta el commit.

Regla de solape (idéntica en cliente, servidor y Optimus):

choca(a, b) = a.inicio < b.fin && a.fin > b.inicio
   en el mismo día operacional, la misma ruta normalizada,
   ignorando canceladas y Ruta 20; duración por defecto 60

Lógica del monto al guardar (lo menos obvio):

montoGuardado = base.metadata.monto          // valor y tipo crudos
intacto = !tocoMonto && !tocoServicios && montoGuardado !== undefined
nuevo   = entero(campo) o 0
cambia  = !intacto && Number(montoGuardado || 0) !== nuevo
metadata.monto = montoGuardado               // el batch NUNCA lleva el monto nuevo
commit
si cambia: aplicarCambioMontoCita(id, montoGuardado, nuevo)   // va por la función del servidor (5.4)

Lección: el monto se formateaba al cargar y se releía al guardar; en citas viejas con texto o decimales eso cambiaba el tipo y la regla lo tomaba como cambio de plata, rebotando con "permisos insuficientes" aunque solo se hubiera corregido un comentario.

Armado de metadata:

• Parte de la metadata fresca del servidor y le aplica los cambios del formulario.
• Si la ruta deja de ser 20, borra los cuatro campos de cancelación (si no, una segunda cancelación reusaba el motivo viejo y el panel la contaba como revisada).
• confirmada24_48: si el check no cambió se conserva el objeto con su fecha (evita historial espurio).
• Calidad de venta: quien no tiene permiso guarda los valores frescos. Bug que lo motivó: un modal abierto antes de la marca de las 3:30 p. m. traía la venta limpia y al guardar borraba la marca.
• metodoPago: si venció el plazo de arqueo, se conserva el guardado.
• Se preservan si existen: reporte, coordenadas_corregidas, horas y GPS del técnico, precio_final_rutero, imagenes, modalidad_cita_creada, confirmacion_vencida, excluidos.

Escritura: buildHistorialEdicion(base, datos) → limpiar indefinidos → índices → un writeBatch con update(citas/id) y set(extras/historial, {historial: arrayUnion(...)}, merge). Después: monto por la función, registro de movimiento ajeno, nota de especiales, cerrar modal, recargar y recalcular traslados de la ruta vieja y la nueva.

5.2 Crear una cita (guardarNuevaCita)

• Id reservado al abrir el formulario (doc(collection(db,'citas'))) y escritura con setDoc: una doble ejecución escribe el mismo documento.
• Mismas validaciones que editar, sin la regla de 7 días; la fecha pasada solo gerencia y sin tolerancia.
• modalidad_cita_creada del formulario: drag_and_drop por defecto, optimizador_algoritmo (Compás y Optimus), mapa_logistica, desde_cotizacion, excepcion_ruta_hora.
• Vista previa del pantallazo de Ventas antes de guardar (si la cita califica).
• Historial inicial del monto: entrada metadata.monto con valor anterior vacío y origen: 'creacion_cita' (el 88 % de las citas de un mes no tenía ninguna entrada sobre su monto). Si esa escritura falla no se aborta la creación.
• Se suben los adjuntos y el pantallazo de confirmación que esperaban el id.

Recurrencia:

• Mensual (n-ésimo día de la semana o día fijo): 11 copias. Bimensual: 5 copias. Manual: hasta 12 fechas.
• "N-ésimo día de la semana": si la quinta semana no existe, cae en la cuarta.
• Cada fecha valida solape; las que chocan se omiten.
• Escritura en lotes de 400 por writeBatch; antes iban una por una y un fallo a mitad dejaba la serie incompleta sin aviso. Al final se informa cuántas se crearon, omitieron y fallaron.

5.3 Clonar una cita

clonarCitaEn(cita, "AAAA-MM-DDTHH:MM", ruta, extra). Desde el 30-oct-2026 el botón Clonar lleva a Compás (compas.html?clonar=<id>) para elegir día, hora y ruta por cercanía, y vuelve a la agenda a crear la copia.

metadataParaCopiaCita(origen):
  base = {estado:'agendada', confirmada24_48:{false,null}, imagen_confirmacion:null, metodoPago:''}
  copiar todo metadata menos CAMPOS_NO_CLONABLES:
    confirmación, método de pago, factura, historial, ultima_edicion,
    encuesta y su justificación, ingreso/salida/GPS, reporte, coordenadas_corregidas,
    precio_final_rutero, imagenes, campos de cancelación, whatsapp_coordinacion,
    campos de cotización

• Teléfono extranjero se conserva; recortar a 8 dígitos inventaba un número nacional.
• Valida solape salvo en Ruta 20. Escribe creado_por y fecha_creacion, lo que habilita al creador a ajustar el monto durante 24 h.

5.4 Monto protegido

Desde el navegador, nadie que no sea gerencia cambia metadata.monto (regla de Firestore). Los demás pasan por la función HTTP cambiarMontoCita (POST, empleado autenticado), con body {citaId, monto, motivo}.

Reglas de entrada: citaId de 1 a 128 caracteres, monto entero mayor o igual a 0, motivo recortado a 300 caracteres. Si el monto ya es ese, 400.

evaluarPolitica(usuario, cita, nuevo):
  si gerencia                                     → permitido ("gerencia")
  si nuevo == 0 y tiene permiso anular_monto_cita:
      si inicio de la cita > ahora                → permitido ("anular_monto_cita")
      si no                                       → 403 "anular después de la hora es de gerencia"
  si es su venta (creado_por == yo o yo ∈ vendedores):
      si inicio + 18 h > ahora o fecha_creacion + 24 h > ahora → permitido ("ajuste_mi_venta")
      si no                                       → 403 "la venta ya cerró"
  si no                                           → 403
transacción:
  metadata.monto = nuevo (y monto en la raíz si existía el espejo)
  metadata.historial arrayUnion(extracto), metadata.ultima_edicion
  extras/historial arrayUnion(entrada completa con motivo, origen 'cambiarMontoCita', regla)
  citas_monto_log/{auto} = {citaId, antes, despues, usuario, uid, motivo, regla, fecha_dia, creado}

• anular_monto_cita es un permiso propio que no se hereda. Motivo: en un mes hubo anulaciones entre 21 y 28 días después de la cita, patrón de cobrar en efectivo y borrar la venta.
• citas_monto_log se lee con reportes_gerenciales o gerencia; escritura solo servidor.
• El cliente tiene un respaldo que escribe directo si la función no responde, marcado para retirar; con la regla actual solo funciona para gerencia.

Reglas de actualización de citas (resumen):

allow update: empleado
  && (no toca metadata.monto || gerencia)
  && (no toca precio_final_rutero || cobrandoElMismoDia || gerencia)   // inicio + 18 h > ahora
  && (no toca creado_por ni fecha_creacion || gerencia)
  && (no toca calidad de venta || gerencia o usuaria autorizada)
allow create: empleado && (creado_por es quien escribe y fecha_creacion == request.time || gerencia)
allow delete: false

• cobrandoElMismoDia existe porque el técnico cobra en casa del cliente después del servicio; cerrar ese campo rompía la operación y lo detectó el emulador de reglas.
• Discrepancia conocida: la pantalla considera gerencia solo departamento === 'gerencia'; las reglas también aceptan cargos que contengan "gerenc/gerent".
• Advertencia: no usar match /{sub=**} dentro de citas; ese comodín también calza el documento de la cita y su write anulaba las restricciones del monto.

5.5 Historial y auditoría

buildHistorialEdicion(anterior, nuevos):
  comparar raíz (telefono, inicio_gmt6 por milisegundos, duracion_minutos)
  y cada clave de metadata salvo historial y ultima_edicion
  igualdad por JSON con claves ordenadas
  entrada = {usuario, timestamp (texto es-CR), campo, valorAnterior, valorNuevo (cortados a 80),
             valorAnteriorRaw, valorNuevoRaw}         // Timestamp como {__ts: ms}

• cita-historial.js: desde sep-2026 el historial completo vive en citas/{id}/extras/historial porque era la mitad del peso de cada cita y el costo de Firestore se cobra por transferencia. En la cita queda un extracto: inicio_gmt6, duracion_minutos, metadata.ruta, metadata.servicios, metadata.productos y todo campo con "monto" o "precio_final" (sin los "manual" ni "pesos").
• cargarHistorial: une extras con el extracto y deduplica por campo|usuario|timestamp|valorNuevo. Si la lectura falla lanza error: antes devolvía vacío y revertir guardaba una lista vacía encima del historial real.
• Regla de extras/historial: crear para empleados; actualizar solo si la lista nueva contiene toda la vieja (hasAll); borrar nunca.
• Revertir: toma el valor crudo (se niega si el texto viene recortado con "…"), valida solape si es hora, duración o ruta, agrega una entrada revertido:true, escribe por ruta de campo, recalcula índices y, si el campo es el monto, pasa por cambiarMontoCita. Lección: revertir una hora escribía texto en inicio_gmt6 y la cita desaparecía del cronograma; por eso se guardan los valores crudos.
• Modal "Historial del día operacional": une cambios del ruteador con eventos de citas (creación, ruta, hora, duración) y marca con luna lo hecho entre 7 p. m. y 5 a. m.

5.6 Cancelar (mover a Ruta 20)

Caminos: modal de edición, cita nueva directa en Ruta 20, arrastre a la columna 20, migración en lote (una justificación para todas), importador CSV.

• Motivos (lista cerrada): "Cliente cancela", "Vendedor cancela", "Gerencia cancela" (varias variantes con nombre), "Pendiente de reagendar", "Cliente no aceptó su visita de garantía", "Cliente no contesta para su visita de garantía", "Otro - Especifique".
• Justificación de 50 a 2.000 caracteres.
• Ruta 20 no valida solapamiento: busca un hueco libre del día para no apilar.
• El arrastre escribe fecha_cancelacion: Timestamp.now(); el modal no (inconsistencia conocida).
• Revisión de cancelaciones (botón flotante, solo gerencia): lee el mes, separa pendientes de revisadas y exige un texto de 50 caracteres que se guarda en metadata.revision_cancelacion {texto, usuario, fecha}.
• Efectos de servidor: si el motivo es uno de los dos de garantía, se cierra la garantía vinculada (cliente_desiste o cliente_no_contesta). Los triggers de solape, cartera, garantías y llamada ignoran Ruta 20.

Botón flotante "Sin ruta": citas del mes con ruta vacía o "Sin asignar", con conteo propio y monto. reporte_sin_ruta.html (sección 12.6) permite anular su monto.

5.7 Citas ficticias (venta en ruta)

Es una venta que el técnico hace en campo (por ejemplo, el cliente pide un servicio extra), no una visita.

crearCitaFicticia(citaOrigen, descripcion, precio):
  candado contra doble toque          // cada duplicado infla ventas
  exigir descripción y precio > 0
  inicio = fin de la última cita de esa ruta ese día + 30 min (9:00 si la ruta no tiene citas)
  duracion_minutos = 30
  metadata = {estado:'agendada', confirmada24_48: copia de la cita origen, monto: precio,
              vendedores: técnicos del ruteador de esa ruta, servicios:[{id:'ficticio', nombre, cantidad:1, precio}],
              canal:'Ficticio', es_ficticio:true, cita_origen_id, dirección y coordenadas copiadas}
  sin ingreso, salida, GPS ni reporte; no escribe creado_por

Regla: la plata cuenta, la visita no. Suma en ventas y comisiones y dispara el evento de compra; queda fuera de encuestas, puntualidad, recordatorios de reporte, tickets en rojo, refuerzo de garantía, alisto y conteo de visitas. Antes copiaba el GPS de la cita origen y los reportes de cumplimiento la contaban como una visita más.

5.8 Confirmación y sus plazos

Fuente única en el navegador: js/confirmacion-plazos.js. El servidor replica la misma regla.

turno(inicio) = nocturna si hora >= 16 o hora < 5 ; diurna si no
limiteConfirmacion(inicio):
  dia = fecha de inicio
  si hora < 5: dia -= 1          // la madrugada es de la jornada anterior
  dia -= 1                       // vence el día antes de la jornada
  return dia a las 15:30
estaConfirmada(cita) = confirmada24_48.confirmada
   && (si ruta 11..17 y inicio >= 10-sep-2026: imagen_confirmacion presente)
evaluarCita → {estado: confirmada | a_tiempo | vencida, faltaFoto, exigeFoto, minutosAlLimite, limiteMs}

• Historia: hasta el 16-oct-2026 había dos plazos (12 MD diurnas, 4 p. m. nocturnas); desde el 17-oct-2026 uno solo a las 3:30 p. m. del día anterior.
• Ventana para marcar: se abre 3 días operacionales antes. El botón funciona como interruptor y solo se escribe al pulsar Guardar. Requiere GPS.
• Pantallazo de confirmación: una sola imagen, aparte de los adjuntos ("es un documento de control"), JPEG en citas/{id}/confirmacion/{ts}.jpg; se escribe solo metadata.imagen_confirmacion.
• Plantilla de confirmación por WhatsApp: dos tipos, casas (avisa de más o menos 15 min) y locales (hora exacta), con plantillas aprobadas por la plataforma de mensajería y respaldo si la plantilla falla. Guarda cnf_tipo y nombre_saludo. Enviar la plantilla no marca la cita como confirmada. Lección: se mandaban 8 dígitos y el servidor anteponía el código nacional, así que un cliente extranjero terminaba en el número de otra persona.

Servidor (functions/confirmacion-vencida.js), zona Costa Rica, 540 s, 512 MiB:

citasDelPlazo(hoy):
  citas con fecha_dia entre mañana y pasado mañana
  descartar: canceladas, Ruta 20, sin hora, cuyo límite no sea exactamente hoy 15:30,
             teléfonos en confirmacion_no_necesaria
  motivo: 'sin_check' o 'falta_foto'
aplicarPlazo():
  falta = limite - ahora
  si falta > 120 s: salir ("todavía no vence") ; si 0 <= falta: esperar falta + 1 s
  por cada cita no confirmada que no esté ya marcada hoy:
     subir constancia SVG a calidad_venta/confirmacion_vencida/{plazo}_{citaId}.svg
     batch: venta_no_calidad=true, justificación (concatenada si ya había una manual),
            evidencias += constancia, confirmacion_vencida={plazo, limiteMs, revisadoMs, motivo, avisada, constancia},
            ultima_edicion = "sistema (confirmación vencida)", historial
  alertas_confirmacion/{id}.aplicado = {at, totalCitas, marcadas[], errores[]}
  WhatsApp "aplicado" una vez (lista o "al día")

• En la agenda (agenda-aviso-confirmaciones.js): listener sobre alertas_confirmacion/{hoy}_1530; todos ven las pendientes de todos (decisión de "compañerismo"), las propias primero; cada 60 s se reevalúan y se quitan las ya confirmadas; después de las 3:30 muestra "quedaron sin comisión".
• El ruteo de quién responde por cada vendedor en el aviso está fijo en el código (por ejemplo, los vendedores de calle reportan a su encargada).
• Según la documentación del proyecto, a fines de octubre la regla marcó cerca del 6 % de las citas y se revirtió la comisión de las marcadas (confirmacion_vencida.revertida); el schedule sigue activo.

5.9 Plazos de arqueo y encuesta (días hábiles)

siguienteHabil(d): d + 1 mientras sea domingo o feriado (lista fija de feriados por año)
plazoArqueo(cita)   = siguienteHabil(dia de la cita) a las 10:00   // método de pago editable hasta aquí
plazoEncuesta(cita) = siguienteHabil(plazoArqueo) a las 10:00      // enlace de encuesta o justificación

El corte de arqueo es fijo porque contabilidad copia el TSV del día a las 10:00. Lección: citas de un viernes vencían un sábado feriado y se perdía la comisión sin forma de evitarlo.

5.10 Movimientos de citas ajenas

agenda-movimientos-ajenos.js se engancha antes y después de guardar o soltar.

No avisa si: es gerencia; la cita tiene reacomodo_libre; la cita no tiene vendedores o el usuario es uno de ellos; es la encargada de ventas de calle y todos los vendedores son técnicos; no cambió la hora (60 s o más) ni la ruta; ni el día de origen ni el de destino es hoy o mañana.

Si aplica: modal con motivo (autorizado_vendedor, cliente_pidio, gerencia_autorizo, otro), texto de al menos 15 caracteres y casilla de responsabilidad. Después del guardado (nunca revierte) escribe movimientos_ajenos/{auto} con dueño, quién movió, motivo, de{inicioMs, ruta, fechaDia}, a{...}, estado:'pendiente', una entrada de historial y una tarea en notas_mentales para cada vendedor. El vendedor marca autorizado o no_autorizado; gerencia revisado. La válvula "Libre/Protegida" la cambia solo el vendedor o gerencia. No lo disparan la migración en lote ni las cancelaciones.

Lecciones: el candado del aviso quedaba en verdadero y bloqueaba todo movimiento hasta recargar; el focus trap de Bootstrap robaba el foco del textarea.

5.11 Productos especiales ya alistados al mover

Caso real: bodega alistó producto para el técnico de una ruta y minutos después movieron la cita a otra ruta. Hay un portero (avisarEspecialesAlMoverCita) al inicio de cada camino que mueve citas:

puertas (de la más barata a la más cara):
  1. cambió la ruta y el origen no es "Sin asignar"
  2. la cita es de hoy o mañana
  3. la cita requiere productos (asociados al servicio + sueltos)
  4. hubo movimientos_inventario hacia las bodegas especiales de los técnicos de la ruta origen
     en el día operacional, con ítems de esta cita (sin anulados)
si pasa: avisa, copia un mensaje para bodega y, tras confirmar el guardado (válido 5 min),
  escribe ruteador/{fecha}_{Ruta-N}.notasBodega[citaId] = {cliente, hora, rutaOrigen, rutaDestino,
  bodegas y técnicos de origen y destino, items[{productoId, nombre, cantidad}], avisadoPor, en, resuelto:false}

No mueve inventario; despacho resuelve. El caso simétrico (cambian los técnicos de una ruta) lo maneja agenda-reasignar-especiales.js: "el inventario pertenece a la ruta, no al técnico". Para hoy mueve el saldo real; para otro día solo lo alistado para ese día (bug: editar una ruta futura vació la bodega del día en curso). Usa una bodega transitoria mientras la ruta no tiene técnico.

5.12 Migración de rutas

Mueve todas las citas de una ruta origen a una destino dentro del día operacional. Destino Ruta 20 pide una justificación única. Aviso de especiales en bloque (si se cancela uno, no se migra ninguna). Cada cita: lectura fresca, escritura por rutas de campo (metadata.ruta y cancelación, con deleteField si sale de la 20) y historial. No valida solapamiento en el destino ni dispara movimientos ajenos. Lección: reemplazar el mapa borró ingreso, GPS, reporte y fotos de todas las citas migradas.

5.13 Triggers de servidor sobre citas

6. Ruteador: técnicos, vehículos y convocatoria

6.1 Propósito y pantallas

Cada ruta de cada día necesita técnicos, un vehículo y una hora de convocatoria (hora a la que los técnicos se presentan en la central). La asignación se hace en el cronograma de la agenda (modal "Asignar técnicos y vehículos" y arrastre de recursos sobre la cabecera de cada ruta). La página ruteador.html no asigna: es un reporte de eficiencia por ruta (permiso ruteador).

Lo usan coordinación de operaciones y gerencia; los técnicos solo lo leen (ruta.html decide "cuál es mi ruta" con este documento).

6.2 Colección ruteador

Un documento por ruta y día con id determinista {fecha}_{Ruta-N} (por ejemplo 2026-10-31_Ruta-7); la ruta se recupera del id si falta el campo. Todas las escrituras son setDoc(..., {merge: true}).

Colecciones hermanas:

• ruteador_dias/{fecha}: caché del reporte de eficiencia y candado de convocatoria (convocatoriaBloqueada, candadoPor, candadoEn).
• ruteador_historial: un documento por guardado que cambió algo.
• atlas_zonas: {nombre, color, poligono[]}.
• configuracion/rutas: turnos{ruta: diurna | nocturna | rural}, turno fijo de cada ruta.

6.3 Guardado con historial

Todos los caminos de escritura pasan por un único helper:

guardarRuteadorConHistorial(id, payload, origen):
  antes = leer ruteador/id (si falla, sigue)
  setDoc(ruteador/id, payload, merge)          // el guardado nunca depende del historial
  try:
    cambios = para campo en [tecnicos, vehiculos, horaConvocatoria, bloqueoHorario, zona, turno]:
                si payload[campo] definido y norm(antes) != norm(payload): {campo, antes, despues}
    si cambios: addDoc(ruteador_historial, {fecha, ruta, usuario, usuario_nombre, origen,
                 esNuevo, cambios, tieneVehiculos, fechaISO})
  catch: solo registrar en consola

• Orígenes: modal, arrastre, arrastre-hora, apv (asignación automática), masivo, zona, tecnico-fijo, despacho.
• Bandera tieneVehiculos (desde 10-sep-2026): Firestore no filtra por el contenido de un arreglo de objetos y un día activo tenía unos 5.000 documentos de historial (cerca de 6 MB), de los cuales solo unos 30 tocaban vehículos.
• Lección: escribir la zona en cada repintado generaba miles de documentos de historial al día en pares simétricos (zona → null → zona); se dejó de escribir si no cambió.

6.4 Reglas de técnicos y vehículos

• Nadie en dos rutas el mismo día. validarDuplicadosRuteador lee el día completo y devuelve conflictos. El aviso resuelve: "Quitar de Ruta X y guardar acá" ejecuta quitarRecursoDeRutas y vuelve a guardar (pedir "quitalo primero de la otra ruta" dejaba a la persona rebotando entre modales).
• quitarRecursoDeRutas(fecha, {tipo, valor}, {rutas?, excepto?}) busca contra el servidor en todas las rutas del día. Con caché el arrastre no veía la segunda ruta y el recurso quedaba duplicado.
• Cola global de arrastres: una promesa encadenada procesa un arrastre a la vez. Bug del 22-oct-2026: dos arrastres seguidos corrían en paralelo y un vehículo quedó en dos rutas.
• Técnicos disponibles: departamento de fumigación con visibleEnRutas != false; los que están de vacaciones salen en rojo con etiqueta VAC.
• Técnicos fijos de las rutas 11 a 15: cada ruta se asocia a un técnico por la etiqueta de su gafete y se aplica solo de hoy en adelante, de lunes a viernes, si la ruta está vacía y sin tecnicosAuto, y nunca a quien ya esté en otra ruta. Si la etiqueta coincide con dos empleados no se asigna ("adivinar es peor que no ponerlo").
• Botones masivos: mover todos los técnicos (o vehículos) a sin asignar.
• Bloqueos de horario: máximo 2 por ruta. Con ayudaRuta, las citas de la ruta ayudada que se solapan con la franja se copian como "Apoyo" en la columna de quien ayuda (dibujadas solo dentro de la franja, debajo de las propias). Solo personal autorizado (permisos.habilitado o gerencia) borra una franja; si otro la vacía, se restaura en silencio.
• Drag and drop de recursos: dataTransfer, con respaldo en variables globales que se limpian a los 500 ms. Soltar sobre una fila: turno de cola → candado → confirmación de día pasado → quitar el recurso de todas las rutas → escribir destino → barrido final excepto el destino. Soltar en "Sin asignar" lo desasigna; doble clic sobre la insignia lo quita. Soltar sobre una cita asigna a la ruta de esa cita (antes no lo sacaba de su ruta anterior). El candado del drop se libera siempre (salidas tempranas lo dejaban puesto y esa zona quedaba muda hasta recargar).

6.5 Hora de convocatoria y candado

• Línea horizontal en la columna. Sin hora: gris punteada a las 5:30. Con hora: en el color de la ruta, con "Xh Ymin hasta la 1.ª cita".
• Arrastre de la línea redondeado a 15 min; bloqueado si el día ya pasó, si la hora ya pasó hoy o si el día tiene candado.
• Candado del día (ruteador_dias.convocatoriaBloqueada): con él no se arrastran línea, técnicos ni vehículos; todo se cambia desde el modal. Motivo: "la línea se movía sin querer con un clic". Al quitarlo se advierte que los cambios se avisan a gerencia, que avisa a los técnicos.
• Apertura de bodega: para cada técnico su convocatoria más temprana; la bodega abre a la menor. Se copia como texto para WhatsApp.
• La hora de convocatoria alimenta la alerta de llegada tardía (11.5) y el reporte de puntualidad (12.5).

6.6 Guard de días pasados

_confirmarModRuteadorPasado(fecha): hoy nunca se frena (mover gente el mismo día es normal). Para días anteriores se pide resolver una suma a + b con números de 2 a 9, porque cambiar una ruta pasada reescribe la asistencia. Un movimiento entre dos rutas pregunta una sola vez. El permiso vale para un guardado. Lecciones: Bootstrap robaba el foco al campo de respuesta; un clic afuera cancelaba en silencio; cancelar ahora se informa.

6.7 Traslados entre citas (tiempos de manejo)

En el cronograma, por ruta se arman los tramos: salida (central → primera cita con GPS), entre citas consecutivas y regreso (última → central), incluyendo las de apoyo.

• Se consultan a un servicio de direcciones de mapas agrupando tramos contiguos en cadenas de hasta 11 puntos (origen, 9 intermedios, destino) sin optimizar el orden: pasar de 10 intermedios u optimizar cambia a una tarifa más cara.
• Días pasados no se recalculan.
• Se guarda en ruteador.traslados = {citasHash, salidaCentral, entreCitas[], regresoCentral, horaFinEstimadaMinutos}; citasHash (id, lat, lng, inicio, duración) marca si quedó desactualizado; hay recálculo incremental por segmentos.
• Se dibuja: salida máxima de la central (inicio de la primera cita menos traslado), saldo entre citas (tiempo libre menos manejo, verde o rojo), llegada estimada (fin de la última + regreso + 15 min de descarga + 10 min de imprevisto) y jornada (llegada menos convocatoria).
• Estos tramos medidos calibraron el modelo de manejo de Compás (12.1).

6.8 Asignación automática de vehículos

POOL = [vehículo 01 .. vehículo 08]           // flota de la empresa
para bloque en [rutas diurnas, rutas nocturnas]:     // un vehículo puede repetirse entre bloques
  rutas = bloque sin "Sin asignar", en orden numérico
  libres = POOL - vehículos ya usados por alguna ruta del bloque
  i = 0
  para ruta en rutas:
    si i >= len(libres): parar
    si la ruta no tiene citas o ya tiene vehículo: seguir
    asignar libres[i++]  (guardar con origen 'apv')

Es un reparto glotón por número de ruta, sin mirar zona ni kilometraje.

6.9 Sombra del vehículo

Cuando una ruta liquida, entrega su vehículo y otra ruta lo puede tomar; el ruteador deja de decir con qué carro anduvo.

sombraDeRuta(ruta, rt, sombrasDelHistorial):
  si rt.vehiculos no vacío: ''              // todavía lo lleva
  si rt.vehiculoPrevio: devolverlo          // apunte al liquidar
  si rt.sinSombraVehiculo: ''               // se lo quitaron, no lo entregó
  devolver sombrasDelHistorial[ruta]        // último valor no vacío en ruteador_historial del día

Caché por fecha de 2 minutos y deduplicación de pedidos: sin caché cada repintado bajaba cerca de 1 MB, "el grueso de lo que la gente sentía como agenda pegada". Se comparte entre agenda y despacho para no tener dos cuentas distintas.

6.10 ruteador.html: eficiencia por ruta

calcularDia(fecha):
  citas del día; excluir Ruta 20 y canceladas
  ficticias suman facturación pero no son parada, horas ni km
  por ruta: ordenar por inicio; hash = djb2(ids + lat/lng con 5 decimales)
    si cambió el hash: ruteo de calles (OSRM público) central → citas → central, timeout 9 s
       si falla: haversine * 1,35 a 30 km/h, marcado 'estimado'
  guardar caché en ruteador_dias/{fecha}
métricas por ruta: facturación, horas agendadas, km, horas de traslado, ₡/km, ₡/h de traslado (orden por defecto),
  ₡/cita, ₡/h agendada
bandera: valor más de 30 % por debajo de la mediana de 14 días (la propia si hay 5 datos o más, si no la global)

"Construir histórico" recalcula los días faltantes con 600 ms entre llamadas al ruteo.

6.11 Búsqueda de espacio por proximidad (heredada)

Herramienta vieja del mapa de la agenda, reemplazada por Compás y Optimus pero útil como referencia:

punto del cliente; citas de hoy a hoy+28 días; descartar la misma ubicación (< 10 m)
buckets: 0-3, 4-7, 8-14, 15-28 días; filtros por día de semana y turno
hayEspacio(antes|después) = hueco >= servicio + 2 * traslado (60 y 30 min por defecto) contra la cita vecina
rango: 0 si hay espacio y dist <= 5 km; 1 si hay espacio; 2 si no; luego por distancia; 10 por bucket

Su falla (solo miraba la cita vecina, no todas las del día) motivó Optimus y Compás.

7. Despacho y alisto

7.1 Propósito

despacho.html (permiso despacho) es el tablero de quien saca las rutas en la mañana y en la noche. Responde de un vistazo: quién ya inició turno, si la ruta recogió todo lo que necesita y si ya salió. Concentra además el alisto de productos especiales (de la bodega principal a la bodega especial de cada técnico), el cambio de vehículo, la liquidación de cierre, devoluciones y sobrantes, la bodega transitoria y la impresión de certificados y hojas de alisto.

alisto.html quedó como redirección a despacho desde el 26-ago-2026: el alisto en bloque es la función "Alistar especiales" de despacho.

7.2 Pantalla

• Pestañas: Tablero, Servicios (catálogo con productos y herramientas asociados) y Herramientas (catálogo herramientas_alisto).
• Filtro de turno: diurna (por defecto), nocturna, rural o todos.
• Tira de fechas de 3 días atrás a 7 adelante; días con devoluciones sin revisar marcados en rojo.
• Tarjeta por ruta: técnicos con estado de turno (sin encender, trabajando con minutos, terminado), las tareas, vehículo con botón de cambio, barra de liquidación, especiales, sobrantes, no recibidos, traslados entre rutas y notas de bodega.

Turno de una ruta:

turnoElegido = ruteador.turno (solo ese día) || configuracion/rutas.turnos[ruta] || rural para 18 y 19
si elegido es diurna o nocturna: usarlo
si algún técnico tiene bodega personal clasificada nocturna: nocturna
si la primera cita es a las 19 h o más, o antes de las 5 h: nocturna
si no: diurna

El valor por defecto no se guarda ("quedaría escrito como decisión de alguien").

7.3 Datos que lee

• citas por fecha_dia y por rango de inicio_gmt6 del día operacional, deduplicadas, sin ficticias ni Ruta 20, en vivo.
• ruteador en vivo.
• work_sessions en vivo: un turno es vigente si arrancó desde las 5:00 de hoy y no lleva más de 2 h sin actividad (un turno no cerrado de ayer pintaba al técnico en verde y podía disparar el despacho automático).
• empleados, bodegas, servicios, productos, herramientas, movimientos_inventario del día, stock_bodegas.

7.4 Tareas "Antes de salir"

Cinco tareas: datáfono, certificados, herramientas, especiales y vehículo.

Una tarea está hecha si existe ruteador.checklistRuta[tarea] o si el técnico marcó todos sus renglones en ruta.html. Despacho solo lee esas marcas.

todoEnVerde(ruta) = tiene técnicos && ninguna tarea pendiente && todos con turno vigente
autoDespachar (solo el día operacional de hoy):
  si !rt.despacho && !rt.despachoAutoOff && todoEnVerde: rt.despacho = {por:'auto', auto:true, en:ahora}
quitar la marca a mano → despachoAutoOff = true

7.5 Agregación del alisto

acumularRequeridos(acum, metadataCita):
  para cada servicio de la cita:
     def = catálogo de servicios (por id o nombre)
     para cada productoAsociado no excluido:
        acum[productoId] += servicio.cantidad (1) * pa.cantidadPorUnidad (1)
  para cada producto suelto (legado): acum[id] += cantidad
requeridos[ruta] = suma sobre las citas de la ruta (sin ficticias ni Ruta 20)
yaAlistado[ruta] = suma, por técnico de la ruta, del NETO DEL DÍA cargado a su bodega especial
                   (entradas del día operacional menos devoluciones; lo gastado cuenta como alistado)
faltantes = productos con yaAlistado + 0,001 < requerido ; día pasado: cerrado

Lecciones: el saldo arrastrado no cuenta (una ruta salía como alistada porque al técnico le quedaba producto de antes); cuenta todo movimiento del día, no solo los marcados como pedido especial; corte por día operacional (la nocturna perdía su alisto); un traslado a la especial de otro técnico no se suma de vuelta.

planDeAlisto():
  para cada ruta con citas, no rural, en el turno filtrado:
     destino = bodega 'especial' activa de algún técnico de la ruta
     líneas = faltantes (con productoId; buscar por nombre mandaba dos veces el primero de dos homónimos)
repartirPorStock(): el saldo de la principal se reparte en orden de ruta; celdas apagadas envían 0
generarAlisto():
  releer especiales y stock (otro despachador pudo alistar)
  rehacer el plan; si alguna línea bajó, avisar y no generar
  por línea > 0: procesarMovimientoInventario({tipo:'transferencia', origen: principal, destino: especial,
     cantidad, motivo:'Pedido Especial', esPedidoEspecial:true, origenPantalla:'despacho',
     rutaOperativa, fecha: día a las 12:00})
  guardar la hoja solo si salió algo

• La hoja de alisto es un tablero de 4 rutas por página que se convierte a PDF en el navegador y se envía por WhatsApp a bodega.
• Los certificados se imprimen agrupados por ruta (registrándolos antes, ver 9.7).

7.6 Liquidación, vehículo y otras operaciones

• Liquidada: todos los técnicos con reloj apagaron la app (su app no los deja apagar con la liquidación incompleta, ver 8.9). Días pasados se juzgan solo por lo anotado.
• Al liquidar hoy se vacía vehiculos y se escribe vehiculoPrevio; despacho lo repite por si el técnico ya cerró el teléfono.
• Cambiar vehículo: primero quitarlo de la otra ruta, después ponerlo aquí (si falla la segunda escritura queda sin ruta, visible, nunca en dos). Solo de hoy en adelante.
• Quitar un ítem de una cita: se escribe metadata.excluidos o se reduce metadata.productos, y se devuelve a bodega solo lo que sobra:

devolver = max(0, min(cantidadQuitada, tiene - (pide - cantidadQuitada), tope))

Antes se devolvía siempre y "el faltante se movía, no se resolvía".

• Bodega transitoria (se crea sola): sala de espera del alisto de una ruta sin técnico.
• Cargas del día con opción de revertir.

7.7 Inventario que toca la operación

• bodegas {nombre, tipo, empleadoId, vehiculoId, activa, clasificacionRutero?}; tipos principal, especial (una por técnico), rutero (personal), herramientas, apv (vehículo, fuera de uso), transitoria.
• stock_bodegas/{bodegaId}__{itemId} con stockActual.
• Toda escritura de stock pasa por la función movimientoInventario (transacción en dos fases, unidades enteras, stock suficiente, firma del servidor, permisos por tipo de movimiento y por participación en la bodega). Detalle en el capítulo de inventario.

7.8 Traslado Flash y Traslado Exprés

Pantallas de bodega para mover producto rápido con lector de código de barras:

• Traslado Flash: dos pantallas. Primero se escanea la etiqueta de la bodega destino (código corto de 7 dígitos que empieza con 9, o el id crudo); luego cada producto. Una bodega especial pregunta antes para cuál ruta es el alisto; ese alisto se imputa al día operacional de la ruta a las 12:00 y se marca como pedido especial. Sonido agudo si entró, grave si no. Historial de 48 h con eliminar. Los productos inactivos se pueden mover (apagado significa "ya no se compra", no "no se puede sacar").
• Traslado Exprés: tres estaciones (de dónde, qué, a dónde), destinos agrupados por tipo y turno, opción de gasto a una cuenta. Un lector escribe en ráfaga (menos de 40 ms por tecla); se espera a que termine antes de entrar al producto. Los códigos se comparan sin espacios ni mayúsculas y, si son solo dígitos, sin ceros a la izquierda (un EAN-13 leído como UPC-A pierde el cero).
• Las bodegas de vehículo no se ofrecen desde el 21-oct-2026.

8. Vista del técnico (ruta.html)

8.1 Propósito y arquitectura

Aplicación web móvil del técnico fumigador: ver su ruta del día, iniciar y cerrar turno, recibir lo alistado, marcar ingreso y salida en cada cita con GPS, llenar el reporte de servicio con fotos y audios, cobrar y liquidar su inventario. Permiso ruta. También la abren oficina y gerencia para mirar o corregir.

• Una sola página grande con módulo JS; Leaflet con teselas libres para el mapa.
• Caché offline persistente de Firestore (IndexedDB, varias pestañas) inicializada antes que cualquier otro módulo, porque una vez arrancado Firestore no se puede cambiar la caché. Sin IndexedDB cae a memoria.
• El inventario se carga con import() al primer toque: abrir la ruta no debe costar lecturas de bodegas.
• Toda escritura por ruta de campo y con historial (CitaHistorial.prepararHistorial deja extracto en la cita y lista completa en extras/historial en el mismo batch).

8.2 Qué ruta le toca

cargarCitas(fecha) = citas where fecha_dia == fecha, ordenadas por inicio
getMiRuta(fecha):                       // memo de 60 s
  docs = ruteador where fecha == fecha
  usuario = usuario de la vista ("ver como" si está activo)
  ruta = doc cuyo tecnicos[] contiene usuario (comparando con trim)
  normalizar a "Ruta N"

• Se lee el día completo y se compara a mano: con array-contains un username guardado con un espacio al final no aparecía y el turno arrancaba como "oficina".
• Selector con las rutas que tienen citas (sin Ruta 20) más la propia. Sin ruta: "Para el día X aún no has sido asignado a ninguna ruta".
• noEsMiRuta = soloVerComo || !miRuta || miRuta != rutaEnPantalla: franja roja "NO es tu ruta asignada" y botones de alisto y liquidación convertidos en etiquetas. Bug corregido: con miRuta nulo la expresión vieja decía "sí es mía" y cualquiera quedaba con cobros y vehículo ajenos.
• "Ver como" (permiso suplantar): muestra la ruta de otro empleado en solo lectura; todas las escrituras quedan desarmadas porque se firmarían con el uid de quien mira.

Tiempo real: tres listeners (ruteador del día, citas del día de la ruta y sus rutas de apoyo con metadata.ruta in [...], stock de las bodegas de la ruta hasta 10). Se ignoran el primer snapshot y las escrituras pendientes; con un modal abierto el repintado se aplaza. Una cita que sale de la ruta se quita (antes se le podía marcar ingreso). citaVigente(cita) devuelve siempre el objeto vivo (bug: con el detalle abierto el reporte se guardaba en un objeto y la salida leía otro sin reporte).

Citas de apoyo: si un bloqueo del ruteador tiene ayudaRuta, las citas de la ruta ayudada que tocan la franja aparecen como copia recortada a la franja; su ingreso y salida se guardan en metadata.apoyos.<Ruta_N>.* sin pisar los de la ruta dueña; no piden reporte ni cobro.

Avisos:

• Al abrir: citas con hora pasada sin ingreso y terminadas sin salida (una vez por combinación).
• Navegar a la siguiente cita queda bloqueado si una anterior no tiene ingreso o salida.
• Cercanía: watchPosition más lectura cada 60 s; a menos de 500 m de la siguiente cita sin ingreso y sin modal abierto, pregunta "¿Querés marcar ingreso?" (con un modal abierto se espera: antes hacía marcar la cita equivocada).
• Rastro de ubicación en dim_location como máximo cada 55 s.

8.3 Turno (iniciar y apagar)

work_sessions {username, userId, firebaseAuthUID, startTime, endTime, status:'working', gpsStart, distanciaInicio, inicioTardanza?, minutosTardeConvocatoria?}.

verificarCentral(accion):            // desde el 19-oct-2026, al iniciar y al cerrar
  gps = posición con alta precisión, timeout 15 s, sin caché
  dist = haversine(gps, CENTRAL)
  margen = min(gps.accuracy, 150)
  si dist - margen > 300 m: error "Estás a X m de la central"

• Tardanza: si hay convocatoria y el turno se inicia más de 5 min después, se anota.
• Sesión colgada de otro día: se cierra con su última señal y se abre la de hoy. Doble toque: se reconsulta justo antes de crear.
• Tipo de turno: sin ruta, oficina sin inventario; rural, sin vehículo; resto, ruta (las bodegas de vehículo están apagadas desde el 21-oct-2026).
• Técnicos de fumigación sin turno pasada la convocatoria: pantalla bloqueada con enlace al registro de horas.
• Apagar se bloquea si hay faltas de liquidación (8.9) o si toca la revisión semanal de EPP y herramientas. Citas sin método de pago o, en rutas 11 a 19, sin condición, solo avisan.

8.4 Alisto recibido

ruteador.checklistRuta[item] = {por, en, ok, recibidas} con merge. Solo con la app encendida y desde 10 minutos antes de la convocatoria. Un especial que no llegó queda en espFaltan para que despacho decida; el técnico no mueve ese inventario.

8.5 Ingreso a la cita

guardarHoraIngreso(cita):                      // la cita viaja por parámetro, no la "abierta" global
  si ficticia: rechazar ("una venta en ruta no lleva ingreso ni salida")
  si ya hay ingreso: confirmar actualización
  valor = ahora como texto es-CR               // la hora se guarda como TEXTO
  gps = capturarGPS()
  puntos = coordenadas de la cita + coordenadas_corregidas + coordenadas de cada servicio
  dist = distancia al punto más cercano
  si (dist - accuracy) > 300 m: pedir causa
       "Olvidé marcar en el punto" → culpa_tecnico: true
       "El punto de la cita está mal (error de ventas)" → culpa_tecnico: false
  B = 'metadata.' o 'metadata.apoyos.<Ruta_N>.'
  batch: B+hora_ingreso, B+gps_ingreso {lat,lng,accuracy,timestamp, gps_dudoso?, alerta_lejos?,
         culpa_tecnico?, distancia_cita_metros?} + historial ; tope offline de 8 s
  si no es apoyo y monto > 0: recordar foto del comprobante (una vez por cita)

Reglas de GPS: | Regla | Valor | |---|---| | Reutilizar la última posición del mapa | Si tiene menos de 30 s; se descarta al volver de segundo plano | | Primer intento | Alta precisión, timeout 15 s, sin caché | | Segundo intento | Baja precisión, timeout 10 s, caché de 30 s | | GPS dudoso | accuracy > 150 m, se anota sin preguntar | | Fuera de rango | (distancia - accuracy) > 300 m | | Sin GPS | Se guarda igual con aviso |

Lección: con 2 s de timeout el GPS se rendía dentro de las casas y el ranking de puntualidad culpaba al técnico.

Borrar el ingreso: deleteField() de hora y GPS, con _gps_backup en el historial.

8.6 Salida de la cita

Orden de validación:

1. Ficticia: no se puede.
2. Sin ingreso no hay salida (salvo gerencia).
3. Reporte completo (salvo apoyo):

faltantesReporteParaSalida(rep):
  rep.condicion
  al menos 1 foto (rep.fotos + secciones.*.fotos)
  algún comentario (en secciones, comentario_cliente u observaciones)
  si reportado_en >= 9-oct-2026 11:30: condición de los grupos roedores, insectos y especiales

4. Método de pago con respaldo (asegurarMetodoDePago, 8.8). Si el técnico cierra la hoja, no hay salida.
5. Mismo GPS, misma alerta y mismo batch que el ingreso (hora_salida, gps_salida).
6. Si la cita no tiene condición, a los 400 ms sale un modal chico "¿Cómo quedó?" que graba solo la condición.
7. Si todas las citas del día tienen salida, aviso de revisión semanal de EPP.

Corrección del punto por el técnico (punto de la cita mal cargado): lectura de alta precisión, distancia al original (verde < 100 m, amarillo < 500 m, rojo más), precisión (excelente hasta 10 m, buena 30, moderada 100, baja más), frescura (en vivo hasta 5 s, reciente hasta 30 s), foto del frente obligatoria (800 px, JPEG 0,6, Storage ubicaciones/{citaId}_{ts}.jpg). Escribe metadata.coordenadas_corregidas {lat, lng, distancia_metros, precision_metros, edad_senal_segundos, foto_url, foto_path, corregido_por, corregido_en, estado_revision}; oficina la aprueba o rechaza. El punto corregido cuenta para la distancia de ingreso y salida.

Corrección manual de ingreso y salida (solo gerencia): mapa con dos marcadores arrastrables (E y S), hora sugerida igual a inicio e inicio + duración; escribe gps_* {..., accuracy:0, manual_fix:true} y en el historial "(fix manual)". En la agenda (agenda-gps-fix.js) además permite eliminar un registro.

8.7 Reporte de servicio

Estructura de metadata.reporte:

condicion: 'rojo' | 'amarillo' | 'verde'          // grave, leve, libre de plagas
grupos: { roedores, insectos, especiales }        // desde 9-oct-2026
plagas: [{ nombre, condicion }]
secciones: {
  servicio:   { comentario, fotos[] }
  roedores:   { fotos[{url,path}], audios[{url,path,segundos}] }
  insectos:   { ... }
  especiales: { ... }
  (viejas: limpieza, diagnostico, resultados; alias ratas → roedores)
}
hoja_servicio: { url, path }                      // foto de la hoja física firmada
comentario_interno                                // nunca sale al cliente
reportado_por, reportado_en, editado_por, editado_en, reporte_escrito_por?

Árbol de condiciones:

condGrupo(k) = si hay plagas marcadas del grupo → peor(condición de cada una) ; si no → grupos[k]
general = peor(pendienteGeneral, condGrupo de cada grupo)
"Libre" en un nivel → todo lo que cuelga pasa a verde
"Leve" o "Grave" en un nivel → queda pendiente hasta que algún hijo tenga ese color ("?" en los hijos)
no se puede bajar un nivel por debajo de su peor hijo
tocar la condición de una plaga no marcada la marca

Validación al guardar: cada plaga marcada con condición, sin pendientes, cada grupo con condición, un grupo que no está en verde necesita al menos 1 foto subida, general resuelta. Reportes anteriores al 9-oct-2026 11:30 no exigen esto.

El reporte no registra productos ni dosis por cita; el consumo se liquida por bodega al final del día. El nivel de infestación es el semáforo.

Fotos y audios:

• Evidencia: 800 px, JPEG 0,6, hasta 100 por reporte. Hoja de servicio: 1600 px, calidad 0,8 (para leer la firma).
• Storage reportes/{citaId}_{seccion}_{ts}_{4 caracteres}.{jpg|webm|m4a}; reintento de subida máximo 60 s.
• Cada foto se guarda sola al terminar de subir: updateDoc({'metadata.reporte.secciones.<k>.fotos': arrayUnion({url,path})}) contra el citaId anotado al iniciar la subida. Lección del 2-sep-2026: 269 fotos perdidas porque un autoguardado tardío de una cita cayó en otra y el guardado reemplazaba el reporte entero.
• Quitar una foto: arrayRemove con el valor exacto guardado.
• Fotos fallidas en rojo con Reintentar; cerrar con subidas en curso pide confirmación.
• Audios con MediaRecorder, tope 3 minutos, se descartan los de menos de 1.000 bytes.
• Comentario general dictado por voz (reconocimiento del navegador en español de Costa Rica) y pulido por IA (pulirComentarioReporte); el técnico elige original o pulido.

Autoguardado y guardado:

autoGuardar (debounce 500 ms en chips, 1.500 ms en texto):
  cita = la del modal; si la abierta cambió → descartar
  si hay guardado en vuelo → marcar pendiente y repetir
  updateDoc por rutas de punto (condición, plagas, grupos, comentario, editado_*,
    reportado_* solo si no existían, arrayUnion de fotos que no se guardaron solas) ; tope 8 s
Guardar:
  esperar hasta 30 s a que terminen las subidas
  validar árbol y evidencia; confirmar si algo no subió ("lo que no subió no existe")

• El técnico del reporte es el del ruteador de esa ruta y día; si escribe otro, queda en reporte_escrito_por.
• Oficina edita con js/reporte-editar.js: lee fresco, comprime a 1600 px calidad 0,82 y escribe metadata.reporte completo (excepción mitigada con la relectura), historial "(editado desde la agenda)". ubicaciones_mapa.html tiene otro editor que conserva la hoja firmada y repone fotos que no cargó.

Firma del cliente: no hay firma digital en pantalla. Respaldo en foto: la hoja de servicio firmada (opcional; si falta se marca "sin hoja firmada") y el recibo de efectivo del talonario.

8.8 Cobro

Contrato compartido (js/pagos-cita.js, para que ruta y agenda escriban lo mismo):

metadata.pagos               [{ metodo, monto, linea?, motivo? }]
metadata.metodoPago          método de la parte más grande
metadata.precio_final_rutero suma de las partes (null si 0)
metadata.motivoPago
metadata.voucherPago         { url, por, en }   Storage vauchers/{citaId}_{ts}.jpg
metadata.reciboEfectivo      { url, por, en }   Storage recibos_efectivo/{citaId}_{ts}.jpg

• Si no existe pagos, el arqueo viejo (método más precio final, o monto) se lee como una línea.
• Métodos: efectivo, SINPE (transferencia móvil), datáfono (tarjeta), link de pago, transferencia bancaria, cuenta por cobrar, cheque, no aplica. El mixto viejo se lee pero ya no se ofrece: el pago se parte.
• Motivo obligatorio: cuenta por cobrar (atajos "crédito", "no estaba presente", "es empresa") y no aplica ("no se hizo").
• Pago partido: mínimo 2 partes positivas; lo que falta cae en la primera parte no tocada; si suman más que la cita se avisa y se acepta. Lo cobrado puede diferir de lo vendido.
• Pago por línea de servicio (linea: i); no puede convivir con el arqueo de la cita entera (contaba la plata dos veces).
• Respaldos: datáfono sin voucher o efectivo sin recibo bloquean. Fotos a 1000 px calidad 0,7 en campos separados (una cita mixta necesita las dos).
• metadata.monto es la venta (solo gerencia o la función); precio_final_rutero es lo cobrado, editable por cualquier empleado mientras inicio + 18 h > ahora.
• Tocar confirmar sin cambiar el monto no escribe (llenaba el historial).

asegurarMetodoDePago(cita):
  si hay método y no falta respaldo: ok
  si monto <= 0: ok
  abrir hoja de métodos → motivo → voucher → recibo
  si el técnico cierra: false (no se marca la salida)

8.9 Liquidación y cierre del día

js/ruta-inventarios.js con tres paneles (vehículo, mi bodega, mi especial). Lee stock y movimientos con caché de 2 min; el neteo de especiales cubre 8 días contables más 1 (despacho fecha el alisto al mediodía del día de ruta y lo hace la tarde anterior).

listarEspecialesDeRuta():
  por bodega especial de cada técnico de la ruta:
     netearPorDia(movimientos)          // entradas - salidas por día contable; reversión de gasto resta salida
     toparConStock(saldos)              // "el juez es el stock": se recorta al stock real, del día más reciente al más viejo
  liquidable = min(saldo, disponible) > 0
  días futuros (alisto de mañana cargado hoy) no se liquidan

• Liquidar un especial obliga a elegir devolución (a la principal) o gasto con número de recibo entero mayor a 0, sin preselección ("contablemente son dos cosas muy distintas"). Personal: gasto sin recibo. El gasto va a la cuenta de gasto natural con fecha de cierre del día contable (23:00).

Bloqueo de apagar (faltasDeLiquidacion): citas sin arquear, datáfono sin voucher, efectivo sin recibo ("hacé el depósito hoy mismo"), unidades en la especial, inventario personal sin revisar renglón por renglón. Las bodegas de compañeros no traban. Devuelve null mientras no se sepa.

Reporte de cierre: PNG dibujado en canvas con cobros por método, especiales, inventario y fotos de vouchers y recibos, para copiar o compartir.

8.10 Offline

guardarConTopeOffline: carrera entre la escritura y 8 s. Si gana el reloj, la UI se actualiza y avisa "guardado en el teléfono, se envía solo cuando haya señal, no lo registres de nuevo". Usan el tope: ingreso, salida, método de pago, condición, autoguardado, fotos ya subidas, quitar evidencia. Esperan red: pago partido, precio final, voucher, recibo, corrección de GPS, ficticia y alisto. Storage no tiene cola offline: falla al minuto y se reintenta desde la miniatura.

8.11 Lecciones con fecha

9. Después del servicio: reportes, citas en rojo, certificados, garantías y portal

Todo lo que pasa después parte de metadata.reporte con metadata.hora_salida. "Reporte cerrado" significa que la cita tiene salida: antes es un borrador que se autoguarda y los procesos de servidor no lo miran.

9.1 Tres caminos de reporte al cliente

9.2 Citas en rojo: ticket al vendedor

Objetivo: cuando el técnico cierra una visita en rojo (plaga grave), el vendedor debe ofrecer un repaso con precio especial y mandarle al cliente su reporte.

Corre dentro del trigger garantiaRefuerzoOnCita (functions/tickets-rojo.js):

esRojoCerrado(c) = reporte.condicion == 'rojo' && hora_salida && ruta != 'Ruta 20'
                   && !ficticia && !demo && fecha_dia >= fecha de arranque del módulo
alGuardarCita(antes, despues):
  si ni ahora ni antes es rojo cerrado: salir
  si dejó de serlo y hay ticket abierto: cerrar con cierre='ya_no_es_rojo'
  si ya existe ticket y cambió el reporte: rehacer reportes_publicos/{token} con merge
  si no existe:
    pct  = config_tickets_rojo/general.pct (1..100) o 70
    base = precio_final_rutero || monto
    token = 12 bytes aleatorios en base64url
    crear reportes_publicos/{token} con comentario = ''      // vacío hasta pasar la revisión IA
    crear tickets_rojo/{citaId} = {token, estado:'abierto', fecha_dia, ruta, cliente, telefono,
        vendedor: vendedores[0], vendedores, plagas_rojo, monto_base: base, pct,
        precio_repaso: redondear(base * pct / 100 a centenas), enlace, creado_en}
    "already exists" se ignora (carrera entre dos disparos)

Ejemplo: pagó ₡40.000 con 70 % → repaso ₡28.000.

reportes_publicos/{token}: citaId, cliente, fecha_dia, condicion, grupos, plagas[] (solo no verdes), fotos[] (hasta 24 {url, seccion}), comentario_tecnico (nota cruda, hasta 2.000 caracteres, concatenada de las secciones, nunca el comentario interno), comentario (lo que ve el cliente), revision{}, dias_repaso: 14. Reglas: lectura pública por id, listado solo empleados, escritura solo servidor.

Página pública: nivel en rojo, "Qué encontramos", "Lo que anotó el técnico" (solo el texto revisado), fotos, "Nuestra recomendación" (repaso a 14 días con fecha calculada) y botón de WhatsApp prellenado. No muestra precio, vendedor, técnico ni ruta. Todo escapado.

Reglas de tickets_rojo: lectura empleados; crear y borrar solo servidor; un empleado solo actualiza precio_repaso, precio_editado_por, precio_editado_en, intentos. config_tickets_rojo solo gerencia.

9.3 Revisión IA de la nota del técnico

Trigger revisarReporteRojo sobre reportes_publicos/{token} (functions/revision-reporte-rojo.js). Evita que al cliente le lleguen: groserías, juicios sobre la persona o su casa, lenguaje discriminatorio, datos de terceros, promesas que la ley de protección al consumidor obliga a cumplir ("garantía", "erradicar", "100 %", "no vuelven", "libre de plagas"), afirmaciones médicas o comentarios internos.

alEscribirReporte(token, doc):
  si no hay comentario_tecnico: salir
  h = sha1(comentario_tecnico)
  si doc.revision.hash == h:                      // anti bucle: el propio update re-dispara el trigger
     si doc.comentario != revision.texto: reponer comentario
     salir
  r = revisar(texto)
  update reportes_publicos: comentario = r.texto, revision = {hash, estado, texto, cambios, modelo, en}
  copiar revision a tickets_rojo/{citaId}
revisar(texto):
  vacío → ok
  llamar al modelo de lenguaje con salida JSON {hay_problema, texto, cambios[{antes, despues, motivo}]}
     instrucciones: si no hay nada, devolver el texto letra por letra igual; cambiar solo la frase;
     no agregar; no bajar la gravedad; no alargar
  error de red o parseo → estado 'error', texto ''     // no se publica la nota
  si !hay_problema:
     si politicaPromesas.revisar(original) ok → 'ok' con el ORIGINAL (si la IA "mejoró", se ignora)
     si no → 'error'                                   // la regla dura gana
  si largo(nuevo) > largo(original) + 10 → 'error'
  si politicaPromesas.revisar(nuevo) falla → 'error'
  → 'corregido' con hasta 10 cambios

• Con error el cliente ve nivel, plagas y fotos, pero no la nota.
• politica-promesas.js existe en dos copias idénticas: navegador (avisa) y servidor (decide). Detecta "garantía" y "erradicar" en subcadenas, partidas con espacios y con 1 o 2 letras de distancia de edición (palabras de 6 a 16 letras; 2 de distancia si tiene 8 o más). Ignora enlaces propios.

9.4 Verificador de tickets y burbuja roja

ticketsRojoVerificar (cada 10 minutos, zona Costa Rica, 512 MiB, 300 s), para cada ticket abierto:

1. Rehace la copia del cliente si el ticket no tiene revisión o si el hash no coincide con la nota actual (cubre tickets anteriores a la revisión y un bug donde la nota se leía de la sección equivocada).
2. Busca envío posterior a creado_en: en la línea oficial (mensaje saliente no fallido con la plantilla del repaso, o con el token, o con el enlace de la encuesta de esa cita) y en los teléfonos de empresa (chats del cliente con mensajes propios que contengan el enlace). De paso calcula por qué canal va la conversación.
3. Si no hubo envío, busca un refuerzo agendado: cita del mismo teléfono desde el día siguiente, no ficticia ni cancelada, creada después de la visita y del mismo cliente (nombre normalizado o misma sede: las cuentas corporativas tienen decenas de sedes con el mismo teléfono). Si la hay: estado:'enviado', cierre:'refuerzo_agendado'.
4. Con envío: estado:'enviado', envio{canal, tipo, por, en}, cierre:'mensaje_enviado'.
5. Si nada: actualiza conversacion{canal, numero, ultimo_ms} solo si cambió.

Burbuja roja en la agenda (js/agenda-fab-rojo.js): listener de tickets abiertos (del vendedor, o todos para gerencia) y enviados de los últimos 3 días. Tarjeta con cliente, plagas graves, "Pagó ₡X → Repaso ₡Y" editable y fecha sugerida. Mensaje armado con primer nombre, fecha de visita, plagas, enlace, repaso a 14 días y precio. Canales: plantilla por el CRM (abre el embudo del vendedor con parámetros), WhatsApp de empresa o copiar. Botones apagados hasta que exista la revisión. Cada clic anota intentos[]. Gerencia edita el porcentaje.

9.5 Reporte consolidado mensual con clave

• reportes_cliente/{telefono}: clave, mes, nombre_cliente, comentario_general, citas[] (copia de las citas elegidas con condición, plagas, secciones, fotos, servicios, hoja), citas_mapa[], generado_por, generado_en.
• Lo genera un empleado desde ubicaciones_mapa.html: marca citas del mes, opcionalmente pide a la IA un comentario consolidado (generarComentarioConsolidado: 3 a 4 oraciones con hallazgos que requieren acción del cliente; si todo está verde, frase fija) y genera.
• Clave: palabra de una lista de 30 más un número de 1000 a 9999, o manual (mínimo 4 caracteres, sin espacios). Regenerar conserva la anterior.
• Enlace con el teléfono ofuscado (XOR con una cadena fija y base64url; es ofuscación, no seguridad).
• Endpoint reporteCliente (POST sin login): teléfono de 6 dígitos o más; límite de 12 intentos por teléfono por minuto con transacción en _rate_limits/rep_<tel>_<minuto> (expira a 24 h, responde 429); 404 si no existe, 401 si la clave no coincide; devuelve el documento sin la clave. La colección solo la leen empleados.
• La página muestra índice por condición, mapa con puntos por color, cada cita con observaciones, fotos, audios, hoja firmada, servicios con total y texto por condición, aviso de confidencialidad y botón de PDF.

9.6 Hoja de servicio

hoja_servicio.html es una plantilla imprimible estática (Carta vertical) que replica la hoja de papel que firma el cliente. No lee ni escribe base de datos (permiso cumplimiento_salud). La versión firmada vuelve como foto en metadata.reporte.hoja_servicio.

Contenido, basado en los datos obligatorios del reglamento sanitario de control de plagas (razón social, dirección, teléfono, nombre comercial y genérico de cada producto, medidas de seguridad antes, durante y después):

• Frente: valoración global en semáforo (Libre, Moderada, Grave) y "requiere repaso"; datos de la visita (cliente, dirección, fecha, horas de inicio, fin y reingreso, dos técnicos); precauciones (mascotas en otra habitación hasta que seque; asmáticos y adultos mayores reingresan a los 120 min; niños a los 60 min); diagnóstico por plaga; productos aplicados (lista de unos 13 con nombre comercial y genérico, casillas sí y no, dos líneas "Otro"); medidas de seguridad; condición de limpieza (óptima, adecuada, requiere mejoras, favorece la reinfestación); próximo servicio (2 semanas si es grave, 1, 3 o 6 meses); refuerzo con fecha y precio; monto y método de pago; emergencias; firmas.
• Reverso (términos): objetos de valor, distancia de 5 m, ventilar 2 h; el servicio es de control, no de erradicación; verde con garantía de 30 días naturales y reclamo con evidencia dentro de 5 días de la reaparición; amarillo con nuevo servicio en 30 días o menos; rojo requiere servicios adicionales; locales de alimentos con control mensual; aviso previo a emergencias en termonebulización; cebos solo en cebadera con llave.

9.7 Certificados de fumigación y verificación por QR

Regla central: el certificado se registra en la base antes de dibujar el QR, y el QR solo lleva el serial. Lo que no está en la base no es un certificado.

certificados_emitidos/{serial}: | Campo | Notas | |---|---| | tipo | fumigacion o capacitacion | | establecimiento | Fumigación; puede llevar varias líneas separadas por ; | | direccion | "provincia, cantón, distrito" | | servicio | Nombres de los servicios de la cita; por defecto "Fumigación" | | fecha | AAAA-MM-DD, día operacional de la cita | | vigenciaDias | Por defecto 30 (de metadata.validez_dias), 1 a 365 en pantalla | | citaId, emitidoPor, emitidoEn | | | nombre, cedula, curso, porcentaje | Capacitación |

Reglas de Firestore: get público; list empleados; update y delete prohibidos; create solo empleado con lista cerrada de claves, serial que calce con CERT-EP-[0-9]{4}-[A-Z0-9-]{6,40}, campos obligatorios por tipo, topes de largo, vigencia de 0 a 3.650, porcentaje de 0 a 100 y emitidoPor igual al usuario que escribe.

Numeración: CERT-EP-<año>-<8 caracteres> con alfabeto base32 sin I, O, 0 ni 1 (dictable por teléfono), generado con crypto.getRandomValues. No es correlativo; un choque haría fallar el create.

Emisión:

1. Desde la agenda: cada renglón del campo certificados es un establecimiento; provincia, cantón y distrito de la cita; fecha operacional.
2. Se abre la pestaña nueva antes del await (para que el navegador no la bloquee); si falla el registro se cierra y no se genera nada.
3. Un certificado abre certificado_fumigacion.html?s=<serial>; varios van a certificados_seccion.html (un certificado por hoja).
4. Desde despacho: mismo mecanismo para varias rutas.

Páginas: certificado_fumigacion.html?s= lee la base sin sesión y pinta la hoja (Carta horizontal) con QR que apunta a sí misma y "verificado en la base"; sin ?s= es un enlace viejo con datos en la URL y se marca "sin verificación". "Válido hasta" = fecha + vigencia. verificar-certificado.html verifica ambos tipos (capacitación con puntaje mínimo 90). Generador de PDF con los certificados anuales de capacitación de cada técnico (4 cursos, el aprobado más reciente fija la vigencia de 12 meses).

9.8 Garantías del lado de la cita

garantias/{token} (token de 28 caracteres base36 aleatorios):

• Al crear desde la cita (botón Garantía): datos de la cita origen, estado:'solicitud_enviada', creado_por; la cita recibe garantiaId. Si ya hay caso, el botón abre su seguimiento (antes se creaban dos o tres enlaces por cliente).
• El cliente llena garantia.html?t=<token> sin login: motivo (hasta 2.000 caracteres) y evidencia obligatoria desde el 30-oct-2026 (hasta 20 archivos; fotos a 1600 px calidad 0,82; videos hasta 60 MB) en Storage garantias_publicas/<token>/.
• Estados: solicitud_enviada → pendiente_revision → aprobada o rechazada → realizada (visita agendada); cierres cliente_desiste, cliente_no_contesta.
• Reglas: lectura pública por id, listado empleados, borrar nunca; el cliente sin login actualiza una sola vez (de enviada a pendiente, solo sus 6 campos); cualquier empleado puede marcar realizada con la cita agendada o agregar seguimientos; el resto lo hace quien gestiona garantías.

Automatismos:

vincular(cita):                         // dentro de garantiaRefuerzoOnCita
  si cancelada, Ruta 20, ya ligada o ficticia: salir
  abiertas = garantías del teléfono, no cerradas, no demo
  calza si no es la cita origen, no fue descartada,
        inicio >= día del reclamo (holgura 6 h) y <= creado_en + 60 días
  tomar la más reciente
  si monto <= 0: transacción → garantía 'realizada' con vinculo:'auto'; cita es_garantia=true, garantia_de
                 (aunque no estuviera aprobada: decisión de gerencia)
  si monto > 0: refuerzos_posibles += {citaId, fecha_dia, ruta, monto}   // alguien confirma o descarta

• Cancelar la visita con el motivo "no aceptó" o "no contesta" cierra el caso.
• garantiaAvisoRespuesta (al pasar a pendiente de revisión): avisa por WhatsApp al grupo configurado con cliente, días desde el servicio (marcado si pasan de 30), condición del reporte, cantidad de evidencias, motivo, enlace al caso y mención al vendedor.
• garantiasResumenDiario (lunes a sábado 8:00): casos por decidir con 1 día o más (8 más viejos), aprobados sin visita (5), formularios sin llenar con 2 días o más, agrupados por quien generó el enlace. Candado diario.
• Panel garantias.html: busca espacios libres de 30 min en los próximos 7 días pegados a una cita existente de la misma ruta y turno, ordenados por distancia; "Agendar aquí" aprueba y abre la agenda con la cita en ₡0. Los mensajes al cliente nunca dicen "garantía" (política de promesas).

9.9 Portal del cliente al cerrar el reporte

portalPushAlCerrarReporte (onWrite de citas, 1 GiB, concurrencia 4): si el reporte cambió y el teléfono pertenece a una cuenta de cartera (portal_cuentas con telefonos array-contains o por id), relee 24 meses de citas de la cuenta, infiere sedes (por nombre, o por GPS a 120 m; antes 75 m partía la misma sede en dos) y escribe portal_cuentas/{cuenta}/reportes/{citaId} recortado (sin comentario interno ni monto) y visitas/{citaId} futuras (sin técnico, ruta ni monto). Triggers espejoPortal* replican esos documentos a otro proyecto (el portal), en una sola vía, con una cuenta de servicio en secretos.

10. Encuestas y satisfacción del cliente

10.1 Encuesta por cita

Colecciones: encuestas_citas/{citaId} (principal); encuestas y encuestas_id (flujo viejo con id base36 de 9 caracteres); justificaciones_sin_encuesta/{citaId}.

Generación (agenda):

generarLinkEncuesta(cita, tipo):
  si es ficticia: bloquear ("la encuesta va en la cita de la visita")
  si venció plazoEncuesta (5.9): bloquear; la justificación queda en solo lectura
  si encuestas_citas/{citaId}.estado == 'respondida': devolver la URL sin escribir
  setDoc merge {cita_id, tipo_encuesta, estado:'pendiente', fecha_link_generado}
  URL = encuesta.html?c={citaId}&t={tipo}; copiar invitación al portapapeles

Tipos y número de preguntas: hogares 17, locales 15, garantías 6, especiales 12, roedores 14, áreas comunes 21.

Página pública encuesta.html (sin login): una pregunta por pantalla, comentario opcional, avance automático. Tipos: escala 1 a 5, sí y no (con N/A), puntualidad (sí, no, "no, pero me avisaron"), texto.

principal = satisfacción con el técnico
resto = preguntas puntuables sin la principal ni la del vendedor
scorePrincipal = (v - 1) / 4 * 100
resto: N/A = 100; escala = (v - 1)/4*100; puntualidad sí o avisado = 100; sí/no: sí = 100, no = 0
final = 0,5 * scorePrincipal + 0,5 * promedio(resto)
etiqueta: >= 95 Bueno ; >= 90 Aceptable ; si no "Requiere atención"
scores = {satisfaccion_tecnico, satisfaccion_vendedor (aparte), cumplimiento, final, etiqueta}

Reglas de la respuesta pública: estado respondida, solo campos de una lista cerrada, una sola vez, respuestas máximo 60 elementos, user_agent 400 caracteres. Antes era update: if true y cualquiera podía reescribir encuestas ajenas.

Reporte (reporte_encuestas.html, permiso reportes_gerenciales): une todas las fuentes; técnicos de cada encuesta por cita → ruteador/{fecha_dia}_{ruta} (lección: derivar el id con UTC acreditaba las citas de la tarde a la cuadrilla del día siguiente); vistas individual, ranking por técnico, ficha y diagnóstico con "impacto negativo" (promedio sin esa encuesta menos promedio con ella); muestra novedad_tecnico (lo que el técnico reportó antes de que el cliente se quejara).

10.2 Satisfacción por WhatsApp (clasificación con IA)

satisfaccionClientes corre a las 4:30 todos los días (zona Costa Rica, 1 GiB, 540 s).

unidad: cita de Ruta 1..19, no garantía, no ficticia, desde la fecha en que los teléfonos de empresa quedaron completos
ventana de cada cita: inicio + 1 h hasta inicio + 14 días, o hasta la siguiente cita del mismo teléfono
madura: fecha_dia <= hoy - 15 (después no se reclasifica salvo cambio de versión del método)
rango: desde hoy - 15, más rezagadas de 60 días sin madurar o pendientes
texto por cita: líneas "MM-DD HH:MM CLI|EP: texto" (empresa cortado a 300, cliente a 1.500);
                la encuesta respondida entra como "[ENCUESTA n de 100, comentarios]"
audios del cliente: transcritos con un servicio externo de voz a texto, caché por sha1(url)
si hash(texto) igual y misma versión: reusar clasificación
modelo de lenguaje con salida JSON, prompt en caché, lotes de 6, hasta 3 intentos (5 s × intento ante 429 o 5xx)
categoría única: contento, tramite, duda, reclamo_leve, reclamo_fuerte, silencio (chat sin respuesta), sin_chat
                 (las dos últimas sin IA); pendiente si la IA falla
causa (prioridad): plaga (igual, bajo, volvio) > ejecución (incompleto, metodo, danos, trato)
                   > agenda (tarde, cambios) > cobro (distinto, precio) > atención (seguimiento, info) > otro
si hay elogio y reclamo: gana el reclamo
escribe satisfaccion_citas/{citaId} (lotes de 400) y satisfaccion_semanas/{lunes} con porcentajes,
  causas, plagas, desglose por vendedor y técnico, madura

La pantalla satisfaccion_clientes.html muestra la última semana definitiva y la semana en curso marcada "todavía sube"; en las matrices por persona una celda se colorea solo con 5 citas o más.

11. Automatizaciones de servidor de la operación

11.1 Optimus: espacios de agenda para el bot de ventas (functions/optimus.js)

Propósito: que el vendedor virtual de WhatsApp proponga al cliente horarios reales pegados a otras citas cercanas, y cree la cita cuando el cliente elige. Es la versión de servidor del buscador de la agenda, con una corrección de fondo: cada inicio propuesto se valida contra todas las citas de ese día y esa ruta, no solo contra la vecina.

Reglas fijas: | Regla | Valor | |---|---| | Ventana de trabajo | Inicio entre 07:00 y antes de 20:00 hora local | | Rutas por defecto | Ruta 1 a Ruta 10 | | Radio | 5 km | | Traslado entre citas | 30 min | | Rango | Desde mañana, 14 días | | Resultados | 3 | | Misma ubicación | Una cita a menos de 10 m es el mismo inmueble, no una vecina | | Ocupación extra | Propuestas del bot en estado elegida o aprobada (bot_ventas_propuestas) cuentan como ocupadas |

proponerEspacios(lat, lng, duracion, opciones):
  citas = citas del rango (sin Ruta 20, sin asignar ni canceladas) + propuestas elegidas
  porDiaRuta = índice fecha|ruta
  para cada cita c con coordenadas, en ruta permitida, día no evitado, 10 m < dist <= radio:
     para posición en [antes: c.inicio - (duracion + traslado), después: c.fin + traslado]:
        descartar si ya pasó, si está fuera de 07:00-20:00 o cae en otro día operacional
        descartar si choca con alguna cita de esa ruta y día (solape puro)
        descartar si choca con alguna otra (sin contar la vecina) dejando el traslado como colchón
  leer ruteador de cada día y ruta sobreviviente; descartar si toca un bloqueo
  score = 100
        - min(40, 6 * días desde hoy)
        - min(40, 8 * km)
        + 10 si la ruta ya tiene técnicos
        + 10 si la zona del ruteador coincide con la del cliente
        - 15 si es "antes" y empieza antes de las 8
        + 8 si es un día de la semana preferido
        + 12 si está a 60 min o menos de la hora preferida
  deduplicar por fecha_ruta_hora quedándose con el mejor
  elegir primero un espacio por día distinto (opciones reales al cliente), completar con los mejores
  devolver ordenados por hora, con motivo "A X km de otro servicio en <distrito> el <día> a las <hora>"
validarEspacio(...): justo antes de crear, relee el día y el ruteador; ignora la propuesta que se aprueba
crearCita(...): teléfono 506 + 8 dígitos obligatorio, coordenadas obligatorias, valida espacio,
  arma el documento con la misma forma que una cita hecha a mano (estado 'agendada', confirmada false,
  servicios, detalle_cotizacion, validez 30, modalidad 'bot_optimus' o la indicada) y crea o actualiza clientes/{tel}
  sin pisar un nombre existente con uno vacío

La ubicación del cliente (pin, enlace de mapas, texto como "barrio X de cantón Y") se resuelve con functions/geo.js (11.8).

11.2 Compuerta "agendar sin optimizador"

Se mide cuántas citas de cada vendedor entran por el optimizador (modalidad_cita_creada = optimizador_algoritmo). Cuando el vendedor está por debajo del mínimo de uso, la agenda exige una justificación escrita; la función revisarJustificacionSinOptimus (POST, empleado) la revisa con un modelo de lenguaje: rechaza textos de menos de 100 o más de 4.000 caracteres, sanitiza la entrada y devuelve un veredicto valida, debil o invalida (restricción real de la cita frente a relleno para pasar el contador). Desde el 29-oct-2026 el arrastre en el cronograma lleva directamente a Compás, que cuenta como optimizador.

11.3 Envío de citas al grupo Ventas (functions/cita-a-ventas.js)

Propósito: que todo el equipo de ventas vea cada venta nueva con un mapa de la ruta de ese día, para detectar citas agendadas lejos del resto.

Envío automático:

automatico(citaId):
  cfg = wa_equipo_config/ventas_auto ; si cfg.activo == false: salir
  esperar cfg.minutos (3 por defecto)        // el 97 % de los envíos manuales ocurría antes; las correcciones
                                              // de hora o precio pasan en los primeros 2 minutos
  releer la cita; enviar solo si existe, tiene fecha_dia, monto > 0, vendedor, no es Ruta 20,
       no es ficticia, no está cancelada y nadie la mandó ya (ventas_envios/{citaId})
  número de salida = teléfono de empresa conectado del primer vendedor (el de menor orden) o el bot de avisos
  mandar(...)

Una ejecución por cita, para que un lote salga como pantallazos individuales.

La imagen (1620 × 1080, enviada a escala 2) se arma en el servidor con HTML y un navegador sin cabeza:

• Cabecera amarilla para rutas diurnas y negra para especiales: cliente, día y hora, lugar (acrónimo de provincia, cantón, distrito), "cliente nuevo" o número de vez (sin contar ficticias), servicios, observaciones y monto.
• Columna izquierda: línea de tiempo de la ruta con eje fijo por turno (diurnas 7 a. m. a 4 p. m., nocturnas 3 p. m. a 1 a. m., se abre si una cita se sale), bloques por duración, en cada hueco el manejo estimado y en rojo si no cabe o si se pisan.
• Mapa: recorrido por calles entre las citas de la ruta en orden de hora, tramos de esta cita en rojo con su tiempo, las otras rutas del mismo turno de fondo. Teselas de un proveedor de mapas con llave (cupo gratuito mensual amplio); sin llave cae a teselas libres.
• Cita movida: banda roja "CITA MOVIDA" con antes y ahora, y dos columnas de ruta (de dónde venía, dónde quedó); el texto etiqueta a los vendedores y dice quién la movió. Rastro en ventas_movidas.

tiemposDeManejo(citas):                    // servicio público de ruteo OSRM, sin llave ni costo
  una consulta con todos los puntos en orden de hora; timeout 8 s (si no contesta, la imagen sale sin tiempos)
  por tramo: min = max(1, redondear(duración/60)), metros, trazado aligerado a ~80 puntos
resumir(d): "Parada N de M. Desde la anterior: X min de manejo, Y libre (o 'se pisan Z', 'no alcanza'). ..."

Salida: imagen a Storage, documento en wa_equipo_salida {numero, chatId, tipo:'imagen', ruta, texto, hd, estado:'pendiente', creadoPor} con texto "Venta de ", teléfono y enlaces cortos a la cita en la agenda y al mapa de rutas del turno; rastro ventas_envios/{citaId} {por, numero, cuando, salidas[], veces}. La agenda pide la vista previa al guardar una cita nueva y al soltar una cita arrastrada.

11.4 Línea de coordinación por cita (functions/wa-coordinacion-citas.js)

Guarda en cada cita por cuál WhatsApp de la empresa se conversa con ese cliente, para mandar luego la encuesta por ahí. Solo con evidencia.

waCoordinacionCitasHoraria: minuto 20 de cada hora, zona Costa Rica, citas de hoy a +7 días. waCoordinacionCitasNow (HTTP, gerencia) acepta dias (hasta 120) y desdeDias (hasta −120) para rellenar historia.

evidencia:
  teléfonos de empresa: wa_equipo_cuentas/{numero}/chats (sin grupos ni cuentas privadas), con asignado y ts
  línea oficial: whatsapp_conversations/{tel} con lastMessageAt y assignedTo (lecturas de a 100)
decidir(cita):
  1. vendedor_cita: un teléfono de empresa asignado a un vendedor de la cita con chat del cliente
  2. crm: la línea oficial tiene conversación
  3. otro_equipo: cualquier otro teléfono de empresa con chat
  en el mismo escalón gana el chat más reciente; sin candidatos no se escribe nada
escribe citas/{id}.whatsapp_coordinacion = {linea, canal, asignado, regla, telefonoCliente, chatId,
  ultimoMensajeAt, candidatos[], actualizadoAt, version} solo si cambió; nunca borra lo ya guardado
lotes de 400 escrituras

Es un campo de primer nivel para que sobreviva a las escrituras de la agenda.

11.5 Alerta de llegada tardía (functions/alertas-llegadas.js)

alertasLlegadas: cada 5 minutos de 5:00 a 22:55, zona Costa Rica. Es informativa: da visibilidad, no castiga.

esperados(fecha):
  técnicos: hora de convocatoria de su ruta en el ruteador del día (sin Ruta 20)
  ventas: rol de la semana (roles_ventas/{lunes}): diurno 8:00, temprano 7:00, nocturno 12:00,
          domingo 8:00, sábado tarde 14:00 los sábados; solo los días que el rol trabaja
  gerencia, administración y bodega no se avisan
entradas = primer startTime en work_sessions dentro de la ventana
           (una sesión hasta 4 h antes de la hora esperada cuenta como "madrugó"; antes de eso es otro turno)
por persona:
  tarde = minutoActual - esperado ; si < 0: aún no
  si ya marcó y se le avisó antes: aviso verde "inició turno a las HH:MM (N min tarde)" una vez
  si no marcó: el escalón más alto alcanzado y no enviado de [6, 11] minutos (amarillo, rojo)
rastro: alertas_llegadas/{fecha}_{username} {esperadoMin, enviados[], llegoAvisado, llegoMs}
envío: al grupo personal de WhatsApp de cada uno con su @ (gerencia está en todos); sin grupo, al grupo de alertas;
       los avisos de "sin marcar" llevan imagen fija; el verde solo texto

Hasta el 21-oct-2026 los escalones eran 0, 5 y 10 minutos. Configuración en alertas_config/llegadas.

11.6 Alertas del GPS de los vehículos (functions/alertas-gps*.js)

Los vehículos tienen rastreadores que guardan lotes de puntos en flota_tracks cada unos 2 minutos.

• alertasGpsOnTrack (onWrite de flota_tracks): detecta episodios de velocidad.
• alertasGpsBarrido (cada 5 minutos): cierra episodios de vehículos que dejaron de reportar y revisa rutas terminadas.
• alertasGpsEnviar (onCreate de alertas_gps): arma la imagen y la encola para WhatsApp.

La alerta de velocidad espera la confirmación de quién manejaba antes de enviarse.

11.7 Respuestas en el grupo de coordinación

coordinacionRespuestas (cada 15 minutos) mide cuánto tarda el equipo en responder las etiquetas (@) que ponen los técnicos en el grupo de coordinación de ruta (regla: toda etiqueta de un técnico se responde, al menos "Recibido", citando el mensaje). Fuente: mensajes que el agente de WhatsApp guarda con autor, menciones y mensaje citado. Resultado diario en coordinacion_respuestas/{fecha} con totales, desglose por etiquetado, por quien respondió y por técnico.

11.8 Geografía en el servidor (functions/geo.js)

• Mapa de distritos precalculado (distritos-cr.json, unos 1,5 MB) con caja y centroide por polígono, para que el punto en polígono solo corra sobre los polígonos cuya caja contiene el punto. Nombres con tildes en ubicaciones-cr.json (árbol provincia → cantón → distrito con ids).
• Límites aceptados: latitud 8,0 a 11,2 y longitud −85,9 a −82,5.
• Si un punto no cae en ningún polígono (costa, mar frente a la playa) se toma el distrito más cercano hasta 3 km.
• Texto libre: normalización con alias coloquiales, búsqueda de distrito por nombre y geocodificación con un servicio público de mapas (1 llamada por segundo). Enlaces cortos de mapas se resuelven siguiendo la redirección.
• Cobertura: atlas_zonas (caché 10 min) con punto en polígono. Si el atlas no se puede leer o está vacío se responde "cubierto": mandar a humano a todos los leads por una falla de lectura sería peor que atender uno fuera de zona.

puntoEnPoligono(lat, lng, poligono):        // ray casting
  dentro = false
  para cada arista (i, j):
     si (yi > lat) != (yj > lat) y lng < (xj - xi) * (lat - yi) / (yj - yi) + xi: dentro = !dentro
  return dentro

12. Logística, mapas y geografía (pantallas)

12.1 Compás: optimizador de huecos (compas.html)

Propósito: elegir día, ruta y hora para una cita nueva de modo que el técnico maneje lo menos posible, agrupando citas cercanas. Desde el 29-oct-2026 es la forma normal de agendar (el arrastre en el cronograma y el botón Clonar llevan aquí). Lo usan vendedores y coordinación. espacios_ruta.html y mapa_agenda.html redirigen aquí.

Entrada: GPS pegado, enlace de mapas, clic en el mapa o teléfono del cliente (toma la ubicación de su última cita con GPS y muestra última visita, número de servicios y si ya tiene cita futura). Filtros: duración, turno (D o N), días hacia adelante, fecha exacta, día de la semana (mira al menos 3 semanas), mañana o tarde (corte a las 12:00 en diurnas y a las 19:00 en especiales), ruta específica.

Modelo de manejo:

manejo(a, b) = km(a, b) < 0,05 ? 0 : 6,2 + 1,83 * km_en_línea_recta(a, b)     // minutos
   calibrado con 2.387 tramos reales medidos por el servicio de direcciones (error típico 2,5 min)
factorPico(hora) = 1,35 entre 6:30 y 9:00 ; 1,3 entre 16:00 y 19:00 ; si no 1   (supuesto, no calibrado)
holgura(m) = m > 0 ? 5 + 0,2 * m : 0      // a cada lado de la cita, para imprevistos
ventanas: diurno [7:00, 17:00] ; especial [15:00, 26:00 (2 a. m.)]

Lectura de ocupación: citas del rango (sin Ruta 20 ni canceladas), ruteadores del rango (técnicos y bloqueos, con bloqueos de madrugada pasados a +24 h) y propuestas del bot elegidas.

huecosDeRuta(rd, X, dur, turno, minimoInicio, ventana):
  nodos = citas ordenadas; una cita sin GPS toma el punto de la anterior con GPS (o la central)
  para cada hueco entre prev y sig (incluye antes de la primera y después de la última):
     ida    = manejoA(prev o central → X, a la hora en que termina prev)
     vuelta = manejoA(X → sig o central, a la hora en que debe llegar a sig)
     desde  = prev ? fin(prev) + ida + holgura(ida) : inicioVentana
     limite = sig ? inicio(sig) - vuelta - holgura(vuelta) : finVentana
     desde  = max(desde, inicioVentana, minimoInicio)       // hoy: nada antes de ahora + 60 min
     inicio = redondear arriba a 15 ; saltar bloqueos del ruteador (hasta 4 veces)
     ultimoInicio = redondear abajo a 15 de (min(limite, finVentana) - dur)
     si cabe:
        sugerida = inicio, salvo antes de la primera: lo más tarde posible (pegada en el tiempo)
        costo = sin citas: 15 (umbral de grupo nuevo)
                entre dos: ida + vuelta - manejo(prev → sig)     // desvío real
                antes de la primera: vuelta ; después de la última: ida
        // la salida y el regreso a la central NO cuentan: ese viaje se hace siempre

Con 2.491 citas de dos meses simuladas en orden de creación a ±2 días, este criterio bajó 23 % el manejo entre citas contra lo real.

Resultados:

• Solo rutas que salen ese día (con citas o técnico) y del turno elegido.
• Colores: hasta 10 min de desvío "bueno", hasta 25 "medio", más "malo".
• "Para ofrecerle al cliente": 5 opciones, primero el hueco más barato de cada día distinto, luego los siguientes sin repetir ruta en el mismo día. Botón Copiar arma el mensaje con las 3 mejores como se le dice al cliente.
• Día por día: el mejor hueco de cada ruta, con "ver más".
• "Abrir una ruta adicional": cuando nada sirve, 2 opciones de rutas que ese día no salen (sin citas, sin técnico ni bloqueos), nunca en domingo salvo pedido expreso; el técnico se asigna después en el ruteador.
• Al elegir una opción: timeline del día con la cita nueva en su hueco (movible de 15 en 15 dentro del rango que respeta manejo y holgura), mapa con los tramos nuevos en rojo y la salida y regreso a la central punteados.
• Al confirmar abre la agenda con nuevaCita=1&hora&ruta&duracion&modalidad=optimizador_algoritmo&origen=compas&lat&lng.

Reacomodos sugeridos (con la cita nueva puesta):

para cada cita c de OTRA ruta del mismo día y turno, a 6 km o menos de la nueva:
  ahorro = lo que su ruta deja de manejar sin ella (desvío)      ; exigir >= 10 min
  mejor hueco para c en esta ruta (con la nueva incluida)
  neto = ahorro - costo del hueco                                 ; exigir >= 6 min
mostrar los 3 de mayor neto; mover la cita es de quien la vendió o con su autorización

Probado con días reales: las citas que estorban ahorran 10 a 19 min al sacarlas pero meterlas cuesta 7 a 13, neto típico 3 a 6.

Compactar rutas (próximos 7 días):

para cada cita c con GPS (sin ficticias, sin propuestas, no pasada):
  ahorro en su ruta A ; exigir >= 8 min
  para cada otra ruta B del mismo turno y día: costo geométrico de insertarla en su mejor lugar
  mejor B con neto >= 8 y la vecina a 5 km o menos (lejos de todo no es un reacomodo)
  estrella si en B hay hueco a la MISMA hora ±90 min (se mueve sin renegociar con el cliente)
ordenar: primero con estrella, luego por ahorro; una cita se sugiere una vez; una cita que sirve de ancla
de otra sugerencia no se propone mover
mapa: ruta de origen fina, ruta destino gruesa, flecha animada de la cita a su vecina nueva

"Aprovechar el viaje": garantías por atender y clientes inactivos de la cartera que caen cerca de la ruta elegida. Desde la lista se puede agendar una garantía en un hueco de 30 min pegado a la cita más cercana y armar el WhatsApp de confirmación en el teléfono donde ya está el chat (sin la palabra garantía ni promesas).

12.2 Logística (logistica.html)

Herramienta anterior a Compás para encajar trabajo nuevo en días futuros. Fijar un punto en el mapa → buscar citas dentro de un radio (5 km por defecto, de 1 a 25) en los próximos 21 días (solo posteriores a hoy), ordenadas por distancia (verde hasta 2 km, ámbar hasta 5) → elegir día y ruta → timeline compacto con huecos libres de al menos 45 min → arrastrar sobre el timeline para fijar inicio y duración (un toque vale 1 hora, mínimo media hora) → abre la agenda prellenada con modalidad mapa_logistica. Usa distancia en línea recta a propósito: el tiempo real de manejo cuesta dinero por llamada y para ordenar candidatos alcanza.

12.3 Mapa de rutas del día (mapa_rutas.html)

Vista de solo mapa de las rutas de un día, pensada para el teléfono desde los enlaces cortos del grupo Ventas (/m/AAAA-MM-DD/d diurnas o /n nocturnas). Barra de rutas (tocar una deja solo esa), ficha de cita al tocar un punto (igual a la Vista Ventas), tiempos libres entre citas apagados por defecto (preferencia local), zoom mínimo 11 en la mediana para que una cita lejana no encuadre todo el país.

12.4 Agenda de ruta (timeline-ruta.html)

Timeline de una ruta y un día (50 px por hora, 18 horas) con arrastrar y soltar para mover citas y colocar una cita nueva desde la búsqueda por proximidad. Escribe por ruta de campo, recalcula fecha_dia y fecha_mes por día operacional, guarda metadata.ruta como texto "Ruta N" (antes quedaba el número suelto) y pasa por el portero de especiales alistados.

12.5 Supervisor de puntualidad (reporte_puntualidad.html)

mes operacional: del día 1 a las 5:00 al día 1 siguiente a las 5:00
convocatoria por técnico y fecha = la más temprana de las rutas donde aparece (ruteador.horaConvocatoria)
entrada = primer startTime de work_sessions del día operacional (sin turnos anulados)
diff = entrada - convocatoria (minutos)
categoría: sin sesión → ausencia ; diff < -10 → temprana ; diff <= 5 → en hora ; si no → atraso
puntualidad = (díasConEntrada - atrasos) / díasConEntrada   // las ausencias no cuentan como puntuales
colores: >= 90 % verde ; >= 60 % amarillo ; si no rojo
"ahorro potencial" = suma de minutos de llegada demasiado temprana

Solo días pasados. La edición de la hora de entrada por un supervisor queda en work_sessions_logs (misma bitácora que la pantalla de edición de horas). Lección: contar las ausencias como puntuales inflaba el porcentaje.

12.6 Citas sin ruta (reporte_sin_ruta.html)

Lista las citas del mes con ruta vacía o "Sin asignar" (excluye reservas: nombres con "reserv", "no tocar", "apartad" o teléfonos de relleno). Única escritura: anular el monto (solo a ₡0, solo citas sin ruta, relee la cita antes, firmado en el historial) por la función cambiarMontoCita. El botón aparece con el permiso anular_monto_cita o gerencia, resolviendo el cargo desde la ficha completa del empleado (el objeto de sesión no trae departamento ni cargo; probando en vivo ni gerencia veía el botón).

12.7 Mapa de inteligencia de clientes (mapa.html + js/mapa.js)

Buscador de direcciones por teléfono, análisis de citas por periodo (por defecto los últimos 3 meses; antes leía 8.000 citas y filtraba en el navegador): mapa de calor, rankings por provincia, cantón y distrito, Pareto (cuántos territorios hacen el 80 % de citas y monto), citas por semana y mini mapas de los 5 primeros territorios. Excluye canceladas (Ruta 20).

12.8 Zonas, atlas y ubicaciones

• Atlas (atlas.html): editor de polígonos de zonas de servicio en atlas_zonas {nombre, color, poligono[{lat,lng}], createdAt, updatedAt} (Firestore no admite arreglos anidados, se guardan objetos; se leen ambos formatos). Modo dibujo (clic agrega vértice, clic en el primero cierra) y modo edición (arrastrar vértices, insertar desde el punto medio, el vértice nuevo va en el segmento que menos perímetro agrega). Guardado en segundo plano; si falla, la zona se repinta punteada y se avisa (antes se veía igual que una guardada). Las zonas sirven para la cobertura del bot, la zona de cada ruta en el ruteador y el puntaje de Optimus.
• Clustering (zonas_clustering.html): propone zonas a partir de las citas de varios meses. Proyección local equirrectangular en metros; filtro de densidad (radio 3.000 m, al menos 5 vecinos; las aisladas se pintan aparte); k-means++ con k = 8 por defecto (2 a 20) y 20 reinicios quedándose con la menor inercia; casco convexo (cadena monótona) por cluster y centroide.
• Ubicaciones frecuentes (ubicaciones_frecuentes.html): catálogo ubicaciones_frecuentes {nombre, lat, lng, comentarios} (importable por CSV) para elegir GPS por servicio; sugiere nuevas agrupando puntos históricos de citas a 150 m.
• Mapa de ubicaciones (ubicaciones_mapa.html): citas del mes de un cliente en mapa, pendientes sugeridos por última visita, edición del reporte desde oficina y generación del reporte consolidado con clave (9.5).
• Revisión de ubicaciones (revision_ubicaciones.html): solo lectura. Encuentra citas cuyo rótulo de provincia, cantón y distrito no calza con el punto real (punto de la sucursal si existe, si no el de la cita) usando el KML de distritos. No corrige en bloque: son citas viejas, algunas ya facturadas y reportadas.
• Correcciones GPS (reporte_correcciones_gps.html): lista las coordenadas_corregidas de los técnicos con podio por empleado; permite aprobar, rechazar o borrar (y borra la foto de Storage).

12.9 Otras pantallas

• Dónde está el equipo: última posición de quien tiene turno abierto. Fuente principal dim_location (cada carga de página, en vivo); respaldo gpsStart de la sesión, dibujado punteado. Umbrales de frescura de 10 minutos y 1 hora. No usa el rastreo continuo de la app nativa porque casi nadie la tiene corriendo.
• Diagnóstico de solapes (diagnostico_overlap.html): timeline por ruta de 5:00 a 22:00 a 3 px por minuto para revisar choques.
• GPS 360: vista única del GPS de los vehículos con recorrido, paradas y su cruce con las citas del día (detalle en el capítulo de flota).

13. Resumen de procesos programados y disparadores

Todos los mensajes de WhatsApp de estos procesos se encolan en wa_equipo_salida y los despacha un agente propio conectado a los teléfonos de la empresa; la línea oficial del CRM usa la API oficial de mensajería con plantillas aprobadas.

14. Lo que no se pudo verificar

• No se encontró ningún proceso actual que escriba metadata.estado distinto de agendada; puede existir en scripts sueltos o páginas no revisadas.
• generarCronograma en detalle (cómo arma los bloques de rutas para la asignación automática y si Ruta 20 entra en el bloque nocturno) y los manejadores de soltar recursos línea por línea.
• El recálculo incremental de traslados y la llamada exacta al servicio de direcciones.
• El contenido real en la base de catálogos (servicios, productos, herramientas_alisto, canales) y de configuraciones (configuracion/rutas, alertas_config/*, wa_equipo_config/*).
• Si las funciones HTTP mencionadas están todas desplegadas (por ejemplo cambiarMontoCita; si no lo está, el respaldo del navegador solo funciona para gerencia).
• La reversión de confirmaciones vencidas de fines de octubre y sus cifras salen de la documentación del proyecto, no del código.
• Las reglas de storage.rules por carpeta (reportes/, vauchers/, recibos_efectivo/, ubicaciones/); solo se vio la validación genérica de tipo y tamaño (menos de 60 MB).
• Las colecciones ruteador, ruteador_dias, ruteador_historial y atlas_zonas no tienen reglas propias y caen en el comodín de empleados; las restricciones de ruteador (días pasados, candado, borrar bloqueos) son solo de pantalla.
• La primera lectura de encuesta.html sin sesión y la consumición real de wa_equipo_salida por el agente de WhatsApp.
• Las pruebas de reglas con el emulador no se ejecutaron: todo lo de reglas es lectura del código.

Este capítulo describe todo lo que pasa entre que un posible cliente escribe por primera vez y el servicio postventa: la línea oficial de WhatsApp (API de Meta), el tablero de vendedores ("embudo"), el reparto automático de leads, las reglas de comportamiento que el servidor hace cumplir, los vendedores virtuales (bot), los teléfonos de empresa conectados por WhatsApp Web, la cartera de clientes corporativos con su portal, y los módulos de postventa (garantías, tickets de reporte grave, satisfacción, recuperación de clientes dormidos).

Convenciones del capítulo:

• Hora: todo el servidor trabaja en hora de Costa Rica (UTC-6 fijo, sin horario de verano). Para obtener el día local se resta 6 h y se leen los campos UTC.
• Día operacional: de 5:00 a. m. a 4:59 a. m. del día siguiente. Una cita a las 2 a. m. pertenece al día anterior.
• Moneda: colones enteros, sin céntimos.
• Teléfono: llave universal del cliente. Se normaliza a 506 + 8 dígitos (solo dígitos; si viene con 00 se quitan; si tiene 8 dígitos se antepone 506). Es el id del documento de conversación.
• Ruta 20: la "ruta" de las citas canceladas. Toda métrica de venta excluye Ruta 20 y monto 0.
• Ficticia (metadata.es_ficticio): venta cerrada en ruta por un técnico; cuenta como dinero, no como visita.
• Gerencia: un conjunto de usuarios con permiso reportes_gerenciales. Los módulos nuevos tienen clave de permiso propia que hereda de esa.
• Usuario: el username del empleado sale del correo corporativo sin el dominio. Los bots tienen username terminado en .bot.
• Toda función HTTP valida el idToken de Firebase y exige que el empleado tenga ficha (empleados_uid_lookup/{uid}); devuelve username, permisos con herencia y si es gerencia.

Mapa del área

Ciclo de vida de un lead

                     ┌──────────────────────────────────────────────────────────────┐
 1. LLEGA            │ Cliente escribe a la línea oficial (o Messenger, o desde el    │
                     │ sitio con un código W/G en el texto)                           │
                     └──────────────────────────────────────────────────────────────┘
   whatsappWebhook crea whatsapp_messages/{wamid} (direction=inbound, status)
   y crea/actualiza whatsapp_conversations/{tel}:
     phone, name, whatsappName, lastMessage, lastMessageAt, lastMessageDirection="inbound",
     lastInboundAt, unreadCount+1, windowExpires (+24 h, o +72 h si vino de anuncio),
     source, subSource, sourceAt, clienteAlEntrar   ← primer toque, CONGELADO
     esCliente/totalFacturado (de analitica_clientes), boardCol="__sin_asignar__"
     (si es aspirante a empleo: assignedTo=reclutamiento, boardCol="__empleo__")
     (si vino de anuncio: evento "Contact" a la API de conversiones)
                                   │
                                   ▼
 2. BOT (opcional)   botVentasOnInbound: si el lead está en modo bot, assignedTo="<bot>.bot",
                     el bot contesta; al pedir humano o al agendar → handoff (assignedTo humano)
                                   │
                                   ▼
 3. SE ASIGNA        embudo detecta lead sin dueño, espera 6 s, llama repartirLeads:
                     assignedTo=<vendedor>, assignedAt, boardCol=<vendedor>, embudoVendedor=""
                     trigger estamparPrimerAsignado → primerAsignado, primerAsignadoAt,
                     primerAsignadoFuente (no cambia nunca más)
                     libro mayor de 72 h: buckets[vendedor][hora]++
                                   │
                                   ▼
 4. SE RESPONDE      whatsappSend (texto dentro de 24 h, plantilla fuera):
                     guardas: autor del token, 60/min, política de promesas,
                     aceptación de política, llamadas vencidas, opt-out (solo plantillas)
                     → whatsapp_messages (status "sent" → "delivered" → "read" por webhook)
                     → si el dueño no está en turno y el cliente fue el último: assignedTo=autor,
                       reasignadoTurno{de,a,at,rolDe,rolA}
                     → Google/Directo/Sitio: llamGInicio, llamGVence = +3 h, llamGResp
                     → lastMessageDirection="outbound", lastMessageAt
                     tiempos_respuesta/{día} mide minutos hasta esta respuesta
                                   │
                                   ▼
 5. LLAMADA          vendedor llama (WhatsApp o celular) y la documenta:
                     llamadas_documentadas/{id}, llamDocHecha, llamDocAt, llamDocN
                     si era obligatoria: llamGHecha, llamGResultado
                     sin documentar > 2 h del vencimiento → whatsappSend devuelve 423
                                   │
                                   ▼
 6. SE COTIZA        plantilla de cotización (templateName en el mensaje) y/o
                     embudoVendedor="__cotizaciones__" (columna final), followUpAt
                                   │
                                   ▼
 7. SE AGENDA        se crea citas/{id} (metadata.vendedores, metadata.monto, telefono_normalizado,
 (COMPRA)            metadata.canal). Triggers:
                     stampClienteOnCita → analitica_clientes{total_facturado,total_citas},
                        conversación esCliente=true, totalFacturado, boardCol="__clientes__"
                     llamGCompraOnCita → llamGCompro, llamGComproAt
                     ventasAutoEnviar → imagen de la venta al grupo de ventas (3 min)
                     ventasSync (6 h) → ventas_atribuidas/{citaId} + evento Purchase
                     portalPushAlAgendar (si es cliente de cartera) → visita en el portal
                                   │
             ┌─────────────────────┴──────────────────────┐
             ▼                                            ▼
 8a. POSTVENTA                                  8b. SE ENFRÍA
   reporte del técnico → portal, tickets_rojo     sin mensajes > 3 días:
   (si condición roja), satisfaccion_citas,         plantilla de recontacto ("raspa"):
   garantias (si reclama), whatsapp_coordinacion     embudoVendedor = __raspa1__ → __raspa2__
   a los 183 días sin volver →                       → __raspa_def__ → __raspa_no_mas__
   recuperador_cartera (estado disponible)          si otro vendedor lo revive: reasignarLeadFrio
                                                     (assignedTo = quien raspó)
                                                    archived=true / __basurero__ / __no_compro__
                                                    opt-out (botón "No deseo más mensajes"):
                                                     optOut=true → no más plantillas

Qué campo decide en qué columna del tablero aparece el lead (boardCol, desnormalizado y recalculado por el servidor):

columnaDelTablero(c):
  si c.embudoVendedor es una columna final → esa
  si (c.esCliente o c.esClienteManual) y no c.fueraDeClientes:
       "__recuperador__" si c.recuperadorEnviado, si no "__clientes__"
  si no hay c.assignedTo → "__sin_asignar__"
  si no → c.assignedTo

Columnas finales (orden del tablero): Empleo, Empleo prospecto, Empleo descartado, Rural, Recuperador 3000, Garantías, Cotizaciones, Raspa 1, Raspa 2, Raspa definitivo, No raspar más, Leadsales, Recuperador (categoría), Basurero, No compró. La lista de claves finales tiene que ser idéntica en servidor y navegador: cuando al servidor le faltaron seis claves, el trigger reescribía la columna de esos leads.

WhatsApp oficial: arquitectura

• Una sola línea oficial de WhatsApp Business (Cloud API de Meta). El webhook entra por una Cloud Function HTTP. Los envíos salen por otra Cloud Function que llama a Graph.
• El estado vive en Firestore. La colección whatsapp_conversations tiene un documento por teléfono (id = teléfono normalizado). La colección whatsapp_messages tiene un documento por mensaje.
• Messenger reutiliza las mismas colecciones con id fb_<psid> (y está previsto ig_ para Instagram). Un helper esIdMeta(id) desvía esos casos. Todo código nuevo que use el id de conversación como teléfono tiene que respetar ese desvío.
• Versiones de Graph en uso: media y mensajes v23, marcar como leído v21, llamadas y permisos v24, plantillas v22. Al reconstruir conviene unificarlas.
• Secretos usados: token de acceso de WhatsApp, app secret (para la firma), verify token, id del número de teléfono, token y id de la página de Meta (Messenger) y la llave del proveedor del modelo de lenguaje. Todos son secretos de Functions. El id de la cuenta WABA está fijo en el código y el que mande el cliente se ignora.
• Autenticación de endpoints: verifyEmpleado(req) valida el idToken de Firebase y exige que exista la ficha empleados_uid_lookup/{uid}. Devuelve username, permisos (con herencia) y esGerencia. El username sale del correo de la cuenta. Los permisos se piden con exigirPermiso(authUser, [claves]).
• CORS restringido a una lista de orígenes (CORS_OPTIONS).

Normalización de teléfono (normalizePhone)

p = solo dígitos
si empieza con "00": quitar los dos ceros
si tiene 8 dígitos: anteponer el código de país 506

Limitación conocida: un número extranjero de 8 dígitos también recibe el 506. Sin quitar el 00, un mismo número pegado como 00506... abría una conversación paralela. Para el cruce con clientes existe otra llave, shared/telefono.normalizar.

WhatsApp oficial: modelo de datos

whatsapp_conversations/{telefono}

boardColFor(c) tiene que coincidir exactamente con la función del tablero en el navegador:

si embudoVendedor está en BOARD_FINAL_KEYS: devolver embudoVendedor
si (esCliente o esClienteManual) y no fueraDeClientes:
    devolver "__recuperador__" si recuperadorEnviado, si no "__clientes__"
si no hay assignedTo: devolver "__sin_asignar__"
si no: devolver assignedTo

Las claves finales son: empleo y sus dos subcategorías (prospecto y descartado), rural, recuperador, garantías, cotizaciones, raspa1, raspa2, raspa_def, raspa_no_mas, leadsales, cat_recuperador, basurero y no_compro. Si a la lista del servidor le falta una clave, el trigger le reescribe la columna al lead (ya pasó con seis claves).

whatsapp_messages/{id}

• Id del documento: el wamid en los entrantes (eso da idempotencia). Un id automático en los salientes de whatsappSend. El wamid en el pedido de permiso. call_<callId> en el rastro de llamada. El mid en Messenger.
• Campos comunes: conversationPhone, from, to, type, body, mediaUrl, mediaId, direction, status, timestamp, wamid, contactName, sentBy (solo salientes), replyTo, fileName, mimeType, voice, latitude, longitude, locationName, locationAddress, sharedContacts, buttonPayload, interactiveId, interactiveType, interactiveDescription, callPermission, reactedMessageId, order, systemType, rawPayload (500 caracteres), forwarded y frequentlyForwarded.
• Referral de anuncio: referralSource, referralSourceUrl, referralHeadline, referralBody, referralAdId, referralSourceId, referralMediaType, referralMediaUrl, referralThumbnailUrl.
• Atribución: googleAdsRef, webRef.
• Plantillas: templateName, templateUrlParam.
• Fallos: failReason, failCode, failDetails.
• Media: mediaPendiente, mediaError, mediaIntentoAt, mediaBarridos, mediaAbandonadaAt.
• Borrado lógico: deleted, deletedAt, deletedBy.
• Llamadas: callId, callStatus, callAnsweredBy, callDuration.
• Permiso: permisoMotivo, permisoVia.
• Otros: bot (true en mensajes del bot) y canal: "messenger".

Otras colecciones del núcleo

whatsappWebhook (HTTP)

Configuración: máximo 10 instancias, 120 s, 512 MiB.

GET (verificación): si hub.mode == "subscribe" y hub.verify_token coincide con el secreto, devuelve hub.challenge. Si no, 403.

POST:

1. Valida la firma x-hub-signature-256: HMAC-SHA256 del raw body con el app secret, comparado con timingSafeEqual y largos iguales. Si falla, 403.
2. Si body.object !== "whatsapp_business_account", responde 200 y sale.
3. El 200 va después de guardar. En Functions v2 la instancia puede quedarse sin CPU al responder, y Meta no reintenta un 200, así que antes los mensajes se perdían en silencio. Ante cualquier excepción responde 500 para que Meta reintente. Todo el procesamiento es idempotente.
4. Las escrituras van en un batch que se confirma cada 400 operaciones.
5. sourceDecidido es un Map por teléfono dentro del mismo POST. Sin él, un anuncio y un texto en el mismo lote dejaban el segundo pisando el canal del primero, porque la conversación se lee por mensaje pero se escribe al final.

value.statuses (estados de entrega)

• Busca el mensaje con where("wamid","==",id).limit(1).
• El rango es sent=1, delivered=2, read=3, failed=0. Solo actualiza si el nuevo rango es mayor o si el estado es failed. Así un delivered tardío no pisa un read.
• En failed guarda failReason (title o message), failCode y failDetails (error_data.details).
• Si el estado no encuentra el mensaje, se descarta. Por eso whatsappSend crea el documento del mensaje apenas responde Meta (ver 4.6).
• Si viene status.conversation y el origen no es business_initiated, actualiza windowExpires (de expiration_timestamp) y windowOrigin, solo si la fecha nueva es mayor. Guarda conversationId.

value.messages (entrantes)

Para cada mensaje:

a) Cuerpo según el tipo:

• text: text.body.
• image, video, audio, document, sticker: caption o [tipo], más mediaId. Documento agrega fileName y mimeType. Audio agrega voice.
• location: 📍 nombre, dirección o las coordenadas, más lat, lng, nombre y dirección.
• contacts: 👤 Nombre, tel, más sharedContacts[].
• button: button.text, más buttonPayload.
• interactive: button_reply y list_reply (id y descripción). call_permission_reply: el cuerpo dice "Autorizó llamadas de WhatsApp", "Autorizó llamadas por 7 días" o "No autorizó". Guarda callPermission (permanente, temporal o rechazado) y llama a waPermisoLlamada.guardarRespuesta. Antes caía como [interactivo] y el permiso nunca se guardaba.
• reaction: el emoji y reactedMessageId.
• order: "Pedido recibido".
• system: system.body y systemType.
• otro tipo: [tipo] más rawPayload.

b) Referral (click-to-WhatsApp): campos referral*. ctwa_clid se guarda en referralAdId.

c) Context: replyTo, forwarded, frequentlyForwarded.

d) Marcadores del sitio: la regex Ref:? G-[a-z0-9]{3,10} llena googleAdsRef (clic pagado de Google; Google no manda referral, este marcador es la señal). La regex de web-leads Ref: W-xxxx llena webRef (visita del sitio).

e) Idempotencia: msgRef = whatsapp_messages/{wamid}. Si ya existe, no se reescribe, porque borraría el mediaUrl que puso la descarga, y tampoco se recuenta.

f) Conversación:

• Siempre escribe whatsappName, phone y updatedAt.
• Para todo lo que no sea reacción: lastMessage, lastMessageAt, lastMessageDirection: "inbound" y lastInboundAt se escriben solo si el mensaje es nuevo y su timestamp ≥ el lastMessageAt previo. Un reintento o un webhook fuera de orden no puede rebobinar a inbound, porque la reasignación por turno lee ese campo y otro vendedor se llevaba el lead.
• unreadCount += 1 solo la primera vez que se guarda el mensaje (increment no es idempotente).
• archived: false si estaba archivada. Archivar significa "ya lo atendí", no "no me escriba más".
• Ventana: timestamp + 72 h si vino de anuncio, si no + 24 h. Se toma el máximo contra la ventana guardada (cada entrante la reinicia, pero no se acorta una de 72 h). Las reacciones no tocan la ventana.

g) Alta de conversación (lead nuevo): si el documento no existe:

• name = contactName.
• totalFacturado y esCliente se leen de analitica_clientes/{tel}, para que un cliente que regresa caiga al instante en Clientes.
• boardCol = boardColFor(convUpdate), que en un lead nuevo da __sin_asignar__.
• El webhook no asigna vendedor. La asignación la hace el reparto de servidor (wa-asignacion.js: modos por ratio de 72 h, baraja y nivelación) o el bot. La excepción es empleo (ver i).

h) Canal, primer toque congelado: el canal es asignable solo si no fue decidido en el lote y el source actual es vacío o saliente. Un saliente (contacto que iniciamos nosotros) sí se promueve al canal real cuando el cliente escribe.

• Con referral: source = "ad", sourceAt, clienteAlEntrar, metaPlataforma (instagram.com, fb.me o facebook.com, wa.me u otro). Los campos ad* se actualizan siempre. Si campaña, titular o cuerpo calzan con la regex de empleo: source = subSource = "empleo". Hasta octubre 2026 esos aspirantes entraban como anuncio e inflaban los leads de Meta.
• CAPI "Contact": solo en el primer guardado. event_id = contact_<tel>_<wamid>. user_data con hash SHA-256 de ph (con 506), external_id, país, nombre y apellido, más ctwa_clid. custom_data: moneda CRC, value: 0, content_category y campaign_name.
• Sin referral, en este orden: 1. googleAdsRef presente: youtube si la visita registrada tiene utm de YouTube, si no google_ads. subSource anuncio_video_youtube o clic_pagado_google. Recupera gclid y wbraid de gads_clicks/{ref} y copia los campos de visita. 2. Visita W con gclid, wbraid o gbraid: igual, con googleAdsRef = "G-" + resto del W. 3. Visita con msclkid: bing / clic_pagado_bing. 4. Visita registrada sin click id: sitio_web, con subSource = webSubcanal. 5. Marcador W sin visita registrada (bloqueador o red): sitio_web / sitio_sin_registro. 6. Clasificación del primer mensaje (clasificarPrimerMensaje): botón de Google, empleo, Instagram, Facebook, Maps, QR, textos de anuncio. 7. "Vengo del sitio web": sitio_web / boton_sitio. 8. Si nada calza: directo, más directoTipo (precargada, saludo, no_texto o propio).
• Comején o termita desde el sitio: webSeguimientoPendiente: true y webLeadAt, para avisar a las 48 y 72 h.
• Si el canal no es asignable pero trae W: solo webRefUltimo.

i) Empleo: si source == "empleo", el canal es asignable y no es cliente: assignedTo = un usuario fijo de reclutamiento, assignedAt, embudoVendedor = boardCol = "__empleo__", esClienteManual: false, fueraDeClientes: true. Sin esto caía en Sin asignar y el reparto se lo daba a un vendedor.

j) batch.set(convRef, convUpdate, {merge: true}).

value.errors

Solo se registran en el log.

value.calls (llamadas de WhatsApp)

• Documento whatsapp_calls/{callId}.
• ¿Es saliente? Sí si el documento previo dice direction: outbound, o si call.direction == BUSINESS_INITIATED, o si el evento es connect con un SDP de respuesta: contiene a=setup:passive o a=setup:active y no contiene actpass. El SDP de un cliente que llama es una oferta (actpass). En una saliente el cliente es to, no from.
• Saliente, y llega accept o connect con SDP: status: active, sdpAnswer, answeredAt. Sin guardar sdpAnswer, el navegador se quedaba en "Llamando..." para siempre. Registra el rastro en el chat.
• Saliente y reject: status: rejected, endedAt.
• connect entrante (si es saliente sin SDP, se ignora para que al vendedor no le suene su propia llamada): crea el documento con from, contactName, direction: inbound, status: ringing, sdpOffer, timestamp. Deja el rastro "ringing" en el chat y llama a marcarEntrante (la llamada del cliente abre 24 h para devolverla).
• terminate o disconnected:
• Si ya está en missed, rejected o no_answer, no hace nada (un reintento convertiría una perdida en "ended").
• Estado final: ringing pasa a missed; calling pasa a no_answer; rejected se queda igual; si nunca hubo documento o estado previo, no_answer (saliente) o missed (entrante); en otro caso, ended.
• Duración = fin − answeredAt, solo en ended.
• Si el vendedor ya colgó desde el navegador (ended), el documento no se toca pero el rastro del chat sí se cierra.
• Al final llama a documentarLlamadaWhatsapp.
• Otros eventos: status = event.

registrarLlamadaEnChat

• Escribe un mensaje con id fijo call_<callId>, type: "call", status: delivered, callStatus y su texto ("Llamada perdida", "Llamada contestada por X · m:ss", "Llamada saliente sin respuesta", etc.).
• En la conversación: lastMessage = "📞 ...", lastCallAt, lastCallStatus, lastCallId.
• Perdida entrante: unreadCount +1, llamadasPerdidas +1, llamadaPendiente: true. Una ended la deja en false.
• Si alguien llama sin haber escrito nunca, crea el contacto: source: directo, sourceDetalle: llamada, sourceAt, clienteAlEntrar, boardCol.
• Si falla, no tumba el webhook.

documentarLlamadaWhatsapp

Se documenta si hubo conversación (ended con duración > 0) o si fue una saliente sin respuesta (no_answer o rejected). Una entrante perdida no cuenta.

• Id fijo llamadas_documentadas/wa_<callId>; si ya existe, no hace nada.
• Campos: tipo: whatsapp, resultado (vacío si hubo conversación, para que el vendedor lo elija; no_contesto si no), prueba: "Registro de la llamada de WhatsApp (Meta)", inicio, contestada y fin, y google si tenía llamada obligatoria pendiente.
• En la conversación: llamDocHecha, llamDocAt, llamDocPor, llamDocN +1. Si tenía la obligatoria pendiente también llamGHecha, llamGAt, llamGPor, llamGSeg, llamGResultado (o pendiente) y llamGFuente: whatsapp.
• La llamada por WhatsApp es la prueba: no hace falta pantallazo.

descargarMediaWA (trigger al crear whatsapp_messages/{msgId})

Configuración: retry: true, 120 s, 512 MiB.

1. Si el mensaje no tiene mediaId, sale (el 95 % de los mensajes no trae media).
2. Relee el documento. Con retry el snapshot que llega es siempre el de la creación. Si ya tiene mediaUrl, sale, para no subir el archivo dos veces.
3. bajarMediaWA: - GET a Graph /{mediaId} para obtener url y mime_type. - GET a esa url con Bearer. - Audio ogg o webm se transcodifica a MP3 con ffmpeg (libmp3lame, -q:a 4, 30 s). Si falla, se guarda el original: el transcode es una mejora, no un requisito. - Sube a Storage en la ruta determinista whatsapp_media/{tel}/{docId}_{mediaId}.{ext} con un token de descarga. Reintentar sobrescribe el mismo objeto en vez de dejar huérfanos.
4. Errores: red, 429, 5xx y fallas de Storage son transitorios y se relanzan para que Firebase reintente. Los 4xx son definitivos (media vencida o sin permiso; reintentarlos sería un bucle de días). - Todo fallo anota mediaPendiente: true, mediaError y mediaIntentoAt. - Si el evento tiene más de 6 h (MEDIA_HORAS_REINTENTO), ya no se relanza. - El éxito borra mediaPendiente y mediaError.

Barrido barrerMediaPendiente (dentro de la corrida nocturna de atributos):

• where mediaPendiente == true limit 50. Es una igualdad simple, no necesita índice.
• Trabaja con presupuesto de tiempo (máximo 120 s).
• Después de 5 barridos (mediaBarridos) se abandona: mediaPendiente: false y mediaAbandonadaAt.
• Meta conserva el archivo 30 días, así que una pasada por noche alcanza.

whatsappSend (HTTP POST)

Configuración: 10 instancias, 180 s, 1 GiB.

Body: to, type, text, template{name, language, components}, templateBody, templateUrlParam, mediaUrl, mediaType, caption, fileName, sentBy, replyToWamid, emoji, reactMessageId, lat/lng, nombre y dirección de ubicación, contactName, contactPhone.

Guardas en orden exacto

1. Método distinto de POST: 405.
2. verifyEmpleado falla: 401.
3. Sin to: 400 "Destinatario requerido".
4. Autor. Sale del token, no del body. Si sentBy es distinto del usuario del token, solo se acepta cuando quien llama es gerencia (las pantallas de campaña eligen a quién abonar el contacto). Si no, se ignora y queda en el log. Antes cualquiera firmaba a nombre de otro, y los envíos masivos salían todos a nombre de una sola persona.
5. Límite: 60 mensajes por minuto por uid, en transacción sobre _rate_limits/wa_{uid}_{minuto} (con expira a +24 h). Si se pasa: 429.
6. El phone se normaliza, salvo que esIdMeta(to) (Messenger), donde se deja tal cual.
7. Si type !== "reaction": - a. Política de promesas sobre textosDelEnvio: text, caption, contactName, locationName, locationAddress, templateBody y cada parameters[].text de los componentes de la plantilla. Vale para todos, gerencia incluida. Si bloquea: registra en promesas_bloqueadas y responde 422 codigo: "promesa_prohibida" con AVISO, motivos y palabras. - b. Si el autor es de Ventas y no aceptó la versión vigente de la política: 428 politica_pendiente. - c. Si es de Ventas y tiene llamadas obligatorias vencidas hace más de 2 h, salvo cuando escribe a uno de esos mismos leads: 423 llamadas_vencidas con la lista leads. Si Firestore falla, no se bloquea.
8. Con mediaUrl, el host tiene que ser el de Firebase Storage. Si no: 400 "mediaUrl no permitida".
9. Desvío a Messenger (esIdMeta): messengerFns.enviar(...). Escribe el o los mensajes con canal: "messenger" (un adjunto con texto son dos mensajes, mid y midTexto), aplica tomarLeadPorTurno y actualiza last*. Si el error contiene "outside", "window" o "24", responde que la ventana de 24 h de Messenger está cerrada. Messenger no pasa por la guarda de opt-out ni tiene plantillas, reacciones, ubicación ni contactos.
10. Plantilla y opt-out: si type == template y la conversación tiene optOut === true: 409 "El cliente pidió no recibir más mensajes". El opt-out solo frena plantillas (que son lo que Meta cuenta como spam). El texto libre dentro de la ventana no se frena aquí.

El servidor no verifica la ventana de 24 h para texto libre. Meta rechaza con 131047 y ese error se traduce.

Armado del payload según el tipo

• reaction: {message_id, emoji}.
• template: {name, language: {code: language || "es"}, components}.
• audio (siempre transcodifica): 1. Descarga de Storage. 2. ffmpeg a OGG/Opus: 24 kbps, mono, 48 kHz, application voip, vbr, 30 s. 3. Si el resultado pesa menos de 100 bytes, se trata como corrupto: 502. 4. Sube a /{phoneId}/media con multipart audio/ogg; codecs=opus. 5. Si no vuelve id, plan B: AAC/M4A a 64 kbps, 44,1 kHz, subido como audio/mp4. Pierde el formato de nota de voz, pero mejor un audio básico que nada. 6. Espera 3 s (propagación en el CDN de Meta). 7. Payload {id, voice: true}, sin voice si fue M4A. voice:true es lo que da nota de voz nativa (con descarga automática y forma de onda). Sin eso, iOS no reproduce OGG como archivo genérico.
• video: si la extensión no es mp4, 3gp o 3gpp, transcodifica (libx264, preset fast, crf 28, AAC 96k, +faststart, 90 s), sube y espera 3 s. Si ya es mp4, va por link.
• image: siempre intenta subir a Meta y mandar por id. Mandar por link falla con "Downloading media from weblink failed with http code 500" en fotos grandes o con hipos de Storage. Convierte webp, bmp, tif y svg, o cualquier imagen mayor de 4,5 MB (WhatsApp acepta hasta 5 MB), a JPEG de ancho máximo 1600 px con q:v 3. Espera 1 s. Si algo falla, cae a link.
• document: igual que imagen. Si el MIME viene vacío u octet-stream y el nombre tiene ".pdf", usa application/pdf. Lleva filename.
• location y contacts: payload directo (el teléfono del contacto con tipo CELL).
• Cualquier otro tipo: text: {body}.
• Si viene replyToWamid y no es reacción: context.message_id.

Envío a Graph /{phoneId}/messages

• Error: si era audio con voice:true, reintenta una vez sin voice. Si no, 502 con errorMetaEnvio:

• Una reacción que sale bien responde {ok, wamid} sin escribir nada en Firestore.

Texto que queda guardado (body)

• template: templateBody (el texto real con las variables resueltas, que manda la pantalla) o [Plantilla: nombre].
• location: 📍 nombre.
• contacts: 👤 nombre.
• document: 📄 fileName.
• otros: text, caption o [tipo].

Persistencia en este orden

1. El mensaje se crea de inmediato con status: "sent", sentBy, templateName, templateUrlParam, etc. El estado failed o delivered del webhook puede llegar antes de que terminen los pasos siguientes. Si no encuentra el wamid lo descarta, y el mensaje quedaba con el tick gris para siempre y sin mostrar el error.
2. tomarLeadPorTurno(db, phone, autor) (ver 5). Si falla, solo queda un warning.
3. arrancarLlamadaGoogle(db, phone, autor, now) (ver 6).
4. Conversación: lastMessage, lastMessageAt, lastMessageDirection: "outbound", updatedAt. Va después de la reasignación, que necesita ver inbound.
5. Respuesta: {ok, wamid, messageId, tomado?, tomadoDe?}.

Reasignación por turno al contestar (tomarLeadPorTurno)

Regla: si el cliente fue el último en escribir y el dueño del lead no está en turno, el vendedor de Ventas en turno que le contesta se queda con el lead, sin aprobación. Gana el primero que envía. El lead no vuelve solo al dueño anterior: lo recupera contestando, como cualquiera.

No se mueve cuando:

• el autor está vacío o es *.bot;
• la conversación no existe, no tiene dueño, el dueño es el mismo autor o el dueño es *.bot;
• lastMessageDirection !== "inbound";
• es cliente (esCliente, esClienteManual o totalFacturado > 0);
• el canal es empleo o proveedor;
• el autor no es de Ventas (empleados.departamento contiene "venta" y no está inactivo; se cachea 30 min por username);
• el autor no está en turno, o el dueño sí lo está.

Turnos (wa-nivelacion.js): roles_ventas/{lunes CR} define temprano, nocturno, domingo y sábado. Quien no tiene rol es diurno.

Entre las 12 y las 17 h están todos en turno, así que en esa franja no hay traspasos.

Transacción: relee y verifica que assignedTo siga siendo el mismo y que el último siga siendo inbound. Escribe assignedTo: autor, fueraDeClientes: true, reasignadoTurno {de, a, at, rolDe, rolA}, embudoVendedor: "" (salvo que esté en una columna final) y recalcula boardCol. Crea un registro en reasignaciones_turno. No toca assignedAt ni el saldo del reparto.

Llamada obligatoria a leads nuevos (reloj de 3 h y bloqueo)

Base del dato: cerca del 62 al 65 % de las ventas de Google, Directo y Sitio web cierra en las 3 h que siguen a la primera respuesta. Meta anda en 43 % y no entra en la regla.

arrancarLlamadaGoogle, dentro de whatsappSend

Arranca el reloj solo si se cumple todo esto:

• el autor no está vacío, no es *.bot y no es sistema.web;
• la conversación existe y source es google_ads, directo o sitio_web (YouTube no entra);
• clienteAlEntrar !== true;
• todavía no hay llamGVence;
• sourceAt ≥ 17-oct-2026 00:00 hora de Costa Rica;
• el autor es de Ventas.

En transacción (si ya hay llamGVence, no hace nada) escribe llamGInicio = now, llamGVence = now + 3 h y llamGResp = autor. Los campos llevan el prefijo "G" por historia: la regla empezó solo con Google y Directo y Sitio web se sumaron el mismo día. Las reglas de Firestore reservan estos campos al servidor o a gerencia, y llamGHecha y llamGExento solo los puede escribir quien firma con su propio username.

Compra (llamGCompraOnCita, trigger sobre citas)

Marca la compra cuando se cumple todo esto:

• la cita tiene monto > 0 y no está en Ruta 20 (Ruta 20 = cancelada);
• la conversación tiene llamGVence y todavía no tiene llamGCompro;
• la cita se creó como mucho 1 h antes de sourceAt (si es más vieja, es de antes de que el cliente escribiera);
• la versión anterior de la cita no calificaba ya igual (con monto, sin Ruta 20 y el mismo teléfono); si calificaba, esa escritura ya marcó la compra.

Si todo calza, estampa llamGCompro y llamGComproAt.

Cierre de la llamada

Se cierra de tres formas:

• desde el formulario del embudo, con llamGHecha y llamGResultado. Los resultados son compro, le_interesa, no_contesto, no_interesa y otro_momento. Pide pantallazo obligatorio, minutos y segundos y nota opcional;
• con "No es cliente": llamGExento más una justificación de 15 caracteres o más;
• con la llamada de WhatsApp documentada sola (sección 2.6).

El responsable es llamAsignada || assignedTo. Basurero y Empleo quedan exentos.

Bloqueo en el servidor (llamGBloqueo)

• llamGPendientes: una sola consulta para todos, cacheada 60 s. Busca llamGVence entre max(30-oct-2026 00:00 CR, ahora − 7 días) y ahora − 2 h.
• Excluye las que tienen llamGHecha, llamGExento o llamGCompro, las de clientes, las del basurero y las de empleo.
• Si el vendedor aparece en la lista, la vuelve a leer en fresco (para no frenar a quien acaba de registrar).
• Si debe alguna y el destino no es uno de sus leads pendientes, whatsappSend responde 423.
• En el embudo la presión se suavizó: el aviso sale como mucho una vez por hora y siempre se puede cerrar. El bloqueo de 2 h del servidor sigue activo.

Política de promesas (functions/politica-promesas.js)

• Una regla, dos copias idénticas. La de public/js/politica-promesas.js avisa mientras se escribe. La de functions/ es la que decide. Se edita la de public y se copia encima con cp, sin tocarla a mano.
• VERSION (hoy 2026-10-18). Cambiarla obliga a todos los vendedores a aceptar de nuevo en politica_promesas/{username} (campo version). La aceptación se cachea 10 min. Si Firestore falla, se considera aceptada (no se frena la venta; el texto igual se revisa).
• APROBADAS: cuatro respuestas aprobadas (¿tienen garantía?, una sola visita, dos aplicaciones, por qué nosotros). Solo pasan si el texto es idéntico.
• Normalización:
• sin tildes y en minúsculas;
• el emoji 💯 se traduce a "100 %";
• letras sueltas separadas por espacio, punto, guion, asterisco o coma se juntan ("g a r a n t i a");
• números que hacen de letras dentro de una palabra se cambian (0→o, 1→i, 3→e, 4→a, @→a, 5→s, 7→t, $→s);
• letras repetidas se reducen a una ("erradicar" pasa a "eradicar");
• todo lo demás se pasa a espacios.
• Se ignoran los enlaces propios del sitio (la página de garantía y el formulario del caso) antes de revisar.
• Detección: 1. Subcadenas: garant, garnti, grantia, grantiz, guarant, warant (motivo garantía); eradic, eradik, eraddic (motivo erradicación). También se buscan sobre el texto sin espacios, para atrapar "ga-ran-tía". 2. Distancia de Levenshtein contra la familia de palabras: 1 letra para palabras de 6 o 7 letras, 2 para las de 8 a 16. Se excluyen falsos positivos como predicar y radicar. 3. Frases: eliminación total o por completo; eliminar "todas las cucarachas" (y otras plagas); exterminio total; "acabar con... para siempre"; "desaparecen por completo"; "control, resultado o eficacia total, asegurado o garantizado"; "100 %" o "cien por ciento", salvo cuando sigue natural, seguro para, biodegradable u orgánico; "para siempre" o "de por vida"; "solución definitiva"; "nunca más vuelven"; "seguro que se van"; "libre de plagas" o "cero cucarachas"; "le aseguramos que no vuelven"; "resultados asegurados".
• Salida: {ok, motivos[], palabras[]}.
• Dónde se aplica: whatsappSend (422), crearPlantillaWA (texto, botones y ejemplos del cuerpo y del encabezado) y wa-envio.enviar (el bot). El audio no se revisa.
• Los intentos bloqueados van a promesas_bloqueadas: usuario, autor, phone, origen, tipo, plantilla, motivos, palabras, texto (2000 caracteres) y at.

WhatsApp oficial: endpoints menores (leído, borrado, asistente, evaluación, atribución)

whatsappMarkRead

• Body {phone, wamid}.
• Messenger: solo pone unreadCount: 0.
• Con wamid: POST {status: "read", message_id} a Graph (el cliente ve el doble check azul).
• Con phone: unreadCount: 0.

whatsappDeleteMessage

• Es un borrado lógico y solo en el CRM. La Cloud API no permite borrar un mensaje ya enviado: el intento anterior con status:"deleted" siempre devolvía el error 100.
• Pide wamid y, si viene, messageDocId (validado con ^[A-Za-z0-9_-]{1,64}$).
• Solo pueden borrar el autor (sentBy == username) o gerencia: un mensaje con una promesa es evidencia.
• Escribe deleted, deletedAt y deletedBy, más whatsapp_activity con action: "mensaje_eliminado". Responde metaDeleted: false.

whatsappAssistant

• Body {messages[], contactName, vendedorName}. Usa solo el primer nombre del vendedor.
• Arma la conversación como líneas "Vendedor:" y "Cliente:". Modelo liviano, 500 tokens.
• El prompt de sistema trae formato, saludo, flujo de venta, precios de referencia, objeciones, seguimientos y prohibiciones. Incluye la política de promesas (nunca garantía; dos aplicaciones si no fumigó en 6 meses) y la prohibición de pedir ubicación GPS.
• Si la IA está sin saldo: 503 ia_sin_saldo y aviso a gerencia (iaSaldo).
• Devuelve {suggestion}.

whatsappEvaluate

• Body {employeeName, conversations[]}.
• Toma como mucho 15 conversaciones y los últimos 30 mensajes de cada una. El nombre se sanea contra inyección de prompt.
• Siete criterios. Devuelve un JSON con score (1 a 10), fortalezas, oportunidades, erroresOrtografia, preguntasSinResponder, ejemplosMejora y resumen. Modelo liviano, 1500 tokens.
• Si el JSON no se puede leer, devuelve un objeto vacío con el texto en resumen.

whatsappAtribucion

• Body {messages[], vendedores[≥2]}. Usa los últimos 60 mensajes saneados.
• Pesos: agenda y cierre 30 %, persuasión y paquetes 25 %, calidad de información 20 %, seguimiento 15 %, tiempo de respuesta 10 %.
• Niveles permitidos: 100/0, 75/25, 50/50 y los inversos. El saludo genérico vale 0.
• La sugerencia se descarta (422 atribucion_invalida) si los dos usernames no están en la lista, son iguales o los porcentajes no suman 100.

Llamadas salientes y entrantes

whatsappCallAction

• Body {action, callId, sdp, sdpType, to}.
• connect (llamada saliente): 1. Lee el permiso local (waPermisoLlamada.leer). Si dice que no, sincroniza con Meta. Si sigue sin permiso: 403 sin_permiso_llamada. 2. Tope de 20 llamadas salientes por usuario por día en _rate_limits/call_{uid}_{día CR}. Si se pasa: 429 tope_llamadas. La cuota de Meta es de 100 por 24 h para todo el número. 3. POST /{phoneId}/calls con {type: voice, action: connect, session: {sdp, sdp_type: offer}}. 4. Si sale bien, crea whatsapp_calls/{id} con direction: outbound, status: calling, sdpOffer y calledBy.
• Otras acciones (pre_accept, accept, terminate): {call_id, action, session con sdp_type answer}.
• El error 138003 se traduce a "ese número todavía tiene una llamada abierta".

Navegador (public/wa-call.js)

• Usa WebRTC con STUN públicos.
• Entrantes: escucha whatsapp_calls con status == "ringing", ordenadas por timestamp desc, limit(5) (con limit(1) la segunda llamada nunca aparecía). Solo suena para empleados de Ventas activos. Una llamada sirve si es inbound, no fue silenciada localmente y tiene menos de 45 s.
• Si el que llama es lead del vendedor que mira la pantalla, el aviso pasa a modo urgente con otro timbre. Tampoco reemplaza el popup visible por una llamada más nueva.
• Aceptar: 1. Confirma que siga en ringing. 2. getUserMedia, aplica la oferta y crea la respuesta cambiando a=setup:actpass por active. 3. Junta los ICE (máximo 5 s) y vuelve a confirmar que siga sonando. 4. Manda pre_accept y después accept, y escribe status: active, answeredBy y answeredAt.
• Si hay error antes de que pre_accept saliera bien, no manda terminate, porque cortaría la llamada que otro compañero ya atendió.
• Rechazar es local: solo deja de sonar en esa pantalla. Cortar para todos pide confirmación, manda terminate y deja status: rejected y rejectedBy.
• Saliente: 1. Arma la oferta, junta ICE (máximo 5 s) y manda connect. 2. Escucha el documento hasta que llegue sdpAnswer, lo aplica como respuesta y arranca el cronómetro.
• Colgar sin startTime queda como no_answer, no como una "contestada de 0:00".
• Si el estado de la conexión WebRTC pasa a failed o closed (o queda en disconnected más de 6 s), corta.
• Al terminar avisa al embudo (c2LlamWaTerminada) para abrir el formulario del resultado.

Permiso de llamada (functions/wa-permiso-llamada.js y endpoints)

• Colección whatsapp_call_permissions/{tel} con status (granted, pending, denied, expired o none), isPermanent, expiresAt, requests[] (ms, podados a 7 días), lastRequestAt, lastRequestBy, lastRequestTemplate, lastReplyAt, lastReplySource, lastInboundCallAt, statusMeta, metaPuedeLlamar, metaPuedePedir y syncAt.
• Estados reales de Meta: devuelve temporary, permanent y no_permission, que no figuran en la documentación. Se normalizan: los dos primeros a granted, el último a none.
• Vigencia: el permanente no vence. El temporal se calcula contra el reloj con expiresAt, y si Meta no manda fecha son 7 días. Una llamada entrante abre 24 h para devolverla.
• Límites de pedidos: 1 cada 24 h y 2 cada 7 días. Si el cliente rechazó (denied), no se vuelve a pedir.
• sincronizar: GET /{phoneId}/call_permissions?user_wa_id=. start_call.can_perform_action manda sobre el status (da autorizado_meta o revocado_meta). Si local dice pending y Meta dice none, se conserva pending: Meta no sabe que le preguntamos y todavía no contesta.
• guardarRespuesta: un sí limpia requests[]. Un permanente borra expiresAt.
• whatsappCallPermission: si la copia local dice que se puede llamar y no se pidió sync, responde local. Si no, consulta a Meta, y si Meta falla responde con lo local más avisoSync.
• whatsappPedirPermisoLlamada: 1. Messenger: 400. optOut: 409. Ya puede llamar: 409. Límite de pedidos: 429 con motivo y esperaHasta. 2. Ventana abierta (lastInboundAt de menos de 24 h): mensaje interactive de tipo call_permission_request (gratis, sin plantilla). 3. Ventana cerrada: hace falta una plantilla. Si no viene, responde 400 necesitaPlantilla. 4. Error 138007: Meta no acepta otro pedido todavía. 5. Registra el pedido, guarda el mensaje con type: call_permission_request y body = cuerpoReal (el texto exacto que leyó el cliente), y pone lastMessage "Permiso de llamada solicitado".
• Plantillas de permiso: llevan el componente de primer nivel {"type":"CALL_PERMISSION_REQUEST"}, sin botones. Un botón VOICE_CALL no sirve para esto: marca directo al tocarlo (ya le sonó el teléfono a un cliente). Meta bloquea reutilizar el nombre de una plantilla borrada durante unas 4 semanas. Sin el parámetro {{1}}, Meta devuelve 132000. El 132001 significa que todavía está en revisión.
• Frontend (public/wa-permiso-llamada.js):
• Envuelve window.makeCall: sin permiso abre el modal. Si Meta rebota la llamada, sincroniza y ofrece pedir permiso.
• Seis motivos, cada uno con texto para dentro de la ventana y plantilla para fuera.
• Primero intenta dentro de la ventana. Si recibe necesitaPlantilla, reintenta con la plantilla usando el primer nombre (limpio de emojis; si el nombre es solo un teléfono, usa "buenas").
• Al terminar llama a evReasignarPorRecontacto (regla de lead frío).

Lead frío al raspar (reasignarLeadFrio y backfill)

Regla: si un vendedor manda una plantilla de recontacto (raspa) o pide permiso de llamada a un teléfono que no es cliente, sin ventas y con más de 3 días sin ningún mensaje, el lead pasa a quien lo revive. El navegador no puede hacer esto porque las reglas de Firestore no permiten tocar el assignedTo ajeno. En el embudo, si el lead no tiene dueño lo toma el navegador; si es de otro, llama a esta función.

Flujo:

1. Messenger: 400. Sin teléfono: 400. Solo Ventas o gerencia (si no, 403).
2. Si la conversación no existe o ya es del solicitante: {reasignado: false}.
3. Si esCliente o esClienteManual: no reasigna, con mensaje.
4. Frío:

ms = últimos 25 mensajes del teléfono, del más nuevo al más viejo
recorrer ms, saltando los salientes del propio solicitante de los últimos 10 min
ultimoMs = timestamp del primero que no se saltó
si se saltaron todos: ultimoMs = lastInboundAt
diasFrio = floor((ahora - ultimoMs) / 1 día), o 9999 si no hay ninguno
si ultimoMs y diasFrio < 3: no reasignar, explicando cuánto hace del último movimiento

5. Sin ventas: busca en citas por telefono y por telefono_normalizado, con las variantes (con 506, sin 506). Si encuentra alguna, no reasigna.
6. Transacción: relee y verifica que el dueño no cambió y que no es cliente. Escribe assignedTo, embudoVendedor: "", esClienteManual: false, fueraDeClientes: true, updatedAt y boardCol.
7. Registra whatsapp_activity con action: "asignado".

Lecciones:

• Cualquier regla que se evalúe después de un envío tiene que ignorar ese mismo envío. Entre el 3 y el 9 de octubre la función medía con lastMessageAt, que el envío acababa de mover a "ahora", y no reasignó a nadie.
• Después, con limit(5), una campaña de 5 plantillas propias dejaba ultimoMs = 0 y la regla tomaba un lead ajeno que había escrito ese mismo día. Por eso ahora se miran 25 mensajes y, si todos son propios, manda lastInboundAt.

backfillLeadFrio (solo gerencia, máximo 300 s):

• Body {dias (1 a 14, por defecto 3), aplicar, forzar: [{phone, a}]}. Sin aplicar solo cuenta.
• Toma la primera plantilla por (teléfono, vendedor) en el período.
• Salta: lead sin dueño o que ya era del raspador; dueño especial (reclutamiento o bot); cliente; lead no frío (medido antes de la plantilla, saltando los propios de los 10 minutos previos); lead reasignado a mano después del raspado; lead con ventas.
• forzar asigna directo, sin evaluar la regla.
• Devuelve los conteos por motivo.

Primer asignado (estamparPrimerAsignado, trigger sobre whatsapp_conversations)

• Si ya existe primerAsignado, no hace nada.
• Si no, el primer asignado es el dueño anterior cuando era humano, o el nuevo. Los dueños *.bot no cuentan: se espera a la primera persona.
• primerAsignadoAt es el assignedAt solo si lo cambió esta misma escritura (las asignaciones a mano no lo tocan y puede venir viejo). Si no, la hora del servidor.
• En transacción: escribe primerAsignado en minúsculas y primerAsignadoFuente: "al_asignar". El reparto por nivelación lo escribe por su cuenta en la misma transacción, con fuente reparto_nivelacion.
• Uso: los leads de la semana se cuentan para quien los recibió primero. Un raspado o una cesión no se lo quitan.

Plantillas de WhatsApp

public/wa-templates.js

• Es la fuente única de plantillas: DEFAULT_TEMPLATES tiene 437 definiciones (309 de marketing y 128 de utilidad; 39 con imagen en el encabezado; 24 con botón URL).
• Cada una trae id, name, category, language, headerType, headerImageUrl, headerText, bodyText (con {{n}}), footerText, buttons[], buttonType, buttonUrl, paramLabels, urlParamLabels y keywords.
• TPL_GROUPS las agrupa por propósito: primer contacto, cotización, plagas, objeciones, preguntas frecuentes, seguimiento, raspa/retomar, reactivación, confirmación, recordatorio, coordinación, cancelación, cobro, post-servicio, garantía, reclutamiento, recuperador, etc. Las que no tienen grupo caen en "otros" (getTplGroup).
• seedTemplates(db) sincroniza con whatsapp_templates: crea, actualiza solo si cambió algún campo y borra las huérfanas.
• El opt-out se ofrece como botón de respuesta rápida ("No deseo más mensajes"). El bot lo detecta (botón con "no deseo", o regex más confirmación de modelo liviano) y escribe optOut: true y optOutAt.

crearPlantillaWA

• Borrar: {borrar: nombre}, solo gerencia. El nombre tiene que calzar con ^[a-z0-9_]{1,512}$. Hace un DELETE en la WABA por nombre.
• Crear: pide el permiso whatsapp. Pasa la política de promesas sobre textos, botones y ejemplos. Hace POST a la WABA (fija) sin el wabaId en el cuerpo y devuelve {ok, data}.
• Reglas de Meta que ya rebotaron: los botones de respuesta rápida no aceptan emojis; un encabezado de imagen exige example.header_handle, que se obtiene por la Resumable Upload API de la app, porque Meta no acepta una URL como muestra.

estadisticasPlantillas

• Sin ?recalcular devuelve la caché plantillas_stats/resumen. Recalcular cuesta unas 65 mil lecturas y es solo para gerencia.
• Recalcular: 1. Lee los mensajes ordenados por templateName (solo los campos usados) y todos los entrantes. 2. "Respondió en 24 h" busca con búsqueda binaria el primer entrante estrictamente posterior al envío. 3. Cuenta por plantilla: envíos, entregados (read cuenta también como entregado), leídos, fallidos, respondidos, primer y último uso, y los 3 usuarios que más la mandan. 4. Une el resultado con el catálogo vivo de Meta (estado, categoría, quality_score) paginando de a 200. 5. Marca las "nunca usadas" y las "huérfanas" (usadas pero ya no están en Meta). 6. enviosPorFecha se calcula por día de Costa Rica (en UTC, lo raspado de 6 pm a medianoche caía al día siguiente) y se recorta a 180 días, para no pasar de 1 MiB por documento.

Hallazgo de negocio (octubre 2026): lo que decide si una plantilla rinde es cuántos días lleva callado el lead, no el número de plantilla. Con 2 o 3 días de silencio todas suman. Con 8 o más días, la primera suma un poco, la segunda no se distingue de cero y la tercera no vendió nada en 111 envíos. El costo por plantilla no es el problema.

Calidad de escritura (evaluarEscrituraVendedores)

• Permiso reportes_gerenciales. Toma dias entre 1 y 30 (por defecto 7).
• Candado: si el reporte de hoy (reportes_escritura/{día CR}) tiene menos de 12 h, lo devuelve sin volver a pagar el modelo.
• Qué se evalúa: solo texto. Excluye plantillas (incluido lo que trae templateName), mensajes borrados, fallidos, de menos de 15 caracteres o menos de 3 palabras, y los que son solo un enlace.
• Un guion repetido se cuenta una sola vez (se normalizan URLs, números y espacios) y se anota cuántas veces se usó.
• El vendedor necesita al menos 5 textos únicos. Se envían como máximo 140 mensajes por vendedor (los más repetidos primero), recortados a 900 caracteres.
• Modelo grande con razonamiento adaptativo: hay que filtrar los bloques de tipo text, no tomar el primero. Tres reintentos con espera creciente y tandas de 3 vendedores en paralelo.
• Salida: notas de ortografía, puntuación, mayúsculas, gramática, profesionalismo y concisión, más nota global, resumen, fortalezas, a mejorar y hasta 12 hallazgos.
• El voseo y el trato tico respetuoso no cuentan como errores.

Tiempos de respuesta (functions/tiempos-respuesta.js)

• Corre cada 30 min, solo entre las 6:00 y las 22:59 de Costa Rica. Recalcula hoy y ayer (las respuestas a mensajes de ayer pueden llegar hoy).
• Qué mide: por cada entrante que abre una ráfaga (el mensaje anterior no era entrante), el tiempo hasta la siguiente respuesta humana.
• Respuesta humana: saliente, que no sea del bot (bot != true y el autor no termina en .bot), que no sea type: call y que no la haya firmado el sistema web.
• Solo cuentan los leads con dueño de Ventas, y solo si el cliente escribió en un minuto en que el dueño estaba activo en la app (presence_days/{user}_{día}.slots[minuto] con clics o teclas mayores a 0).
• Sin respuesta en 24 h queda como null (fuera de la mediana).
• Guarda en tiempos_respuesta/{día} un datos como texto JSON de filas [username, canal, minutos]. Va como texto para que Firestore no indexe cada elemento.

Atributos de CRM (crm-atributos.js y actualizarAtributosCrmScheduled)

• Horario: todos los días a las 4:45 hora de Costa Rica, con 540 s y 1 GiB. A las 4:30 corre la reconciliación de clientes.
• Marca de avance: crm_meta/atributos.ultimoTimestamp es el timestamp del último mensaje procesado, no la hora de la corrida. Antes había un solape de 2 h que se volvía a sumar todas las noches. La consulta usa timestamp > estricto.
• Backfill sin función nueva: gerencia escribe backfillPendiente: true y backfillDesde, y la corrida siguiente recalcula ese tramo reemplazando los acumulados.
• Lotes: de unos 400 teléfonos. Nunca se corta entre dos mensajes con el mismo timestamp (corte forzado a los 480). Cada lote se confirma en un solo batch junto con la marca, así una corrida que muere a mitad no vuelve a sumar lo ya escrito.
• Cómo se fusiona: los contadores se suman, las banderas se combinan con OR, las listas se unen, la fecha del primero se conserva y la del último se toma la mayor.
• Los rastros de llamada (type: call) no cuentan como mensajes: van a total_llamadas y llamadas_perdidas.
• Léxico: plagas, tipo de propiedad, intención (precio, agendar, urgencia, garantía, queja), mascotas y niños, empleo. Tiene que coincidir con el script de backfill manual.
• Campos derivados: nunca_respondio, conversacion_profunda (más de 10 entrantes), nos_dejo_en_visto (último mensaje nuestro hace más de 7 días), ventana_abierta, plantillas_distintas (usa __tpls acumulado, con el valor histórico como piso), horario_preferido, y los que se leen de la conversación (embudo, vendedor, archivado, etiquetas).
• Después de los atributos corren refrescarDerivados (días desde el último mensaje, antigüedad, dejado en visto) y, con el tiempo que sobre de un tope de 480 s, el barrido de media.

public/wa-chat-shared.js

• detectMediaType, formatBytes, parseLatLng (enlaces de Maps con @lat,lng, !3d!4d, ?q= o "lat, lng"), geocodeAddress (geocodificador público de OpenStreetMap, Costa Rica por defecto) e isForwardableMediaUrl (rechaza la media de Meta, que no se puede re-subir).
• runSendQueue: envío secuencial. Si hace falta comprime el video, sube el archivo a Storage en whatsapp_media/{tel}/{ts}_{nombre} y llama a whatsappSend. Solo el primer elemento lleva replyToWamid. Espera 350 ms entre envíos y devuelve {sent, failed[]}.

WhatsApp oficial: casos borde y lecciones

1. Responder 200 después de guardar y 500 ante cualquier error. Todo el webhook tiene que ser idempotente (id = wamid, contador solo la primera vez, last* solo avanza).
2. Los estados de entrega pueden llegar antes que el documento del mensaje: se crea el mensaje apenas responde Meta.
3. El canal es MECE y congelado: cada conversación tiene exactamente un canal, decidido en el primer toque. Los aspirantes a empleo se separan, también por campaña.
4. Reasignación por turno: se evalúa antes de escribir outbound y en transacción.
5. Las reglas posteriores a un envío ignoran ese envío (lección del lead frío).
6. La política de promesas la decide el servidor. El navegador solo avisa. Vale también para gerencia y para las plantillas nuevas.
7. Opt-out: frena las plantillas y los pedidos de permiso, no el texto libre. Messenger no lo revisa.
8. Ventana de 24 h: 72 h si el cliente entró por un anuncio. El servidor no la valida para texto: se traduce el 131047.
9. Media saliente: subir a Meta y mandar por id, con plan B por enlace. Audio como OGG/Opus con voice:true, con plan B M4A sin voice.
10. Media entrante: trigger con reintento, tope de 6 h, barrido nocturno con 5 intentos y ruta determinista en Storage.
11. Llamadas: distinguir saliente de entrante por el SDP. Rechazar es local; cortar para todos va aparte. Nunca mandar terminate antes de que el pre_accept propio haya salido bien.
12. Permiso de llamada: Meta manda sobre el estado local. El pending es nuestro y hay que protegerlo del sync. Nunca usar el botón VOICE_CALL como pedido de permiso.
13. Autor: siempre del token. Solo gerencia firma por otra persona.

WhatsApp oficial: protocolo de pruebas

• Toda prueba de envío va entre dos números internos fijos de gerencia, nunca a clientes.
• Antes de mandar, verificar el encabezado del chat abierto y abortar si no es el número esperado o si es un grupo. Un mensaje enviado no se deshace: ya cayó una prueba en un grupo real del equipo.
• Las reglas de Firestore se prueban contra el emulador: que compilen no significa que estén cerradas.
• El login desde localhost está bloqueado, así que se publica primero y se prueba en vivo.

CRM: pantallas vigentes

Lección: cualquier enlace que lleve a un chat tiene que apuntar a embudo_vendedor.html?tel= (o ?phone=). El botón "Confirmar CRM" de la agenda estuvo roto porque abría crm.html?phone=...&tpl=....

CRM: modelo de datos común

whatsapp_conversations/{id}

El id es el teléfono normalizado 506XXXXXXXX, o fb_<psid> en Messenger.