Casos de uso y workflows

Esta página recorre los diez flujos que estructuran la operación diaria sobre EMA Vault. La perspectiva es funcional —qué pasa, en qué orden y por qué importa— y deja para el manual de usuario los pasos concretos por rol.

Pipeline lead a cliente provisionado

El flujo de captura, conversión y provisioning es el camino más ejercitado del producto. Recorre cuatro áreas distintas del equipo y termina con un cliente operativo en sus productos contratados. La orquestación entre áreas es manual en lo decisorio (el comercial trabaja el lead, finanzas valida los datos fiscales, admin dispara el provisioning) pero automatizada en lo mecánico.

El lead nace cuando alguien de comercial registra un caso nuevo en el módulo de pipeline. La fuente del lead se anota explícitamente —web, referido, evento, conversación con EMI— porque permite atribuir después qué canal de adquisición está produciendo conversiones. Si la fuente es EMI, el sistema vincula automáticamente las invocaciones del chatbot al lead vía el join con emi_invocations, lo que produce un badge violeta visible en el pipeline y permite leer la conversación previa antes de hacer la primera llamada.

A medida que el lead avanza por las siete etapas del pipeline (Nuevo, Contactado, Reunión, Propuesta, Negociación, Ganado o Perdido), la probabilidad asociada se ajusta automáticamente. Cuando el lead llega a Ganado, comercial dispara la conversión: el sistema crea la organization con tipo cliente, el contacto principal en people y un placeholder de contrato. Finanzas toma el control desde aquí para llenar el fiscal_config (identificador tributario del país, razón social, certificado digital, ambiente del organismo fiscal, tipos de documentos habilitados). Cuando los datos están completos, admin dispara el provisioning con un POST: el sistema crea la Organization raíz en Aidbox, encripta el secret OAuth con AES-GCM, lo persiste, y luego loop cross-product invoca a cada producto contratado con X-Platform-Key. El cliente recibe el email de invitación y el tenant queda operativo en cuestión de minutos.

Provisioning manual sin pasar por pipeline

No todos los clientes nacen en el pipeline. Para los casos en que la relación parte por canal informal —referido directo, partnership con un integrador, cliente histórico de fundadores— el provisioning arranca creando la organization manualmente y siguiendo el mismo camino fiscal que en el flujo anterior. El resultado es el mismo estado final, pero el origen del cliente queda registrado como “manual” en lugar de “lead converted”.

La invitación al admin del cliente se hace en un paso separado, después de confirmar el provisioning. Esa separación deliberada permite revisar que todo quedó bien antes de generar el primer contacto formal con el cliente.

Contrato con alerta de vencimiento

Los contratos viven con ciclo propio: nacen como draft, se firman offline o por DocuSign externo, y queda como vigente hasta su end_date. El sistema vigila las fechas de vencimiento y alerta con treinta días de anticipación, lo que da margen al equipo comercial para gestionar la renovación sin sobresaltos.

Las renovaciones generan un nuevo contrato vinculado al anterior por previous_contract_id. Esa cadena permite trazar la historia contractual de un cliente a lo largo de varios años sin perder contexto.

Generación de propuesta comercial con AI

Cuando un lead llega a etapa de Propuesta, comercial puede pedir al sistema que genere un primer borrador. El endpoint POST /api/ai/proposal recopila contexto del lead (email, empresa, fuente, conversaciones EMI cuando existen) y consulta Anthropic Sonnet, que devuelve un documento markdown estructurado.

El borrador se guarda como documents asociado al lead, lo que permite trazar después qué versión recibió el cliente y qué cambios hizo el equipo sobre el output del modelo.

Configuración de facturación electrónica para nuevo cliente

La configuración fiscal de un cliente nuevo es la pieza más regulatoria del producto, porque los organismos fiscales de cada país exigen certificado digital y datos exactos para emitir documentos electrónicos. El flujo está pensado para que un staff de finanzas pueda completarlo en una sola sesión sin saltar entre sistemas, sirviendo cualquier país soportado por el plug-in fiscal correspondiente.

Casi todos los organismos fiscales modernos ofrecen un ambiente de certificación y otro de producción. En el plug-in chileno el SII los nombra maullin (certificación) y palena (producción), y el flujo típico es arrancar el onboarding en certificación para validar el comportamiento end-to-end y, una vez aprobado, mover el tenant a producción real. Otros países usan nombres distintos pero el patrón es el mismo. Vault sincroniza el fiscal_config con cada producto del ecosistema vía X-Platform-Key, lo que permite que clinic y lab emitan documentos fiscales inmediatamente después de la actualización.

Producto module: gestión de release con GitHub sync

El módulo de producto mantiene un catálogo vivo de los once productos de EMA Health. Para cada producto existe un dashboard, listado de issues, backlog de features, journeys editables, mapa de módulos, tech stack, releases con changelog y roadmap con capas inline-editables. La sincronización con GitHub funciona en dos vías para que el catálogo refleje siempre el estado real del repo.

Por un lado, un webhook conectado en cada repositorio escribe en la cache local cuando cambia el estado de un issue; por otro, un cron horario hace pull paginado de toda la lista para asegurar consistencia eventual incluso si el webhook fallara. Cuando un issue está vinculado a una feature en el backlog y el issue se cierra, la feature pasa a estado completado automáticamente. Los releases se componen desde la UI de Vault, no desde GitHub, y se publican con changelog markdown que después aparece en la sección de releases del producto.

Matriz de acceso EMI

La matriz de acceso EMI permite al admin habilitar o deshabilitar el asistente conversacional por cada combinación de tenant y aplicación. Es el control que decide si una clínica concreta tiene EMI activo en su instalación de Clinic, en Lab, en Vault o en ninguna.

El cambio de un toggle se traduce en una actualización de emashared.tenant_emi_access y, desde el siguiente request, el tenant correspondiente puede o no invocar /api/emi/chat. La analítica complementaria muestra KPIs de los últimos treinta días: total de invocaciones, tokens consumidos, costo estimado, time series, distribución por aplicación y top tenants. Esos datos sirven para detectar abuso, anticipar facturación y priorizar optimizaciones.

Lead a EMI conversation linking

Cuando un lead nace de una conversación con el chatbot público —típicamente en el sitio de EMA Clinic, EMA Lab o el landing principal— Vault establece el vínculo entre el lead y las invocaciones EMI vía un session id compartido. El resultado es que el comercial puede leer la conversación completa antes de hacer la primera llamada al lead.

El badge violeta sobre el lead en el kanban es el indicador visible de que existe contexto previo. Click sobre el badge expande la sección “Conversaciones EMI” con todas las invocaciones vinculadas, ordenadas cronológicamente.

Audit trigger cross-product

Toda mutación a las doce tablas críticas dispara el audit_trigger() SECURITY DEFINER, que escribe en emashared.audit_log el cambio completo con sanitización de secrets. El registro queda accesible para queries y exportación desde el módulo de audit.

El audit es la herramienta principal cuando el equipo necesita investigar qué pasó: quién canceló un contrato, cuándo se cambió la configuración fiscal, qué admin desactivó a un usuario. Las queries estándar (por usuario, por tabla, por rango de tiempo) están disponibles desde la UI sin necesidad de tocar SQL.

Métricas Ema Well en read-only

El último de los workflows operativos es el dashboard de Ema Well, que vive en un proyecto Supabase separado por requerimientos de protección de datos de salud (en Chile, la Ley 21.719; en otros países, sus equivalentes locales como LGPD en Brasil, HIPAA en Estados Unidos o GDPR en Europa). Vault accede a ese proyecto exclusivamente con service-role en modo lectura, y solo expone métricas agregadas: nunca datos individuales de pacientes.

Los cinco KPIs disponibles son retention por cohorte, distribución de streaks activos, popularidad de pillars, actividad diaria y overview de usuarios activos. La separación arquitectónica garantiza que ningún staff de Vault puede inadvertidamente acceder a datos individuales: la query simplemente no lo permite.

Patrones que recorren todos los flujos

A lo largo de los diez workflows aparecen seis principios de diseño comunes. El primero es la transparencia del audit: cualquier acción crítica queda registrada con secrets sanitizados, lo que permite reconstruir incidents sin riesgo de exponer credenciales. El segundo es la idempotencia del provisioning: re-correr no produce duplicados, lo que permite reintentar con confianza después de un fallo parcial.

El tercero es la AI como best-effort: las propuestas, los resúmenes de contrato y los analysis de leads son drafts que el humano revisa antes de actuar. El cuarto es que cada invocación EMI es un evento auditable: queda registro en emi_invocations con tenant, usuario, lead asociado y tokens consumidos. El quinto es la preservación de slug history: cuando un cliente renombra su subdominio, las URLs antiguas siguen redirigiendo durante doce meses vía tenant_slug_history. El sexto es que el theme persiste en localStorage, una decisión menor pero coherente: el usuario elige light o dark y el sistema lo respeta.