# MIGRATION_GUIDE.md — Guía de Migraciones del Organismo 4GatosCoin

Esta guía explica cómo evolucionar el organismo 4GatosCoin sin romper órganos, sin desincronizar el estado global y sin afectar la narrativa o la experiencia de los usuarios.

Es el manual oficial para realizar cambios profundos, estructurales o evolutivos.

---

# 1. Principios de Migración

Toda migración debe seguir estos principios:

- **Compatibilidad hacia atrás**: nunca romper datos existentes.  
- **Evolución incremental**: migrar en pasos pequeños.  
- **Sincronización total**: actualizar todos los órganos afectados.  
- **Narrativa coherente**: toda migración debe tener sentido simbólico.  
- **Logs obligatorios**: registrar cada paso.  
- **Sandbox-first**: probar migraciones en sandbox antes de producción.  

---

# 2. Tipos de Migraciones

| Tipo | Descripción |
|------|-------------|
| Migración de modelos | Cambios en schemas de MongoDB |
| Migración de endpoints | Cambios en rutas API |
| Migración de órganos | Cambios en lógica de un órgano |
| Migración de reglas | Cambios en temporadas, puntos, energía |
| Migración narrativa | Cambios en ecos, patrones, rituales |
| Migración global | Cambios en OrganismoGlobal |
| Migración de paneles | Cambios en DevWeb3 |
| Migración de OTT | Cambios en visualización |

---

# 3. Flujo de Migración

```
Diseño → Sandbox → Scripts → Validación → Staging → Producción
```

### 3.1. Diseño
- definir impacto  
- definir órganos afectados  
- definir narrativa afectada  
- definir riesgos  

### 3.2. Sandbox
- probar migración con datos falsos  
- validar sincronización  
- validar narrativa  

### 3.3. Scripts
Crear scripts en:

```
scripts/migrations/
```

Ejemplo:

```
2026-01-add-avatar-fields.ts
```

### 3.4. Validación
- tests unitarios  
- tests de integración  
- tests narrativos  
- tests territoriales  
- tests de estado global  

### 3.5. Staging
- migrar base de datos staging  
- validar paneles  
- validar OTT  
- validar logs  

### 3.6. Producción
- confirmar variables  
- confirmar conexión  
- ejecutar migración  
- verificar estado global  

---

# 4. Migración de Modelos

Pasos:

1. Crear nuevo schema en `models/`  
2. Crear script de migración  
3. Actualizar lógica en `lib/`  
4. Actualizar endpoints en `app/api/`  
5. Actualizar panel DevWeb3  
6. Actualizar documentación  
7. Ejecutar en sandbox  
8. Ejecutar en staging  
9. Ejecutar en producción  

---

# 5. Migración de Endpoints

Pasos:

1. Crear nueva versión del endpoint  
2. Mantener la versión antigua temporalmente  
3. Actualizar frontend  
4. Actualizar panel DevWeb3  
5. Actualizar documentación  
6. Deprecar endpoint antiguo  
7. Eliminar cuando no haya tráfico  

---

# 6. Migración de Órganos

Ejemplos:

- cambiar reglas de energía  
- cambiar niveles del avatar  
- cambiar rarezas de semillas  
- cambiar umbrales de ciclos  
- cambiar reglas de temporada  

Pasos:

1. Actualizar órgano en `lib/<organo>/`  
2. Actualizar estado global  
3. Actualizar narrativa  
4. Actualizar panel DevWeb3  
5. Actualizar tests  
6. Actualizar documentación  

---

# 7. Migración Narrativa

Pasos:

1. Actualizar patrones en `lib/narrative/patterns`  
2. Actualizar transformaciones  
3. Actualizar manifestaciones  
4. Actualizar MEMORY_SYSTEM.md  
5. Actualizar NARRATIVE_ENGINE.md  
6. Validar en sandbox  

---

# 8. Migración del Estado Global

Pasos:

1. Añadir campos en `OrganismoGlobal.ts`  
2. Actualizar `updateGlobalState.ts`  
3. Actualizar panel DevWeb3  
4. Actualizar OTT  
5. Actualizar documentación  
6. Validar sincronización  

---

# 9. Migración de Temporadas

Pasos:

1. Crear nueva temporada en `SEASONS.md`  
2. Actualizar reglas en `lib/temporadas/`  
3. Actualizar puntos, energía, narrativa  
4. Actualizar OTT  
5. Actualizar panel DevWeb3  
6. Validar en sandbox  

---

# 10. Migración de Territorio

Pasos:

1. Actualizar zonas  
2. Actualizar dominancia  
3. Actualizar energía por zona  
4. Actualizar narrativa territorial  
5. Actualizar OTT  
6. Validar en sandbox  

---

# 11. Migración de Rituales

Pasos:

1. Actualizar cláusulas  
2. Actualizar impacto energético  
3. Actualizar narrativa profunda  
4. Actualizar logs  
5. Actualizar OTT  
6. Validar en sandbox  

---

# 12. Checklist de Migración

- [ ] impacto definido  
- [ ] órganos afectados listados  
- [ ] narrativa actualizada  
- [ ] scripts creados  
- [ ] tests actualizados  
- [ ] sandbox validado  
- [ ] staging validado  
- [ ] documentación actualizada  
- [ ] producción confirmada  

---

# 13. Roadmap de Migraciones

- migraciones automáticas  
- migraciones narrativas generativas  
- migraciones territoriales dinámicas  
- migraciones de avatar visual  
- migraciones de temporadas vivas  

---

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