Resumen de la arquitectura
Resumen de la arquitectura de Matcher
Contextos delimitados
Matcher está dividido en módulos. Cada uno es dueño de sus datos y expone interfaces limpias a los demás.
- Configuración: qué concilias (contextos, fuentes, mapas de campos, reglas)
- Discovery: conexiones a fuentes de datos externas, detección de esquemas y orquestación de extracciones con el motor de extracción embebido de Matcher
- Ingesta: entrada de los datos (parseo, validación, normalización)
- Coincidencia: el motor (ejecución de reglas, puntuación de confianza)
- Excepción: manejo de los ítems no conciliados (workflow, asignación, resolución)
- Gobernanza: registros de auditoría (logs solo por adición para cumplimiento)
- Informes: visibilidad (informes, exportaciones, dashboards)
Configuración
Define qué concilias y cómo. Maneja:- Contextos (qué concilias)
- Fuentes (de dónde vienen los datos)
- Mapas de campos (traducción de los campos externos)
- Reglas (cómo hacer coincidir)
ReconciliationContext: el ámbito de la conciliaciónReconciliationSource: configuración de la fuenteFieldMap: reglas de traducción de camposMatchRule: lógica de coincidencia
Discovery
El contexto delimitado Discovery gestiona la conectividad con fuentes de datos externas, la detección de esquemas y la orquestación de extracciones con el motor de extracción. Discovery se ejecuta dentro de Matcher. Responsabilidades:- Gestionar las conexiones a fuentes de datos externas
- Detectar y cachear los esquemas de las fuentes
- Ejecutar extracciones en el mismo proceso y entregar los resultados directamente a Ingesta
- Seguir los ciclos de vida de las conexiones y de las extracciones
- Gestionar las conexiones a APIs REST y guardar el historial de esquema de cada conexión
ExtractionRequest: sigue el ciclo de vida de una extracción que ejecuta el motor embebido
Consulta Discovery para ver cómo Discovery se conecta a bases de datos externas con el motor de extracción.
Ingesta
El contexto delimitado Ingesta maneja la entrada y la normalización de los datos. Responsabilidades:- Parsear los archivos subidos
- Validar los datos entrantes contra los esquemas configurados
- Normalizar los datos externos a una representación canónica
- Detectar y manejar los registros duplicados
- Emitir eventos de dominio cuando termina la ingesta
IngestionJob: sigue el ciclo de vida y el estado de la ingestaTransaction: registro canónico normalizado de una transacción
ingestion.completed: indica que los datos están listos para la coincidencia
Coincidencia
El contexto delimitado Coincidencia contiene el motor de conciliación. Responsabilidades:- Cargar las reglas aplicables a un contexto de conciliación
- Ejecutar las estrategias de coincidencia (exacta, por tolerancia, difusa, por fecha)
- Calcular las puntuaciones de confianza
- Crear grupos de coincidencia y asignar transacciones
- Identificar las transacciones no conciliadas
MatchRun: ejecución de un trabajo de coincidenciaMatchGroup: grupo de transacciones conciliadasMatchItem: asignación individual de una transacción
match_group.confirmed: un grupo de coincidencia quedó finalizadomatch_group.unmatched: una coincidencia confirmada antes fue revertidatransaction.pending_review: un candidato no automático necesita revisión
Gestión de excepciones
El contexto delimitado Excepción gestiona las transacciones sin resolver. Responsabilidades:- Clasificar las excepciones por severidad
- Asignar las excepciones a tu equipo
- Admitir anulaciones, ajustes y disputas manuales
- Seguir el estado de resolución
- Recibir callbacks de resolución desde sistemas externos
Exception: una transacción sin resolver
Gobernanza
El contexto delimitado Gobernanza preserva la trazabilidad de la conciliación. Responsabilidades:- Registrar en logs de auditoría solo por adición los cambios de configuración y las resoluciones de excepciones
- Proveer un historial de auditoría consultable
- Admitir los informes regulatorios y de cumplimiento
AuditLog: registro solo por adición de los workflows de mutación auditables instrumentados
Informes
El contexto delimitado Informes provee visibilidad operativa. Responsabilidades:- Generar informes de conciliación
- Exponer métricas de dashboard
- Exportar los datos de conciliación en varios formatos
Report: resumen de la conciliaciónDashboard: métricas operativas agregadasExportJob: ejecución asíncrona de una exportación
Flujo de datos
La conciliación sigue un pipeline determinista a través de los contextos delimitados:
1
Configuración
Defines los contextos de conciliación, las fuentes, los mapeos de campos y las reglas a través de la API.
2
Discovery
Discovery se conecta a las fuentes externas, detecta sus esquemas y ejecuta extracciones en el mismo proceso con el motor de extracción. Discovery entrega los resultados extraídos directamente a Ingesta.
3
Ingesta
Ingesta parsea, valida, normaliza y deduplica los archivos subidos y los datos que extrae Discovery. Ingesta emite un evento
ingestion.completed.4
Coincidencia
Coincidencia aplica las reglas a las transacciones elegibles y produce grupos de coincidencia con puntuaciones de confianza en una escala entera de 0 a 100. Los grupos de reglas
EXACT y TOLERANCE con una confianza de al menos 90 sobre 100 se autoconfirman. Los grupos de reglas FUZZY y DATE_LAG siempre requieren revisión manual. Los ítems no conciliados se convierten en excepciones.5
Manejo de excepciones
El contexto Excepción clasifica las excepciones, y tu equipo las asigna y resuelve. Los sistemas externos pueden informar resoluciones mediante callbacks. Las actualizaciones de resolución vuelven a Matcher.
6
Gobernanza
Gobernanza registra en logs de auditoría solo por adición los cambios de configuración y las resoluciones de excepciones.
7
Informes
Los usuarios acceden a informes y dashboards que muestran el estado de la conciliación, las tasas de coincidencia y la antigüedad de las excepciones.
Componentes de infraestructura
Matcher depende de los siguientes servicios de infraestructura:
Arquitectura de la base de datos
- Consistencia eventual para las vistas de informes
Resolución del tenant
Matcher resuelve el tenant así:- Matcher nunca acepta identificadores de tenant desde los parámetros de la solicitud
Para más detalles, consulta Seguridad.
Patrones de diseño
Patrón outbox
Matcher usa políticas de entrega por evento. Matcher persiste un registro de outbox para los eventos respaldados por outbox y los despacha de forma asíncrona. Otros eventos pueden usar entrega directa con un respaldo en outbox cuando el circuito está abierto.Próximos pasos
Inicio rápido
Explora la arquitectura con un ejemplo guiado.
Seguridad
Revisa los mecanismos de autenticación, autorización y aislamiento entre tenants.