Catalogo de Eventos de Dominio

Este documento define el lenguaje común de eventos para servicios, auditoría y analítica.

1. Contrato base de evento

{
  "event_id": "uuid",
  "event_name": "APPOINTMENT_CONFIRMED",
  "occurred_at": "2026-02-13T16:30:00Z",
  "trace_id": "uuid",
  "producer": "appointments-service",
  "schema_version": "1.0.0",
  "payload": {},
  "meta": {
    "country_code": "GT",
    "source": "api"
  }
}

2. Eventos canónicos por dominio

Event name	Productor	Consumidor(es)	Payload mínimo	PII	Idempotencia
REGISTER_STARTED	auth-service	audit, analytics	user_id, channel	Baja	event_id único
REGISTER_COMPLETED	auth-service	profile-service, analytics	user_id, roles	Media	event_id único
USER_LOGGED_IN	auth-service	audit, analytics	user_id, method	Media	event_id único
REFRESH_REUSE	auth-service	security, audit	user_id, session_id	Media	event_id único
PROFILE_VERIFIED	backoffice-service	profile-service, audit	user_id, decision	Media	event_id único
CAT_GEO_CREATED	catalog-service	search-service, audit	node_id, level	Baja	event_id único
CAT_SPECIALTY_CREATED	catalog-service	search-service, audit	specialty_id, area_id	Baja	event_id único
SEARCH_PERFORMED	search-service	analytics	query, filters, result_count	Baja	muestreo permitido
APPOINTMENT_CONFIRMED	appointments-service	notification-service, analytics	appointment_id, patient_id, doctor_id	Alta	appointment_id + estado
APPOINTMENT_CANCELLED	appointments-service	notification-service, analytics	appointment_id, reason	Media	appointment_id + estado
NOTIF_SENT	notification-service	audit, analytics	message_id, channel, status	Baja	message_id
NOTIF_FAILED	notification-service	ops, dlq-monitor	message_id, channel, error_code	Baja	message_id
REVIEW_SUBMITTED	review-service	moderation, analytics	review_id, target_id, rating	Baja	review_id
COUPON_CREATED	promotions-service	audit, analytics	coupon_id, owner_id	Baja	coupon_id
POST_PUBLISHED	content-service	search-service, analytics	post_id, author_id	Baja	post_id

3. Política de versionado de eventos

• Todo evento incluye schema_version.
• Cambios incompatibles de payload requieren nueva versión de esquema.
• Consumidores deben soportar al menos versión actual y versión anterior durante migración.

4. Entrega, retries y DLQ

Tipo de evento	Estrategia	Retries	DLQ
Crítico transaccional (APPOINTMENT_*, REFRESH_REUSE)	At-least-once + deduplicación por event_id	5	Sí
Operativo (NOTIF_*)	At-least-once	8	Sí
Analítico (SEARCH_PERFORMED)	At-most-once/muestreo	0-1	No

Reglas:

• dlq_depth > 0 por 5 min dispara alerta SEV2.
• Reprocesamiento de DLQ debe quedar auditado.
• Nunca incluir secretos/tokens en payload.

5. Checklist de adopción por servicio

• Producer emite evento con contrato base y schema_version.
• Consumer valida esquema y maneja versiones.
• Métricas de entrega/fallo expuestas (published, processed, failed, dlq_depth).
• Runbook incluye pasos de reproceso de DLQ.