# LOGS_SYSTEM.md — Sistema de Logs del Organismo 4GatosCoin

El **Sistema de Logs** es la capa de auditoría, trazabilidad y memoria técnica del organismo 4GatosCoin.  
Registra cada gesto, evento, anomalía, ritual, ciclo y transición del organismo.

Este documento describe cómo funcionan los logs, cómo se almacenan, cómo se clasifican y cómo deben implementarse.

---

# 1. ¿Qué son los Logs?

Los logs representan:

- trazabilidad técnica  
- auditoría interna  
- registro de eventos  
- memoria estructurada  
- diagnóstico del organismo  
- base para la narrativa profunda  

Son el **diario interno** del organismo.

---

# 2. Componentes Técnicos

### 2.1. Modelo
Los logs se almacenan en:

```
models/Log.ts
```

Campos típicos:

```json
{
  "type": "gesture",
  "wallet": "0x123...",
  "timestamp": 1700000000,
  "metadata": {}
}
```

### 2.2. Endpoints relacionados

```
GET /api/logs
```

### 2.3. Panel DevWeb3
Ubicación:

```
app/devweb3/logs/
```

Funciones:

- ver logs  
- filtrar por tipo  
- ver anomalías  
- ver rituales  
- ver ciclos  
- ver eventos energéticos  

---

# 3. Tipos de Logs

Los logs se clasifican en:

## 3.1. Logs de Gestos
Generados por:

- `POST /api/gesture`

Ejemplo:

```json
{
  "type": "gesture",
  "gesture": "pulso_vocal",
  "wallet": "0xabc..."
}
```

---

## 3.2. Logs de Puntos
Generados por:

- asignación de puntos  
- bonus  
- penalizaciones  

Ejemplo:

```json
{
  "type": "points",
  "wallet": "0xabc...",
  "pointsAdded": 6
}
```

---

## 3.3. Logs de Energía
Generados por:

- generación  
- consumo  
- rituales  
- ciclos  

Ejemplo:

```json
{
  "type": "energy",
  "amount": 50,
  "source": "ritual"
}
```

---

## 3.4. Logs de Semillas
Generados por:

- generación  
- rareza  
- distribución  

Ejemplo:

```json
{
  "type": "seed",
  "rarity": "epic",
  "seedId": "seed_777"
}
```

---

## 3.5. Logs de Rituales
Generados por:

- activación  
- participación  
- impacto  

Ejemplo:

```json
{
  "type": "ritual",
  "ritual": "elgritoquecrea",
  "participants": 120
}
```

---

## 3.6. Logs de Ciclos
Generados por:

- completar ciclo  
- alcanzar umbral  

Ejemplo:

```json
{
  "type": "cycle",
  "cycle": 12
}
```

---

## 3.7. Logs de Temporadas
Generados por:

- inicio de temporada  
- transición  
- cierre  

Ejemplo:

```json
{
  "type": "season",
  "season": 3
}
```

---

## 3.8. Logs de Territorio
Generados por:

- expansión  
- dominancia  
- zonas activas  

Ejemplo:

```json
{
  "type": "territory",
  "zone": "norte",
  "dominance": 14
}
```

---

## 3.9. Logs de Anomalías
Generados por:

- actividad inusual  
- ráfagas  
- errores rituales  
- patrones inesperados  

Ejemplo:

```json
{
  "type": "anomaly",
  "description": "burst of 200 gestures in 10 seconds"
}
```

---

# 4. Flujo de un Log

```
Evento → Clasificación → Registro → Memoria → Visualización
```

### 4.1. Entrada
El sistema recibe:

- gestos  
- puntos  
- energía  
- semillas  
- rituales  
- ciclos  
- temporadas  
- territorio  
- anomalías  

### 4.2. Clasificación
El sistema determina el tipo de log.

### 4.3. Registro
Se inserta en:

```
models/Log.ts
```

### 4.4. Memoria
Los logs alimentan la memoria viva.

### 4.5. Visualización
Los logs pueden aparecer en:

- DevWeb3  
- OTT  
- paneles narrativos  

---

# 5. Relación con Otros Órganos

### 5.1. Con Memoria
Los logs son la base de la memoria viva.

### 5.2. Con Energía
Los logs energéticos permiten depurar picos y caídas.

### 5.3. Con Territorio
Los logs territoriales permiten ver expansión y dominancia.

### 5.4. Con Avatar
Los logs personales alimentan narrativa individual.

### 5.5. Con Temporadas
Los logs marcan transiciones de temporada.

### 5.6. Con Rituales
Los logs rituales son esenciales para narrativa profunda.

---

# 6. Ejemplo de Log Completo

```json
{
  "type": "gesture",
  "wallet": "0xabc...",
  "gesture": "pulso_vocal",
  "timestamp": 1700000000,
  "metadata": {
    "pointsAdded": 3,
    "energyGenerated": 3
  }
}
```

---

# 7. Cómo Extender el Sistema de Logs

1. Añadir tipos en:
   ```
   types/Log.ts
   ```
2. Añadir lógica en:
   ```
   lib/logs/
   ```
3. Añadir UI en:
   ```
   app/devweb3/logs/
   ```
4. Actualizar documentación si aplica.

---

# 8. Roadmap del Sistema de Logs

- logs combinatorios  
- logs por avatar  
- logs territoriales avanzados  
- logs visualizados en OTT  
- logs narrativos profundos  
- logs por temporada  
- logs rituales avanzados  

---

# 9. Licencia
Proyecto interno.  
Acceso restringido a desarrolladores autorizados.