# ZPL to PDF Microservice - Agent Orchestration

Este microservicio actúa como un sidecar local para el ecosistema GT:Sync / Pampero. Resuelve la incompatibilidad de versiones de Node.js en el backend principal (Next.js con Node 12), renderizando etiquetas ZPL a formato PDF de forma aislada y 100% offline utilizando un entorno gráfico simulado en memoria.

## Infraestructura y Ejecución

- **Puerto del servicio:** `3040`
- **Host:** `127.0.0.1` (Localhost)
- **Host remoto/LAN/ZeroTier:** usar `0.0.0.0` al levantar el proceso para escuchar en todas las interfaces.
- **Motor Node:** Binario aislado (v24.15.0) para no afectar el PATH global.
- **Core Stack:** `fastify` (Web Server), `zpl-js` (Parser), `canvas` (Render gráfico), `jspdf` (Exportación binaria).

## Control De Versiones

- **Repositorio oficial Gitea:** `https://gitea.globaltechscm.com/gt-microservices/zpl-pdf-microservice.git`
- Este microservicio usa Gitea, no Bonobo. Para este proyecto, configurar siempre `origin` contra el remoto Gitea anterior.
- No versionar `node_modules/`, `.cache/` ni el runtime local `node-v24.15.0/`. El runtime aislado se instala/restaura localmente en la ruta documentada abajo.

### Ruta Absoluta del Intérprete
Para ejecutar el servidor o instalar paquetes a través de PM2 o consola, se DEBE utilizar obligatoriamente la siguiente ruta absoluta:
`C:\Users\Dorado\Desktop\Pampero\Proyectos\zpl-pdf-microservice\node-v24.15.0\node.exe`

### Comandos de Gestión (Usar CMD/PowerShell)

**Levantar el servicio manualmente:**
```powershell
C:\Users\Dorado\Desktop\Pampero\Proyectos\zpl-pdf-microservice\node-v24.15.0\node.exe server.js
```

**Levantarlo para acceso desde LAN/ZeroTier:**
```powershell
C:\Users\Dorado\Desktop\Pampero\Proyectos\zpl-pdf-microservice\node-v24.15.0\node.exe server.js --host=0.0.0.0 --port=3040
```

El default sigue siendo `127.0.0.1:3040` para uso local. También se puede configurar con variables de entorno `HOST` y `PORT`.

## Parámetros de Render

El endpoint `POST /convert` acepta, además de `zpl`, los parámetros `width`, `height`, `dpi`, `sourceDpi`, `fontWidthScale`, `code128WidthScale` y `qrSizeScale`.

Para etiquetas Mercado Libre 4x6 con coordenadas Zebra a 203 DPI y PDF de salida a 300 DPI, usar como base:

```json
{
  "width": 4,
  "height": 6,
  "dpi": 300,
  "sourceDpi": 203,
  "fontWidthScale": 0.82,
  "code128WidthScale": 1.42,
  "qrSizeScale": 0.5
}
```

`code128WidthScale` ajusta el ancho visual de `^BC` porque `bwip-js` genera Code128 más angosto que Labelary/Zebra para algunas etiquetas ML con `^BY3`.
`qrSizeScale` ajusta el tamaño visual de `^BQ` porque `bwip-js` incluye una matriz QR más grande que la salida observada en etiquetas ML/Zebra para `^BQN`.