> For the complete documentation index, see [llms.txt](https://senselab.gitbook.io/senselab-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://senselab.gitbook.io/senselab-docs/docs/archive/fase_3_completada.md).

# FASE 3 - SISTEMA RBAC COMPLETO ✅

## Resumen Ejecutivo

La **FASE 3** ha sido completada exitosamente. Se implementó un sistema completo de **Role-Based Access Control (RBAC)** con autenticación vía Laravel Sanctum, incluyendo middleware, modelos con métodos avanzados, seeders de datos de prueba y endpoints de autenticación.

***

## Implementación Realizada

### 1. Middleware de Autorización

**Archivo**: `app/Http/Middleware/CheckPermission.php`

```php
public function handle(Request $request, Closure $next, string $permission): Response
{
    if (!$request->user()) {
        return response()->json(['message' => 'No autenticado'], 401);
    }

    if (!$request->user()->hasPermission($permission)) {
        return response()->json(['message' => 'No autorizado'], 403);
    }

    return $next($request);
}
```

**Registro**: `bootstrap/app.php`

```php
'permission' => \App\Http\Middleware\CheckPermission::class
```

**Uso en rutas**:

```php
Route::get('/productos', [ProductoController::class, 'index'])
    ->middleware('permission:ver-productos');
```

***

### 2. Modelos RBAC Mejorados

#### Usuario (`app/Models/Usuario.php`)

**Herencia**: Cambió de `Model` a `Authenticatable`

**Traits**:

* `HasApiTokens` (Laravel Sanctum)

**Métodos RBAC**:

```php
// Verificar si tiene un permiso específico
hasPermission(string $permissionSlug): bool

// Verificar si tiene un rol específico
hasRole(string $roleName): bool

// Verificar si tiene alguno de los roles
hasAnyRole(array $roleNames): bool

// Obtener todos los permisos del usuario
getAllPermissions(): Collection

// Asignar múltiples roles al usuario
assignRoles(array $roleIds): void

// Método para autenticación con password_hash
getAuthPassword()
```

#### Rol (`app/Models/Rol.php`)

**Relaciones agregadas**:

```php
usuarios(): BelongsToMany     // Through rol_usuario
permisos(): BelongsToMany     // Through roles_permisos
```

**Métodos**:

```php
assignPermissions(array $permisoIds): void
```

#### Permiso (`app/Models/Permiso.php`)

**Cambios**:

* Campo `codigo_unico` → `slug` (consistencia con seeders)
* Relación: `roles(): BelongsToMany`

***

### 3. Seeders de Datos Demo

#### CargosSeeder

**Registros**: 7 cargos

```
- Gerente General
- Contador
- Administrador de Sistema
- Vendedor
- Comprador
- Bodeguero
- Asistente Administrativo
```

#### EmpresaDemoSeeder

**Empresa creada**: "Senselab"

* **RUC**: 3-101-123456
* **Régimen**: Tradicional (01)
* **Ubicación**: San José, Costa Rica
* **Sucursal**: Oficina Central

#### UsuarioAdminSeeder

**Usuario administrador**:

* **Email**: `admin@senselab.com`
* **Password**: `admin123`
* **Rol**: Administrador
* **Permisos**: 68 permisos (TODOS los del sistema)
* **Cargo**: Administrador de Sistema
* **Empresa**: Senselab

***

### 4. Controlador de Autenticación

**Archivo**: `app/Http/Controllers/API/AuthController.php`

#### Endpoints:

**POST `/api/login`**

```json
{
  "email": "admin@senselab.com",
  "password": "admin123"
}
```

**Respuesta**:

```json
{
  "success": true,
  "data": {
    "usuario": { /* datos completos */ },
    "token": "1|3Cp3P7hatmlPlno4R9we0ihkDWYlvaxteBAmtQiLf7213d12",
    "permisos": [
      "ver-empresas",
      "crear-empresas",
      ...
      "eliminar-configuracion"
    ]
  },
  "message": "Login exitoso"
}
```

**POST `/api/logout`** (protegida)

* Revoca el token actual

**GET `/api/me`** (protegida)

* Retorna usuario autenticado con permisos

***

## Migraciones Ejecutadas

✅ `create_personal_access_tokens_table`

* Tabla requerida por Laravel Sanctum para tokens API

***

## Datos Creados

| Entidad               | Cantidad          | Descripción                            |
| --------------------- | ----------------- | -------------------------------------- |
| Regímenes Tributarios | 2                 | Tradicional, Simplificado              |
| Formas de Pago        | 6                 | Efectivo, Tarjeta, Transferencia, etc. |
| Tipos de Cuentas      | 8                 | Activo, Pasivo, Patrimonio, etc.       |
| Unidades de Medida    | 11                | Unid, Kg, L, m, etc.                   |
| Permisos              | 68                | 17 módulos × 4 acciones                |
| Roles                 | 7                 | Administrador, Gerente, Contador, etc. |
| Cargos                | 7                 | Gerente, Contador, Vendedor, etc.      |
| Empresas              | 1                 | Senselab                               |
| Sucursales            | 1                 | Oficina Central                        |
| Usuarios              | 1                 | <admin@senselab.com> (Administrador)   |
| **TOTAL**             | **112 registros** | **Datos maestros + demo**              |

***

## Pruebas Realizadas

### Login Exitoso

```bash
curl -X POST "http://localhost:8000/api/login" \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@senselab.com", "password": "admin123"}'
```

**Resultado**: ✅ Token generado + 68 permisos retornados

***

## Flujo RBAC Implementado

```
Usuario autenticado
    ↓
hasPermission('ver-productos')
    ↓
Usuario → Roles (tabla rol_usuario)
    ↓
Roles → Permisos (tabla roles_permisos)
    ↓
Verificar si slug='ver-productos' existe y activo=true
    ↓
true → Continuar request
false → 403 Forbidden
```

***

## Commits Realizados

### Commit 1: FASE 1

**Hash**: `0dd7c39` **Mensaje**: Correcciones críticas DB

### Commit 2: FASE 2

**Hash**: `58e2055` **Mensaje**: Seeders de datos maestros

### Commit 3: FASE 3

**Hash**: `e668c64` **Mensaje**: Sistema RBAC completo

***

## Estado del Proyecto

### Completado ✅

* ✅ FASE 1: Correcciones críticas
* ✅ FASE 2: Seeders de datos maestros
* ✅ FASE 3: Sistema RBAC completo

### Pendiente

* ⏳ FASE 4: Testing (AuthTest, ProductoTest, etc.)
* ⏳ FASE 5: Documentación API (Swagger)

***

## Próximos Pasos Sugeridos

### FASE 4: Testing

1. **Crear Tests de Autenticación**

   ```bash
   php artisan make:test AuthTest
   ```

   * Probar login válido/inválido
   * Probar logout
   * Probar endpoints protegidos
2. **Crear Tests de Permisos**

   ```bash
   php artisan make:test PermissionTest
   ```

   * Verificar middleware CheckPermission
   * Probar acceso con/sin permisos
   * Probar roles múltiples
3. **Crear Tests de Modelos**

   ```bash
   php artisan make:test ProductoTest
   php artisan make:test VentaTest
   ```

### FASE 5: Documentación API

1. **Instalar Swagger**

   ```bash
   composer require darkaonline/l5-swagger
   php artisan vendor:publish --provider="L5Swagger\L5SwaggerServiceProvider"
   ```
2. **Anotar Controladores**
   * Agregar `@OA\Tag`, `@OA\Post`, `@OA\Get`, etc.
   * Documentar request/response schemas
3. **Generar Documentación**

   ```bash
   php artisan l5-swagger:generate
   ```

   * Acceder a `/api/documentation`

***

## Credenciales de Prueba

### Usuario Administrador

* **Email**: `admin@senselab.com`
* **Password**: `admin123`
* **Rol**: Administrador
* **Permisos**: TODOS (68 permisos)

### Headers para Requests Protegidos

```
Authorization: Bearer {token}
Content-Type: application/json
```

***

## Archivos Clave

### Middleware

* `app/Http/Middleware/CheckPermission.php`
* `bootstrap/app.php` (registro)

### Controladores

* `app/Http/Controllers/API/AuthController.php`

### Modelos

* `app/Models/Usuario.php` (Authenticatable + HasApiTokens)
* `app/Models/Rol.php`
* `app/Models/Permiso.php`

### Seeders

* `database/seeders/CargosSeeder.php`
* `database/seeders/EmpresaDemoSeeder.php`
* `database/seeders/UsuarioAdminSeeder.php`
* `database/seeders/DatabaseSeeder.php` (orquestador)

### Migraciones

* `database/migrations/2025_11_20_190541_create_personal_access_tokens_table.php`

***

## Comandos Útiles

```bash
# Ejecutar todos los seeders
php artisan db:seed

# Ejecutar seeder específico
php artisan db:seed --class=UsuarioAdminSeeder

# Refrescar DB y seeders
php artisan migrate:fresh --seed

# Crear usuario admin (manual)
php artisan tinker
>>> $usuario = App\Models\Usuario::find(1);
>>> $usuario->hasPermission('ver-productos'); // true

# Verificar permisos de usuario
php artisan tinker
>>> $usuario = App\Models\Usuario::with('roles.permisos')->find(1);
>>> $usuario->getAllPermissions()->pluck('slug')->toArray();
```

***

## Conclusión

La **FASE 3** ha sido completada exitosamente. El sistema ahora cuenta con:

1. ✅ Autenticación completa vía Sanctum
2. ✅ Sistema RBAC funcional con middleware
3. ✅ Modelos con métodos RBAC avanzados
4. ✅ Datos de prueba (empresa demo + admin)
5. ✅ API endpoints de autenticación
6. ✅ 68 permisos asignados al rol Administrador
7. ✅ Relaciones Usuario ↔ Rol ↔ Permiso operacionales

**Estado Git**: Todos los cambios committeados y pusheados a `origin/main`.

***

**Desarrollado por**: GitHub Copilot\
**Fecha**: 20 de noviembre de 2025\
**Versión del Proyecto**: Laravel 11 | PHP 8.4


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://senselab.gitbook.io/senselab-docs/docs/archive/fase_3_completada.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.