kroz docs
kroz.co Abrir app
Para times técnicos do piloto. O que está aqui é um resumo. Spec completa, credenciais e homologação saem com o time kroz em contato@kroz.co.

Rule Engine

Contrato parametrizado → payload BaaS: resolver, gatilhos, settlement e prova criptográfica.

Em resumo

O Rule Engine resolve qual versão de regra aplicar dado um evento, compila alocações em baas_split[] e registra execução com snapshot_hash.

Princípio: a regra é dados + versão + hash. A execução é determinística dado (evento, versão ativa).

Nome comercial: "O contrato vira regra executável". Não usar "smart contract".

Arquitetura

flowchart LR
    subgraph config [Configuração]
        C[contracts]
        SM[split_matrices]
        RT[rule_triggers]
    end
    subgraph runtime [Runtime]
        DE[domain_events]
        RR[rule_resolver]
        SE[split_executions]
    end
    subgraph io [I/O]
        API[Dry-run de regra]
        WH[Webhook liquidação]
        BAAS[baas_split payload]
    end
    C --> SM
    SM --> RT
    API --> RR
    WH --> DE --> RR
    RR --> SE
    RR --> BAAS

Dry-run antes de executar

Antes de qualquer cobrança real, a UI e integrações podem simular a resolução da regra:

  • Qual matriz ativa se aplica
  • Quais alocações resultam (SPE, terrenista, vendas…)
  • Se o split[] bate com o que o operador montou na tela (payload_match)
  • Hash da versão (rule_snapshot_hash) para trilha de Fechamento

Sem dry-run aprovado → não executar cobrança real.

Gatilhos (rule_triggers)

Tipo Uso
payment_settled Liquidação confirmada
installment_due Vencimento da parcela
installment_number_gte ex.: comissão a partir da 3ª parcela
construction_milestone_gte Marco de obra
amount_gte Multa ou juros
manual_approval aprovação humana
default Fallback

O gatilho da 3ª parcela é o caso mais comum em incorporação: força de vendas só entra no split quando installmentNumber >= 3.

Settlement (pós-liquidação)

Quando o webhook do BaaS confirma pagamento:

  1. Resolver regra vigente na data do evento
  2. Registrar split_executions com snapshot_hash
  3. Se valor divergir → fila de Conciliação

Versionamento

Regra Comportamento
Versão publicada Imutável
Correção Nova versão + encadeamento
snapshot_hash Prova criptográfica do JSON canônico
Só ativa entra no resolver Status check

Integração com adaptador BaaS

resolveRuleExecution()
  → baas_split[]
  → cobrança com split (dry-run ou real)
  → webhook de liquidação
  → split_executions confirmado

Ver Matriz de rateio · Adaptadores BaaS

Na prática

  • ✅ Simular regra antes de cobrança real
  • ✅ Compare payload_match com o split da UI
  • ✅ Registre rule_snapshot_hash na evidência de Fechamento
  • ❌ Não editar matriz ativa, criar nova versão
  • ❌ Não ignorar avisos (warnings) no preview

Relacionado