Engenharia de CRM: Máquinas de Estados Finitos para Fluxos de Crédito Habitação

No panorama atual do desenvolvimento de software para o setor fintech, a robustez do código não é um luxo, mas um requisito de conformidade. Ao projetar um CRM destinado à gestão de processos de crédito, o erro mais comum é confiar o ciclo de vida do processo a uma série desordenada de condições booleanas. Neste contexto, a Máquina de Estados Finitos (FSM – Finite State Machine) surge como a entidade arquitetural fundamental para garantir que processos complexos, como a concessão de um crédito habitação, sigam caminhos determinísticos e seguros. Este artigo explora como aplicar os princípios da engenharia de sistemas para transformar a lógica de negócio num motor de fluxo de trabalho inatacável, refletindo a experiência adquirida no desenvolvimento de plataformas de alta criticidade como o CRM BOMA.

O Problema da “Lógica Esparguete” nos CRMs Financeiros

Imaginem ter de gerir um processo de crédito habitação. Numa abordagem ingénua, o programador poderia adicionar colunas à base de dados como is_approved, docs_uploaded, contract_signed. O código resultante para verificar se um crédito pode ser libertado assemelhar-se-ia a isto:

if (loan.is_approved && loan.docs_uploaded && !loan.is_rejected) {
  // Liberta fundos
}

Esta abordagem escala desastrosamente. O que acontece se o processo for suspenso? Adicionamos um flag is_suspended? E se for reaberto? A combinação de N flags booleanos cria 2^N estados possíveis, a maioria dos quais são estados inconsistentes (ex. um processo simultaneamente “rejeitado” e “a aguardar assinatura”). As máquinas de estados finitos resolvem este problema reduzindo o universo de possibilidades a um grafo direto de estados válidos e transições explícitas.

O que é uma Máquina de Estados Finitos (FSM)?

Uma FSM é um modelo matemático de computação. É um sistema abstrato que pode encontrar-se exatamente num de um número finito de estados num dado momento. A FSM muda de estado em resposta a inputs externos; a passagem de um estado para outro é chamada de transição.

Para um CRM de crédito habitação, uma FSM é definida por:

• Estados (S): {RASCUNHO, INSTRUÇÃO, DECISÃO, ASSINATURA, CONCEDIDO, REJEITADO, CANCELADO}
• Eventos/Input (E): {ENVIAR_DOCUMENTOS, APROVAR_CREDITO, ASSINATURA_CLIENTE, LIBERTAR_TRANSFERENCIA}
• Função de Transição (δ): Uma regra que define: Se estou no estado X e ocorre o evento Y, passo para o estado Z.

Modelação do Fluxo de Crédito Habitação

Em vez de perguntar “que flags estão ativos?”, perguntamos “em que estado se encontra o processo?”. Eis como modelar um fluxo padrão de crédito habitação:

1. RASCUNHO: O intermediário está a inserir os dados. O único evento possível é ENVIAR_PARA_INSTRUCAO.
2. INSTRUÇÃO: O banco analisa os documentos. Eventos possíveis: APROVAR (leva a DECISÃO) ou REJEITAR (leva a REJEITADO). Não é possível ir diretamente para CONCEDIDO.
3. DECISÃO: O crédito está aprovado. Evento: EMITIR_OFERTA.
4. ASSINATURA: O cliente deve assinar. Evento: REGISTAR_ASSINATURA.
5. CONCEDIDO: Estado final positivo.

Diagrama de Transições (Representação Lógica)

O poder das máquinas de estados finitos reside na proibição implícita. Se o sistema recebe o evento LIBERTAR_TRANSFERENCIA enquanto o processo está no estado INSTRUÇÃO, a FSM não se deve limitar a falhar silenciosamente: deve lançar uma exceção de Transição Ilegal. Isto torna o sistema determinístico.

Implementação Técnica: Padrões e Código

Para implementar uma FSM num stack backend moderno (ex. Node.js/TypeScript ou Python), desaconselhamos o uso de switch/case gigantes. É preferível utilizar o State Pattern ou bibliotecas dedicadas como XState. Eis um exemplo de implementação conceptual em TypeScript:

type LoanState = 'DRAFT' | 'UNDERWRITING' | 'APPROVED' | 'DISBURSED' | 'REJECTED';

class MortgageFSM {
  private state: LoanState;

  private transitions = {
    DRAFT: { SUBMIT: 'UNDERWRITING' },
    UNDERWRITING: { APPROVE: 'APPROVED', REJECT: 'REJECTED' },
    APPROVED: { DISBURSE: 'DISBURSED', CANCEL: 'REJECTED' },
    DISBURSED: {}, // Estado terminal
    REJECTED: {}   // Estado terminal
  };

  constructor(initialState: LoanState) {
    this.state = initialState;
  }

  public transition(event: string): void {
    const nextState = this.transitions[this.state][event];
    
    if (!nextState) {
      throw new Error(`Transição inválida: Impossível executar ${event} a partir do estado ${this.state}`);
    }

    console.log(`Transição: ${this.state} -> ${nextState}`);
    this.state = nextState;
    this.onStateChange(nextState);
  }

  private onStateChange(newState: LoanState) {
    // Hook para side effects (ex. envio de email, webhooks)
  }
}

Persistência e Base de Dados

Ao nível da base de dados (SQL), a representação mais eficiente não é uma série de booleanos, mas uma única coluna status indexada, frequentemente suportada por um tipo ENUM para garantir a integridade referencial.

Contudo, para trilhos de auditoria complexos (exigidos pela normativa bancária), é aconselhável uma tabela separada loan_state_history:

• loan_id (FK)
• previous_state
• new_state
• trigger_event
• timestamp
• user_id (quem desencadeou a transição)

Arquitetura Event-Driven e Side Effects

A integração das máquinas de estados finitos com uma arquitetura orientada a eventos é onde o CRM se torna proativo. Cada transição de estado válida deve emitir um Domain Event.

O Fluxo Reativo

1. O utilizador clica em “Aprovar Processo” no dashboard.
2. A API invoca a FSM: fsm.transition('APPROVE').
3. A FSM valida a lógica, atualiza a BD e, em caso de sucesso, emite o evento LoanApprovedEvent num message broker (ex. RabbitMQ ou Kafka).
4. Consumers desacoplados reagem:
   • O Notification Service envia um email ao intermediário.
   • O Document Service gera o PDF da decisão.
   • O Audit Service regista a operação para compliance.

Este desacoplamento impede que a lógica de envio de email “polua” a lógica pura de aprovação do crédito.

Prevenção de Estados Inconsistentes (Safety)

Na experiência de desenvolvimento de sistemas como o BOMA, identificámos três regras de ouro para a segurança das FSM:

1. Atomicidade: A transição de estado e a gravação na BD devem ocorrer na mesma transação de base de dados. Se a gravação falhar, o estado em memória deve ser restaurado.
2. Idempotência: Se um sistema externo enviar duas vezes o evento APPROVE, a FSM deve gerir a segunda tentativa com graciosidade (ignorando-a ou devolvendo o estado atual), sem criar duplicados ou erros.
3. Guardas (Guards): Além da validade da transição (A -> B), é possível implementar “guardas”. Exemplo: “Podes passar de INSTRUÇÃO para DECISÃO apenas se a soma dos documentos carregados > 5”. As guardas adicionam um nível de lógica condicional controlada dentro da estrutura rígida da FSM.

Conclusão

A adoção das máquinas de estados finitos no desenvolvimento de CRM para crédito habitação não é apenas uma escolha estilística de código, mas uma decisão arquitetural estratégica. Esta desloca a complexidade da gestão de erros para a fase de conceção, forçando engenheiros e gestores de produto a definir o processo de negócio com precisão cirúrgica antes de escrever uma única linha de código. O resultado é um sistema previsível, auditável e, sobretudo, seguro para a gestão de ativos financeiros.

Perguntas frequentes