Altairis Backoffice

Sistema de gestión hotelera full-stack con panel de control para administrar hoteles, reservas, inventario y usuarios.

---

Índice

1. Instalación
2. Acceso a la aplicación
3. Stack tecnológico
4. Credenciales de acceso
5. Roles y permisos
6. Instrucciones de uso
7. API REST — Referencia de endpoints

---

Instalación

Requisitos previos

• Docker o Docker Desktop instalado y en ejecución

Levantar toda la aplicación

docker compose up --build

Este único comando:

1. Descarga e inicia PostgreSQL 16
2. Compila y lanza el backend Spring Boot (espera a que la BD esté lista)
3. Compila y sirve el frontend Vue 3 via Nginx
4. Ejecuta el seeder automáticamente al arrancar el backend — carga hoteles, tipos de habitación, usuarios, inventario y reservas de ejemplo

La primera vez tarda varios minutos (descarga de imágenes y compilación Maven). Las siguientes ejecuciones son mucho más rápidas gracias al caché de Docker.

Para detener todos los servicios:

docker compose down

Para detener y borrar también los datos de la base de datos:

docker compose down -v

---

Acceso a la aplicación

⚠️ La URL de entrada es directamente la pantalla de login:

http://localhost/login

Servicio	URL
Frontend (login)	http://localhost/login
API REST	http://localhost:8080
Base de datos	localhost:5432

---

Stack tecnológico

Backend

Tecnología	Versión	Justificación
Java	17	LTS activo, soporte hasta 2029, referencia en el ecosistema empresarial
Spring Boot	4.0	Framework estándar de facto para APIs REST en Java; autoconfiguración, seguridad y JPA integrados
Spring Security + JWT	—	Autenticación stateless adecuada para SPAs; los tokens se validan en cada petición sin estado en servidor
Spring Data JPA / Hibernate	—	Abstracción de acceso a datos que elimina SQL boilerplate; migraciones automáticas con ddl-auto=update
PostgreSQL	16	Base de datos relacional robusta, ACID, con soporte nativo en Spring y amplia compatibilidad con herramientas de producción
Maven	3.9	Gestión de dependencias y ciclo de build estándar en el ecosistema Spring

Frontend

Tecnología	Versión	Justificación
Vue 3	3.5	Framework progresivo con Composition API; curva de aprendizaje suave y rendimiento optimizado con el compilador de plantillas
TypeScript	5.x	Tipado estático que previene errores en tiempo de desarrollo y mejora el mantenimiento del código
Vite	5.x	Servidor de desarrollo ultrarrápido con HMR nativo; build de producción optimizado con Rollup
Pinia	2.x	Store oficial de Vue 3; más simple y tipado que Vuex, integración nativa con Devtools
Vue Router	4.x	Enrutado oficial con guards de navegación para control de acceso por rol
PrimeVue 4	4.x	Librería de componentes UI completa y accesible; tema personalizable con tokens CSS
Axios	1.x	Cliente HTTP con interceptores para adjuntar JWT y gestionar errores 401 globalmente
vue-i18n	9.x	Internacionalización completa ES/EN con cambio dinámico de idioma
MSW (Mock Service Worker)	—	Intercepta peticiones HTTP en el navegador; permite desarrollo y testing sin depender del backend

Infraestructura

Tecnología	Justificación
Docker + Docker Compose	Entorno reproducible en cualquier máquina con un solo comando; aísla servicios y elimina problemas de configuración local
Nginx	Servidor estático de alto rendimiento; actúa como proxy inverso hacia la API eliminando problemas de CORS en producción

---

Credenciales de acceso

Administrador global

Email	Contraseña	Acceso
admin@altairis.com	admin123	Panel completo: hoteles, usuarios, reservas, inventario de todos los hoteles

Administradores de hotel

Email	Contraseña	Hotel
hadmin@central.com	hadmin123	Hotel Central (Madrid)
hadmin@seaside.com	hadmin123	Seaside Resort (Valencia)
hadmin@mountain.com	hadmin123	Mountain Lodge (Granada)
hadmin@business.com	hadmin123	Business Tower (Barcelona)
hadmin@palace.com	hadmin123	Historic Palace (Seville)

Staff

Email	Contraseña	Hotel
staff1@central.com	staff123	Hotel Central (Madrid)
staff2@central.com	staff123	Hotel Central (Madrid)
staff@seaside.com	staff123	Seaside Resort (Valencia)
staff@mountain.com	staff123	Mountain Lodge (Granada)
staff1@business.com	staff123	Business Tower (Barcelona)
staff2@business.com	staff123	Business Tower (Barcelona)
staff@palace.com	staff123	Historic Palace (Seville)

---

Roles y permisos

Rol	Descripción	Acceso
ROLE_ADMIN	Administrador global	Todo el sistema: todos los hoteles, usuarios, reservas e inventario
ROLE_HOTEL_ADMIN	Administrador de hotel	Gestión completa de su hotel asignado: reservas, inventario, tipos de habitación
ROLE_STAFF	Personal de hotel	Solo gestión de reservas de su hotel asignado

---

Instrucciones de uso

1. Dashboard

Disponible para ROLE_ADMIN y ROLE_HOTEL_ADMIN. Muestra KPIs de ocupación, ingresos y reservas recientes. El admin global ve datos agregados de todos los hoteles; el admin de hotel ve solo los suyos.

2. Hoteles

Exclusivo para ROLE_ADMIN. Permite crear, editar, activar/desactivar propiedades y acceder al detalle de cada hotel donde se gestionan sus tipos de habitación.

3. Inventario

Disponible para todos los roles. Muestra la disponibilidad de habitaciones por fecha y tipo. Permite ajustar manualmente unidades disponibles.

4. Reservas

Disponible para todos los roles. Ciclo de vida completo: PENDING → CONFIRMED → CHECKED_IN → CHECKED_OUT. También permite cancelar (CANCELLED) o marcar como no presentado (NO_SHOW). El staff solo ve las reservas de su hotel.

5. Usuarios

Exclusivo para ROLE_ADMIN. Gestión completa de usuarios: crear, editar rol y hotel asignado, cambiar contraseña y eliminar.

Idioma y tema

En la barra superior hay controles para cambiar el idioma (ES/EN) y el tema (claro/oscuro). La preferencia se guarda en localStorage.

---

API REST — Referencia de endpoints

Base URL: http://localhost:8080

Todos los endpoints excepto /auth/login requieren el header:

Authorization: Bearer <token>

Autenticación — /auth

Método	Ruta	Acceso	Descripción
POST	/auth/login	Público	Obtiene el token JWT. Body: { "email": "...", "password": "..." }. Devuelve { token, expiresIn, user }

---

Hoteles — /hotels

Método	Ruta	Acceso	Descripción
GET	/hotels	Autenticado	Lista paginada. Params: page, size, name, city, sort
GET	/hotels/{id}	Autenticado (propio hotel)	Detalle de un hotel
POST	/hotels	ROLE_ADMIN	Crear hotel
PUT	/hotels/{id}	ROLE_ADMIN	Actualizar hotel
DELETE	/hotels/{id}	ROLE_ADMIN	Eliminar hotel → 204 No Content

Tipos de habitación — /hotels/{hotelId}/room-types

Método	Ruta	Acceso	Descripción
GET	/hotels/{hotelId}/room-types	Autenticado (propio hotel)	Lista todos los tipos del hotel
GET	/hotels/{hotelId}/room-types/{id}	Autenticado (propio hotel)	Detalle de un tipo
POST	/hotels/{hotelId}/room-types	ADMIN o HOTEL_ADMIN (propio)	Crear tipo de habitación
PUT	/hotels/{hotelId}/room-types/{id}	ADMIN o HOTEL_ADMIN (propio)	Actualizar tipo de habitación
DELETE	/hotels/{hotelId}/room-types/{id}	ROLE_ADMIN	Eliminar tipo de habitación → 204 No Content

---

Reservas — /reservations

Método	Ruta	Acceso	Descripción
GET	/reservations	Autenticado	Lista paginada. Params: page, size, status, hotelId, from, to, sort
GET	/reservations/stats	ADMIN o HOTEL_ADMIN	KPIs agregados de reservas
GET	/reservations/today	Autenticado	Check-ins y check-outs del día
GET	/reservations/{id}	Autenticado	Detalle de una reserva
POST	/reservations	Autenticado	Crear reserva
PATCH	/reservations/{id}/status	Autenticado	Cambiar estado. Body: { "status": "CONFIRMED" | "CHECKED_IN" | "CHECKED_OUT" | "CANCELLED" | "NO_SHOW" }

Estados válidos y transiciones:

PENDING → CONFIRMED → CHECKED_IN → CHECKED_OUT
    ↓           ↓           ↓
CANCELLED   CANCELLED   NO_SHOW

---

Inventario — /inventory

Método	Ruta	Acceso	Descripción
GET	/inventory/grid	Autenticado (propio hotel)	Cuadrícula de disponibilidad. Params requeridos: hotelId, startDate, endDate (yyyy-MM-dd)
GET	/inventory/room-type/{roomTypeId}	Autenticado	Disponibilidad por tipo de habitación
POST	/inventory	ADMIN o HOTEL_ADMIN	Crear entrada de inventario
POST	/inventory/bulk	ADMIN o HOTEL_ADMIN	Creación masiva de inventario (rango de fechas)
PUT	/inventory/{id}	ADMIN o HOTEL_ADMIN	Actualizar disponibilidad de una entrada

---

Usuarios — /users

Método	Ruta	Acceso	Descripción
GET	/users	ADMIN o HOTEL_ADMIN	Lista todos los usuarios. Param opcional: hotelId
POST	/users	ADMIN o HOTEL_ADMIN	Crear usuario
PUT	/users/{id}	ADMIN o HOTEL_ADMIN	Actualizar usuario
DELETE	/users/{id}	ADMIN o HOTEL_ADMIN	Eliminar usuario → 204 No Content

---

Dashboard — /dashboard

Método	Ruta	Acceso	Descripción
GET	/dashboard/summary	ADMIN o HOTEL_ADMIN	KPIs globales: ocupación, ingresos, reservas activas y hoteles. El HOTEL_ADMIN recibe solo los datos de su hotel

---