# 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

```yaml
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)
```json
{
  "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)
```json
{
  "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)
```json
{
  "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*