workspace-v1/shared/catalog/audit-logs/README.md

Audit Logs (Registro de Auditoria)

Version: 1.0.0 Origen: projects/gamilit, projects/erp-core Estado: Produccion Ultima actualizacion: 2025-12-27

---

Descripcion

Sistema completo de auditoria y logging con:

• Registro automatico de cambios en entidades
• Historial de acciones de usuario
• Tracking de acceso a recursos sensibles
• Busqueda y filtrado de logs
• Retencion configurable
• Exportacion de reportes

---

Caracteristicas

Caracteristica	Descripcion
Entity Tracking	Cambios automaticos en entidades (create, update, delete)
User Actions	Registro de acciones de usuario
Access Logs	Tracking de acceso a recursos
Immutable	Logs no modificables (append-only)
Searchable	Busqueda full-text y filtros
Retention	Politicas de retencion configurables
Export	Exportacion a CSV/JSON

---

Stack Tecnologico

backend:
  framework: NestJS
  orm: TypeORM
  interceptors: AuditInterceptor
  subscribers: EntitySubscriber

database:
  engine: PostgreSQL
  schemas:
    - audit (logs, access_logs)
  extensions:
    - pg_trgm (busqueda)

optional:
  elasticsearch: Para busqueda avanzada
  s3: Para archivo de logs antiguos

---

Tipos de Audit Log

1. Entity Audit (Cambios en datos)

{
  "action": "UPDATE",
  "entity": "users",
  "entityId": "uuid-xxx",
  "changes": {
    "name": { "old": "John", "new": "Johnny" }
  },
  "userId": "uuid-yyy",
  "timestamp": "2025-12-27T10:30:00Z"
}

2. Action Audit (Acciones de usuario)

{
  "action": "LOGIN",
  "userId": "uuid-xxx",
  "metadata": {
    "ip": "192.168.1.1",
    "userAgent": "Mozilla/5.0..."
  },
  "timestamp": "2025-12-27T10:30:00Z"
}

3. Access Audit (Acceso a recursos)

{
  "action": "VIEW",
  "resource": "medical_record",
  "resourceId": "uuid-xxx",
  "userId": "uuid-yyy",
  "reason": "Consulta de rutina",
  "timestamp": "2025-12-27T10:30:00Z"
}

---

Estructura del Modulo

audit-logs/
├── backend/
│   ├── src/
│   │   ├── modules/
│   │   │   └── audit/
│   │   │       ├── entities/
│   │   │       │   ├── audit-log.entity.ts
│   │   │       │   └── access-log.entity.ts
│   │   │       ├── services/
│   │   │       │   ├── audit.service.ts
│   │   │       │   └── retention.service.ts
│   │   │       ├── subscribers/
│   │   │       │   └── entity-audit.subscriber.ts
│   │   │       └── audit.module.ts
│   │   ├── interceptors/
│   │   │   └── audit.interceptor.ts
│   │   └── decorators/
│   │       ├── audited.decorator.ts
│   │       └── track-access.decorator.ts
│   └── database/
│       └── ddl/
│           └── audit-schema.sql
│
├── frontend/
│   ├── src/
│   │   ├── pages/
│   │   │   └── admin/
│   │   │       └── AuditLogs.tsx
│   │   └── components/
│   │       └── audit/
│   │           ├── AuditLogTable.tsx
│   │           ├── AuditLogFilters.tsx
│   │           └── AuditLogDetail.tsx
│   └── stores/
│       └── audit.store.ts
│
└── docs/
    ├── entity-tracking.md
    └── compliance-requirements.md

---

Casos de Uso

• Cumplimiento normativo (SOX, HIPAA, GDPR)
• Investigacion de incidentes
• Historial de cambios en registros criticos
• Acceso a datos sensibles (expedientes medicos, financieros)
• Deteccion de anomalias

---

Trade-offs

Ventaja	Desventaja
Cumplimiento normativo	Storage adicional
Investigacion de incidentes	Performance overhead
Historial completo	Complejidad de queries
Inmutabilidad	No se puede borrar

---

Proyectos que lo Usan

Proyecto	Version	Notas
gamilit	1.0.0	Auditoria de progreso
erp-core	1.0.0	Base para verticales
erp-clinicas	pendiente	Requerido por NOM-024

---

Requisitos de Cumplimiento

Normativa	Requisito	Implementacion
GDPR	Right to access	Export de logs por usuario
HIPAA	Access tracking	access-log por expediente
SOX	Financial audit	Entity audit en transacciones
NOM-024	Expediente electronico	Access log + entity audit

---

Referencias

• IMPLEMENTATION.md - Guia paso a paso
• _reference/ - Codigo de referencia
• auth - Informacion de usuario para logs
• multi-tenancy - Aislamiento de logs por tenant

---

Catalogo de Funcionalidades - SIMCO v3.4