Skip to content

README.md

Latest commit

 

History

History
223 lines (180 loc) · 9.1 KB

README.md

File metadata and controls

223 lines (180 loc) · 9.1 KB

Reservas del local

Sistema de reservas del local para gestionar espacios y horarios, con calendario interactivo, validación de disponibilidad, campos configurables, notificaciones por email y gestión desde el panel de administración.

Características

  • Recursos reservables: Gestión de espacios con horarios de operación y modos de programación
  • Calendario interactivo: Vista de calendario con selección de franjas horarias disponibles
  • Modos de programación: Franjas horarias (time_slots) o bloques predefinidos (time_blocks)
  • Modo de aprobación: Confirmación automática o aprobación manual por administradores
  • Campos configurables: Campos predefinidos y personalizados con visibilidad configurable
  • Validación de elegibilidad: Límite de reservas activas, antelación mínima y máximo de días futuros
  • Mis reservas: Los usuarios pueden ver y gestionar sus propias reservas
  • Integración con módulos: Asociación con mesas de rol y campañas (si están habilitados)
  • Notificaciones por email: Creación, confirmación, cancelación, rechazo y recordatorio
  • Panel de administración: Gestión completa de recursos, reservas y configuración desde Filament

Requisitos

  • PHP >= 8.2
  • GuildForge core

Instalación

  1. Copiar el módulo a src/modules/venue-bookings/

  2. Descubrir y habilitar el módulo:

php artisan module:discover
php artisan module:enable venue-bookings
  1. Ejecutar las migraciones:
php artisan migrate

Configuración

Configuración global

Valores almacenados en config/settings.php:

Clave Valor por defecto Descripción
approval_mode require_approval Modo de aprobación: auto_confirm o require_approval
max_active_bookings_per_user 19 Máximo de reservas activas por usuario
min_advance_minutes 60 Antelación mínima en minutos para reservar
max_future_days 15 Máximo de días en el futuro para reservar
time_block_presets Mañana, Tarde, Noche Bloques horarios predefinidos
predefined_fields actividad, participantes, teléfono, notas Campos predefinidos con visibilidad configurable
custom_fields [{ key: 'num-socios', ... }] Campos personalizados
notifications todas habilitadas, recordatorio 24h Configuración de notificaciones
associations mesas y campañas habilitadas Integración con otros módulos

Bloques horarios predefinidos

Bloque Apertura Cierre
Mañana 10:00 14:00
Tarde 14:00 20:00
Noche 20:00 10:00

Modos de programación

Modo Valor Descripción
Franjas horarias time_slots El usuario elige hora de inicio y fin dentro del horario de operación
Bloques predefinidos time_blocks El usuario selecciona un bloque horario predefinido (Mañana, Tarde, Noche)

Estados de reserva

Estado Valor Descripción
Pendiente pending Reserva creada, pendiente de aprobación
Confirmada confirmed Reserva aprobada
Completada completed Reserva finalizada
Cancelada cancelled Cancelada por el usuario o administrador
No presentado no_show El usuario no se presentó
Rechazada rejected Rechazada por administrador

Transiciones válidas

  • Pendiente → Confirmada, Cancelada, Rechazada
  • Confirmada → Completada, Cancelada, No presentado

Los estados Completada, Cancelada, No presentado y Rechazada son finales.

Arquitectura

src/modules/venue-bookings/
├── config/
│   ├── module.php             # Activación del módulo
│   └── settings.php           # Configuración del módulo
├── database/
│   ├── migrations/            # Migraciones (resources, schedules, bookings)
│   └── seeders/               # Seeders de desarrollo
├── lang/
│   └── es/                    # Traducciones en español
│       └── messages.php
├── resources/js/
│   ├── components/            # Componentes Vue
│   │   └── profile/           # Componentes de perfil
│   ├── locales/               # Traducciones i18n (frontend)
│   ├── pages/
│   │   └── VenueBookings/     # Páginas Inertia
│   └── types/                 # Tipos TypeScript
├── routes/
│   └── web.php                # Rutas web
├── src/
│   ├── Application/
│   │   ├── DTOs/              # Data Transfer Objects
│   │   │   └── Response/      # DTOs de respuesta
│   │   └── Services/          # Interfaces de servicios
│   ├── Console/
│   │   └── Commands/          # Comandos Artisan (recordatorios)
│   ├── Domain/
│   │   ├── Entities/          # Entidades (BookableResource, Booking, OperatingSchedule)
│   │   ├── Enums/             # Enumeraciones (BookingStatus, SchedulingMode, etc.)
│   │   ├── Events/            # Eventos de dominio
│   │   ├── Exceptions/        # Excepciones de dominio
│   │   ├── Repositories/      # Interfaces de repositorios
│   │   └── ValueObjects/      # Objetos de valor
│   ├── Filament/
│   │   ├── Pages/             # Páginas de configuración
│   │   ├── Resources/         # Recursos CRUD (BookableResource, Booking)
│   │   └── Widgets/           # Widgets del dashboard
│   ├── Http/
│   │   ├── Controllers/       # Controladores
│   │   └── Requests/          # Form Requests
│   ├── Infrastructure/
│   │   ├── Listeners/         # Listeners de eventos (notificaciones)
│   │   ├── Persistence/       # Repositorios Eloquent
│   │   └── Services/          # Implementaciones de servicios
│   ├── Notifications/         # Notificaciones por email
│   └── Policies/              # Políticas de autorización
├── tests/
│   ├── Feature/               # Tests funcionales (Filament, HTTP)
│   ├── Integration/           # Tests de integración (repositorios, servicios)
│   └── Unit/                  # Tests unitarios (entidades, enums, VOs)
├── module.json                # Manifiesto del módulo
└── phpunit.xml                # Configuración de tests

Rutas web

Método Ruta Descripción
GET /reservas Calendario de reservas
GET /reservas/api/slots API: franjas horarias disponibles
GET /reservas/api/events API: eventos del calendario
GET /reservas/api/bookings/{booking} API: detalle de una reserva
GET /reservas/api/eligibility API: elegibilidad del usuario (auth)
POST /reservas Crear una reserva (auth)
GET /reservas/mis-reservas Mis reservas (auth)
DELETE /reservas/{booking} Cancelar una reserva (auth)

Componentes Vue

Componentes

Componente Descripción
BookingCalendar Calendario interactivo con vista de reservas
BookingCard Tarjeta resumen de una reserva
BookingDetailModal Modal con el detalle completo de una reserva
BookingForm Formulario de creación de reserva
BookingSlotPicker Selector de franja horaria disponible
BookingStatusBadge Insignia de estado de la reserva con colores
BookingTooltip Tooltip con información de la reserva
ResourceSelector Selector de recurso reservable
ProfileBookingsSection Sección de reservas en el perfil del usuario

Páginas

Página Ruta Descripción
VenueBookings/Index /reservas Calendario de reservas con formulario de creación
VenueBookings/MyBookings /reservas/mis-reservas Listado de reservas del usuario

Eventos de dominio

Evento Descripción
BookingCreated Se creó una nueva reserva
BookingConfirmed Una reserva fue confirmada
BookingCancelled Una reserva fue cancelada
BookingCompleted Una reserva fue completada
BookingRejected Una reserva fue rechazada
BookingNoShow El usuario no se presentó a la reserva
BookingReminder Se envió un recordatorio de reserva

Permisos

Permiso Descripción
bookings.view_any Ver listado de reservas
bookings.view Ver detalle de reserva
bookings.create Crear reservas
bookings.cancel_own Cancelar reservas propias
bookings.cancel_any Cancelar cualquier reserva
bookings.manage Gestionar reservas (confirmar, rechazar, completar)
bookings.settings Gestionar configuración del módulo

Tests

Ejecutar los tests del módulo:

# Desde el directorio del módulo
cd src/modules/venue-bookings
../../../vendor/bin/phpunit

# O desde el directorio raíz
php artisan test --filter=VenueBooking

Licencia

Este módulo es parte de GuildForge y está bajo la misma licencia del proyecto principal.