> ## Documentation Index
> Fetch the complete documentation index at: https://alan-ramirez-dev.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 👤 Introducción al Sitema de Gestión de Identidad y Acceso

> IAM Core API - Gestión de Identidad y Acceso (Backend)

¡Te doy la bienvenida a la documentación del cuarto microservicio del proyecto. El Sistema de Gestión de Identidad y Acceso de mi Portafolio!

Este proyecto actúa como el backend centralizado para gestionar identidades y permisos. Está diseñado bajo una arquitectura REST estricta para demostrar capacidades en seguridad de APIs, control de accesos basado en roles (RBAC) y diseño de bases de datos relacionales en entornos modernos.

## 🚀 Características y Arquitectura Backend

<CardGroup cols={2}>
  <Card title="Seguridad JWT" icon="key">
    Implementación de autenticación sin estado (stateless) para asegurar las transacciones entre el cliente y el servidor mediante JSON Web Tokens.
  </Card>

  <Card title="Control de Accesos (RBAC)" icon="user-check">
    Middlewares personalizados que interceptan y validan privilegios granulares (`admin`, `auditor`, `operador`) antes de ejecutar los controladores.
  </Card>

  <Card title="Bitácora Inmutable" icon="history">
    Registro transaccional de eventos con campos JSON (`payload`) para metadatos históricos y anonimización de direcciones IP mediante Traits.
  </Card>

  <Card title="Protección de Datos" icon="database">
    Implementación de "Soft Deletes" para bajas lógicas de usuarios, manteniendo la integridad referencial sin perder el historial.
  </Card>

  <Card title="Estandarización RESTful" icon="network">
    Contratos de comunicación homologados bajo versionado estricto (`/api/v1/`), garantizando la evolución segura de las interfaces.
  </Card>

  <Card title="Testing Automatizado" icon="flask-conical">
    Cobertura de lógica de negocio y endpoints mediante **Pest**, garantizando flujos predecibles y a prueba de regresiones.
  </Card>
</CardGroup>

## 🛠️ Stack Tecnológico

| Tecnología     | Versión | Propósito en el proyecto                                  |
| :------------- | :------ | :-------------------------------------------------------- |
| **Laravel**    | `^13.8` | Framework base, enrutamiento MVC y ORM (Eloquent)         |
| **PHP**        | `^8.3`  | Lenguaje de servidor con tipado estricto                  |
| **PostgreSQL** | `17`    | Motor de base de datos relacional y gestión de secuencias |
| **jwt-auth**   | `^2.3`  | Generación y validación de tokens de acceso               |
| **Pest**       | `^4.7`  | Framework de pruebas (Testing)                            |

## 💻 Comandos de Desarrollo

Instrucciones para levantar el entorno localmente (se asume que PostgreSQL está corriendo en el puerto `5434`).

```bash theme={null}
# Instalar dependencias
composer install

# Generar variables de entorno y llaves
cp .env.example .env
php artisan key:generate
php artisan jwt:secret

# Reconstruir BD y siembra de datos
php artisan migrate:fresh --seed

# Iniciar servidor local
php artisan serve

# Ejecutar suite de pruebas
php artisan test
```

## 📡 Documentación de la API

Todas las peticiones a rutas protegidas exigen el header: `Authorization: Bearer <token>`.

### 🔐 Autenticación (`/api/v1/auth`)

| Método | Endpoint  | Descripción                                   | Acceso    |
| :----- | :-------- | :-------------------------------------------- | :-------- |
| `POST` | `/login`  | Autentica credenciales y devuelve el JWT      | Público   |
| `GET`  | `/me`     | Devuelve la información del usuario en sesión | Protegido |
| `POST` | `/logout` | Invalida el token actual en la lista negra    | Protegido |

### 👥 Gestión de Accesos

| Método   | Endpoint              | Descripción                               | Roles Permitidos           |
| :------- | :-------------------- | :---------------------------------------- | :------------------------- |
| `GET`    | `/roles`              | Lista el catálogo de roles del sistema    | `admin, auditor, operador` |
| `GET`    | `/users`              | Obtiene el directorio y estado lógico     | `admin, auditor, operador` |
| `POST`   | `/users`              | Hashea credenciales y registra un usuario | `admin`                    |
| `DELETE` | `/users/{id}`         | Ejecuta una baja lógica (Soft Delete)     | `admin`                    |
| `POST`   | `/users/{id}/restore` | Revierte la baja lógica                   | `admin`                    |

### 📜 Bitácora y Tráfico

| Método | Endpoint         | Descripción                          | Roles Permitidos |
| :----- | :--------------- | :----------------------------------- | :--------------- |
| `GET`  | `/audit-logs`    | Retorna los 50 eventos más recientes | `admin, auditor` |
| `POST` | `/demo/simulate` | Inyecta tráfico cronológico simulado | `admin`          |