{"id":25085644,"url":"https://github.com/asobrados03/hotelmanagementapi","last_synced_at":"2026-04-13T21:02:26.507Z","repository":{"id":275049966,"uuid":"924913869","full_name":"asobrados03/HotelManagementAPI","owner":"asobrados03","description":"API RESTful para la gestión de un hotel, permitiendo administrar reservas, habitaciones, pagos, clientes y administradores, con autenticación, validaciones y documentación en Swagger/OpenAPI","archived":false,"fork":false,"pushed_at":"2025-06-05T08:56:25.000Z","size":551,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-06T02:41:55.947Z","etag":null,"topics":["clean-architecture","design-patterns","docker","docker-container","docker-image","gradle-java","hexagonal-architecture","java","junit5","jwt","jwt-authentication","lombok-gradle","mariadb-database","mockito","spring-boot","spring-data-jdbc","spring-security","springboot","swagger-openapi","testcontainers-java"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/asobrados03.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-01-30T21:35:37.000Z","updated_at":"2025-06-05T08:56:26.000Z","dependencies_parsed_at":"2025-01-30T22:31:27.169Z","dependency_job_id":"071fc349-1631-4745-b45b-a10a3be686ea","html_url":"https://github.com/asobrados03/HotelManagementAPI","commit_stats":null,"previous_names":["asobrados03/hotelmanagementapi"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/asobrados03/HotelManagementAPI","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asobrados03%2FHotelManagementAPI","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asobrados03%2FHotelManagementAPI/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asobrados03%2FHotelManagementAPI/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asobrados03%2FHotelManagementAPI/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/asobrados03","download_url":"https://codeload.github.com/asobrados03/HotelManagementAPI/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asobrados03%2FHotelManagementAPI/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31770726,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T20:17:16.280Z","status":"ssl_error","status_checked_at":"2026-04-13T20:17:08.216Z","response_time":93,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clean-architecture","design-patterns","docker","docker-container","docker-image","gradle-java","hexagonal-architecture","java","junit5","jwt","jwt-authentication","lombok-gradle","mariadb-database","mockito","spring-boot","spring-data-jdbc","spring-security","springboot","swagger-openapi","testcontainers-java"],"created_at":"2025-02-07T08:29:23.694Z","updated_at":"2026-04-13T21:02:26.490Z","avatar_url":"https://github.com/asobrados03.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HotelManagementAPI - Ejercicio de DeHaroHub\n¡Hola y bienvenido!\nEste desarrollo se trata de un ejercicio propuesto en la comunidad de Skool DeHaroHub por Nacho De Haro (el creador de la comunidad) en [este repositorio](https://github.com/Deharotech/DHHotel). En el propio enunciado pone que se debe realizar una PR en ese mismo repositorio para que toda la gente de la comunidad pueda revisarlo, aprender de él y aportar su granito de arena. Pero como la comunidad esta inactiva y actualmente cerrada porque el creador esta a otras cosas he optado por publicar mi desarrollo en este repositorio.\n\n## Índice\n\n- [Descripción](#descripción)\n- [Objetivo](#objetivo)\n- [Características Funcionales](#características-funcionales)\n- [Requerimientos Técnicos](#requerimientos-técnicos)\n- [Arquitectura del Proyecto](#arquitectura-del-proyecto)\n- [Tecnologías Utilizadas](#tecnologías-utilizadas)\n- [Instalación y Configuración](#instalación-y-configuración)\n  - [Requisitos Previos](#requisitos-previos)\n  - [Configuración de Docker](#configuración-de-docker)\n  - [Ejecutar la API](#ejecutar-la-api)\n- [Documentación de la API](#documentación-de-la-api)\n- [Pruebas](#pruebas)\n- [Desafíos Adicionales y Mejoras Futuras](#desafíos-adicionales-y-mejoras-futuras)\n- [Contribuciones](#contribuciones)\n- [Licencia](#licencia)\n\n## Descripción\n\nEsta API RESTful permite la gestión completa de un hotel, incluyendo la administración de clientes, habitaciones, reservas, pagos y administradores. Se ha desarrollado utilizando Java con Spring Boot, aplicando los principios de una arquitectura limpia para separar la lógica de negocio del acceso a datos y la presentación.\n\n## Objetivo\n\nEl objetivo de este proyecto es crear una API para la gestión de un hotel que permita:\n\n- Manejar reservas, habitaciones, pagos, clientes y administradores.\n- Implementar la lógica de negocio, estructuras de datos y endpoints necesarios.\n- Aprender las habilidades en la creación de APIs RESTful, mejorar el manejo de bases de datos y aplicación de buenas prácticas en arquitectura de software.\n\n## Características Funcionales\n\n### Clientes\n- **CRUD**: Crear, leer, actualizar y eliminar clientes.\n- **Campos obligatorios**: ID, Nombre, Apellidos, Correo electrónico, Número de teléfono.\n\n### Habitaciones\n- **CRUD**: Crear, leer, actualizar y eliminar habitaciones.\n- **Campos obligatorios**: ID, Número de habitación, Tipo de habitación (simple, doble, suite), Precio por noche, Estado (disponible, ocupada, en mantenimiento).\n\n### Reservas\n- **CRUD**: Crear, leer, actualizar y cancelar reservas.\n- **Campos obligatorios**: ID, ID del cliente, ID de la habitación, Fecha de inicio, Fecha de fin, Estado (pendiente, confirmada, cancelada).\n\n### Pagos\n- **Registro de pagos**: Asociados a una reserva.\n- **Campos obligatorios**: ID, ID de la reserva, Monto, Fecha de pago, Método de pago (tarjeta, efectivo, transferencia).\n\n### Administradores\n- **CRUD**: Crear, leer, actualizar y eliminar administradores.\n- **Campos obligatorios**: ID, Nombre, Correo electrónico, Contraseña (hasheada), Rol (admin, superadmin).\n\n### Autenticación y Autorización\n- Implementación de autenticación JWT para administradores y clientes.\n- Solo los administradores pueden crear, actualizar o eliminar habitaciones y reservas.\n- Los clientes pueden crear y ver sus reservas, pero no modificarlas una vez confirmadas.\n\n## Requerimientos Técnicos\n\n- **Lenguaje y Framework**: Java con Spring Boot.\n- **Base de Datos**: MariaDB ejecutado en un contenedor Docker, con un script sql para crear y poblar las tablas de la base de datos.\n- **ORM**: No he usado ningún ORM en su lugar he usado JDBC de manera directa ya que es más flexible.\n- **Contenedores**: Docker para MariaDB y Adminer.\n- **Documentación**: Swagger/OpenAPI para la documentación de la API.\n- **Pruebas**: Pruebas unitarias y de integración con JUnit5, Mockito, Testcontainers y Postman para pruebas manuales de la API.\n\n## Diagrama Entidad-Relación de la Base de Datos de la API\n\n```mermaid\nerDiagram\n    User {\n        INT id PK\n        VARCHAR email\n        VARCHAR password\n        ENUM role \"CLIENT, ADMIN, SUPERADMIN\"\n    }\n\n    Client {\n        INT id PK\n        INT user_id FK\n        VARCHAR first_name\n        VARCHAR last_name\n        VARCHAR phone\n    }\n\n    Administrator {\n        INT id PK\n        INT user_id FK\n        VARCHAR name\n    }\n\n    Room {\n        INT id PK\n        INT room_number\n        ENUM room_type \"SINGLE, DOUBLE, SUITE\"\n        DECIMAL price_per_night\n        ENUM status \"AVAILABLE, OCCUPIED, MAINTENANCE\"\n    }\n\n    Reservation {\n        INT id PK\n        INT client_id FK\n        INT room_id FK\n        DECIMAL total_price\n        DATE start_date\n        DATE end_date\n        ENUM status \"PENDING, CONFIRMED, CANCELED\"\n    }\n\n    Payment {\n        INT id PK\n        INT reservation_id FK\n        DECIMAL amount\n        DATE payment_date\n        ENUM payment_method \"CARD, CASH, TRANSFER\"\n    }\n\n    Client ||--o{ Reservation : has\n    Room ||--o{ Reservation : \"is booked in\"\n    Reservation ||--o{ Payment : has\n    User ||--|| Client : \"is a\"\n    User ||--|| Administrator : \"is a\"\n```\n\n## Arquitectura del Proyecto\n\nEl proyecto está organizado siguiendo una arquitectura limpia:\n\n- **Adaptadores**:  \n  - Controladores REST para recibir peticiones y enviar respuestas.\n  - DTOs para el mapeo de datos entre la API y la lógica de negocio.\n  - Adaptador de seguridad (JWT, filtros, etc.).\n  \n- **Aplicación**:  \n  - Casos de Uso que orquestan la lógica de negocio.\n\n- **Dominio**:  \n  - Entidades de dominio (Modelos) y lógica de negocio.\n  - Interfaces de repositorios (Puertos).\n\n- **Infraestructura**:  \n  - Implementaciones de repositorios (con JDBC).\n  - Configuración de acceso a la base de datos (MariaDB en Docker).\n \n### Diagrama hexagonal de la arquitectura general y limpia de la API\n\n![Arquitectura hexagonal de la API](resources/Arquitectura-hexagonal-API-Gestión-Hotel.png)\n\n### Diagrama de flujo general de la arquitectura\n\n```mermaid\ngraph TD;\n  subgraph CLIENTE\n    Client[\"💻 Cliente (Front-end)\"]\n  end\n\n  subgraph ADAPTADORES\n    Controller[\"🌐 @RestController Controladores Web\"]\n    DTOs[\"🔌 DTOs \n    (Request/Response)\"]\n    Security[\"🔐 Filtros y JWT \n    (Adaptador de Seguridad)\"]\n  end\n\n  subgraph APLICACIÓN\n    UseCase[\"⚙️ Casos de Uso \n    (Lógica de Negocio)\"]\n  end\n\n  subgraph DOMINIO\n    Entities[\"🗃️ Entidades de Dominio (Modelos)\"]\n    Ports[\"📁 Interfaces de Repositorios (Puertos)\"]\n  end\n\n  subgraph INFRAESTRUCTURA\n    RepoImpl[\"📂 @Repository Implementación de Repositorios con JDBC\"]\n    DB[\"🗄️🐋 Base de Datos (MariaDB)\"]\n  end\n\n  Client -- \"HTTP Request\" --\u003e Controller\n  Controller -- \"DTO Mapping\" --\u003e UseCase\n  UseCase -- \"Invoca reglas de negocio\" --\u003e Entities\n  UseCase -- \"Solicita persistencia\" --\u003e Ports\n  Ports -- \"Implementado por\" --\u003e RepoImpl\n  RepoImpl -- \"Acceso a datos\" --\u003e DB\n  Controller -- \"HTTP Response\" --\u003e Client\n  %% Opcional: Integración de seguridad\n  Controller -- \"Autenticación/Autorización\" --\u003e Security\n```\n\n### Esquema del Proceso de Autenticación/Registro basado en JWT (JSON Web Tokens)\n\n```mermaid\ngraph TD;\n    subgraph CLIENTE\n        Cliente[\"💻 Cliente (Front-end)\"]\n    end\n\n    subgraph FILTROS\n        JwtFilter[\"🔍 JwtAuthenticationFilter{}🔸 Verifica si el JWT es null\"]\n    end\n\n    subgraph AUTENTICACION\n        AuthController[\"🔐 AuthenticationController{}\"]\n        AuthService[\"⚙️ AuthenticationService{}\"]\n        JwtService[\"🛠️ JwtService{}\n        🔸Genera JWT Token\"]\n    end\n\n    subgraph REPOSITORIO\n        UserRepo[\"📂UserRepository{} 🔸Guarda/Obtiene UserDetail\"]\n        User[\"🧑‍💼 User{}\n        🔸Implementa UserDetails\"]\n    end\n\n    subgraph CONFIGURACION\n        Config[\"⚙️ ApplicationConfig 🔸Authentication Manager 🔸Providers 🔸PasswordEncoders\"]\n    end\n\n    subgraph BASE DE DATOS\n        DB[(\"🗄️🐋 Base de Datos (MariaDB)\")]\n    end\n\n    %% Flujo del proceso de autenticación\n    Cliente -- \"HTTP Request\" --\u003e JwtFilter\n    JwtFilter --\u003e AuthController\n    AuthController --\u003e AuthService\n    AuthService --\u003e UserRepo\n    UserRepo --\u003e User\n    User --\u003e DB\n\n    AuthService --\u003e JwtService\n    JwtService --\u003e AuthController\n    AuthController -- \"HTTP Response (JWT Token)\" --\u003e Cliente\n\n    %% Conexiones de configuración\n    Config -.-\u003e AuthService\n```\n\n### Esquema del Proceso de Validación JWT\n\n```mermaid\ngraph TD;\n    subgraph CLIENTE\n        Cliente[\"💻 Cliente (Front-end)\"]\n    end\n\n    subgraph FILTROS\n        JwtFilter[\"🔍 JwtAuthenticationFilter{}🔸 Verifica el JWT\"]\n    end\n\n    subgraph SERVICIOS\n        JwtService[\"🛠️ JwtService{}\n        🔸Extrae el usuario del JWT \n        🔸Verifica el token\"]\n        UserDetailsService[\"⚙️ UserDetailsService{} 🔸 loadUserByUsername()\"]\n    end\n\n    subgraph REPOSITORIO\n        User[\"🧑‍💼 User{}\n        🔸Implementa UserDetails\"]\n        DB[(\"🗄️🐋 Base de Datos\")]\n    end\n\n    subgraph SecurityContext\n        Authentication[\"🔐Authentication\n        Principle  | Credentials | Authorities\"]\n    end\n\n    subgraph CONTROLADOR\n        Controller[\"⚡ Controller{}\"]\n    end\n\n    %% Flujo del proceso de validación JWT\n    Cliente -- \"HTTP Request (Token)\" --\u003e JwtFilter\n    JwtFilter --\u003e JwtService\n    JwtService --\u003e UserDetailsService\n    UserDetailsService --\u003e User\n    User --\u003e DB\n\n    JwtFilter --\u003e Authentication\n    Authentication --\u003e Controller\n    Controller -- \"✅ HTTP Response (JSON)\" --\u003e Cliente\n\n    %% Manejo de errores (403)\n    JwtFilter -- \"❌ HTTP 403: Token inválido\" --\u003e Cliente\n    JwtFilter -- \"❌ HTTP 403: Falta token o usuario no existe\" --\u003e Cliente\n```\n\n## Tecnologías Utilizadas\n\n- **Java 21+**\n- **Spring Boot**\n- **Spring Security con JWT**\n- **JDBC**\n- **Docker**  \n  - **MariaDB**\n  - **Adminer**\n- **Swagger/OpenAPI**\n- **Gradle**\n- **JUnit5**\n- **Mockito**\n- **Testcontainers**\n- **Postman**\n\n## Instalación y Configuración\n\n### Requisitos Previos\n\n- JDK 21 o superior instalado.\n- Docker y Docker Compose instalados.\n- Git instalado.\n\n### Configuración de Docker\n\nEl proyecto incluye un archivo `docker-compose.yml` para levantar la base de datos y Adminer. Un ejemplo de `docker-compose.yml` podría ser:\n\n```yaml\nversion: '3.8'\n\nservices:\n  mariadb:\n    image: mariadb:10.5\n    container_name: hotel-mariadb\n    environment:\n      MYSQL_ROOT_PASSWORD: rootpassword\n      MYSQL_DATABASE: hotel_db\n      MYSQL_USER: hoteluser\n      MYSQL_PASSWORD: hotelpassword\n    ports:\n      - \"3306:3306\"\n    volumes:\n      - db_data:/var/lib/mysql\n\n  adminer:\n    image: adminer\n    container_name: hotel-adminer\n    ports:\n      - \"8080:8080\"\n\nvolumes:\n  db_data:\n```\n\nPara iniciar los contenedores, ejecuta en la raíz del proyecto:\n\n```bash\ndocker compose up -d\n```\n\n### Ejecutar la API\n\n\u003e [!CAUTION]\n\u003e Antes de ejecutar el código fuente de la API, el contenedor Docker con la base de datos MariaDB debe estar corriendo.\n\n1. Clona el repositorio:\n   ```bash\n   git clone https://github.com/asobrados03/HotelManagementAPI.git\n   cd HotelManagementAPI\n   ```\n\n2. Compila y ejecuta la aplicación:\n   ```bash\n   ./gradlew build\n   ./gradlew bootRun\n   ```\n\n3. La API estará disponible en `http://localhost:8080`.\n\n## Documentación de la API\n\nLa documentación interactiva se genera automáticamente con Swagger. Una vez iniciada la aplicación, puedes acceder a ella en:\n- `http://localhost:8080/swagger-ui.html` o\n- `http://localhost:8080/swagger-ui/index.html`\n\n## Pruebas\n\nSe han implementado pruebas unitarias y de integración para asegurar el correcto funcionamiento de la API. Para ejecutarlas:\n\n```bash\n./gradlew test\n```\n\n\u003e [!IMPORTANT]\n\u003e Para las pruebas de integración debe estar corriendo Docker en la máquina.\n\n## Desafíos Adicionales y Mejoras Futuras\n\n- **Optimización de Consultas:** Mejorar el rendimiento en operaciones complejas sobre reservas y habitaciones.\n- **Gestión de Estados:** Refinar la lógica de transición de estados en reservas.\n- **Manejo de Concurrencia:** Evitar sobre-reservas mediante bloqueos o estrategias de concurrencia.\n- **Escalabilidad:** Adaptar la API para despliegues en entornos distribuidos o en la nube.\n- **Seguridad:** Mejorar la protección contra ataques (SQL Injection, XSS, etc.) y optimizar el manejo de autenticación y autorización.\n\n## Contribuciones\n\n¡Las contribuciones son bienvenidas! Si deseas colaborar en el proyecto, sigue estos pasos:\n\n1. Realiza un fork del repositorio.\n2. Crea una rama para tu funcionalidad: `git checkout -b feature/nueva-funcionalidad`.\n3. Realiza tus cambios y haz commit.\n4. Envía un pull request describiendo los cambios realizados.\n\n## Licencia\n\nEste proyecto se distribuye bajo la [Licencia MIT](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasobrados03%2Fhotelmanagementapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fasobrados03%2Fhotelmanagementapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasobrados03%2Fhotelmanagementapi/lists"}