Google Cloud Pub/Sub

7.1 Topics propuestos

Topic	Uso
nexus.purchase-order.requested	Eventos de solicitudes validadas para creación en ERP. Publisher principal.
nexus.purchase-order.retry	Eventos reprocesables tras error temporal (alternativa: re-delivery en subscription requested).
nexus.purchase-order.dlq	Dead Letter Queue; después de máximos reintentos o errores NO_RETRYABLE.

Recomendación de diseño

Implementar solo 2 topics en MVP: requested y dlq. Los reintentos pueden manejarse con la retry policy de la subscription de requested, en vez de topic de retry adicional (simplifica mantenimiento y monitoreo). Si en el futuro aparecen necesidades de routing complejo, agregar retry topic.

7.2 Envelope estándar (por evento)

{
  "eventId": "1f0c2f04-8243-4c52-9191-5e77c3b0f1e0",
  "requestId": "bcd5f9a7-4ced-4d25-bf3f-6ae762f05b41",
  "eventType": "PURCHASE_ORDER_REQUESTED",
  "partnerId": "GEPP",
  "companyId": "ALPURA_MX",
  "sourceSystem": "GEPP_ERP",
  "timestamp": "2026-08-12T18:00:00.123Z",
  "version": "1.0",
  "attempt": 1,
  "idempotencyKey": "abc...",
  "externalReference": "PO-123456",
  "payload": {
    "purchaseOrder": { "header": {...}, "lines": [...] },
    "validationChecksum": "sha256..."
  }
}

• eventType values: PURCHASE_ORDER_REQUESTED, PURCHASE_ORDER_RETRY, PURCHASE_ORDER_FAILED, PURCHASE_ORDER_CREATED (audit).

7.3 Subscription principal (consolidado)

Subscription	Enlazada a	Consumer
sub-nexus-po-requested-erp-workers	nexus.purchase-order.requested	Nexus Oracle Fusion PO Worker (HPA por backlog)

7.3.1 Propiedades recomendadas

Propiedad	Valor TBD	Nota
Ack deadline	60s TBD	Ajustar a p99 de Fusion + safety margin
Retention message	7 días (default)	Ajustar por SLA
Retry policy (subscription)	min backoff: 10s, max backoff: 10min. TBD	Acotado.
Dead Letter Policy	topic nexus.purchase-order.dlq, max delivery attempts: TBD 5-15	Acotado.
Ordering key	NO por defecto	Usar ordering solo si requieren orden absoluto por partnerId en un use case estricto; en MVP: sin ordering, mejor throughput.
Filter attributes	NO en MVP	Usar en fases posteriores si hay múltiples workers por ERP
Exactly Once Delivery (Pub/Sub)	Evaluar TBD	Con processed_event table y idempotent consumer, no es crítico.

7.4 Atributos Pub/Sub (para tracing y filter)

Attribute	Propósito
requestId	Depuración y logs
partnerId	Métricas y filtros
eventType	Ruteo futuro
attempt	Retry policy y alertas
traceparent	W3C Trace Context (propagación OTEL)
tracestate	Complementario

Cardinalidad en métricas

Exportar métricas Pub/Sub por subscription_id + partnerId si es requerido; no por requestId/eventId (riesgo cardinalidad).

7.5 Publisher (Outbox Publisher)

• Usa Spring Cloud GCP PubSubTemplate con batching configurable TBD.
• Reintentos al publicar: Resilience4j Retry + exponential backoff.
• Fallas: mantener outbox_event en PENDING; alerta tras TBD N minutos de lag.

7.6 Consumer (Worker Fusion)

• @Acknowledge(Mode.MANUAL): ack después de actualizar estado + processed_event insert en una sola transacción DB.
• Nack con delay si TEMPORARY_ERROR → reintento por Pub/Sub subscription retry policy o enviar a retry topic; en NO_RETRYABLE → a DLQ + actualiza estado FAILED + integration_error.
• Bulk processing: opcional; MVP por mensaje.
• HPA: por metric pubsub.googleapis.com/subscription/num_undelivered_messages.