# RF-AUDIT-002: Logs de Acceso

## Identificacion

| Campo | Valor |
|-------|-------|
| **ID** | RF-AUDIT-002 |
| **Modulo** | MGN-007 Audit |
| **Titulo** | Logs de Acceso |
| **Prioridad** | P0 - Critica |
| **Estado** | Draft |
| **Fecha** | 2025-12-05 |

---

## Descripcion

El sistema debe registrar todos los accesos a recursos protegidos, incluyendo peticiones HTTP, accesos a APIs, y consultas a datos sensibles, para monitoreo de seguridad y cumplimiento normativo.

---

## Requisitos Funcionales

### RF-AUDIT-002.1: Estructura del Log de Acceso

| Campo | Tipo | Descripcion |
|-------|------|-------------|
| id | UUID | Identificador unico |
| tenant_id | UUID | Tenant (si aplica) |
| user_id | UUID | Usuario (si autenticado) |
| session_id | UUID | ID de sesion |
| request_id | UUID | ID unico de la peticion |
| method | VARCHAR(10) | GET, POST, PUT, DELETE |
| path | VARCHAR(500) | Ruta del recurso |
| query_params | JSONB | Parametros de query |
| status_code | INTEGER | Codigo de respuesta HTTP |
| response_time_ms | INTEGER | Tiempo de respuesta |
| ip_address | INET | IP del cliente |
| user_agent | TEXT | User agent |
| referer | VARCHAR(500) | Referer header |
| country_code | VARCHAR(2) | Pais (geo-ip) |
| created_at | TIMESTAMPTZ | Timestamp |

### RF-AUDIT-002.2: Niveles de Logging

```typescript
enum AccessLogLevel {
  MINIMAL = 'minimal',   // Solo errores y auth
  STANDARD = 'standard', // Todo excepto GET de listas
  VERBOSE = 'verbose',   // Todo incluyendo GETs
  DEBUG = 'debug'        // Todo + request body
}
```

Configurable por tenant y globalmente.

### RF-AUDIT-002.3: Recursos a Monitorear

| Tipo | Ejemplos | Prioridad |
|------|----------|-----------|
| Autenticacion | /auth/login, /auth/logout | Siempre |
| Admin APIs | /admin/*, /settings/* | Siempre |
| Datos sensibles | /users/*, /contacts/* | Siempre |
| APIs publicas | /api/v1/* | Configurable |
| Assets estaticos | /assets/*, /public/* | Nunca |

### RF-AUDIT-002.4: Excepcion de Logging

Ciertos paths se excluyen por defecto:

```typescript
const EXCLUDED_PATHS = [
  '/health',
  '/metrics',
  '/favicon.ico',
  '/assets/*',
  '/static/*'
];
```

### RF-AUDIT-002.5: Request Body Logging

Para operaciones criticas, se puede registrar el body:

```typescript
// Solo para operaciones de escritura en recursos criticos
// Body se sanitiza (passwords -> ****)
// Maximo 10KB de body almacenado
{
  "requestBody": {
    "email": "user@example.com",
    "password": "****",
    "name": "John Doe"
  }
}
```

### RF-AUDIT-002.6: Metricas de Acceso

El sistema calcula metricas en tiempo real:

```typescript
interface AccessMetrics {
  requestsPerMinute: number;
  errorRate: number;
  avgResponseTime: number;
  uniqueUsers: number;
  topEndpoints: { path: string; count: number }[];
  topErrors: { statusCode: number; count: number }[];
}
```

---

## Operaciones

### Consultar Logs de Acceso

```typescript
GET /api/v1/audit/access?from=2025-12-01&to=2025-12-05&userId=uuid&statusCode=500

Response:
{
  "data": [
    {
      "id": "uuid",
      "method": "POST",
      "path": "/api/v1/users",
      "statusCode": 201,
      "responseTimeMs": 45,
      "user": { "id": "...", "name": "Admin" },
      "ipAddress": "192.168.1.100",
      "createdAt": "2025-12-05T10:00:00Z"
    }
  ],
  "meta": { "total": 1000, "page": 1 }
}
```

### Consultar Metricas

```typescript
GET /api/v1/audit/access/metrics?period=1h

Response:
{
  "period": "1h",
  "requestsTotal": 5000,
  "requestsPerMinute": 83.3,
  "errorRate": 0.02,
  "avgResponseTime": 120,
  "p99ResponseTime": 450,
  "uniqueUsers": 150,
  "topEndpoints": [
    { "path": "/api/v1/users", "count": 500 }
  ]
}
```

### Consultar Sesiones de Usuario

```typescript
GET /api/v1/audit/access/user/:userId/sessions

Response:
{
  "sessions": [
    {
      "sessionId": "uuid",
      "startedAt": "2025-12-05T08:00:00Z",
      "lastActivityAt": "2025-12-05T10:30:00Z",
      "ipAddress": "192.168.1.100",
      "userAgent": "Mozilla/5.0...",
      "requestCount": 150
    }
  ]
}
```

---

## Reglas de Negocio

| ID | Regla | Severidad |
|----|-------|-----------|
| BR-001 | Logs de acceso son inmutables | Critical |
| BR-002 | Retencion: 90 dias por defecto | Compliance |
| BR-003 | Body de request sanitizado | Security |
| BR-004 | Solo admins acceden a logs | Security |
| BR-005 | Rate limit en consultas de logs | Performance |

---

## Criterios de Aceptacion

- [ ] Logging automatico de todas las peticiones
- [ ] Filtrado por paths excluidos
- [ ] Sanitizacion de datos sensibles
- [ ] Metricas en tiempo real
- [ ] Consulta con filtros multiples
- [ ] Geo-IP para ubicacion
- [ ] Performance < 5ms overhead

---

## Historial

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