# Sistema Modular con Enfoque en Roles

Sistema web modular construido con Laravel 13. Gestiona múltiples dominios de negocio (hoteles, restaurante, finanzas, cursos, etc.) bajo un sistema centralizado de roles y permisos. Cada módulo es independiente y se activa/desactiva desde el panel de administración.

---

## Stack Tecnológico

### Backend

| Tecnología | Versión | Rol |
|---|---|---|
| PHP | ^8.5 | Lenguaje base |
| Laravel | ^13.0 | Framework principal |
| Livewire | ^4.0 | Componentes reactivos server-side |
| Livewire Volt | ^1.10 | Componentes en un solo archivo |
| MaryUI | ^2.8 | Librería de componentes UI sobre DaisyUI |
| Spatie Permission | ^7.0 | Roles y permisos granulares (RBAC) |
| DomPDF | ^3.0 | Generación de PDFs servidor |
| OpenSpout | ^4.0 | Exportación Excel/CSV (XLSX, ODS, CSV) |
| PHP-RRule | ^2.6 | Reglas de recurrencia (RFC 5545) |
| Intervention Image | ^3.11 | Procesamiento de imágenes |
| HTMLPurifier | ^4.19 | Sanitización de HTML |

### Frontend

| Tecnología | Versión | Rol |
|---|---|---|
| Tailwind CSS | ^4.1 | Framework de estilos utility-first |
| DaisyUI | ^5.0 | Componentes base para Tailwind |
| Alpine.js | (vía Livewire) | Reactividad DOM del lado del cliente |
| Vite | ^6.0 | Bundler y dev server |
| Chart.js | ^4.5 | Gráficas y visualizaciones |
| FullCalendar | ^6.1 | Calendarios interactivos |
| SortableJS | ^1.15 | Drag & drop (Kanban, listas) |
| Quill | ^2.0 | Editor de texto enriquecido |
| FontAwesome | ^6.7 | Iconos adicionales |

> Chart.js, FullCalendar, SortableJS y Quill se cargan de forma **lazy** via `import()` dinámico — solo se incluyen en las páginas que los usan.

---

## Módulos Disponibles

| Alias | Nombre | Descripción |
|---|---|---|
| `core` | Core | Núcleo del sistema: autenticación, usuarios, roles, permisos, ajustes globales |
| `sfm` | Gestión Financiera Simple | Finanzas personales: billeteras, transacciones, metas, presupuesto familiar |
| `bk` | Bitácora | Registro de trabajo personal: tareas, archivos editados, notas, exportación CSV |
| `mm` | Ministerio de Medios | Eventos, tareas, banco de medios, construcción de copias, apoyo bíblico |
| `hm` | Gestión de Hoteles | Hotel, habitaciones, reservaciones, check-in/out, pagos, housekeeping, recursos |
| `cm` | Cursos | Catálogo de cursos con lecciones, inscripciones y progreso; catálogo público |
| `rm` | Restaurante | Pedidos, menú, carta QR para autoservicio, cocina con Kanban en tiempo real |

---

## Requisitos

- **PHP** 8.5 o superior (con extensiones: PDO, mbstring, xml, gd, zip)
- **MySQL** 8.0 o superior
- **Composer** 2.x
- **Node.js** 20+ con **pnpm** 11+
- **Git**

---

## Instalación

```bash
# 1. Clonar el repositorio
git clone <repo-url> && cd <proyecto>

# 2. Instalar dependencias PHP
composer install

# 3. Instalar dependencias Node
pnpm install

# 4. Configurar variables de entorno
cp .env.example .env
php artisan key:generate
```

Edita `.env` con tus credenciales de base de datos:

```env
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel_roles
DB_USERNAME=root
DB_PASSWORD=
```

```bash
# 5. Ejecutar migraciones y seeders base (roles, permisos, admin inicial)
php artisan migrate:fresh --seed
```

---

## Levantar el Sistema

### Desarrollo (todo en un comando)

```bash
composer dev
```

Esto ejecuta en paralelo:
- `php artisan serve` — servidor Laravel en `http://localhost:8000`
- `php artisan queue:listen` — procesador de jobs en cola
- `pnpm run dev` — Vite con HMR

### Producción

```bash
composer install --no-dev --optimize-autoloader
pnpm run build
php artisan config:cache
php artisan route:cache
php artisan view:cache
```

---

## Seeders

| Comando | Efecto |
|---|---|
| `php artisan migrate:fresh --seed` | Migra todo desde cero + crea roles, permisos y usuario admin base |
| `php artisan db:seed --class=DemoSeeder` | Carga datos de demostración (usuarios ficticios, transacciones, reservaciones, etc.) |

> El DemoSeeder **no es idempotente** — si se corre dos veces en la misma BD duplicará registros. Úsalo solo en una BD limpia.

---

## Estructura Modular

Cada módulo sigue esta estructura dentro de `Modules/<Nombre>/`:

```
Modules/<Nombre>/
├── module.json               # Metadatos: alias, prioridad, permisos, páginas públicas
├── pages.json                # Definición de páginas para el sistema de navegación
├── Routes/
│   └── web.php               # Rutas del módulo
├── Http/
│   ├── Controllers/          # Controladores tradicionales (PDF, exports, etc.)
│   └── Livewire/             # Componentes Livewire del módulo
├── Models/                   # Modelos Eloquent
├── Database/
│   ├── Migrations/           # Migraciones con prefijo del alias (ej. hm_, rm_)
│   └── Seeders/              # Seeders del módulo
└── Resources/
    └── views/                # Vistas Blade del módulo
```

Los módulos se registran automáticamente en `app/Providers/AppServiceProvider.php` y sus rutas se cargan vía `ModuleServiceProvider`.

---

## Comandos Útiles

```bash
# Migraciones
php artisan migrate                        # Solo nuevas migraciones
php artisan migrate:fresh --seed           # Reset completo + seeders

# Desarrollo
php artisan tinker                         # REPL interactivo
php artisan pail                           # Visor de logs en tiempo real

# Calidad de código
./vendor/bin/pint                          # Formatear código (Laravel Pint)
php artisan test                           # Correr suite de tests (Pest)

# Cache
php artisan cache:clear
php artisan config:clear
php artisan view:clear

# Demo
# Abrir /Demo en el navegador para ver la guía de componentes del proyecto
```

---

## Acceso Inicial

Tras ejecutar `migrate:fresh --seed`, el sistema crea un usuario administrador. Las credenciales predeterminadas se configuran en `DatabaseSeeder.php`. El panel de administración de roles está en `/PermissionManager`.

> La página raíz `/` puede configurarse desde `/PublicLanding` para apuntar al módulo o vista deseada.
