# Elo AMES → SIMBA - design

## ERRATA 2026-07-19

Este desenho ficou desatualizado no ponto central. A verificação de 19/07 provou que o elo AMES para SIMBA JÁ ESTÁ COSTURADO ponta a ponta no código, inclusive a UI que o texto abaixo dava como faltante. NÃO haverá endpoint novo `POST /v1/regulatory/ames/:id/simba-response`; o caminho vigente é o endpoint EXISTENTE `POST /v1/regulatory/ames/:id/response` com `type=simba`.

Âncoras do que já existe:

- Backend: `core/backend/lib/monetarie_web/controllers/regulatory/ames_controller.ex:72-76` (`attach_response` com `type=simba` chama `Ames.attach_simba_response(id, simba_params(params), actor(conn))`; `simba_params/1` nas linhas 146-153), roteado pelo endpoint existente `POST /v1/regulatory/ames/:id/response` (`router.ex:969`).
- Use case: `core/backend/lib/monetarie/use_cases/regulatory/ames.ex:90-117` (`attach_simba_response/3` delega a `Simba.generate_case/1`, adota o `regulatory_file` gerado como resposta com `response_type: "simba"` e o `deliver/2` envia via STA HTTP).
- UI: `core/apps/admin/src/views/regulatory/AmesView.vue` (respondType "Caso SIMBA" nas linhas 100-103, `simbaForm` na linha 107, Dialog de resposta nas linhas 316-346, `attachSimbaResponse` na linha 141) e `core/apps/admin/src/composables/useAmes.ts:117-119`.

O gap real desta frente é outro:

- (a) cobertura de teste do caminho `attach_response type=simba`, que não existia. Adicionada em 19/07 e ela provou defeitos reais de shape no elo (o caminho respondia 500 em qualquer uso). Detalhe e correção em `docs/reports/2026-07-19-ames-simba-validacao.md`.
- (b) validação viva do fluxo completo, nunca exercitado (local e depois janela HML).

O restante do texto abaixo permanece como registro histórico do desenho original. Onde ele diz "endpoint novo", leia "endpoint existente `POST /v1/regulatory/ames/:id/response` com `type=simba`".

## Descoberta central (evidência)

O elo de código JÁ EXISTE e está inerte: `Ames.attach_simba_response/3` (`core/backend/lib/monetarie/use_cases/regulatory/ames.ex:90`) delega a `Simba.generate_case/1` (:93) e adota o `regulatory_file` gerado como resposta da solicitação AMES (:96-111; `response_type: "simba"` em `ames_request.ex:24,35`). Ponto de junção: `regulatory_file_id` nos dois lados + documento do investigado. O que falta é o wiring operacional (UI) e a validação viva - o elo nunca foi exercitado.

## Desenho (enxuto, YAGNI)

1. **UI**: na `AmesView.vue`, quando a demanda exigir quebra de sigilo, o operador escolhe "Responder com SIMBA" e preenche os `case_params` que `Simba.generate_case/1` já exige (case_number, documento do investigado, período); o front chama endpoint novo `POST /v1/regulatory/ames/:id/simba-response` → `Ames.attach_simba_response/3`. Validação de erro legível quando o documento não tem contas/movimento (o lookup do SIMBA já responde isso).
2. **Trilha**: o AMES request guarda o vínculo (já guarda via regulatory_file_id); a tela mostra o ZIP SIMBA anexado + status do envio STA pelo trilho `deliver/2` existente (`ames.ex:117`).
3. **Auditoria**: reusar `simba_audit_logs` (já existe) + audit do controller AMES.
4. Nada de novo no gerador SIMBA nem no tracker STA - só a costura.

## Testes e validação

- TDD: endpoint novo com case_params válidos (ZIP anexado, report_type vira AMES, status respondida), documento sem acervo (422 legível), auditoria gravada, deliver na sequência usa o arquivo anexado.
- Validação viva (HML): criar demanda AMES de teste, responder com SIMBA sobre cliente de teste com movimento, enviar via STA HTTP (sonda já provada no F3), acompanhar tracker. Só depois PRD.
- Dependência externa: código STA por demanda é informado pelo operador (D6 do gap-analysis) - a tela já pede o `sta_file_code` `AMES\d{3}`.