# Fase 1 (higiene de código) — validação de prontidão para deploy

Data: 2026-07-08. Ref validado: `origin/main` = `e7ba6288` (higiene completa) mais o commit de
correção dos 3 labels visíveis (abaixo). Método: workflow de validação multi-lente, 5 lentes
empíricas em paralelo, cada uma em worktree/Postgres efêmero isolado, mais síntese de go/no-go.
Nada foi deployado — este documento atesta que o código está pronto para virar imagens HML e
seguir o modus operandi de deploy.

## Veredito

**PRONTO PARA CONSTRUIR IMAGENS.** 4 das 5 lentes deram PASS empírico; a única em CONCERNS
(auditoria de resíduo) não achou vazamento de marca legada nem quebra funcional — só 3 labels
visíveis com vocabulário cooperativo ("associados"), que foram corrigidos nesta sessão (commit
abaixo). Sem esses 3, a auditoria de resíduo também fica limpa.

## Tabela de prontidão

| Dimensão | Veredito | Evidência empírica |
|---|---|---|
| Build | PRONTO | 7 alvos buildam limpo em `e7ba6288`: `vue-tsc --noEmit` + `vite build` nos 5 fronts (Core admin/banking/merchant-portal, PIX admin, SPB); `mix compile` exit 0 em Core e PIX; zero `CompileError`. |
| Testes | PRONTO | 405 testes, 0 falhas em PG efêmero: 315/315 front admin (39 arquivos), 71/0 backend Core (7 suítes-alvo das ondas), 19/0 cabine PIX (operation_query + camt054_parser). |
| Resíduo | LIMPO (pós-fix) | Marca OnZ/AvivPay 100% limpa (zero string viva; só aliases de compat, comentários de proveniência e tripwires de teste); `es.ts` órfão não existe mais. Os 3 labels coop "associados" foram corrigidos. |
| Money-path | PRONTO | Esqueleto de código de `money_unit`/`money_boundary` IDÊNTICO ao baseline (só docstring; scale 100 intacto); diff VAZIO em tigerbeetlex/deposit/wallet no range; conversões novas provadas value-preserving rodando o fonte de `e7ba6288` (`from_cents(123456)|>to_brl(2)="1234.56"`). |
| Migrations + Deploy-skew | PRONTO | As 3 migrations aplicam UP/DOWN limpo em PG16 efêmero, rpc-safe (zero `get_env`), não tocam tabela de dinheiro; dual-emission viva e 154 aliases de rota resolvem para a ação canônica (deploy-skew seguro). |

## Correção aplicada nesta validação

A lente de resíduo isolou 3 labels visíveis no admin com vocabulário cooperativo, duas apontando
o usuário para "Instituição → Associados" (item de menu já removido). Corrigidos para "Clientes"
(destino canônico da SCD):
- `core/apps/admin/src/views/investments/InvestmentPositionsView.vue:456`
- `core/apps/admin/src/views/regulatory/efinanceira/components/PendenciasEnderecoCard.vue:55`
- `core/apps/admin/src/views/reports/clients/TotalClientsReportView.vue:79`

Build do admin re-validado verde após a correção.

## Checklist de deploy (modus operandi, na ordem)

1. **Credenciais AWS**: `AWS_PROFILE=vulcimonetarie AWS_REGION=sa-east-1` (conta `990933657879`).
   Nunca o profile `default` (outra conta).
2. **Backup do banco Core ANTES das 2 migrations da onda 1.5**: `20260707190000` (OR-merge RBAC
   coop->clients) e `20260707190100` (`conselheiro`->NULL) são lossy (o DOWN é no-op). Snapshot do
   Aurora antes de aplicar.
3. **Aplicar as 3 migrations via `rpc`, não `eval`** (ECS exec não herda secrets). Ordem da cadeia:
   `20260707190000`, `20260707190100`, `20260708100000` (create `treasury_reconciliation_snapshots`).
   Conferir logs ANTES/DEPOIS do RBAC e "conselheiro->NULL afetados: N".
4. **Build das imagens HML a partir do HEAD** (arm64 -> ECR). Ordem: backends primeiro (core-api,
   depois pix-api), depois os fronts (core admin/banking/merchant-portal, pix-admin-ui,
   spb-admin-ui). Os fronts consomem contratos do backend; a dual-emission de claims deve já estar viva.
5. **Provisionar `SPI:create` para o principal `PIX_CABIN_ADMIN_LOGIN`**: sem isso a MgmtQuery
   retorna `cabin_forbidden`. Antes de validar as telas de tesouraria/consulta da cabine.
6. **Confirmar a caixa `regulatorio@monetarie.com.br` do CADOC 1201** (e os defaults irmãos
   `resp_telefone`/`resp_nome`, hoje placeholders) antes de habilitar o fluxo.
7. **Deploy no ECS** (`update-service --force-new-deployment`), aguardar `rolloutState=COMPLETED`,
   conferir por DIGEST da imagem (tag mutável não confia) e `/health` 200 nos hosts
   `*-h.monetarie.internal` via VPN.
8. **Screenshots (regra #11) SÓ DEPOIS que as imagens HML novas subirem**: rodar
   `scripts/codex_capture_core_pix_spb.cjs` após o rollout COMPLETED. Capturar antes fotografaria
   as imagens antigas e invalidaria a evidência. Exigir screenshot + metadados + validador sem erro.
9. **Promoção a produção por digest** só depois do HML validado, mesma ordem de serviços; produção
   é ambiente isolado (rede 10.50, hosts sem sufixo `-h`).

## Itens abertos (não bloqueiam o build)

1. **Namespace de domínio `Cooperative.*` no backend** (schemas/use_cases, tabelas `cooperative_*`,
   strings de erro JSON "Cooperado não encontrado"): decisão do dono de deixar fora da Fase 1;
   API-only, não user-visible. Reavaliar se as telas de capital-share/tarifa forem expostas ao SCD.
2. **DRE / results_engine de-cooperativizado** (perda do split 80/20 e reservas FATES/legal/
   IRPJ/CSLL): remoção intencional (ondas 5/6); `gross_result` byte-idêntico. Confirmar que nenhum
   relatório regulatório/tributário downstream ainda depende dos campos 80/20 antes do go-live.
3. **Sinal da despesa no DRE**: `gross_result` = 130k para receita 100k / despesa 30k (convenção
   pré-existente; despesa armazenada negativa). Líquido econômico seria 70k. Revisão contábil.
4. **`Capital.apply_dividend`** (rota `.../capital/dividend`): cabeada porém dormant após a onda 4;
   rename `total_surplus`->`total_amount` puramente lexical. Reavaliar remoção pós-HML.
5. **JWT de SSO emite só claims legadas** (`cooperative_role`/`cooperative_permissions`): seguro
   para o deploy-skew atual, mas unidirecional. Adicionar o vocabulário novo quando o token SSO
   passar a ser consumido por cliente forward-only.
6. **CADOC 4111 dead code**: `Regulatory.Cosif.Cadoc4111` + `AccountingReports.generate_cadoc_4111`
   são dead code E pré-quebrados (colunas `j.cosif_account`/`j.entry_type` inexistentes; a submissão
   viva usa `Generator4111`). Corrigir as colunas ou deletar o wrapper morto.
7. **Saúde da suíte backend**: ~807 falhas em banco efêmero limpo no próprio `main`, pré-existentes/
   ambientais (constraint `users_tax_id_alfa_chk` no setup + testes obsoletos). Delta antes/depois
   das ondas = 0. Frente de higiene da suíte separada.
8. **`mix compile --warnings-as-errors`** falha (77 warnings pré-existentes em credit/cosif). Gate
   exige só `mix compile` plain (passa). Onda técnica de warnings.
9. **Shims de compat** (aliases `/cooperative/*` e `/treasury/caixa-aviv/*`, dual-emission de
   claims): todos marcados no código; remover depois de HML confirmar a UI nova e o BACEN validado.

## Evidência por lente (o que cada uma provou)

- **Build**: rodou os 7 builds em worktree isolado (node v24.1.0 / Elixir 1.19.5), colheu os
  "✓ built in Ns" e "Generated ... app" com `mix compile` exit 0; grep de `CompileError` = 0.
- **Testes**: executou as suítes em PG efêmero, coletou 315/315 front, 71/0 backend Core, 19/0
  cabine; resolveu a colisão holidays/ownership_validations stampando as versions (rodou, não carimbou).
- **Resíduo**: `git grep` read-only produziu tabelas por categoria (onz/aviv, coop, homolog),
  confirmou zero marca viva, `es.ts` bare ausente, e isolou os 3 labels "associados" (corrigidos).
- **Money-path**: comparou `git diff a78a190e e7ba6288` nos arquivos proibidos (esqueleto de código
  idêntico, scale 100 intacto, diff vazio em tigerbeetlex/deposit/wallet) e RODOU o fonte de
  `e7ba6288` provando as conversões sem float.
- **Migrations + Deploy-skew**: aplicou a cadeia UP e o `rollback -n 3` DOWN em postgres:16-alpine
  efêmero, provou o OR-merge de grants e o `conselheiro`->NULL com seed via psql, e cruzou 2187
  rotas de `mix phx.routes` mostrando os 154 aliases resolvendo method+path+controller+action idênticos.