Eventos de Reporter

Reporter tiene 17 definiciones de eventos de negocio emitidos. Son mensajes CloudEvents 1.0 en modo binario. Todos los eventos viajan por RabbitMQ cuando STREAMING_ENABLED=true. Cuando STREAMING_KAFKA_BROKERS también está definido, worker publica report.finished y report.partial también en Kafka. Cuando el streaming está desactivado, Reporter no publica eventos.

Envelope y enrutamiento

Todos los eventos usan ce-source reporter y un ce-type calificado por fuente con la forma studio.lerian.reporter.<resource>.<event>. El payload es JSON con claves en snake_case.

Elemento del contrato	Valor
Exchange	Valor de `RABBITMQ_REPORT_EVENTS_EXCHANGE`
Routing key de AMQP	Exactamente la clave de definición, por ejemplo `report.finished`
Tema de Kafka	`lerian.streaming.reporter`, solo para `report.finished` y `report.partial`, cuando `STREAMING_KAFKA_BROKERS` está definido
Tipo de contenido	`application/json`
Modo de entrega	Mensaje AMQP persistente
Tipo de recurso	`template`, `report`, `deadline` o `regulatory`
Asunto	Id de plantilla, informe o plazo. En `regulatory.version_adopted`, el id del documento regulatorio
Tenant	Tenant de contexto en `ce-tenantid` y `X-Tenant-ID`; `default` en el modo de un solo tenant
Manifest	`GET /v1/streaming/events`

Ambas copias llevan el mismo ce-id. Usa el envelope compartido para el contrato completo de encabezados de CloudEvents.

Semántica de entrega

Reporter emite después de confirmar el cambio de estado de negocio. Los errores de publicación no hacen fallar la operación subyacente.

Importante: publicación directa, con fallback a un outbox duradero cuando el circuito del broker está abierto.
Crítica: Reporter omite la publicación directa. Siempre persiste el evento en el outbox duradero para su despacho y reintento.
Ambas políticas solicitan on_routable_failure, pero las rutas no definen un destino DLQ explícito. El publicador ve un fallo enrutable. Ninguna copia llega a una ruta dead-letter.
La entrega del broker es al menos una vez. Los consumidores deben ser idempotentes y deduplicar con (ce-source, ce-id).

Catálogo de eventos emitidos

Clave de definición	Emitido por	Política	Schema	Se dispara cuando
`template.created`	Manager	Importante	`1.0.0`	Se persisten el archivo y los metadatos de la plantilla.
`template.updated`	Manager	Importante	`1.0.0`	Se completan una actualización de la plantilla y cualquier reemplazo de archivo, o una asignación de familia de informes cambia la categoría de la plantilla.
`template.deleted`	Manager	Importante	`1.0.0`	Se completa la eliminación de una plantilla; el rollback de creación no lo emite.
`report.requested`	Manager	Importante	`1.0.0`	Un informe creado mediante `POST /v1/reports` o por el disparador de plazos se persiste como `Processing`, antes de que manager publique el comando del worker. No prueba que el comando se haya encolado. Una solicitud de presentación regulatoria no lo emite.
`report.finished`	Worker	Crítica	`2.0.0`	Se almacena el artefacto y se confirma el estado `Finished`.
`report.partial`	Worker	Crítica	`2.0.0`	Se almacena el artefacto y se confirma el estado `Partial`.
`report.errored`	Manager y worker	Crítica	`2.0.0`	Se confirma un estado `Error`: la ejecución del worker falló, manager no pudo encolar el comando de un informe creado mediante `POST /v1/reports` o por el disparador de plazos, o manager detectó que el worker dejó de enviar heartbeats.
`deadline.created`	Manager	Importante	`1.0.0`	Se persiste un plazo.
`deadline.updated`	Manager	Importante	`1.0.0`	Se persiste la actualización de un plazo y se carga el registro actualizado.
`deadline.deleted`	Manager	Importante	`1.0.0`	Se persiste la eliminación lógica de un plazo.
`deadline.delivered`	Manager	Crítica	`1.0.0`	Se persiste la marca de entrega.
`deadline.delivery_reverted`	Manager	Crítica	`1.0.0`	Se elimina la marca de entrega.
`deadline.due`	Manager	Crítica	`1.0.0`	El disparador de plazos anuncia una ocurrencia cuyo día llegó. Requiere `DEADLINE_TRIGGER_ENABLED=true`.
`deadline.generation_failed`	Manager	Crítica	`1.0.0`	El disparador anunció una ocurrencia, y el informe que debía generar para una categoría de `DEADLINE_TRIGGER_GENERATE_CATEGORIES` se rechazó o falló.
`regulatory.draft_ready`	Worker	Crítica	`1.0.0`	Un borrador regulatorio y su archivo están almacenados y listos para revisión. `template_id` es un string vacío cuando una suscripción generó el borrador.
`regulatory.filing_approved`	Manager	Crítica	`1.0.0`	Una persona aprobó un borrador regulatorio, y está en `Final`. Entrega la presentación a partir de este evento.
`regulatory.version_adopted`	Manager	Crítica	`1.0.0`	Una suscripción pasa a otra versión de su documento regulatorio. Adoptar la versión ya vigente no emite nada.

Una presentación regulatoria emite regulatory.draft_ready en lugar de report.finished. Una ejecución de presentación que falla emite report.errored.

Identificadores de eventos

Reporter define un ce-id determinista en estos eventos:

Evento	`ce-id`
`report.finished`, `report.partial`	`reporter.report.<status>.<report_id>`, con `finished` o `partial`
`report.errored`	`reporter.report.error.<report_id>`
`deadline.delivered`	`reporter.deadline.delivered.<deadline_id>.<delivered_at>`
`deadline.delivery_reverted`	`reporter.deadline.delivery_reverted.<deadline_id>.<reverted_at>`
`deadline.due`	`reporter.deadline.due.<deadline_id>.<occurrence_at>`
`deadline.generation_failed`	`reporter.deadline.generation_failed.<deadline_id>.<occurrence_at>`
`regulatory.draft_ready`	`<report_id>:draft:1`
`regulatory.filing_approved`	`<report_id>:approved`
`regulatory.version_adopted`	`<document_id>:<adopted_version>:<tenant_id>`

Todas las variantes de report.errored usan el mismo ce-id. Por eso, un consumidor que deduplica según (ce-source, ce-id) conserva solo el primer report.errored recibido para un report_id. Los eventos de plantilla, report.requested y los eventos de creación, actualización y eliminación de plazos llevan un identificador generado.

Contratos `data` completos

Estas declaraciones al estilo TypeScript reflejan la forma del JSON en el wire. ? indica que la propiedad es opcional. | null indica que la propiedad está presente pero puede ser null en JSON.

type RFC3339 = string
type UUID = string

type TemplateCreatedDataV1 = {
  template_id: UUID
  output_format: string
  description: string
  file_name: string
  category: string
  mapped_datasource_keys: string[]
  mapped_fields_count: number
  created_at: RFC3339
}

type TemplateUpdatedDataV1 = {
  template_id: UUID
  output_format: string
  description: string
  category: string
  updated_fields: string[]
  file_replaced: boolean
  updated_at: RFC3339
}

type TemplateDeletedDataV1 = {
  template_id: UUID
  hard_delete: boolean
  cascaded_deadlines_deleted: number
  deleted_at: RFC3339
}

type ReportRequestedDataV1 = {
  report_id: UUID
  template_id: UUID
  output_format: string
  status: string
  request_id: string
  filter_datasource_count: number
  template_description: string
}

type ReportFinishedDataV2 = {
  report_id: UUID
  template_id: UUID
  output_format: string
  status: string
  artifact_object_key: string
  artifact_content_type: string
  document_type: string
  artifact_ttl?: string
  completed_at: RFC3339
  duration_ms: number
  section_count: number
}

type ReportPartialDataV2 = {
  report_id: UUID
  template_id: UUID
  output_format: string
  status: string
  artifact_object_key: string
  artifact_content_type: string
  document_type: string
  section_failures: string[]
  completed_at: RFC3339
  duration_ms: number
  section_count: number
  failed_section_count: number
}

type ManagerReportErroredDataV2 = {
  report_id: UUID
  status: string
  error_code: "report_generation_failed" | "report_worker_lost"
  error_summary: string
  completed_at: RFC3339
}

type WorkerTerminalReportErroredDataV2 = {
  report_id: UUID
  template_id: UUID
  output_format: string
  status: string
  error_code: "report_generation_failed"
  error_summary: "All report data sections failed"
  document_type: string
  document_id: string
  document_version: string
  completed_at: RFC3339
  duration_ms?: number
}

type WorkerFunnelReportErroredDataV2 = {
  report_id: UUID
  status: string
  error_code:
    | "report_generation_failed"
    | "report_generation_timeout"
    | "report_generation_canceled"
  error_summary: string
  document_type: string
  document_id: string
  document_version: string
  completed_at: RFC3339
}

type ReportErroredDataV2 =
  | ManagerReportErroredDataV2
  | WorkerTerminalReportErroredDataV2
  | WorkerFunnelReportErroredDataV2

type DeadlineCreatedDataV1 = {
  deadline_id: UUID
  name: string
  type: string
  template_id: UUID | null
  template_name: string
  due_date: RFC3339
  frequency: string
  months_of_year: number[] | null
  active: boolean
  notify_days_before: number
  color: string
  status_snapshot: string
  created_at: RFC3339
}

type DeadlineUpdatedDataV1 = {
  deadline_id: UUID
  updated_fields: string[]
  template_id: UUID | null
  template_name: string
  due_date: RFC3339
  frequency: string
  months_of_year: number[] | null
  active: boolean
  status_snapshot: string
  updated_at: RFC3339
}

type DeadlineDeletedDataV1 = {
  deadline_id: UUID
  soft_delete: boolean
  deleted_at: RFC3339
}

type DeadlineDeliveredDataV1 = {
  deadline_id: UUID
  template_id: UUID | null
  template_name: string
  type: string
  due_date: RFC3339
  delivered_at: RFC3339 | null
  status_snapshot: string
  frequency: string
  next_occurrence: RFC3339 | null
  updated_at: RFC3339
}

type DeadlineDeliveryRevertedDataV1 = {
  deadline_id: UUID
  template_id: UUID | null
  template_name: string
  type: string
  due_date: RFC3339
  reverted_at: RFC3339
  previous_delivered_at: RFC3339 | null
  status_snapshot: string
  frequency: string
  updated_at: RFC3339
}

type DeadlineDueDataV1 = {
  deadline_id: UUID
  template_id: UUID | null
  type: string
  category?: string
  due_date: RFC3339
  frequency: string
  occurrence_at: RFC3339
}

type DeadlineGenerationFailedDataV1 = {
  deadline_id: UUID
  template_id: UUID | null
  category?: string
  occurrence_at: RFC3339
  retryable: boolean
  reason:
    | "business_refusal"
    | "budget_exceeded"
    | "sweep_cancelled"
    | "transient"
    | "unknown"
  error_summary: string
  failed_at: RFC3339
}

type RegulatoryDraftReadyDataV1 = {
  report_id: UUID
  document_id: string
  document_version: string
  template_id: string
  output_format: string
  draft_version: number
  required_gaps_count: number
  requested_by: string
  generated_at: RFC3339
}

type RegulatoryFilingApprovedDataV1 = {
  report_id: UUID
  document_id: string
  document_version: string
  template_id: string
  output_format: string
  artifact_object_key: string
  artifact_sha256: string
  artifact_size_bytes: number
  draft_version: number
  delivery_attempt: number
  parameters: Record<string, string>
  corrections_count: number
  corrected_by: string
  corrected_at: string
  approved_by: string
  approved_at: RFC3339
}

type RegulatoryVersionAdoptedDataV1 = {
  document_id: string
  previous_version: string
  adopted_version: string
  adopted_by: string
  adopted_at: RFC3339
  binding_gaps_count: number
  mapping_broken: boolean
}

document_type lleva la categoría de la plantilla. Contiene un string vacío en la variante de fallo del worker que no lleva template_id. Trata un valor vacío como ausencia de categoría. document_id y document_version en report.errored nombran el documento regulatorio cuando una suscripción generó el informe, y son strings vacíos en los demás casos. artifact_object_key en report.finished, report.partial y regulatory.filing_approved es la clave de almacenamiento del archivo exactamente como Reporter la escribió, y nunca está vacía. Úsala tal cual. No la reconstruyas a partir de otros campos. En regulatory.filing_approved, verifica el objeto almacenado contra artifact_sha256 antes de enviarlo. parameters lleva los parámetros de generación sin los que empiezan con system.. binding_gaps_count en regulatory.version_adopted cuenta los campos de la versión adoptada que el mapeo existente deja sin asignar. El campo mapping_broken es true cuando Reporter no pudo evaluar el mapeo existente contra la versión adoptada. En ese caso, binding_gaps_count es 0.

Riel interno de comandos separado

Manager envía a worker un comando JSON que no es CloudEvents por RabbitMQ. Usa RABBITMQ_EXCHANGE, RABBITMQ_GENERATE_REPORT_KEY y RABBITMQ_GENERATE_REPORT_QUEUE, con entrega persistente. Este comando no forma parte del catálogo público de eventos, y su forma no es un contrato público.

Estado de eventos entrantes

Reporter no consume ningún evento de negocio público. Su suscriptor de Hub no está disponible: habilitarlo se rechaza al iniciar.

Primeros pasos

API de Plantillas

API del Constructor de Plantillas

API de Informes

API de Plazos

API de Fuentes de Datos

API de Instituciones

API de Catálogo Regulatorio

API de Suscripciones Regulatorias

API de Mapeos Regulatorios

API de Informes Regulatorios

API de Métricas

API de Streaming

Manejo de errores

Eventos

Eventos de Reporter

Envelope y enrutamiento

Semántica de entrega

Catálogo de eventos emitidos

Identificadores de eventos

Contratos `data` completos

Riel interno de comandos separado

Estado de eventos entrantes

​Envelope y enrutamiento

​Semántica de entrega

​Catálogo de eventos emitidos

​Identificadores de eventos

​Contratos data completos

​Riel interno de comandos separado

​Estado de eventos entrantes

Envelope y enrutamiento

Semántica de entrega

Catálogo de eventos emitidos

Identificadores de eventos

Contratos `data` completos

Riel interno de comandos separado

Estado de eventos entrantes