feat(authorization): establish many-to-many relationship between roles and menus, add migration and seeder updates

app/Domains/Auth/Models/User.php

@@ -2,27 +2,49 @@
 
 namespace App\Domains\Auth\Models;
 
+use App\Domains\Authorization\Models\Role;
+use App\Domains\Tenant\Models\Tenant;
 use Database\Factories\UserFactory;
 use Illuminate\Database\Eloquent\Attributes\Fillable;
 use Illuminate\Database\Eloquent\Attributes\Hidden;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
 use Illuminate\Database\Eloquent\Relations\HasMany;
 use Illuminate\Foundation\Auth\User as Authenticatable;
 use Illuminate\Notifications\Notifiable;
 use Laravel\Sanctum\HasApiTokens;
+use LogicException;
 
-#[Fillable(['nombre_apellido', 'email', 'password', 'dni', 'telefono', 'google_id'])]
+#[Fillable(['nombre_apellido', 'email', 'password', 'dni', 'telefono', 'google_id', 'rol_codigo', 'tenant_codigo'])]
 #[Hidden(['password', 'remember_token'])]
 class User extends Authenticatable
 {
     /** @use HasFactory<UserFactory> */
     use HasApiTokens, HasFactory, Notifiable;
 
+    protected $attributes = [
+        'rol_codigo' => 'user',
+    ];
+
     protected static function newFactory(): UserFactory
     {
         return UserFactory::new();
     }
 
+    protected static function booted(): void
+    {
+        static::saving(function (User $user): void {
+            $hasTenant = $user->tenant_codigo !== null;
+            $isTenantAdmin = $user->rol_codigo === 'tenant_admin';
+
+            if ($hasTenant !== $isTenantAdmin) {
+                throw new LogicException(
+                    'tenant_codigo debe estar informado únicamente para usuarios con rol tenant_admin.'
+                );
+            }
+        });
+    }
+
     /** @return HasMany<ResetPasswordAttempt, $this> */
     public function resetPasswordAttempts(): HasMany
     {
@@ -35,6 +57,22 @@ class User extends Authenticatable
         return $this->hasMany(LoginAttempt::class);
     }
 
+    /**
+     * @return BelongsTo<Role, $this>
+     */
+    public function role(): BelongsTo
+    {
+        return $this->belongsTo(Role::class, 'rol_codigo', 'codigo');
+    }
+
+    /**
+     * @return BelongsTo<Tenant, $this>
+     */
+    public function tenant(): BelongsTo
+    {
+        return $this->belongsTo(Tenant::class, 'tenant_codigo', 'codigo');
+    }
+
     /**
      * @return array<string, string>
      */

app/Domains/Auth/Resources/UserResource.php

@@ -2,11 +2,12 @@
 
 namespace App\Domains\Auth\Resources;
 
+use App\Domains\Auth\Models\User;
 use Illuminate\Http\Request;
 use Illuminate\Http\Resources\Json\JsonResource;
 
 /**
- * @mixin \App\Domains\Auth\Models\User
+ * @mixin User
  */
 class UserResource extends JsonResource
 {
@@ -21,6 +22,8 @@ class UserResource extends JsonResource
             'email' => $this->email,
             'dni' => $this->dni,
             'telefono' => $this->telefono,
+            'rol_codigo' => $this->rol_codigo,
+            'tenant_codigo' => $this->tenant_codigo,
         ];
     }
 }

app/Domains/Authorization/Models/Permission.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace App\Domains\Authorization\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsToMany;
+
+class Permission extends Model
+{
+    protected $table = 'permisos';
+
+    protected $fillable = [
+        'codigo',
+        'nombre',
+        'descripcion',
+    ];
+
+    /**
+     * @return BelongsToMany<Role, $this>
+     */
+    public function roles(): BelongsToMany
+    {
+        return $this->belongsToMany(
+            Role::class,
+            'roles_permisos',
+            'codigo_permiso',
+            'rol_codigo',
+            'codigo',
+            'codigo'
+        )->withTimestamps();
+    }
+}

app/Domains/Authorization/Models/Role.php

@@ -0,0 +1,59 @@
+<?php
+
+namespace App\Domains\Authorization\Models;
+
+use App\Domains\Auth\Models\User;
+use App\Domains\Menu\Models\Menu;
+use App\Domains\Menu\Models\MenuRole;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsToMany;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+
+class Role extends Model
+{
+    protected $table = 'roles';
+
+    protected $fillable = [
+        'codigo',
+        'nombre',
+        'descripcion',
+    ];
+
+    /**
+     * @return BelongsToMany<Permission, $this>
+     */
+    public function permissions(): BelongsToMany
+    {
+        return $this->belongsToMany(
+            Permission::class,
+            'roles_permisos',
+            'rol_codigo',
+            'codigo_permiso',
+            'codigo',
+            'codigo'
+        )->withTimestamps();
+    }
+
+    /**
+     * @return HasMany<User, $this>
+     */
+    public function users(): HasMany
+    {
+        return $this->hasMany(User::class, 'rol_codigo', 'codigo');
+    }
+
+    /**
+     * @return BelongsToMany<Menu, $this>
+     */
+    public function menus(): BelongsToMany
+    {
+        return $this->belongsToMany(
+            Menu::class,
+            'menues_roles',
+            'rol_codigo',
+            'menu_codigo',
+            'codigo',
+            'code'
+        )->using(MenuRole::class);
+    }
+}

app/Domains/Authorization/Models/RolePermission.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace App\Domains\Authorization\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+class RolePermission extends Model
+{
+    protected $table = 'roles_permisos';
+
+    protected $fillable = [
+        'codigo_permiso',
+        'rol_codigo',
+    ];
+
+    /**
+     * @return BelongsTo<Permission, $this>
+     */
+    public function permission(): BelongsTo
+    {
+        return $this->belongsTo(Permission::class, 'codigo_permiso', 'codigo');
+    }
+
+    /**
+     * @return BelongsTo<Role, $this>
+     */
+    public function role(): BelongsTo
+    {
+        return $this->belongsTo(Role::class, 'rol_codigo', 'codigo');
+    }
+}

app/Domains/Menu/Models/Menu.php

@@ -2,6 +2,7 @@
 
 namespace App\Domains\Menu\Models;
 
+use App\Domains\Authorization\Models\Role;
 use App\Domains\Tenant\Models\Tenant;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Model;
@@ -78,4 +79,16 @@ class Menu extends Model
             ->withPivot('static_content')
             ->withTimestamps();
     }
+
+    public function roles(): BelongsToMany
+    {
+        return $this->belongsToMany(
+            Role::class,
+            'menues_roles',
+            'menu_codigo',
+            'rol_codigo',
+            'code',
+            'codigo'
+        )->using(MenuRole::class);
+    }
 }

app/Domains/Menu/Models/MenuRole.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace App\Domains\Menu\Models;
+
+use App\Domains\Authorization\Models\Role;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\Pivot;
+
+class MenuRole extends Pivot
+{
+    protected $table = 'menues_roles';
+
+    public $incrementing = true;
+
+    public $timestamps = false;
+
+    protected $fillable = [
+        'rol_codigo',
+        'menu_codigo',
+    ];
+
+    public function role(): BelongsTo
+    {
+        return $this->belongsTo(Role::class, 'rol_codigo', 'codigo');
+    }
+
+    public function menu(): BelongsTo
+    {
+        return $this->belongsTo(Menu::class, 'menu_codigo', 'code');
+    }
+}

database/migrations/2026_07_28_000000_create_roles_and_permissions_tables.php

@@ -0,0 +1,53 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('permisos', function (Blueprint $table): void {
+            $table->id();
+            $table->string('codigo')->unique();
+            $table->string('nombre');
+            $table->text('descripcion')->nullable();
+            $table->timestamps();
+        });
+
+        Schema::create('roles', function (Blueprint $table): void {
+            $table->id();
+            $table->string('codigo')->unique();
+            $table->string('nombre');
+            $table->text('descripcion')->nullable();
+            $table->timestamps();
+        });
+
+        Schema::create('roles_permisos', function (Blueprint $table): void {
+            $table->id();
+            $table->string('codigo_permiso');
+            $table->string('rol_codigo');
+            $table->timestamps();
+
+            $table->foreign('codigo_permiso')
+                ->references('codigo')
+                ->on('permisos')
+                ->cascadeOnUpdate()
+                ->cascadeOnDelete();
+            $table->foreign('rol_codigo')
+                ->references('codigo')
+                ->on('roles')
+                ->cascadeOnUpdate()
+                ->cascadeOnDelete();
+            $table->unique(['rol_codigo', 'codigo_permiso']);
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('roles_permisos');
+        Schema::dropIfExists('roles');
+        Schema::dropIfExists('permisos');
+    }
+};

database/migrations/2026_07_28_000100_add_role_and_tenant_codes_to_users_table.php

@@ -0,0 +1,63 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        $now = now();
+
+        DB::table('roles')->insertOrIgnore([
+            [
+                'codigo' => 'admin',
+                'nombre' => 'Administrador general',
+                'descripcion' => 'Administra la plataforma y todos sus tenants.',
+                'created_at' => $now,
+                'updated_at' => $now,
+            ],
+            [
+                'codigo' => 'tenant_admin',
+                'nombre' => 'Administrador del tenant',
+                'descripcion' => 'Administra la operación de su propio tenant.',
+                'created_at' => $now,
+                'updated_at' => $now,
+            ],
+            [
+                'codigo' => 'user',
+                'nombre' => 'Usuario',
+                'descripcion' => 'Cliente final limitado a sus propios datos y operaciones.',
+                'created_at' => $now,
+                'updated_at' => $now,
+            ],
+        ]);
+
+        Schema::table('users', function (Blueprint $table): void {
+            $table->string('rol_codigo')->default('user')->after('id');
+            $table->string('tenant_codigo')->nullable()->after('rol_codigo');
+
+            $table->foreign('rol_codigo')
+                ->references('codigo')
+                ->on('roles')
+                ->cascadeOnUpdate()
+                ->restrictOnDelete();
+            $table->foreign('tenant_codigo')
+                ->references('codigo')
+                ->on('tenants')
+                ->cascadeOnUpdate()
+                ->restrictOnDelete();
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('users', function (Blueprint $table): void {
+            $table->dropForeign(['tenant_codigo']);
+            $table->dropForeign(['rol_codigo']);
+            $table->dropColumn(['tenant_codigo', 'rol_codigo']);
+        });
+    }
+};

database/migrations/2026_07_30_000000_create_menues_roles_table.php

@@ -0,0 +1,35 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('menues_roles', function (Blueprint $table): void {
+            $table->id();
+            $table->string('rol_codigo');
+            $table->string('menu_codigo');
+
+            $table->foreign('rol_codigo')
+                ->references('codigo')
+                ->on('roles')
+                ->cascadeOnUpdate()
+                ->cascadeOnDelete();
+            $table->foreign('menu_codigo')
+                ->references('code')
+                ->on('menues')
+                ->cascadeOnUpdate()
+                ->cascadeOnDelete();
+
+            $table->unique(['rol_codigo', 'menu_codigo']);
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('menues_roles');
+    }
+};

database/seeders/AuthorizationSeeder.php

@@ -0,0 +1,178 @@
+<?php
+
+namespace Database\Seeders;
+
+use App\Domains\Authorization\Models\Permission;
+use App\Domains\Authorization\Models\Role;
+use Illuminate\Database\Seeder;
+
+class AuthorizationSeeder extends Seeder
+{
+    /**
+     * @var array<string, array{nombre: string, descripcion: string}>
+     */
+    private const PERMISSIONS = [
+        'tenant.ver' => [
+            'nombre' => 'Ver configuración del tenant',
+            'descripcion' => 'Permite consultar la configuración general de un tenant.',
+        ],
+        'tenant.editar' => [
+            'nombre' => 'Editar configuración del tenant',
+            'descripcion' => 'Permite modificar los datos generales, dominio, colores y recursos visuales del tenant.',
+        ],
+        'usuarios.ver' => [
+            'nombre' => 'Ver usuarios',
+            'descripcion' => 'Permite consultar los usuarios asociados al tenant.',
+        ],
+        'usuarios.gestionar' => [
+            'nombre' => 'Gestionar usuarios',
+            'descripcion' => 'Permite invitar, editar, desactivar y asignar roles permitidos a los usuarios del tenant.',
+        ],
+        'roles.ver' => [
+            'nombre' => 'Ver roles',
+            'descripcion' => 'Permite consultar los roles y sus permisos.',
+        ],
+        'roles.gestionar' => [
+            'nombre' => 'Gestionar roles',
+            'descripcion' => 'Permite crear, modificar y asignar permisos a roles.',
+        ],
+        'catalogo.ver' => [
+            'nombre' => 'Ver catálogo',
+            'descripcion' => 'Permite consultar administrativamente productos, variantes, categorías, marcas y bundles.',
+        ],
+        'catalogo.gestionar' => [
+            'nombre' => 'Gestionar catálogo',
+            'descripcion' => 'Permite crear, modificar, archivar y eliminar productos, variantes, categorías, marcas y bundles.',
+        ],
+        'inventario.ver' => [
+            'nombre' => 'Ver inventario',
+            'descripcion' => 'Permite consultar el stock y la información de inventario.',
+        ],
+        'inventario.ajustar' => [
+            'nombre' => 'Ajustar inventario',
+            'descripcion' => 'Permite modificar el stock disponible.',
+        ],
+        'pedidos.ver' => [
+            'nombre' => 'Ver pedidos',
+            'descripcion' => 'Permite consultar los pedidos del tenant.',
+        ],
+        'pedidos.gestionar' => [
+            'nombre' => 'Gestionar pedidos',
+            'descripcion' => 'Permite modificar estados y datos operativos de los pedidos.',
+        ],
+        'pedidos.cancelar' => [
+            'nombre' => 'Cancelar pedidos',
+            'descripcion' => 'Permite cancelar pedidos y liberar sus reservas de inventario.',
+        ],
+        'pagos.ver' => [
+            'nombre' => 'Ver pagos',
+            'descripcion' => 'Permite consultar el estado y la información de los pagos.',
+        ],
+        'pagos.gestionar' => [
+            'nombre' => 'Gestionar pagos',
+            'descripcion' => 'Permite confirmar, rechazar o devolver pagos.',
+        ],
+        'tickets.ver' => [
+            'nombre' => 'Ver tickets',
+            'descripcion' => 'Permite consultar los tickets emitidos.',
+        ],
+        'tickets.gestionar' => [
+            'nombre' => 'Gestionar tickets',
+            'descripcion' => 'Permite emitir, invalidar o regenerar tickets.',
+        ],
+        'contenido.gestionar' => [
+            'nombre' => 'Gestionar contenido',
+            'descripcion' => 'Permite administrar menús, carruseles, destacados y redes sociales.',
+        ],
+        'integraciones.ver' => [
+            'nombre' => 'Ver integraciones',
+            'descripcion' => 'Permite consultar la configuración y el estado de las integraciones.',
+        ],
+        'integraciones.gestionar' => [
+            'nombre' => 'Gestionar integraciones',
+            'descripcion' => 'Permite configurar credenciales y proveedores de integraciones.',
+        ],
+        'reportes.ver' => [
+            'nombre' => 'Ver reportes',
+            'descripcion' => 'Permite consultar reportes de ventas y métricas.',
+        ],
+        'reportes.exportar' => [
+            'nombre' => 'Exportar reportes',
+            'descripcion' => 'Permite descargar reportes e información comercial.',
+        ],
+    ];
+
+    /**
+     * @var array<string, array{nombre: string, descripcion: string, permisos: list<string>}>
+     */
+    private const ROLES = [
+        'admin' => [
+            'nombre' => 'Administrador general',
+            'descripcion' => 'Administra la plataforma y todos sus tenants.',
+            'permisos' => [],
+        ],
+        'adminapp' => [
+            'nombre' => 'Administrador de la aplicación',
+            'descripcion' => 'Accede a los menús administrativos de la aplicación.',
+            'permisos' => [],
+        ],
+        'tenant_admin' => [
+            'nombre' => 'Administrador del tenant',
+            'descripcion' => 'Administra la operación de su propio tenant.',
+            'permisos' => [
+                'tenant.ver',
+                'tenant.editar',
+                'usuarios.ver',
+                'usuarios.gestionar',
+                'roles.ver',
+                'catalogo.ver',
+                'catalogo.gestionar',
+                'inventario.ver',
+                'inventario.ajustar',
+                'pedidos.ver',
+                'pedidos.gestionar',
+                'pedidos.cancelar',
+                'pagos.ver',
+                'pagos.gestionar',
+                'tickets.ver',
+                'tickets.gestionar',
+                'contenido.gestionar',
+                'integraciones.ver',
+                'integraciones.gestionar',
+                'reportes.ver',
+                'reportes.exportar',
+            ],
+        ],
+        'user' => [
+            'nombre' => 'Usuario',
+            'descripcion' => 'Cliente final limitado a sus propios datos y operaciones.',
+            'permisos' => [],
+        ],
+    ];
+
+    public function run(): void
+    {
+        foreach (self::PERMISSIONS as $code => $attributes) {
+            Permission::query()->updateOrCreate(
+                ['codigo' => $code],
+                $attributes
+            );
+        }
+
+        foreach (self::ROLES as $code => $attributes) {
+            $role = Role::query()->updateOrCreate(
+                ['codigo' => $code],
+                [
+                    'nombre' => $attributes['nombre'],
+                    'descripcion' => $attributes['descripcion'],
+                ]
+            );
+
+            $permissionCodes = $code === 'admin'
+                ? array_keys(self::PERMISSIONS)
+                : $attributes['permisos'];
+
+            $role->permissions()->sync($permissionCodes);
+        }
+    }
+}

database/seeders/DatabaseSeeder.php

@@ -24,6 +24,7 @@ class DatabaseSeeder extends Seeder
 
         $this->call([
             WebsiteTypeSeeder::class,
+            AuthorizationSeeder::class,
             SocialMediaSeeder::class,
             TenantSeeder::class,
             AttributeSeeder::class,

database/seeders/MenuSeeder.php

@@ -2,6 +2,7 @@
 
 namespace Database\Seeders;
 
+use App\Domains\Authorization\Models\Role;
 use App\Domains\Menu\Models\Menu;
 use App\Domains\Tenant\Models\Tenant;
 use Illuminate\Database\Seeder;
@@ -133,6 +134,19 @@ class MenuSeeder extends Seeder
             ->whereIn('code', ['profile', 'purchases', 'tickets'])
             ->delete();
 
+        $allRoleMenuCodes = Menu::query()->pluck('code');
+        $userMenuCodes = Menu::query()
+            ->where('code', 'not like', 'admin.%')
+            ->pluck('code');
+
+        Role::query()
+            ->whereIn('codigo', ['admin', 'adminapp'])
+            ->each(fn (Role $role) => $role->menus()->sync($allRoleMenuCodes));
+
+        Role::query()
+            ->where('codigo', 'user')
+            ->each(fn (Role $role) => $role->menus()->sync($userMenuCodes));
+
         $tenants = Tenant::all();
 
         $allMenus = Menu::pluck('code')->toArray();

docs/authorization.md

@@ -0,0 +1,91 @@
+# Roles y permisos
+
+El sistema utiliza control de acceso basado en roles. Los códigos son identificadores
+estables para uso interno; los nombres y las descripciones pueden modificarse sin
+afectar las reglas de autorización.
+
+Los permisos administrativos deben evaluarse siempre dentro del tenant correspondiente.
+El rol `admin` es la única excepción porque su alcance es toda la plataforma.
+
+Cada registro de `users` contiene:
+
+- `rol_codigo`: código obligatorio del rol. Su valor predeterminado es `user`.
+- `tenant_codigo`: código nullable del tenant. Solamente se utiliza para usuarios con
+  rol `tenant_admin`; para `admin` y `user` debe permanecer en `null`.
+
+## Roles
+
+| Código | Nombre | Alcance |
+| --- | --- | --- |
+| `admin` | Administrador general | Administra la plataforma, todos los tenants, roles y permisos. Tiene todos los permisos. |
+| `tenant_admin` | Administrador del tenant | Administra usuarios y la operación de su tenant. No puede gestionar la definición de roles. |
+| `user` | Usuario | Cliente final. No tiene permisos administrativos y solamente puede operar sobre sus propios datos, carrito, pedidos y tickets. |
+
+## Permisos
+
+| Código | Nombre | Descripción |
+| --- | --- | --- |
+| `tenant.ver` | Ver configuración del tenant | Consultar la configuración general de un tenant. |
+| `tenant.editar` | Editar configuración del tenant | Modificar datos generales, dominio, colores y recursos visuales. |
+| `usuarios.ver` | Ver usuarios | Consultar los usuarios asociados al tenant. |
+| `usuarios.gestionar` | Gestionar usuarios | Invitar, editar, desactivar y asignar roles permitidos a usuarios del tenant. |
+| `roles.ver` | Ver roles | Consultar los roles y sus permisos. |
+| `roles.gestionar` | Gestionar roles | Crear, modificar y asignar permisos a roles. |
+| `catalogo.ver` | Ver catálogo | Consultar productos, variantes, categorías, marcas y bundles administrativamente. |
+| `catalogo.gestionar` | Gestionar catálogo | Crear, modificar, archivar y eliminar productos, variantes, categorías, marcas y bundles. |
+| `inventario.ver` | Ver inventario | Consultar stock e información de inventario. |
+| `inventario.ajustar` | Ajustar inventario | Modificar el stock disponible. |
+| `pedidos.ver` | Ver pedidos | Consultar los pedidos del tenant. |
+| `pedidos.gestionar` | Gestionar pedidos | Modificar estados y datos operativos de pedidos. |
+| `pedidos.cancelar` | Cancelar pedidos | Cancelar pedidos y liberar sus reservas de inventario. |
+| `pagos.ver` | Ver pagos | Consultar el estado y la información de pagos. |
+| `pagos.gestionar` | Gestionar pagos | Confirmar, rechazar o devolver pagos. |
+| `tickets.ver` | Ver tickets | Consultar tickets emitidos. |
+| `tickets.gestionar` | Gestionar tickets | Emitir, invalidar o regenerar tickets. |
+| `contenido.gestionar` | Gestionar contenido | Administrar menús, carruseles, destacados y redes sociales. |
+| `integraciones.ver` | Ver integraciones | Consultar la configuración y el estado de integraciones. |
+| `integraciones.gestionar` | Gestionar integraciones | Configurar credenciales y proveedores de integraciones. |
+| `reportes.ver` | Ver reportes | Consultar reportes de ventas y métricas. |
+| `reportes.exportar` | Exportar reportes | Descargar reportes e información comercial. |
+
+## Matriz de asignación
+
+| Permiso | `admin` | `tenant_admin` | `user` |
+| --- | :---: | :---: | :---: |
+| `tenant.ver` | Sí | Sí | No |
+| `tenant.editar` | Sí | Sí | No |
+| `usuarios.ver` | Sí | Sí | No |
+| `usuarios.gestionar` | Sí | Sí | No |
+| `roles.ver` | Sí | Sí | No |
+| `roles.gestionar` | Sí | No | No |
+| `catalogo.ver` | Sí | Sí | No |
+| `catalogo.gestionar` | Sí | Sí | No |
+| `inventario.ver` | Sí | Sí | No |
+| `inventario.ajustar` | Sí | Sí | No |
+| `pedidos.ver` | Sí | Sí | No |
+| `pedidos.gestionar` | Sí | Sí | No |
+| `pedidos.cancelar` | Sí | Sí | No |
+| `pagos.ver` | Sí | Sí | No |
+| `pagos.gestionar` | Sí | Sí | No |
+| `tickets.ver` | Sí | Sí | No |
+| `tickets.gestionar` | Sí | Sí | No |
+| `contenido.gestionar` | Sí | Sí | No |
+| `integraciones.ver` | Sí | Sí | No |
+| `integraciones.gestionar` | Sí | Sí | No |
+| `reportes.ver` | Sí | Sí | No |
+| `reportes.exportar` | Sí | Sí | No |
+
+## Carga inicial
+
+El seeder `Database\Seeders\AuthorizationSeeder` crea o actualiza este catálogo y
+sincroniza sus asignaciones. Puede ejecutarse de manera independiente:
+
+```bash
+php artisan db:seed --class=AuthorizationSeeder
+```
+
+También se ejecuta como parte de `DatabaseSeeder`.
+
+Las acciones del rol `user` no se representan como permisos administrativos. El
+acceso al perfil, carrito, pedidos y tickets se autoriza comprobando que el recurso
+pertenezca al usuario autenticado y al tenant actual.

tests/Feature/Auth/UserAuthorizationRelationsTest.php

@@ -0,0 +1,106 @@
+<?php
+
+namespace Tests\Feature\Auth;
+
+use App\Domains\Attachable\Enums\AttachmentType;
+use App\Domains\Attachable\Models\Attachment;
+use App\Domains\Auth\Models\User;
+use App\Domains\Authorization\Models\Role;
+use App\Domains\Tenant\Models\Tenant;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Support\Facades\Schema;
+use LogicException;
+use Tests\TestCase;
+
+class UserAuthorizationRelationsTest extends TestCase
+{
+    use RefreshDatabase;
+
+    public function test_users_table_has_role_and_tenant_codes(): void
+    {
+        $this->assertTrue(Schema::hasColumns('users', [
+            'rol_codigo',
+            'tenant_codigo',
+        ]));
+    }
+
+    public function test_a_new_user_has_the_user_role_and_no_tenant_by_default(): void
+    {
+        $user = User::factory()->create();
+
+        $this->assertSame('user', $user->rol_codigo);
+        $this->assertNull($user->tenant_codigo);
+        $this->assertSame('user', $user->role->codigo);
+        $this->assertNull($user->tenant);
+    }
+
+    public function test_a_tenant_admin_belongs_to_its_role_and_tenant(): void
+    {
+        $tenant = $this->createTenant();
+        $user = User::factory()->create([
+            'rol_codigo' => 'tenant_admin',
+            'tenant_codigo' => $tenant->codigo,
+        ]);
+
+        $this->assertSame('tenant_admin', $user->role->codigo);
+        $this->assertTrue($user->tenant->is($tenant));
+        $this->assertTrue(
+            Role::query()
+                ->where('codigo', 'tenant_admin')
+                ->firstOrFail()
+                ->users
+                ->contains($user)
+        );
+    }
+
+    public function test_only_a_tenant_admin_can_have_a_tenant_code(): void
+    {
+        $tenant = $this->createTenant();
+
+        $this->expectException(LogicException::class);
+
+        User::factory()->create([
+            'rol_codigo' => 'user',
+            'tenant_codigo' => $tenant->codigo,
+        ]);
+    }
+
+    public function test_a_tenant_admin_must_have_a_tenant_code(): void
+    {
+        $this->expectException(LogicException::class);
+
+        User::factory()->create([
+            'rol_codigo' => 'tenant_admin',
+        ]);
+    }
+
+    private function createTenant(): Tenant
+    {
+        $headerLogo = $this->createAttachment('header.png');
+        $footerLogo = $this->createAttachment('footer.png');
+
+        return Tenant::query()->create([
+            'codigo' => 'acme',
+            'nombre' => 'Acme',
+            'dominio' => 'acme.test',
+            'primary_color' => '#111111',
+            'secondary_color' => '#222222',
+            'danger_color' => '#333333',
+            'success_color' => '#444444',
+            'header_bg_color' => '#ffffff',
+            'footer_bg_color' => '#ffffff',
+            'header_logo_id' => $headerLogo->id,
+            'footer_logo_id' => $footerLogo->id,
+        ]);
+    }
+
+    private function createAttachment(string $filename): Attachment
+    {
+        return Attachment::query()->create([
+            'path' => "test/{$filename}",
+            'filename' => $filename,
+            'type' => AttachmentType::Image,
+            'mime_type' => 'image/png',
+        ]);
+    }
+}

tests/Feature/Authorization/RolePermissionModelTest.php

@@ -0,0 +1,126 @@
+<?php
+
+namespace Tests\Feature\Authorization;
+
+use App\Domains\Authorization\Models\Permission;
+use App\Domains\Authorization\Models\Role;
+use App\Domains\Authorization\Models\RolePermission;
+use Illuminate\Database\QueryException;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Support\Facades\Schema;
+use Tests\TestCase;
+
+class RolePermissionModelTest extends TestCase
+{
+    use RefreshDatabase;
+
+    public function test_authorization_tables_have_the_expected_columns(): void
+    {
+        $this->assertEqualsCanonicalizing([
+            'id',
+            'codigo',
+            'nombre',
+            'descripcion',
+            'created_at',
+            'updated_at',
+        ], Schema::getColumnListing('permisos'));
+
+        $this->assertEqualsCanonicalizing([
+            'id',
+            'codigo',
+            'nombre',
+            'descripcion',
+            'created_at',
+            'updated_at',
+        ], Schema::getColumnListing('roles'));
+
+        $this->assertEqualsCanonicalizing([
+            'id',
+            'codigo_permiso',
+            'rol_codigo',
+            'created_at',
+            'updated_at',
+        ], Schema::getColumnListing('roles_permisos'));
+    }
+
+    public function test_a_role_and_permission_can_be_related_by_their_codes(): void
+    {
+        $role = Role::query()->create([
+            'codigo' => 'administrador',
+            'nombre' => 'Administrador',
+            'descripcion' => 'Administra la tienda.',
+        ]);
+        $permission = Permission::query()->create([
+            'codigo' => 'catalogo.editar',
+            'nombre' => 'Editar catálogo',
+        ]);
+
+        $role->permissions()->attach($permission->codigo);
+
+        $this->assertTrue($role->permissions()->firstOrFail()->is($permission));
+        $this->assertTrue($permission->roles()->firstOrFail()->is($role));
+        $this->assertDatabaseHas('roles_permisos', [
+            'rol_codigo' => $role->codigo,
+            'codigo_permiso' => $permission->codigo,
+        ]);
+    }
+
+    public function test_the_pivot_model_exposes_its_role_and_permission(): void
+    {
+        $role = Role::query()->create([
+            'codigo' => 'editor',
+            'nombre' => 'Editor',
+        ]);
+        $permission = Permission::query()->create([
+            'codigo' => 'catalogo.editar',
+            'nombre' => 'Editar catálogo',
+        ]);
+        $assignment = RolePermission::query()->create([
+            'rol_codigo' => $role->codigo,
+            'codigo_permiso' => $permission->codigo,
+        ]);
+
+        $this->assertTrue($assignment->role->is($role));
+        $this->assertTrue($assignment->permission->is($permission));
+    }
+
+    public function test_a_permission_cannot_be_assigned_twice_to_the_same_role(): void
+    {
+        $role = Role::query()->create([
+            'codigo' => 'editor',
+            'nombre' => 'Editor',
+        ]);
+        $permission = Permission::query()->create([
+            'codigo' => 'catalogo.editar',
+            'nombre' => 'Editar catálogo',
+        ]);
+        $role->permissions()->attach($permission->codigo);
+
+        $this->expectException(QueryException::class);
+
+        $role->permissions()->attach($permission->codigo);
+    }
+
+    public function test_deleting_a_role_removes_its_permission_assignments(): void
+    {
+        $role = Role::query()->create([
+            'codigo' => 'editor',
+            'nombre' => 'Editor',
+        ]);
+        $permission = Permission::query()->create([
+            'codigo' => 'catalogo.editar',
+            'nombre' => 'Editar catálogo',
+        ]);
+        $role->permissions()->attach($permission->codigo);
+
+        $role->delete();
+
+        $this->assertDatabaseMissing('roles_permisos', [
+            'rol_codigo' => $role->codigo,
+            'codigo_permiso' => $permission->codigo,
+        ]);
+        $this->assertDatabaseHas('permisos', [
+            'codigo' => $permission->codigo,
+        ]);
+    }
+}

tests/Feature/Seeders/AuthorizationSeederTest.php

@@ -0,0 +1,51 @@
+<?php
+
+namespace Tests\Feature\Seeders;
+
+use App\Domains\Authorization\Models\Permission;
+use App\Domains\Authorization\Models\Role;
+use Database\Seeders\AuthorizationSeeder;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Tests\TestCase;
+
+class AuthorizationSeederTest extends TestCase
+{
+    use RefreshDatabase;
+
+    public function test_it_creates_the_initial_roles_and_permissions(): void
+    {
+        $this->seed(AuthorizationSeeder::class);
+
+        $this->assertSame(
+            ['admin', 'adminapp', 'tenant_admin', 'user'],
+            Role::query()->orderBy('codigo')->pluck('codigo')->all()
+        );
+        $this->assertCount(22, Permission::query()->get());
+    }
+
+    public function test_it_assigns_the_expected_permissions_to_each_role(): void
+    {
+        $this->seed(AuthorizationSeeder::class);
+
+        $admin = Role::query()->where('codigo', 'admin')->firstOrFail();
+        $appAdmin = Role::query()->where('codigo', 'adminapp')->firstOrFail();
+        $tenantAdmin = Role::query()->where('codigo', 'tenant_admin')->firstOrFail();
+        $user = Role::query()->where('codigo', 'user')->firstOrFail();
+
+        $this->assertCount(22, $admin->permissions);
+        $this->assertCount(0, $appAdmin->permissions);
+        $this->assertCount(21, $tenantAdmin->permissions);
+        $this->assertFalse($tenantAdmin->permissions->contains('codigo', 'roles.gestionar'));
+        $this->assertCount(0, $user->permissions);
+    }
+
+    public function test_it_can_run_more_than_once_without_creating_duplicates(): void
+    {
+        $this->seed(AuthorizationSeeder::class);
+        $this->seed(AuthorizationSeeder::class);
+
+        $this->assertCount(4, Role::query()->get());
+        $this->assertCount(22, Permission::query()->get());
+        $this->assertDatabaseCount('roles_permisos', 43);
+    }
+}

tests/Feature/Seeders/MenuSeederTest.php

@@ -4,8 +4,10 @@ namespace Tests\Feature\Seeders;
 
 use App\Domains\Attachable\Enums\AttachmentType;
 use App\Domains\Attachable\Models\Attachment;
+use App\Domains\Authorization\Models\Role;
 use App\Domains\Menu\Models\Menu;
 use App\Domains\Tenant\Models\Tenant;
+use Database\Seeders\AuthorizationSeeder;
 use Database\Seeders\MenuSeeder;
 use Illuminate\Foundation\Testing\RefreshDatabase;
 use Tests\TestCase;
@@ -45,6 +47,48 @@ class MenuSeederTest extends TestCase
         }
     }
 
+    public function test_it_assigns_menus_to_the_expected_roles(): void
+    {
+        $this->seed(AuthorizationSeeder::class);
+        $this->seed(MenuSeeder::class);
+
+        $allMenuCodes = Menu::query()
+            ->orderBy('code')
+            ->pluck('code')
+            ->all();
+        $userMenuCodes = Menu::query()
+            ->where('code', 'not like', 'admin.%')
+            ->orderBy('code')
+            ->pluck('code')
+            ->all();
+
+        foreach (['admin', 'adminapp'] as $roleCode) {
+            $roleMenuCodes = Role::query()
+                ->where('codigo', $roleCode)
+                ->firstOrFail()
+                ->menus()
+                ->orderBy('menues.code')
+                ->pluck('menues.code')
+                ->all();
+
+            $this->assertSame($allMenuCodes, $roleMenuCodes);
+        }
+
+        $userRoleMenuCodes = Role::query()
+            ->where('codigo', 'user')
+            ->firstOrFail()
+            ->menus()
+            ->orderBy('menues.code')
+            ->pluck('menues.code')
+            ->all();
+
+        $this->assertSame($userMenuCodes, $userRoleMenuCodes);
+        $this->assertDatabaseCount(
+            'menues_roles',
+            (count($allMenuCodes) * 2) + count($userMenuCodes)
+        );
+    }
+
     public function test_it_seeds_the_account_menu_hierarchy(): void
     {
         $tenant = $this->createTenant('account_tenant');