# RF-AUDIT-001: Audit Trail de Entidades

## Identificacion

| Campo | Valor |
|-------|-------|
| **ID** | RF-AUDIT-001 |
| **Modulo** | MGN-007 Audit |
| **Titulo** | Audit Trail de Entidades |
| **Prioridad** | P0 - Critica |
| **Estado** | Draft |
| **Fecha** | 2025-12-05 |

---

## Descripcion

El sistema debe registrar automaticamente todos los cambios realizados en entidades criticas, incluyendo quien, cuando, que cambio y los valores anteriores/nuevos, permitiendo trazabilidad completa y restauracion de datos.

---

## Requisitos Funcionales

### RF-AUDIT-001.1: Estructura del Registro de Auditoria

| Campo | Tipo | Descripcion |
|-------|------|-------------|
| id | UUID | Identificador unico |
| tenant_id | UUID | Tenant donde ocurrio |
| user_id | UUID | Usuario que realizo la accion |
| action | ENUM | CREATE, UPDATE, DELETE, RESTORE |
| entity_type | VARCHAR(100) | Tipo de entidad (tabla) |
| entity_id | UUID | ID del registro afectado |
| old_values | JSONB | Valores anteriores |
| new_values | JSONB | Valores nuevos |
| changed_fields | TEXT[] | Lista de campos modificados |
| ip_address | INET | IP del cliente |
| user_agent | TEXT | User agent del navegador |
| request_id | UUID | ID de la peticion HTTP |
| created_at | TIMESTAMPTZ | Timestamp del evento |

### RF-AUDIT-001.2: Acciones Auditables

```typescript
enum AuditAction {
  CREATE = 'create',
  UPDATE = 'update',
  DELETE = 'delete',
  RESTORE = 'restore',     // Restaurar soft-delete
  ARCHIVE = 'archive',     // Archivar
  EXPORT = 'export',       // Exportar datos
  IMPORT = 'import',       // Importar datos
  BULK_UPDATE = 'bulk_update'
}
```

### RF-AUDIT-001.3: Entidades Auditables

Por defecto, se auditan las siguientes entidades:

| Modulo | Entidades |
|--------|-----------|
| Auth | sessions, password_changes |
| Users | users, user_roles |
| Roles | roles, permissions, role_permissions |
| Tenants | tenants, subscriptions |
| Catalogs | contacts, products, categories |
| Financial | accounts, journal_entries |

**Configuracion:**
```typescript
@Auditable({
  fields: ['name', 'email', 'status'],  // Campos a auditar
  sensitiveFields: ['password'],         // Campos a ocultar
  enabled: true
})
export class User { ... }
```

### RF-AUDIT-001.4: Campos Sensibles

Ciertos campos se registran de forma especial:

| Tipo | Tratamiento |
|------|-------------|
| Passwords | Solo registrar que cambio, no valores |
| Tokens | Enmascarar (mostrar ultimos 4 chars) |
| Datos personales | Encriptar en audit log |
| Datos financieros | Registrar sin enmascarar |

### RF-AUDIT-001.5: Diferencias (Diff)

Para UPDATEs, solo se almacenan los campos modificados:

```typescript
// Ejemplo de registro
{
  "action": "update",
  "entityType": "users",
  "entityId": "uuid-123",
  "oldValues": {
    "name": "John Doe",
    "email": "john@old.com"
  },
  "newValues": {
    "name": "John Smith",
    "email": "john@new.com"
  },
  "changedFields": ["name", "email"]
}
```

### RF-AUDIT-001.6: Restauracion de Datos

El sistema permite restaurar un registro a un estado anterior:

```typescript
POST /api/v1/audit/:auditId/restore

// Restaura la entidad a los valores en old_values
// Crea nuevo registro de audit con action=RESTORE
```

---

## Operaciones

### Consultar Historial de Entidad

```typescript
GET /api/v1/audit/entity/:type/:id

Response:
{
  "entityType": "users",
  "entityId": "uuid-123",
  "history": [
    {
      "id": "audit-uuid-1",
      "action": "update",
      "changedFields": ["name"],
      "user": { "id": "...", "name": "Admin" },
      "createdAt": "2025-12-05T10:00:00Z"
    },
    {
      "id": "audit-uuid-2",
      "action": "create",
      "user": { "id": "...", "name": "System" },
      "createdAt": "2025-12-01T10:00:00Z"
    }
  ]
}
```

### Consultar Detalle de Cambio

```typescript
GET /api/v1/audit/:auditId

Response:
{
  "id": "audit-uuid-1",
  "action": "update",
  "entityType": "users",
  "entityId": "uuid-123",
  "oldValues": { "name": "John Doe" },
  "newValues": { "name": "John Smith" },
  "changedFields": ["name"],
  "user": { "id": "...", "name": "Admin" },
  "ipAddress": "192.168.1.100",
  "createdAt": "2025-12-05T10:00:00Z"
}
```

### Buscar en Audit Log

```typescript
GET /api/v1/audit?entityType=users&action=update&userId=uuid&from=2025-12-01&to=2025-12-05

Response:
{
  "data": [...],
  "meta": { "total": 50, "page": 1, "limit": 20 }
}
```

---

## Reglas de Negocio

| ID | Regla | Severidad |
|----|-------|-----------|
| BR-001 | Audit logs son inmutables (nunca se modifican) | Critical |
| BR-002 | Retencion minima: 1 año | Compliance |
| BR-003 | Solo admins pueden ver audit log | Security |
| BR-004 | Restauracion requiere permiso especial | Security |
| BR-005 | Operaciones bulk generan un registro por entidad | Info |

---

## Criterios de Aceptacion

- [ ] Registro automatico de CRUD en entidades marcadas
- [ ] Almacenamiento de valores old/new
- [ ] Consulta de historial por entidad
- [ ] Busqueda por usuario, fecha, tipo
- [ ] Restauracion a estado anterior
- [ ] Campos sensibles enmascarados
- [ ] Performance < 10ms overhead por operacion

---

## Historial

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