# NOVASIS: Vertical Gimnasios (producto multisede · primer cliente: 1 sede)

> **Cliente piloto**: **Fly Fitness – Gym & Spa** (1 sede)
> **Versión**: 0.5 (09/11/2026). Agrega la **agenda y facturación del spa** (sección 6.1) · 5 pendientes menores del cliente (sección 14) · **Estado**: listo para pasar a tickets (F0–F3 y F4)
> **Implementación**: F0, F1, F2a (MVP de demo), turnos y tablet sin sesión hechas en `feat/gimnasio` (03–06/11/2026). Desde el 10/11 se migran a la UI nueva y el spa de la v0.5 se construye directo ahí. Seguimiento, decisiones de implementación y lo que se tocó del ERP: **§15**.
> **Directorio backend**: `src/gimnasio/` · **Prefijo de tablas**: `gym_` · **Módulos de suscripción**: `GYM_ESENCIAL`, `GYM_PRO`
> **Tipo**: vertical, igual que Inmobiliario y Taller: tablas propias y reutiliza Clientes, Productos, POS/Caja, Lista de precios, Facturación SIFEN, Inventario, Tesorería, Contabilidad (CONT-MA), CRM 360 y RRHH.
> **Criterio de diseño**: es un **producto** para vender a muchos gimnasios. Todo lo que este cliente no usa (matrícula, promociones, congelamiento, gracia, bloqueo, comisiones, devengamiento, varias sedes) **existe como configuración apagada**, no como desarrollo a medida.

### Cambios de la v0.5 (spa: carta de servicios + agenda en cuaderno)

| Tema | Lo que muestran la carta, el cuaderno y el cliente | Impacto en el diseño |
|---|---|---|
| Catálogo | 10 servicios con precio: 7 tratamientos de 50 min, Día Spa, Hidromasaje (25 min) y Sauna | Se precargan en F0 como productos `SERVICIO` con precio en la lista de precios (sección 6.1.2). |
| Precio y cantidad | "Pongo el precio por unidad y al agendar la cantidad" | **Cada servicio tiene una unidad de tiempo y un precio por unidad. Al agendar se elige la cantidad.** Duración = cantidad × unidad; importe = cantidad × precio. |
| Hora y media | Masaje de 50 min + 25 min extra, a **mitad de precio** | **Cantidad 1,5** del masaje (75 min). Ej.: Relax 1,5 × 130.000 = **Gs. 195.000**. No hace falta un producto "extensión". |
| Grilla | Masajes e hidromasaje se agendan en bloques de 25 min | Agenda con **bloques de 25 min**: L–V 14:00–21:30, sáb. 14:00–20:00. |
| Recursos | Cuaderno con 2 columnas = 2 cabinas; hidromasaje para **1 persona por turno** | 3 recursos: **Cabina 1, Cabina 2, Hidromasaje** (capacidad 1). |
| Cobro | **Al terminar el servicio** | El turno se reserva sin pago. Al terminar, "Cobrar" abre el POS con todo cargado y factura (reemplaza la columna "Fac" del cuaderno). |
| Masajistas | **Cobran por masaje realizado** | Tarifa por masajista y tratamiento (monto o %), con **liquidación de masajistas** por período (sección 6.1.6). Cambia lo dicho en la v0.2 ("sin comisiones"), que sigue valiendo para recepción e instructores. |

### Cambio de la v0.4

| Tema | Pedido | Impacto en el diseño |
|---|---|---|
| Aviso de vencimiento | **Enviar por email el vencimiento de la cuota mensual** | Nueva sección **7.1**. Email automático con la cuenta de correo de la empresa (`empresas_correo`, ya existe). **Pasa a F1** (no depende del proveedor de WhatsApp). El email del socio se pide en el alta (recomendado, no obligatorio). |

### Cambios de la v0.3 (pendientes cerrados)

| Tema | Respuesta del cliente | Impacto en el diseño |
|---|---|---|
| Renovación tarde | **Siempre desde la fecha de vencimiento** | `renovacion_desde = FIN_ANTERIOR` fijo para este cliente. Los días que entrenó vencido quedan dentro del período nuevo. |
| Pilates | **2 horarios por semana**; poder crear más | 2 filas en `gym_horarios_plantilla`; recepción o el gerente agregan horarios sin programar nada. |
| Masajes | **2 cabinas** | 2 cabinas (`gym_salas` tipo `CABINA`). Hasta 2 masajes simultáneos; la agenda impide superponer turnos en la misma cabina o con el mismo profesional. |
| Sauna | **Se paga por hora** (además de estar incluida en el plan) | Nueva modalidad de servicio **`POR_TIEMPO`** (sección 4.1): se cobra por horas en el POS y recepción ve un contador con aviso al vencer el tiempo. |
| Menores | **No se registra al tutor; desde 13 años** | `menor_requiere_tutor = false`, nuevo `edad_minima = 13`. El alta rechaza a un menor de 13 y marca "Menor" en la ficha. La factura sale a nombre de quien paga (cliente del POS), aunque no quede vinculado como tutor. |
| Equipos | **PC en recepción, sin molinete** | Se recomienda un **lector 2D USB** (sección 5.1), que funciona como el escáner de códigos que ya usa el POS. Cámara web solo para la foto. El molinete queda en F4, como opción a futuro. |

### Cambios respecto a la v0.1 (respuestas del cliente)

| Tema | Respuesta del cliente | Impacto en el diseño |
|---|---|---|
| Sedes | **1 sede**, sin proyección de más. El producto debe soportar cadenas | La empresa arranca con 1 sede (sin selector de sede visible). El modelo multisede queda completo para otros clientes. |
| Razón social / franquicias | Preparado para **todos los escenarios** | Nueva sección **4.4**, con 4 escenarios: 1 empresa con 1 sede, 1 empresa con N sedes, N empresas de un mismo dueño y franquicias. Se agrega la **Red de gimnasios** (`gym_redes`) para el acceso entre empresas. |
| Migración | El cliente no tiene sistema; preparar para futuros clientes | Nueva sección **4.5: importador genérico** de socios, membresías vigentes y saldos (Excel/CSV, plantilla, simulación previa, informe de errores). |
| Planes | **Mensual Gs. 230.000** (musculación + sauna). Servicios aparte: **masajes, sauna, pilates** | Plan `PERIODO` con actividades incluidas. Los servicios aparte son **servicios adicionales** (sección 4.1): venta suelta o en paquete, y con **agenda** cuando hay turno o cupo (masajes, pilates). |
| Matrícula / promociones | No usa; preparado | `requiere_matricula = false`. Promociones vía `ofertas-promociones`, sin uso en este cliente. |
| Congelamiento | No usa | `congelamientos_max = 0`: el botón no aparece. |
| Vencimiento | **Sin gracia, sin bloqueo, solo aviso** | Nuevo parámetro **`modo_vencido` = AVISAR \| GRACIA_Y_BLOQUEO \| BLOQUEAR**. Este cliente usa `AVISAR`: entra con semáforo amarillo "Vencido – cobrar hoy" y queda registrado. Nuevo reporte **"Ingresos con plan vencido"** para controlar la fuga. |
| Menores | Se admiten, sin apto físico | `admite_menores = true`, `apto_fisico_modo = OFF`. Tutor: dato opcional (ver pendiente 3). |
| Trainers | Arreglan sus clases por su cuenta | **El personal trainer queda fuera del sistema** en este cliente. El tipo de actividad `PT` se mantiene para otros clientes. |
| Instructores / recepción | **Salario fijo**, sin comisiones | No hay liquidación por clase dentro del vertical. Se pagan por **RRHH** (o por el sistema actual de sueldos hasta que RRHH esté). Comisiones apagadas. |
| Productos | Venden suplementos/bebidas | POS + Inventario con depósito de la sede (ya existe). |
| Contabilidad | Reconocimiento **al facturar** | `diferir_ingresos = false`. El devengamiento queda como opción para otros clientes (backlog). |
| GYM_PRO | **Sí** al débito automático y al molinete | Se ofrece desde el inicio. **F4 pasa a ser una fase planificada** con cronograma (sección 13). |

### Respuestas iniciales (v0.1, siguen vigentes salvo lo que ajusta la tabla anterior: escala, gracia/bloqueo y débito automático)

| Tema | Respuesta | Impacto en el diseño |
|---|---|---|
| Tipo y escala | **Cadena multisede** | Cada sede = sucursal NOVASIS (timbrado/punto de expedición, caja y depósito propios). Planes con **sede base** o **acceso a todas las sedes**. Reportes consolidados y por sede. |
| Acceso | **QR desde la app** + **manual en recepción** | **QR dinámico** (rota cada 30 s, no sirve una captura de pantalla) leído con la cámara de la tablet/PC de recepción. Respaldo manual por CI o nombre **con foto del socio en pantalla**. Sin molinete en v1 (queda preparado: ver F4). |
| Cobro | **En recepción: efectivo/POS** | La membresía se vende **en el POS** como un producto más → factura SIFEN contado. **Sin débito automático en v1**. Modelo **prepago por período**: al vencer, el acceso se bloquea tras los días de gracia. Recordatorios de vencimiento por WhatsApp para traer al socio a la caja. |
| App socio | **Básica** | PWA con login por CI + código: **QR de acceso, reserva de clases, estado de membresía y facturas, historial de asistencia**. Rutinas, progreso y pagos en la app quedan para GYM_PRO. |

---

## 1. Resumen ejecutivo

El objeto central es la **Membresía**: un socio compra un **plan** (mensual, trimestral, anual, pase diario o paquete de clases) en cualquier sede, lo paga en caja y recibe la factura SIFEN. La membresía define **hasta cuándo**, **en qué sedes**, **en qué horarios** y **cuántas clases** puede usar.

Todo lo demás cuelga de ahí:

```
Lead (CRM) → Visita/clase de prueba → Alta del socio → Venta del plan en POS (factura SIFEN)
   → Membresía ACTIVA → Check-in (QR o recepción) + Reservas de clases
   → Aviso de vencimiento (WhatsApp) → Renovación en caja | Vencida → Gracia → Bloqueo
   → Riesgo de abandono (IA) → Campaña de recuperación (CRM)
```

El diferencial frente a un software de gimnasio genérico es que **todo pasa por el ERP**: la venta de la membresía es una factura SIFEN normal, la caja de recepción es la caja del POS, los suplementos descuentan stock del depósito de la sede, los instructores cobran por RRHH y el contador ve los asientos sin cargar nada.

---

## 2. Referencias de mercado

| Sistema | Segmento | Qué tomamos |
|---|---|---|
| **ABC Glofox / ABC Evo** (EE. UU./Irlanda) | Estudios y cadenas, escala a 2.000 sedes | App del socio como canal principal (reserva, check-in, cuenta). Control central de marca y precios con reportes consolidados por sede. |
| **PerfectGym** (Polonia) | Cadenas multiclub | Datos del socio únicos para toda la red, **acceso por QR/RFID sin personal**, app de empleados, detección de socios en riesgo de abandono. |
| **Mindbody** (EE. UU.) | Estudios boutique, wellness | Agenda de clases con **cupo y lista de espera**, paquetes de clases (créditos), venta retail en mostrador. |
| **Fitco** (Latinoamérica) | Gimnasios LatAm | Check-in por **QR en la app** o huella, POS integrado, control de caja, **pago automático a profesores y vendedores**, mensajes automáticos de renovación y cumpleaños, app con la marca del gimnasio. |
| **Wodify / PushPress** | Boxes funcionales | Registro de entrenamientos, marcas personales y rankings (idea para GYM_PRO). |
| **Smart Fit** (competidor local) | Cadena low-cost en PY | Dos niveles de plan: **sede base** vs **todas las sedes + invitados** (plan Black). Rutinas cargadas por el entrenador y visibles en la app. |

**Datos de retención que guían el diseño**

- La retención anual promedio de la industria es de **~66%**: 1 de cada 3 socios se va cada año (Health & Fitness Association, 2025). Cerca de la mitad de los nuevos abandona en los primeros 6 meses.
- **Señales tempranas de abandono**: no formar una rutina semanal en las semanas 3–4; un arranque fuerte que se cae; **14 días sin check-in**. Meta de arranque: **4 visitas en las primeras 4 semanas**; hábito sostenible: ~2 visitas por semana.
- Conclusión: el **check-in es el dato más valioso del sistema**. Por eso el acceso por QR registra todo, y la IA de retención (F3) trabaja sobre esa información.

---

## 3. Mapa de integración con NOVASIS

| Módulo NOVASIS | Uso en el gimnasio | Qué recibe del vertical / qué le entrega | Estado NOVASIS | Fase |
|---|---|---|---|---|
| **Empresas / Sucursales** | Cada sede = sucursal con timbrado y punto de expedición | `gym_sedes.sucursal_id` | ✅ | F0 |
| **Holding / suscripciones SaaS** (`plan-suscripciones-escalable`) | Grupos con varias razones sociales y franquicias | `gym_redes` agrupa empresas para el acceso cruzado y los reportes de red | Fase 2 de migración | F5 (Red) |
| **Clientes** | El socio es un cliente (CI o RUC para la factura) | `gym_socios.cliente_id`; alta rápida socio + cliente en un solo formulario | ✅ | F0 |
| **Productos** | Planes de membresía como productos tipo `SERVICIO_MEMBRESIA`; suplementos, bebidas y accesorios como productos con stock | `gym_planes.producto_id` | ⚠️ backend ✅, frontend básico | F0 |
| **Lista de precios** | Precio de cada plan por sede o lista (corporativo, estudiante, promoción) | **Nunca** se hardcodea el precio del plan | ✅ | F0 |
| **POS / Ventas + Caja** | Recepción vende y renueva membresías, pases diarios y productos en la **caja de la sede** | Al facturar una línea `SERVICIO_MEMBRESIA`, el POS llama a `GymMembresiasService.activarDesdeVenta()` | ⚠️ F1 85% | F1 (**dependencia crítica**) |
| **Facturación SIFEN** | Factura contado por cada venta. Anulación con evento ECAN → la membresía se anula | `gym_membresias.factura_id` | ✅ | F1 |
| **Ofertas y promociones** | Matrícula bonificada, 2×1, descuento por referido | Se aplican en el POS sobre el producto plan | ✅ (`ofertas-promociones`) | F1 |
| **Inventario** | Stock de suplementos/bebidas por depósito de sede | `movimientos_inventario` normales del POS (nada nuevo) | ✅ | F1 |
| **Tesorería** | Cierre de caja por sede, depósitos bancarios, POS bancario | Sin cambios; reportes de recaudación por sede | ✅ mayormente | F1 |
| **Cobranzas** | Solo para **convenios corporativos** a crédito (empresa paga los socios de sus empleados) | Factura a crédito mensual a la empresa del convenio | ⚠️ parcial | F4 (opcional) |
| **CRM 360** | Leads (visitas, prueba gratis, Instagram/WhatsApp), pipeline de venta de planes, campañas de renovación y recuperación de ex-socios, WhatsApp | El vertical publica eventos: `gym.membresia.por_vencer`, `gym.membresia.vencida`, `gym.socio.riesgo_alto`, `gym.clase.no_show` | ❌ Fase 0 pendiente | F3 (avisos básicos de WhatsApp en F2 sin CRM) |
| **RRHH** | **Este cliente**: instructores y recepción con salario fijo, liquidación normal (IPS). **Otros clientes**: pago por clase/hora y comisiones | Este cliente: solo la FK `gym_instructores.empleado_id` (y la asistencia del biométrico si se usa). Otros: exporta clases dictadas y comisiones a `rrhh_comisiones_pendientes` | ❌ pendiente | Independiente (no bloquea el vertical) |
| **Vendedores / comisiones** | Este cliente **no** usa comisiones. Otros: asesores de venta de planes | `vendedor_id` opcional en la venta; comisión apagada por configuración | ✅ | F1 (apagado) |
| **Contabilidad (CONT-MA)** | Ingresos por membresías y servicios **al facturar** (este cliente). Devengamiento solo como opción | Eventos de la sección 8 | ✅ | F3 (opcional) |
| **IA Dashboard / Soporte IA** | Riesgo de abandono, consultas en lenguaje natural ("¿cuántos socios activos tiene la sede Lambaré?") | Vistas read-only `gym_v_*` | ⚠️ parcial | F3–F4 |
| **Bancard vPOS** | **GYM_PRO (el cliente lo quiere)**: pago en la app, tarjeta guardada (token) y **débito automático mensual** | Cobro aprobado → factura SIFEN + renovación automática; rechazado → reintentos y aviso | Planificado (`plan-bancard-vpos-compra-asistida`) | F4 |
| **Molinete / control de puerta** | **GYM_PRO (el cliente lo quiere)**: el molinete abre con QR o rostro si el acceso es válido | Lector QR en el molinete o terminal Hikvision (mismo conector de DS-K1T343MFWX); relé controlado por el servidor | ✅ conector en RRHH | F4 |
| **TURNE APP** | Canal de captación: reserva de clase de prueba o de evaluación con PT, que entra como lead | Endpoint externo TURNE → CRM | ✅ en deploy | F4 |
| **API pública / Webhooks** | Integraciones futuras (apps de entrenamiento, wearables) | Eventos `gym.*` | Spec v1 | F4 |

---

## 4. Conceptos y reglas de negocio

### 4.1 Planes (catálogo central, precio por lista)

| Tipo de plan | Ejemplo | Cómo se consume |
|---|---|---|
| `PERIODO` | Mensual, trimestral, semestral, anual | Acceso libre entre `fecha_inicio` y `fecha_fin` |
| `PASE` | Pase diario, semanal | Igual que período, de 1 a 7 días |
| `CREDITOS` | Pack de 10 clases de spinning (vence a los 60 días) | Cada reserva o check-in a clase descuenta 1 crédito |
| `MIXTO` | Mensual + 8 clases de pilates | Acceso libre + créditos para clases premium |

**Plan de este cliente**: `Mensual` · tipo `PERIODO` · 1 mes · actividades incluidas: musculación + sauna · Gs. 230.000 (precio en la lista de precios, no en el plan).

**Servicios de este cliente**: el **spa** (7 tratamientos, Día Spa, hidromasaje y sauna), detallado en la **sección 6.1**, más **Pilates** (`CLASE`, 2 horarios semanales iniciales, ampliables).

**Regla general de precio** (todos los servicios): `importe = cantidad × precio por unidad` y `duración = cantidad × unidad_min`. La cantidad admite fracciones según `fraccion_minima` del servicio (0,5 en masajes). El precio por unidad sale **siempre de la lista de precios**.

**Servicios adicionales** (este cliente: **masajes, sauna suelta, pilates**). Son productos `SERVICIO` que se venden en el POS, con o sin plan. Cada uno se configura:

| Modalidad | Uso | Ejemplo |
|---|---|---|
| `VENTA_SIMPLE` | Se cobra y se usa en el momento, sin agenda | Una bebida, una toalla |
| `POR_TIEMPO` | Se cobra por hora o fracción y se controla el tiempo de uso | **Sauna por hora** (este cliente): se venden N horas en el POS; en la pantalla Recepción, "Iniciar sauna" registra la hora de inicio y muestra un contador con aviso al terminar. Capacidad máxima simultánea configurable |
| `TURNO` | Sesión con cupo 1, con profesional y horario (usa el motor de la sección 6) | Masaje de 50 min con la masajista X |
| `CLASE` | Sesión con cupo N y reservas | Pilates, con cupo de la sala |
| `PAQUETE` | Plan tipo `CREDITOS` que descuenta 1 crédito por uso | 8 clases de pilates por mes |

Si el servicio está incluido en el plan (ej. sauna en el plan mensual), el socio no paga; si no, recepción lo cobra en el POS o descuenta un crédito.

Atributos del plan: **alcance de sedes** (`SEDE_BASE` | `TODAS` | `LISTA` de sedes), **franja horaria** (ej. plan "Mañana" de 06:00 a 14:00), **actividades incluidas** (musculación, clases grupales, clases premium), **invitados por mes**, **cantidad de congelamientos permitidos y días máximos**, **matrícula** (producto aparte, cobrada solo en el alta), **días de gracia**, si es **renovable** y si admite **menores**.

### 4.2 Reglas

1. **No hay membresía sin factura**. La membresía nace `ACTIVA` cuando el POS factura la línea del plan. (Única excepción, con permiso, motivo y reporte: el plan que el socio ya pagó antes del sistema, §15.12.) Si la factura se cancela (ECAN), la membresía queda `ANULADA` y el acceso se bloquea.
2. **Renovación anticipada encadena**. Si el socio renueva antes del vencimiento, la nueva membresía arranca el día siguiente al fin de la actual (no se pierden días).
3. **Vencimiento** según `gym_config.modo_vencido`:
   - `AVISAR` (**este cliente**): al vencer pasa a `VENCIDA`, pero **el acceso se permite** con semáforo amarillo "Vencido hace N días – cobrar hoy". Cada ingreso queda registrado como `ALERTA_VENCIDA` y aparece en el reporte "Ingresos con plan vencido".
   - `GRACIA_Y_BLOQUEO`: `EN_GRACIA` durante N días con aviso; después se rechaza.
   - `BLOQUEAR`: se rechaza desde el día siguiente al vencimiento.
3b. **Fecha de inicio al renovar tarde** (`gym_config.renovacion_desde`): `FIN_ANTERIOR` (el nuevo mes arranca el día siguiente al vencimiento, así los días que entrenó vencido no quedan gratis) o `FECHA_PAGO`. **Este cliente: `FIN_ANTERIOR` siempre** (confirmado).
4. **Congelamiento** (este cliente: **apagado**, `congelamientos_max = 0`). Para otros clientes: por viaje o lesión, dentro del límite del plan; corre la `fecha_fin` por la misma cantidad de días; requiere permiso `GYM_CONGELAR` y motivo. Un certificado médico se adjunta como archivo, **sin registrar el diagnóstico**.
5. **Cambio de plan (upgrade)**. Se cobra la diferencia prorrateada en el POS (producto "Diferencia de plan"); la membresía anterior queda `REEMPLAZADA`. Un downgrade solo aplica al renovar (sin devoluciones).
6. **Transferencia de membresía** a otra persona: configurable (default no permitida). Si se permite, cobra un cargo y queda en el historial.
7. **Un socio puede tener solo una membresía de acceso vigente**, más paquetes de créditos en paralelo.
8. **Sede**: en un plan `SEDE_BASE`, el check-in en otra sede se rechaza, salvo un "pase de visita" (cantidad por mes configurable).
9. **Menores de 18** (este cliente: **desde 13 años, sin registrar tutor**). `gym_config.edad_minima` rechaza el alta por debajo de la edad mínima (por eso la fecha de nacimiento es obligatoria). `menor_requiere_tutor` (false en este cliente) permite a otros clientes exigir el tutor y la autorización firmada. La ficha muestra la marca "Menor" hasta que cumple 18.
10. **Apto físico / declaración de salud** (este cliente: **no se pide**, `apto_fisico_modo = OFF`). Para otros clientes: documento adjunto con vencimiento y alerta o bloqueo. **No se registran datos clínicos**, solo "presentado / vence el …".
11. **Nada se borra**: membresías anuladas con motivo, historial completo de estados y auditoría global de NOVASIS.

### 4.3 Estados de la membresía

```
PENDIENTE (venta en curso) → ACTIVA ⇄ CONGELADA
                               │
                               ├─► EN_GRACIA ─► VENCIDA ─► (renueva) nueva membresía
                               ├─► REEMPLAZADA (upgrade)
                               └─► ANULADA (factura cancelada / baja con motivo)
(EN_GRACIA solo existe con modo GRACIA_Y_BLOQUEO; CONGELADA solo si congelamientos_max > 0)
```

### 4.4 Escenarios de sedes, razones sociales y franquicias

| # | Escenario | Cómo se modela | Socio | Facturación | Acceso entre sedes |
|---|---|---|---|---|---|
| **A** | 1 empresa, 1 sede (**este cliente**) | 1 empresa NOVASIS, 1 `gym_sedes` | Único | Timbrado de la sucursal | — (selector de sede oculto) |
| **B** | 1 empresa, N sedes | 1 empresa, N sedes = N sucursales | Único en la empresa | Cada sede con su punto de expedición, o todas con el mismo | Por alcance del plan (`SEDE_BASE`, `TODAS`, `LISTA`) |
| **C** | N empresas del mismo dueño (razones sociales distintas) | N empresas NOVASIS agrupadas en un **holding** + una **`gym_red`** | Uno por empresa, **vinculados por CI** dentro de la red | Cada empresa factura lo que vende con su propio RUC | El plan "Red" de la empresa X habilita el check-in en las sedes de Y. La sede que recibe valida contra la membresía de la empresa emisora vía **servicio interno de red** (sin compartir datos fiscales) |
| **D** | Franquicias (franquiciante + franquiciados) | Cada franquiciado es una empresa; la franquiciante es dueña de la red | Igual que C | Cada franquiciado factura a sus socios. **Regalías** (% de la facturación de membresías) = factura de la franquiciante al franquiciado, generada con un reporte mensual (F5) | Según el acuerdo de la red (`gym_red_acuerdos`): permitido, con cupo de visitas o no permitido. Registro de **visitas de otras empresas** para compensar entre ellas |

**Reglas multiempresa**
- La regla de NOVASIS se mantiene: **toda tabla filtra por `empresa_id`**. El acceso cruzado (C/D) **no** lee tablas de otra empresa: llama a `GymRedService.validarAccesoExterno(ci, empresa_emisora_id)`, que responde solo `PERMITIDO/RECHAZADO + nombre + foto + plan`.
- La red solo comparte lo mínimo: CI, nombre, foto, estado de la membresía y alcance. Ni montos ni facturas.
- Catálogo de planes **centralizado opcional** en la red (la franquiciante define los planes y el precio sugerido; cada franquiciado lo puede ajustar con su lista de precios si el acuerdo lo permite).
- Reporte consolidado de red para el dueño o la franquiciante: socios activos, check-ins e ingresos por empresa y sede.

### 4.5 Migración desde otros sistemas (para futuros clientes)

Este cliente arranca de cero: se cargan los socios en el alta. Para los siguientes clientes, el importador genérico (`/gym/importar`) funciona así:

1. **Plantillas Excel/CSV** descargables: **Socios** (CI, nombre, teléfono, email, fecha de nacimiento, sede base, tutor), **Membresías vigentes** (CI, plan, fecha de inicio, fecha de fin, créditos restantes, monto pagado), **Saldos pendientes** (opcional) y **Planes**.
2. **Mapeo de columnas** guardable por origen (planillas propias y exportaciones de otros sistemas del mercado), para reutilizarlo con el próximo cliente que venga del mismo sistema.
3. **Simulación** sin grabar: informe de filas válidas, duplicadas (misma CI), con errores (CI inválida, plan inexistente, fechas incoherentes) y avisos.
4. **Importación** en una transacción por lote, con `gym_importaciones` (quién, cuándo, archivo, resultados) y **reversa del lote** si algo salió mal (solo si las membresías importadas aún no tienen movimientos).
5. Las membresías importadas quedan con `origen = MIGRACION` y **sin factura** (fueron cobradas en el sistema anterior). Las fotos se toman en el primer check-in.
6. Los saldos pendientes se migran como deuda en Cobranzas (CxC inicial), no como facturas.

---

## 5. Control de acceso (QR + recepción)

### 5.1 QR dinámico

- La app genera un QR con `socio_id + timestamp + firma HMAC` (patrón TOTP), que **rota cada 30 segundos**. Una captura de pantalla compartida deja de servir enseguida.
- Funciona **sin conexión en el celular** (el secreto se descarga al iniciar sesión), así el socio entra aunque no tenga datos móviles.
- La **pantalla de recepción** (`/gym/acceso`) valida en el servidor. Dos formas de leer el QR:
  - **Lector 2D USB (recomendado para este cliente, que tiene PC)**: lee la pantalla del celular en menos de 1 segundo, también con poco brillo, y entra como teclado. Es el mismo mecanismo que el escáner del POS (`BARCODE_SCAN_THRESHOLD_MS`), así que la pantalla solo necesita el foco en el campo de lectura. Costo de referencia: un lector 2D de mostrador (presentation scanner) apto para pantallas.
  - **Cámara web** (librería `html5-qrcode` o similar): sirve como alternativa sin hardware extra, pero es más lenta para leer pantallas de celular. En este cliente la cámara web se usa **para la foto del socio** en el alta.

### 5.2 Validación (un solo endpoint: `POST /gym/accesos/validar`)

```
1. Firma y vigencia del QR (±60 s)          → si falla: RECHAZADO_QR_INVALIDO
2. Socio activo y no suspendido             → RECHAZADO_SOCIO_SUSPENDIDO
3. Membresía vigente (ACTIVA o EN_GRACIA)   → según modo_vencido: AVISAR → ALERTA_VENCIDA (entra, amarillo, botón "Cobrar renovación")
                                               BLOQUEAR → RECHAZADO_VENCIDA (muestra botón "Renovar en caja")
4. Sede permitida por el plan               → RECHAZADO_SEDE (ofrece pase de visita si le quedan)
5. Franja horaria del plan                  → RECHAZADO_HORARIO
6. Anti-passback: no hay otro ingreso en los últimos N minutos  → ALERTA (no bloquea)
7. Apto físico vigente (si está configurado) → ALERTA o RECHAZO
→ PERMITIDO: registra gym_accesos y muestra foto grande + nombre + plan + días restantes
```

La recepción **siempre ve la foto del socio** en grande para verificar que es la misma persona.

### 5.3 Check-in manual

Búsqueda por CI, nombre o teléfono → misma validación → registro con `metodo = MANUAL` y el usuario de recepción. Es el respaldo si el socio no tiene la app o el celular.

### 5.4 Invitados y pases

- Invitado de un socio (si su plan lo incluye): se registra con nombre y CI y descuenta su cupo mensual.
- Pase diario de un no-socio: se vende en el POS y genera una membresía `PASE` de 1 día con un QR impreso en el ticket.

---

## 6. Clases grupales y reservas

- **Actividades** (spinning, funcional, pilates, zumba…), **salas** por sede con capacidad e **instructores**.
- **Horario semanal recurrente** por sede (plantilla), que genera las **sesiones** concretas con 4 semanas de anticipación. Se puede editar una sesión puntual: cambio de instructor, cancelación con aviso a los reservados.
- **Reserva** desde la app o en recepción: valida membresía, actividad incluida en el plan (o crédito disponible) y cupo. Si no hay cupo, **lista de espera** con promoción automática cuando alguien cancela (aviso push/WhatsApp).
- **Ventana de reserva** configurable (ej. desde 48 h antes) y **cancelación sin penalidad** hasta X horas antes.
- **No-show**: si reservó y no hizo check-in, cuenta una falta. Con N faltas en 30 días, se bloquea la reserva por X días (configurable). Con créditos, el crédito se consume igual.
- **Check-in a la clase**: el instructor marca la asistencia desde su celular (vista de la lista) o se toma automáticamente del ingreso a la sede.
- **Turnos de servicios** (este cliente: **masajes, 2 cabinas**): la misma agenda con cupo 1, por profesional y cabina. No se pueden superponer turnos en la misma cabina ni con el mismo profesional. Recepción agenda o el socio reserva desde la app; el cobro se hace en el POS (o se descuenta un crédito del paquete).
- **Pilates** (este cliente): actividad tipo `CLASE` con cupo de la sala, vendida aparte (clase suelta o paquete). No está incluida en el plan mensual. Arranca con **2 horarios semanales** en la plantilla; el gerente agrega más desde la pantalla de horarios (permiso `GYM_CLASES_GESTIONAR`), sin intervención de desarrollo.
- **Personal trainer**: **fuera del alcance en este cliente** (los trainers coordinan por su cuenta). Para otros clientes, sesiones 1 a 1 como paquetes `PT` con la agenda del entrenador.

---

### 6.1 Spa: agenda, reserva y facturación (Fly Fitness Gym & Spa)

#### 6.1.1 Situación actual

- **Carta de servicios** impresa con precios. Los turnos se piden por teléfono (0986-700572).
- **Agenda en cuaderno**: una hoja por día con **dos bloques, uno por cabina**. Cada bloque tiene filas por hora (de 14 a 20) y las columnas **Hora · Nombre y apellido · Tratamiento · Tpo · Teléfono · Fac**, con un **Total** del día por cabina al pie.
- **Problemas que resuelve el sistema**: superposición de turnos, servicios realizados que no se facturan (la columna "Fac" se llena a mano), cierre del día sumado a mano, liquidación de masajistas sin respaldo y nada de historial por cliente.

#### 6.1.2 Catálogo precargado (precios a hoy, editables en la lista de precios)

| Servicio | Modalidad | Recurso | Unidad | Precio por unidad | Fracción | Incluye en el día |
|---|---|---|---|---|---|---|
| Masaje Relax | `TURNO` | Cabina + masajista | 50 min | Gs. 130.000 | 0,5 (25 min) | Sauna húmedo, seco y piscina |
| Masaje Descontracturante | `TURNO` | Cabina + masajista | 50 min | Gs. 150.000 | 0,5 | Sauna húmedo, seco y piscina |
| Drenaje linfático | `TURNO` | Cabina + masajista | 50 min | Gs. 150.000 | 0,5 | Sauna húmedo, seco y piscina |
| Reductor | `TURNO` | Cabina + masajista | 50 min | Gs. 150.000 | 0,5 | Sauna húmedo, seco y piscina |
| Contractor | `TURNO` | Cabina + masajista | 50 min | Gs. 70.000 | 0,5 | Sauna húmedo, seco y piscina |
| Baño de luna | `TURNO` | Cabina + masajista | 50 min | Gs. 130.000 | 0,5 | Sauna húmedo, seco y piscina |
| Pulido corporal | `TURNO` | Cabina + masajista | 50 min | Gs. 150.000 | 0,5 | Sauna húmedo, seco y piscina |
| Hidromasaje (adicional) | `TURNO` | Hidromasaje (1 persona) | 25 min | Gs. 20.000 | 1 | — |
| Día Spa | `VENTA_SIMPLE` + pase del día | (Hidromasaje, ver pendiente 1) | Día | Gs. 50.000 | 1 | Sauna húmedo, seco, hidromasaje y piscina |
| Sauna | `POR_TIEMPO` | Sauna (capacidad configurable) | 60 min | Gs. 30.000 | 1 | — |

**Ejemplos de cantidad al agendar**

| Pedido del cliente | Se carga | Duración | Importe |
|---|---|---|---|
| Masaje relax | Relax × 1 | 50 min (2 bloques) | 130.000 |
| Masaje relax "hora y media" | Relax × **1,5** | 75 min (3 bloques) | **195.000** |
| Descontracturante de 100 min | Descontracturante × 2 | 100 min (4 bloques) | 300.000 |
| Hidromasaje 50 min | Hidromasaje × 2 | 50 min | 40.000 |
| Combo: relax + hidromasaje | Relax × 1 (cabina) **seguido de** Hidromasaje × 1 | 50 + 25 min, encadenados | 150.000 |

En la factura, la línea sale como *"Masaje relax (50 min) – cant. 1,5 – Gs. 130.000 – Gs. 195.000"*. SIFEN admite cantidades con decimales.

#### 6.1.3 Agenda (la pantalla que reemplaza al cuaderno)

- **Vista del día con una columna por recurso** (Cabina 1 · Cabina 2 · Hidromasaje), igual que el cuaderno pero digital. Filas en **bloques de 25 min**: L–V 14:00–21:30 y sáb. 14:00–20:00 (`gym_config.horario_spa`, por día de la semana; el domingo queda cerrado, editable). También hay vista de semana y una vista por masajista.
- Cada **tarjeta** muestra nombre, teléfono, tratamiento, cantidad/duración, masajista y el **estado de cobro** (en lugar de la columna "Fac": *pendiente* o *factura 001-001-0000123*).
- **Total del día por cabina** y total general al pie, como en el cuaderno, pero calculados: los realizados, los facturados y la diferencia.
- Arrastrar una tarjeta mueve el turno; estirarla cambia la cantidad en pasos de 25 min (siempre que el siguiente bloque esté libre).

#### 6.1.4 Reserva (por teléfono, en recepción; desde la app en F2)

1. **Buscar al cliente** por teléfono, nombre o CI. Si no existe: **alta rápida con nombre + teléfono**. No hace falta que sea socio del gym: es un cliente NOVASIS común, y el RUC/CI se completa al facturar.
2. Elegir **tratamiento y cantidad** (1 · 1,5 · 2 …). El sistema muestra la duración y el importe estimado.
3. Elegir **día y hora**: muestra solo los huecos donde entra la duración completa en una cabina libre. Valida que el turno **termine antes del cierre** (un masaje de 50 min un día de semana empieza, como tarde, a las 20:40).
4. **Masajista**: opcional al reservar ("cualquiera") y **obligatorio al marcarlo como realizado**, porque de eso depende su liquidación. El sistema no permite superponer turnos de la misma cabina ni del mismo masajista.
5. Se pueden **agregar servicios encadenados** en la misma reserva (ej. hidromasaje al terminar el masaje), y también reservar para **2 personas a la misma hora** usando las 2 cabinas.
6. **Confirmación** por email (y por WhatsApp desde F2) y **recordatorio** el día anterior.

**Estados del turno**

```
RESERVADO ─► LLEGÓ (check-in: habilita sauna/piscina del día) ─► EN_CURSO ─► REALIZADO ─► FACTURADO
    │                                                                  ▲
    ├─► CANCELADO (con motivo, libera el hueco)                        └─ "Cobrar" en el POS
    └─► NO_SHOW (no vino; queda en la ficha del cliente)
```

#### 6.1.5 Facturación: se cobra al terminar

1. Al terminar, recepción toca **"Cobrar"** en el turno, o en la ficha del cliente si hizo varios servicios ese día.
2. Se abre el **POS** con el cliente y **todas las líneas pendientes del día** (tratamientos × cantidad, hidromasaje, sauna por hora y lo que haya consumido del bar). Se puede **corregir la cantidad real** si el servicio se extendió o se acortó (queda registrado quién lo cambió).
3. Se emite **una sola factura SIFEN contado** por cliente con cualquier medio de pago de la caja. Los turnos pasan a `FACTURADO` con el número de factura.
4. Si la factura se cancela (ECAN), los turnos vuelven a `REALIZADO – pendiente de cobro`.
5. **Control diario**: el cierre de caja muestra los **"Realizados sin facturar"**. No se puede cerrar la caja con turnos realizados sin cobrar sin justificar el motivo (cortesía, error…). Esto reemplaza el control a mano de la columna "Fac".
6. **Cortesías**: un turno se puede marcar como cortesía (precio 0) con el permiso `GYM_SPA_CORTESIA` y un motivo. Por defecto **no** genera pago al masajista (configurable).
7. **Los masajes incluyen el sauna y la piscina del día**: con el check-in del turno, el cliente queda habilitado ese día para el sauna y la piscina, aunque no sea socio (se registra en `gym_accesos` con `metodo = SERVICIO_SPA`).

#### 6.1.6 Liquidación de masajistas (cobran por masaje realizado)

- **Tarifa** por masajista y tratamiento: **monto fijo** por unidad (ej. Gs. 40.000 por cada 50 min) o **porcentaje** del importe facturado. Las fracciones se pagan proporcionales: un masaje de 1,5 cobra 1,5 × la tarifa.
- **Base de cálculo**: solo los turnos **`FACTURADO`** del período (configurable: fecha del servicio o fecha de la factura). Las cortesías y los no-shows no suman, salvo que se configure lo contrario.
- **Liquidación** semanal, quincenal o mensual: pantalla con el detalle por masajista (fecha, cliente, tratamiento, cantidad, importe facturado, tarifa, a pagar), aprobación del gerente y PDF para la firma.
- **Pago**, según cómo esté contratado cada masajista (pendiente 2):
  - **Independiente que factura** (honorarios): la liquidación aprobada genera un **gasto a pagar** en Compras & Gastos contra la factura del masajista, y se paga desde Tesorería.
  - **En planilla (IPS)**: la liquidación aprobada pasa a `rrhh_comisiones_pendientes` como concepto `COMISION_SERVICIOS` (plan de integración comisiones → RRHH). Mientras RRHH no esté, el PDF sirve para pagar por fuera.
- Reporte **"Productividad por masajista"**: turnos, horas, importe facturado, liquidado y ocupación de las cabinas.

## 7. App del socio (básica, PWA)

Misma tecnología que el POS y la app del técnico del Taller (React + PWA, funciona con mala señal). Se publica con la marca del gimnasio en la web y como acceso directo instalable. Las tiendas de apps quedan como opción en F4, con el pipeline de TURNE.

| Pantalla | Contenido |
|---|---|
| **Inicio** | **QR de acceso** grande (con brillo al máximo), plan, días restantes, sede base, botón "Renovar" (muestra las sedes y horarios de caja; el pago online queda para Pro) |
| **Clases** | Horario por sede y día, cupos libres, reservar, cancelar, lista de espera, mis reservas |
| **Mi cuenta** | Membresías (actual e historial), **facturas con descarga del KuDE**, congelamientos, invitados disponibles |
| **Mi actividad** | Historial de check-ins, racha semanal ("vas 2 de 3 esta semana"), clases asistidas |
| **Avisos** | Notificaciones: reserva confirmada, sale de la lista de espera, membresía por vencer, clase cancelada |

**Login**: CI + código de un solo uso por WhatsApp/SMS o email (sin contraseñas que recordar). Al hacer el alta en recepción, el socio recibe por WhatsApp el link de la app.

---

### 7.1 Aviso de vencimiento de la cuota mensual por email

**Cuándo se envía** (job diario a las 07:00; los días son configurables en `gym_config.avisos_vencimiento`):

| Aviso | Momento (default) | Asunto |
|---|---|---|
| Recordatorio | **3 días antes** del vencimiento | "Tu cuota mensual vence el {fecha}" |
| Día del vencimiento | **El mismo día** | "Tu cuota mensual vence hoy" |
| Vencida | **3 días después** si no renovó (una sola vez) | "Tu cuota mensual está vencida desde el {fecha}" |

**Contenido** (plantilla HTML editable por la empresa, con el logo):
- *Buen día, {nombre}.* Tu plan **{plan}** vence el **{fecha_vencimiento}**.
- Importe de la renovación: **Gs. {precio}**, tomado de la **lista de precios vigente** (nunca un precio fijo en la plantilla).
- Recordatorio de la regla: la renovación cuenta **desde la fecha de vencimiento**.
- Dónde y cómo pagar: dirección y horario de caja de la sede. Con GYM_PRO (F4), además, un **botón "Pagar online"** con el link de Bancard.
- Link a la app del socio (estado de cuenta y facturas).
- Pie: datos del gimnasio y la opción **"No quiero recibir estos avisos"** (baja de avisos, que se guarda en el socio).

**Reglas**
1. **No se envía** si el socio ya renovó: el job verifica que no exista una membresía posterior `ACTIVA` o `PENDIENTE`. Tampoco si la membresía está anulada o el socio está de baja.
2. **Sin duplicados**: un solo envío por membresía y tipo de aviso (`UNIQUE` en `gym_avisos_log` por `membresia_id + tipo + canal`). Si el job se ejecuta dos veces, no reenvía.
3. Si el socio no tiene email o el envío rebota, queda registrado (`estado = SIN_EMAIL | REBOTADO`) y aparece en el reporte **"Avisos no entregados"**, para que recepción complete el dato.
4. **Menores de edad**: el aviso va al email cargado en su ficha (puede ser el de quien paga, ya que no se registra al tutor).
5. Envío por la cuenta SMTP de la empresa (`empresas_correo` + nodemailer), en cola con reintentos. Volumen máximo por hora configurable, para no caer en listas de spam.
6. El mismo motor sirve después para WhatsApp (F2): `gym_config.canales_aviso_vencimiento` = `[EMAIL]` en este cliente; `[EMAIL, WHATSAPP]` cuando se active.

**En la ficha del socio** se ven los avisos enviados (fecha, canal, estado) y hay un botón **"Reenviar aviso"**.

## 8. Integración contable (opcional, motor CONT-MA)

| Evento | Cuándo | Debe | Haber |
|---|---|---|---|
| Factura del plan | La genera Facturación (POS) | Caja de la sede | Ingresos por membresías + IVA débito |
| `GYM_DIFERIR` (opcional) | Al facturar planes de más de 1 mes | Ingresos por membresías | **Ingresos cobrados por anticipado** (pasivo) |
| `GYM_DEVENGAR` (opcional) | Job mensual por la parte del período consumido | Ingresos cobrados por anticipado | Ingresos por membresías |
| `GYM_CONGELAMIENTO` | Corre el devengamiento (sin asiento propio) | — | — |
| Venta de productos | Ventas e Inventario normales | Caja / Costo de ventas | Ventas / Mercaderías |
| Pago a instructores | Lo genera RRHH (liquidación) | Sueldos y jornales / honorarios | Sueldos a pagar |

- **Este cliente: reconocimiento al facturar** (`diferir_ingresos = false`). Los eventos `GYM_DIFERIR` / `GYM_DEVENGAR` no se publican; quedan en el backlog para clientes que vendan planes anuales y lo pidan.
- Cuentas sugeridas para este cliente: *Ingresos por membresías*, *Ingresos por servicios (masajes, pilates, sauna)*, *Venta de mercaderías*. Se separan con la categoría del producto.
- Con `tieneModuloContabilidad() = false` no se publica nada.
- Centro de costo = **sede**, para tener un estado de resultados por sede.

---

## 9. Modelo de datos

### Reutiliza

| Necesidad | Tabla/servicio existente |
|---|---|
| Socio (datos fiscales) | `clientes` |
| Sede | `sucursales` + `depositos` + `cajas` |
| Plan (precio y facturación) | `productos` (tipo `SERVICIO_MEMBRESIA`) + `lista_precios` |
| Venta | POS → `factura_cab` / `factura_det` (+ `gym_membresia_id` en el detalle) |
| Promociones | `ofertas-promociones` |
| Stock de productos | `movimientos_inventario` por depósito de sede |
| Vendedores y comisiones | `vendedores_cobradores` → `rrhh_comisiones_pendientes` |
| Instructores en nómina | `rrhh_empleados` (FK opcional) |
| WhatsApp / email | `IWhatsAppProvider` (Meta Cloud API / Evolution API) + `empresas_correo` |
| Asientos | Motor CONT-MA |

### Tablas nuevas `gym_`

```
gym_config               — modo_vencido (AVISAR|GRACIA_Y_BLOQUEO|BLOQUEAR), renovacion_desde (FIN_ANTERIOR|FECHA_PAGO),
                           dias_gracia, menor_requiere_tutor, edad_minima, usa_comisiones, usa_multisede (oculta el selector si es false),
                           minutos_antipassback, apto_fisico_modo (OFF|AVISAR|BLOQUEAR),
                           ventana_reserva_horas, horas_cancelacion_sin_penalidad, max_no_show_30d, dias_bloqueo_reserva,
                           qr_rotacion_seg (30), avisos_vencimiento (JSON: dias_antes [3], el_dia (true), dias_despues [3]),
                           canales_aviso_vencimiento ([EMAIL]), hora_envio_avisos (07:00), plantilla_email_vencimiento_id, diferir_ingresos (bool), permite_transferencia, cargo_transferencia_producto_id,
                           textos (reglamento, consentimiento), canal_avisos (WHATSAPP|EMAIL|PUSH)
gym_sedes                — sucursal_id, deposito_id, caja_id, nombre, direccion, horario_apertura (JSON por día),
                           capacidad_maxima, activa
gym_actividades          — nombre, tipo (MUSCULACION|CLASE_GRUPAL|CLASE_PREMIUM|PT), color, duracion_min, descripcion
gym_salas                — sede_id, nombre, capacidad
gym_planes               — producto_id, nombre, tipo (PERIODO|PASE|CREDITOS|MIXTO), duracion_valor, duracion_unidad
                           (DIA|MES), alcance_sedes (SEDE_BASE|TODAS|LISTA), sedes_permitidas (uuid[]),
                           franja_horaria (JSON), actividades_incluidas (uuid[]), creditos, creditos_actividades (uuid[]),
                           vencimiento_creditos_dias, invitados_mes, pases_visita_mes, congelamientos_max,
                           congelamiento_dias_min/max, requiere_matricula, matricula_producto_id, admite_menores,
                           renovable, activo
gym_socios               — cliente_id, numero_socio, foto_url, fecha_nacimiento, sexo (opcional), telefono, email,
                           sede_base_id, tutor_cliente_id (menores), contacto_emergencia (nombre, teléfono),
                           apto_fisico_vence, apto_fisico_archivo_url, reglamento_firmado_at, firma_url,
                           estado (ACTIVO|SUSPENDIDO|BAJA), motivo_suspension, origen (WALK_IN|REFERIDO|CRM|TURNE|WEB),
                           referido_por_socio_id, app_activada_at, acepta_avisos_email (default true), qr_secret (cifrado), crm_contacto_id
gym_membresias           — socio_id, plan_id, sede_venta_id, sede_base_id, factura_id, factura_det_id, vendedor_id,
                           fecha_inicio, fecha_fin, fecha_fin_original, estado (PENDIENTE|ACTIVA|CONGELADA|EN_GRACIA|
                           VENCIDA|REEMPLAZADA|ANULADA), creditos_totales, creditos_usados, invitados_usados_mes,
                           membresia_anterior_id, precio_neto, motivo_anulacion
gym_congelamientos       — membresia_id, desde, hasta, dias, motivo, adjunto_url, autorizado_por
gym_accesos              — socio_id, membresia_id, sede_id, fecha_hora, metodo (QR|MANUAL|INVITADO|PASE),
                           resultado (PERMITIDO|RECHAZADO_*|ALERTA_*), usuario_id (recepción), dispositivo, invitado_nombre/ci
gym_horarios_plantilla   — sede_id, sala_id, actividad_id, instructor_id, dia_semana, hora_inicio, duracion_min, cupo,
                           vigente_desde, vigente_hasta
gym_sesiones             — plantilla_id (null si es puntual), sede_id, sala_id, actividad_id, instructor_id, inicio, fin,
                           cupo, estado (PROGRAMADA|CANCELADA|DICTADA), motivo_cancelacion
gym_reservas             — sesion_id, socio_id, membresia_id, estado (CONFIRMADA|LISTA_ESPERA|CANCELADA|ASISTIO|NO_SHOW),
                           posicion_espera, canal (APP|RECEPCION), creada_at, cancelada_at, credito_consumido (bool)
gym_instructores         — nombre, ci, telefono, empleado_id (rrhh, opcional), especialidades (uuid[]),
                           modalidad_pago (POR_CLASE|POR_HORA|FIJO), tarifa, sedes (uuid[]), pin_hash, activo
gym_evaluaciones         — socio_id, instructor_id, fecha, peso, altura, porcentaje_grasa, medidas (JSON), objetivo,
                           observaciones  (GYM_PRO; datos de condición física, no clínicos)
gym_avisos_log           — socio_id, membresia_id, tipo (POR_VENCER|VENCE_HOY|VENCIDA|RESERVA|LISTA_ESPERA|CUMPLEANOS|RIESGO),
                           canal (EMAIL|WHATSAPP|PUSH), destino, enviado_at, estado (ENVIADO|REBOTADO|SIN_EMAIL|ERROR|BAJA),
                           error, referencia_id   — UNIQUE (membresia_id, tipo, canal)
gym_riesgo_abandono      — socio_id, fecha_calculo, score (0-100), nivel (BAJO|MEDIO|ALTO), señales (JSON),
                           accion_sugerida, atendido_por, atendido_at     (F3)
gym_historial_estados    — entidad (MEMBRESIA|SOCIO), entidad_id, estado_anterior, estado_nuevo, usuario_id, motivo, fecha
gym_servicios            — producto_id, actividad_id (opcional), modalidad (VENTA_SIMPLE|POR_TIEMPO|TURNO|CLASE|PAQUETE),
                           unidad_tiempo_min (50 masajes, 25 hidromasaje, 60 sauna), fraccion_minima (0.5 masajes), capacidad_simultanea,
                           recurso_tipo_requerido (CABINA|HIDROMASAJE|SAUNA), incluye_acceso_dia (JSON: sauna, piscina),
                           paga_profesional (bool),
                           duracion_min, requiere_profesional, sala_id/cabina_id, incluido_en_planes (uuid[])
gym_profesionales        — (masajistas y similares) nombre, ci, servicios (uuid[]), agenda_semanal (JSON), empleado_id (opcional)
                           → en la práctica puede unificarse con gym_instructores con un campo tipo (INSTRUCTOR|PROFESIONAL)
gym_importaciones        — tipo (SOCIOS|MEMBRESIAS|SALDOS|PLANES), archivo_url, mapeo_id, estado (SIMULADA|IMPORTADA|REVERTIDA),
                           filas_ok, filas_error, informe_url, usuario_id, fecha
gym_usos_tiempo          — servicio_id, socio_id (opcional), cliente_id, factura_det_id, sede_id, inicio, fin_previsto,
                           fin_real, minutos_comprados, estado (EN_USO|FINALIZADO|EXCEDIDO), usuario_id
gym_recursos             — sede_id, nombre (Cabina 1, Cabina 2, Hidromasaje, Sauna), tipo (CABINA|HIDROMASAJE|SAUNA|SALA),
                           capacidad (1 en cabinas e hidromasaje), activo   (reemplaza a gym_salas para el spa)
gym_turnos               — sede_id, cliente_id, socio_id (opcional), fecha, estado (RESERVADO|LLEGO|EN_CURSO|REALIZADO|
                           FACTURADO|CANCELADO|NO_SHOW), canal (TELEFONO|RECEPCION|APP|WHATSAPP), telefono_contacto,
                           observaciones, factura_id, cortesia (bool), motivo_cortesia, motivo_cancelacion, creado_por
gym_turno_items          — turno_id, servicio_id, producto_id, recurso_id, profesional_id, inicio, fin, cantidad (numeric(6,2)),
                           precio_unitario (de la lista al reservar), importe, cantidad_real, factura_det_id, orden (encadenados)
                           — EXCLUDE/validación de solapamiento por (recurso_id, rango) y (profesional_id, rango)
gym_profesional_tarifas  — profesional_id, servicio_id (null = todos), modo (MONTO_POR_UNIDAD|PORCENTAJE), valor, vigente_desde
gym_liq_profesionales    — profesional_id, periodo_desde, periodo_hasta, base (FECHA_SERVICIO|FECHA_FACTURA), total,
                           estado (BORRADOR|APROBADA|PAGADA|ANULADA), destino (GASTO|RRHH|EXTERNO), gasto_id, aprobado_por, pdf_url
gym_liq_profesionales_det — liquidacion_id, turno_item_id (UNIQUE: un ítem se liquida una sola vez), cantidad, importe_facturado,
                           tarifa, a_pagar
gym_import_mapeos        — nombre_origen (ej. "Planilla propia", "Sistema X"), tipo, mapeo_columnas (JSON)

-- Red (escenarios C y D, F5)
gym_redes                — nombre, empresa_duena_id (holding o franquiciante), tipo (GRUPO|FRANQUICIA), catalogo_central (bool)
gym_red_empresas         — red_id, empresa_id, rol (DUENA|MIEMBRO|FRANQUICIADO), activa
gym_red_acuerdos         — red_id, empresa_origen_id, empresa_destino_id, modo (PERMITIDO|CUPO|NO), visitas_mes,
                           tarifa_compensacion, porcentaje_regalia
gym_red_visitas          — red_id, socio_ci, empresa_emisora_id, empresa_receptora_id, sede_id, fecha_hora, resultado
```

**Campos agregados por la v0.2/v0.3**: `gym_salas.tipo` (SALA|CABINA). Además,: `gym_membresias.origen` (VENTA|MIGRACION|RED|DEBITO_AUTOMATICO), `gym_accesos.resultado` incorpora `ALERTA_VENCIDA`.

**Índices clave**: `gym_accesos (empresa_id, sede_id, fecha_hora)`, `gym_membresias (empresa_id, socio_id, estado, fecha_fin)`, `gym_reservas (sesion_id, estado)`. Toda tabla lleva `empresa_id` (regla multi-empresa).

### Fórmulas

```
Días restantes            = fecha_fin − hoy
Socios activos            = membresías ACTIVA + EN_GRACIA + CONGELADA (distintos socios)
Retención mensual         = activos al fin del mes que también estaban activos al inicio / activos al inicio
Churn mensual             = membresías que pasaron a VENCIDA sin renovar en 30 días / activos al inicio
Tasa de renovación        = renovaciones del mes / vencimientos del mes
Ocupación de clase        = reservas ASISTIO / cupo
Ocupación de sede (hora)  = check-ins en la franja / capacidad_maxima
Ingreso por socio (ARPM)  = ingresos de membresías del mes / socios activos promedio
LTV estimado              = ARPM × permanencia media en meses
Pago a instructor         = Σ sesiones DICTADAS × tarifa (POR_CLASE) | horas × tarifa | fijo
```

---

## 10. Experiencia de uso (staff)

1. **Pantalla Recepción** (la más usada): lector de QR siempre activo, buscador del socio y semáforo grande (**verde** permitido, **amarillo** en gracia o alerta, **rojo** rechazado) con la foto. Al lado, los botones **Renovar** (abre el POS con el plan cargado y el socio como cliente), **Vender pase**, **Registrar invitado** y **Congelar**.
2. **Alta rápida de socio** en un solo formulario: datos + foto con la cámara web + firma del reglamento en pantalla + elección del plan → pasa al POS para cobrar. Al facturar, el socio queda activo y recibe la app por WhatsApp.
3. **Ficha del socio 360**: membresías, pagos, accesos (gráfico de visitas por semana), reservas, faltas, congelamientos, avisos enviados y, en Pro, el **score de riesgo**.
4. **Agenda de clases** por sede (vista semana), con reservas y lista de espera. Desde ahí se cancela o reasigna un instructor.
5. **Vista del instructor** (celular, PIN): sus clases del día, la lista de reservados y el botón de marcar asistencia. No ve importes.
6. **Tablero del gerente** (todas las sedes o una): socios activos, altas y bajas del mes, vencen esta semana, en gracia, ocupación por hora, ingresos por sede, clases más llenas y vacías.
7. **Selector de sede** en la barra superior: el usuario de recepción queda fijo en su sede; el gerente cambia libremente.

---

## 11. Permisos y roles

```
GYM_CONFIG  GYM_SEDES  GYM_PLANES  GYM_SOCIOS_VER  GYM_SOCIOS_EDITAR  GYM_ACCESO_OPERAR  GYM_ACCESO_FORZAR
GYM_MEMBRESIA_ANULAR  GYM_CONGELAR  GYM_TRANSFERIR  GYM_CLASES_GESTIONAR  GYM_RESERVAS_OPERAR
GYM_INSTRUCTOR_OPERAR  GYM_REPORTES  GYM_REPORTES_TODAS_SEDES  GYM_RIESGO_VER
GYM_SPA_AGENDA  GYM_SPA_COBRAR  GYM_SPA_CORTESIA  GYM_SPA_LIQUIDAR  GYM_SPA_TARIFAS_VER
```

| Rol | Permisos | Alcance |
|---|---|---|
| Dueño / gerente general | Todos | Todas las sedes |
| Gerente de sede | Todo menos config, planes y anular | Su sede (reportes solo de su sede) |
| Recepción / caja | Socios, acceso, reservas, congelar (dentro de la regla) + POS/caja | Su sede |
| Vendedor de planes | Socios, ver planes, POS | Su sede |
| Instructor (PIN) | `GYM_INSTRUCTOR_OPERAR` | Sus clases |
| Contador | Reportes + Contabilidad | Todas |

`GYM_ACCESO_FORZAR` permite dejar entrar a un socio rechazado con un motivo (ej. "pagó, factura en proceso"), con auditoría.

---

## 12. Reportes e indicadores

- **Socios**: activos por sede y plan, altas y bajas, **churn y retención mensual**, permanencia media, socios por sede base vs sede donde realmente entrenan (para decidir la apertura de sedes).
- **Vencimientos**: vencen en 7 días, en gracia, vencidos sin renovar (lista de llamadas para recepción).
- **Ingresos con plan vencido** (clave para este cliente, que no bloquea): socio, días de atraso, cantidad de ingresos vencido, monto estimado no cobrado y usuario de recepción que lo dejó pasar.
- **Servicios adicionales**: masajes, pilates y sauna vendidos por día; ocupación de la agenda de masajes y de las clases de pilates.
- **Asistencia**: check-ins por hora y día (mapa de calor por sede), **socios sin visita en 14+ días**, nuevos con menos de 4 visitas en sus primeras 4 semanas.
- **Clases**: ocupación por actividad, horario e instructor; no-shows; listas de espera (dónde abrir otro horario).
- **Ingresos**: por sede, por plan y por vendedor; ticket promedio; venta de productos por sede; ARPM y LTV.
- **Instructores**: clases dictadas, asistencia promedio y liquidación del mes.
- **Caja**: recaudación por sede y medio de pago (reportes estándar de Tesorería).

---

## 13. Plan por fases (estimado con 2 desarrolladores)

Las fases están ordenadas para que **este cliente (1 sede) opere desde F1**. Lo multisede y la red se construyen sin frenarlo.

| Fase | Contenido | Semanas | Entrega al cliente |
|---|---|---|---|
| **F0** | Config con todos los parámetros (modo_vencido, renovación, menores, flags apagados), permisos, sede ↔ sucursal/caja/depósito, actividades (musculación, sauna, pilates), salas y cabinas, **plan mensual** y **servicios adicionales** con producto y lista de precios, instructores y profesionales | 1–2 | Base cargada + núcleo NOVASIS (SIFEN, caja, productos con stock) |
| **F1** | **Spa: agenda por cabina con bloques de 25 min, reserva con cantidad, cobro al terminar → POS/SIFEN, realizados sin facturar en el cierre de caja, liquidación de masajistas** (sección 6.1) · Alta rápida de socio (foto con cámara web, firma, validación de edad mínima 13), **venta del plan y de servicios en el POS → membresía activa**, renovación encadenada (`FIN_ANTERIOR`), vencido con aviso (`AVISAR`), anulación por ECAN, **pantalla Recepción** con check-in manual y semáforo, **lector 2D USB** (sirve también para el QR impreso de los pases), venta de productos, reporte "Ingresos con plan vencido", **aviso de vencimiento por email** (3 días antes, el día y 3 días después) con reporte de avisos no entregados | **4–5** | Operación diaria de recepción y caja |
| **F2** | **App del socio (PWA)** con login por código, **QR dinámico + lector en recepción**, agenda: **clases de pilates con cupo** y **reserva de turnos del spa desde la app** (la agenda de recepción ya está en F1), lista de espera, no-shows, **sauna por hora con contador**, vista del instructor/profesional, avisos por WhatsApp (se suma al email de F1: vence en 3 días, vencido, reserva confirmada) | 4 | Acceso por QR + reservas desde el celular |
| **F3** | Tablero y reportes, **riesgo de abandono** (14 días sin visita, caída de frecuencia, menos de 4 visitas en el primer mes), integración CRM 360 (leads, campañas de recuperación), asientos CONT-MA al facturar | 2 | Gestión y retención |
| **F4 — GYM_PRO** (el cliente lo quiere) | **Bancard**: pago y renovación desde la app, tarjeta guardada, **débito automático mensual** (cobro aprobado → factura SIFEN + renovación; rechazado → reintentos +3/+7 días y aviso). **Molinete**: lector QR en el molinete o terminal facial Hikvision, apertura por relé solo si el acceso es válido (con `modo_vencido = AVISAR` el molinete **no abre** a un vencido y la recepción lo libera con `GYM_ACCESO_FORZAR`, con motivo) | 3–4 | Cobro sin pasar por caja + acceso sin recepción |
| **F5 — Producto multisede/red** (para otros clientes) | Selector y reportes multisede (escenario B), **importador genérico** (sección 4.5), **red de gimnasios** (escenarios C/D: acceso cruzado, visitas, regalías), catálogo central de planes, comisiones y pago por clase a instructores, congelamiento, devengamiento | 4–5 | No aplica a este cliente; habilita vender a cadenas |

**Total para este cliente**: F0–F3 ≈ 12–13 semanas; con GYM_PRO (F4) ≈ 16 semanas. El spa entra en F1 porque hoy funciona en cuaderno y es donde más plata se pierde sin control (servicios sin facturar y liquidación sin respaldo).

> **Nota sobre F5**: el **modelo de datos** de multisede, red y migración se crea en F0 (tablas y campos), para no tener que migrar después. En F5 solo se construyen las pantallas y la lógica.

**Dependencias críticas**
1. **POS F1** (hoy al 85%) debe permitir el hook post-factura por tipo de producto (`SERVICIO_MEMBRESIA` → activar membresía). Es lo único que bloquea F1.
2. **Proveedor de WhatsApp** (Meta Cloud API / Evolution API) para los avisos de F2. Si el CRM 360 no llegó, F2 usa directamente `IWhatsAppProvider` con plantillas fijas.
3. **Bancard en producción** (tokenización y cobro recurrente) para F4: verificar que el comercio tenga habilitado el pago recurrente con Bancard antes de comprometer la fecha.
4. **RRHH ya no bloquea**: los sueldos de los instructores se pagan por la liquidación normal.

---

## 14. Pendientes

**Del cliente (spa, no bloquean F0; se necesitan antes de terminar F1)**
1. **Día Spa** (Gs. 50.000): ¿incluye un turno de hidromasaje de 25 min que hay que agendar, o el hidromasaje se usa libremente si está libre? ¿Tiene límite de horas?
2. **Masajistas**: ¿cuánto cobran por masaje (monto fijo o %; ¿igual para todos los tratamientos?)? ¿Facturan como independientes o están en planilla IPS? ¿Cada cuánto se les paga?
3. **Cuaderno**: ¿qué significa la columna **"Tpo"**? (¿tiempo, tipo de pago?) Lo que sea se agrega a la tarjeta del turno.
4. **No-shows y cancelaciones**: ¿cobran algo si el cliente no viene o cancela tarde? (Por defecto: no se cobra; queda registrado.)
5. **Socios del gym**: ¿tienen precio diferencial en el spa? ¿La **piscina** está incluida en el plan mensual? (Por defecto: sin descuento; se resuelve con una lista de precios "Socios" si hace falta.)

**Internos (antes de F1/F4)**
1. Confirmar con el equipo que el POS F1 expone el hook post-factura por tipo de producto (`SERVICIO_MEMBRESIA`, `POR_TIEMPO`).
2. Definir y comprar el lector 2D USB de recepción (probarlo con QR en celulares de gama baja con poco brillo).
3. Para F4: verificar con Bancard la habilitación de cobro recurrente/tokenización del comercio del cliente.
6. Cargar en F0 los masajistas, sus tarifas y los 3 recursos (Cabina 1, Cabina 2, Hidromasaje) con el horario del spa.
5. Verificar que la cuenta de correo del cliente tenga SPF/DKIM configurados (para que los avisos no vayan a spam) y cargarla en `empresas_correo` en F0.
4. Plantillas de WhatsApp (vence en 3 días, vencido, reserva confirmada, turno de masaje) para aprobar en Meta antes de F2.

## Fuentes

- [The Best Gym Management Software in 2026: Honest Comparison (Fit Pro Tracker)](https://fitprotracker.com/?p=848)
- [How to choose the best gym management software (ABC Glofox)](https://www.glofox.com/blog/how-to-choose-the-best-gym-management-software/)
- [PerfectGym: Club Management Software](https://perfectgym.com/en/features/club-management-software)
- [Fitco: software de gestión (ComparaSoftware)](https://www.comparasoftware.com/fitco)
- [Gym member retention statistics (Uptivo)](https://uptivo.fit/blog/gym-member-retention-statistics)
- [The 5th-Class Cliff: attendance data predicts who's about to quit (Gymdesk)](https://gymdesk.com/blog/5th-class-cliff-gym-member-retention)
- [Smart Fit y su plan de expansión en Paraguay (InfoNegocios, 2021)](https://infonegocios.com.py/default/smart-fit-posee-mas-de-800-sucursales-en-latinoamerica-y-un-ambicioso-plan-de-expansion-en-paraguay)
- Documentos internos: `claude-code/CLAUDE.md`, `plan-taller-chaperia-pintura.md`, `Novasis_CRM360_Analisis_Spec_v1.5.docx`, `plan-integracion-comisiones-rrhh.md`, `Integracion_Biometrico_DS-K1T343MFWX.docx`, `plan-bancard-vpos-compra-asistida.md`, `novasis-endpoint-externo-turne.ts`

---

## 15. Implementación (seguimiento)

### 15.1 Estado

> **11/11/2026:** migración a la UI nueva terminada (U0–U12) y en test; ver la bitácora (§15.7) y el resultado en el front.

| Fase | Estado | Dónde |
|---|---|---|
| **F0** | ✅ Backend, frontend y e2e (03/11/2026). Probado contra la base local; en test con F2a (§15.5), **no** en prod | `src/gimnasio/` (ver su `CLAUDE.md`), migración `20261103_gym_base` |
| **F1** | ✅ Backend, frontend y e2e (04/11/2026). Probado contra la base local; en test con F2a (§15.5), **no** en prod. Pendiente: precarga del POS (§15.3) y plantilla de email editable (F3) | `src/gimnasio/` (socios, recepción, avisos, reportes, ventas), migración `20261104_gym_socios_membresias` |
| **F2a** (MVP de demo) | ✅ Backend, frontend y e2e (04/11/2026). Commits `3baff26` / `5f27182e`. **Desplegado en test** (turno, §15.5), Kety con el módulo. Tablero de inicio, QR de acceso del socio (link personal, código que rota) y clases con cupo y reservas desde el panel. Diseño en §15.9 | `src/gimnasio/clases/`, `socios/qr-gym.service.ts`, `reportes/tablero-gym.service.ts`, migración `20261105_gym_clases_qr` |
| **F2a+** (pedido tras la demo) | ✅ Backend, frontend y e2e (05/11/2026). **Turnos de servicios** (masajes: cliente, horario, servicio, duración, profesional y cabina) y **tablet de ingreso** (el socio escribe la CI, un botón «Ingresar», ve su nombre y si está al día). Commits `b83b5f7` / `83fca739`. Diseño en §15.10 | `src/gimnasio/turnos/`, `recepcion/` (CI exacta), migración `20261106_gym_turnos` |
| **Tablet sin sesión** (06/11, pedido del cliente) | ✅ Backend, frontend y e2e. La tablet de ingreso deja de pedir usuario: se **vincula** una vez desde Recepción › Tablet (link o QR con un código propio) y queda atada a una sede; se desvincula desde el mismo lugar. Diseño en §15.10 | `recepcion/tablets-gym.service.ts`, `recepcion/tablet-publico.controller.ts`, migración `20261107_gym_tablets` |
| F2b | Pendiente: app del socio con login (PWA), reservas y turnos desde el celular, sauna por hora, vista del instructor, WhatsApp | — |
| F3–F5 | Pendientes | — |

### 15.2 Decisiones de implementación que ajustan el plan (03/11/2026)

1. **Módulo de seguridad `GIMNASIO`** con submódulos `GYM_CONFIG`, `GYM_CATALOGO`, `GYM_STAFF`. GYM_PRO = submódulos addon (`es_addon`) del mismo módulo en F4, que es como el ERP cobra lo adicional.
2. **No se agrega `SERVICIO_MEMBRESIA` a `productos.tipo`.** El plan es un producto tipo `servicio` sin inventario; el vertical lo reconoce por `gym_planes.producto_id` (un producto = un solo plan o servicio activo).
3. **El precio vive sólo en el producto** (o su lista de precios). El plan y el servicio crean su producto con `ProductosService.create` y editan el precio con `ProductosService.update`.
4. **Paquete de clases = plan `CREDITOS`**: `gym_servicios` no tiene la modalidad `PAQUETE`.
5. **"Incluido en el plan" se deduce por la actividad** del servicio: no hay `gym_servicios.incluido_en_planes`.
6. **Instructores y profesionales en una sola tabla** `gym_staff` (campo `tipo`), como sugería §9.
7. **Las tablas de red, franquicias e importador se crean en F5**, no en F0. Ya están `sede_id` y `sedes_permitidas`, que son lo caro de agregar después.
8. **Sin bus de eventos**: los "eventos gym.*" de §3 se implementan como llamada directa o job BullMQ (regla del ERP en `src/crm/CLAUDE.md`).
9. `gym_planes.franja_horaria` (JSON) quedó como `hora_desde` / `hora_hasta` (una franja para todos los días). Si un cliente pide franjas por día, se pasa a JSON.
10. Actividad tipo nuevo **`INSTALACION`** (sauna, pileta), que §9 no tenía.

### 15.3 Enganche con facturación (decidido el 04/11/2026)

`FacturasService` no tenía ningún punto de enganche para el vertical. **Decisión: llamada directa** (sin bus de eventos, regla del ERP) a un servicio chico del gimnasio, `GymVentasService` (`src/gimnasio/ventas/`). Vive en su propio módulo `GimnasioVentasModule`, que **sólo depende de Prisma**, para que `FacturasModule` y `MiddlewareSifenModule` lo importen sin dependencias circulares.

| Momento | Dónde se engancha (núcleo) | Qué hace el gimnasio |
|---|---|---|
| **Factura creada** | `FacturasService.create`, en el bloque *post-commit* (junto a los avisos de ecommerce que ya estaban): `await gymVentas.procesarFactura(...)` dentro de su propio `try/catch` | Por cada línea cuyo producto es el de un **plan activo**, crea la membresía (`gym_membresias`, vinculada a `factura_id` y `factura_det_id`). Si el cliente todavía no es socio, lo crea con la ficha marcada como incompleta |
| **Factura anulada** (ECAN, EINU o anulación local) | `MiddlewareSifenService.revertirFacturaAnulada`, el punto único de reversión que comparten los tres caminos de anulación: `await gymVentas.anularPorFactura(...).catch(fallo('gimnasio'))` | Pasa a `ANULADA` las membresías de esa factura, con el motivo |

Reglas del enganche:
1. **Nunca rompe una venta.** La factura ya está confirmada cuando se llama. Si el gimnasio falla, se loguea y la factura queda igual (responder error haría que el POS reintente y emita una segunda factura legal).
2. **Idempotente.** Índice único por `factura_det_id`: llamar dos veces no duplica la membresía. Anular dos veces no hace nada la segunda vez.
3. **Red de seguridad.** Un cron cada 10 minutos (`gym-ventas-reconciliar`) busca facturas de los últimos 3 días con líneas de planes y sin membresía, y las procesa. Cubre un reinicio del backend justo después de facturar, o un error transitorio.
4. **Costo para las empresas sin gimnasio**: una sola consulta (¿hay algún producto de la factura que sea plan del gimnasio?). Si no hay, sale sin hacer nada más.
5. `createFacturaAutomatico` (factura de un solo ítem, sin numeración elegida) **no** se engancha: ningún flujo del gimnasio la usa.
6. **Notas de crédito: fuera de F1.** Una NC no anula la membresía. Si se devuelve el dinero de un plan, recepción anula la membresía a mano (privilegio `GYM_SOC_MEMBRESIA_ANULAR`, con motivo).
7. **Los servicios** (sauna por hora, masajes, pilates) no crean nada al facturar en F1: el uso por tiempo, los turnos y las reservas son de F2 y se engancharán en el mismo `procesarFactura`.

**Precarga del POS (hecha el 16/11/2026 para «Nueva factura», §15.12).** «Cobrar en caja» abre `/pos?buscar_cliente=…[&cliente=…]&producto=…&buscar_producto=…`: la pantalla **Nueva factura** (POS tipo `admin`) elige el cliente y deja el plan **en la carga** del buscador con el precio que resuelve la lista del cliente (mismo camino que si el cajero lo buscara: ofertas, tope de descuento); el cajero confirma con Enter y factura. Con una venta en curso no toca nada (avisa). El **POS de mostrador** (`retail`) todavía no lee esos parámetros: ahí sigue valiendo la CI copiada y el aviso con el nombre del plan.

### 15.4 Código existente que se tocó

| Archivo | Cambio | Por qué | Impacto en el resto del ERP | Commit |
|---|---|---|---|---|
| `prisma/schema.prisma` | Modelos `gym_*` y enums nuevos. Relaciones inversas (solo Prisma, sin cambio en la base) en `empresas`, `empresas_sucursales`, `depositos`, `cajas`, `productos`, `rrhh_empleados` | Las FKs de las tablas `gym_` | Ninguno: el diff del schema es sólo de agregados (sin reformatear modelos ajenos) | `dbffc64` |
| `src/productos/productos.module.ts` | `exports: [ProductosService]` | El vertical crea el producto del plan por el camino normal | Ninguno: sólo expone el servicio | `dbffc64` |
| `src/app.module.ts` | Registra `GimnasioModule` | — | Rutas nuevas bajo `/api/v1/gimnasio` | `dbffc64` |
| `src/seguridad/seeds/seguridad.seed-data.ts` | Módulo `GIMNASIO` con 3 submódulos y 22 privilegios | Permisos del vertical | El bootstrap los siembra al arrancar; nadie los tiene hasta que se asigne el módulo | `dbffc64` |
| Frontend: `utils/dataEstatica.jsx`, `hooks/useMenuAcceso.js`, `utils/screenSubmoduloMap.js`, `routers/routes.jsx`, `_standards/enums/index.js`, `package.json` (`e2e:gym`) | Menú, rutas, breadcrumb, enums y script e2e del gimnasio | — | Sólo visible para empresas con el módulo `GIMNASIO` | `4ea49790` |
| **F1** `src/facturas/facturas.service.ts` + `facturas.module.ts` | Inyecta `GymVentasService`; en el bloque post-commit de `create` llama a `procesarFactura` dentro de su propio `try/catch` | Activar la membresía al facturar (§15.3) | Empresas sin planes de gimnasio: una consulta más por factura, sin efectos. Nunca rompe una venta | `27fc5e0` |
| **F1** `src/middleware-sifen/middleware-sifen.service.ts` + `middleware-sifen.module.ts` | Inyecta `GymVentasService`; `revertirFacturaAnulada` llama a `anularPorFactura` con captura de error propia, como las demás reversiones | Anular la membresía con la factura (ECAN, EINU o local) | Ninguno sin gimnasio. Los specs que construyen el servicio a mano no se tocaron: el `try/catch` cubre el parámetro ausente | `27fc5e0` |
| **F1** `prisma/schema.prisma` | Modelos `gym_socios`, `gym_membresias`, `gym_accesos`, `gym_avisos_log` y sus enums. Relaciones inversas (sólo Prisma) en `empresas`, `clientes` (socio y tutor), `factura_cab`, `factura_det` | FKs de las tablas nuevas | Ninguno: sólo agregados | `27fc5e0` |
| **F1** `src/seguridad/seeds/seguridad.seed-data.ts` | Submódulos `GYM_SOCIOS`, `GYM_RECEPCION`, `GYM_REPORTES` (9 privilegios) | Permisos de F1 | Se siembran al arrancar | `27fc5e0` |
| **F1** Frontend `_standards/CapturaFotoField.jsx`, `_standards/FirmaPad.jsx` (+ barrel) | Componentes estándar nuevos: foto con cámara web (o archivo) y firma en pantalla | Patrones genéricos (regla del `CLAUDE.md` del frontend) | Nadie más los usa todavía | `b8f72c7d` |
| **F1** Frontend `routers/routes.jsx`, `utils/dataEstatica.jsx`, `utils/screenSubmoduloMap.js` | Rutas, menú y breadcrumb de Recepción, Socios (listado y ficha), Reportes y la página **pública** `/gym/baja-avisos` | — | La pública no pide sesión: sólo confirma la baja con un token firmado | `b8f72c7d` |
| **F1** Frontend pantallas de F0 (`GymCatalogo`, `GymStaff`) | Corrige los iconos de las acciones de las tablas: `StandardTable` espera un componente y se pasaba el texto (`mdi:…` se veía escrito) | Bug de F0 | Sólo el gimnasio | `b8f72c7d` |

| **F2a** `prisma/schema.prisma` | Modelos `gym_horarios_plantilla`, `gym_sesiones`, `gym_reservas` y sus enums; `gym_socios.qr_version`. Relaciones inversas (sólo Prisma) en `empresas` y en tablas `gym_` | FKs de las tablas nuevas | Ninguno: sólo agregados | `3baff26` |
| **F2a** `src/seguridad/seeds/seguridad.seed-data.ts` | Submódulo `GYM_CLASES` (`GYM_CLA_AGENDA_VER`, `GYM_CLA_HORARIO_EDITAR`, `GYM_CLA_RESERVA_CREAR`) y `GYM_REP_TABLERO_VER` en `GYM_REPORTES` | Permisos de F2a | Se siembran al arrancar | `3baff26` |
| **F2a** Frontend `routers/routes.jsx`, `utils/dataEstatica.jsx`, `utils/screenSubmoduloMap.js` | Rutas, menú y breadcrumb de *Inicio del gimnasio* y *Clases y reservas*; página **pública** `/gym/mi-acceso` (QR del socio) | — | La pública no pide sesión: muestra el QR con un token firmado del socio | `5f27182e` |
| **F2a** Frontend `e2e/helpers/gimnasio-real.js`, `e2e/gimnasio-f1.real.spec.js`, `package.json` (`demo:gym`) | `facturarPorApi` acepta la fecha de emisión; la e2e de F1 acepta el reglamento si hay uno cargado; script de la carga de demo | La demo carga cuotas vendidas en días pasados | Sólo pruebas | `5f27182e` |

| **Turnos** `prisma/schema.prisma` | Modelo `gym_turnos` y enum `gym_turno_estado`. Relaciones inversas (sólo Prisma) en `empresas`, `clientes` (`gym_turno_cliente`) y tablas `gym_` | FKs de la tabla nueva | Ninguno: sólo agregados | `b83b5f7` |
| **Turnos** `src/seguridad/seeds/seguridad.seed-data.ts` | Submódulo `GYM_TURNOS` (`GYM_TUR_AGENDA_VER`, `GYM_TUR_TURNO_CREAR`) | Permisos de los turnos | Se siembran al arrancar | `b83b5f7` |
| **Turnos** Frontend `routers/routes.jsx`, `utils/dataEstatica.jsx`, `utils/screenSubmoduloMap.js` | Ruta y menú de *Turnos (masajes)*; ruta `/gimnasio/ingreso` **sin el menú** (pantalla completa para la tablet), con el permiso de recepción | — | Pedía sesión. **Reemplazada el 06/11** por la ruta pública `/gym/ingreso` (fila siguiente) | `83fca739` |
| **Tablet sin sesión** `prisma/schema.prisma` | Modelo `gym_tablets`; relación inversa (sólo Prisma) en `empresas` y `gym_sedes` | FK de la tabla nueva | Ninguno: sólo agregados | `0c5da40` / `647bcb1b` |
| **Tablet sin sesión** `src/gimnasio/gimnasio.module.ts` importa `SuscripcionesModule` | La tablet no tiene usuario, así que el guard global de suscripción no la frena: el servicio llama a `verificarEstadoSuscripcion` y corta sólo si la suscripción **venció** (la holding y las empresas sin suscripción propia siguen andando, como en el panel) | Sólo lectura de `suscripciones` | `SuscripcionesModule` sólo importa `AiConfigModule`: sin ciclos | `0c5da40` / `647bcb1b` |
| **Tablet sin sesión** Frontend `routers/routes.jsx`, `utils/screenSubmoduloMap.js` | Sale `/gimnasio/ingreso`; entra la ruta **pública** `/gym/ingreso` (junto a `/gym/mi-acceso`) | — | Un link viejo a `/gimnasio/ingreso` cae en «no encontrado» (sólo existió en test) | `0c5da40` / `647bcb1b` |

| `src/clientes/privilegios-busqueda.ts` | Suma `GYM_SOC_SOCIO_CREAR`, `GYM_SOC_SOCIO_EDITAR` y `GYM_TUR_TURNO_CREAR` a `PRIVILEGIOS_BUSCAR_CLIENTES` | El alta de socio y los turnos del spa buscan al cliente del ERP; sin esto, un perfil solo-gimnasio recibía 403 y la pantalla ofrecía crear un duplicado (relevamiento 2026-11-10, B D-2) | `GET /clientes/search` acepta además esos tres privilegios; nadie pierde acceso | U0 (10/11) |
| `src/gimnasio/ventas/gimnasio-ventas.module.ts` | Importa `AlertasEmpresaModule` | La reconciliación factura → membresía registra la falla como alerta de empresa en vez de solo loguearla | `AlertasEmpresaModule` no importa nada: no hay ciclo con Facturas ni Middleware SIFEN | U0 (10/11) |
| `prisma/schema.prisma` | `gym_acceso_resultado` suma `ALERTA_APTO` y `RECHAZADO_APTO` (migración `20261110_gym_apto_resultados`) | `apto_fisico_modo` se guardaba y nadie lo leía | Solo el gimnasio | U0 (10/11) |

| Frontend `src/utils/offlineTicketGenerator.js` | `formatCantidad`: la cantidad del ítem con sus decimales reales (hasta 6) en vez del redondeo de la moneda | 1,5 masajes salía «2 x …» en guaraníes | Todo ticket del POS retail: las cantidades con decimales se imprimen bien; las enteras no cambian | 11/11 |
| `src/gimnasio/ventas/gym-ventas.service.ts` (enganche) | `procesarFactura` también asigna las líneas de servicios TURNO a los turnos realizados; `anularPorFactura` las suelta; la reconciliación también mira facturas con servicios del spa | Spa: cobro al terminar (plan v0.5 §6.1.5) | Solo facturas con productos de servicios TURNO del gimnasio | U6 (11/11) |
| **Importar socios** `src/seguridad/seeds/seguridad.seed-data.ts` | Privilegio `GYM_SOC_SOCIO_IMPORTAR` (acción `IMPORTAR`) en `GYM_SOCIOS` | Carga inicial de socios desde una planilla (12/11) | Se siembra al arrancar; los perfiles con `GYM_SOCIOS.*` lo reciben solos | 12/11 |
| **Importar socios** `src/gimnasio/gimnasio.module.ts` importa `ClientesModule` | El importador crea cada cliente con `ClientesService.create` (mismas validaciones, duplicados y límite del plan que el alta manual) | Ninguno: `ClientesModule` sólo importa `PersonasModule`, sin ciclos con Facturas ni Middleware SIFEN | 12/11 |
| **Importar socios** (sin cambios) `src/crm/leads/importacion/leads-import.util.ts`, `src/crm/cierre/ruc.util.ts` | Se reusan `aTexto`, `normalizarEncabezado`, `partirRuc` y `dvValido` | Mismo problema ya resuelto en el CRM | Sólo imports: si cambian ahí, cambia la lectura de planillas del gimnasio | 12/11 |
| **Importar socios** Frontend `routers/routes.jsx`, `utils/screenSubmoduloMap.js` | Ruta y breadcrumb de `/gimnasio/socios/importar` (antes de `/:id`) | — | Sólo el gimnasio | 12/11 |
| **Sin plan con aviso** `prisma/schema.prisma` + migración `20261114120000_gym_sin_plan_con_aviso` | Valor `ALERTA_SIN_PLAN` en `gym_acceso_resultado` y columna `gym_config.sin_plan_con_aviso` (default false) | Socio sin ningún plan que el gimnasio deja pasar con aviso | Sólo agrega (enum + columna); requiere `migrate deploy` | 14/11 |
| **Sin plan con aviso** Frontend `components/_standards/enums/gimnasio.js` | Etiqueta «Entró sin plan» (amarillo) en `GYM_ACCESO_RESULTADOS` | Recepción y la ficha muestran el resultado nuevo | Sólo el gimnasio | 14/11 |
| **Plan ya pagado** `prisma/schema.prisma` + migración `20261116120000_gym_membresia_sin_factura` | Valor `MANUAL` en `gym_membresia_origen` y columna `gym_membresias.motivo_sin_factura` | Plan cargado sin factura, con motivo (§15.12) | Sólo agrega (enum + columna nullable); requiere `migrate deploy` | 16/11 |
| **Plan ya pagado** `src/seguridad/seeds/seguridad.seed-data.ts` | Privilegio `GYM_SOC_MEMBRESIA_ASIGNAR` (acción `ASIGNAR`) en `GYM_SOCIOS` | Asignar un plan ya pagado, sin factura | Se siembra al arrancar; los perfiles con `GYM_SOCIOS.*` lo reciben solos (superAdmin lo tiene) | 16/11 |
| **Precarga del POS** Frontend `features/ventas/facturas/nueva/useNuevaFactura.ts`, `SeccionItems.tsx`, `features/ventas/buscadores/BuscarProducto.tsx`, `locales/es-PY/ventas.json` | Nueva factura lee `?buscar_cliente=&cliente=&producto=&buscar_producto=`: elige el cliente (por id, o el único con ese documento exacto) y el buscador de productos recibe `precargar` y elige ese producto como si lo hubiera buscado el cajero (queda en la carga, no en la tabla). Con ítems cargados no hace nada y avisa | «Cobrar en caja» del gimnasio con socio y plan cargados (§15.3) | Ninguno si la URL no trae esos parámetros (los de `?pedido=/?orden=/?presupuesto=` siguen igual). El POS retail no los lee | 16/11 |

### 15.12 Plan en el alta y plan ya pagado (16/11/2026)

Pedido del primer cliente: «quieren poder asignar ya el plan al darle de alta al socio». Detrás había dos casos: el socio nuevo que paga en ese momento, y los ~300 socios importados el 13/11 que **ya habían pagado en el sistema anterior** y figuraban «Sin plan» (la importación no traía membresías y la única forma de dársela era facturarla de nuevo). Se resolvió como funcionalidad estándar, sin nombrar al cliente:

1. **Cobrar en el alta (lo normal, respeta la regla 1).** El alta suma un bloque opcional **Plan** con «¿Cómo?»: *Cobrarlo ahora en caja* (por defecto) o *Ya está pago (sin factura)*. Con «cobrar», el botón pasa a «Dar de alta y cobrar»: guarda el socio, deja la ficha atrás y abre la caja con el socio y el plan precargados (§15.3). La membresía la sigue creando la factura.
2. **Plan ya pagado, sin factura (excepción controlada a la regla 1).** Desde el alta (*Ya está pago*) o desde la ficha (**Más acciones › Asignar plan ya pagado**): plan, desde (hoy), hasta (lo propone la duración del plan con `GET membresias/vigencia`, editable), clases que le quedan (solo planes con créditos) y **motivo obligatorio**. Pide el privilegio nuevo `GYM_SOC_MEMBRESIA_ASIGNAR`. Crea la membresía `ACTIVA`, `origen = MANUAL`, sin factura ni importe, con `motivo_sin_factura` y `created_by`; auditada. No se puede pisar con otra membresía de acceso viva del socio (regla 7, 409 con las fechas de la otra), ni cargar un plan ya vencido, ni a un socio de baja. El próximo cobro en caja encadena con ella como con cualquier otra (renovación desde el día siguiente al fin). Lógica en `socios/membresias-manuales.service.ts`.
3. **Importación con plan.** La planilla acepta columnas opcionales **Plan** (nombre de un plan activo, sin importar mayúsculas ni acentos), **Vence** (obligatoria para cargar el plan) y **Desde** (por defecto, el día de la importación). Las fechas se leen como `dd/mm/aaaa` o fecha de Excel (el formato por defecto de Excel, que muestra mes/día, se lee como fecha y no se invierte). La fila que trae plan se carga con `origen = MIGRACION` y motivo «Plan ya pagado, importado de la planilla «archivo»». **También a quien ya era socio**: volver a subir la planilla con Plan y Vence completa la importación hecha sin esas columnas (los 300 del 13/11), sin duplicar fichas. Lo que no cierra (plan inexistente, sin vencimiento, vencido, se pisa con otra) no frena la fila: entra sin plan con el aviso. Permiso: el mismo de importar (`GYM_SOC_SOCIO_IMPORTAR`); la migración inicial ya estaba prevista en §4.
4. **Control.** Reportes del gimnasio › **Membresías sin factura** (`GET reportes/membresias-sin-factura`, por fecha de carga): socio, plan, vigencia, cómo (a mano / importación), estado, motivo y quién la cargó; métricas «A mano» e «Importadas». En la ficha, la columna Factura dice «Ya pagado» (a mano) o «Migrada» (importación) y el motivo muestra quién la cargó.
5. `GET opciones` devuelve los **planes activos** (id, nombre, tipo, producto con código y descripción, créditos) para elegir el plan sin el permiso de Catálogo y para la precarga del POS.

Pruebas: jest del gimnasio 322 (`membresias-manuales.spec.ts` y la importación con plan, incluida una fecha real de Excel); vitest del gimnasio y del POS 231; e2e `gimnasio-plan-en-alta.real.spec.js` 6/6 contra local (con `E2E_POS=1` abre una caja y verifica la precarga en Nueva factura), más `gimnasio-importar-socios` 3/3, `gimnasio-socios` y `gimnasio-sin-plan-con-aviso` sin cambios de comportamiento.

**Para activarlo en un cliente:** `migrate deploy` (`20261116120000_gym_membresia_sin_factura`) y reiniciar (siembra el privilegio). Los perfiles que no son superAdmin necesitan `GYM_SOC_MEMBRESIA_ASIGNAR` para ver «Asignar plan ya pagado» y la opción «Ya está pago».

### 15.5 Entornos

| Entorno | Qué se hizo | Cómo deshacerlo |
|---|---|---|
| Base local (`novasis_test`) | Migración `20261103_gym_base` aplicada con `db execute` + `migrate resolve --applied`. Datos de prueba del e2e en la empresa holding **Novasis PY**, todo dado de baja salvo los productos creados por los planes y servicios de prueba | `DROP` de las tablas `gym_*` y tipos `gym_*`, y borrar la fila de `_prisma_migrations` |
| Base local, F1 (04/11/2026) | Migración `20261104_gym_socios_membresias` aplicada (`db execute` dos veces para probar la idempotencia + `migrate resolve --applied`). **Además, `prisma migrate deploy` aplicó 38 migraciones de `pos` que la base local no tenía** (23/10 al 02/11; sin ellas no se podía crear un cliente). Datos de prueba en la holding **Novasis PY**: socios de prueba (los de la e2e quedan de baja), facturas de prueba de planes (las de la e2e, anuladas) sobre la numeración local de Presupuesto | Las tablas `gym_*` como en F0; las 38 migraciones de `pos` quedan (son las de la rama que se despliega) |
| DigitalOcean Spaces (bucket configurado en el `.env` local) | La e2e de F1 subió la **firma** de cada socio de prueba (PNG chico, ACL privada) bajo `gimnasio/3b327470-…/` | Borrar ese prefijo del bucket |
| Base local, F2a (04/11/2026) | Migración `20261105_gym_clases_qr` aplicada (`db execute` + `migrate resolve --applied`). **Carga de demo** (`pnpm run demo:gym`) en la holding **Novasis PY**: sede, 3 salas, 5 actividades, 3 instructores, 4 planes, horario semanal de 10 clases, 18 socios inventados (CI 9810001–9810018) con facturas de planes emitidas con fecha pasada, ingresos de hoy y reservas. Además, datos del recorrido por API y de la e2e (dados de baja). Configuración del gimnasio con reglamento cargado | Igual que F1; los socios de demo se dan de baja desde la ficha |
| **Test** (143.198.100.72, 04/11/2026) | Decisión del usuario: **turnar** test con el gimnasio (no se mergea a `pos-dev`/`dev`, que viajan a prod). Backend `/var/www/html/factvoice-erp-api` pasó de `pos-dev` (`528f4b60`) a `feat/gimnasio` (`3baff26`); frontend `/var/www/html/facvoice-erp` pasó de `dev` (`740c444a`) a `feat/gimnasio` (`5f27182e`). `prisma migrate deploy` aplicó en `novasiserp` **35 migraciones de `pos`** (25/10 al 02/11, ya corren en prod) y las 3 del gimnasio. Módulo `GIMNASIO` habilitado a **Comercial Kety** (fila en `suscripcion_modulos`, `Incluido`). Mientras dure el turno, test **no** tiene lo que sólo está en `pos-dev`/`dev` (por ejemplo, el agente de soporte IA) | Volver: en los dos checkouts `git checkout pos-dev` / `git checkout dev`, `pnpm install`, build (y en el backend `prisma generate` + `pm2 restart facvoiceerp-api --update-env` con `nvm use 24`). Las tablas `gym_*` y las 35 migraciones de `pos` quedan en la base (son aditivas). Quitar el módulo: `DELETE` de la fila de `suscripcion_modulos` de Kety |
| Prod | Nada | — |

**10/11/2026 — test con la UI nueva.** Los dos checkouts de test siguen en `feat/gimnasio`, ahora con `nueva-ui` mergeada (backend `123cd42d`, frontend `7f9f8a92`). `migrate deploy` aplicó las migraciones de `nueva-ui` y `20261110_gym_apto_resultados`. El frontend necesita Node ≥ 24.21 y pnpm 11 (`.nvmrc`/`packageManager`): se instaló **Node 24.21.0 con nvm y pnpm 11.2.2** en test; compilar con `nvm use 24.21.0`. El backend sigue con `nvm use 24`. Bundle verificado: solo `facerp-api.factupy.es`. e2e reales contra test: F0 6/6, F1 6 (+2 con facturación), F2a 6 (+1), turnos 6/6.

### 15.6 Pruebas de F0

- `npx jest src/gimnasio` — reglas de plan/servicio/staff y test de forma multiempresa (toda consulta filtra por `empresa_id`).
- Recorrido por API contra el backend local: 58/58 (config, sedes, salas y cabinas, actividades, planes con producto y precio, servicios, staff, bajas con dependencias, límites y errores esperados).
- `e2e/gimnasio-f0.real.spec.js` (Playwright, por la pantalla): 6/6 contra local.

### 15.6b Pruebas de F1

- `npx jest src/gimnasio src/seguridad src/middleware-sifen src/facturas` — 257/257. Nuevos: fechas y semáforo (`common/fechas-acceso.spec.ts`, 21), reglas de avisos (`avisos/avisos-reglas.spec.ts`, 7); el test multiempresa cubre los servicios nuevos (encontró 6 consultas sin `empresa_id` explícito, corregidas).
- Recorrido por API contra el backend local: **48/48**. Incluye alta con edad mínima, factura → membresía, renovación anticipada encadenada, anulación de la factura → membresía anulada, vencido con `AVISAR` y `BLOQUEAR`, forzar, renovación tarde con `FIN_ANTERIOR`, créditos (uno por día, atómico), socio creado desde una venta, 3 × mensual, avisos `SIN_EMAIL` sin duplicar, baja pública con token, reportes y anulación manual.
- Red de seguridad: se borró a mano la membresía de una factura y el cron `gym-ventas-reconciliar` la volvió a crear en su siguiente corrida.
- `e2e/gimnasio-f1.real.spec.js` (Playwright): **8/8** contra local con `E2E_FACTURAR=1`. Suite completa del gimnasio: 12 passed, 2 skipped (los de F0 que necesitan una sucursal libre para otra sede).
- Capturas en escritorio (1366) y celular (390): sin scroll horizontal.
- **No probado**: el envío real del email (para no escribirle a nadie desde local). Están probados el armado del aviso, los umbrales, el log y el caso sin email. Probarlo en test con un socio cuyo email sea nuestro.

**Bugs encontrados al probar (corregidos):**
1. El día del crédito iba a SQL como `Date` de JS: llegaba como `timestamptz` y la base en hora de Asunción guardaba el día anterior, así que se descontaba un segundo crédito el mismo día. Ahora va como texto `::date`.
2. `make_interval(days => bigint)` no existe en Postgres: la reconciliación fallaba siempre. Ahora se castea a `::int`.
3. El lock de los crons: un advisory lock de sesión con el pool de Prisma podía quedar tomado. Se cambió por uno de transacción.

### 15.6c Pruebas de F2a

- `npx jest src/gimnasio` — 60/60. Nuevos: `clases/clases-reglas.spec.ts` (calendario de la plantilla, hora de Asunción, superposición, con qué membresía se reserva, cancelación a tiempo) y `socios/qr-gym.spec.ts` (link, código que vence a los ±60 s, otra empresa, adulterado, link regenerado). El test multiempresa cubre los servicios nuevos.
- Recorrido por API contra el backend local: **40/40**. Horario (duración y cupo por defecto, superposición en la sala, musculación sin horario), 4 semanas generadas, reservas (sin plan, con créditos, doble reserva, cupo lleno → lista de espera, cancelación tarde sin devolver el crédito y con promoción de la espera, cancelación a tiempo que devuelve), recepción con clase reservada (no descuenta otro crédito y marca la asistencia), QR (link, página pública sin ids, buscar ignora el código, validar por QR con método `QR`, adulterado, link regenerado invalida link y códigos), asistencia manual, cambio de hora que conserva las clases con reservas y regenera las demás, cancelar la clase devuelve créditos, tablero.
- `e2e/gimnasio-f2a.real.spec.js` (Playwright, por la pantalla): **7/7** contra local con `E2E_FACTURAR=1`. Suite completa del gimnasio: **19 passed, 2 skipped** (los de F0 que necesitan una sucursal libre).
- Capturas en escritorio (1366) y celular (390) de Inicio, Agenda, detalle de la clase, Horario, diálogo del QR, página del socio y Recepción leyendo el QR: sin scroll horizontal.

**Ajustes encontrados al probar:**
1. La asistencia a mano sólo se podía marcar desde 30 min antes, pero la puerta la marca desde 90 min antes: se igualaron en 90.
2. La página del socio decía «Sin plan» a quien sólo tiene un paquete de clases: ahora muestra los paquetes vigentes con las clases que le quedan.
3. La agenda no entraba en 7 columnas a 1366 px: pasa a 7 columnas por *container query* (≥ 880 px) y si no, los días se acomodan como tarjetas.

### 15.6d Pruebas de turnos y tablet de ingreso

- `npx jest src/gimnasio src/seguridad` — 96/96. Nuevo: `turnos/turnos-reglas.spec.ts` (superposición por profesional y por cabina, turno pegado al anterior, primera cabina libre, transiciones de estado).
- Recorrido por API contra el backend local: **41/41**. Agendar (cabina automática, duración del servicio, socio enlazado), mismo profesional superpuesto (409), otro profesional en la otra cabina, profesional sin ese servicio, sin cabina libre, turno pegado y de 80 min, sin profesional cuando lo requiere, día pasado, cabina elegida ocupada, reprogramar (y encima de otro: 409), cancelar libera el hueco, atendido sólo desde 90 min antes, no se reprograma uno atendido, agenda del día, próximos del cliente, **dos recepciones a la vez por el mismo hueco: sólo una agenda**, baja de un profesional con turnos (409); tablet: CI exacta, CI parcial (404, no muestra a otro), CI con puntos, CI inválida.
- `e2e/gimnasio-turnos.real.spec.js` (Playwright, por la pantalla): **6/6** contra local. Suite completa del gimnasio: **25 passed, 2 skipped**.
- Capturas a 1366, 1280 (tablet) y 390 px de la agenda de turnos, el detalle, el diálogo y la tablet en verde, amarillo, rojo y «no encontramos esa cédula».

**Tablet sin sesión (06/11):** recorrido por API **13/13** (vincular con y sin sede, info sin ids, CI inexistente 404, sin CI 400, ingreso por CI sin ids ni documento en la respuesta, queda en los ingresos del día con el dispositivo, último uso en el listado, desvincular, 410 en info e ingreso, desvincular de nuevo 404). La e2e de la tablet ahora vincula desde Recepción, abre el link en **otro navegador sin sesión**, valida, recarga (sigue vinculada) y desvincula: **6/6** contra local. `gimnasio-multitenancy.spec.ts` lleva la búsqueda por el hash del código como excepción explícita (`POR_SECRETO`): el código ya identifica a la empresa.

**Ajustes encontrados al probar:** el resultado de la tablet se borraba apenas aparecía (el contador arrancaba en cero); los bloques de 30 min cortaban el texto (ahora muestran una, dos o tres líneas según el alto); el motivo del rechazo se decía en tercera persona al propio socio («No tiene una membresía…» → «Todavía no tenés un plan activo»).

### 15.7 Bitácora

- **03/11/2026** — F0: modelo de datos, migración, catálogo de seguridad, API (config, sedes y salas, actividades, planes, servicios, staff), pantallas (Configuración y sedes, Planes y servicios, Instructores y profesionales), e2e F0.

- **04/11/2026** — Decidido el enganche con facturación (§15.3). Diseño de F1 (§15.8).
- **04/11/2026** — F1 implementada y probada en local: socios (alta con foto y firma), membresías desde la factura, recepción con semáforo, avisos de vencimiento por email, reportes, crons (reconciliación, vencidas, avisos), endpoint «Procesar avisos ahora» (no estaba en el plan: sirve para operar y para probar sin esperar al cron). Commit backend `27fc5e0`, frontend `b8f72c7d`.
- **05/11/2026** — Pedido tras la demo: (1) ingreso con la CI en una tablet, con un solo botón, el nombre del socio y si está al día; (2) agendar turnos de masajes: cliente, horario, tipo de servicio y duración. Hecho como §15.10. La carga de demo suma cabinas, 6 servicios con turno y unos 50 turnos (hoy y los dos días siguientes).
- **06/11/2026** — La tablet de ingreso no pide más inicio de sesión (pedido del cliente): se vincula desde Recepción con un link de un solo uso y se desvincula desde ahí (§15.10). La ruta pasa a `/gym/ingreso`. Commits `0c5da40` / `647bcb1b`, desplegados en test el mismo día (migración `20261107_gym_tablets` aplicada en `novasiserp`); la e2e de turnos y tablet pasó 6/6 contra test con Kety.
- **04/11/2026** — Demo cargada en **test, Comercial Kety** (8 min por la API + historial por SQL): 216 socios (172 activos, 22 suspendidos, 22 de baja), 220 membresías (22 renovaciones), 64 reservas confirmadas y 28 en lista de espera, hoy 104 ingresos permitidos, 24 con plan vencido, 22 forzados y 44 rechazados, 732 ingresos en 14 días, 35 avisos sin email.
- **04/11/2026** — Carga de demo ampliada a 22 socios por situación, con reservas, lista de espera, ingresos forzados y rechazados y avisos, más el historial de ingresos por SQL (§15.9). Probada en local en Novasis PY y repetida sin duplicar nada.
- **04/11/2026** — F2a commiteada (`3baff26` / `5f27182e`) y desplegada en test por turno (§15.5); `GIMNASIO` habilitado a Kety. Falta la carga de demo en Kety (necesita login de un usuario de Kety).
- **04/11/2026** — Pedido: «al menos un MVP para una demo». Se adelanta de F2 lo que se puede mostrar sin la app con login (**F2a**, §15.9): tablero de inicio, QR de acceso del socio y clases con reservas desde el panel. Carga de demo por API (`pnpm run demo:gym`).

- **10/11/2026** — Producción pasa a la UI nueva (`nueva-ui` = `main`/`pos`). `nueva-ui` mergeada en `feat/gimnasio` (backend `29720c83`, frontend `49d7729b`). Relevamiento y diseño de la migración del gimnasio a la UI nueva: `frontend-gimnasio/docs/superpowers/specs/2026-11-10-gimnasio-design.md` (aprobado por Kevin), con el spa del plan v0.5 como unidad propia. **U0 (backend previo)**: `GET /gimnasio/opciones` (selectores y reglas con cualquier permiso del módulo), `GET clases/socios/buscar`, buscar clientes con permisos del gimnasio, tablet y QR personal exigen el submódulo contratado (la baja de avisos anda siempre), fallas de avisos y de la reconciliación como alertas de empresa, el cron propaga sus errores, foto/firma con `foto_error`/`firma_error`, reenviar aviso con las reglas del envío automático, bajas y cambios de tipo/rol con 409 si hay horarios/turnos que los usan, servicio TURNO solo con cabinas y CLASE solo con salas, `GET clases/agenda` ya no escribe (`generado_hasta`), `sede_id` validado como UUID, apto físico y ventana de reserva aplicados.

- **11/11/2026** — Spa desplegado en **test** (backend `42549f4c`, frontend `0b596eba`; `migrate deploy` aplicó `20261111_gym_spa` en `novasiserp`). Contra test con Kety: e2e spa 9/9 (con facturación), tablet 3/3, F0 6/6, F1 6 (+2 omitidas), F2a 6 (+1). La F0 cayó primero porque la pantalla vieja de sedes no conocía los tipos HIDROMASAJE/SAUNA (enum del front, arreglado). Carga de demo repetida en Kety: 30 turnos del spa (10 realizados, 3 facturados, 2 cortesías).
- **11/11/2026** — U7 (catálogo en la UI nueva), back: `POST actividades|planes|servicios/:id/reactivar` (la baja deja de ser definitiva, relevamiento C 3.6#4) y `moneda` en los listados de planes y servicios (B0.8).
- **11/11/2026** — U7 en test (back `4b002cc8`, front `04d61127`): e2e `gimnasio-catalogo.real` 6/6 y F0 3/3 contra Kety.
- **11/11/2026** — U8 (instructores y profesionales en la UI nueva), back: `POST staff/:id/reactivar` (`GYM_STF_STAFF_ELIMINAR`; cédula libre y lo elegido activo) y `moneda` en el listado del staff.
- **11/11/2026** — U8 en test (back `4458723e`, front `20280cb6`/`c05a4270`): e2e staff 4/4 y catálogo 6/6 contra Kety.
- **11/11/2026** — U9 (Configuración › Gimnasio en la UI nueva), back: `POST sedes/:id/reactivar` y `POST salas/:id/reactivar` (`GYM_CFG_SEDE_ELIMINAR`; sucursal libre, caja y depósito válidos; la sala pide su sede activa) y `GET sedes?incluir_inactivas=true` con las salas dadas de baja (relevamiento C 5.6#8).
- **11/11/2026** — U9 en test (back `3bffcdba`, front `dc86a8da`): F0 4/4 contra Kety (sede, cabina, baja/reactivar, reglas).
- **11/11/2026** — U3 (Recepción en la UI nueva), back: `recepcion/buscar` devuelve socios y los turnos del spa de hoy de esa persona (decisión 26: quien no es socio y ya llegó tiene sauna y piscina habilitadas; Recepción lo ve) — `clases/socios/buscar` sigue devolviendo solo socios; `recepcion/ingresos` paginado (B0.9) con el resumen del semáforo del día.
- **11/11/2026** — U3 en test (back `fa1a0958`, front `79954cc2`): F1 y tablet 9/9 contra Kety.
- **11/11/2026** — U4 (Socios en la UI nueva), back: el alta y la edición aceptan `apto_fisico_vence` (relevamiento B-4: con `apto_fisico_modo` BLOQUEAR no había cómo cargarlo); el tutor, el referido y el consentimiento ya estaban en el DTO y ahora tienen campo en la pantalla.
- **11/11/2026** — U4 en test (back `bfd480ed`, front `eb681c52`): socios 5/5 contra Kety. U5 (Clases en la UI nueva, solo front `52c787e6`): agenda del día por sala con AgendaGrilla, panel de la clase y horario semanal; F2a 6/6 contra Kety. Contra test, muchas e2e seguidas disparan el límite de intentos del login: esperar unos minutos.
- **11/11/2026** — U10 (Reportes › Gimnasio e Inicio en la UI nueva), back: `reportes/ingresos-vencidos` y `reportes/avisos-no-entregados` paginados (`page`, `limit` ≤ 200; los totales siguen siendo del período; los avisos cortaban en 1000 sin avisar, B0.9) y `socios?situacion=POR_VENCER` (vigentes que vencen en 7 días sin renovación: el KPI del Inicio llevaba a todos los vigentes, relevamiento A#18).
- **11/11/2026** — U10 en test (back `6df25a6c`, front `a1d3985f`): F1 6/6 contra Kety. U11 (públicas en la UI nueva), back: la respuesta pública de la tablet suma la foto del socio (URL firmada; diseño D2: recepción ve de lejos quién entra; sin ids ni documento).
- **11/11/2026** — U11 en test (back `fd8fee2b`, front `b6eabc34`): tablet 3/3 contra Kety. **U12, cierre de la migración a la UI nueva**: guía de NovaIA `docs/guias/guia-gimnasio.md` y 15 entradas del gimnasio en `src/ayuda-ia/ingesta/seed-catalogo.ts` (re-ingesta al desplegar); resultado en `novasispy-erp/docs/superpowers/plans/2026-11-11-gimnasio-resultado.md`. No queda código del gimnasio fuera de `src/features/gimnasio` en el front.

- **11/11/2026** — Pendientes del dueño decididos por Kevin («decidí como mejor nos convenga operativamente»), antes del pase a producción:
  1. **Pases fuera de «Vencen en 7 días»** (hecho): un pase de 1 a 7 días nace por vencer y no es una renovación que perseguir. No cuentan en el KPI ni en la lista del Inicio (`tablero-gym.service.ts`), ni en el filtro `situacion=POR_VENCER` de Socios, y el envío automático de avisos de vencimiento no les escribe (`avisos-gym.service.ts`, `candidatos`); el reenvío manual desde la ficha sigue pudiendo. Una renovación que cubre después sí puede ser un pase.
  2. **Ticket con la cantidad real** (hecho, `src/utils/offlineTicketGenerator.js` del front, §15.4): la cantidad se imprimía con la regla de la moneda (en guaraníes, 1,5 salía 2). Afecta a toda empresa que venda con decimales (POS en modo estación), no solo al spa.
  3. **Precarga del POS al «Cobrar en caja»**: se deja como está (copia la CI, avisa qué cobrar y abre el POS) hasta el primer gimnasio en producción. El POS es de todas las empresas y Derlis lo cambia a diario; se hace con él, en `features/ventas/pos-retail` y en la factura nueva, cuando haya un cliente operando.
  4. **«Realizados sin facturar» en el cierre de caja**: no se toca el cierre (es de todas las empresas). El control de fin de día queda en el Spa: la métrica «Realizados sin cobrar» y el botón que abre el próximo pendiente.
  5. **Emails de confirmación y recordatorio del spa**: no. Los turnos se piden por WhatsApp o teléfono y la confirmación es esa conversación; el recordatorio es el botón de WhatsApp del turno. Se revisa si el cliente lo pide.
  6. **Destino de la liquidación de profesionales**: gasto. Las masajistas son prestadoras independientes que facturan; «Marcar pagada» registra el pago y el egreso se carga en Compras › Gastos con su factura. Integrarlo con RRHH solo si el cliente tiene masajistas en relación de dependencia (pregunta 2 de `Test-QA/preguntas-fly-fitness-spa.md`, sigue abierta).
  7. **Reporte de productividad por masajista**: después de la salida a producción; hoy la liquidación por período ya lo muestra por profesional.

- **12/11/2026** — **Importar socios** (primer cliente real: carga inicial desde su planilla). Gimnasio › Socios › **Importar**: subir el Excel → revisar qué pasa con cada fila (no escribe) → importar. Cada fila crea el cliente por `ClientesService` (con DV → RUC, contribuyente persona física, B2B; sin DV → cédula, B2C) y la ficha de socio **incompleta** con origen `MIGRACION` (el enum ya lo tenía), como la que crea una venta (decisión 11). **No crea membresías** (nacen de la factura): el socio figura «Sin plan» hasta que se le cobra; el cliente eligió cobrar a todos desde un día de arranque en vez de cargar vencimientos. Detecta la hoja (la primera con nombre + documento, aunque haya otras hojas o filas arriba), reconoce encabezados reales (`CLIENTE`, `C.I`, `MAIL`, `PHONE`…), valida el DV, toma «-» como vacío, completa el 0 de los celulares y marca los documentos repetidos en el archivo. Reimportar no duplica («Ya es socio»). Endpoints `POST gimnasio/socios/importar/preview` y `POST gimnasio/socios/importar` (`GYM_SOC_SOCIO_IMPORTAR`). Pruebas: jest 298/298 del gimnasio (util + servicio con libro Excel en memoria + guardas), e2e `gimnasio-importar-socios.real.spec.js` 3/3 y `gimnasio-socios.real.spec.js` 5/5 contra local. La planilla real (300 filas) da 300 nuevos sin errores en el preview. Esto adelanta el «importador» que la decisión 7 dejaba para F5.
- **14/11/2026** — **Socio sin plan: dejar pasar con aviso** (pedido del primer cliente: sus socios se cargaron «Sin plan» y la tablet los rechazaba en rojo; querían que entren con un aviso y que recepción lo vea, sin aceptar nada). Opción de **Configuración › Gimnasio › Reglas**, apagada por defecto (`gym_config.sin_plan_con_aviso`): un socio **activo** sin ninguna membresía entra con resultado `ALERTA_SIN_PLAN` (amarillo, cuenta como ingreso permitido y para el antipassback). No afloja nada más: suspendido/baja, plan que todavía no empieza, paquete sin créditos, vencido con `BLOQUEAR` y apto físico en `BLOQUEAR` siguen sin entrar. El reporte de ingresos con plan vencido los incluye (sin plan ni monto estimado). La tablet, para cualquier amarillo por cuota (vencida, gracia, sin plan), dice «*nombre*, tu cuota está vencida · Por favor, pasá por recepción» (antes «pasá por administración a regularizar el pago»); el amarillo del apto físico ya no dice «cuota vencida». Pruebas: jest 307 del gimnasio, vitest 65 del gimnasio, e2e `gimnasio-sin-plan-con-aviso.real.spec.js` 2/2 y `gimnasio-tablet.real.spec.js` 3/3 contra local.
- **16/11/2026** — **Plan en el alta y plan ya pagado** (pedido del primer cliente: asignar el plan al dar de alta al socio). Alta con plan opcional: cobrarlo en caja (abre Nueva factura con el socio y el plan precargados) o cargarlo como ya pagado sin factura (permiso `GYM_SOC_MEMBRESIA_ASIGNAR`, motivo obligatorio); lo mismo desde la ficha; la importación acepta Plan/Desde/Vence y completa a los socios ya importados; reporte «Membresías sin factura». Detalle en §15.12.

### 15.11 Spa — implementación (10–11/11/2026)

Diseño en `novasispy-erp/docs/superpowers/specs/2026-11-10-gimnasio-design.md` («Spa — decisiones de modelo»); reglas en `src/gimnasio/CLAUDE.md` (decisiones 23–27). Migración `20261111_gym_spa` (idempotente): `gym_salas` suma HIDROMASAJE y SAUNA; `gym_turno_estado` renombra ATENDIDO → REALIZADO y suma LLEGO, EN_CURSO, FACTURADO; `gym_turnos` pasa a cabecera y sus servicios a `gym_turno_items` (cada turno de antes, un ítem; en local 72/72); `gym_config` suma `bloque_agenda_min`, `horario_spa`, `cortesia_paga_profesional`; `gym_servicios` suma `fraccion_minima`, `paga_profesional`, `habilita_acceso_dia`; tablas de tarifas y liquidaciones. Permisos nuevos: `GYM_TUR_TURNO_COBRAR`, `GYM_TUR_CORTESIA` y el submódulo `GYM_LIQUIDACIONES`.

**Desvíos del plan:** (1) sin `gym_recursos`: el recurso es `gym_salas`; (2) sin precio en `gym_turno_items` (regla 1 del módulo); (3) el sauna/piscina del día no escribe `gym_accesos` para un no socio: el turno es la habilitación; (4) permisos con la convención del ERP en vez de `GYM_SPA_*`.

**Pendiente:** decidido el 11/11 (bitácora §15.7): el ticket con cantidad decimal está hecho; la precarga del POS espera al primer gimnasio en producción; el cierre de caja no se toca; sin emails del spa; la liquidación va a gasto; el reporte de productividad, después.

**Pruebas:** jest gimnasio 255/255 (reglas del spa, enganche con la factura, guardas de las rutas nuevas); e2e `gimnasio-spa.real.spec.js` 6/6 contra local con facturación.

### 15.8 Diseño de F1 (04/11/2026)

**Tablas nuevas** (migración `20261104_gym_socios_membresias`, sólo agregados):

| Tabla | Para qué | Notas |
|---|---|---|
| `gym_socios` | El socio, atado a un cliente del ERP (`cliente_id`, uno por cliente) | Número de socio correlativo por empresa (`gym_config.proximo_numero_socio`, incremento atómico). Foto y firma en el almacenamiento **privado** (Spaces, ACL privada, URL firmada al mostrarla). `ficha_incompleta` = creado desde una venta sin pasar por el alta |
| `gym_membresias` | Lo que el socio compró | Nace del enganche (§15.3). `factura_det_id` único. Estados guardados: `ACTIVA`, `VENCIDA` (la marca un cron diario), `ANULADA`. `EN_GRACIA` se calcula al validar el acceso. `PENDIENTE`, `CONGELADA` y `REEMPLAZADA` quedan en el enum para F2/F5 |
| `gym_accesos` | Cada intento de ingreso, aprobado o rechazado | Alimenta el reporte «Ingresos con plan vencido» y el antipassback |
| `gym_avisos_log` | Cada aviso de vencimiento | Único por `membresia + tipo + canal + días`: un job repetido no reenvía |

`gym_historial_estados` (§9) **no** se crea: los cambios de estado van a `audit_logs`, como en el resto del ERP. `gym_config` suma `proximo_numero_socio` y `avisos_max_por_hora` (200).

**Fechas de la membresía** (día calendario de Asunción; la fecha de la venta es la de emisión de la factura):
- `PERIODO` y `MIXTO`: si el socio tiene una membresía de acceso **vigente**, la nueva arranca el día siguiente a su vencimiento (regla 2, renovación anticipada). Si está **vencida**: con `renovacion_desde = FIN_ANTERIOR` arranca el día siguiente al vencimiento, salvo que así ya hubiera terminado (volvió después de más de un período): entonces arranca el día de la venta. Con `FECHA_PAGO`, el día de la venta.
- `PASE`: arranca el día de la venta.
- `CREDITOS`: arranca el día de la venta y vence a los `vencimiento_creditos_dias`. Corre en paralelo a la de acceso (regla 7).
- Cantidad facturada N (ej. 3 × Mensual) = una membresía de N períodos.

**Validación del ingreso** (`POST gimnasio/accesos/validar`; recepción busca por CI, número de socio o nombre, y el lector 2D USB escribe como un teclado):

| Situación | Resultado | Semáforo |
|---|---|---|
| Membresía de acceso vigente, en su sede y su franja horaria | `PERMITIDO` | Verde |
| Vencida, `modo_vencido = AVISAR` (el primer cliente) | `ALERTA_VENCIDA` («vencido hace N días, cobrar hoy»); entra igual | Amarillo |
| Vencida dentro de los días de gracia (`GRACIA_Y_BLOQUEO`) | `ALERTA_GRACIA`; entra | Amarillo |
| Vencida fuera de la gracia, o `BLOQUEAR` | `RECHAZADO_VENCIDA` | Rojo |
| Sólo un paquete de créditos con saldo | `PERMITIDO` y descuenta 1 crédito (como mucho uno por día) | Verde |
| Sin membresía, sin créditos, otra sede (`SEDE_BASE`), fuera de la franja, socio suspendido o de baja, o reingreso dentro de `minutos_antipassback` | `RECHAZADO_*` | Rojo |

Un rechazo se puede **forzar** con motivo (privilegio `GYM_REC_ACCESO_AUTORIZAR`): queda `PERMITIDO_FORZADO` en el registro.

**Avisos de vencimiento por email** (§7.1). El cron corre cada hora y procesa las empresas cuya `hora_envio_avisos` ya pasó en el día. Para cada membresía de acceso no anulada, de un socio activo que acepta avisos y **no renovó**:
- antes del vencimiento, se manda el aviso del umbral más chico de `avisos_dias_antes` que todavía no se mandó;
- el día del vencimiento, si `aviso_el_dia`;
- después, el del umbral de `avisos_dias_despues` ya alcanzado.

Hay un margen de 2 días para recuperar una corrida perdida, y nada más: encender los avisos no les escribe a todos los vencidos viejos.
- Sale por el correo efectivo de la empresa (el propio o el del sistema, igual que la prueba de correo de Empresa). El importe sale de la lista de precios del cliente (`ListaPreciosService`). Se manda un máximo de `avisos_max_por_hora` por corrida.
- Si el socio no tiene email, queda `SIN_EMAIL`. Si el envío falla, queda `ERROR` y se reintenta en las corridas siguientes (hasta 3 intentos). Los dos casos aparecen en el reporte «Avisos no entregados».
- El link «No quiero recibir estos avisos» lleva a una página pública del panel (`/gym/baja-avisos?t=…`), con un token firmado del socio.
- La plantilla es fija, con los datos de la empresa. Hacerla editable queda para F3.

**Permisos nuevos** (módulo `GIMNASIO`):

| Submódulo | Privilegios |
|---|---|
| `GYM_SOCIOS` | `GYM_SOC_SOCIO_VER/CREAR/EDITAR/ELIMINAR`, `GYM_SOC_MEMBRESIA_ANULAR`, `GYM_SOC_AVISO_ENVIAR` |
| `GYM_RECEPCION` | `GYM_REC_ACCESO_CREAR` (registrar ingresos), `GYM_REC_ACCESO_AUTORIZAR` (forzar un rechazo) |
| `GYM_REPORTES` | `GYM_REP_REPORTE_VER` |

**Pantallas**:
- *Recepción*: buscador siempre enfocado, semáforo grande con la foto y botones «Forzar ingreso», «Cobrar en caja» y «Ver ficha», más los ingresos del día.
- *Socios*: listado, alta rápida y ficha.
  - El alta reusa el `ClienteSearch` del POS para elegir o crear el cliente. Suma la fecha de nacimiento (valida la edad mínima), contacto, sede base, foto con la cámara web y firma del reglamento en pantalla.
  - La ficha muestra datos, membresías (con anular), ingresos y avisos (con reenviar).
- *Reportes*: «Ingresos con plan vencido» y «Avisos no entregados».

**Fuera de F1**: QR dinámico y app del socio, reservas, turnos, sauna por hora y WhatsApp (F2); invitados y congelamiento (F5); precarga del POS (§15.3); notas de crédito (§15.3, regla 6).

### 15.9 Diseño de F2a — MVP de demo (04/11/2026)

**Por qué F2a.** La demo necesita lo que un gimnasio espera ver y F1 no tenía: el tablero del día, el QR en el celular del socio y las clases con cupo. Se adelanta de F2 todo lo que **no** depende de la app con login ni de WhatsApp; eso queda para F2b.

**Tablas nuevas** (migración `20261105_gym_clases_qr`, sólo agregados):

| Tabla | Para qué | Notas |
|---|---|---|
| `gym_horarios_plantilla` | Horario semanal recurrente | `dia_semana` ISO (1 = lunes), `hora_inicio`, `duracion_min` (por defecto la de la actividad), `cupo` (por defecto la capacidad de la sala), vigencia. Sólo actividades `CLASE_GRUPAL`, `CLASE_PREMIUM` y `PT`. No se superpone con otra del mismo día en la misma sala ni con el mismo instructor |
| `gym_sesiones` | Cada clase concreta | Se generan desde la plantilla (`createMany` + `ON CONFLICT DO NOTHING` sobre `(plantilla_id, inicio)`): al guardar la plantilla, al abrir la agenda y por un cron diario, 4 semanas hacia adelante; nunca hacia atrás. `dia` = día de Asunción del inicio |
| `gym_reservas` | La reserva de un socio | Una viva por socio y sesión (índice parcial). `CONFIRMADA`, `LISTA_ESPERA` (con posición), `CANCELADA`, `ASISTIO`, `NO_SHOW` |

`gym_socios.qr_version`: subirla invalida el link del QR anterior.

**Reglas de las reservas** (`clases/clases-reglas.ts` + `reservas-gym.service.ts`):
1. **Con qué membresía**: primero un plan vigente el día de la clase que **incluye la actividad** (no descuenta nada); si no, un paquete (`CREDITOS` o `MIXTO`) vigente para esa actividad y con saldo, el que vence antes: **descuenta 1 crédito al confirmar**. Si no hay ninguno, el rechazo dice qué vender.
2. **Cupo**: la fila de la sesión se bloquea (`SELECT … FOR UPDATE`) mientras se cuenta: dos recepciones a la vez no sobrevenden el último lugar. Llena → lista de espera, sin descontar.
3. **Cancelar** con al menos `horas_cancelacion_sin_penalidad` de anticipación devuelve el crédito; más tarde, no (queda `cancelacion_tardia`). Si se libera un lugar, entra el primero de la espera que siga pudiendo reservar (y se le descuenta en ese momento).
4. **Cancelar la clase** cancela todas las reservas vivas y devuelve los créditos.
5. **Asistencia**: al validar el ingreso en recepción, sus reservas de clases que empiezan entre 60 min antes y 90 min después quedan `ASISTIO`. También se marca a mano desde 90 min antes. Un cron cada 15 min pasa las clases terminadas hace más de una hora a `DICTADA`, las confirmadas sin asistencia a `NO_SHOW` (el crédito no vuelve) y la espera a cancelada.
6. **Puerta y créditos**: si el socio entra con una reserva de hoy que ya descontó el crédito del paquete, la puerta no descuenta otro.
7. **Faltas**: con `max_no_show_30d` > 0 (apagado por defecto), al llegar a N faltas en 30 días no puede reservar durante `dias_bloqueo_reserva`.
8. **Editar la plantilla**: sala, instructor y cupo se actualizan en las sesiones futuras. Si cambia el día, la hora o la vigencia, las sesiones futuras **sin** reservas se borran y se regeneran (son derivadas: excepción a «no borrar»), y las que tienen reservas quedan en el horario anterior; se avisa cuántas. Dar de baja la plantilla hace lo mismo.

**QR de acceso** (§5.1, versión sin app):
- Link personal `/gym/mi-acceso?t=` con un token `base64url(socio).version.HMAC`. Lo da la ficha del socio (botón «QR de acceso»): se muestra como QR para abrirlo con la cámara del celular, o se copia o se manda por WhatsApp (`wa.me`).
- La página pública (sin sesión) muestra el nombre, el número de socio, la cuota (o los paquetes con las clases que quedan) y un código `GYM1.<socio>.<ventana>.<HMAC>` que cambia cada `qr_rotacion_seg` (30 s). No devuelve ids ni el documento. Throttle de 30 por minuto por IP.
- En recepción, el lector 2D escribe el código y da Enter; el buscador lo reconoce por el prefijo y valida con `{ qr }` (método `QR` en `gym_accesos`). Vale ±60 s y sólo dentro de la empresa de quien valida. También se puede leer con la cámara (`LectorQrDialog` del estándar).
- «Link nuevo» sube `qr_version`: el link anterior y sus códigos dejan de valer.
- **Diferencia con §5.1**: el código lo calcula el servidor en cada refresco, así que la página necesita conexión. Funcionar sin conexión (secreto en el celular) queda para la app de F2b.

**Tablero** (`GET gimnasio/reportes/tablero`, privilegio `GYM_REP_TABLERO_VER`): socios activos y con la cuota al día, que vencen en 7 días, vencidos sin renovar (30 días), ingresos de hoy (y socios distintos y rechazos), ventas y renovaciones de planes del mes (por moneda), altas del mes, ingresos por hora de hoy, ingresos de los últimos 14 días y clases de hoy con su ocupación. Se refresca solo cada minuto.

**Permisos nuevos**: submódulo `GYM_CLASES` (`GYM_CLA_AGENDA_VER`, `GYM_CLA_HORARIO_EDITAR`, `GYM_CLA_RESERVA_CREAR`) y `GYM_REP_TABLERO_VER` en `GYM_REPORTES`.

**Pantallas**: *Inicio del gimnasio* (tablero), *Clases y reservas* (agenda semanal + detalle de la clase con reservas, espera y asistencia; pestaña «Horario semanal»), botón «QR de acceso» y pestaña «Clases» en la ficha, cámara y lectura del QR en Recepción, página pública del QR.

**Carga de demo** (`frontend: E2E_DEMO=1 pnpm run demo:gym`, con las variables de las e2e): idempotente; emite facturas con fecha pasada para que haya cuotas al día, por vencer y vencidas. **Sólo contra una empresa de prueba sin facturación electrónica.**

Ampliada el 04/11/2026 («al menos 20 registros de cada caso»): 10 actividades, 5 salas, 16 instructores y 6 profesionales, 8 planes, 31 clases semanales y **22 socios por situación**: al día, por vencer, vencidos, con paquete de clases, con pase, sin plan, suspendidos, de baja y renovados (CI 9810100–9810297), más los 18 originales. El movimiento de hoy se agrega en cada corrida a quien todavía no lo tiene: ingresos permitidos, con plan vencido, rechazados y 22 forzados con motivo, las dos próximas clases de Spinning llenas con lista de espera, reservas de Pilates y Yoga con crédito, y los avisos del día (quedan «sin email»). Hay que correrla **la mañana de la demo** para que la recepción y el tablero tengan el movimiento de ese día.

**Historial de ingresos** (`backend: scripts/demo/gimnasio-historial-ingresos.sql`): la API no registra ingresos en el pasado, así que los gráficos de 14 días quedarían vacíos. El script los genera por SQL, coherentes con las membresías de cada socio (vigente → entró, vencida → entró con alerta, sin plan → rechazado), con picos a la mañana y a la tarde, y marcados con el dispositivo `Demo (historial)`. Se puede repetir: borra lo suyo y lo regenera. Va después de la carga por la API. **Sólo en test.**

**Fuera de F2a (→ F2b)**: login del socio y reservas desde el celular, QR sin conexión, turnos de masajes (cabinas y profesionales), sauna por hora, vista del instructor con PIN, avisos por WhatsApp (reserva confirmada, sale de la espera, clase cancelada).

### 15.10 Turnos de servicios y tablet de ingreso (05/11/2026)

**Por qué ahora.** Después de la demo, el cliente pidió dos cosas que estaban en F2b: el ingreso con la cédula en una tablet a la entrada (como el sistema que usa hoy) y agendar los masajes. Se adelantan sin la app del socio: las dos se operan desde el panel.

**Turnos** (`src/gimnasio/turnos/`, tabla `gym_turnos`):
1. Un turno es **un cliente del ERP** (no hace falta que sea socio; si lo es, `socio_id` lo enlaza), un **servicio con modalidad `TURNO`**, el día y la hora, la **duración** (por defecto la del servicio, editable: 30/45/60/90 o cualquiera de 5 a 600 min), el **profesional** y la **cabina**.
2. **No se superponen** ni el profesional ni la cabina (`[inicio, fin)`: uno que empieza cuando el otro termina no choca). La verificación y el alta van en una transacción con un **lock por empresa y día** (`pg_advisory_xact_lock`): dos recepciones a la vez no agendan el mismo hueco.
3. **Cabina**: si no se elige, se asigna **la primera libre** de las del servicio (en su orden); si están todas ocupadas, el rechazo lo dice.
4. **Profesional**: obligatorio si el servicio lo requiere; si el profesional tiene servicios asignados, tiene que tener ese. Si atiende sólo en algunas sedes, tiene que ser una de ellas.
5. **Estados**: `RESERVADO` → `ATENDIDO` / `NO_SHOW` (se marcan desde 90 min antes, como la asistencia a clases, y se pueden corregir) o `CANCELADO` (con motivo; libera el hueco). Sólo se reprograma un turno reservado. No se agenda en un día pasado; en el día de hoy sí, aunque la hora ya haya pasado (para registrar lo que se atendió sin turno).
6. **Bajas**: un servicio, un profesional o una cabina con turnos reservados por delante no se dan de baja (409 con la cantidad).
7. **Cobro**: el detalle del turno tiene «Cobrar en caja» (copia la CI y abre el POS, como recepción, §15.3). Que el turno nazca o se marque pagado desde la factura queda para cuando se haga la precarga del POS.
8. **Recordatorio**: botón de WhatsApp (`wa.me`) con el texto del turno. Los avisos automáticos por WhatsApp siguen en F2b.

Endpoints (`/api/v1/gimnasio/turnos`): `GET agenda?dia&sede_id` (profesionales, cabinas, servicios con turno y los turnos no cancelados del día) · `GET :id` · `GET clientes/:id` (próximos del cliente) · `POST` · `PATCH :id` (reprogramar) · `POST :id/cancelar` · `POST :id/estado`. Permisos: submódulo `GYM_TURNOS` (`GYM_TUR_AGENDA_VER`, `GYM_TUR_TURNO_CREAR`).

Pantalla *Turnos (masajes)* (`/gimnasio/turnos`): un día, una columna por profesional y las horas hacia abajo; tocar un hueco abre el alta con ese profesional y esa hora; tocar un turno abre el detalle (contacto, notas, atendido / no vino, reprogramar, cancelar, cobrar, WhatsApp).

**Tablet de ingreso** (`/gym/ingreso`, pública, sin el menú; hasta el 06/11 fue `/gimnasio/ingreso` con sesión):
- El socio escribe su **cédula** y toca **INGRESAR** (o Enter). `POST recepcion/validar` acepta `{ documento }`: busca el socio por la **CI exacta** (sin puntos; si tiene RUC, el número sin DV), nunca por coincidencia parcial, para no mostrarle el nombre de otro. Si el documento quedó en dos fichas, manda la activa.
- Mismas reglas y mismo registro que recepción (`gym_accesos`, dispositivo «Tablet de ingreso»). Muestra en grande el nombre y: verde «¡Bienvenido/a!» con el plan y hasta cuándo está al día (o las clases que le quedan del paquete); amarillo «tu cuota está vencida… pasá por administración» si el gimnasio deja entrar con aviso; rojo con el motivo dicho al socio. Un pitido distinto para cada caso. A los 8 s (o al tocar) vuelve a pedir la cédula.
- También acepta el QR del socio con un lector 2D. Botón de pantalla completa.

**Tablet sin sesión** (06/11/2026, pedido del cliente: «es libre, no debería pedir inicio de sesión»). Abierta del todo no puede quedar: cualquiera en internet podría probar cédulas y ver nombres, y la página no sabría de qué gimnasio es. Por eso se **vincula** una vez:
1. En Recepción › **Tablet**, quien tiene `GYM_REC_ACCESO_AUTORIZAR` le pone un nombre («Entrada principal») y, con varias sedes, la sede. El backend genera un código al azar (24 bytes), guarda **sólo su hash** (sha256, `gym_tablets.token_hash`) y devuelve el link `/gym/ingreso?k=…` **una sola vez** (también como QR, o «Usar este dispositivo como tablet»).
2. La tablet abre el link: guarda el código en su `localStorage` y lo saca de la barra de direcciones. Desde ahí funciona sin usuario, también después de reiniciar.
3. Cada ingreso va a `POST /api/v1/gimnasio-publico/tablet/ingreso` con el código en el cuerpo (CORS no deja agregar un header propio). Mismas reglas y registro que recepción, en la sede de la tablet, con dispositivo «Tablet: <nombre>» y sin usuario. La respuesta no lleva ids ni documento: nombre, semáforo, motivo y plan (fin o clases que quedan). Throttle de 60 por minuto por IP.
4. **Desvincular** (mismo diálogo, con el último uso de cada tablet) la deja sin acceso al instante: responde **410** y la tablet muestra «Esta tablet fue desvinculada» (410 y no 404, para no confundirlo con «no encontramos esa cédula»). También deja de andar si se da de baja su sede o si la suscripción de la empresa venció.
5. **Logos** (13/11/2026, pedido del cliente): arriba el logo de la empresa (Configuración › Empresa), abajo el de Novasis. `tablet/info` dice sólo `logo: true|false` y la imagen se pide a `POST gimnasio-publico/tablet/logo` (`{ k }`), que la baja del bucket y la entrega en bytes: la URL del bucket lleva el id de la empresa (regla 10). Sólo https, imagen y hasta 3 MB; sin logo, 404 y la tablet muestra el nombre.

### 15.13 Aviso de vencimiento parametrizable (16/11/2026)

Pedido del primer cliente: «enviar una notificación del vencimiento de la cuota, y que sea parametrizable». El aviso por email ya existía desde F1 (§7.1, §15.8: días antes, el día, días después y hora, en Reglas), pero el texto era fijo y no se podía apagar (el back forzaba `EMAIL` si llegaban los canales vacíos). Se decidió (usuario, 16/11): **email ahora, WhatsApp después** (reusará el canal de WhatsApp del CRM cuando esté en prod y el gimnasio tenga un número conectado; `canales_aviso_vencimiento` ya admite `WHATSAPP`).

1. **Prender / apagar**: «Enviar avisos de vencimiento por email» en Configuración › Gimnasio › Reglas › Aviso de vencimiento. Apagado = `canales_aviso_vencimiento` sin `EMAIL` (el back ya no lo fuerza); el cron no procesa esa empresa. Con los avisos apagados se ocultan días, hora y textos.
2. **Texto editable por aviso** (*Por vencer*, *Vence hoy*, *Vencida*): asunto (≤150) y mensaje (≤2000) con variables `{nombre}`, `{plan}`, `{vence}`, `{dias}`, `{importe}` (lista de precios del socio), `{gimnasio}`, `{sede}` (con dirección y teléfono; sin sede, el gimnasio) y `{renovacion}` («la renovación cuenta desde el vencimiento», solo con `FIN_ANTERIOR`). Una línea en blanco separa párrafos; **un párrafo cuya variable quedó vacía no se envía** (sin precio no sale «Importe: .»). Una variable que no existe no deja guardar (front y back). Se guarda en `gym_config.avisos_plantillas` (JSON) **solo lo que difiere del texto original**: «Volver al texto original» lo borra, y una mejora futura del texto original les llega a quienes no lo editaron. El texto original es el de siempre (mismo contenido que el HTML fijo anterior). Lógica pura en `avisos/avisos-plantillas.ts`; el email mantiene encabezado con el gimnasio y pie con el link de baja.
3. **Vista previa** (`POST config/avisos/vista-previa`, con datos de ejemplo: «Juan Pérez», el primer plan de período con su precio de lista, la primera sede) y **Enviar prueba** a una casilla (`POST config/avisos/prueba`, `GYM_CFG_PARAMETROS_EDITAR`, auditado, asunto con «[Prueba]»), desde la misma casilla que los avisos reales. `GET config/avisos` devuelve los textos vigentes, los originales, las variables y si sale desde una casilla propia (se muestra) o la del sistema (no se muestra la dirección: «la casilla de Novasis»).
4. Código existente tocado: solo `prisma/schema.prisma` (columna `gym_config.avisos_plantillas`, migración `20261116130000_gym_avisos_plantillas`, sólo agrega). Se quitaron `asuntoAviso`/`htmlAviso` de `avisos-reglas.ts` (los reemplaza la plantilla).

Pruebas: jest del gimnasio 319 (`avisos-plantillas.spec.ts`: texto original idéntico al anterior, párrafos con variable vacía, escapado, validación, guardar solo lo editado); vitest de Reglas 8; e2e `gimnasio-avisos-texto.real.spec.js` 3/3 contra local (editar, variable mal escrita bloquea Guardar, vista previa en el iframe, guardar, volver al original, apagar; con `E2E_EMAIL_PRUEBA` manda una prueba real).

**Para activarlo en un cliente:** `migrate deploy` (`20261116130000_gym_avisos_plantillas`). Sin tocar nada, los avisos siguen como antes (texto original, prendidos). Fly Active no tiene casilla propia: salen desde la del sistema con su nombre; solo 141 de sus 301 socios tienen email.
