# CONTRIBUTING.md — Guía de Contribución para 4GatosCoin & DevWeb3

Gracias por tu interés en contribuir al ecosistema 4GatosCoin.  
Este documento explica las reglas, estándares y procesos para colaborar de manera segura, consistente y alineada con la arquitectura viva del organismo.

Este proyecto es **interno y privado**.  
Solo desarrolladores autorizados pueden contribuir.

---

# 1. Principios Fundamentales

Toda contribución debe respetar:

### **1.1. Modularidad**
Cada órgano del organismo es independiente y debe mantenerse aislado:

- No mezclar lógica entre órganos.
- No duplicar funciones.
- No crear dependencias circulares.

### **1.2. Seguridad**
- Ningún endpoint debe exponer datos sensibles.
- Ninguna operación crítica debe ejecutarse desde el frontend.
- Todas las wallets deben normalizarse.
- Todos los gestos deben validarse.

### **1.3. Consistencia**
- Seguir la estructura existente.
- Usar los mismos patrones de modelos, endpoints y paneles.
- Mantener el estilo de código.

### **1.4. Reversibilidad**
Cada cambio debe poder revertirse sin romper el organismo.

---

# 2. Flujo de Trabajo

## 2.1. Crear una rama nueva
Cada contribución debe hacerse en una rama independiente:

```
git checkout -b feature/<nombre>
```

Ejemplos:

```
feature/new-gesture
feature/fix-points-calculation
feature/add-seeds-panel
```

## 2.2. Commits claros
Usar mensajes de commit descriptivos:

```
feat: add new gesture type 'mirror'
fix: correct points calculation for pulso_vocal
refactor: extract seed generator into separate module
docs: update architecture diagram
```

## 2.3. Pull Request
Todo PR debe incluir:

- descripción clara del cambio  
- impacto en el organismo  
- archivos modificados  
- pruebas manuales realizadas  
- capturas del panel DevWeb3 si aplica  

---

# 3. Estructura del Proyecto

Toda contribución debe respetar la arquitectura existente:

```
app/
  api/            → Endpoints
  devweb3/        → Panel de ingeniería
models/           → Modelos Mongoose
types/            → Tipos TypeScript
lib/              → Conexión DB y utilidades
components/       → Componentes compartidos
```

---

# 4. Cómo Añadir un Nuevo Órgano

Para añadir un órgano nuevo:

### 4.1. Crear panel
```
app/devweb3/<organo>/
```

### 4.2. Crear endpoints
```
app/api/<organo>/route.ts
```

### 4.3. Crear modelo
```
models/<Organo>.ts
```

### 4.4. Crear tipos
```
types/<Organo>.ts
```

### 4.5. Conectar con Organismo Global si es necesario

---

# 5. Cómo Añadir un Nuevo Endpoint

1. Crear carpeta:
   ```
   app/api/<endpoint>/
   ```
2. Añadir `route.ts` con GET/POST.
3. Importar:
   ```
   import dbConnect from "@/lib/models/dbConnect";
   ```
4. Usar modelos existentes.
5. Validar entrada.
6. Nunca exponer errores internos al cliente.

---

# 6. Cómo Añadir un Nuevo Gesto

1. Añadir tipo en:
   ```
   types/Gesture.ts
   ```
2. Actualizar validación en:
   ```
   app/api/gesture/route.ts
   ```
3. Añadir lógica en puntos si aplica.
4. Añadir UI en:
   ```
   app/devweb3/gestos/
   ```

---

# 7. Estilo de Código

### 7.1. TypeScript obligatorio
Todo archivo nuevo debe ser `.ts` o `.tsx`.

### 7.2. Reglas básicas
- No usar `any`.
- Usar `async/await`.
- Usar `try/catch` en endpoints.
- No dejar `console.log` en producción.
- Mantener funciones puras cuando sea posible.

### 7.3. Formato
El proyecto usa:

- **ESLint**
- **Prettier**

Ejecutar antes de hacer commit:

```
npm run lint
npm run format
```

---

# 8. Pruebas Manuales

Antes de enviar un PR:

### 8.1. Verificar panel DevWeb3
- El panel carga sin errores.
- El nuevo órgano aparece correctamente.
- Los endpoints responden.

### 8.2. Verificar API
Probar con `curl`, Postman o DevWeb3 Sandbox.

### 8.3. Verificar modelos
- Inserción correcta.
- Validación correcta.
- Sin duplicados inesperados.

---

# 9. Seguridad

### 9.1. Wallets
Siempre normalizar:

```
wallet.toLowerCase().trim()
```

### 9.2. Validación estricta
Nunca confiar en datos del cliente.

### 9.3. Operaciones críticas
Solo desde el servidor:

- puntos  
- energía  
- organismo global  
- semillas  
- logs  

### 9.4. No exponer stack traces
Usar respuestas genéricas:

```
return NextResponse.error();
```

---

# 10. Documentación

Cada contribución debe actualizar:

- `README.md` si afecta al uso general  
- `ARCHITECTURE.md` si afecta a la arquitectura  
- `README.es.md` si afecta a la documentación en español  

---

# 11. Roadmap de Contribución

Los colaboradores pueden trabajar en:

- nuevos gestos  
- nuevos órganos  
- mejoras del panel DevWeb3  
- optimización de endpoints  
- mejoras del Organismo Global  
- visualización OTT  
- memoria viva  
- temporadas  

---

# 12. Contacto Interno

Para dudas técnicas:

- Revisar panel DevWeb3  
- Revisar modelos  
- Revisar endpoints  
- Consultar al arquitecto del organismo  

---

# 13. Licencia

Proyecto interno.  
No es open-source.  
Acceso restringido a desarrolladores autorizados.