Eventos de Reporter

Referencia de los CloudEvents que emite Lerian Reporter: las 17 definiciones de evento, sus contratos de payload y versiones de schema, la entrega por el Streaming Hub y las políticas de entrega.

Reporter tiene 17 definiciones de eventos de negocio emitidos. Son mensajes CloudEvents 1.0 en modo binario. Recibes todos los eventos por una suscripción del Streaming Hub. Reporter no publica ningún evento de negocio en RabbitMQ, que lleva solo su cola interna de informes. 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
Suscripción del Hub	Define origin como reporter y toma las claves de evento del catálogo, por ejemplo report.finished
Tipo de contenido	application/json
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; default en el modo de un solo tenant
Manifest	GET /v1/streaming/manifest

Usa el envelope compartido para el contrato completo de encabezados de CloudEvents. Estos encabezados ce-* describen lo que Reporter publica. El Hub reentrega cada evento con encabezados propios; consulta consumir eventos.

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.

• Reporter persiste todo evento en el outbox duradero para su despacho y reintento. Nunca publica directamente.
• La entrega del broker es al menos una vez. Los consumidores deben ser idempotentes y deduplicar según el id de evento del Hub (X-Lerian-Event-Id en webhook, ceId en pull).

Catálogo de eventos emitidos

Clave de definición	Emitido por	Política	Schema	Se dispara cuando
template.created	Manager	Crítica	1.0.0	Se persisten el archivo y los metadatos de la plantilla.
template.updated	Manager	Crítica	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	Crítica	1.0.0	Se completa la eliminación de una plantilla; el rollback de creación no lo emite.
report.requested	Manager	Crítica	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	Crítica	1.0.0	Se persiste un plazo.
deadline.updated	Manager	Crítica	1.0.0	Se persiste la actualización de un plazo y se carga el registro actualizado.
deadline.deleted	Manager	Crítica	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. Los consumidores leen el ce-id del evento y nunca lo reconstruyen. Los ids UUIDv7 de abajo empiezan en Reporter 4.10.0; las versiones anteriores emiten un identificador aleatorio en los eventos de plantilla, en report.requested y en los eventos de creación, actualización y eliminación de plazos, y reporter.report.<status>.<report_id> y <report_id>:draft:<n>, y en los seis eventos de plazo y regulatorios reporter.deadline.<event>.<deadline_id>.<time>, <report_id>:approved y <document_id>:<adopted_version>:<tenant_id>.

Evento	ce-id
template.created, template.deleted, deadline.created, deadline.deleted, report.requested	Un UUIDv7 derivado del evento y del id del sujeto: un id por sujeto y evento. Una reentrega del mismo hecho lo repite.
template.updated, deadline.updated	Un UUIDv7 derivado del id del sujeto y del instante escrito como updated_at, al milisegundo. Una actualización posterior es un evento nuevo. Una reentrega del mismo hecho lo repite.
report.finished, report.partial	Un UUIDv7 derivado del id del informe y del estado (finished o partial). Una reentrega del mismo hecho lo repite.
report.errored	Un UUIDv7 derivado del id del informe y del estado error. Una reentrega del mismo hecho lo repite.
deadline.delivered	Un UUIDv7 derivado del id del plazo y del instante del cambio escrito por la solicitud, al milisegundo. Una reentrega del mismo hecho lo repite.
deadline.delivery_reverted	Un UUIDv7 derivado del id del plazo y del instante del cambio escrito por la solicitud, al milisegundo. Una reentrega del mismo hecho lo repite.
deadline.due	Un UUIDv7 derivado del id del plazo y de occurrence_at. Una reentrega del mismo hecho lo repite.
deadline.generation_failed	Un UUIDv7 derivado del id del plazo y de occurrence_at. Una reentrega del mismo hecho lo repite.
regulatory.draft_ready	Un UUIDv7 derivado del id del informe y de la versión del borrador. Una reentrega del mismo hecho lo repite.
regulatory.filing_approved	Un UUIDv7 derivado del id del informe y del estado approved. Una reentrega del mismo hecho lo repite.
regulatory.version_adopted	Un UUIDv7 derivado del id del documento, la versión adoptada, el id del tenant y el instante de la adopción, al milisegundo. Una reentrega del mismo hecho lo repite.

Todas las variantes de report.errored usan el mismo ce-id. Por eso, un consumidor que deduplica según el id del evento conserva solo el primer report.errored recibido para un report_id.

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.