## Checklist rápido para kick-off Finanto

1. **Revisar a coleta da IN100**
   - Garantir que `FinantoInssCaseController` e `FinantoInssCase` estejam persistindo CPF, NB, UF e consentimento antes de chamar a API.
   - Validar se a fila/cron que monitora o `query_id` está ativa (`automation.php finanto:in100:sync`).
2. **Testar os endpoints de IN100 no Postman**
   - `POST /v3/query-inss-balances/finder`, `POST /v3/query-inss-balances/finder/await` (opcional) e `GET /v3/query-inss-balances/{id}` usando a `apikey` real.
   - Reutilizar a coleção `api finanto/JoinBank.postman_collection.json` para manter os exemplos alinhados.
3. **Conferir armazenamento dos payloads**
   - Campo `finanto_inss_cases.in100_payload` deve receber o JSON completo do `GET query`.
   - `in100_contracts_json` precisa guardar o array `contracts` e `in100_items_json` o array `items`, possibilitando auditoria/reprocessamento.
4. **Mapear os campos de contrato necessários para as calculadoras**
   - Banco (lender), parcelas restantes, saldo/due balance, `lenderCode`, número do contrato e indicadores de seguro.
5. **Planejar parser e UI**
   - Definir como cada contrato aparecerá no painel (cards + tabela com filtros, botões para detalhar payload).
   - Documentar o fluxo de escolha: quem seleciona o contrato/oferta, onde fica o log e como isso habilita a próxima etapa.
6. **Implementar (ou revisar) a calculadora Finanto**
   - Adicionar `calculateSimulation` ao `app/Services/Finanto/FinantoClient.php`.
   - Criar serviço orquestrador que recebe o contrato selecionado e decide a calculadora correta (port, port+refin, novo).
   - Persistir o retorno (parcelas finais, CET, troco, etc.) para reutilizar em `FinantoInssFlow::buildSimulationPayload()`.
7. **Ajustar a criação de simulações**
   - Atualizar `FinantoInssFlow::buildSimulationPayload()` para aceitar múltiplos itens e integrar as saídas das calculadoras.
   - Bloquear o POST oficial até que os arquivos obrigatórios (RG frente/verso) tenham sido enviados.
   - Rodar `POST /v3/loan-inss-simulations` via Postman nos cenários de portabilidade, port+refin e contrato novo.
8. **Termo, contrato e assinatura**
   - Revalidar `GET /auth-term`, `POST /actions` com `create_loans` e `GET /loans/{id}` diretamente no Postman.
   - Ajustar a UI (`app/Views/finanto_inss/...` e `public/assets/js/finanto-simulations.js`) para acionar esses endpoints com feedback visível.
9. **Documentação e validações internas**
   - Atualizar `docs/finanto-inss.md` (este arquivo) com payloads de IN100, calculadoras e simulações usados nos testes.
   - Revisar regras de negócio: saldo mínimo, bancos bloqueados, idade mínima/máxima, parcelas restantes (vide `portability_policy.php`) e demais validações derivadas da IN100.
10. **Workflow de QA contínuo**
    - Começar sempre revalidando cada etapa no Postman antes de mexer no código; qualquer divergência fica registrada mais fácil.

### Ferramentas internas (painel Saque Fácil)

- **Calculadora embutida:** na tela do caso (`/finanto/cases/{id}`) selecione o contrato IN100 e envie `rule_id`, prazo, parcela e valor. O frontend chama `POST /finanto/cases/{id}/calculate`, que persiste o item em `calculated_items_json` e atualiza os campos `selected_*`.
- **Geração de proposta:** após rodar a calculadora e anexar RG frente/verso, clique em “Gerar proposta” para disparar `POST /finanto/cases/{id}/simulation`. O backend reaproveita `FinantoInssFlow::buildDigitalPrefillPayload`, chama a API `/v3/loan-inss-simulations` e atualiza `simulation_id`, termo e tracking automaticamente.
- **Contrato:** permanece em `POST /finanto/cases/{id}/loan`, reutilizando os botões existentes.
- **Lista central:** o menu “Simulações” agora abre `/finanto/cases`, onde é possível buscar leads, iniciar um caso e acessar rapidamente o painel ou o botão “Digitar proposta”.
- Toda ação usa CSRF padrão e adiciona notas/atualizações no caso, permitindo auditar o passo a passo diretamente pelo painel.

## Módulo Port+Refin (novo fluxo operacional)

Para Portabilidade, Port+Refin e os demais produtos Finanto criamos um único módulo **Finanto INSS – Integração API**, embutido na tela do caso. Ele usa o FinantoApiClient, o FinantoInssPortRefinService e registra auditoria em `finanto_requests_log` + anexos em `finanto_files`.

### Configuração do acesso JoinBank

1. Em **Configurações > Integrações** cadastre (ou atualize) uma integração inanto_inss.
2. Informe ase_url (sem barra dupla, ex.: https://api.joinbank.io) e a pi_key fornecida pela Finanto/JoinBank.
3. Sem esses campos o cliente trava as chamadas e o módulo exibe o erro correspondente.

### Sequência das telas

1. **Operação + Produto** – escolha o tipo de operação (port, port+refin, novo, refin etc.), clique em “Buscar produtos” e depois “Listar tabelas” para sincronizar o catálogo direto da API.
2. **IN100 + contrato** – execute a IN100 e selecione o contrato que será usado quando a operação exigir dados de origem.
3. **Calculadora Finanto** – selecione a tabela, preencha prazo/parcela/valor e, quando aplicável, as condições de refin. Clique em “Calcular”; o retorno fica salvo em `calculation_payload` e `calculated_items_json`.
4. **Simulação e termo** – gere a simulação, obtenha o termo (`GET /auth-term`) e aceite (`PUT /signer/{key}/accept`). O bloco “Autorizar Termo” só aparece quando `auth_term_key` existe.
5. **Documentos e contrato** – informe `doc_front_id`/`doc_back_id` válidos e acione “Gerar contrato”/“Consultar contrato”.
6. **Logs e JSONs** – painel à direita mostra todas as requisições (inanto_requests_log) e os payloads crus (cálculo, termo, contrato) para troubleshooting.

### Teste no Postman

1. Configure os headers pikey + Content-Type: application/json.
2. Execute a sequência:
   - POST /v3/loan-products/search/basic
   - POST /v3/loan-product-rules/search/basic
   - POST /v3/loan-inss-simulations/calculation
   - POST /v3/loan-inss-simulations
   - GET /v3/loan-inss-simulations/{id}/auth-term
   - PUT /v3/signer/{auth_term_key}/accept
   - PUT /v3/loan-inss-simulations/{id} (files válidos)
   - POST /v3/loan-inss-simulations/{id}/actions (command: create_loans)
   - GET /v3/loans/{loanId}
3. Compare com o que ficou em inanto_requests_log. O payload deve ser idêntico ao registrado pelo CRM.

### Auditoria

- inanto_requests_log: endpoint, método, payload de request/response e HTTP status por case_id.
- inanto_files: controla quais doc IDs foram anexados (doc_front/doc_back e futuros tipos).
- port_refin_last_error: armazena a última mensagem de erro e aparece em destaque no card inicial.
## Fluxo Finanto – Guia de Integração (Postman)

### Consultas IN100

- **Endpoints principais**
  - `POST https://api.ajin.io/v3/query-inss-balances/finder`
  - `POST https://api.ajin.io/v3/query-inss-balances/finder/await` (opcional)
  - `GET https://api.ajin.io/v3/query-inss-balances/{id}`
- **Headers obrigatórios**: `apikey: <sua_chave>`, `Content-Type: application/json`.
- **Body padrão (`finder`/`await`)**:

```json
{
  "identity": "05391807859",
  "benefitNumber": "5343021510",
  "lastDays": 0,
  "attempts": 3
}
```

- **Persistência obrigatória**
  - `finanto_inss_cases.in100_payload` ← JSON completo do `GET`.
  - `in100_contracts_json` ← array `contracts` (quando existir).
  - `in100_items_json` ← array `items` (quando existir).
- **Uso interno**: exibir contratos na UI e alimentar as calculadoras.

### Calculadoras Finanto

- **Endpoint**: `POST https://api.ajin.io/v3/loan-inss-simulations/calculation`.
- **Portabilidade**:

```json
{
  "ruleId": "{{portRuleId}}",
  "term": 66,
  "rate": 1.3,
  "installmentValue": 344.24,
  "loanValue": 14913.97,
  "originContract": {
    "lenderCode": 341,
    "contractNumber": "1234565",
    "term": 84,
    "installmentsRemaining": 66,
    "installmentValue": 350,
    "dueBalanceValue": 14913.97
  },
  "hasInsurance": false,
  "referenceCode": null
}
```

- **Portabilidade + Refinanciamento**: mesmo payload da portabilidade acrescido do bloco `refinancing` (prazo, taxa e parcela do refinanciamento).
- **Contrato novo**:

```json
{
  "ruleId": "{{newRuleId}}",
  "hasInsurance": false,
  "installmentValue": 43.54,
  "loanValue": 1918.35,
  "rate": 1.66,
  "term": 84,
  "referenceCode": null
}
```

- **Retorno**: reutilize parcelas finais, CET, troco e demais campos calculados ao montar o payload oficial.

### Criação de simulações

- **Endpoint**: `POST https://api.ajin.io/v3/loan-inss-simulations`.
- **Headers**: `apikey`, `Content-Type: application/json`.
- **Estrutura base**:

```json
{
  "borrower": {
    "name": "{{name}}",
    "identity": "{{identity}}",
    "benefit": "{{inss_benefit}}",
    "benefitState": "SP",
    "benefitStartDate": "1999-01-15",
    "benefitPaymentMethod": 1,
    "benefitType": 42,
    "birthDate": "1965-08-19",
    "motherName": "Maria da Silva",
    "maritalStatus": "Solteiro",
    "sex": "Feminino",
    "income": 1800.50,
    "phone": "{{phone}}",
    "email": "maria@gmail.com.br",
    "address": { "...": "..." },
    "document": { "...": "..." }
  },
  "items": [
    {
      "type": "portability",
      "ruleId": "{{ruleId_da_calculadora}}",
      "loanValue": 14913.97,
      "installmentValue": 344.24,
      "term": 66,
      "originContract": {
        "lenderCode": 341,
        "contractNumber": "1234565",
        "term": 84,
        "installmentsRemaining": 66,
        "installmentValue": 350,
        "dueBalanceValue": 14913.97
      }
    }
  ],
  "creditBankAccount": {
    "bank": "001",
    "branch": "1234",
    "number": "123654",
    "digit": "6"
  },
  "step": { "code": 0, "name": null },
  "files": [
    { "id": "{{doc_front_id}}", "type": "doc_front" },
    { "id": "{{doc_back_id}}", "type": "doc_back" }
  ],
  "note": null,
  "brokerId": null,
  "accessId": null,
  "validate": true
}
```

- **Resultado esperado**: `simulation_id` usado pelo fluxo digital.

### Termo, contrato e assinatura

- **Consultar termo**: `GET /v3/loan-inss-simulations/{simulation_id}` + `GET /v3/loan-inss-simulations/{simulation_id}/auth-term`.
- **Confirmar termo no CRM**: `POST /finanto/cases/{id}/authorize`.
- **Criar contrato**: `POST /v3/loan-inss-simulations/{simulation_id}/actions` com `{ "command": "create_loans" }`.
- **Acompanhar assinatura/liberação**: `GET /v3/loans/{loan_id}` até `loan_status = released`.
- **Requisitos internos**
  - Saldo mínimo de R$ 4.000 para portabilidade.
  - Validações de idade, bancos bloqueados, parcelas restantes (80–95) e demais regras em `portability_policy.php`.
  - Registrar notas/logs por etapa: IN100, calculadora, simulação, termo, contrato.

### Como aplicar esta referência

1. Validar cada etapa no Postman antes de integrar no código (reutilize os exemplos acima).
2. No sistema, seguir a sequência: **IN100 → exibir contratos → selecionar contrato/calculadora → montar simulação → termo → contrato/assinatura**.
3. Referenciar os principais arquivos PHP em cada ajuste:
   - `app/Controllers/FinantoInssCaseController.php`
   - `app/Services/Finanto/FinantoClient.php`
   - `app/Services/Finanto/FinantoInssDigitalService.php`
   - `app/Services/Finanto/FinantoInssFlow.php`
   - Views/JS: `app/Views/finanto_inss/...` e `public/assets/js/finanto-simulations.js`

## Fluxo digital Finanto

`FinantoInssDigitalService::submit` s? entra em cena depois que o operador conclui **CPF ? IN100 ? oferta**:
1. Recebe o payload validado por `FinantoInssFlow` (dados pessoais, endere?o, conta de cr?dito e a oferta selecionada).
2. Executa `POST /v3/loan-inss-simulations` (quando `finalize = false`), salva `simulation_id` no `FinantoInssCase` e inicia o monitoramento do termo (`GET .../auth-term`).
3. Quando o termo estiver assinado e o operador disparar o contrato, roda novamente com `finalize = true`, enviando `POST /v3/loan-inss-simulations/{simulation_id}/actions` (`create_loans`).
4. Cada chamada gera entradas em `loan_proposal_bank_payloads`, atualiza `loan_proposals` (status, valores, integra??o) e mant?m `FinantoInssCase` sincronizado (`auth_term_status`, `loan_id`, `signature_status`).
5. `FinantoInssPipelineService` e o cron `finanto:loans:sync` continuam consultando `GET /v3/loans/{loan_id}` at? a assinatura/libera??o final.

Metodos auxiliares reutilizados pelos testes:
- `collectFinantoMessages` agrupa mensagens aninhadas da API.
- `decodeJsonPayload` converte blobs JSON em arrays.
- `prepareFinantoPreviewSelection` (no controller) garante que a pre-simulacao pertence ao lead/integracao antes de copiar campos.

## Fluxo Interno (Backoffice)

### Etapa 1 — CPF e dados mínimos para IN100
- **Operador** abre o caso ou “Nova Proposta” e revisa CPF, número de benefício (NB) e UF.  
- Campos obrigatórios: CPF completo, NB, UF, data de nascimento e, quando disponível, agência/conta para validações futuras.  
- O sistema bloqueia os próximos passos enquanto qualquer um desses campos estiver vazio ou inválido.  
- **Endpoint Finanto:** nenhum (a tela apenas coleta/valida os dados).

### Etapa 2 — Consulta IN100
- Operador clica em **“Consultar IN100”**.  
- O CRM envia `POST /v3/query-inss-balances/finder` e imediatamente registra o `query_id`.  
- Opcionalmente, dispara `POST /v3/query-inss-balances/finder/await` para aguardar o processamento.  
- Assim que o `query_id` estiver pronto, o sistema faz `GET /v3/query-inss-balances/{query_id}` e preenche:
  - Cards de saldo total, margem disponível e quantidade de contratos.
  - Lista compacta de contratos com link “Ver detalhes” (modal/side sheet com payload bruto).
- Histórico da IN100 (responsável, horário, resultado) fica acessível em “Ver histórico”.  
- **Endpoints Finanto:** `POST finder`, `POST finder/await` (opcional) e `GET query`.

### Etapa 3 — Revisão de contratos e seleção da oferta
- Com a IN100 concluída, o operador analisa os contratos retornados e clica em **“Recarregar ofertas”** para atualizar `finanto_inss_offers`.  
- A tabela `Regra | Parcela | Troco | Prazo | Status | Ação` permite selecionar apenas uma oferta por vez (ação “Selecionar oferta”).  
- O painel lateral mostra o resumo (CET, banco de origem, saldo, prazo, margem restante) e o botão **“Usar esta oferta”** confirma a escolha, registrando usuário e timestamp.  
- Enquanto nenhuma oferta estiver marcada como `selected`, as etapas de proposta e contrato permanecem bloqueadas.  
- **Endpoints Finanto:** nenhum (toda a seleção acontece internamente com base no retorno da IN100).

### Etapa 4 — Proposta digital e termo de autorização
- Após confirmar a oferta, o operador aciona **“Gerar proposta”** ou a própria UI dispara automaticamente:
  - `POST /v3/loan-inss-simulations` para criar a simulação com os dados do lead e a oferta escolhida.
  - `GET /v3/loan-inss-simulations/{simulation_id}` para confirmar o status da simulação.
  - `GET /v3/loan-inss-simulations/{simulation_id}/auth-term` em loop até que o termo esteja disponível.  
- A tela exibe o status (`awaiting`, `signed`, `expired`), link do termo e botões “Copiar link”, “Enviar por WhatsApp”, “Enviar por SMS”.  
- O operador escolhe o **canal de autorização** (dropdown) e registra um comentário obrigatório antes de clicar em **“Confirmar autorização recebida”**, que executa `syncAuthTerm` e salva responsável/data.  
- **Endpoints Finanto:** `POST /v3/loan-inss-simulations`, `GET /v3/loan-inss-simulations/{simulation_id}`, `GET /v3/loan-inss-simulations/{simulation_id}/auth-term`.

### Etapa 5 — Envio do contrato
- Com o termo assinado e a oferta ativa, o botão **“Enviar contrato”** fica habilitado.  
- Ao clicar, o CRM chama `POST /v3/loan-inss-simulations/{simulation_id}/actions` com `{"command":"create_loans"}`.  
- Em seguida, executa `GET /v3/loans/{loan_id}` para capturar status inicial do contrato e link de assinatura.  
- A tela mostra o painel “Assinatura do Lead” com timeline (enviado, visualizado, assinado) e ações para reenviar link/lembrar o cliente.  
- **Endpoints Finanto:** `POST /v3/loan-inss-simulations/{simulation_id}/actions`, `GET /v3/loans/{loan_id}` (primeira sincronização).

### Etapa 6 — Assinatura, liberação e acompanhamento
- Após o envio, o sistema continua consultando `GET /v3/loans/{loan_id}` (manual via botão “Forçar sincronização” ou automático pelo cron `php automation.php finanto:loans:sync`).  
- O card final exibe `case.stage`, `loan_status`, `signature_status`, responsável e última atualização; a timeline destaca todos os marcos (IN100, oferta, proposta, termo, contrato, assinatura, liberação).  
- Quando `signature_status = signed` e `loan_status = released`, o caso é marcado como concluído e o dashboard passa a considerar a proposta como `funded`.  
- **Endpoints Finanto:** `GET /v3/loans/{loan_id}` (polling contínuo).

### Visão macro

| Ordem | Ação interna | Endpoint Finanto | Resultado esperado |
|-------|--------------|------------------|--------------------|
| 0 | Operador revisa CPF/NB/UF, coleta consentimentos e salva dados mínimos | — | Formulário validado; etapa de IN100 habilitada. |
| 1 | Operador clica em “Consultar IN100” | `POST /v3/query-inss-balances/finder`<br>`POST /v3/query-inss-balances/finder/await` | Requisição registrada e `query_id` disponível. |
| 2 | Sistema consolida resultado da IN100 | `GET /v3/query-inss-balances/{query_id}` | `in100_payload`, margens e contratos atualizados no caso. |
| 3 | Operador analisa e seleciona a oferta | — | Somente atualiza `finanto_inss_offers`; nenhuma chamada externa. |
| 4 | Proposta digital + termo | `POST /v3/loan-inss-simulations`<br>`GET /v3/loan-inss-simulations/{simulation_id}`<br>`GET /v3/loan-inss-simulations/{simulation_id}/auth-term` | `simulation_id`, status do termo e tracking registrados; etapa pronta para contrato. |
| 5 | Envio do contrato | `POST /v3/loan-inss-simulations/{simulation_id}/actions` (`create_loans`)<br>`GET /v3/loans/{loan_id}` | `loan_id`, link da assinatura e status inicial exibidos. |
| 6 | Monitoramento/Liberação | `GET /v3/loans/{loan_id}` (manual e cron `finanto:loans:sync`) | Atualiza assinatura/liberação; dashboards/cards sincronizados. |

### Requests e payloads (detalhados)

1. **POST /v3/query-inss-balances/finder**  
   - Payload base: `{"identity":"<CPF>","benefitNumber":"<NB>","lastDays":0,"attempts":3}`.  
   - Retorna `query_id`. Registrar em `in100_requests` com responsável/canal.

2. **POST /v3/query-inss-balances/finder/await** (opcional, recomendado)  
   - Mesmo payload; garante que a IN100 finalize antes de buscar o resultado.  
   - Em caso de timeout, registrar log e sugerir reexecução manual.

3. **GET /v3/query-inss-balances/{query_id}**  
   - Resposta salva em `FinantoInssCase.in100_payload` com contratos, margens e ofertas sugeridas.  
   - Normalizar contratos em `finanto_inss_offers` para a etapa 2.

4. **POST /v3/loan-inss-simulations** (após escolha da oferta)  
   - Body típico:  
     ```json
     {
       "borrower": {...},
       "items": [
         {
           "ruleId": "...",
           "term": 84,
           "rate": 1.89,
           "installmentValue": 512.34,
           "loanValue": 35990.00,
           "originContract": {...}
         }
       ],
       "creditBankAccount": {...},
       "metadata": {"lead_id": 123, "case_id": 456}
     }
     ```
   - Resposta grava `simulation_id`, `status.key`, `items`, `authTerm` em `finanto_inss_cases`.

5. **GET /v3/loan-inss-simulations/{simulation_id}**  
   - Confirma status e replica `items`. Usado tanto logo após o POST quanto pelo botão “Atualizar status”.

6. **GET /v3/loan-inss-simulations/{simulation_id}/auth-term**  
   - Polling até `status.key = signed`. Persistir `auth_term_content`, `auth_term_status`, `auth_term_expires_at`, `auth_term_channel`, `auth_term_sent_by/at`.

7. **POST /v3/loan-inss-simulations/{simulation_id}/actions`** (`{"command":"create_loans"}`)  
   - Requer termo assinado e oferta aceita. Retorno inclui `loan.id`, `loan.status`, `signature`.

8. **GET /v3/loans/{loan_id}**  
   - Polling logo após o `create_loans` e via cron `finanto:loans:sync`.  
   - Atualiza `signature_status`, `signature_payload`, `loan_status`, `released_at`. Quando finalizado, `FinantoInssCase.stage = concluded` e `loan_proposals` recebe status definitivo.

### Checkpoints e garantias

- Cada request/response acima gera uma entrada em `loan_proposal_bank_payloads` (com `direction` + timestamp) para auditoria.  
- `FinantoInssCase.stage` avança apenas com dados consistentes (`in100_status`, `selected_offer_id`, `auth_term_status`, `loan_id`, `signature_status`).  
- O `tracking_token` retornado na etapa 1 é armazenado apenas para acompanhamento interno; nenhuma tela pública é exposta enquanto estivermos no modo backoffice puro.  
- Todas as propostas criadas a partir desse fluxo são agregadas nos cards do dashboard via `loan_proposals.product_type = 'finanto_inss'`, garantindo visibilidade unificada com os demais produtos.

## Fluxo operacional interno (operador Finanto)

### Objetivos
- Centralizar o acompanhamento de cada caso em uma unica tela (etapas sequenciais).
- Garantir que consentimentos e solicitacoes criticas fiquem registrados (quem executou, quando, resultado).
- Permitir execucao manual (operador) ou automatizada (cron/job) dos dois primeiros passos: consulta IN100 e termo de autorizacao.

### Stepper proposto (tela `finanto_inss/cases/show.php`)

| Etapa | Objetivo | Destravando o proximo passo | Referencias |
|-------|----------|-----------------------------|-------------|
| 1. IN100 & dados | Registrar consentimento (checkbox + timestamp), disparar `query-inss-balances` e anexar o payload normalizado no caso. | `case.in100_status = success` e `in100_payload` salvo. | Botao `.js-run-in100`, service `FinantoInssCaseService::runIn100`. |
| 2. Ofertas & politicas | Mostrar contratos retornados + ofertas (cards e tabela). Permitir aceitar 1..N ofertas para gerar politica interna. | Pelo menos uma oferta marcada como `selected`/`accepted`. | `finanto_inss_offers`, JS `handleAcceptOffer`. |
| 3. Termo de autorizacao | Operador dispara `syncAuthTerm`, valida conteudo, registra `auth_term_sent_by` e `auth_term_sent_at`. Opcao de reenviar link ao cliente. | `auth_term_status = signed`. | Endpoint `/cases/{id}/authorize`, metodo `FinantoInssDigitalService::syncAuthTerm`. |
| 4. Contrato/acao | Habilita `create_loans` apenas depois do termo assinado. Registrar quem enviou e payload de retorno (`loan_id`, `signature`). | `loan_id` preenchido, `signature_status` atualizado. | Endpoint `/cases/{id}/loan`, comando CLI `finanto:loans:sync`. |
| 5. Status/pagamento | Painel final mostra status Finanto (`released`, `rejected`, etc.), historico e links para proposta interna. | Mantem pipeline sincronizado (`pipeline:sync`) e atualiza cards no lead. | `FinantoInssPipelineService`, widgets no lead. |

### Consentimentos e controles internos

- **Pre-IN100**  
  - A tela deve exibir checkbox "Cliente autorizou consulta IN100" com registro de `consent_in100_by` e `consent_in100_at`.  
  - O botao "Atualizar IN100" fica desabilitado ate que CPF, beneficio e consentimento estejam preenchidos.  
  - Quando executado manualmente, gravar em `finanto_debug.log` (`event = in100_manual_run`, `user_id`, `case_id`).  
  - Opcionalmente, enfileirar job `finanto.inss.in100.await` para continuar consultando ate `status = success`.

- **Termo de autorizacao**  
  - O operador visualiza o HTML no iframe, pode reenviar link por SMS/WhatsApp (registrar `auth_term_channel`).  
  - `syncAuthTerm` pode ser disparado manualmente ou via cron (job `finanto.inss.auth_term.poll`). Quando rodar pelo cron, preencher `auth_term_last_poll_at` e anexar o payload retornado.  
  - Assim que `status = signed`, liberar automaticamente o passo "Enviar contrato".

### Execucao automatizada / cron

1. **Fila interna (`automation_jobs`)**  
   - Criar dois novos tipos de job para os passos iniciais:  
     - `finanto.inss.in100.refresh` (dispara consulta IN100 para casos com `in100_status = pending` e consentimento registrado).  
     - `finanto.inss.auth_term.sync` (polling do termo ate `signed`).  
   - Ambos podem ser agendados a cada 10 minutos via `php automation.php run`.

2. **Jobs existentes**  
   - `php automation.php pipeline:sync [brokerId] [hoursBack]` continua responsavel por atualizar snapshots e cards do funil.  
   - `php automation.php finanto:loans:sync [limit]` busca loans pendentes, atualiza assinatura/contrato e fecha o caso.  
   - `php automation.php run` deve ser agendado (ex.: */5 * * * * ) para garantir execucao continua das filas internas.

3. **Alertas operacionais**  
   - Adicionar notificacoes quando um caso permanecer mais de X horas em `auth_term_status = awaiting` ou `signature_status = awaiting`.  
   - Os alertas podem ser outro job (`finanto.inss.case.watchdog`) que dispara Slack/e-mail ou apenas adiciona tarefas internas.

### Impactos de UX e backlog imediato

1. **Refatorar `finanto_inss/cases/show.php` + `public/assets/js/finanto-case.js`**  
   - Transformar a tela em stepper (IN100 -> Ofertas -> Termo -> Contrato -> Status), exibindo somente a etapa ativa e um resumo lateral com os proximos passos.  
   - Cada etapa precisa mostrar responsavel, timestamps, botoes de acao e dicas (ex.: "Obtenha consentimento antes de consultar IN100").

2. **Widgets no lead**  
   - Em `app/Views/leads/show.php`, incluir um card "Finanto INSS" com resumo (status atual, ultima atualizacao, proximo passo) e link direto para o case.  
   - Mostrar tambem ofertas aprovadas/pendentes para facilitar abordagens comerciais.

3. **Logs e auditoria**  
   - Expandir `finanto_inss_cases` com colunas (`consent_in100_by`, `consent_in100_at`, `auth_term_sent_by`, `auth_term_sent_at`).  
   - Todas as acoes manuais gravam no log `finanto_debug.log` (eventos: `in100_manual_run`, `auth_term_manual_trigger`, `loan_manual_create`).

4. **Documentacao para operador**  
   - Criar um "runbook" resumido (pode ser anexo no Confluence ou PDF) reciclando este guia: checklist por etapa, perguntas para o cliente, scripts de atendimento.

### Blueprint da nova tela (caso Finanto)

| Zona | Conteúdo | Comportamento |
|------|----------|---------------|
| Painel lateral esquerdo (col-md-4) | - Resumo do lead (nome, CPF, benefício, telefone).<br>- Status geral (`stage`, `auth_term_status`, `signature_status`).<br>- Timeline compacta (últimas 5 ações com responsável e data).<br>- Próximos passos sugeridos (ex.: “Aguardando termo” se `auth_term_status = awaiting`). | Fixar ao rolar (sticky) para manter contexto. Badges coloridas (cinza/pending, azul/working, verde/success, vermelho/error). Link rápido “Ver lead” / “Ver propostas”. |
| Painel principal (col-md-8) | Stepper com 5 etapas (IN100 → Ofertas → Termo → Contrato → Status). | Mostrar apenas uma etapa expandida, demais recolhidas com resumo. Obrigatório ter indicador visual de etapa concluída/pendente. |

#### Conteúdo por etapa

1. **IN100 & Consentimento**  
   - Campos editáveis: CPF, NB, UF (read-only se vindos do lead).  
   - Checkbox + registro “Cliente autorizou consulta IN100 em dd/mm às hh:mm por Fulano”.  
   - Botões: `Atualizar IN100` (habilitar só após consentimento), `Ver payload` (abre modal com JSON formatado).  
   - Mensagens de validação inline (ex.: “CPF incompleto”).  
   - Resultado esperado: cards com “Contratos encontrados”, “Margem total”, “Última sincronização”.

2. **Ofertas & Avaliação**  
   - Cards empilhados exibindo: banco original, parcela atual, prazo restante, CET sugerido, troco líquido.  
   - Tabela compacta `Oferta / Prazo / Parcela / Liberado / Status / Ações`.  
   - Botões: `Sincronizar ofertas`, `Selecionar oferta` (transforma card em “Selecionada por Fulano às ...”), `Exportar PDF` (opcional).  
   - Alerta quando nenhuma oferta estiver disponível com CTA “Rodar IN100 novamente”.

3. **Termo de autorização**  
   - Mostrar iframe do termo + botões “Copiar link”, “Enviar por WhatsApp/SMS” (mesmo endpoint, mas registrar canal).  
   - Status chips (`Pendente`, `Enviado`, `Assinado`) + timestamps e responsável.  
   - Checklist rápido: “Dados conferidos”, “Cliente validou endereço”, etc., para forçar operador a rever dados antes do envio.

4. **Contrato / Ação Finanto**  
   - Resumo da oferta selecionada e dados bancários do crédito.  
   - Botão `Enviar para assinatura` (dispara `create_loans`). Mostrar spinner + log do request/response.  
   - Se já houver `loan_id`, exibir painel “Contrato Finanto” com link, status, assinaturas pendentes.

5. **Status & Auditoria**  
   - Linha do tempo detalhada (IN100, oferta, termo, contrato, assinatura, liberações).  
   - Lista de anexos/payloads relevantes com download (IN100, Simulation, Loan, AuthTerm).  
   - Notas internas editáveis e histórico de alterações (quem trocou status manualmente).

#### Estados e Regras de UI

- Stepper deve impedir avanço manual: etapas só aparecem como “Concluído” quando os campos chave estiverem preenchidos (`in100_status = success`, `selected_offer_id`, `auth_term_status = signed`, `loan_id`, `signature_status` final).  
- Cada ação exibirá toast padrão + linha no painel “Últimas ações”.  
- Todas as chamadas AJAX usam CSRF embutido e exibem mensagens amigáveis (“Finanto demorou a responder, tente novamente em 2 minutos”).  
- Responsivo: em telas <768px, o stepper vira acordeão com timeline acima, botões ocupando largura total.

#### Hooks para automação

- Cada botão deve emitir `window.dispatchEvent(new CustomEvent('finanto:action', {detail: { caseId, action: 'run_in100' }}))` para permitir instrumentação/fiscalização.  
- Ao concluir cada etapa, disparar `finanto:stage-change` com `stage` atual para que painéis externos (ex.: lead) possam atualizar sem recarregar.

## Fases de desenvolvimento

1. **Preparação**  
   - Revisar requisitos obrigatórios (CPF, NB, UF, consentimentos, dados bancários).  
   - Validar credenciais Finanto e cron jobs (`pipeline:sync`, `finanto:loans:sync`).  
   - Alinhar com operadores o fluxo CPF → IN100 → Ofertas → Proposta/Termo → Contrato → Acompanhamento.

2. **Etapa 1 – Captura e IN100**  
   - Implementar formulário com validação e histórico das consultas.  
   - Bloquear etapas seguintes até `in100_status = success`.  
   - Exibir cards de saldo/margem e lista de contratos resumidos.

3. **Etapa 2 – Ofertas**  
   - Tabela reduzida com ação única “Selecionar oferta” e painel lateral com detalhes.  
   - Registrar usuário/timestamp da seleção; mostrar alerta quando não houver ofertas.  
   - Botão “Recarregar ofertas” com badge “Sincronizado há X min”.

4. **Etapa 3 – Proposta e Termo**  
   - Exibir status da simulação (`simulation_id`, tracking) e iframe do termo.  
   - Botões “Copiar link”, “WhatsApp”, “SMS”; dropdown “Canal de autorização” + comentário obrigatório.  
   - Logar cada envio/polling e habilitar “Confirmar autorização recebida”.

5. **Etapa 4 – Contrato e Assinatura**  
   - Resumo da oferta/dados bancários; botão “Enviar contrato” com logs de request/response.  
   - Card “Assinatura do Lead” com timeline (enviado, visto, assinado) e ações de reenvio/lembrar.  
   - Persistir payloads em `loan_proposal_bank_payloads` e atualizar `loan_proposals`.

6. **Etapa 5 – Acompanhamento**  
   - Timeline vertical com todos os marcos, card “Status Finanto” e botão “Forçar sincronização”.  
   - Modal para logs/payloads e links rápidos para lead/proposta.  
   - Integração com dashboards/widgets do lead.

7. **QA e Go-live**  
   - Automatizar testes (unit/feature) para os novos fluxos.  
   - Preparar runbook para operadores (checklist, scripts de atendimento).  
   - Rodar piloto controlado antes de liberar para toda a operação.

## Telas e componentes

1. **Painel de Captura / IN100**  
   - Inputs CPF/NB/UF/Data de nascimento/Agência/Conta + checkbox de consentimento.  
   - Botão “Consultar IN100”, histórico retrátil, cards de saldo/margem, tabela de contratos com modal “Ver detalhes”.

2. **Painel de Ofertas**  
   - Tabela `Regra | Parcela | Troco | Prazo | Status | Selecionar` + painel lateral com CET/banco/saldo.  
   - Badge “Sincronizado há X min” e botões “Recarregar ofertas”, “Usar esta oferta”.

3. **Painel Proposta & Termo**  
   - Bloco “Status da Proposta” (simulation_id, tracking, status Finanto).  
   - Iframe + botões “Copiar link”, “WhatsApp”, “SMS”, dropdown “Canal”, comentário obrigatório, log lateral.

4. **Painel Contrato / Assinatura**  
   - Resumo da oferta/dados bancários, botão “Enviar contrato”, log de payloads.  
   - Card “Assinatura do Lead” com status chips e timeline; ações de reenvio/lembrar.

5. **Painel Timeline & Logs**  
   - Card consolidado (`case.stage`, `loan_status`, `signature_status`, responsável, última atualização).  
   - Timeline vertical (IN100 → oferta → proposta → termo → contrato → assinatura → liberação).  
   - Botão “Forçar sincronização” e modal de logs/payloads.

## Analytics e dashboard

### API `/api/analytics/finanto-simulations`
- **Filtros**: `token`, `date_from`, `date_to`, `status` (CSV), `broker_id`, `employee_id`, `integration_id`.
- **Resposta**:
  - `summary`: total, pending, success, rejected, converted, converted_linked, conversion_rate, first/last_created_at.
  - `status`: distribuicao por status.
  - `timeline`: agregacao diaria (`day`, `total`, `success`, `converted`).
  - `brokers` e `integrations`: top 10 com conversao por corretor/integracao.

### Dashboard interno
- Card **"Finanto INSS - Simulacoes"** em `app/Views/dashboard/index.php` consome o endpoint acima.
- `public/assets/js/dashboard-analytics.js` sincroniza filtros do painel principal, atualiza resumo, timeline (Chart.js) e tabelas de top corretores/integracoes.
- Botao "Atualizar" refaz a chamada mantendo os filtros atuais.
- **Propostas internas unificadas**: toda proposta disparada pelo operador na tela de casos Finanto deve registrar `loan_proposals.product_type = finanto_inss` e `loan_proposals.integration_id`. Os widgets do dashboard somam esses registros junto com demais produtos; certifique-se de atualizar `DashboardController::loadLoanWidgets` para incluir o filtro `product_type = 'finanto_inss'` e agrupar por status, garantindo que as metas reflitam o volume interno mesmo sem fluxo publico.

### Pipeline & metas digitais
- O endpoint `/api/analytics/finanto-simulations` agora retorna a chave `pipeline`, com:
  - `summary.total`: total de casos no funil (com *last_synced_at*).
  - `summary.concluded_cases` e `summary.concluded_amount`: casos e valor liberado via Finanto.
  - `stages[]`: lista ordenada pelas etapas configuradas em `config/finanto_inss_pipeline.php`, com rótulo e contagem.
- `dashboard-analytics.js` renderiza essas informações no card Finanto (dois cartões extras + lista de etapas). Qualquer filtro aplicado no dashboard principal também filtra o funil (por período, corretor ou funcionário).
- `FinantoInssPipelineService` é disparado ao final de cada etapa crítica (IN100, cálculo, termo, contrato) tanto pelo `FinantoInssCaseController` quanto pela `FinantoInssDigitalService`, mantendo o snapshot sincronizado para dashboards/funil.
- `GoalProjectionService` soma o volume das etapas `concluded` diretamente do snapshot (`finanto_inss_pipeline_snapshots`) e adiciona o resultado em `goalPlan['company']['finanto_disbursed']`. O card de metas passa a mostrar o acumulado total e destaca quanto veio da jornada digital.
- Checklist operacional na tela do caso (`FinantoInssCaseController::show`) reforça a sequência IN100 → cálculo → simulação → termo → contrato. Cada linha acende automaticamente conforme os dados ficam disponíveis, guiando o operador sem sair do Saque Fácil.

## Exclusoes administrativas e recuperacao

- **Pontos de entrada**:
- `POST /finanto/simulations/{id}/delete` (legado: tela antiga de pre-simulacoes).
  - `POST /dashboard/funnel/finanto-inss/{case}/delete` (funil Finanto INSS).
- Apenas administradores conseguem acionar essas rotas; o motivo e obrigatorio e a acao exige token CSRF valido.
- Impactos imediatos:
  - Pre-simulacoes removem o registro e deixam o lead elegivel para uma nova `createFromIds` na tela de pre-simulacao.
  - Casos Finanto eliminam tambem ofertas (`finanto_inss_offers`) e o snapshot do pipeline (`finanto_inss_pipeline_snapshots`), prevenindo residuos na jornada.
- Auditoria: cada exclusao gera uma linha em `storage/logs/finanto_debug.log`:
  - `finanto_simulation_deleted` inclui `simulation_id`, `record_id`, `lead_id`, `integration_id`, `deleted_by`, `reason`.
  - `finanto_case_deleted` inclui `case_id`, `lead_id`, `integration_id`, `deleted_by`, `reason`.
- Procedimento de recuperacao:
  1. Consultar o log para identificar `lead_id`/`integration_id` e o motivo registrado.
  2. Pre-simulacoes podem ser recriadas via tela interna (`Nova pre-simulacao`), reaproveitando o mesmo lead e integracao. Se o `simulation_id` ainda existir no parceiro, informe ao suporte Finanto para liberar nova tentativa.
  3. Casos podem ser reprocessados convertendo novamente a pre-simulacao correspondente (usando o mesmo lead) ou executando o fluxo digital (`FinantoInssDigitalService::submit`). Assim que um novo caso for criado, rode `php automation.php pipeline:sync` (ou acione o job `finanto.inss.pipeline.sync`) para reconstituir os snapshots.
  4. Registrar no hand-off interno o que foi recuperado e anexar o trecho do log como evidencia.

## Testes automatizados (grupo Finanto)

| Script | Cobertura |
|--------|-----------|
| `tests/FinantoAdminServiceDeletionTest.php` | Valida exclusoes administrativas de pre-simulacoes/casos e as entradas de log correspondentes. |
| `tests/FinantoInssFlowTest.php` | Sanitizacao, payloads e limpeza em `FinantoInssFlow`. |
| `tests/FinantoPreviewReuseTest.php` | Reaproveitamento de pre-simulacao no `LoanProposalController`. |
| `tests/FinantoSimulationServiceTest.php` | Fluxo `FinantoInssSimulationService` (create, reject, convert) com fakes em memoria. |
| `tests/FinantoDigitalServiceTest.php` | Normalizacao de regras, coleta de mensagens e decode na `FinantoInssDigitalService`. |
| `tests/FinantoSimulationAnalyticsServiceTest.php` | Metricas agregadas do endpoint analitico. |
| `tests/FinantoDashboardWidgetsTest.php` | Confirma a existencia dos componentes Finanto no dashboard. |

### Como executar

```bash
composer test:finanto
```

O comando acima executa toda a suite Finanto (sem dependencias externas, usando fakes in-memory).

## Referencias rapidas

- Casos: `finanto_inss_cases`
- Pre-simulacoes: `finanto_inss_simulations`
- Ofertas: `finanto_inss_offers`
- Pipeline snapshot: `finanto_inss_pipeline_snapshots`
- Codigo fonte: `app/Services/Finanto/*`
- Logs debug: `storage/logs/finanto_debug.log`