# Handoff 2026-06-28 - PIX IB/Core/Cabine, comprovantes, reconciliacao e main Este documento e a memoria operacional para continuar com Claude/Codex sem reinventar contexto. Ele fecha a frente aberta pelos problemas de PIX Out no IB, comprovantes divergentes, status falso na cabine/IB, rejeicao `admi.002`, termo "Aceita Liquidacao", saldo/tela incorretos e risco de acoplamento Core -> Cabine. Regra principal: nao inferir. Quando houver divergencia entre tela, Core, cabine PIX e BACEN, a cadeia de prova deve ser: BACEN/SPI/DICT -> cabine PIX -> eventos persistidos/materializados no Core -> IB/fronts. Comprovante so pode representar pagamento liquidado quando houver liquidacao real ou fonte final equivalente. ## 1. Ambiente obrigatorio - Workspace principal: `/Users/luizpenha/monetarie`. - Branch de trabalho no momento deste handoff: `fix/core-etl-visibility`. - HEAD operacional antes deste handoff documental: `e96e1d09`. - `origin/main`, `origin/fix/core-etl-visibility` e `origin/HEAD` apontavam para `e96e1d09` antes do commit deste documento. - AWS correta: conta `990933657879`, regiao `sa-east-1`, profile `vulcimonetarie`. - Nunca usar o profile default do Mac. O wrapper seguro continua sendo: ```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_EC2_METADATA_DISABLED=true aws "$@" } ``` - Homologacao: usar apenas hosts `*-h.monetarie.internal`. - Nao gravar senha, token, JWT, cookie, chave privada, PFX, payload sensivel ou segredo em Markdown, commit, log ou relatorio. - A senha de homologacao mencionada na conversa do dono nao deve ser transcrita neste repo. Quando necessario, buscar segredos no AWS Secrets Manager ou usar input local seguro. ## 2. Memorias e documentos que o proximo agente deve ler Ler nesta ordem: 1. `CLAUDE.md` 2. `docs/handoff/CURRENT.md` 3. Este arquivo: `docs/handoff/2026-06-28-pix-ib-core-handoff-claude.md` 4. `docs/handoff/2026-06-27-consolidacao-pix-core-main.md` 5. `docs/reports/2026-06-27-pix-spb-full-coverage-matrix.md` 6. `docs/handoff/2026-06-27-camt060-resolvido-e-timeline-detalhe-transacao.md` 7. `docs/handoff/2026-06-24-ib-front-proxima-sessao.md` 8. `docs/reports/2026-06-24-coreproviders-parity-study.md` Documentos externos solicitados pelo dono para a atuacao ampla, sempre em sequencia quando a frente for retomada: ```text /Users/luizpenha/Downloads/00_RELATORIO_MESTRE_PRE_CUTOVER.md /Users/luizpenha/Downloads/01_mocks_hardcoded.md /Users/luizpenha/Downloads/02_migrations_indices.md /Users/luizpenha/Downloads/03_i18n_strings_hardcoded.md /Users/luizpenha/Downloads/04_redesconto_desdobro_fluxos_spb.md /Users/luizpenha/Downloads/05_xsd_diff_spi_spb.md /Users/luizpenha/Downloads/06_catalog_versioning.md /Users/luizpenha/Downloads/07_regras_negocio_512.md /Users/luizpenha/Downloads/08_paridade_monetarie_mwbank.md ``` Fontes de paridade e legado autorizadas pelo dono: ```text /Users/luizpenha/coreproviders/* /Users/luizpenha/mwbank/LegadoPIX/* /Users/luizpenha/mwbank/LegadoSPB/* /Users/luizpenha/mwbank/md/* ``` Observacao importante: SGCT/PIX Automatico foi explicitamente deixado para depois. Registrar como pendente, mas nao misturar com a frente atual de PIX Out, comprovante, conciliacao e cabine. ## 3. Estado vivo validado em AWS Validacao feita com `AWS_PROFILE=vulcimonetarie`, conta `990933657879`. Servicos criticos em 2026-06-28 22:38 BRT / 2026-06-29 01:38Z: | Servico | Task definition | Imagem | Desired/Running/Pending | Rollout | |---|---|---|---|---| | `core-api` | `monetarie-core-api-homolog:68` | `monetarie/core-api:homolog-e96e1d09-20260628` | `1/1/0` | `COMPLETED` | | `core-banking-ui` | `monetarie-core-banking-ui-homolog:21` | `monetarie/core-banking-ui:homolog-0dfe794b-20260628` | `1/1/0` | `COMPLETED` | | `core-merchant-ui` | `monetarie-core-merchant-ui-homolog:15` | `monetarie/core-merchant-ui:homolog-0dfe794b-20260628` | `1/1/0` | `COMPLETED` | | `pix-api` | `monetarie-pix-api-homolog:81` | `monetarie/pix-api:homolog-3a5aa273-20260628` | `1/1/0` | `COMPLETED` | | `pix-admin-ui` | `monetarie-pix-admin-ui-homolog:9` | conferir por task definition se necessario | `1/1/0` | `COMPLETED` | | `spb-api` | `monetarie-spb-api-homolog:20` | conferir por task definition se necessario | `1/1/0` | `COMPLETED` | Health checks: - `http://coreapi-h.monetarie.internal/health`: HTTP 200, `{"status":"ok","service":"core"}`. - `http://pixapi-h.monetarie.internal/health`: HTTP 200, `{"status":"healthy","service":"settlement-service"}`. Identidade AWS validada: - Account: `990933657879` - IAM user: `arn:aws:iam::990933657879:user/vulciaws` ## 4. Correcoes que ja estao na main Sequencia relevante de commits em `main`: | Commit | Tema | Resultado | |---|---|---| | `0727e4ff` | PIX AppHdr e netting | Corrige `AppHdr` para BACEN no ICOM, reabre/reusa ciclo de netting, melhora Monitor. E a correcao que responde ao erro `admi.002` sobre ISPB destinatario no AppHdr. | | `3a5aa273` | Comprovante IB exige liquidacao real | Evita comprovante definitivo para PIX ainda nao liquidado e ajusta status/lista PIX. | | `2733b655` | Filtros em transito | Respeita filtros camelCase em in-transit. | | `4478b648` | Merchant receipt branding | Alinha comprovante merchant ao branding Monetarie. | | `8afc0b3e` | Paridade visual coreproviders | Alinha comprovantes Banking e Merchant ao padrao de coreproviders. | | `3c30ecbb` | Reconciliacao IB/in-transit/comprovante | Melhora fluxo de in-transit, rotas e exibicao. | | `d41d18b0` | Cabine como prova pontual | Enriquecimento do comprovante por status da cabine quando ha E2E. | | `c9b6140b` | API da cabine, nao DB direto | `CabinStatusLookup` passa a consultar a API admin da cabine por E2E exato. | | `0dfe794b` | E2E ausente na cabine | Evita fallback DB para E2E ausente na cabine. | | `e96e1d09` | Falha da API da cabine | Evita fallback DB quando a API da cabine falha ou fica indisponivel. | Ponto sobre worktrees: - `etl-autbank` em `acbed1b3`: contido em `HEAD` e em `origin/main`. - `fix/pix-camt060-verifier-spi-msg-audit` em `cedd9203`: contido em `HEAD` e em `origin/main`. - `fix/scd-flow-alignment` em `f9dcf1c8`: o SHA nao e ancestral de `HEAD`, mas o patch de `scripts/etl_remigration_report.cjs` ja estava aplicado por commit equivalente (`efcc9124`) na linha atual. Um `git cherry-pick f9dcf1c8` em 2026-06-28 deu vazio e foi encerrado com `git cherry-pick --skip`. Nao duplicar. - Worktree `scd-alignment` tem `core/backend/deps` e `core/node_modules` nao rastreados. Nao commitar essas pastas. ## 5. Problema original e diagnostico O dono mostrou um fluxo PIX Out pelo IB para a chave: ```text 2e809046-0da3-4fe9-8d02-41162a31e1dc ``` E2E de referencia usado nos testes: ```text E46026562202606281728bgpiecloqud ``` Sintomas observados: - IB mostrava "PIX solicitado" ou "comprovante" como se fosse final, mas a operacao nao chegava corretamente ao destino. - Cabine PIX chegou a exibir "Aceita Liquidacao" para cenarios que exigiam leitura correta de PACS.002/ADMI.002. - Houve rejeicao `admi.002` com descricao: "O ISPB destinatario em AppHdr deve corresponder ao ISPB do Banco Central". - Tela de IB mostrava `Conta Salario`, saldo errado, valor total divergente e apresentacao fora do padrao. - Comprovante tinha divergencias contra coreproviders, faltava tipo de chave, usava informacoes incompletas, tinha historico de branding AvivPay/OWEM e botao com texto inadequado em alguns pontos. - In-transit no IB mantinha operacoes em "Aguardando confirmacao" mesmo quando a cabine ja tinha estado final para um E2E. Conclusao tecnica: - Parte era erro de formacao/integracao PIX na cabine (`AppHdr`). - Parte era erro de semantica de status e comprovante no Core/IB. - Parte era falta de materializacao confiavel no Core para o status final vindo da cabine/BACEN. - Parte era divida de UX/paridade contra coreproviders. ## 6. Estado atual da integracao Core x Cabine O Core nao deve usar a cabine como banco/read model operacional de massa. O que existe hoje: - Consulta pontual por E2E exato, via API admin da cabine: ```text GET /api/v1/transactions?end_to_end_id=&per_page=1 ``` - Implementacao: `core/backend/lib/monetarie/services/pix_providers/in_house/cabin_status_lookup.ex`. - Chamadores principais: - `core/backend/lib/monetarie_web/controllers/v2/transaction_controller.ex` - `core/backend/lib/monetarie/services/pix_providers/in_house/adapter.ex` - Essa consulta e usada para detalhe/comprovante/status/reprocessamento pontual, nao para listar 10 milhoes de operacoes/dia. Mudanca critica: - Antes havia fallback para consulta direta no banco da cabine em algumas falhas. - Em `e96e1d09`, com API configurada, falha da API nao cai mais em SQL direto. - Se a API da cabine estiver configurada e falhar, o lookup falha fechado. - Fallback DB ficou restrito ao caso de API nao configurada, para uso local/legado. Arquitetura correta para escala: 1. Cabine PIX processa DICT/SPI/BACEN e recebe `pacs.002`/`admi.002`. 2. Cabine publica evento definitivo ou o Core consome por canal assincrono controlado. 3. Core materializa status, participantes, E2E, tipo de chave, autenticacao e datas. 4. IB/Merchant leem o Core materializado. 5. Consulta direta a cabine fica para reconciliacao/auditoria/reprocesso manual. Nao implementar lista/in-transit chamando cabine linha a linha. Para 10M/dia isso tem que ser orientado a eventos e/ou tabela materializada, com indices por E2E, merchant/account/status/data. ## 7. Evidencias tecnicas mais recentes Lookup vivo por ECS Exec em `core-api` para: ```text E46026562202606281728bgpiecloqud ``` Retorno da cabine via API: ```text status: "ACSC" status_id: 4 amount: "0.01000" creditor_name: "Mercenarios Stallone Ltda" creditor_ispb: "04838403" creditor_institution: "AVIV INSTITUICAO DE PAGAMENTO" creditor_key: "2e809046-0da3-4fe9-8d02-41162a31e1dc" ``` Validacoes de API Core feitas na frente: - Comprovante por `PIXOUT-e5e2c7fc2be99408` e por outbound id `e5e2c7fc2be994083df96ac0e1f00800` retornaram `status: "settled"` depois do enriquecimento. - Valor em centavos: `amount: 1` para R$ 0,01. - `auth_code` presente. - `completed_at` preenchido. - `pix.end_to_end_id` presente. - `pix.chave_pix` presente. - Tipo de chave deve ser `evp` quando vindo de cabin key type ou detectado pela chave aleatoria. Validacoes automatizadas executadas: ```bash pnpm --filter @monetarie/banking test:run src/views/receipts/__tests__/ReceiptView.test.ts pnpm --filter @monetarie/merchant-portal test:run src/views/receipts/__tests__/ReceiptView.test.ts mix compile --force git diff --check ``` Resultado: - Banking receipt tests: passaram. - Merchant receipt tests: passaram. - `mix compile --force`: passou com warnings pre-existentes. - `git diff --check`: passou antes dos commits de codigo. Limitacao conhecida: - `MIX_ENV=test mix test ...` completo foi bloqueado localmente por autenticacao do banco local (`FATAL 28P01 invalid_password` para usuario `monetarie`). Nao usar isso como prova negativa de codigo; e problema de ambiente local. ## 8. Comprovantes e paridade coreproviders Arquivos centrais: - `core/apps/banking/src/views/receipts/ReceiptView.vue` - `core/apps/merchant/src/views/receipts/ReceiptView.vue` - `core/apps/banking/src/views/receipts/__tests__/ReceiptView.test.ts` - `core/apps/merchant/src/views/receipts/__tests__/ReceiptView.test.ts` O que foi ajustado: - Layout aproximado ao padrao coreproviders. - Branding Monetarie no comprovante. - Remocao de marca d'agua OWEM/AvivPay no componente de comprovante. - Texto de botao tratado como "Imprimir comprovante". - Remocao de "Protocolo de solicitacao" do comprovante PIX. - Inclusao de "Tipo de chave" quando a API fornece ou quando e detectavel. - Tratamento de status para nao apresentar comprovante definitivo em operacao nao liquidada. Testes cobrem explicitamente: - Nao conter `receipt-watermark`. - Nao conter `OWEM`. - Nao conter `AvivPay` nem `Comprovante - AvivPay` no markup de comprovante. - Nao conter `Protocolo de solicitacao`. - Conter informacoes de pagamento e tipo de chave quando presentes. Ponto de atencao: - Ainda existem strings globais `AvivPay` em i18n/temas fora do componente de comprovante. Isso e outra frente de rebrand/i18n, nao deve ser confundido com regressao do comprovante se os testes de receipt seguirem verdes. - Se o dono comparar contra coreproviders, validar tambem tela e impressao/PDF com screenshot atual, nao so teste unitario. ## 9. Evidencias locais nao commitadas Existem artefatos locais em: ```text docs/reports/screenshots/2026-06-28-* ``` Tamanho aproximado total: poucos MB. Nao commitar bruto sem sanitizacao. Motivo: alguns JSONs locais de validacao contem token/JWT de login e dados pessoais de homologacao. Preservar localmente, mas se for versionar, gerar versao sanitizada primeiro. Itens uteis, apos sanitizar se necessario: - `docs/reports/screenshots/2026-06-28-postdeploy-ib-pix-out/` - `docs/reports/screenshots/2026-06-28-receipt-coreproviders-parity/` - `docs/reports/screenshots/2026-06-28-merchant-receipt-validation/` - `docs/reports/screenshots/2026-06-28-pix-hml-old-e2e-monitor.json` Importante: alguns desses artefatos foram capturados antes dos ultimos commits de correcao de `tipo_chave`/enriquecimento por cabine. Nao usar como fonte final sem recaptura. ## 10. HSM RTM: porta correta atual Nao reintroduzir `:6443` como endpoint operacional atual de PIX/SPB. Estado atual em codigo: - `infra/aws/greenfield/locals.tf` - `local.rtm_hsm_base_url = "https://monetarie-hsm-hml.priv.rtmcloud.net.br"` - Comentario do arquivo indica RTM Cloud Link em HTTPS 443. - `pix/backend/config/runtime.exs` e `spb/services/bacen_gateway/config/runtime.exs` tambem usam `https://monetarie-hsm-hml.priv.rtmcloud.net.br` como default/fonte. Documentos antigos que falam em `cloudhsm-hml...:6443` sao historicos da etapa de diagnostico. A orientacao atual do dono e do codigo e porta 443 no host `monetarie-hsm-hml.priv.rtmcloud.net.br`. ## 11. Status e termos PIX na cabine/admin O termo "Aceita Liquidacao" foi criticado e deve ficar fora da UX final. Diretriz: - Para status final positivo de liquidacao, usar "Liquidado". - Para pendente, usar "Em processamento" ou "Aguardando confirmacao" conforme contexto. - Para rejeicao `admi.002`/erro de processamento, nao mostrar como liquidado. - So marcar "Liquidado" com `ACSC`/status final equivalente. Ponto importante: - `admi.002` nao e `pacs.002` de liquidacao. Se houver `admi.002` com rejeicao, a operacao precisa aparecer como rejeitada/erro, nao como liquidada. ## 12. In-transit e reconciliacao O endpoint generico de in-transit no Core nao deve consultar a cabine em massa. Ele le dados do Core, com limite pequeno, e deve ser alimentado por materializacao ou reprocesso pontual. Estado atual: - Fluxo genericamente limita a leitura no Core. - Reprocessamento/status pontual pode consultar a cabine por E2E. - O E2E alvo liquidado nao deveria permanecer como pendente apos reconciliacao. Risco ainda aberto: - Operacoes antigas que ficaram pendentes antes dos fixes podem continuar na lista ate passarem por reprocesso/reconciliacao. - Nao resolver isso com loop de chamadas a cabine para cada linha da lista. Proximo desenho correto: - Criar worker de reconciliacao/event consumer que materialize `settled/rejected` no Core a partir de evento da cabine. - Indices necessarios: E2E, outbound_request_id/client_request_id, account_id, merchant_id, status, inserted_at/updated_at. - Reprocessar legados por lote controlado, com rate limit e checkpoint. ## 13. Escala: 10M operacoes/dia Para 10M/dia, a regra e: - Nao usar a cabine como read model quente do IB/Core. - Nao fazer lookup por E2E em toda renderizacao de lista. - Nao abrir SQL direto do Core no banco da cabine. - Nao autenticar na API da cabine a cada item. O que esta aceitavel agora: - Lookup pontual de um unico E2E para comprovante/detalhe/reprocesso. - Falha fechada quando a API da cabine falha. O que precisa endurecer: - Token/session cache para API admin da cabine. - Circuit breaker e rate limit. - Persistencia assincrona do status final no Core. - Reconciliacao por lote para legados. - Metricas de latencia, erro e volume de lookup por E2E. ## 14. SPB/Redesconto/Desdobro e matriz ampla O dono pediu cobertura ampla contra LegadoPIX, LegadoSPB, catalogo 5.12, redesconto, desdobro, timeline das cabines e regras de negocio. Nao declarar "100% coberto" sem matriz item a item e evidencia. Ja existe base para isso em: - `docs/reports/2026-06-27-pix-spb-full-coverage-matrix.md` - Documentos `00` a `08` em `/Users/luizpenha/Downloads` - Legados em `/Users/luizpenha/mwbank/LegadoPIX`, `/Users/luizpenha/mwbank/LegadoSPB` e `/Users/luizpenha/mwbank/md` Ao retomar: - Separar PIX, SPB, Core, IB, Merchant, Admin, Infra. - Para cada mensagem/fluxo, registrar: fonte oficial, legado, codigo atual, teste vivo, lacuna, prioridade, owner. - Nao misturar `trck002` com SPB. Validar dominio da mensagem antes de classificar. - SGCT/PIX Automatico fica anotado para depois, conforme decisao do dono. ## 15. Comandos uteis de validacao Status git e main: ```bash git status --short --branch git log --oneline --decorate -12 git rev-parse HEAD origin/main origin/fix/core-etl-visibility ``` Servicos ECS: ```bash awsmon ecs describe-services \ --cluster monetarie-greenfield-homolog \ --services core-api core-banking-ui core-merchant-ui pix-api pix-admin-ui spb-api \ --query 'services[].{service:serviceName,desired:desiredCount,running:runningCount,pending:pendingCount,taskDefinition:taskDefinition,rollout:deployments[0].rolloutState}' \ --output table ``` Health: ```bash curl -sS -m 10 -i http://coreapi-h.monetarie.internal/health curl -sS -m 10 -i http://pixapi-h.monetarie.internal/health ``` Imagens task definition: ```bash awsmon ecs describe-task-definition \ --task-definition monetarie-core-api-homolog:68 \ --query 'taskDefinition.containerDefinitions[].image' \ --output text ``` Testes de comprovante: ```bash pnpm --filter @monetarie/banking test:run src/views/receipts/__tests__/ReceiptView.test.ts pnpm --filter @monetarie/merchant-portal test:run src/views/receipts/__tests__/ReceiptView.test.ts ``` Compilacao Core: ```bash cd core/backend mix compile --force ``` ## 16. Proximas acoes recomendadas 1. Atualizar local `main` para o mesmo commit de `origin/main` depois do commit deste handoff. 2. Recapturar screenshots de IB e Merchant apos os ultimos fixes, sem gravar token em JSON commitado. 3. Validar de ponta a ponta um novo PIX Out de R$ 0,01 para a chave EVP alvo: DICT -> envio -> cabine PIX com `ACSC` ou rejeicao real -> Core materializado -> IB comprovante -> in-transit sem stale para o E2E. 4. Implementar materializacao assincrona Core para status final da cabine, evitando dependencia sincrona do comprovante em consulta a cabine. 5. Rodar matriz ampla PIX/SPB contra documentos `00` a `08`, LegadoPIX, LegadoSPB e catalogo 5.12. Nao declarar cobertura total sem evidencia por item. 6. Manter SGCT/PIX Automatico anotado para etapa posterior.