0006 — Chaves naturais + UPSERT diff-aware

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-06-11 · Decidido em: 2026-05-08

Contexto

Reprocessar um período (reupload do mesmo mês) não pode gerar checkpoints PowerSync desnecessários: cada linha "tocada" no Postgres re-propaga para os clientes móveis, gastando banda e bateria mesmo quando nada mudou de fato.

Decisão

Cada fato tem uma UNIQUE composta sobre as colunas do ERP que o identificam logicamente (chave natural: bi_faturamento com 10 colunas; bi_movimento com 16 + seq_dentro_grupo para colisões legítimas). O pipeline é diff-aware:

1. UPSERT: INSERT … ON CONFLICT (chave_natural) DO UPDATE … WHERE … IS DISTINCT FROM … — só atualiza se algum campo realmente mudou.
2. DELETE seletivo: remove só as linhas que sumiram do upload naquele período, nunca o período inteiro.
3. Ordem: UPSERT primeiro (preserva id), DELETE depois.

Consequências

• Linhas inalteradas mantêm id e xmin → o PowerSync não re-propaga.
• Métricas finas por tabela (inseridas/atualizadas/inalteradas/removidas).
• FKs apontam para a chave natural UNIQUE (Postgres aceita).

Alternativas consideradas

• DELETE do período inteiro + INSERT: recria todas as linhas → churn massivo de checkpoint no PowerSync. Descartado.
• UPSERT cego (sem WHERE IS DISTINCT FROM): bumpa xmin de tudo, mesmo sem mudança real → re-propaga à toa. Descartado.