# US-MGN007-002: Gestionar Logs de Acceso

## Identificacion

| Campo | Valor |
|-------|-------|
| **ID** | US-MGN007-002 |
| **Modulo** | MGN-007 Audit |
| **Sprint** | Sprint 5 |
| **Prioridad** | P0 - Critica |
| **Story Points** | 8 |
| **Estado** | Ready |
| **RF Relacionado** | RF-AUDIT-002 |
| **Fecha** | 2025-12-05 |

---

## Historia de Usuario

**Como** administrador del sistema
**Quiero** tener registro de todos los accesos a recursos del sistema
**Para** monitorear el uso, detectar anomalias y cumplir con normativas

---

## Descripcion

El sistema registra automaticamente todas las peticiones HTTP a recursos protegidos, incluyendo informacion del usuario, IP, tiempo de respuesta y resultado. Soporta diferentes niveles de logging configurables.

### Contexto

- Logging automatico de peticiones HTTP
- Filtrado de paths irrelevantes
- Sanitizacion de datos sensibles
- Metricas en tiempo real

---

## Criterios de Aceptacion

### Escenario 1: Registro automatico de peticion

```gherkin
Given un usuario autenticado
When realiza una peticion POST /api/v1/users
Then el sistema registra automaticamente:
  | method | "POST" |
  | path | "/api/v1/users" |
  | status_code | 201 |
  | response_time_ms | 45 |
  | user_id | ID del usuario |
  | ip_address | IP del cliente |
```

### Escenario 2: Excluir paths de logging

```gherkin
Given paths configurados como excluidos: ["/health", "/metrics"]
When un servicio llama a GET /health
Then el sistema NO registra la peticion
  And el endpoint responde normalmente
```

### Escenario 3: Consultar logs de acceso

```gherkin
Given un administrador con permiso "audit.access.read"
When accede a GET /api/v1/audit/access?from=2025-12-01&userId=uuid
Then el sistema responde con status 200
  And retorna lista de accesos filtrados
  And soporta paginacion
```

### Escenario 4: Consultar metricas de acceso

```gherkin
Given registros de acceso de la ultima hora
When consulta GET /api/v1/audit/access/metrics?period=1h
Then retorna:
  | requestsPerMinute | 83.3 |
  | errorRate | 0.02 |
  | avgResponseTime | 120 |
  | p99ResponseTime | 450 |
```

### Escenario 5: Logging de errores

```gherkin
Given una peticion que resulta en error 500
When el sistema registra el acceso
Then incluye el status_code 500
  And se marca como error para facil filtrado
```

### Escenario 6: Sanitizacion de datos sensibles

```gherkin
Given nivel de logging = VERBOSE (incluye body)
  And peticion POST con { password: "secret123" }
When el sistema registra la peticion
Then el body se guarda como { password: "****" }
  And otros campos se mantienen intactos
```

### Escenario 7: Geo-localizacion por IP

```gherkin
Given una peticion desde IP 200.55.128.100
When el sistema registra el acceso
Then incluye country_code basado en geo-IP
  And se puede filtrar por pais
```

### Escenario 8: Consultar sesiones de usuario

```gherkin
Given un usuario con multiples sesiones activas
When consulta GET /api/v1/audit/access/user/{userId}/sessions
Then retorna lista de sesiones con:
  | sessionId, startedAt, lastActivityAt, ipAddress, requestCount |
```

### Escenario 9: Top endpoints

```gherkin
Given metricas del periodo
When consulta metricas
Then incluye topEndpoints con los paths mas accedidos
  And topErrors con los errores mas frecuentes
```

---

## Mockup / Wireframe

```
+------------------------------------------------------------------+
|  LOGS DE ACCESO                                                   |
+------------------------------------------------------------------+
| [Periodo: 1h v] [Usuario: ___] [Status: Todos v] [Metodo: Todos v]|
+------------------------------------------------------------------+

METRICAS
+------------------------------------------------------------------+
| Peticiones/min: 83  | Error Rate: 2%  | Resp Avg: 120ms          |
+------------------------------------------------------------------+

| FECHA              | METODO | PATH              | STATUS | TIEMPO |
+------------------------------------------------------------------+
| 2025-12-05 10:30   | POST   | /api/v1/users     | 201    | 45ms   |
| 2025-12-05 10:29   | GET    | /api/v1/users     | 200    | 12ms   |
| 2025-12-05 10:28   | DELETE | /api/v1/users/123 | 500    | 230ms  |
| 2025-12-05 10:27   | GET    | /api/v1/settings  | 200    | 8ms    |
+------------------------------------------------------------------+
                                              [< Anterior] [1] [Siguiente >]

Detalle de Acceso:
+------------------------------------------------------------------+
| DETALLE DEL ACCESO                                          [X]  |
+------------------------------------------------------------------+
| Request ID: req-uuid-456                                          |
| Fecha: 2025-12-05 10:30:00                                       |
| Usuario: admin@company.com                                        |
|                                                                   |
| REQUEST                                                           |
| Metodo: POST                                                      |
| Path: /api/v1/users                                              |
| Query: ?notify=true                                               |
|                                                                   |
| RESPUESTA                                                         |
| Status: 201 Created                                               |
| Tiempo: 45ms                                                      |
|                                                                   |
| ORIGEN                                                            |
| IP: 192.168.1.100                                                |
| Pais: MX                                                          |
| User-Agent: Mozilla/5.0 (Windows NT 10.0)...                     |
+------------------------------------------------------------------+
```

---

## Notas Tecnicas

### API Endpoints

| Metodo | Path | Descripcion |
|--------|------|-------------|
| GET | /audit/access | Listar logs |
| GET | /audit/access/:id | Detalle de acceso |
| GET | /audit/access/metrics | Metricas agregadas |
| GET | /audit/access/user/:userId/sessions | Sesiones de usuario |

### Middleware de Logging

```typescript
@Injectable()
export class AccessLogMiddleware implements NestMiddleware {
  use(req: Request, res: Response, next: NextFunction) {
    const startTime = Date.now();

    res.on('finish', () => {
      const duration = Date.now() - startTime;
      this.logAccess(req, res, duration);
    });

    next();
  }
}
```

### Niveles de Logging

| Nivel | Registra |
|-------|----------|
| MINIMAL | Solo errores y autenticacion |
| STANDARD | Todo excepto GETs de listas |
| VERBOSE | Todas las peticiones |
| DEBUG | Todo + request body |

---

## Definicion de Done

- [ ] Middleware de logging implementado
- [ ] Filtrado de paths excluidos
- [ ] Sanitizacion de body
- [ ] Geo-IP lookup
- [ ] Endpoint de consulta con filtros
- [ ] Metricas agregadas
- [ ] Dashboard de sesiones
- [ ] Tests unitarios
- [ ] Documentacion Swagger

---

## Dependencias

### Requiere

| Item | Descripcion |
|------|-------------|
| Tabla access_logs | Con particionamiento diario |
| Redis | Para cache de metricas |
| Servicio GeoIP | Para localizacion |

### Bloquea

| Item | Descripcion |
|------|-------------|
| US-MGN007-003 | Eventos de seguridad (usa datos) |
| US-MGN007-004 | Reportes de auditoria |

---

## Historial

| Version | Fecha | Autor | Cambios |
|---------|-------|-------|---------|
| 1.0 | 2025-12-05 | Requirements-Analyst | Creacion inicial |
