https://github.com/luiggi-piero/shepard-backend

API comercial para el alquiler de habitaciones y departamentos, organizado por roles como USER, ADMIN, GUEST, CLEANING, SECURITY y RECEPTION.
https://github.com/luiggi-piero/shepard-backend

auth0 java postgresql spring-boot spring-doc-openapi spring-security

Last synced: about 2 months ago
JSON representation

API comercial para el alquiler de habitaciones y departamentos, organizado por roles como USER, ADMIN, GUEST, CLEANING, SECURITY y RECEPTION.

Host: GitHub
URL: https://github.com/luiggi-piero/shepard-backend
Owner: Luiggi-piero
License: mit
Created: 2025-07-20T04:02:26.000Z (11 months ago)
Default Branch: main
Last Pushed: 2025-08-07T21:10:09.000Z (10 months ago)
Last Synced: 2025-08-07T23:21:43.425Z (10 months ago)
Topics: auth0, java, postgresql, spring-boot, spring-doc-openapi, spring-security
Language: Java
Homepage:
Size: 112 KB
Stars: 0
Watchers: 0
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

SHEPARD API

![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)

API Rest que ofrece servicios de reservación de habitaciones y departamentos desarrollada en Java con Spring Boot, Spring Security, Spring Doc, PostgreSQL, entre otros para la gestión de usuarios(login y registro).

## Índice

1. [Funcionalidades](#Funcionalidades)
2. [Requerimientos previos](#requerimientos-previos)
3. [Configuración](#configuración)
4. [Swagger](#swagger)
5. [Tecnologías utilizadas](#tecnologías-utilizadas)
6. [Estructura del proyecto](#estructura-del-proyecto)
7. [Modelo entidad-relación](#modelo-entidad-relación)
8. [Licencia](#licencia)

## Funcionalidades

🔐 Autenticación

| Método | Endpoint | Reglas de negocio |
|--------|----------|-------------------|
| POST | `/api/v1/login` | Inicia sesión y obtiene un Token JWT. |

👤 Usuarios

| Método | Endpoint | Reglas de negocio |
|--------|-------------------|-------------------|
| POST | `/api/v1/users/register` | - Verificar si todos los campos obligatorios se están ingresando correctamente.
- La API no debe permitir el registro de usuarios duplicados (con el mismo correo) y debe tener al menos un número y una letra mayúscula.
- Asignar el rol USER por defecto.
- La API debe retornar la información del nuevo usuario y el token.
- Si elige el rol RECEPTION, la propiedad receptionist es necesaria y de forma similar para el rol CLEANING con la propiedad cleaningStaff.
- Si el correo ya existe retornar un código HTTP 409.
- Si la contraseña tiene menos de 8 o más de 15 caracteres retornar un 400.
- Si la contraseña no tiene al menos un letra mayúscula y un número retornar un 400.|
| GET | `/users` | - Retornar los primeros 10 resultados ordenados por id.
- Devolver todos los atributos menos la contraseña.
- Obtener la respuesta con paginación para controlar el volumen de los datos.
- Solo el rol ADMIN puede obtener todos los usuarios. |
| GET | `/api/v1/users/{id}` | - Retornar el usuario que coincida con el id y que además se encuentre habilitado.
- Si no encuentra el usuario retornar un 404.
- Solo el rol ADMIN puede buscar usuarios. |
| UPDATE | `/api/v1/users/{id}` | - Si no se completan los campos obligatorios retorna un 400.
- Si no encuentra el usuario retornar un 404.
- Solo el rol ADMIN puede actualizar usuarios.
- Si elige el rol RECEPTION, la propiedad receptionist es necesaria y de forma similar para el rol CLEANING con la propiedad cleaningStaff.
- Si el correo ya existe retornar un código HTTP 409.
- Si la contraseña tiene menos de 8 o más de 15 caracteres retornar un 400.
- Si la contraseña no tiene al menos un letra mayúscula y un número retornar un 400.|
| DELETE | `/api/v1/users/{id}` | - Si la eliminación es exitosa retornar un 204.
- Si no encuentra el usuario retornar un 404.
- Solo el rol ADMIN puede eliminar usuarios. |

🏢 Departamentos

| Método | Endpoint | Reglas de negocio |
|--------|-------------------|-------------------|
| POST | `/api/v1/departments` | - Verificar si todos los campos obligatorios se están ingresando correctamente.
- Solo usuarios con rol ADMIN tienen acceso
- La API debe retornar la información del nuevo departamento.
- Si la creación es exitosa retorna el código HTTP 201.
- Si los datos son inválidos retornar el código HTTP 400.
| GET | `/api/v1/departments` | - Retornar los primeros 10 resultados ordenados por code.
- Obtener la respuesta con paginación para controlar el volumen de los datos.
- Solo el rol ADMIN y RECEPTION pueden obtener todos los usuarios.
- El tamaño por defecto de la página será de 10|
| GET | `/api/v1/departments/{id}` | - Retornar el departamento que coincida con el id y que además se encuentre habilitado.
- Si no encuentra el departamento retornar un 404.
- Solo el rol ADMIN y RECEPTION puede buscar usuarios.|
| UPDATE | `/api/v1/departments/{id}` | - Verificar si todos los campos obligatorios se están ingresando correctamente.
- Solo usuarios con rol ADMIN tienen acceso
- La API debe retornar la información del departamento actualizado.
- Si la edición es exitosa retorna el código HTTP 200.
- Si los datos son inválidos retornar el código HTTP 400.
- Si el departamento no se encuentra retornar el código HTTP 404.|
| DELETE | `/api/v1/departments/{id}` | - Si la eliminación es exitosa retornar un 204.
- Si no encuentra el departamento retornar un 404.
- Solo el rol ADMIN puede eliminar departamentos. |

🚪 Habitaciones

| Método | Endpoint | Reglas de negocio |
|--------|-------------------|-------------------|
| POST | `/api/v1/rooms` | - Verificar si todos los campos obligatorios se están ingresando correctamente.
- Solo usuarios con rol ADMIN tienen acceso
- La API debe retornar la información de la nueva habitación.
- Si la creación es exitosa retorna el código HTTP 201.
- Si los datos son inválidos retornar el código HTTP 400.
- Si no se encuentra el tipo de habitación retornar un 404.
| GET | `/api/v1/rooms` | - Retornar los primeros 10 resultados ordenados por number.
- Obtener la respuesta con paginación para controlar el volumen de los datos.
- Solo el rol ADMIN y RECEPTION pueden obtener todas las habitaciones.
- El tamaño por defecto de la página será de 10.|
| GET | `/api/v1/rooms/{id}` | - Retornar la habitación que coincida con el id y que además se encuentre habilitado.
- Si no encuentra el departamento retornar un 404.
- Solo el rol ADMIN y RECEPTION puede buscar habitaciones.|
| UPDATE | `/api/v1/rooms/{id}` | - Verificar si todos los campos obligatorios se están ingresando correctamente.
- Solo usuarios con rol ADMIN tienen acceso
- La API debe retornar la información de la habitación actualizada.
- Si la edición es exitosa retorna el código HTTP 200.
- Si los datos son inválidos retornar el código HTTP 400.
- Si no se encuentra la habitación o el tipo de habitación retornar un 404.|
| DELETE | `/api/v1/rooms/{id}` | - Si la eliminación es exitosa retornar un 204.
- Si no encuentra la habitación retornar un 404.
- Solo el rol ADMIN puede eliminar habitaciones. |

📅 Reservas

| Método | Endpoint | Reglas de negocio |
|--------|-------------------|-------------------|
| POST | `/api/v1/bookings` | - Verificar si todos los campos obligatorios se están ingresando correctamente.
- Solo usuarios con rol ADMIN o RECEPTION tienen acceso a este endpoint.
- La API debe retornar la información de la nueva reserva.
- Si la creación es exitosa retorna el código HTTP 201.
- Si los datos son inválidos retornar el código HTTP 400.
- Si no se encuentra huésped, recepcionista o el alojamiento retornar un 404.
- Verifica que no exista algún conflicto de tiempos entre la nueva reserva y las existentes.
| GET | `/api/v1/bookings` | - Retornar los primeros 10 resultados ordenados por fecha de creación.
- Obtener la respuesta con paginación para controlar el volumen de los datos.
- Solo el rol ADMIN y RECEPTION pueden obtener todas las reservas.
- El tamaño por defecto de la página será de 10.
- Es posible realizar búsquedas con filtros como: ID del huésped, ID del recepcionista, estado de la reserva, nombre del huésped y fechas|
| GET | `/api/v1/bookings/{id}` | - Retornar la reserva que coincida con el id y que además se encuentre habilitado.
- Si no encuentra la reserva retornar un 404.
- Solo el rol ADMIN y RECEPTION puede buscar habitaciones.|
| UPDATE | `/api/v1/bookings/{id}` | - Verificar si todos los campos obligatorios se están ingresando correctamente.
- Solo usuarios con rol ADMIN o RECEPTION tienen acceso a este endpoint.
- La API debe retornar la información de la reserva actualizada.
- Si la edición es exitosa retorna el código HTTP 200.
- Si los datos son inválidos retornar el código HTTP 400.
- Si no se encuentra huésped, recepcionista o el alojamiento retornar un 404.
- Verificar que no exista algún conflicto de tiempos entre la nueva reserva y las existentes.
- Si no encuentra la reserva retornar el código HTTP 404.|
| DELETE | `/api/v1/bookings/{id}` | - Si la eliminación es exitosa retornar un 204.
- Si no encuentra la reserva retornar un 404.
- Solo el rol ADMIN y RECEPTION puede eliminar reservas. |

🏨 Tipos de habitaciones

| Método | Endpoint | Reglas de negocio |
|--------|-------------------|-------------------|
| POST | `/api/v1/room-types` | - Verificar si todos los campos obligatorios se están ingresando correctamente.
- Solo usuarios con rol ADMIN tienen acceso a este endpoint.
- La API debe retornar la información del nuevo tipo de habitación.
- Si la creación es exitosa retorna el código HTTP 201.
- Si los datos son inválidos retornar el código HTTP 400.
| GET | `/api/v1/room-types` | - Retornar los primeros 10 resultados ordenados por el nombre.
- Obtener la respuesta con paginación para controlar el volumen de los datos.
- Solo el rol ADMIN y RECEPTION pueden obtener todos los tipos de habitaciones.
- El tamaño por defecto de la página será de 10.|
| GET | `/api/v1/room-types/{id}` | - Retornar el tipo de habitación que coincida con el id y que además se encuentre habilitado.
- Si no lo encuentra retornar un 404.
- Solo el rol ADMIN y RECEPTION puede buscar los tipos de habitaciones.|
| UPDATE | `/api/v1/room-types/{id}` | - Verificar si todos los campos obligatorios se están ingresando correctamente.
- Solo usuarios con rol ADMIN tienen acceso a este endpoint.
- La API debe retornar la información actualizada.
- Si la actualización es exitosa retorna el código HTTP 200.
- Si los datos son inválidos retornar el código HTTP 400.
- Si no se encuentra el recurso retornar el código HTTP 404.|
| DELETE | `/api/v1/room-types/{id}` | - Si la eliminación es exitosa retornar un 204.
- Si no encuentra el recurso retornar un 404.
- Solo el rol ADMIN puede eliminar. |

## Requerimientos previos

- **JDK: Java 21 o superior**
- **Gestor de dependencias: Maven 4.0.0**
- **Spring Boot 3.3.5**
- **Base de datos PostgreSQL (cambiar la configuración de application.properties)**

## Configuración

1. Clona el repositorio

```bash
git clone https://github.com/Luiggi-piero/shepard-backend.git
cd shepard-backend
2. Configura las variables de entorno para la conexión a la base de datos desde `application-prod.yml`

```yaml
spring:
datasource:
url: ${DB_URL:jdbc:postgresql://localhost:5432/shepard_db}
username: ${DB_USER}
password: ${DB_PASS}
driver-class-name: org.postgresql.Driver
jpa:

hibernate:
ddl-auto: update
show-sql: true

server:
port: 8080

konecta:
cors:
allowed-origins: "*"
allowed-methods: "GET,POST,PUT,DELETE,OPTIONS"
allowed-headers: "*"

security:
secret: ${JWT_SECRET} # Get from env vars
expiration-ms: ${JWT_EXPIRATION_MS:86400000}

3. Crea un base de datos vacía con el nombre shepard_db

4. Ejecuta el proyecto

5. La aplicación estará disponible en: http://localhost:8080

## Swagger
Swagger está configurado para generar documentación de la API automáticamente. Puedes acceder a la interfaz de Swagger en la siguiente URL cuando el servidor esté en funcionamiento:
```
http://localhost:8080/swagger-ui/index.html
```

## Tecnologías utilizadas

- **Spring Boot**: Desarrollo rápido y robusto de aplicaciones.
- **Spring Security y JWT**: Autenticación segura.
- **PostgreSQL**: Sistema de gestión de bases de datos relacional.

## Estructura del proyecto

Arquitectura basada en paquetes funcionales, se organizan las carpetas de acuerdo con las características o módulos de la aplicación (por ejemplo, auth, category, challenge), es un diseño entre aspectos funcionales y principios de Clean Architecture y este tipo de arquitectura agrupa cada módulo con sus propios componentes como controladores, servicios, repositorios y modelos.

## Modelo Entidad Relación

## Licencia
Este proyecto está licenciado bajo la Licencia MIT. Consulta el archivo LICENSE para más detalles.

> [!IMPORTANT]
> * Con sql crea los roles: USER, ADMIN, GUEST, CLEANING, RECEPTION y SECURITY en la tabla roles
> * Cambia a enabled 1 todos los roles
> * Registra un usuario con los roles necesarios
> * Agrega la configuración de la bd en `application-prod.yml`
> * Para aquellos que no tienen la zona horaria GMT-5 modificar el archivo ...TokenService (para indicar la expiración del token)

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/luiggi-piero/shepard-backend

Awesome Lists containing this project

README