# Guia tecnica para desarrolladores y agentes

Este documento es el mapa tecnico vivo del repositorio. Actualizalo cuando cambien arquitectura, comandos, variables, builds, despliegue, datos, integraciones o debugging.

## Arquitectura

- GZ-Util es un sitio publico de utilidades web servido desde `www/`.
- La mayoria de herramientas son cliente puro con HTML, CSS y JavaScript estatico.
- Algunas herramientas delegan procesamiento pesado en APIs independientes:
  - `www/herramientas/pdf_imagen/api/`: FastAPI + PyMuPDF para convertir PDFs a imagenes y entregar un ZIP.
  - `www/herramientas/text_comparator/api/`: Express + `diff` para comparar textos.
- El sitio principal se publica por FTP desde GitHub Actions al hacer push a `main`.
- Las APIs incluyen `railway.json`, por lo que se despliegan como servicios separados en Railway.

## Estructura

- `.github/workflows/ftp-deploy.yml`: sincroniza el repo al servidor FTP remoto en `/gzutil/`.
- `docs/by-os/`: guias operativas por plataforma.
- `www/index.html`: landing/listado principal de herramientas.
- `www/styles.css`, `www/css/main.css`, `www/js/common.js`: estilos y comportamiento compartidos.
- `www/herramientas/`: herramientas publicas.
- `www/herramientas/codigos_postales_madrid/`: cliente estatico para clasificar CSV/Excel por municipio de la Comunidad de Madrid a partir de codigos postales.
- `www/herramientas/pdf_imagen/`: cliente de conversion PDF a imagen.
- `www/herramientas/pdf_imagen/api/`: backend Python/FastAPI de conversion.
- `www/herramientas/text_comparator/`: cliente de comparacion de textos.
- `www/herramientas/text_comparator/api/`: backend Node/Express de comparacion.
- `www/lib/`: librerias frontend vendorizadas.
- `www/recursos/`: imagenes, iconos, PDFs y otros recursos publicos.

## Configuracion y variables

- GitHub Actions requiere secretos `FTP_SERVER`, `FTP_USERNAME` y `FTP_PASSWORD` para publicar por FTP. No guardes sus valores en el repo.
- `pdf_imagen/api` usa `PORT` en Railway o puerto `8000` por defecto.
- `text_comparator/api` usa `PORT` en Railway o puerto `3000` por defecto.
- Los clientes de `pdf_imagen` y `text_comparator` usan localhost en desarrollo y URLs Railway en produccion, definidas en sus respectivos `script.js`.

## Desarrollo local

Sitio estatico:

```bash
cd www
python3 -m http.server 8080
```

API PDF a imagen:

```bash
cd www/herramientas/pdf_imagen/api
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -r requirements.txt
uvicorn main:app --reload --host 127.0.0.1 --port 8000
```

API comparador de textos:

```bash
cd www/herramientas/text_comparator/api
npm install
npm run dev
```

## Comprobaciones

Smoke del sitio estatico:

```bash
cd www
python3 -m http.server 8080
```

Abrir `http://127.0.0.1:8080/` y la herramienta afectada.

Smoke de `codigos_postales_madrid`:

```bash
cd www
python3 -m http.server 8080
```

Abrir `http://127.0.0.1:8080/herramientas/codigos_postales_madrid/`, subir un CSV o Excel con una columna de codigos postales y verificar deteccion, clasificacion y descarga CSV/XLSX.

Datos de referencia de `codigos_postales_madrid`:

- `www/herramientas/codigos_postales_madrid/data.js` contiene la tabla estatica de codigos postales asociados a municipios con codigo INE de provincia `28`.
- Fuente procesada: `ds-codigos-postales-ine-es`, derivada del Callejero del Censo Electoral del INE.
- Si se actualiza la fuente, regenerar el archivo filtrando `municipio_id` por prefijo `28` y volver a validar codigos ambiguos.

Smoke de `pdf_imagen/api`:

```bash
curl http://127.0.0.1:8000/health
```

Smoke de `text_comparator/api`:

```bash
curl http://127.0.0.1:3000/health
curl -s http://127.0.0.1:3000/api/compare \
  -H 'Content-Type: application/json' \
  -d '{"original":"hola","modified":"hola mundo","mode":"word"}'
```

No hay comandos globales de lint/test en la raiz en este momento. Usa comprobaciones locales acordes a la superficie tocada.

## Deploy y releases

- Publicacion del sitio: push a `main` dispara `.github/workflows/ftp-deploy.yml` y sincroniza el repo por FTP.
- Directorio remoto configurado en workflow: `/gzutil/`.
- APIs: desplegar desde su carpeta de API correspondiente en Railway segun `railway.json`.
- Para `pdf_imagen/api`, conservar el contexto de build que incluya `Dockerfile`, `requirements.txt` y `main.py`.
- Para `text_comparator/api`, Railway usa Nixpacks y `node server.js`.
- Registrar cambios de deploy o publicacion en `docs/RELEASE_LOG.md`.

## Pasos externos

- Usar `docs/MANUAL_STEPS.md` para secretos, dashboards, FTP, Railway, dominios o acciones que no se puedan completar solo con cambios de codigo.

## Troubleshooting

- Sintoma: el frontend llama a produccion aunque se esta probando localmente.
  - Verificacion: revisar `window.location.hostname` y `window.location.protocol` en el navegador.
  - Solucion: servir desde `localhost` o `file:` para activar la URL local definida en `script.js`.
- Sintoma: fallo de deploy FTP en GitHub Actions.
  - Verificacion: revisar el job `Deploy to FTP` y la presencia de secretos `FTP_SERVER`, `FTP_USERNAME`, `FTP_PASSWORD`.
  - Solucion: actualizar secretos desde GitHub sin imprimir valores.
- Sintoma: `pdf_imagen` no devuelve descarga.
  - Verificacion: comprobar `/health`, crear tarea en `/api/task`, consultar estado y revisar logs de Railway.
  - Solucion: validar dependencias de `requirements.txt`, memoria del servicio y compatibilidad de PyMuPDF.

## Documentacion progresiva

- Promover aprendizajes estables desde notas o chats a este documento.
- Corregir secciones obsoletas cuando una tarea cambie el comportamiento real.
- Mantener `AGENTS.md` como reglas operativas y esta guia como mapa tecnico.