fix(dre): fecha a auditoria da DRE — folha contada 2x, recorte que mentia e estorno que sumia

[BarryBits]

Fecha as Ondas 3, 4 e 5 da auditoria da DRE (docs/atros-v3/handoff-2026-07-31-auditoria-dre.md). As Ondas 1 e 2 já estavam em produção (#39, #40).

Dois commits, um por gate.

---

f1cf688 — Ondas 3 e 4: a folha para de ser contada duas vezes

totaisPorCategoria[catId] tinha dois significados. Em mês aberto era por-categoria de verdade; em mês fechado a reconciliação jogava a L50 inteira em despesas_administrativas e deixava pessoas com o valor do motor TS.

Por isso os leitores erravam em direções opostas:

Leitor	Convenção	Mês aberto	Mês fechado
anomaly-detection, dfc-direct-mapper	admin + pessoas	✅	❌ folha 2×
break-even (extrato-processor)	admin só	❌ sem a folha	✅
ponto de equilíbrio (kpi-advanced-service)	admin só	❌ sem a folha	✅

Os três de baixo o handoff da auditoria não listava.

A tabela CATEGORIA_LINHA_SINAL morreu — o sinal do catálogo reproduz ela inteira. Como a v3 fecha por linha e o dre_detalhado guarda por categoria, a reconciliação passa a ratear a linha entre as categorias que a dividem, com a última absorvendo o resíduo (a soma bate exato, que é a invariante de que os leitores dependem). Valor não atribuível cai na residual: afirmar "a folha foi X" sem saber é pior que dizer "administrativas foi X". Convenção registrada em categorization-rules.ts.

Junto vão três defeitos de recorte:

• addMonths transbordava — em 31/05, "Mês passado" devolvia MAIO. Idem 31/07, 31/10, 31/12 e 29–31/03.
• Recorte de um mês abria em coluna semanal enquanto o rótulo prometia "último mês fechado". Era esse recorte que levava erro de cascata aos olhos do dono. O toggle DIA/SEM/MÊS segue disponível.
• Transação sem categoria sumia da tela — o balde existia no acumulador e o loop iterava só CATEGORIAS. Agora vira linha visível "Não categorizado", em L99, fora do resultado.

Re-fechamento aplicado

Os 30 snapshots gravados estavam todos corrompidos — R$ 13.962.202,16 de folha em dobro, o mesmo número da Onda 1. O fix de código sozinho não alcançava produção, e o refechar-snapshots-catalogo não pegava: o gate dele era headline || subs, e esse drift não mexe em nenhum dos dois. Ganhou o terceiro detector, categoriasComDrift.

Rodado: 30 gravados, diagnóstico depois deu 0 corrompidos, novo dry-run dá 0 mudanças (idempotente). Resultado Líquido não mudou em nenhum mês — muda só o split.

---

1c05831 — Onda 5: o estorno para de sumir

calculate_monthly_dre_v3 somava um lado só conforme o sinal. Um estorno — crédito numa categoria de despesa (devolução de compra, reembolso) ou débito numa de receita (chargeback) — contribuía zero. E não caía em L90 nem L99: o dinheiro sumia da cascata inteira. O extrato mexia e a DRE não sabia.

Em regime de caixa quem está certo é o TS: se o dinheiro voltou pra conta, ele voltou, e reduz a despesa do mês em que caiu.

A migration passa a somar magnitude líquida. Escolha deliberada de não inverter a convenção do JSONB linhas: linha de despesa continua positiva quando é despesa líquida e a escada continua subtraindo, então nenhum leitor de linhas_dre foi tocado (montarKpisDeV3, cash-cycle-analyzer, dre-v3-aggregate, sinalDaLinha). O caminho óbvio — SQL fazendo credito−debito e escada virando soma — teria raio de explosão enorme à toa. O corpo da função é cópia byte-idêntica do dump com as duas linhas do CASE trocadas.

Por que agora

Medido antes de aplicar: 18.004 transações, 0 estornos. A divergência era 100% latente. Dry-run depois da migration: 30/30 idênticos — nada a gravar. Era essa a hora: com estorno real em campo, a correção passaria a mexer em número que o cliente já viu.

Terceira cópia da convenção

visao-service.ts (ranking top-8 da Visão do Projeto) também somava um lado só — a DRE diria 35.000 e o ranking 40.000 pro mesmo fornecedor no mesmo mês. Alinhada junto.

---

Banco

Migration 20260804000000_dre_v3_sinal_liquido já aplicada no remoto. Re-dump confirma: diff contra o dump de 30/07 dá exatamente 3 linhas, todas da migration (as 2 do CASE + o COMMENT); roles.sql sem mudança de conteúdo; zero drift fora de migration. Snapshot volta a 🟢 autoritativo (20260804000000 = max(repo)).

Com 0 estornos a saída da RPC é idêntica nas duas versões — então ler a função era a única prova possível de que a migration entrou. Nenhum teste de comportamento serviria.

Gate

• 1465/1465 testes (157 arquivos), +21 novos
• f1cf688 verificado verde isoladamente (164 testes) — sem commit intermediário quebrado
• next build ok · tsc limpo · 0 erro e 0 warning novo de eslint

Armadilha que ficou documentada

O gabarito motorSqlV3 dentro de cascata.test.ts é uma cópia da álgebra do SQL, não uma leitura dela. Trocar o CASE da RPC sem trocar o gabarito deixaria a paridade verde e mentirosa — exatamente o modo de falha que deixou a folha sumir na primeira vez. Aviso no cabeçalho do arquivo.

Como revisar

O check ao vivo que falta é na tela: abrir a DRE da Vertímetal e conferir que entra em coluna mensal e que Administrativas × Pessoas aparecem separadas somando a L50.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
atr-os	Ready	Preview	Aug 4, 2026 11:18pm

[supabase]

Updates to Preview Branch (fix/dre-ondas-3-4-5) ↗︎

Deployments	Status	Updated
Database	✅	Tue, 04 Aug 2026 23:14:59 UTC
Services	✅	Tue, 04 Aug 2026 23:14:59 UTC
APIs	✅	Tue, 04 Aug 2026 23:14:59 UTC

Tasks are run on every commit but only new migration files are pushed.
Close and reopen this PR if you want to apply changes from existing seed or migration files.

Tasks	Status	Updated
Configurations	✅	Tue, 04 Aug 2026 23:15:04 UTC
Migrations	❌	Tue, 04 Aug 2026 23:15:06 UTC
Seeding	⏸️	Tue, 04 Aug 2026 23:14:54 UTC
Edge Functions	⏸️	Tue, 04 Aug 2026 23:14:54 UTC

---

❌ Branch Error • Tue, 04 Aug 2026 23:15:06 UTC

ERROR: relation "projects" does not exist (SQLSTATE 42P01)
At statement: 0
-- ============================================================
-- ATR OS - Migration: Project Lifecycle States
-- ============================================================
-- Adiciona campos de lifecycle para o fluxo de onboarding:
-- aguardando_docs → diagnostico_7d → plano_entregue → em_execucao → concluido
-- ============================================================

-- 1. Adicionar colunas de timestamp para cada etapa do lifecycle
ALTER TABLE projects
ADD COLUMN IF NOT EXISTS docs_solicitados_em timestamptz,
ADD COLUMN IF NOT EXISTS docs_recebidos_em timestamptz,
ADD COLUMN IF NOT EXISTS diagnostico_deadline timestamptz,
ADD COLUMN IF NOT EXISTS plano_entregue_em timestamptz,
ADD COLUMN IF NOT EXISTS execucao_inicio timestamptz,
ADD COLUMN IF NOT EXISTS execucao_deadline timestamptz

---

View logs for this Workflow Run ↗︎.
Learn more about Supabase for Git ↗︎.