# Pages for Dummies

Guía práctica para agregar, modificar o eliminar páginas del sistema sin romper nada.

---

## Cómo funciona el sistema

Una página vive en **3 lugares** que deben estar sincronizados:

| Lugar | Qué controla |
|---|---|
| `Modules/*/pages.json` | Qué aparece en el menú y qué permiso lo protege |
| `Modules/*/Routes/web.php` | La ruta nombrada de Laravel |
| Base de datos (tabla `permissions`) | Los registros de permisos reales |

### Campos de pages.json

```json
{
    "icon": "o-banknotes",      // Ícono del ítem en el menú lateral
    "title": "Mi Página",       // Texto visible en el menú
    "menu": "Admin",            // Nombre del grupo/sección en el sidebar
    "permission": "mi_pagina",  // Nombre base del recurso — SIN .index
    "route": "mi_pagina.index", // Nombre de ruta Laravel (->name(...) en web.php)
    "submenu": "none"           // Siempre "none" por ahora
}
```

### Por qué una página puede desaparecer del menú

`buildNavigationMenu()` en `resources/views/layouts/navigation/both.blade.php`
silenciosamente filtra páginas si:

1. `Route::has($page['route'])` es `false` → la ruta no existe o tiene otro nombre
2. El usuario no tiene `{permission}.index` en DB → el permiso no fue creado o asignado

---

## Casos de cambio y qué tocar

### Cambiar solo título o ícono

Solo edita `pages.json`. Sin consecuencias en rutas ni DB.

```
php artisan cache:clear
```

---

### Cambiar la ruta (`route`)

Afecta: `pages.json` + `web.php` + cualquier referencia al nombre viejo.

1. Editar `pages.json` → campo `route`
2. En `web.php` cambiar `->name('nombre_viejo')` al nuevo nombre
3. Buscar referencias al nombre viejo:
   ```bash
   grep -r "nombre_viejo" Modules/
   ```
4. `php artisan cache:clear`

No toca la DB ni permisos.

---

### Cambiar el permiso (`permission`) ← el más crítico

Los permisos en DB **no se renombran solos**. Si solo cambias `pages.json`, el menú
desaparece porque el usuario ya no tiene el permiso nuevo asignado.

1. Editar `pages.json` → campo `permission`
2. En el controller, actualizar `checkPermission('permiso_viejo', ...)` → `checkPermission('permiso_nuevo', ...)`
3. **Wizard → Tab "Page Permissions" → Sync** — crea los nuevos permisos en DB:
   `permiso_nuevo.index`, `.create`, `.update`, `.delete`, `.export`
4. **Users → Roles (o Permissions)** — asignar el nuevo permiso a los roles correspondientes
5. Los permisos viejos quedan huérfanos en DB — no rompen nada, pero si quieres limpiarlos:
   ```php
   Permission::where('name', 'like', 'permiso_viejo.%')->delete();
   ```

---

### Agregar una página nueva

1. Agregar entrada en `pages.json` con los 6 campos: `icon`, `title`, `menu`, `permission`, `route`, `submenu`
2. Agregar ruta en `web.php`:
   ```php
   Route::get('/MiPagina', [MiController::class, 'index'])->name('mi_pagina.index');
   ```
3. Crear el controller y la vista
4. En el método `index` del controller:
   ```php
   $this->checkPermission('mi_pagina', 'index');
   ```
5. **Wizard → Sync** — crea los permisos en DB
6. **Roles → asignar** el permiso al rol que debe ver la página

---

### Eliminar una página

1. Eliminar la entrada de `pages.json`
2. Eliminar la ruta de `web.php` (y el controller/view si ya no sirven)
3. Limpiar permisos huérfanos en DB si se desea:
   ```php
   Permission::where('name', 'like', 'mi_pagina.%')->delete();
   ```

---

## Ejemplo real: renombrar el permiso de la página "Wizard"

Situación: `Core/pages.json` tiene `"permission": "wizard"` y se quiere cambiar a `"permission_manager"`.

**Archivos a tocar:**

1. `Modules/Core/pages.json`
   ```json
   "permission": "permission_manager"
   ```

2. `Modules/Core/Http/Controllers/Wizard/WizardController.php` — todos los `checkPermission`:
   ```php
   // antes
   $this->checkPermission('wizard', 'index');
   // después
   $this->checkPermission('permission_manager', 'index');
   ```

3. **Wizard → Sync** (crea `permission_manager.index/.create/.update/.delete/.export` en DB)

4. **Roles → asignar** `permission_manager.index` al rol Admin u otros que necesiten acceso

---

## Caché del menú

El menú se cachea por usuario con un número de versión (`PermissionVersion`).
Se invalida automáticamente cuando se usa el Wizard (Sync). Para forzar la invalidación manual:

```bash
php artisan cache:clear
```
