# Metodologia de iteracion y redeploy del RAG

**Proyecto:** Workspace de tools IA para empresas  
**Modulo:** RAG  
**Ultima actualizacion:** 2026-04-06  
**Ultima modificacion por:** Agente tools IA para potenciar servicios empresariales  
**Estado:** Activa

---

## Proposito

Dejar explicado de forma explicita el flujo de trabajo que se esta siguiendo para:

- implementar mejoras del RAG
- validarlas localmente
- subir solo los cambios adecuados al repo propio
- avisar al usuario cuando ya solo queda hacer `Deploy` en EasyPanel

La idea es que futuros agentes o nuevas sesiones no tengan que redescubrir este proceso.

---

## Principio general

El flujo correcto que ya esta funcionando bien es este:

1. implementar cambios en local
2. validar localmente antes de tocar produccion
3. documentar lo relevante
4. hacer commit y push solo de lo que debe versionarse
5. avisar al usuario de que ya puede hacer `Deploy` en EasyPanel
6. probar el resultado desplegado en produccion

---

## Flujo operativo paso a paso

### 1. Implementacion local

Los cambios se hacen en el workspace local, dentro del modulo:

```text
RAG/
```

Esto incluye:
- backend
- playground
- documentacion del modulo

---

### 2. Validacion local obligatoria

Antes de pedir redeploy, se valida en local.

Minimo esperado:

```bash
cd /home/pancho/Documentos/Empresa/Desarrollo/IA/RAG
npm run build
```

Y si aplica, pruebas HTTP locales contra:

- `/health`
- `/ingest`
- `/retrieve`
- `/answer`
- `/chat`
- endpoints de logs

No se debe pedir deploy al usuario sin haber comprobado antes que la mejora compila y que el flujo principal funciona en local.

---

### 3. Documentar antes de cerrar el bloque

Si el cambio introduce una mejora real o un comportamiento nuevo, hay que dejarlo reflejado en la documentacion adecuada.

Documentos tipicos a revisar:

- `RAG/docs/API_RAG.md`
- `RAG/docs/PLAYGROUND.md`
- `RAG/docs/LOGS_EVALUACION.md`
- `RAG/docs/DESPLIEGUE_EASYPANEL.md`
- `docs/HISTORIAL_SESIONES.md`

Objetivo:
- que otros agentes entiendan el cambio sin tener que inferirlo del codigo

---

### 4. Separar versionable de sensible

Antes de commitear, revisar que no entren en Git cambios sensibles o aun no cerrados.

No subir:
- `.env.local`
- `.env.easypanel.local`
- accesos o secretos
- respaldos locales

Solo subir:
- codigo
- docs sin secretos
- cambios de UX/API realmente listos para produccion

---

### 5. Commit y push

El commit se hace en el repo local del workspace y luego se sube al repo propio en Forgejo.

Remote actual:

```text
ssh://git@git.por-correo.com:2222/paco/rag-service.git
```

Regla importante:
- usar solo la configuracion local del repo
- no tocar `git config --global`

---

### 6. Aviso al usuario

Cuando los cambios ya estan:

- implementados
- validados en local
- documentados
- subidos al repo

entonces se avisa al usuario con un mensaje claro de este tipo:

- ya esta subido
- commit: `<hash>`
- ya puedes darle a `Deploy` en EasyPanel

La idea es que el usuario no tenga que adivinar si falta algo mas.

---

### 7. Redeploy en EasyPanel

El usuario hace `Deploy` en EasyPanel para que el servicio:

- coja el ultimo commit del repo
- reconstruya desde `Dockerfile`
- redepliegue la app

No hace falta reconstruir a mano en el VPS como se hizo antiguamente con `webfetch`.

---

### 8. Validacion en produccion

Tras el deploy, hay que probar el dominio publico:

```text
https://rag.por-correo.com
```

Probar segun aplique:

- `health`
- funcionamiento del playground
- consultas documentales
- consultas de codigo
- logs
- uploads
- bootstrap
- chat

---

## Criterio de corte

Un agente no deberia decir "haz deploy" si no se cumplen estas condiciones:

- compila en local
- el flujo nuevo ha sido probado localmente
- la documentacion minima esta actualizada
- el commit y push ya estan hechos
- no se han subido secretos por error

---

## Resultado esperado de esta metodologia

Aplicando siempre este flujo se consigue:

- menos redeploys innecesarios
- menos pruebas rotas en produccion
- mejor continuidad entre agentes
- cambios mas explicables y revisables
- una forma estable de trabajar que ya ha demostrado funcionar bien en este workspace