Decisions

Estas decisões refletem o estado canonical da Versão Atual (07/05/2026). Cada ADR resume o que, por que e status atual. Pendências e gaps do audit ficam ao final.

ADR-1 · Versão Atual: AABC-only

• What — Integração exclusiva via aplicativo Omie AABC (CNPJ 50.162.682/0001-07). LNG fora do escopo desta versão.
• Why — Foco MVP. Reduz superfície de teste e evita conflito de regras fiscais entre orgs.
• Status — Decidido 07/05/2026 · Confluence 3813310465.

ADR-2 · Mínimo Bubble

• What — Bubble dispara exatamente 1 trigger automático (POST /v1/orders/{bubble_order_id}/sync-omie em “Pedido criado”) e expõe N botões backoffice/website chamando endpoints do backend (retry, cancel-nf, mark-nf-manual, approve-billing-hold, override-day25, transfer-cc, use-cc). Bubble não recebe webhook Pagar.me nem chama Brasil API.
• Why — Bubble continua dono dos dados e do front; backend é orquestrador. Não recriar funcionalidades existentes; centralizar side-effects e regras fiscais onde há capacidade de teste e observability.
• Status — Decidido · canonical em AGENTS.md (“Premissa Mínimo Bubble”).

ADR-3 · Sync síncrono atômico no MVP

• What — Bubble chama sync-omie síncrono e espera resposta. Não há outbox pattern. Backend escreve status writeback de volta no Bubble Data API dentro da mesma transação lógica.
• Why — Simplicidade. Evita consistency lag visível ao backoffice. Deferir outbox até segundo consumer aparecer ou até volume justificar.
• Status — Decidido para MVP · revisar pós primeiro produção.

ADR-4 · Status duplos independentes

• What — Pedido carrega status_pedido ∈ cancelado (3 valores) e status_faturamento ∈ faturamento_manual (9 valores), evoluídos independentemente.
• Why — Lifecycle de pagamento ≠ lifecycle de faturamento. Carta de crédito, holds manuais, regra dia 25 e cancelamento de NF têm transições próprias que não mapeiam 1:1 em estado de pedido.
• Status — Decidido · Confluence 3812950022 (Modelo de Estados).

ADR-5 · HubSpot Fase 2 descartado

• What — BLU-766 (integração HubSpot Fase 2) removido do escopo da Versão Atual.
• Why — Scope reduction. Sem caso de uso bloqueante para MVP.
• Status — Mover para wontfix-mvp · ação pendente no board.

ADR-6 · Consolidação de pedidos descartada

• What — BLU-781 (consolidação de pedidos) fora do escopo da Versão Atual.
• Why — Complexidade incremental sem caso de uso confirmado no MVP. Reabrir se demanda comercial surgir pós-launch.
• Status — Mover para wontfix-mvp · ação pendente no board.

ADR-7 · Pagar.me webhook direto ao backend

• What — POST /webhooks/pagarme no backend, HMAC mandatory. Idempotência por charge_id. Bubble não processa webhook.
• Why — HMAC verification e idempotência cabem no backend; Bubble não tem capacity nativa para assinatura HMAC nem para gating de retry com janela de 31min do rate-limit Omie.
• Status — Decidido · Confluence 3812327443 (Módulo Pagar.me).

ADR-8 · Brasil API CNPJ chamado pelo backend

• What — Backend chama Brasil API CNPJ lookup e escreve resultado no Bubble via Data API.
• Why — Rate limit e cache no backend; Bubble não é HTTP client capable para integração externa com retry policy e TTL.
• Status — Decidido · Confluence 3813539856 (Mapeamento Payload).

Pendências em aberto

• P11 · formato vendedor na O.S. Omie (consultar /geral/vendedores/) — Aguardando Luiz
• P12 · estratégia homologação NFS-e (acesso 7d ambiente demo) — Aguardando Luiz
• PAGARME-1 · PAGARME_WEBHOOK_SECRET rotacionado? — Aguardando Luiz
• BUBBLE-1 · Bubble tem pagarmedetails + pagarmewebhookcall no schema — substitui ou convive com handler atual? — Aguardando Luiz
• OMIE-1 · cache strategy /servicos/listaservico/ (TTL? refresh diário?) — Discovery
• BLU-783 · rate-limit Omie discovery existe, falta ticket filho de implementação — Bloqueia retry policy

Gaps OrderToBillingFlow

Top-5 gaps identificados no audit docs/reports/order-to-billing-flow-audit.html, em ordem de implementação:

1. Gap 4 (1h) — Unificar enum status writeback Bubble: sync_service.py:430 escreve "NF emitida" (PT) vs invoice_service.py:222 escreve "invoiced" (EN). Confirmar Option Set ns_status canonical antes de unificar. Quick win
2. Gap 2 (1d) — Alembic migration adicionando billing_scheduled_date + billing_trigger em billing_schedule. Pré-requisito Gap 1
3. Gap 1 (1d) — run_billing_job deve chamar InvoiceService.emit_invoice (depende de Gap 2). Bloqueia faturamento agendado
4. Gap 5 (4h) — BanError específico → HTTP 503 com Retry-After: 1860 (31min). Higiene de retry
5. Gap 3 — outbox pattern. Defer pós-MVP (alinhado ADR-3).