# POINTS_SYSTEM.md — Sistema de Puntos del Organismo 4GatosCoin

El **Sistema de Puntos** es el motor cuantitativo del organismo 4GatosCoin.  
Convierte gestos en progreso, energía, narrativa y evolución del avatar.

Este documento describe cómo funcionan los puntos, cómo se calculan, cómo se almacenan y cómo afectan al organismo.

---

# 1. ¿Qué son los Puntos?

Los puntos representan:

- la actividad individual  
- la intensidad ritual del usuario  
- el impacto de sus gestos  
- su contribución al organismo  
- su evolución personal  

Los puntos son **individuales**, pero afectan al organismo de forma colectiva.

---

# 2. Componentes Técnicos

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

```
models/Points.ts
```

Campos típicos:

```json
{
  "wallet": "0x123...",
  "points": 42,
  "lastUpdated": 1700000000
}
```

### 2.2. Endpoints relacionados

```
GET  /api/points
POST /api/points/update
```

### 2.3. Panel DevWeb3
Ubicación:

```
app/devweb3/points/
```

Funciones:

- ver puntos por wallet  
- ver reglas activas  
- ver impacto de gestos  
- ver multiplicadores  

---

# 3. Flujo del Sistema de Puntos

```
Gesto → Validación → Cálculo → Actualización → Energía → Avatar → Organismo
```

### 3.1. Entrada
El sistema recibe:

- wallet  
- tipo de gesto  
- racha  
- temporada  
- multiplicadores  

### 3.2. Cálculo
El sistema calcula:

- puntos base  
- multiplicadores  
- bonus  
- penalizaciones  
- límites  

### 3.3. Salida
Los puntos afectan:

- energía personal  
- energía global  
- nivel del avatar  
- memoria  
- ciclos  
- territorio  

---

# 4. Puntos Base por Gesto

Ejemplo de configuración:

| Gesto           | Puntos |
|-----------------|--------|
| pulso_vocal     | 3      |
| pause           | 0      |
| walletConnect   | 5      |
| clauseTrigger   | 10     |
| dropPlay        | 2      |
| reflection      | 1      |
| mirror          | 4      |
| loop            | 1      |

Estos valores pueden cambiar por temporada.

---

# 5. Multiplicadores

Los multiplicadores modifican los puntos base.

### 5.1. Por racha
Ejemplo:

```
racha 3 días → x1.1
racha 7 días → x1.3
racha 14 días → x1.5
```

### 5.2. Por temporada
Ejemplo:

```
Temporada 3 — Eco Expansivo → x1.5
```

### 5.3. Por ritual
Ejemplo:

```
Durante El Grito Que Crea → x2
```

### 5.4. Por avatar
Ejemplo:

```
Nivel 5 → x1.2
Nivel 10 → x1.5
```

---

# 6. Bonus y Penalizaciones

### 6.1. Bonus
- primer gesto del día  
- completar racha  
- participar en ritual  
- alcanzar hito  

### 6.2. Penalizaciones
- spam de gestos  
- repetición excesiva  
- romper racha  

---

# 7. Límites del Sistema

### 7.1. Límites diarios
Ejemplo:

```
máximo 200 puntos por día
```

### 7.2. Límites por gesto
Ejemplo:

```
loop → máximo 20 veces por día
```

### 7.3. Límites por temporada
Ejemplo:

```
Temporada 4 → puntos reducidos para pulso_vocal
```

---

# 8. Relación con Otros Órganos

### 8.1. Con Energía
Los puntos generan energía personal y global.

### 8.2. Con Avatar
Los puntos alimentan niveles y narrativa personal.

### 8.3. Con Memoria
Los hitos de puntos generan memoria profunda.

### 8.4. Con Ciclos
Los puntos contribuyen a completar ciclos.

### 8.5. Con Territorio
La energía generada por puntos afecta zonas.

### 8.6. Con Temporadas
Las temporadas redefinen reglas de puntos.

---

# 9. Ejemplo de Cálculo Completo

### Gesto
```
pulso_vocal
```

### Puntos base
```
3
```

### Multiplicadores
- racha 7 días → x1.3  
- temporada 3 → x1.5  

### Cálculo
```
3 × 1.3 × 1.5 = 5.85 → 6 puntos
```

### Resultado
```json
{
  "wallet": "0xabc...",
  "pointsAdded": 6,
  "totalPoints": 88
}
```

---

# 10. Cómo Extender el Sistema de Puntos

1. Añadir reglas en:
   ```
   app/api/points
   ```
2. Añadir tipos en:
   ```
   types/Points.ts
   ```
3. Añadir UI en:
   ```
   app/devweb3/points/
   ```
4. Actualizar documentación si aplica.

---

# 11. Roadmap del Sistema de Puntos

- puntos combinatorios  
- puntos por avatar  
- puntos por zona  
- puntos por temporada  
- puntos rituales avanzados  
- puntos narrativos  

---

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