Composição (1:N, N:1, N:M)
Conciliação por soma: um contra vários, vários contra um, subconjunto contra subconjunto e parcelas.
Nem todo registro tem um par único do outro lado. Uma nota pode ser paga em três transferências; um pagamento pode quitar quatro notas. A seção composite do ruleset procura grupos cuja soma fecha, depois das passadas 1:1, sobre os registros que elas deixaram abertos.
| Modo | Esquerda | Direita | Exemplo |
|---|---|---|---|
1:N | 1 | vários | Uma nota paga em várias transferências |
N:1 | vários | 1 | Várias notas quitadas por um pagamento |
N:M | vários | vários | Duas notas de R$ 60 e R$ 40 pagas por transferências de R$ 70 e R$ 30 |
Estrutura
"composite": {
"modes": ["1:N", "N:1", "N:M"],
"group_by": [{ "left": "left.doc_tomador", "right": "right.doc_pagador" }],
"sum": { "left": "left.valor", "right": "right.valor", "tolerance": 0, "tolerance_percent": 0.5 },
"window": { "left": "left.vencimento", "right": "right.data_pagamento", "days": 30 },
"max_items": { "left": 10, "right": 12 },
"strategies": {
"complete_group": true,
"amount_variance": { "max_percent": 5 },
"partial": { "min_members": 2, "min_completion": 0.2 }
},
"thresholds": { "match": 80, "possible": 50 },
"matchers": [
{ "name": "datas", "score": 70, "expr": "decay(days_between(min(lefts.map(l, l.vencimento)), max(rights.map(r, r.data_pagamento))), 30)" },
{ "name": "itens", "score": 30, "expr": "size(lefts) + size(rights) <= 4" }
]
}| Atributo | Papel |
|---|---|
modes | Quais modos rodam, na ordem da lista. Cada modo consome os registros que conciliou antes do próximo |
group_by | Chave obrigatória: um grupo só junta registros com os mesmos valores nesses campos. É o que limita a busca |
sum | Campos somados de cada lado (integer ou decimal, do mesmo tipo e, em decimal, com o mesmo scale) e a tolerância aceita |
window | Opcional: limite de dias entre as datas dos registros do grupo (0 a 366) |
max_items | Máximo de registros de cada lado num match, de 2 a 100. Padrão 10 |
strategies | Comportamentos opcionais, descritos abaixo |
thresholds | Limiares próprios da composição |
matchers | Pontuação do grupo. Sem matchers, um grupo que fecha pontua 100 |
Soma e tolerância
toleranceé absoluta, em unidades mínimas (centavos comscale: 2).tolerance_percenté relativa ao valor do alvo (o registro único em 1:N e N:1, e o total esperado nos parciais), de 0 a 100.- Com as duas, vale a maior.
- Valores negativos (tarifas, estornos, notas de crédito) entram na soma normalmente: uma nota de R$ 100,00 fecha com um crédito de R$ 102,50 e uma tarifa de −R$ 2,50.
Registros sem valor no campo de soma ou na data da janela ficam fora da composição.
Matchers de grupo
As expressões recebem as listas lefts e rights, com os mesmos campos dos datasets. Em 1:N, lefts tem um elemento só, então a mesma expressão serve para todos os modos. Use as macros do CEL e as agregações:
decay(days_between(min(lefts.map(l, l.vencimento)), max(rights.map(r, r.data_pagamento))), 30)
rights.all(r, lefts.exists(l, similarity(l.razao_social, r.nome_pagador) > 0.8))
sum(rights.map(r, r.valor)) == sum(lefts.map(l, l.valor))Como no 1:1, required: true descarta o grupo quando a expressão dá 0, e score: 0 com required: true funciona como filtro.
Ambiguidade
O motor guarda as duas melhores combinações de cada busca. Se duas combinações diferentes empatam no melhor score, o resultado é possible: o Nexus não escolhe no chute entre parcelas idênticas. Um matcher de data costuma desempatar esses casos.
Estratégias
| Estratégia | Efeito |
|---|---|
complete_group: true | Testa primeiro o grupo inteiro: se todos os candidatos somam o alvo, esse é o resultado |
amount_variance: { max_percent } | Grupo que quase fecha (juros, multa, desconto) vira possible com amount_diff, desde que a diferença fique dentro de max_percent (até 50) |
partial | Só com 1:N: parcelas que ainda não somam o total viram um match partial, completado por jobs seguintes |
Parciais
Com partial, uma nota de R$ 1.000 paga em parcelas de R$ 250 gera, quando chegam as duas primeiras, um match partial com expected_count: 4. Os registros ficam reservados para esse match.
min_members(padrão 2): parcelas mínimas para abrir o parcial.min_completion(padrão 0,2): fração mínima do total já paga.uniformity(padrão 0,05): quanto as parcelas podem variar entre si (desvio padrão sobre a média, até 0,5).
No início de cada job do mesmo ruleset, o Nexus tenta completar os parciais abertos com os registros novos. Quando a soma fecha, o match passa a matched e sai o evento match.completed.
No resultado
Matches da composição têm kind (1:N, N:1 ou N:M), pass: -1 e strategy com o caminho que encontrou o grupo:
strategy | Origem |
|---|---|
complete_group | O grupo inteiro fechou |
subset | Busca de subconjunto |
meet_in_the_middle | Busca de subconjunto em grupos maiores ou com valores negativos |
amount_variance | Quase fechou; sempre possible |
partial | Parcial aberto ou completado |
amount_diff traz o total da direita menos o total da esquerda, em unidades mínimas.
Limites
- Um grupo com mais de 500 registros em um dos lados é pulado e contado em
stats.steps[].composite.skipped_groups. Use uma chave degroup_bymais seletiva ou uma janela. - Quando a busca de um grupo passa do orçamento sem achar solução, ela para e conta em
searches_exhausted. Os registros continuam abertos para o próximo job.

