# Configuración de una clínica / spa nuevo Guía de puesta en marcha de una instancia del sistema (producto multi-giro). Todo lo que sigue se configura desde la interfaz, **sin tocar código**. Para crear la instancia (base de datos, puerto, servicio, dominio, secretos y primer usuario admin) usa el script de provisioning: ver [`nueva-instancia.md`](../nueva-instancia.md). Esta guía empieza cuando la instancia ya está levantada y con sesión de administrador. La configuración vive en `Configuración` (panel con pestañas). El administrador ve todas; gerencia ve un subconjunto (no ve la pestaña Clínica con los datos de la instancia, ni Catálogos, API o Auditoría; en Licencia solo consulta el estado). Salvo donde se diga lo contrario, cada bloque tiene un interruptor de encendido y **apagado por defecto**: mientras no se active, la instancia se comporta como una instalación base. --- ## 1. Identidad de la clínica **Configuración → Clínica** (sección de identidad) | Qué | Efecto | |---|---| | Nombre comercial | Login, títulos, tickets, documentos y mensajes | | Logo claro / oscuro | Sidebar, login y tema claro | | Pie de página | Login y documentos impresos | | Color primario / acento | Se aplican en vivo sobre los 3 temas; vacío = tema original | | URL pública | Base para enlaces de pago, correos y el enlace de reservas | La marca es **por instancia y no vive en el código**: sale del parámetro `skeen.clinic.brand` (API `/skeen/frontend/v1/brand`). Por eso una misma build del frontend sirve a varias clínicas white-label sin recompilar. ## 2. Terminología (giro del negocio) **Configuración → Terminología** Elige el pack según el negocio y ajusta cualquier término a mano. El glosario tiene **24 términos** configurables (singular y plural de paciente, cita, visita, expediente, médico, personal, sucursal, cabina/sala, servicio, paquete, receta y tratamiento). | Término | Clínica (default) | Spa / Wellness | Estética | Dental | |---|---|---|---|---| | Paciente | Paciente | Cliente | Cliente | Paciente | | Cita | Cita | Reserva | Cita | Cita | | Visita | Visita | Sesión | Sesión | Consulta | | Expediente | Expediente | Ficha | Ficha | Expediente | | Médico | Médico | Terapeuta | Especialista | Odontólogo | | Cabina / sala | Cabina | Sala | Cabina | Consultorio | | Servicio | Servicio | Servicio | Servicio | Tratamiento | | Receta | Receta | Recomendación | Receta | Receta | | Tratamiento | Tratamiento | Tratamiento | Tratamiento | Procedimiento | El pack cambia menús, títulos, botones, estados y también los mensajes de notificación y el portal público de reservas. El pack `custom` parte de Clínica y aplica solo los ajustes manuales. ## 3. Idioma de la interfaz **Menú de usuario → idioma** o **Configuración → Clínica** (selector ES/EN). - El selector cambia el idioma de toda la interfaz a **Español** o **English**. - El idioma es **por navegador** (se guarda en el navegador del equipo), no por clínica ni por usuario; dos equipos pueden ver idiomas distintos. - La i18n y el glosario conviven: el **glosario** define el *vocabulario del negocio* (paciente↔cliente, cita↔reserva) y **solo existe en español**; en inglés se usa un mapa base equivalente. El **idioma** traduce el resto del texto. En español manda el término del pack configurado. ## 4. Operación **Configuración → Clínica** (datos y horarios) - Teléfono, email, dirección, sitio web, RFC, nota de ticket. - **Horario de apertura y cierre**: define la rejilla de la agenda (default 08:00–19:00). - Zona horaria (default `America/Tijuana`) y moneda base (default `MXN`). **Configuración → Sucursales**: alta de sedes (nombre, código, dirección, teléfono) y cuál es la predeterminada. Cada cita pertenece a una sucursal. Las sucursales con histórico no se borran: se desactivan (quedan archivadas). Vienen dos de ejemplo (Rosarito predeterminada y Tijuana). **Configuración → Categorías**: las 4 categorías base (Consulta, Tratamiento, Procedimiento, Paquete) se pueden renombrar y se pueden crear más (p. ej. "Depilación", "Faciales"). Las de sistema no se borran. ## 5. Catálogo y precios - **Servicios**: nombre, categoría, precio, duración (define el tamaño del bloque en la agenda), paquete y tasa de impuesto. - **Inventario**: artículos, consumibles (con caducidad, que bloquea la venta al vencer) y su tasa de impuesto. - Los precios se editan en Servicios / Inventario; el POS y la agenda los toman de ahí. ## 6. Impuestos **Configuración → Clínica → Impuestos** (apagado por defecto) - Activar impuestos, nombre (default `IVA`), tasa por defecto (default `0`) y catálogo de tasas (default `0, 8, 16`). - `Precios incluyen impuesto`: si el precio capturado ya trae impuesto, el sistema lo desglosa automáticamente. - Con impuestos activos: desglose en POS, tickets, estado de cuenta y reporte **Reportes → Impuestos** (por mes, servicio y sucursal, exportable). ## 7. Reservas en línea (portal del cliente) **Configuración → Reservas en línea** (apagado por defecto) - Activar el portal y compartir el enlace `/reservar` de la clínica (el propio panel muestra el enlace listo para copiar). - Opciones (con sus valores por defecto entre paréntesis): título y descripción visibles al cliente, confirmación manual o automática (`requiere_confirmacion` = sí), permitir elegir especialista (sí), permitir elegir sucursal (no), máximo de días a futuro (60), anticipación mínima en horas (2), teléfono de contacto, mensaje de confirmación y política de cancelación (permitir cancelar = sí, hasta 24 h antes). - El cliente recibe un enlace propio para consultar o cancelar su cita. Las reservas que llegan por el portal se distinguen en la agenda. ## 8. Recursos (cabinas, salas y equipos) **Configuración → Recursos** (apagado por defecto) Sirve para agendar **recursos físicos** además del médico: cabinas, salas, consultorios o equipos. Con el módulo apagado la agenda se ve igual que siempre y no se valida nada. - **Catálogo** (`skeen.recurso`): nombre, código, tipo (Cabina / Sala / Consultorio / Equipo / Otro), activo, secuencia, sucursales donde aplica (vacío = todas), capacidad, costo por hora, color y notas. Vienen dos recursos semilla (Cabina y Consultoría). - **Opciones del bloque** (defaults): activo (no), `validar_solape` (sí), `obligatorio_al_agendar` (no), `permitir_multiples` (sí), `mostrar_en_agenda` (sí), `filtrar_como_doctores` (sí). - **Asignación**: en el modal de la cita se eligen uno o varios recursos. - **Validación de solape**: con `validar_solape` encendido el sistema impide dos citas en el mismo recurso a la misma hora e informa con qué cita choca. También respeta los bloqueos del recurso. - **Bloqueos por recurso**: un bloqueo de agenda puede ser de un médico, de un recurso o de ambos (`skeen.cita.bloqueo`): fecha, todo el día o rango horario, motivo y serie (grupo). - **Vista por recurso**: la agenda puede mostrar el recurso en la tarjeta y ofrecer el filtro por recurso junto al de doctores. El reporte **Reportes → Recursos** muestra ocupación e ingresos estimados por recurso. ## 9. Usuarios, roles y permisos **Configuración → Usuarios**: alta de usuarios, rol, menús visibles y, para agenda, las acciones específicas (consultar, agendar, editar, mover, eliminar, generar visitas, ver todas, bloquear). **Configuración → Roles**: tres pestañas: 1. **Roles**: crear roles propios del negocio (p. ej. Terapeuta, Recepción de fin de semana), renombrar, ajustar jerarquía y activar/desactivar. Vienen 10 roles base (admin, médico, recepción, enfermería, cosmetología, psicóloga, farmacia, gerencia, marketing, lectura). 2. **Permisos**: **71 permisos por acción agrupados en 16 grupos** (Agenda, Recursos, Pacientes, Visitas, Ventas, Inventario, Servicios, Reportes, WhatsApp, Notificaciones, Formularios, Membresías, Compras, Comisiones, Configuración, Plataforma), con botones todo/ninguno. El backend los hace cumplir aunque el usuario manipule la interfaz. 3. **Menús**: qué sección ve cada rol. Recomendación: partir del rol más parecido, ajustar y guardar. ## 10. Notificaciones **Configuración → Notificaciones** (apagado por defecto, con modo prueba) - Recordatorios automáticos antes de la cita (ventanas configurables de hasta 168 h; default 24 h y 2 h), confirmación al reservar en línea, felicitación de cumpleaños, seguimiento post-visita (horas configurable) y recuperación de pacientes que no se presentaron. - Canales: WhatsApp, correo o ambos (default WhatsApp). Plantillas editables con vista previa y variables (`{nombre}`, `{cita}`, `{servicio}`, `{fecha}`, `{hora}`, `{doctor}`, `{sucursal}`, `{telefono}`, `{enlace}`, `{formulario}` y las de membresía `{plan}`, `{membresia}`, `{monto}`, `{sesiones}`, `{periodo}`). - **Modo prueba** (default): registra lo que se habría enviado sin contactar a nadie — úsalo para revisar textos antes de encenderlo. - **Configuración → Notificaciones enviadas**: historial por paciente y por cita, con reintento. ## 11. Membresías **Configuración → Membresías** (apagado por defecto) y **Membresías** (menú). Una membresía **no es un paquete**: es un plan recurrente con vigencia, sesiones incluidas, cobro periódico, congelamiento y renovación. - **Planes** (`skeen.membresia.plan`): precio y moneda, periodicidad (semanal, mensual, trimestral, semestral, anual), sesiones incluidas por periodo (0 = ilimitadas), servicios y categorías incluidos, descuento en servicios no incluidos, cargo de inscripción, meses mínimos, permite congelamiento, sucursales y servicio con el que se cobra. - **Opciones del bloque** (defaults): activo (no), `dias_aviso_renovacion` (`[7, 1]`), `permitir_congelamiento` (sí), `dias_max_congelamiento_anio` (30), `renovacion_automatica_default` (no), `descuento_porcentaje_default` (0), `permitir_pausa_pago` (no), `generar_cargo_al_renovar` (sí), `dias_gracia` (5). - **Alta**: la membresía recibe folio `MEM-` y calcula su periodo actual, próximo cobro y fin de compromiso. - **Cobro**: genera una venta y un pago normales (aparece en cortes de caja como cualquier venta). También cobra la inscripción la primera vez. - **Consumo desde POS/expediente**: el consumo de sesiones **no se descuenta en silencio**; el POS o la cita llaman explícitamente a "usar sesión de membresía". Al cancelar una cita que usó una sesión, la sesión se libera. - **Congelamiento**: se congela con rango y motivo, respetando el tope anual; al descongelar se corre el fin de periodo y el próximo cobro. - **Renovación**: manual (avanza el periodo y genera el cargo si aplica) o automática por cron. - **Vencimientos y avisos**: un cron diario marca vencidas (con días de gracia), envía avisos de renovación en cada ventana y descongela al terminar la ventana. - **Reporte**: **Membresías → reporte** con ingreso recurrente por periodo. ## 12. Compras y proveedores **Configuración → Compras** (apagado por defecto) y **Compras** (menú). - **Proveedores**: sobre el contacto (`res.partner`) con marca propia de proveedor, días de crédito, contacto de compras, banco, cuenta/CLABE y notas. Un proveedor con historial no se borra: se desactiva. - **Órdenes de compra** (`skeen.compra`): folio `OC-`, proveedor, líneas de artículo, moneda (MXN/USD), descuento e impuesto por línea. Estados: Borrador → Enviada → Recibida parcial / Recibida → Cancelada. Cancelar solo se permite si no hubo recepciones (si ya entró mercancía se usa una baja/ajuste). - **Recepción total o parcial**: cada recepción es acumulativa; al recibir se carga inventario (movimiento tipo compra) y se puede capturar lote y caducidad. - **Costo promedio**: al recibir se recalcula el costo promedio ponderado del artículo y se guarda el último costo (si `actualizar_costo_promedio` está encendido). - **Pagos a proveedor**: egresos separados de los cobros a pacientes (no aparecen en corte de caja ni en estado de cuenta del paciente). - **Cuentas por pagar**: saldo por proveedor y reporte con antigüedad. - **Reportes**: **Reportes → Compras** y margen por artículo (contra costo promedio y precio de venta sin impuesto). - **Opciones del bloque** (defaults): activo (no), `actualizar_costo_promedio` (sí), `permitir_recepcion_parcial` (sí), `requiere_autorizacion` (no), `dias_credito_default` (0), `margen_minimo_alerta` (0), `permitir_compras_sin_orden` (no). ## 13. Comisiones **Configuración → Comisiones** (apagado por defecto), **Reportes → Comisiones** y **Liquidaciones** (menú). Con el módulo apagado se conserva el reporte de comisiones de siempre (porcentaje plano por empleado). Al encenderlo se usa el motor de reglas. - **Reglas** (`skeen.comision.regla`): alcance global, por categoría, por servicio, por artículo, por plan de membresía o por paquete; tipo porcentaje, monto fijo o escalonado por metas; prioridad; dirigidas a un empleado, a un tipo de staff (doctor/cosmetóloga) o a todos; vigencia; y base propia opcional. La regla ganadora se decide por prioridad, luego por especificidad (artículo > servicio > membresía/paquete > categoría > global) y luego por empleado > tipo de staff > genérica. Sin ninguna regla aplicable se usa el porcentaje de comisión del empleado (respaldo de compatibilidad). - **Base**: `cobrado` (default, sobre lo efectivamente pagado) o `vendido` (subtotal de la línea). Opcionalmente suma impuestos y resta la parte devuelta. - **Escalonados**: el porcentaje se decide con la venta total del periodo del empleado y se aplica a cada línea cubierta. - **Metas y bonos** (`skeen.comision.meta`): por empleado y periodo (`AAAA-MM` o `mensual`), monto objetivo y bono fijo o porcentaje sobre la venta. - **Ajustes** manuales firmados (+/−), que suman o restan a la liquidación. - **Liquidaciones**: se generan por empleado y periodo; al generarlas el desglose queda **congelado** (ya no cambia aunque después se editen reglas o precios). Estados Borrador → Pagada, o Borrador → Cancelada (una pagada no se cancela: se registra un ajuste). Folio `LIQ-`. - **Opciones del bloque** (defaults): activo (no), `base` (`cobrado`), `incluir_impuestos` (no), `neto_de_devoluciones` (sí), `comisionar_membresias` (sí), `comisionar_paquetes` (sí), `comisionar_productos` (sí), `permitir_ajustes_manuales` (sí), `dia_corte` (1), `redondeo` (2 decimales), `pago_minimo` (0). ## 14. Formularios y consentimientos **Configuración → Formularios** y, en el expediente del paciente, la pestaña de formularios. - **Plantillas** (`skeen.formulario.plantilla`): tipo consentimiento informado, nota de expediente, encuesta o autorización; con campo de **texto legal**, requerir firma y/o foto, duración estimada y asociación opcional a sucursales y servicios. Las plantillas se **versionan**: cada respuesta guarda la versión con la que se llenó. - **Tipos de campo** (12): texto, texto largo, número, fecha, selección, multiselección, casilla, escala, firma, foto, archivo y consentimiento. Los campos de foto/archivo pueden marcarse como antes / después / otro, lo que arma la **galería antes/después** del expediente. - **Envío**: por WhatsApp, correo o enlace. El enlace es un token firmado (HMAC, vigencia 180 días) y deja de servir al llenarse. - **Llenado por el paciente**: página pública `/formulario/` (también funciona en el celular) con firma capturada como PNG (hasta 3 MB) y fotos (hasta 5 MB cada una, máximo 10). El sistema valida campos obligatorios, firma y fotos requeridas. - **Historial**: respuestas por paciente con canal, fecha, firma y fotos. ## 15. Tickets y documentos **Configuración → Tickets**: ancho (58/80 mm), fuente, logo y qué secciones se imprimen (incluida la de impuestos). Se aplica al ticket de venta y al de reimpresión. Los perfiles de ticket son **por instancia**, con defaults neutros: una instancia nueva no arrastra datos de SKEEN. ## 16. Licencia **Configuración → Licencia** (admin; gerencia también ve el estado). Cada instancia white-label puede llevar una **licencia firmada** que decide qué módulos incluye y sus límites de uso. Sin licencia aplicada el sistema se comporta con todas las funciones habilitadas. - **Planes**: `basico`, `profesional`, `enterprise` y `custom`. - Básico: agenda, pacientes, POS, inventario y reportes. - Profesional: Básico + WhatsApp, notificaciones, reservas en línea y recursos. - Enterprise: todos los módulos. - Custom: lo que diga la clave. - **Módulos gateables** (controlables por licencia): WhatsApp, notificaciones, reservas en línea, recursos, membresías, compras, comisiones y formularios. Login, agenda, pacientes, POS, inventario, reportes y configuración **nunca** se bloquean. - **Límites**: usuarios, sucursales, citas del mes y almacenamiento (MB). `0` = sin límite. - **Modo**: `aviso` (default; solo advierte y registra en el log) o `bloqueo` (oculta menús, responde 403 en los endpoints del módulo y aplica los límites). - **Cómo aplicar una clave**: pegar la clave `SKN1...` en Configuración → Licencia y guardar. La clave se verifica contra la firma y la vigencia; si es inválida o vencida responde 400 y no sobrescribe la licencia previa. Un campo vacío quita la licencia y vuelve a habilitar todo. El detalle del formato de la clave, la herramienta del vendedor y los endpoints está en [`licencias.md`](licencias.md). ## 17. API para terceros **Configuración → API** (admin). Gestión de claves con alcances (*scopes*), vencimiento y revocación, sobre la API pública `/skeen/api/v1/*` que consume Hermes. La clave se muestra una sola vez al crearla. Alcances disponibles: `citas.read`, `citas.write`, `pacientes.read`, `servicios.read` y `monedero.write`. El detalle está en [`api-terceros.md`](api-terceros.md). ## 18. Webhooks **Configuración → Webhooks** (admin/gerencia). Notificación de eventos de la clínica hacia sistemas externos, con patrón outbox + reintentos + bitácora y firma HMAC de cada entrega. Sin webhooks activos no se emite ni se envía nada. El catálogo de eventos, la verificación de la firma y los endpoints están en [`webhooks.md`](webhooks.md). ## 19. PWA (instalable en tablet y celular) El panel es una **aplicación web instalable** (PWA), sin tienda de aplicaciones. - **Instalar**: abrir el panel en el navegador del dispositivo. En Android/Chrome aparece el aviso "Instalar aplicación"; en iPhone/Safari se usa "Compartir → Añadir a pantalla de inicio" (el aviso trae la guía de iOS). - **Comportamiento offline**: un service worker precachea el *app shell* y los assets con hash. La navegación es *network-first* (un deploy nuevo se ve al primer refresh); si no hay red se sirve la última copia del shell o una página `offline.html`. Las llamadas al API (`/api/*`) y cualquier petición con credenciales **nunca** se cachean. - **Limitación**: los iconos y el nombre del manifest son **fijos por build** ("Panel Clínico" e iconos genéricos). No cambian con la marca de la instancia; cambiarlos requiere recompilar el frontend. La marca visual (nombre, logos, colores) sí es por instancia y no requiere build. --- ## Checklist de arranque - [ ] Identidad: nombre, logos, colores, URL pública. - [ ] Terminología: pack del giro + ajustes finos. - [ ] Idioma de la interfaz (si el cliente no trabaja en español). - [ ] Horarios, zona horaria, moneda, sucursales, categorías. - [ ] Catálogo de servicios con precios y duraciones. - [ ] Inventario y consumibles (caducidades y costos reales). - [ ] Impuestos (tasa por defecto + tasas por servicio/artículo). - [ ] Usuarios y roles/permisos. - [ ] Recursos (si la agenda depende de cabinas/salas/equipos). - [ ] Membresías (si vende planes recurrentes). - [ ] Compras y proveedores (si controla abasto y margen). - [ ] Comisiones (reglas, metas y liquidaciones). - [ ] Formularios y consentimientos. - [ ] Reservas en línea (activar y difundir el enlace). - [ ] Notificaciones en modo prueba → revisar textos → encender. - [ ] Tickets: formato y secciones. - [ ] Licencia: aplicar la clave del plan contratado. - [ ] API / Webhooks si se integra con terceros. - [ ] Confirmar que las credenciales del admin se cambiaron. ## Estado del producto por fases Todas las fases están **entregadas**. | Fase | Alcance | Estado | |---|---|---| | 1 | Capa de configuración (terminología, sucursales, categorías, ajustes, colores, horarios, URLs de pago), defaults neutros, provisioning de instancias | Entregado | | 2.1 | Roles y permisos editables | Entregado | | 2.2 | Impuestos configurables | Entregado | | 2.3 | Portal público de reservas en línea | Entregado | | 2.4 | Recordatorios y notificaciones automáticas | Entregado | | 2.5 | Formularios digitales y consentimientos con firma y fotos | Entregado | | 2.6 | Membresías y suscripciones | Entregado | | 3.1 | Recursos físicos en la agenda | Entregado | | 3.2 | Compras y proveedores | Entregado | | 3.3 | Comisiones por reglas y liquidación | Entregado | | 3.4 | PWA instalable y branding por instancia | Entregado | | 3.5 | Licenciamiento por plan, API keys gestionables y webhooks | Entregado | | 3.6 | i18n español/inglés | Entregado | | Operación | Backups automáticos verificados y panel/CLI multi-instancia | Entregado | Los pendientes y limitaciones conocidos (los que aún no están cerrados) viven en [`limitaciones-y-pendientes.md`](limitaciones-y-pendientes.md).