Arquitectura

​

Resumen de la arquitectura

​

Contextos delimitados

• 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, enrutamiento, resolución)
• Gobernanza: registros de auditoría (logs inmutables para cumplimiento)
• Informes: visibilidad (informes, exportaciones, dashboards)

​

Configuración

• 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ón
• ReconciliationSource: configuración de la fuente
• FieldMap: reglas de traducción de campos
• MatchRule: lógica de coincidencia

​

Discovery

• 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

• FetcherConnection: conexión a una fuente externa gestionada localmente por el motor de extracción
• ExtractionRequest: sigue el ciclo de vida de una extracción que ejecuta el motor embebido

​

Ingesta

• Parsear los archivos subidos (CSV, JSON, XML)
• 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 ingesta
• Transaction: registro canónico normalizado de una transacción

• ingestion.completed: indica que los datos están listos para la coincidencia

​

Coincidencia

• 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 coincidencia
• MatchGroup: grupo de transacciones conciliadas
• MatchItem: asignación individual de una transacción

• match_group.confirmed: un grupo de coincidencia quedó finalizado
• match_group.unmatched: una coincidencia confirmada antes fue revertida
• transaction.pending_review: un candidato no automático necesita revisión

​

Gestión de excepciones

• Clasificar las excepciones por severidad
• Enrutar las excepciones a equipos internos o a sistemas externos
• Admitir anulaciones y ajustes manuales
• Seguir el estado de resolución y los SLA
• Integrarse con herramientas externas de workflow

• Exception: una transacción sin resolver
• Resolution: resultado del manejo de una excepción
• RoutingRule: lógica de enrutamiento y de escalamiento

• JIRA para el seguimiento de incidencias
• ServiceNow para incidentes de la Table API
• Webhooks para workflows personalizados

​

Gobernanza

• Registrar en logs de auditoría inmutables los workflows de mutación auditables instrumentados
• 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

• Generar informes de conciliación
• Exponer métricas de dashboard
• Exportar los datos de conciliación en varios formatos

• Report: resumen de la conciliación
• Dashboard: métricas operativas agregadas
• ExportJob: ejecución asíncrona de una exportación

​

Flujo de datos

​

Componentes de infraestructura

​

Arquitectura de la base de datos

• Resolución de pool por tenant en los despliegues multi-tenant configurados, para separar los datos
• Consistencia fuerte para el estado de coincidencia y de excepciones
• Consistencia eventual para las vistas de informes

​

Multi-tenancy

• En los despliegues multi-tenant con AUTH_PROVIDER=plugin-auth, Matcher toma la identidad del tenant de los claims JWT tenant_id o tenantId
• Los despliegues single-tenant y los que tienen la autenticación deshabilitada usan el tenant predeterminado configurado
• Matcher nunca acepta identificadores de tenant desde los parámetros de la solicitud
• Todo el acceso a la base de datos pasa por el pool de conexiones del tenant activo
• Matcher restringe de forma automática cada consulta al tenant activo

​

Patrones de diseño

​

Arquitectura hexagonal

context/
├── adapters/
│ ├── http/
│ ├── postgres/
│ └── redis/
├── ports/
├── services/
│ ├── command/
│ ├── query/
│ └── worker/
└── domain/
 ├── entities/
 └── errors/

​

Cqrs-light

• *_commands.go para las mutaciones de estado
• *_queries.go para las operaciones de lectura

​

Patrón outbox

​

Próximos pasos