===================================================================
 ALIGANT ERP V5 - ROLES, PERMISOS Y USUARIOS (RBAC propio)
===================================================================
Sistema de control de acceso SIN paquetes externos.
Esquema solicitado:
  - roles
  - permissions
  - role_permission   (rol  <-> permiso)
  - user_branch       (usuario <-> sucursal)
  - users  + columnas: role_id, activo
Relaciones por llaves foráneas. Diseño actual (aerp-*) intacto.
Requiere: Empresas y Sucursales ya existentes + MySQL configurado.

-------------------------------------------------------------------
 1) ARCHIVOS (descomprimir sobre el proyecto, combinar/sobrescribir)
-------------------------------------------------------------------
NUEVOS:
  database/migrations/2025_03_01_000001_create_roles_table.php
  database/migrations/2025_03_01_000002_create_permissions_table.php
  database/migrations/2025_03_01_000003_create_role_permission_table.php
  database/migrations/2025_03_01_000004_create_user_branch_table.php
  database/migrations/2025_03_01_000005_add_role_id_and_activo_to_users_table.php
  database/seeders/RbacSeeder.php
  app/Models/Role.php
  app/Models/Permission.php
  app/Http/Controllers/RoleController.php
  app/Http/Controllers/PermissionController.php
  app/Http/Controllers/UserController.php
  app/Http/Requests/RoleRequest.php
  app/Http/Requests/PermissionRequest.php
  app/Http/Requests/UserRequest.php
  resources/views/roles/{index,create,edit,show,_form}.blade.php
  resources/views/permisos/{index,create,edit,show,_form}.blade.php
  resources/views/usuarios/{index,create,edit,show,_form}.blade.php

REEMPLAZADOS:
  app/Models/User.php                          (agrega role_id, activo, relaciones, permisos)
  app/Providers/AppServiceProvider.php         (Gate por permisos -> habilita @can)
  routes/web.php                               (agrega usuarios, roles, permisos)
  resources/views/layouts/sidebar.blade.php    (menú filtrado por permisos)

  *** Si tu User.php tenía algo extra (traits, casts propios), revísalo:
      este User.php es la versión RBAC completa, sin paquetes.
  *** Si tu web.php tenía rutas adicionales, vuelve a agregarlas; este
      web.php trae welcome, dashboard, profile, empresas, sucursales,
      usuarios, roles y permisos.

-------------------------------------------------------------------
 2) COMANDOS (en orden) en C:\xampp2\htdocs\aligant_erp_v5
-------------------------------------------------------------------
  php artisan migrate
  php artisan db:seed --class=Database\\Seeders\\RbacSeeder
  php artisan optimize:clear

  -> El seeder crea los permisos, el rol "Administrador" con TODOS los
     permisos, un rol "Operador" de ejemplo, y asigna "Administrador"
     a los usuarios que aún no tienen rol (para que NO te quedes sin menú).

  (Opcional, en Windows si el namespace da problemas, alternativa:)
     php artisan db:seed --class=RbacSeeder

-------------------------------------------------------------------
 3) IMPORTANTE - FILTRADO DEL MENÚ POR PERMISOS
-------------------------------------------------------------------
  - El menú lateral ya usa @can('empresas.ver'), @can('roles.ver'), etc.
  - @can funciona porque AppServiceProvider concede el permiso si el ROL
    del usuario tiene esa "clave" (ver Gate::before).
  - También puedes usar en cualquier vista/controlador:
        @can('usuarios.crear') ... @endcan
        auth()->user()->hasPermission('roles.editar')
        auth()->user()->hasAnyPermission(['empresas.ver','sucursales.ver'])
  - Si un usuario no tiene un permiso, NO verá ese ítem del menú.

  NOTA: este paso filtra el MENÚ. Las rutas siguen accesibles por URL
  (no se añadió middleware de permisos para no alterar el comportamiento
  existente). Si más adelante quieres BLOQUEAR rutas por permiso, se puede
  agregar middleware; dímelo y lo preparo.

-------------------------------------------------------------------
 4) USO
-------------------------------------------------------------------
  /roles      CRUD de roles (con asignación de permisos por módulo)
  /permisos   CRUD de permisos (modulo / nombre / clave)
  /usuarios   CRUD de usuarios (nombre, email, contraseña, rol,
              estado activo/inactivo y SELECCIÓN MÚLTIPLE de sucursales)

  Formulario de usuario:
   - Rol: selección única (users.role_id)
   - Sucursales: casillas múltiples agrupadas por empresa (tabla user_branch)

-------------------------------------------------------------------
 5) NOTAS TÉCNICAS
-------------------------------------------------------------------
  - users.role_id es nullable con FK a roles (nullOnDelete): si borras un
    rol, los usuarios quedan sin rol (no se borran).
  - No se puede eliminar el rol "Administrador" ni un rol con usuarios.
  - La migración de users es idempotente: solo agrega role_id/activo si
    no existen (no rompe si ya tenías 'activo').
  - Contraseña: se hashea sola (cast 'hashed' en el modelo User).

===================================================================