erp-core/docs/02-fase-core-business/MGN-007-audit/requerimientos/RF-AUDIT-001.md

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

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:

@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:

// 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:

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

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

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

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