# Fase 0: por que o PIX enviado de R$ 2.500 da M2 ficou sem recebedor no extrato (PROD, read-only) Data: 2026-07-15. Investigação SOMENTE LEITURA em produção (cluster `monetarie-greenfield-prod`), via `bin/monetarie rpc` com `Repo.query!` (apenas SELECT) e um GET à API admin da cabine. Nenhuma escrita, nenhum deploy, nenhum reinício. ## 1. O caso Tela Contas Correntes do coreadmin de PROD, conta `000000891` (id 2472), titular "M2 Serviços Médicos em Clinica Geral Ltda" (CNPJ 36.588.881/0001-50): débito "PIX enviado" de R$ 2.500,00 em 15/07/2026 com a coluna Recebedor vazia ("-"). ## 2. Evidência do caso (dados reais de PROD) Lançamento em `account_entries` (amount em SUBCENTAVOS): ``` id e8a0201b-14d9-4097-9a0a-606da394ec63 account_id 2472 (conta 000000891, M2) amount -25000000 (R$ 2.500,00) description "PIX enviado" reference E46026562202607151443g2y2zizu2ig entry_date 2026-07-15 (inserted_at 14:45:17 UTC) metadata {"creditor_ispb": "00416968", "end_to_end_id": "E46026562202607151443g2y2zizu2ig", "source": "pix_outbound_settled", "transaction_id": "PIXMANE46026562202607151443g2y2zizu2ig"} ``` O metadata NÃO tem `counterparty_name` nem `counterparty_document`. Só o ISPB do recebedor chegou. Linha em `transactions` (partição 2026-07): ``` transaction_id PIXMANE46026562202607151443g2y2zizu2ig end_to_end_id E46026562202607151443g2y2zizu2ig type/direction pix / outbound, payment_status settled counterparty_name NULL recipient_key 022*******86 (CPF, mascarado neste relatório) merchant_id NULL description "Pix Eli Simao Goulart" (texto digitado/derivado na tela da cabine) metadata {"source": "pix_manual_register", "settlement_source": "spi_pacs002", "spi_status": "settled", "spi_status_id": 4, "pix_transaction_id": 13663, "tb_transfer_id": "CB89528478360D1C45C50919D2D86202", ...} ``` O metadata da transação NÃO tem `recipient_name`, `recipient_document` nem `recipient_ispb`. `outbound_requests`: NENHUMA linha para esse E2E ou transaction_id. Isso é o esperado, `move_to_transactions` apaga a request ao materializar a transação (`core/backend/lib/monetarie/use_cases/payments/outbound_requests.ex:145`). A cabine PIX, no MESMO E2E, conhece o recebedor por completo (SELECT no banco da cabine, task `pix-api` de PROD): ``` monetarie_spi.messages: id 13663, pacs.008, OUTBOUND, status_id 4 (ACSC), debtor_ispb 46026562, creditor_ispb 00416968 monetarie_spi.payments: creditor_name "ELI SIMAO GOULART", creditor_cpf_cnpj 022*******86, creditor_account 052*******78, creditor_proxy 022*******86, debtor_name "M2 Serviços Medicos", initiation_form "DICT" ``` Ou seja: o dado existiu na origem (consulta DICT resolvida na cabine) e nunca entrou no Core. ## 3. Causa raiz: a cadeia do envio manual descarta o recebedor em DOIS elos O canal é o ENVIO MANUAL pela cabine PIX (tela Nova Transação do pix-admin), prefixo `PIXMAN` e `metadata.source = "pix_manual_register"`. A cadeia, com arquivo e linha: 1. A cabine TEM o recebedor no create: `PaymentController.create` completa os campos do recebedor com a consulta DICT cacheada (`@consult_field_map` inclui `creditor_name`, `creditor_document`, `creditor_ispb`; `pix/backend/apps/spi_service/lib/spi_service_web/controllers/payment_controller.ex:144-151`) e persiste tudo em `monetarie_spi.payments`. 2. ELO 1 (registro do débito no Core): `register_debtor_debit` monta o request com APENAS `account`, `document`, `amount_subcent`, `end_to_end_id`, `recipient_key` e `description` (`payment_controller.ex:400-424`; contrato em `pix/backend/apps/spi_service/lib/spi_service/core_debit_validation.ex:76-98`). `creditor_name`, `creditor_document` e `creditor_ispb` são descartados aqui. 3. No Core, `PixDebitValidator.insert_pix_request` persiste a `outbound_request` só com `recipient_key` e `description`; os campos `recipient_name`, `recipient_document`, `recipient_ispb` (que EXISTEM no schema) ficam NULL (`core/backend/lib/monetarie/infra/nats/responders/pix_debit_validator.ex:181-204`). 4. Na liquidação, o `AtomicPaymentHandler.post_and_settle(req, payload)` repassa o payload do evento (NÃO é vazio nesse caminho; o payload vazio só acontece no caminho de recuperação, `atomic_payment_handler.ex:206`). `move_to_transactions` copia `recipient_*` da request para o metadata da transação via `request_metadata/1` (`outbound_requests.ex:248-256`), mas não havia nada para copiar. 5. ELO 2 (evento settled da cabine): `settled_event_payload` publica `creditor_ispb` mas NÃO publica `creditor_name` nem `creditor_document` (`pix/backend/apps/spi_service/lib/spi_service/workers/status_updater.ex:276-296`). Por isso o fallback de 14/07 `payload["creditor_name"]` em `outbound_counterparty` (`core/backend/lib/monetarie/use_cases/pix/statement_entries.ex:304-306`) NUNCA dispara para esse fluxo, em nenhum dos dois caminhos (Máquina A e PixHandler linha 402). 6. Resultado: `record_outbound_settled` calcula `counterparty = tx.counterparty_name (NULL) || tx.metadata["recipient_name"] (ausente) || payload["creditor_name"] (ausente)` e grava o extrato sem recebedor. O `creditor_ispb` do lançamento veio do payload do evento, o que prova que o payload foi repassado. ## 4. Veredito das hipóteses - (a) A origem nunca entregou o dado ao Core: VENCEDORA, com a precisão de que a fonte (cabine) TINHA o dado e o descartou na fronteira (elo 1), e o evento settled também não o carrega (elo 2). - (b) O dado entrou na `outbound_request` e se perdeu na materialização: REFUTADA. `request_metadata/1` copia corretamente; os campos nunca foram preenchidos. Provado pela transação sem `recipient_*` e pelo contrato do register. - (c) O evento settled trazia `creditor_name` e o caminho usado ignora o payload: REFUTADA nas duas partes. O payload É repassado (o `creditor_ispb` do lançamento veio dele), mas o evento não traz o nome (contrato do `settled_event_payload`). ## 5. A cabine conhece o recebedor? Sim. E o lookup HTTP do Core está quebrado em PROD - Banco da cabine (read-only): `monetarie_spi.payments` tem nome, CPF, conta e chave do recebedor para o E2E do caso (seção 2). A fonte para backfill EXISTE e é confiável. - `Monetarie.Services.PixProviders.InHouse.CabinStatusLookup.by_end_to_end_id/1` em PROD retornou `{:error, {:auth_failed, 401}}` com log `[PixCabinStatusLookup] cabin login failed: status=401`. O módulo ESTÁ configurado (tentou o login em `/api/v1/auth/login` da cabine), mas a credencial do Core para a API admin da cabine está inválida em PROD. Achado colateral que afeta reconciliação e reprocesso pontual, e qualquer backfill via API. Corrigir a credencial (secret da task do core-api) ou fazer o backfill por outro caminho. ## 6. Dimensionamento do backfill (contagens de PROD) Total de `account_entries`: 231.542 (195.357 créditos, 36.185 débitos). Débitos sem contraparte (nem `counterparty_name` nem `recipient_name` no metadata), por source: | source | débitos | |---|---| | autbank (acervo ETL do legado) | 36.173 | | etl_opening | 8 | | pix_outbound_settled | 3 | Créditos sem pagador (nem `payer_name` nem `counterparty_name`), por source: | source | créditos | |---|---| | autbank (acervo ETL do legado) | 195.175 | | etl_opening | 59 | | spb_inbound_credit | 7 | | pix_inbound_settled | 3 | | pix_return_received | 3 | | (sem source: remediação manual `pix_in_remediation_0709`) | 1 | Detalhe dos casos do caminho VIVO (alvo real do backfill; acervo `autbank`/`etl_opening` é massa histórica do ETL, fora do escopo deste fix): - 3 débitos `pix_outbound_settled`, TODOS envio manual (`PIXMAN...`): R$ 7.000,00 (conta 2059, 15/07), R$ 2.500,00 (conta 2472, o caso M2), R$ 2,00 (conta 1644, 15/07). Desde 2026-06-01 existem 5 transações PIX outbound liquidadas no total: 0 com `counterparty_name`, 4 sem nome algum (as 4 manuais), 1 com nome só no metadata (`PIXOUT-4a0a7ea59c6e9508`, canal IB, 09/07, anterior ao hook de extrato). - 3 créditos `pix_inbound_settled` sem pagador: R$ 20.000,00 (conta 2867, 14/07), R$ 1.370,00 (conta 2949, 13/07), R$ 2,00 (conta 1644, 13/07). O evento de crédito não trouxe `debtor_name`. - 3 `pix_return_received` (conta 2031): têm o nome na description ("Devolução recebida - ...") mas não têm `counterparty_name` no metadata (só ajuste de metadata, exibição já funciona). - 1 crédito de remediação manual do incidente pacs.008 de 09/07 (R$ 4,54, conta 2677), sem payer_name. - 7 `spb_inbound_credit` sem pagador: TODOS `message_type = STR0006` (o parser de STR0006 não extrai as partes; gap já conhecido da frente SPB saldo vivo, 6 dos 7 na conta 2627). Os STR0008 do acervo vêm ricos (nome, documento, agência, conta do pagador). Pertence à frente SPB, não ao fix PIX. - TED enviada: população ZERO desde 2026-06-01 (`transactions` não tem nenhuma TED outbound settled/completed no recorte), logo 0 sem extrato. Não há acervo PROD para backfill de TED enviada nesse recorte. - TEF `_RCV`: população ZERO desde 2026-06-01, logo 0 sem extrato. Recorte usado nas queries de `transactions`: `started_at >= '2026-06-01'` (tabela particionada por mês; PROD entrou em operação PIX em julho). Nota de proveniência: o 4º débito `pix_outbound_settled` (R$ 1,00, E2E `E46026562202607142123qpkge6wcevr`, 14/07) TEM nome e documento no metadata, mas foi inserido às 22:57:18 UTC, 1h33min DEPOIS da liquidação (21:24:06), ou seja, é inserção posterior (reparo do acervo na sessão de 14/07), não produto do caminho vivo. O caminho vivo nunca gravou recebedor para envio manual. ## 7. Decisão de fix de origem (Task 8) O fix correto é carregar o recebedor de ponta a ponta no fluxo do envio manual, nos DOIS elos: 1. Cabine, `register_debtor_debit` (`payment_controller.ex:417-423`): incluir `recipient_name`, `recipient_document` e `recipient_ispb` no request do register, a partir de `params["creditor_name"]`, `params["creditor_document"]`, `params["creditor_ispb"]` (já presentes após `merge_consult_defaults`). Contrato em `core_debit_validation.ex` `register/1` acompanha. Nota da implementação (Task 8): as chaves escolhidas para o FIO foram `creditor_name`/`creditor_document`/`creditor_ispb` (vocabulário canônico da cabine e do fallback do evento settled); o Core as mapeia para as colunas `recipient_*` da `outbound_request` no `insert_pix_request`. 2. Core, `PixDebitValidator.insert_pix_request` (`pix_debit_validator.ex:181-204`): persistir esses campos na `outbound_request` (as colunas já existem). Daí em diante o pipeline atual já resolve sozinho: `request_metadata/1` leva para `transactions.metadata` e `outbound_counterparty/2` usa `tx.metadata["recipient_name"]`. 3. Defesa em profundidade (cobre a classe da hipótese c para TODOS os fluxos outbound): adicionar `creditor_name` e `creditor_document` ao `settled_event_payload` da cabine (`status_updater.ex:276-296`). O contrato do evento diz "não mudar as chaves"; ADICIONAR chaves é compatível com consumidores existentes, e o fallback `payload["creditor_name"]` de 14/07 passa a funcionar. Compatibilidade de versão: Core antigo ignora campos extras do register (lê o map por chave); cabine antiga sem os campos mantém o comportamento atual (fallback do payload cobre quando o item 3 estiver no ar). Nenhuma migration necessária. Backfill (Task 10/11): para os 3 débitos manuais e os 3 créditos sem pagador, a fonte é o banco da cabine (`monetarie_spi.payments` por `message_id` = `metadata.pix_transaction_id`, ou join por E2E em `monetarie_spi.messages`). O caminho HTTP (`CabinStatusLookup`) exige antes o conserto da credencial 401 em PROD. ## 8. Como reproduzir (read-only) ```bash awsmon() { env -u AWS_ACCESS_KEY_ID -u AWS_SECRET_ACCESS_KEY -u AWS_SESSION_TOKEN AWS_PROFILE=vulcimonetarie AWS_REGION=sa-east-1 aws "$@"; } # 1. Task de PROD do core-api (e pix-api para o banco da cabine) awsmon ecs list-tasks --cluster monetarie-greenfield-prod --service-name core-api awsmon ecs list-tasks --cluster monetarie-greenfield-prod --service-name pix-api # 2. rpc read-only (o código Elixir vai em base64 para não brigar com o quoting do ECS exec) B64=$(base64 -i consulta.exs | tr -d '\n') script -q /dev/null awsmon ecs execute-command --cluster monetarie-greenfield-prod \ --task --container core-api --interactive \ --command "bin/monetarie rpc 'Code.eval_string(Base.decode64!(\"$B64\"))'" # (no pix-api o binário é bin/monetarie_pix) ``` Queries usadas (todas SELECT, via `Monetarie.Repo.query!/2` no core-api e `Shared.Repo.query!/2` no pix-api): ```sql -- caso M2 SELECT id, account_id, amount, description, category, reference, entry_date, metadata FROM account_entries WHERE amount = -25000000 AND entry_date >= '2026-07-14' ORDER BY inserted_at DESC LIMIT 5; SELECT a.id, a.account_number, u.name, u.tax_id FROM accounts a JOIN users u ON u.id = a.user_id WHERE u.tax_id LIKE '36588881%'; SELECT transaction_id, end_to_end_id, type, direction, payment_status, counterparty_name, recipient_key, merchant_id, metadata FROM transactions WHERE started_at >= '2026-07-01' AND (end_to_end_id = 'E46026562202607151443g2y2zizu2ig' OR transaction_id = 'PIXMANE46026562202607151443g2y2zizu2ig'); SELECT * FROM outbound_requests WHERE transaction_id = 'PIXMANE46026562202607151443g2y2zizu2ig' OR end_to_end_id = 'E46026562202607151443g2y2zizu2ig'; -- 0 linhas -- cabine (pix-api) SELECT id, end_to_end_id, message_code, direction, status_id, debtor_ispb, creditor_ispb FROM monetarie_spi.messages WHERE end_to_end_id = 'E46026562202607151443g2y2zizu2ig'; SELECT m.end_to_end_id, p.creditor_name, p.creditor_cpf_cnpj, p.creditor_account, p.creditor_proxy, p.debtor_name, p.initiation_form FROM monetarie_spi.payments p JOIN monetarie_spi.messages m ON m.id = p.message_id WHERE m.end_to_end_id = 'E46026562202607151443g2y2zizu2ig'; -- amostragem e dimensionamento (core) SELECT reference, metadata FROM account_entries WHERE metadata->>'source' = 'spb_inbound_credit' ORDER BY inserted_at DESC LIMIT 20; SELECT metadata->>'source' AS src, count(*) FROM account_entries WHERE amount > 0 AND metadata->>'payer_name' IS NULL AND metadata->>'counterparty_name' IS NULL GROUP BY 1 ORDER BY 2 DESC; SELECT metadata->>'source' AS src, count(*) FROM account_entries WHERE amount < 0 AND metadata->>'counterparty_name' IS NULL AND metadata->>'recipient_name' IS NULL GROUP BY 1 ORDER BY 2 DESC; SELECT count(*) FROM transactions t WHERE t.started_at >= '2026-06-01' AND t.type = 'ted' AND t.direction = 'outbound' AND t.payment_status IN ('settled','completed') AND NOT EXISTS (SELECT 1 FROM account_entries e WHERE e.reference IN (t.end_to_end_id, t.transaction_id)); SELECT count(*) FROM transactions t WHERE t.started_at >= '2026-06-01' AND t.transaction_id LIKE '%\_RCV' AND NOT EXISTS (SELECT 1 FROM account_entries e WHERE e.reference IN (t.end_to_end_id, t.transaction_id)); ``` Consulta à cabine via Core (o GET que falhou com 401): ```elixir Monetarie.Services.PixProviders.InHouse.CabinStatusLookup.by_end_to_end_id("E46026562202607151443g2y2zizu2ig") # => {:error, {:auth_failed, 401}} ``` ## 9. Achados colaterais (fora do escopo do fix, registrar) 1. Credencial do Core para a API admin da cabine PIX inválida em PROD (login 401). Afeta reconciliação de status e reprocesso pontual, além de backfill via API. 2. STR0006 sem partes no extrato (7 créditos `spb_inbound_credit` com payer nulo, todos STR0006). Já mapeado na frente SPB saldo vivo de 15/07. 3. O crédito da remediação de 09/07 (R$ 4,54) está com `category = "deposit"` e metadata mínimo, sem payer_name (inserção manual de incidente). 4. Os 3 lançamentos de devolução recebida têm o nome na description mas não no metadata (`counterparty_name` ausente), o que pode afetar telas que leem o metadata em vez da description. ## 10. Execução local (Task 11): dry_run, apply idempotente e reconcile validados em 2026-07-15 O `Monetarie.Release.StatementBackfill` foi executado no ambiente local de desenvolvimento, com o código deste worktree rodando NATIVAMENTE contra o Postgres de dev (container `monetarie-pg`, `localhost:15432`, banco `mon_core`), via `mix run --no-start` com boot mínimo (só o `Repo.Base`; sem NATS, Oban ou consumers, porque o ambiente é compartilhado com as sessões PIX e SPB). Nada de HML/PROD foi tocado. ### 10.1 Estado do ambiente encontrado - `mix ecto.migrations` mostrou 16 migrations pendentes no `mon_core` local (acervo da main de 07/07 a 14/07). NENHUMA foi rodada. Único ajuste: as 2 colunas `bacen_reference`/`bacen_reference_type` de `transactions` foram criadas por DDL idempotente idêntico ao da migration pendente `20260714150000` (que é `add_if_not_exists`, então o `ecto.migrate` futuro segue limpo), porque o schema Ecto do worktree já as referencia e sem elas nenhuma query em `Transaction` roda. - O `mon_core` local estava VAZIO de dados de negócio (0 users, 0 accounts, 0 transactions, 0 account_entries; conferido por SQL). O acervo local antigo não existe mais nesta máquina. - TigerBeetle local PARADO (container `monetarie-tigerbeetle` exited há 3 semanas; não foi religado, por regra do ambiente compartilhado). Cabine PIX local fora do ar (lookup best-effort não exercitado). ### 10.2 Execução 1: sequência canônica no `mon_core` de dev `dry_run()` = todas as 7 categorias com 0 candidatos (banco vazio); `apply()` = tudo `%{found: 0, updated: 0, created: 0, skipped: 0}`; segundo `apply()` idêntico; `reconcile()` = `[]`. Valor da execução: prova que o módulo roda ponta a ponta contra o SCHEMA REAL (transactions particionada por RANGE, operadores JSONB, dedup por reference+source) sem erro; mas com 0 candidatos ela não exercita as curas. ### 10.3 Execução 2: validação com fixtures em banco isolado (mesmo PG, zero impacto no dev) Para dar dentes à validação sem alterar dados compartilhados, foi criado um banco descartável `mon_core_backfill_check` (`CREATE DATABASE ... TEMPLATE mon_core`, mesmo container) com 1 candidato curado por categoria (6 transactions + 4 entries, contas/users/bank de fixture com ids 999xxx). Resultado da mesma sequência: | categoria | dry_run | apply #1 | apply #2 (idempotência) | |---|---|---|---| | pix_out_counterparty | 1 | found 1, updated 1 | 0 | | tef_out_counterparty | 1 | found 1, updated 1 | 0 | | pix_in_document | 1 | found 1, updated 1 | 0 | | ted_out_missing_entry | 1 | found 1, created 1 | 0 | | ted_in_document | 1 | found 1, updated 1 | 0 | | internal_missing_legs | 1 | found 1, created 1 | 0 | | tef_missing_rcv_tx (informativa) | 1 | found 1, skipped 1 | found 1, skipped 1 | O segundo `apply` zera TODAS as categorias mutantes (updated = created = 0); a informativa `tef_missing_rcv_tx` continua found 1/skipped 1 em toda rodada POR DESIGN (ela nunca escreve; recriar a transaction `_RCV` ficou fora do apply por decisão do dono). `dry_run` pós-apply confirma: só a informativa permanece. Amostras de cura (metadata antes vs depois, conferidas por SELECT): - `E46026562...T11A0` (PIX out): antes sem contraparte; depois `counterparty_name = "Maria Recebedora Silva"`, `counterparty_document = "98765432100"` (vindos de `transactions.metadata.recipient_*`) e description `"PIX enviado - Maria Recebedora Silva"`. Amount, status e reference intactos. - `TEF-T11B` (TEF out): depois `counterparty_name = "Recebedor TEF T11"`, `counterparty_document = "12345678909"` (titular da conta destino via `to_account_id`), description com o nome anexado. - `STR20260701000000042` (TED in): depois `payer_document = "55566677788"`, `payer_name = "Empresa Pagadora SA"` (da transaction espelho `SPBCRSTR...` do Core); description NÃO alterada. - Entries criadas: `TEDOUT-T11D` (débito -99990, `"TED enviada - Fornecedor XYZ Ltda"`, source `pix_outbound_settled`) e `PIXINT-T11F_RCV` (crédito +25000, `"PIX recebido - Conta Origem Interna"`, source `pix_internal`), ambas com o MESMO par reference/source do caminho vivo (dedup enxerga). `reconcile` em 3 modos: 1. Default (TB fora): não crasha; o lookup trata `noproc` como transiente (3 tentativas) e a conta entra na lista com `tb_balance: nil, drift: nil, error: {:service_unavailable, ...}` e `extrato_sum: -20670` (soma CORRETA das 6 entries pós-cura: -123450 -50000 +77770 +150000 -99990 +25000). 2. `balance_fn` stub com saldo igual ao extrato: `[]` (0 divergências). 3. Stub com drift proposital (saldo TB simulado sem o débito do PIX out): acusou `drift: -123450` exato. O banco de fixtures foi DROPADO ao final; o `mon_core` de dev ficou como estava (mesmos 0s, mais as 2 colunas do item 10.1). ### 10.4 Limitações desta validação local - O `reconcile` contra o TigerBeetle REAL não foi exercitado (TB local parado; religar container fugia da regra do ambiente compartilhado). O comportamento fail-soft com TB fora está provado; o batimento de verdade acontece em HML/PROD onde o TB está vivo. - O caminho `CabinStatusLookup` (fonte cabine para skipped) não foi exercitado (cabine local fora; em PROD está 401 de qualquer forma, ver §5). Todas as curas validadas usaram as fontes locais (transactions do Core), que é o caminho dominante do dimensionamento da Fase 0. - O acervo real não existe no dev local; as contagens de referência para HML/PROD continuam sendo as do §6. ### 10.5 Roteiro recomendado para HML/PROD 1. `bin/monetarie rpc 'Monetarie.Release.StatementBackfill.dry_run()'` (read-only) e conferir as contagens contra o §6 (ordens de grandeza: dezenas/centenas; qualquer número fora disso = parar e investigar). 2. Revisão do dono sobre as contagens do dry_run (inclusive a informativa `tef_missing_rcv_tx`, que NÃO será tocada). 3. `apply(limit: 500)` em janela (fora de operação de money-path ao vivo), repetindo até todas as categorias mutantes zerarem; o GOTCHA do §7 vale: derivados que somam `account_entries` (adiantamento_trigger, workers de crédito) vão se mover junto com as entries criadas, o operador precisa saber. 4. Re-rodar `apply` uma vez a mais como prova de idempotência no dado vivo (esperado: tudo 0 exceto a informativa). 5. `reconcile()` com TB vivo; investigar qualquer drift != 0 ANTES de dar a frente por encerrada (skipped por cabine 401 são esperados e ficam para a frente SPB/credencial).