# Plano de correção dos gaps de paridade DICT v2.11.0 + ICOM/SPI

> **For Claude:** executar via subagent-driven-development, UMA task por vez (sequencial, sem paralelo) para evitar overlap de arquivos. Revisar entre tasks. TDD estrito por gap.

**Goal:** fechar todos os gaps confirmados das matrizes `2026-07-07-paridade-dict-v2110-matriz.md` e `2026-07-07-paridade-icom-spi-fluxos-matriz.md`, com prova por teste e deploy vivo.

**Sequência (ordenada para não colidir arquivos):** cada task toca um conjunto disjunto do anterior. Deploy e evidência agrupados ao final.

**Convenções:** pt-br sem travessão; trailer de commit padrão; pré-existentes conhecidas (3 reda namespace no shared, 1 dict headers, 14 cert no settlement_web, theme.spec no front) não contam. PG local `DB_PASS=monetarie` porta 15432.

---

### Task 1 — CID full-sync + event-poll (ligar e validar) [DICT gap #1, alto]

**Área:** `apps/dict_service/lib/dict_service/sync/cid_sync_service.ex` + config/runtime + env ECS.
**Gap:** `CID_FULL_SYNC_ENABLED=false`, `CID_EVENT_POLL_ENABLED=false` por default — base de chaves não reconcilia com o DICT.
**Passos:** (1) confirmar que o serviço liga e agenda corretamente quando as flags = true (ler o boot gating); (2) NÃO mudar o default do código (flag OFF é seguro), mas preparar para ligar em HML via env; (3) teste de que, com flag on, o GenServer agenda full-sync e event-poll nos intervalos configurados; (4) na fase de deploy, setar `CID_FULL_SYNC_ENABLED=true`/`CID_EVENT_POLL_ENABLED=true` na task-def do pix-api com intervalo seguro e validar vivo (1 ciclo de full-sync + 1 event-poll sem erro, sem estourar budget). Evidência: log de sync + contagem de chaves reconciliadas.

### Task 2 — claimer_opening_date no create_claim [DICT gap #2, alto]

**Área:** `apps/shared/lib/shared/bacen/dict_client.ex` (`claim_attrs`/mapeamento :1634-1663), `apps/dict_service/.../claims.ex`, e o caminho Core (`core/backend .../pix_providers/in_house/adapter.ex` + `dict_api_responder`).
**Gap:** `claimer_opening_date` ausente → `{:missing_field, :claimer_opening_date}` falha-fecha.
**Passos:** TDD — teste que create_claim com dados completos monta o payload com `ClaimerAccount>OpeningDate`; threading do campo desde a origem (params do IB/admin) até o builder; se a data de abertura da conta do reivindicador vier da conta local, resolver dela. GREEN + suíte dict_service.

### Task 3 — reason/situation_type no create_infraction [DICT gap #3, alto]

**Área:** `dict_client.ex` (`infraction_attrs` :708), `apps/dict_service/.../infractions.ex`, caminho Core.
**Gap:** `reason`/`situation_type` ausentes → falha-fecha.
**Passos:** TDD — create_infraction com reason+situation_type monta payload válido; threading dos campos; default seguro só quando o fluxo garante o valor. GREEN.

### Task 4 — FraudType enum 6→5 oficiais [DICT gap #4, médio]

**Área:** `FraudMarkerEnumMapper` (fraud marker enum) em dict_service/shared.
**Gap:** nosso enum tem 6 valores; oficial v2.11 = APPLICATION_FRAUDS/MULE_ACCOUNTS/SCAMMER_ACCOUNTS/OTHER_FRAUDS/UNKNOWN_FRAUDS (5).
**Passos:** TDD — todo valor do nosso enum mapeia para um dos 5 oficiais (nenhum valor sem correspondência); corrigir o mapa; teste exaustivo do to_bacen/1.

### Task 5 — Estados de refund/recovery vs enum legado [DICT gap #5, médio]

**Área:** `funds_recovery.ex`, `dict_external_reconciler.ex` (estados refund).
**Gap:** nossos estados não batem com TOTALLY_ACCEPTED/PARTIALLY_ACCEPTED/REJECTED do legado.
**Passos:** auditar close_refund e o mapeamento de analysis_result parcial; TDD para os 3 resultados de análise; garantir persistência do estado correto. (Se a análise parcial não se aplica ao nosso fluxo hoje, documentar e cobrir os que se aplicam.)

### Task 6 — Validações de negócio no ENVIO (GSCB/saque/DICT/TxId) [ICOM gap #8, alto-regulatório]

**Área:** novo validador em `apps/settlement_service` (send gate) ou `apps/spi_service/.../validators`, chamado antes do dispatch da pacs.008.
**Gap:** builder monta mas não valida GSCB=2 valores (VLCP+VLDN), OTHR/saque=1 valor, DICT exige proxy, QRDN TxId 26-35, INIC exige InitgPty.
**Passos:** TDD por regra (espelhar `ValidaPaymentUseCase.cs:200-315`); rejeitar pacs.008 semanticamente inválida antes de assinar/enviar, com mensagem clara. GREEN.

### Task 7 — Mapa erro-crédito → código ISO na recepção [ICOM gap #9, alto]

**Área:** `apps/spi_service/.../workers/inbound_processor.ex` + validators (caminho de recusa de crédito da pacs.008 recebida).
**Gap:** rejeição hoje primariamente estrutural; falta de-para conta-não-encontrada→AC03, bloqueada→AC06, fechada→AC07, tipo inválido→AC14, não-pertence→BE01, fallback→ED05 (espelho de `ConversaoValidationError.cs:12-70`).
**Passos:** TDD — dado um crédito recusado por cada causa, o pacs.002 sai com o código ISO certo; implementar o mapa; fallback ED05. GREEN.

### Task 8 — Catálogo pacs.004: 13 motivos de devolução no Construtor [ICOM gap #10, médio]

**Área:** `apps/settlement_service/.../message_form_catalog.ex` (field_meta do return_reason).
**Gap:** Construtor mostra 4; validador aceita 13.
**Passos:** completar o select de return_reason com os 13 códigos do whitelist (`spi_validator.ex:21`) com descrições oficiais; teste do field_meta. (Não tocar builder — só catálogo/UI.)

### Task 9 — person-statistics path + event-notifications [DICT gaps #6/#7, baixo]

**Área:** `dict_client.ex` (statistics path), rotas event-notifications.
**Gap:** person-statistics usa rota local vs `/persons/{TaxId}/statistics`; event-notifications sem chamada BACEN.
**Passos:** alinhar path da person-statistics quando external_mode=:bacen; avaliar/implementar poll de event-notifications se aplicável (senão documentar como superfície local intencional). TDD onde houver mudança de contrato.

### Task 10 — Passada de verificação dos VERIFICAR restantes + estados/expurgo [ICOM itens residuais]

**Área:** leitura (inbound/outbound/return processors) + doc.
**Passos:** confirmar os VERIFICAR remanescentes da matriz ICOM (validação de crédito conta bloqueada/fechada — pode já estar coberto pela Task 7; estados sem equivalente; expurgo). Atualizar a matriz com os vereditos finais; abrir gaps residuais só se reais. Sem código a menos que confirme gap.

---

### Fase final — deploy + evidência + fechamento
Build arm64 pix-api (+ pix-admin-ui se Task 8 tocar front), deploy, ligar flags CID em HML (Task 1), validar vivo cada correção, screenshots (regra 11), atualizar handoff + CLAUDE.md + memória. Atualizar as duas matrizes com os vereditos pós-correção.