Aprovações por alçada
Engine genérico que governa toda decisão financeira da plataforma, com callbacks automáticos
Por que existe um engine de aprovações
Em uma incorporadora, toda decisão que move dinheiro precisa passar por alçada — quanto maior o valor, mais alta a alçada. O OctaBuild centraliza essa lógica num engine único: políticas, fila de aprovações, delegação por ausência, escalação automática por SLA, e callbacks que executam ações na entidade aprovada.
Conceitos
Entity types
Cada tipo de aprovação tem um entity_type:
requisicao_compra— RC > limiar precisa aprovaçãocotacao_decisao— escolha do vencedor da cotaçãopedido_compra— emissão direta sem RC (contrato-mestre)contrato_empreitada— contrato formal de obrarecebimento_divergente— divergência no 3-way matchaditivo_contrato— alteração de prazo/valor/escopoliberacao_retencao— devolver retenção técnicamedicao_empreiteiro— boletim de medição mensalsuprimento_fundos— fundo fixo ou adiantamentopagamento— lote de pagamento acima da alçadaviabilidade,baseline,documento,contrato_venda,distrato,alteracao_orcamento,chamado_assistencia,projeto_revisao
Policies (políticas)
Regra que casa com um valor → define a sequência de aprovadores.
Exemplo:
- "Cotação > R$ 10k" → 1 step (gerente)
- "Cotação > R$ 50k" → 2 steps (gerente + diretor)
A policy de maior priority cuja condition casa é a aplicada. Cada org tem políticas próprias (configuráveis).
Steps
Cada policy tem N steps. Cada step define:
approver_type: role | usuário específico | regra dinâmica (ex: "gerente do projeto")requires_all: se todos os aprovadores devem aprovar (default: qualquer um)
A aprovação avança para o próximo step somente quando o atual está completo.
Callbacks
Quando uma approval é resolvida (aprovada ou rejeitada), o engine dispara o callback registrado que atualiza a entidade subjacente. Por exemplo:
| Entity type | Callback aprovação |
|---|---|
requisicao_compra | RC.status = aprovada, registra aprovada_por |
cotacao_decisao | Cria PO automaticamente com itens dos vencedores |
aditivo_contrato | Aditivo.status = aprovado (depois aplica manualmente) |
liberacao_retencao | Medição.retencao_liberada = true |
recebimento_divergente | Libera 3-way + dispara entrada estoque |
medicao_empreiteiro | Medição.status = aprovada |
suprimento_fundos | Fundo.status = aprovado (financeiro libera) |
Onde aprovar
Painel → Aprovações (sidebar): lista de aprovações pendentes para você. Cards mostram entidade, valor, justificativa, urgência. Aprovar/rejeitar com 1 clique + comentário opcional.
Configurar
Settings → Aprovações & Compras → Políticas de Aprovação:
- Visualizar políticas por entity_type
- Editar condições, steps, alçadas
- Criar políticas customizadas
Delegação por ausência
Settings → Aprovações → Delegações: o usuário pode delegar suas aprovações a outra pessoa por período definido (férias, viagem). Escopo configurável: todas / por entity_type / por empreendimento.
SLA e escalação
Cada policy pode ter SLA (default 24h úteis). Aprovador parado por mais que isso recebe lembrete; escala para o próximo nível após o threshold configurado.
Settings → Aprovações → Regras de Escalação — define quem recebe quando um aprovador não responde no SLA.
Auditoria
Toda decisão (aprovado, rejeitado, delegado, escalado, expirado) gera registro imutável em approval_audit_log. Visível em qualquer aprovação resolvida — clique em "Ver histórico".
Regra de ouro: solicitante ≠ aprovador
O engine bloqueia automaticamente que o solicitante de uma RC/medição/etc. seja também aprovador da mesma. Se a alçada cair em si mesmo, escala automaticamente para o próximo nível.