# Contrato HTTP del worker privado (v1)

Laravel implementa el cliente de este contrato. La API Python aún no existe en este proyecto. Mantener `BI_WORKER_ENABLED=false` hasta desplegar y verificar el worker por una red privada con HTTPS.

## Configuración

El servidor Laravel utiliza `BI_WORKER_URL`, `BI_WORKER_TOKEN` y `BI_WORKER_ENABLED`. La URL debe comenzar con `https://`; el token se envía solo como `Authorization: Bearer <token>` desde Laravel. Nunca se entrega al navegador ni se incluye en errores. El cliente usa 3 segundos para conectar y 10 segundos como tiempo máximo por petición. Los Jobs usan la conexión de cola `database`; se necesita un proceso `queue:work` independiente cuando se active la integración.

## Crear una ejecución completa

`POST /api/v1/sync-runs` con JSON:

```json
{
  "run_id": "9d301564-c7f8-4a04-bf02-9d2a3cb342e6",
  "connection": "iberofarmacos",
  "mode": "full",
  "tables": ["ventas_facturacion"]
}
```

`run_id` es el UUID generado y persistido por Laravel. `tables` contiene exclusivamente nombres de vistas de origen registradas en MySQL. El worker debe imponer unicidad duradera sobre `run_id`: repetir el mismo POST jamás debe iniciar otra importación física. Si el UUID ya existe, debe devolver el estado de esa misma ejecución.

Respuesta normal: HTTP `202 Accepted` con `{"run_id":"...","status":"queued"}`. Una repetición puede devolver HTTP `200` con un estado existente. La aceptación no confirma éxito.

## Consultar estado y resultado

`GET /api/v1/sync-runs/{run_id}` devuelve HTTP `200` y una instantánea. HTTP `404` significa que el worker no conoce ese UUID. El mismo endpoint contiene el progreso y el resultado final, por lo que no se requiere un segundo endpoint de resultados.

```json
{
  "run_id": "9d301564-c7f8-4a04-bf02-9d2a3cb342e6",
  "status": "running",
  "started_at": "2026-11-02T05:55:00Z",
  "tables": [
    {
      "name": "ventas_facturacion",
      "status": "running",
      "previous_rows": 100000,
      "rows_imported": 120000,
      "started_at": "2026-11-02T05:56:00Z"
    }
  ]
}
```

Estados: `pending`, `queued`, `running`, `completed`, `failed`; `cancelled` se admite únicamente si el worker confirma una cancelación real. No existe todavía una acción de cancelar en el panel. Las respuestas finales deben incluir todas las tablas seleccionadas. `completed` requiere que cada tabla tenga estado `completed` y `rows_imported` no negativo. Los campos opcionales por tabla son `backup_table`, `finished_at` y `error_message`. Fechas en UTC, formato ISO 8601. Laravel las presenta en `America/Santo_Domingo`.

## Fallos y reintentos

HTTP `401` y otras respuestas `4xx` diferentes de `404` no se reintentan automáticamente. HTTP `5xx` y timeouts se reintentan con backoff. Antes de cada POST, Laravel consulta el UUID. Si un POST termina en timeout o `5xx`, vuelve a consultar el mismo UUID antes de reintentar. El worker debe conservar el contrato idempotente aun cuando un GET temporal devuelva `404` después de que el primer POST haya comenzado.

Si Laravel no puede confirmar el estado tras agotar los intentos, conserva la ejecución en `pending`, `queued` o `running` y registra un mensaje administrativo. Esto bloquea otra recarga de la misma conexión hasta reconciliar manualmente el UUID con el worker; evita lanzar una segunda importación física mientras el estado anterior sea incierto. Solo una respuesta terminal explícita del worker cambia el estado a `completed`, `failed` o `cancelled`.

El contenido de errores HTTP no se registra ni se muestra directamente. Laravel guarda mensajes administrativos seguros. Las respuestas con UUID distinto, tablas no seleccionadas, identificadores inválidos o resultados `completed` incompletos se rechazan.

## Activación futura

Antes de habilitarlo, desplegar y probar el worker privado, su autenticación, HTTPS, persistencia idempotente por UUID y el proceso de cola de Laravel. No se activa ningún scheduler en esta fase. El panel conserva el botón deshabilitado mientras `BI_WORKER_ENABLED=false`.
