puerto 0.23.0

Puerto — Rust full-stack DDD framework CLI. Scaffolds Clean Architecture projects with auto-wired DI, SQLx support, and zero manual wiring. Formerly puerto-framework.
# Worker — notas para agentes de IA

El segundo proceso de este proyecto (ADR-0018 de Puerto). Las unidades de trabajo de la API
escriben cada evento en la tabla `outbox`, en la misma transacción que la entidad; este proceso
**hace de relay** del outbox al transporte y **ejecuta los consumidores**. Es una raíz de
composición, como `presentacion/api`: aquí no vive lógica de negocio; un consumidor decodifica el
evento y llama a un caso de uso.

## Estructura

```
presentacion/worker/src/
├── main.rs                  # `ConfigWorker::from_env()` + `Worker::new(config).intentar_ejecutar(…)` (no cambia nunca)
├── generado.rs              # `pub mod registro;`
├── generado/registro.rs     # GENERADO: el relay y cada `[[consumidor]]`; no lo edites a mano
├── consumidores.rs          # `pub mod <consumidor>;`, sin `mod.rs`
└── consumidores/
    └── <consumidor>.rs      # Tuyo: un `ManejadorEvento`, lo escribe una vez `puerto generar consumidor`
```

## Reglas críticas

- **Añade un consumidor con `puerto generar consumidor <nombre> --tras <tipo_evento>[,…]`**:
  declara `[[consumidor]]` en `puerto.toml`, escribe el handler y sus tests, y regenera
  `generado/registro.rs`. No cablees nunca uno a mano.
- **Los handlers deben ser idempotentes.** La entrega es al menos una vez: el mismo `evento.id`
  puede llegar dos veces. Comprueba si el trabajo ya se hizo (por `evento.id`) antes de volver a
  hacerlo.
- **Responde con honestidad**: `Ack` cuando termina; `Reintentar` para un fallo que puede pasar (se
  vuelve a entregar con una espera creciente de 1 s → 300 s, `MAX_DELIVERIES` veces);
  `ResultadoManejo::descartar(motivo, detalle)` para uno que no pasará nunca. Un payload que no se
  decodifica es `MOTIVO_PAYLOAD_INVALIDO`. Nada se tira sin una fila en `descartados`
  (`make eventos/descartados`).
- **Lo que necesita un consumidor se construye en su `construir(pool)`**, que `generado/registro.rs`
  llama al arrancar: guárdalo en un campo del struct (`cableado::<contexto>::construir(pool)` da los
  casos de uso de un contexto, como `Arc<dyn …>`; añade `cableado = { workspace = true }` a
  `presentacion/worker/Cargo.toml` la primera vez). Sus tests construyen el struct con dobles
  (`dobles::Mock<Caso>`), sin base de datos.
- **Decodifica el snapshot, nunca el modelo de dominio**:
  `evento.decodificar::<SnapshotProducto>()`. El snapshot es el contrato público del evento.

{% if kafka -%}
## Transporte Kafka

- El relay publica cada evento en el topic de su agregado, `<KAFKA_TOPIC_PREFIX>.<agregado>`, con
  el id del agregado como clave: los eventos de un agregado se consumen en el orden en que
  ocurrieron.
- Un consumidor es el grupo de consumidores `<KAFKA_TOPIC_PREFIX>.<consumidor>`. Su offset se
  confirma cuando el resultado está resuelto. Un `Reintentar` retiene los registros que vienen
  detrás en su partición hasta que se confirma o se descarta; tras un reinicio, sus intentos vuelven
  a empezar.
- `make docker-compose/up` arranca Redpanda junto a Postgres; los topics se crean cuando arranca el
  worker. Los descartados se quedan en Postgres.

{% endif -%}
## Salud y apagado

Lo sirve el runtime de Puerto, `puerto-eventos`, en `WORKER_PORT` (8081).

- `GET /health`: vida; el proceso responde.
- `GET /health/ready`: disponibilidad; `503` hasta que el relay y cada consumidor terminan una
  pasada sin fallos recientes (una base de datos caída se ve aquí).
- Con SIGTERM / Ctrl-C cada bucle termina el lote que está procesando, durante 8 s como mucho.

## Configuración

`WORKER_PORT` (8081), `RELAY_BATCH_SIZE` (100), `RELAY_POLL_INTERVAL_MS` (500),
`CONSUMER_POLL_INTERVAL_MS` (500), `MAX_DELIVERIES` (5), `RETRY_MAX_DELAY_MS` (sin valor: la espera
creciente de arriba), además de `DATABASE_URL`. Un valor presente pero inválido detiene el worker
en el arranque.{% if kafka %}
Kafka: `KAFKA_BROKERS` (`localhost:9092`) y `KAFKA_TOPIC_PREFIX` (el nombre del proyecto).{% endif %}