Hotelería HO-001 a HO-009

¿Qué es el módulo de Hotelería?

El módulo de Hotelería permite operar un hotel, posada o cabinas dentro de FactuPOS: registrar huéspedes, crear reservaciones multi-habitación, controlar check-in / check-out, llevar limpieza y mantenimiento, ver ocupación en línea de tiempo y obtener métricas hoteleras (ADR, RevPAR, ocupación).

Reemplaza al módulo legacy Reservaciones y se integra con el resto del sistema:

• Clientes: los huéspedes pueden vincularse a un ClienteCodigo de FactuPOS para facturarles directamente. El default es SN (cliente genérico).
• Artículos: cada habitación puede tener un código de artículo asociado para facturar la noche.
• Parámetros: usa los parámetros estándar (moneda, IVA, empresa).

Menú principal HO-001

Página landing de Hotelería. Muestra 8 tiles que llevan a cada submódulo. Se accede desde el menú principal de FactuPOS (slot Hotelería).

Recepción HO-002

Dashboard operativo del front desk para el día seleccionado. Layout en 2 columnas: sidebar de grupos a la izquierda + lista de detalle a la derecha.

Sidebar de grupos (izquierda)

Cinco fichas clickables, cada una con icono, etiqueta, sublabel y contador grande. Al hacer click se filtra la lista de la derecha:

• Llegadas hoy — reservas pendientes/confirmadas con check-in hoy o anteriores no procesadas.
• En casa — huéspedes con estado CheckIn activos.
• Salidas hoy — huéspedes en casa con check-out previsto = hoy.
• Disponibles — habitaciones sin reserva activa que cubra la fecha.
• Vencidas (alerta roja) — huéspedes en casa con check-out previsto < hoy.

Lista de detalle (derecha)

Cada fila muestra: Habitación · Cliente (Nombre + Cédula + Teléfono + Dirección) · Llegada · Salida · Estado · Acciones.

• Habitación: chip azul con código. Si la reserva tiene varias habitaciones, indica +N.
• Estado: chip color según contexto — Pendiente Confirmada En casa rosa "Sale hoy" rojo "Vencida".
• Acciones: Confirmar, Check-In, Check-Out, Hospedar (libres), Detalle (abre la reservación completa).

Toolbar superior

• Fecha: input + botón Hoy para volver al día actual.
• Walk-in (header): redirige a reservaciones.php?walkin=1 para hospedar un huésped sin reserva previa.
• Refrescar: recarga manual; el dashboard también auto-refresca cada 60 segundos.
• Banner rojo si hay reservaciones vencidas.

Calendario habitaciones HO-003

Vista timeline (Gantt) con una fila por habitación y columnas por día. Permite ver de un vistazo la ocupación del rango.

Layout

• Header de fechas sticky arriba: día de semana + número + mes; fines de semana en azul más oscuro; hoy en verde con borde inferior amarillo.
• Columna habitación sticky izquierda: código + tipo + porcentaje de ocupación del rango (chip color).
• Bookings: bloques rectangulares que ocupan los días reservados. Atraviesan varias celdas como un solo segmento.

Estados (color del booking)

• Pendiente ámbar #f59e0b
• Confirmada azul #0047AB
• CheckIn verde #15803d con borde amarillo y emoji 🏠 (en casa)
• CheckOut gris

Navegación

• Botones ← / Hoy / →: avanza o retrocede el rango completo.
• Presets 7 / 15 / 30 / 90 días.
• Inputs Desde / Hasta para rango manual.

Interacción

• Click en un booking → abre la reservación (reservaciones.php?open={id}).
• Click en una celda libre → walk-in pre-cargado con la habitación y fecha (reservaciones.php?walkin=1&hab=...&fecha=...).

Reservaciones HO-004

CRUD completo de reservaciones con workflow de estados, multi-habitación y tarifas automáticas por temporada.

Listado

• 5 KPIs: llegadas hoy, salidas hoy, en check-in, confirmadas, pendientes.
• Filtros: búsqueda libre (consecutivo / huésped / cédula), estado, rango de check-in.
• Botón Nuevo abre el modal de reservación vacío.

Modal de reservación

1. Huésped: dos campos — Nombre manual y ClienteCodigo (default SN). Botones para abrir el modal de búsqueda de clientes o crear cliente nuevo.
2. Fechas: Check-In previsto y Check-Out previsto en formato DD/MM/AAAA HH:MM (Flatpickr). Al cambiarlas, las líneas de habitaciones se sincronizan automáticamente.
3. Adultos / Niños / Origen / Notas.
4. Habitaciones (líneas dinámicas): seleccionar de un modal de "disponibles" que excluye las que ya tienen reserva con overlap. Al agregar, se busca automáticamente la tarifa de la temporada que cubre la fecha.
5. Resumen: subtotal, anticipo, total — recalculado en tiempo real.
6. Workflow buttons según estado actual.

Walk-in

Llegando a reservaciones.php?walkin=1&hab=XXX&fecha=YYYY-MM-DD se abre el modal pre-cargado con la habitación y fecha indicadas. Los parámetros de URL se limpian con history.replaceState para que un refresh no reabra la reserva.

Habitaciones HO-005

Catálogo de habitaciones físicas del hotel.

• KPIs por estado físico: Disponible · Limpia · Sucia · Bloqueada · Mantenimiento.
• Filtros: búsqueda texto, tipo, estado, activa.
• Modal completo: código, tipo, piso, características, código de artículo (para facturar la noche), capacidad adultos/niños, activa.
• Botón ⟳ "cambiar estado rápido" registra el cambio en HotelHousekeepingLog.
• Validaciones: código único, no eliminar si tiene reservaciones, estado físico de lista cerrada.

Huéspedes HO-006

Listado de huéspedes con historial de reservaciones. No es una BD aparte — todo huésped está vinculado a un cliente FactuPOS vía ClienteCodigo.

• Filtros: búsqueda (cédula / nombre / email), nacionalidad, activo.
• Modal completo: tipo identificación (01-05 Hacienda), cédula, nombre, apellidos, fecha nacimiento, sexo, nacionalidad, teléfono, email, dirección, vínculo opcional a Cliente FactuPOS, notas.
• Avatar con iniciales en gradiente azul, contador de reservas.
• Validaciones: nombre requerido, email RFC, sexo M/F, ClienteCodigo verificado contra vista_cliente.

Housekeeping HO-007

Vista operativa para personal de limpieza y mantenimiento.

• Cards por habitación con fondo según estado físico (verde/azul/ámbar/rojo/morado).
• Botones grandes para cambio rápido de estado (no muestra el estado actual, solo los demás).
• Modal con campo de notas opcional (registra en bitácora).
• Si la habitación está en CheckIn, muestra el huésped actual.
• Filtro por piso, KPIs por estado físico.
• Bitácora últimos 50 cambios con marca de tiempo, estado anterior → nuevo, usuario y notas.
• Auto-refresca cada 90 segundos.

Reportes HO-008

Analítica hotelera con métricas estándar de la industria.

• 6 KPIs grandes: Ocupación %, ADR (tarifa diaria promedio), RevPAR (ingreso por habitación disponible), Ingreso total, Reservas únicas, Noches ocupadas.
• Gráfico CSS de ocupación día a día (FDS distinto, hoy con highlight).
• Tabla por tipo de habitación: reservas / noches / ADR / ingreso + % del total.
• Tabla por origen / canal: reservas / noches / ingreso + %.
• Top 10 huéspedes por ingreso.
• Presets: Hoy, 7 días, 30 días, Este mes, Mes pasado, Año.

Fórmulas

Configuración HO-009

Setup del módulo en 4 tabs:

Tab 1 — Tipos de habitación

• Código, nombre, capacidad adultos / niños, descripción.
• Validación: código único.

Tab 2 — Temporadas

• Patrones recurrentes anuales (sin año, sólo MM-DD).
• Una temporada se compone de bloques (cadena sin huecos): cada bloque tiene rango FechaInicio → FechaFin.
• Manejadores entre bloques permiten arrastrar la frontera para reasignar días.
• Bloque solo necesita ID y rango — no requiere nombre/código.

Tab 3 — Tarifas

• Por tipo + temporada: precio por noche, moneda (default param 249).
• El sistema busca automáticamente la tarifa aplicable comparando MM-DD de la fecha de reserva contra los bloques de cada temporada.
• Si dos temporadas coinciden en un día, gana la de mayor prioridad ("premium").

Tab 4 — Parámetros

• Hora estándar de check-out (default 11:00 CR).
• Otros parámetros operativos del hotel.

Estados de reservación

Workflow de estados de una reservación:

Las transiciones se validan tanto en cliente como en servidor. CheckIn y CheckOut registran automáticamente la fecha real.

Flujo típico de operación

Errores comunes

• "Sin tarifa configurada" al agregar habitación → la fecha de reserva no cae dentro de ninguna temporada con tarifa para ese tipo. Revisar HO-009 → Temporadas / Tarifas.
• "Habitación no disponible" → ya tiene una reserva activa con overlap en el rango. El sistema previene double-booking.
• "Cliente no encontrado" → el ClienteCodigo manual no existe en vista_cliente. Usar SN o el botón de búsqueda de cliente.
• "Reservación con check-out vencido" (banner rojo en Recepción) → huésped en casa con fecha de salida pasada; ir al grupo "Vencidas" y procesar el check-out.
• Calendario muestra fecha sin reserva pero la reserva existe → verificar el rango de fechas del calendario; expandir con preset 30 o 90 días si la salida queda fuera del rango actual.