# US-MGN007-001: Gestionar Audit Trail de Entidades

## Identificacion

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

---

## Historia de Usuario

**Como** administrador del sistema
**Quiero** tener registro automatico de todos los cambios en entidades criticas
**Para** mantener trazabilidad completa y poder restaurar datos si es necesario

---

## Descripcion

El sistema registra automaticamente todas las operaciones CRUD en entidades marcadas como auditables. Cada registro incluye quien hizo el cambio, cuando, que campos cambiaron y los valores anteriores/nuevos. Los campos sensibles se enmascaran.

### Contexto

- Registro automatico sin intervencion del desarrollador
- Almacenamiento de valores old/new para cada cambio
- Campos sensibles enmascarados
- Posibilidad de restaurar estado anterior

---

## Criterios de Aceptacion

### Escenario 1: Registro automatico de creacion

```gherkin
Given una entidad marcada con @Auditable (ej: User)
When un usuario crea un nuevo registro
Then el sistema crea automaticamente un audit log con:
  | action | "create" |
  | old_values | null |
  | new_values | { todos los campos } |
  | user_id | ID del usuario que creo |
```

### Escenario 2: Registro automatico de actualizacion

```gherkin
Given un usuario existente con name = "John Doe"
When un administrador cambia el nombre a "John Smith"
Then el sistema crea un audit log con:
  | action | "update" |
  | old_values | { "name": "John Doe" } |
  | new_values | { "name": "John Smith" } |
  | changed_fields | ["name"] |
  And solo se registran los campos que cambiaron
```

### Escenario 3: Registro de eliminacion soft-delete

```gherkin
Given un registro activo
When un usuario lo elimina (soft delete)
Then el sistema crea un audit log con:
  | action | "delete" |
  | old_values | { "deleted_at": null } |
  | new_values | { "deleted_at": "2025-12-05T..." } |
```

### Escenario 4: Consultar historial de entidad

```gherkin
Given un usuario administrador con permiso "audit.read"
When accede a GET /api/v1/audit/entity/users/{userId}
Then el sistema responde con status 200
  And retorna lista de cambios ordenados por fecha desc
  And cada entrada incluye: action, user, changedFields, createdAt
```

### Escenario 5: Ver detalle de un cambio

```gherkin
Given un registro de audit existente
When accede a GET /api/v1/audit/{auditId}
Then el sistema responde con status 200
  And retorna oldValues y newValues completos
  And incluye metadata: ipAddress, userAgent, requestId
```

### Escenario 6: Campos sensibles enmascarados

```gherkin
Given una entidad con campo password marcado como sensitiveField
When se cambia el password
Then el audit log registra:
  | old_values | { "password": "[REDACTED]" } |
  | new_values | { "password": "[REDACTED]" } |
  And el valor real nunca se almacena
```

### Escenario 7: Restaurar estado anterior

```gherkin
Given un registro de audit para update de User
  And administrador con permiso "audit.restore"
When envia POST /api/v1/audit/{auditId}/restore
Then la entidad se restaura a los valores de old_values
  And se crea nuevo audit log con action = "restore"
  And el cambio se refleja inmediatamente
```

### Escenario 8: Filtrar audit logs

```gherkin
Given multiples registros de audit
When consulta GET /api/v1/audit?entityType=users&action=update&from=2025-12-01
Then retorna solo logs que coinciden con todos los filtros
  And soporta paginacion
```

### Escenario 9: Operacion bulk genera multiples registros

```gherkin
Given una operacion de actualizacion masiva de 50 usuarios
When se ejecuta la operacion
Then se crean 50 registros de audit individuales
  And cada uno tiene su entity_id correspondiente
  And comparten el mismo request_id
```

---

## Mockup / Wireframe

```
+------------------------------------------------------------------+
|  HISTORIAL DE CAMBIOS - Usuario: John Smith                       |
+------------------------------------------------------------------+
| [Filtrar por accion v]  [Desde: ____]  [Hasta: ____]  [Buscar]   |
+------------------------------------------------------------------+

| FECHA              | ACCION   | USUARIO      | CAMPOS           |
+------------------------------------------------------------------+
| 2025-12-05 10:30   | update   | Admin        | name, email      |
|   name: "John Doe" -> "John Smith"                               |
|   email: "old@mail.com" -> "new@mail.com"          [Ver] [↺ Rest]|
+------------------------------------------------------------------+
| 2025-12-04 15:00   | update   | System       | status           |
|   status: "pending" -> "active"                    [Ver]         |
+------------------------------------------------------------------+
| 2025-12-01 09:00   | create   | HR Manager   | (nuevo registro) |
|   Registro creado con todos los campos             [Ver]         |
+------------------------------------------------------------------+

Modal: Detalle de Cambio
+------------------------------------------------------------------+
| DETALLE DEL CAMBIO                                          [X]  |
+------------------------------------------------------------------+
| ID: audit-uuid-123                                                |
| Fecha: 2025-12-05 10:30:00                                       |
| Usuario: Admin (admin@company.com)                                |
| IP: 192.168.1.100                                                |
| Accion: update                                                    |
|                                                                   |
| CAMPOS MODIFICADOS                                                |
+------------------------------------------------------------------+
| Campo        | Valor Anterior     | Valor Nuevo                  |
+------------------------------------------------------------------+
| name         | John Doe           | John Smith                   |
| email        | old@mail.com       | new@mail.com                 |
+------------------------------------------------------------------+
|                                                                   |
|                              [Cerrar]  [=== Restaurar ===]       |
+------------------------------------------------------------------+
```

---

## Notas Tecnicas

### API Endpoints

| Metodo | Path | Descripcion |
|--------|------|-------------|
| GET | /audit/entity/:type/:id | Historial de entidad |
| GET | /audit/:auditId | Detalle de cambio |
| GET | /audit | Buscar con filtros |
| POST | /audit/:auditId/restore | Restaurar estado |

### Decorator @Auditable

```typescript
@Auditable({
  fields: ['name', 'email', 'status', 'role_id'],
  sensitiveFields: ['password', 'token'],
  enabled: true
})
@Entity()
export class User extends BaseEntity { ... }
```

### Performance

- Logging asincrono (no bloquea operacion principal)
- Overhead target: < 10ms por operacion
- Indices en: tenant_id, entity_type, entity_id, created_at

---

## Definicion de Done

- [ ] TypeORM subscriber para capturar cambios
- [ ] Decorator @Auditable funcional
- [ ] Diff de campos modificados
- [ ] Enmascaramiento de campos sensibles
- [ ] Endpoint historial por entidad
- [ ] Endpoint restaurar estado
- [ ] Busqueda con filtros multiples
- [ ] Tests unitarios
- [ ] Documentacion Swagger

---

## Dependencias

### Requiere

| Item | Descripcion |
|------|-------------|
| Tabla audit_logs | Con particionamiento mensual |
| TypeORM Subscriber | Para interceptar operaciones |
| Auth Module | Para obtener usuario actual |

### Bloquea

| Item | Descripcion |
|------|-------------|
| US-MGN007-004 | Reportes de auditoria |

---

## Historial

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