# Módulo de Produção de Empréstimos – Modelagem (Módulo 1)

## Objetivos

1. Registrar propostas de empréstimo associadas a leads, corretores e funcionários.
2. Garantir rastreabilidade completa (status, valores, responsáveis, integrações bancárias).
3. Preparar base para integrações com APIs dos bancos já cadastrados no sistema.
4. Permitir auditoria e histórico de alterações, mantendo aderência à LGPD.

## Entidades Principais

### loan_proposals
- `id` (PK)
- `lead_id` (FK → leads.id)
- `broker_id` (FK → users.id) – corretor responsável
- `employee_id` (FK → users.id, nullable) – funcionário executor
- `created_by` (FK → users.id)
- `api_integration_id` (FK → api_integrations.id, nullable) – banco escolhido
- `status` (enum)
- `product_type` (varchar) – FGTS, INSS, consignado, etc.
- `requested_amount`, `approved_amount`, `disbursed_amount`
- `installment_value`, `term_months`, `interest_rate`
- `commission_value`, `commission_percent`
- `sign_method` (enum: presencial, digital, biometria)
- `external_reference` (varchar) – protocolo do banco
- `submitted_at`, `approved_at`, `funded_at`, `paid_at`
- `last_synced_at`, `next_sync_at`
- `notes` (text)
- `metadata` (json armazenado em TEXT)
- timestamps (`created_at`, `updated_at`)

### loan_proposal_status_history
- `id` (PK)
- `proposal_id` (FK → loan_proposals.id)
- `old_status`, `new_status`
- `description` (text)
- `payload` (json/text) – respostas do banco
- `changed_by` (FK → users.id, nullable) – null quando automático
- `changed_at` (datetime)
- `ip_address`

### loan_proposal_documents
- `id` (PK)
- `proposal_id` (FK → loan_proposals.id)
- `label`
- `storage_path`
- `mime_type`
- `file_size`
- `status` (enum: pending, uploaded, approved, rejected)
- `uploaded_by` (FK → users.id)
- `uploaded_at`, `reviewed_at`, `expires_at`
- `review_notes`

### loan_proposal_bank_payloads
- `id` (PK)
- `proposal_id` (FK → loan_proposals.id)
- `direction` (enum: request, response, webhook)
- `endpoint`
- `payload` (longtext)
- `status_code` (int, nullable)
- `created_at`

### Índices e Relacionamentos
- Índices por `status`, `product_type`, `submitted_at`, `funded_at`.
- Índice composto (`broker_id`, `status`) para relatórios por corretor.
- `loan_proposal_status_history` indexado por (`proposal_id`, `changed_at`).
- Documentos indexados por (`proposal_id`, `status`).

## Regras de Acesso
- Administradores: CRUD completo, visibilidade global.
- Corretores: acesso às propostas de sua equipe (leads onde é broker), leitura de métricas por funcionário.
- Funcionários: acesso às propostas atribuídas a eles ou criadas por eles.
- Operacional: acesso ao painel de operacoes para triagem e acompanhamentos pendentes.
- Logs de auditoria registrados em `loan_proposal_status_history` e tabela de payloads.

## Integração com módulos existentes
- Lead: cada proposta pertence a um lead existente.
- API Integrations: reutiliza tabela atual para definir bancos com API liberada.
- LGPD: `loan_proposals` armazenará campos anonimizáveis (nome, e-mail) através da ligação com `leads`. Em casos de exclusão LGPD, devemos limpar/desvincular `metadata`, `notes` e documentos sensíveis.
- Simplix/Finanto: estruturas semelhantes servem de referência para campos e integração.

## Próximos Passos
1. Criar migrações das tabelas acima.
2. Implementar models e serviços base com métodos de criação, atualização, consulta e histórico.
   - `LoanProposal`, `LoanProposalStatusHistory`, `LoanProposalDocument`, `LoanProposalBankPayload`, `LoanProposalStatusCatalog`.
   - Serviço `LoanProposalService` centraliza validações, permissões (admin, corretor, funcionário) e orquestra status + logs.
3. Adicionar seeds iniciais (status padrão já inseridos na migração).
4. Produzir endpoints/controladores e telas (nos módulos seguintes).
- Presenca Bank CLT: funil interno atualiza 'presenca_bank_clt_cases', cria a proposta automaticamente e registra payloads de request/response em 'loan_proposal_bank_payloads'.

## Fluxo Finanto INSS

O módulo de propostas agora inclui toda a orquestração do consignado INSS com a Finanto:

- **Serviço dedicado**: `App\Services\Finanto\FinantoInssDigitalService` concentra a criação/atualização do case, disparo da simulação (`createSimulation`), envio do contrato (`runSimulationAction`) e sincronização da proposta interna (payloads, status e dados INSS).
- **Backoffice**: o formulário digital na tela de “Nova Proposta” reutiliza o partial `loan/partials/finanto_inss_fields.php`, reduzindo duplicação e garantindo os mesmos campos usados no fluxo público.
- **Canal público**: o controlador `PublicFinantoInssController` aceita capturas via link (`/inss?link={token}`), cria/atualiza o lead e dispara automaticamente o fluxo Finanto. O status pode ser acompanhado em `/inss/status/{tracking_token}`.
- **Configuração**: a integração Finanto deve ter `base_url` e `api_key` preenchidos. Opcionalmente, é possível definir `owner_user_id` no `extra_config` para apontar o corretor responsável pelos leads captados no canal público.
- **Persistência**: a tabela `finanto_inss_cases` passou a armazenar `borrower_birth_date` e `loan_proposal_id`, permitindo reprocessar dados e vincular o case à proposta interna.
- **Ofertas múltiplas**: o fluxo agora gera registros em `finanto_inss_offers`, permitindo apresentar várias combinações de valor/parcela ao cliente. Cada oferta guarda status, payloads da Finanto e referência à proposta interna criada após o aceite.
- **Pré-qualificação IN100**: o funil público foi redesenhado para receber somente CPF e benefício, consultar a IN100 via Finanto, calcular a margem disponível e então montar as ofertas exibidas ao cliente. O retorno completo da IN100 é armazenado em `finanto_inss_cases.in100_payload` para auditoria e geração de propostas.

### Como testar

1. Cadastre (ou atualize) uma integração Finanto com URL base e API Key válidas.
2. Gere um link de captura para o funil `consignado_inss` selecionando a integração Finanto.
3. Acesse `/inss?link={token}` e preencha o formulário público.
4. Revise as ofertas em `/inss/ofertas/{tracking_token}`, selecione uma ou mais combinações e confirme.
5. Após o aceite, acompanhe a contratação em `/inss/status/{tracking_token}` ou pela proposta criada em "Propostas de Empréstimo".