Sketch de gestão — Automatizando a execução orçamentária de um órgão público

Antes de qualquer reunião com o cliente, estudo o domínio para conseguir fazer boas perguntas. No setor público, toda despesa segue o mesmo caminho, definido pela Lei 4.320/1964: primeiro o empenho reserva o dinheiro no orçamento; depois a liquidação confirma que o serviço foi entregue, com a nota fiscal atestada pelo fiscal do contrato; só então vem o pagamento.

Em volta desse ciclo está o contrato, regido pela Lei 14.133/2021. Ele tem gestor e fiscal designados, vigência, valor e saldo; os aditivos mudam prazo e valor, e os pagamentos precisam respeitar uma ordem cronológica. Saber isso muda a conversa: em vez de “o que vocês querem que o sistema faça?”, posso perguntar “onde, nesse ciclo, as coisas travam?”.

O discovery dura três semanas e começa por quem vive o problema. Mapeio as partes interessadas e entrevisto cada perfil separadamente: o ordenador de despesa (o patrocinador), a chefia do orçamento, a equipe do financeiro, gestores e fiscais de contrato, a contabilidade, o controle interno e a TI do órgão. Cada um vê um pedaço diferente do mesmo processo — e sente dores diferentes.

As entrevistas são semiestruturadas: um roteiro curto, muito espaço para histórias concretas e nenhuma pergunta sobre solução. Além de ouvir, acompanho um ciclo real de pagamento do início ao fim (shadowing), leio os procedimentos e normativos internos e levanto números do sistema: quantas notas, quantos contratos, quanto tempo cada etapa leva.

• Entregável do discovery: mapa de partes interessadas, processo AS-IS em BPMN validado com quem executa, lista de dores priorizada e números de base para medir o antes e o depois.
• Achado típico desse tipo de entrevista: o fiscal atesta sem ver o saldo do empenho, e o financeiro descobre o problema só na liquidação — dias depois.

## Roteiro — fiscal de contrato (45 min)

1. Me conte como foi a última nota fiscal que você atestou,
   do momento em que ela chegou até sair da sua mesa.
2. O que você precisou conferir? Onde buscou cada informação?
3. Qual foi a última vez que algo deu errado nesse caminho?
   O que aconteceu depois?
4. Como você sabe quanto ainda resta de saldo no contrato?
5. Como fica sabendo que um contrato está perto de vencer?
6. Se pudesse mudar uma única coisa amanhã, qual seria?

Regra: perguntar sobre o passado concreto, nunca sobre a solução.

O diagnóstico AS-IS mostra o caminho real de uma nota: ela chega por e-mail ou papel, vira um processo no SEI, alguém confere à mão contra uma planilha de empenhos, o fiscal atesta por despacho e o financeiro redigita tudo no sistema oficial. A mesma informação é digitada três vezes, o saldo vive numa planilha e a vigência dos contratos depende da memória de uma pessoa.

O TO-BE não troca o sistema financeiro oficial — ele continua sendo a fonte da verdade contábil. O novo sistema orquestra o caminho até ele: captura a nota eletrônica pelo XML ou pela chave de acesso, valida a autenticidade na SEFAZ, vincula nota, empenho e contrato, mostra o saldo na hora, leva o atesto para dentro do sistema com prazo e lembrete e entrega a liquidação pré-preenchida, numa fila que respeita a ordem cronológica.

Com o TO-BE desenhado, transformo a ideia em decisões de produto. Primeiro, princípios que orientam todo o resto: o sistema oficial segue como fonte da verdade; nenhum pagamento é decidido automaticamente; toda ação fica registrada para auditoria; e a interface precisa ser acessível, porque servidores públicos têm necessidades diversas.

Depois, o recorte do MVP com MoSCoW. Obrigatório: cadastro de contratos e empenhos importados do sistema oficial, captura e validação de NF-e, vínculo com saldo, fluxo de atesto e fila de liquidação. Desejável: alertas de vigência, saldo e certidões. Fica para depois: notas de serviço (NFS-e), integração de escrita com o sistema financeiro e aplicativo móvel para fiscais. Um protótipo navegável é testado com cinco servidores antes de qualquer linha de código de produção.

• Métricas de sucesso definidas antes do código: tempo médio da nota até a liquidação, notas com retrabalho, pagamentos fora da ordem cronológica e contratos que venceram sem aviso.
• Primeiro alerta de vigência com 120 dias: o tempo realista para decidir entre prorrogar e abrir uma nova contratação.

AVISOS_VIGENCIA = (120, 90, 60, 30)  # dias antes do fim
SALDO_MINIMO = Decimal("0.20")       # 20% do valor atualizado

def alertas_do_contrato(contrato: Contrato, hoje: date) -> list[Alerta]:
    alertas = []
    dias = (contrato.fim_vigencia - hoje).days
    if dias in AVISOS_VIGENCIA:
        alertas.append(Alerta.vigencia(contrato, dias))
    if contrato.saldo < contrato.valor_atualizado * SALDO_MINIMO:
        alertas.append(Alerta.saldo_baixo(contrato))
    # Alerta avisa; quem decide prorrogar ou aditivar é o gestor.
    return alertas

Desenho a arquitetura no modelo C4, começando pela visão de containers. A escolha central é um monólito modular, e não microsserviços: o time é pequeno, o domínio é um só e quem vai manter o sistema depois é a TI do órgão. Uma aplicação web conversa com uma API; um worker separado cuida de tudo o que é lento ou externo — consultas à SEFAZ, importação de empenhos, alertas agendados.

Os sistemas do governo ficam do lado de fora, atrás de adaptadores isolados que só o worker chama. Se o sistema financeiro sair do ar ou a SEFAZ demorar, o usuário continua trabalhando e a integração tenta de novo depois. Cada mudança relevante vira um evento numa trilha de auditoria que só aceita inclusões, pensada para o controle interno e para o tribunal de contas.

# ADR 0003 — Integração com o sistema financeiro oficial

Status: aceito

## Contexto
O sistema financeiro do estado não tem API de escrita. Há exportação
diária de empenhos e importação de lotes de liquidação por arquivo.

## Decisão
Ler empenhos pela exportação diária e gerar lotes de liquidação para
importação, via adaptador no worker. Nada é gravado direto no sistema.

## Consequências
+ Sem dependência de API que não existe; o sistema oficial segue soberano.
- Saldo pode ter até um dia de atraso: a tela mostra a data da última carga.

Cada tecnologia é escolhida pelo problema e por quem vai mantê-la depois. No setor público, a pergunta “a TI do órgão consegue sustentar isso daqui a cinco anos?” pesa tanto quanto desempenho.

• Next.js + React: renderização no servidor, boa base para acessibilidade (eMAG e WCAG) e um ecossistema fácil de contratar.
• Python + FastAPI: Python lida bem com XML de NF-e e PDFs; Pydantic valida cada entrada e o OpenAPI documenta a API sozinho.
• PostgreSQL: transações para dinheiro, JSONB para guardar o XML interpretado e uma fila simples com SELECT … FOR UPDATE SKIP LOCKED, sem mais um serviço para operar.
• Keycloak (OIDC): login único integrado ao Active Directory do órgão ou ao gov.br, com perfis por papel.
• Armazenamento de objetos compatível com S3 para os XMLs e PDFs, e OpenTelemetry para logs, métricas e rastreio das integrações.
• Tudo em contêineres, implantável no datacenter do órgão ou numa nuvem de governo — com os dados no Brasil, como pede a LGPD.

O time é enxuto: eu na gestão do projeto e liderança técnica, dois desenvolvedores full-stack, um designer em meio período e um servidor do órgão como product owner — de preferência alguém do financeiro, com autoridade para priorizar. Qualidade é responsabilidade do time todo, não de uma etapa no final.

Depois do discovery, trabalho em Scrum com sprints de duas semanas. A cadência fixa ajuda o órgão a planejar a agenda dos servidores para as revisões, que são feitas com quem vai usar o sistema, e não só com a chefia. Em paralelo, o discovery continua em menor escala para validar o que vem a seguir.

• Definição de pronto: testes automatizados, revisão de código, critérios de acessibilidade, nada de dado pessoal em log e documentação atualizada.
• Governança: status semanal com semáforo (verde, amarelo, vermelho) para o patrocinador e comitê mensal para decisões de escopo.
• Mudanças de escopo entram no backlog e trocam de lugar com outra entrega: prazo e qualidade ficam fixos, o escopo é o que se negocia.
• Transferência de conhecimento contínua para a TI do órgão: pareamento, ADRs e runbooks — o sistema não pode depender de quem o construiu.

Riscos são levantados no discovery, ganham um responsável e são revistos a cada sprint. Os principais deste cenário:

• O sistema financeiro não tem API → um experimento técnico na semana 1 confirma o que é possível; o plano B é integração por arquivo (ADR 0003).
• Resistência à mudança → servidores no desenho desde a primeira entrevista, piloto em uma unidade e treinamento no posto de trabalho.
• Troca de gestão ou de equipe → patrocínio documentado, decisões registradas em ADR e entregas de valor a cada duas semanas.
• Certificado digital e acesso à SEFAZ dependem de trâmites do órgão → pedido aberto já no discovery, com a TI como responsável.
• Dados de contratos desatualizados → saneamento dos cadastros como parte do piloto, com relatório de inconsistências.

São 20 semanas da primeira entrevista ao piloto: três de discovery, três de concepção, quatro sprints de MVP, duas de homologação com servidores e quatro de piloto em uma unidade gestora. Cada marco tem um critério objetivo — o mapa AS-IS validado por quem executa, o protótipo aprovado nos testes com usuários, o MVP homologado.

No fim do piloto vem a decisão de expandir ou não, tomada com as métricas definidas na concepção comparadas aos números de base do discovery. Se o tempo da nota até a liquidação não cair e o retrabalho não diminuir, o projeto volta para a prancheta antes de crescer.

Tecnologia é a parte mais fácil de trocar num projeto; entendimento errado do processo é a mais cara. Por isso a ordem aqui é sempre a mesma: pessoas, processo, decisões de produto, arquitetura e só então ferramentas.

No setor público, isso pesa ainda mais. O sistema precisa respeitar a lei antes de ser elegante, conviver com os sistemas oficiais em vez de competir com eles e continuar de pé quando o time que o construiu já tiver ido embora.