# Projeto: HISCON 360 – Parser, Painel e Motor de Oportunidades

## 1. Visão Geral
- **Objetivo**: ingerir o extrato HISCON (layout fixo) de cada lead, estruturar os dados e abastecer um painel no CRM com suporte a simulações manuais e geração automática de oportunidades via motor de regras.
- **Escopo**:
  1. Upload, parsing e armazenamento do HISCON (PDF + payload JSON).
  2. Card exclusivo no detalhe do lead exibindo o snapshot atual e histórico.
  3. Simulações manuais por contrato (checkbox + ação “Simular oportunidade”), com sugestão do melhor banco/produto para atender cada parcela.
  4. Motor de regras mensal que avalia leads com HISCON, projeta próximas oportunidades e agenda automaticamente follow-ups no módulo de agendamentos.
- **Perfil de usuários**: Administrador, Corretor e Funcionário (mesma base de permissões do módulo de leads).

## 2. Arquitetura de Alto Nível
```
Upload PDF → HisconParser → lead_hiscon_snapshots (PDF + JSON)
                                         ↓
                               Lead Panel (card HISCON)
                                         ↓
             Seleção manual (checkbox)               Motor mensal
                  ↓                                       ↓
            Simulação Oportunidade → lead_opportunities ← OpportunityRuleEngine
```

## 3. Modelo de Dados

### 3.1 Tabela `lead_hiscon_snapshots`
| Coluna | Tipo | Descrição |
|---|---|---|
| `id` | PK | Identificador |
| `lead_id` | FK -> `leads` | Lead associado |
| `file_path` | string | Caminho do PDF armazenado em disco |
| `hash` | string | Hash SHA-256 para deduplicação |
| `document_datetime` | datetime | Data/hora original do HISCON (cabeçalho) |
| `verification_code` | string | Código de autenticação do INSS |
| `payload` | json | JSON estruturado (beneficiário, margens, contratos etc.) |
| `status` | enum (`ok`, `parser_failed`) | Estado do processamento |
| `errors` | json nullable | Lista de campos com problema (quando falha) |
| `created_by` | FK -> `users` | Usuário que importou |
| `created_at` / `updated_at` | datetime | Auditoria |

### 3.2 Tabela `lead_opportunities`
| Coluna | Tipo | Descrição |
|---|---|---|
| `id` | PK | Identificador |
| `lead_id` | FK -> `leads` | Lead alvo |
| `hiscon_snapshot_id` | FK -> `lead_hiscon_snapshots` | Snapshot base (opcional) |
| `contract_origin_code` | string | Código do contrato avaliado (ex.: FIN0000) |
| `contract_number` | string | Número completo do contrato |
| `type` | enum (`portabilidade`, `refinanciamento`, `novo_consignado`, etc.) |
| `source` | enum (`manual_simulation`, `rule_engine`) |
| `payload` | json | Dados usados na análise (margens, taxas, parcelas) |
| `status` | enum (`nova`, `em_andamento`, `concluida`, `descartada`) |
| `priority` | tinyint | Prioridade sugerida (1-5) |
| `notes` | text | Observações do motor ou do usuário |
| `created_by` | FK -> `users` | Usuário (null para motor) |
| `created_at` / `updated_at` | datetime | Auditoria |

### 3.3 Tabela `opportunity_rules`
| Coluna | Tipo | Descrição |
|---|---|---|
| `id` | PK | Identificador |
| `name` | string | Nome amigável |
| `description` | text | Explicação da regra |
| `condition_expression` | text | Expressão (ex.: JSONPath + operadores) |
| `action_type` | enum | Tipo de oportunidade gerada |
| `priority` | tinyint | Prioridade sugerida |
| `schedule` | enum (`monthly`, `weekly`, `on_import`) | Frequência |
| `enabled` | boolean | Ativa/inativa |
| `valid_from` / `valid_to` | datetime | Janela de aplicação |
| `metadata` | json | Config extra (limiares, taxa mínima, etc.) |
| `created_at` / `updated_at` | datetime | Auditoria |

### 3.4 Tabela `opportunity_logs`
| Coluna | Tipo | Descrição |
|---|---|---|
| `id` | PK | Identificador |
| `lead_opportunity_id` | FK | Oportunidade relacionada |
| `rule_id` | FK -> `opportunity_rules` | Regra aplicada (quando motor) |
| `log_type` | enum (`created`, `updated`, `closed`, `error`) |
| `message` | text | Detalhe do evento |
| `payload` | json | Snapshot de dados usados |
| `created_at` | datetime | Auditoria |

## 4. Parser HISCON

### 4.1 Pipeline
1. **Extração de texto** com `PyPDF2` (texto nativo, sem OCR).
2. **Normalização**: remover quebras, ajustar encoding (acentos), separar seções.
3. **Mapeamento**:
   - Beneficiário: nome, benefício, status, banco pagador, agência, conta, flags (procurador, representante, pensão).
   - Margens: disponível, reservada, extrapolada, utilizada, base de cálculo, total comprometido, máximo permitido.
   - Contratos Ativos: código, número, banco, competência inicial/final, parcelas, valor parcela, valor emprestado, valor liberado (quando existir), CET, taxa de juros, datas de inclusão/primeiro desconto.
   - Contratos Reservados/Excluídos: mesma estrutura (armazenar para histórico, opcional nos cards).
   - RMC/RCC: se disponível, extrair limite e status.
4. **Validação**:
   - Campos obrigatórios (nome, número do benefício, pelo menos uma margem).
   - Prazo das parcelas (início/fim coerente).
   - Registro de warnings (ex.: valor extrapolado > 0).
5. **Persistência**: JSON final (beneficiary, margins, contracts_active, contracts_other, metadata).

### 4.2 JSON (snapshot)
```json
{
  "beneficiary": {
    "name": "...",
    "benefit_type": "...",
    "benefit_number": "...",
    "status": "...",
    "payment_bank": "...",
    "agency": "...",
    "account": "...",
    "flags": {
      "has_procurator": false,
      "has_representative": false,
      "alimony": false,
      "loan_enabled": true,
      "loan_eligible": true
    }
  },
  "margins": {
    "available": 0.0,
    "reserved": 1122.87,
    "extrapolated": 167.91,
    "used": 167.91,
    "consignable": 1175.38,
    "base_calculation": 3358.23,
    "total_committed": 1511.20,
    "max_committed": 1343.28,
    "benefit_margin_extrapolated": 0.0
  },
  "contracts": {
    "active": [
      {
        "origin_code": "FIN0000",
        "contract_number": "547697329",
        "bank": "QI SOCIEDADE DE CREDITO DIRETO S.A.",
        "situation": "ATIVO",
        "origination_type": "REFINANCIAMENTO",
        "inclusion_date": "2025-10-10",
        "competence_start": "11/2025",
        "competence_end": "10/2033",
        "installments": 96,
        "installment_value": 805.39,
        "principal_value": 36743.26,
        "released_value": 36230.45,
        "cit": {
          "cet_month": 1.76,
          "cet_year": 23.22,
          "interest_month": 1.72,
          "interest_year": 22.70
        },
        "first_discount": "2025-12-10"
      }
    ],
    "others": [
      { "...": "Contratos reservados/suspensos/excluídos" }
    ]
  },
  "metadata": {
    "document_datetime": "2025-10-15T15:04:16",
    "verification_code": "251015QWETOFH8VVZ6MU22",
    "pages": 16,
    "source": "hiscon_pdf_v2024",
    "parser_version": "1.0.0",
    "warnings": []
  }
}
```

## 5. UI – Card HISCON (Lead)
### 5.1 Layout
- **Header**: “HISCON – Histórico de Empréstimo Consignado” + badge com data da última importação.
- **Beneficiário & Benefício**: nome, status, banco/conta, flags (alertas).
- **Margens**: tabela com colunas “Dispo­nível, Reservada, Utilizada, Extrapolada, Base cálculo, Total comprometido, Máximo permitido”.
- **Contratos Ativos**:
  - Tabela com colunas: `Selecionar`, `Origem/Código`, `Banco`, `Competência`, `Parcelas`, `Parcela`, `Valor contratado`, `Valor liberado`, `Taxa mensal`, `Taxa anual`.
  - Checkbox por linha (apenas contratos ativos/suspensos). Botão “Simular oportunidade” habilita quando há seleção.
- **Histórico** (colapsável): lista de importações anteriores (data, usuário, link para baixar PDF).
- **Ações**:
  - Botão “Importar novo HISCON” (modal file upload).
  - Botão “Baixar PDF” para o snapshot atual.
  - Botão “Simular oportunidade” (quando há seleção manual).

### 5.2 Estados
- **Sem HISCON**: card mostra CTA “Nenhum HISCON importado” + botão de upload.
- **Parser falhou**: alerta vermelho “Falha ao processar arquivo” + botão “Reprocessar”.

## 6. Simulação Manual
- Evento: usuário seleciona um ou mais contratos → clica “Simular oportunidade”.
- Backend: `HisconOpportunityService::simulate(lead, contracts, snapshot)`:
  - Calcula margem disponível pós-quitação/portabilidade.
  - Estima valor refinanciável (parcelas restantes × parcela - saldo liberado).
  - Aplica regras rápidas (ex.: se taxa > 1.8% ao mês → sugerir portabilidade).
  - Retorna payload com recomendação, possíveis ganhos (redução de parcela, troco, etc.).
- Frontend: exibir resultado em modal com opção “Gerar oportunidade” (cria registro `lead_opportunities` com source `manual_simulation`).

## 7. Motor de Regras (Automático)
- **Execução**: comando `php automation hiscon:scan`.
  - Frequência: mensal (1º dia útil) + opcionalmente ao importar novo HISCON (`schedule = on_import`).
  - Seleciona leads com snapshot `status = ok`.
  - Recupera regras ativas de `opportunity_rules`.
  - Avalia cada contrato (JSONPath/expressões) e cria/atualiza oportunidades.
- **Exemplo de regra**:
  - Nome: “Portabilidade taxa alta”.
  - Condição: `contract.cit.interest_year > 25` **AND** `margins.available > 0`.
  - Ação: criar oportunidade `type = portabilidade`, `priority = 4`, payload com taxa atual, parcelas restantes, recomendação do banco mais competitivo e agendamento automático para contato futuro.
- **Logs/Auditoria**: `opportunity_logs` registra resultado (criado, já existia, descartado).
- **Notificações**: ao gerar nova oportunidade, opcional disparar alerta (badge no lead, e-mail para corretor).

## 8. Segurança e Compliance
- Armazenar PDFs e JSON em diretório protegido (apenas usuários autenticados com permissão).
- Registrar importador e horário (auditoria LGPD).
- Oferecer mecanismo de exclusão do documento caso cliente solicite.
- Sanitizar exibição (mascarar CPF parcialmente quando necessário).

## 9. Roadmap Detalhado
1. **Infra/Modelos**
   - Criar migrations das tabelas (`lead_hiscon_snapshots`, `lead_opportunities`, `opportunity_rules`, `opportunity_logs`).
   - Criar modelos Eloquent correspondentes + relacionamentos com `Lead`.
2. **Parser `HisconParser`**
   - Implementar serviço com testes unitários (input fixture → JSON esperado).
   - Tratamento de erros e normalização (acentos, conversão de valores).
3. **Upload & API**
   - Rota `POST /leads/{id}/hiscon` (CSRF + ACL).
   - Controller aciona parser, salva snapshot, retorna status.
   - Logar eventos em `storage/logs/hiscon.log`.
4. **Card HISCON no Lead**
   - Atualizar `LeadController::show` para carregar snapshot.
   - Criar partial view `leads/partials/hiscon.php` com layout descrito.
   - Implementar modal de upload e ação de download.
5. **Simulação Manual**
   - Endpoint `POST /leads/{id}/hiscon/simulate` (recebe array de contratos).
   - Serviço `HisconOpportunityService` calcula sugestões, ranqueia bancos/produtos e retorna JSON.
   - Modal na view exibe resultado; botão “Criar oportunidade” (persistir em `lead_opportunities` e gerar registro em `lead_schedules` para contato futuro, quando aplicável).
6. **Motor de Regras**
   - Implementar `OpportunityRuleEngine` com suporte a expressões (JSONPath + DSL simples).
   - Comando agendado `php automation hiscon:scan`.
   - Registrar logs, evitar duplicidades (oportunidade já aberta) e criar agendamentos automáticos (tabela de lembretes) com base na data ideal de contato.
7. **Histórico & Reprocessamento**
   - Exibir lista de snapshots anteriores.
   - Permitir reprocessar (reparsear JSON) sem reenviar PDF.
8. **Integração WhatsApp (futuro)**
   - Possibilitar que oportunidade criada gere disparo de mensagem pré-aprovada (ver doc `whatsapp-integration.md`).

## 10. Riscos & Mitigações
- **Mudança no layout HISCON**: monitorar código de versão (`metadata.source`), criar testes regressivos, flag `parser_failed` para revisão manual.
- **Falhas de parsing**: capturar exceções e registrar stack trace em log; reduzir dependência de regex frágil.
- **Volume de dados**: armazenar snapshots antigos; considerar limpeza ou compressão após X meses.
- **Motor de regras complexo**: iniciar com critério simples; planejar UI futura para manutenção de regras.
- **Privacidade**: mascarar dados sensíveis; limitar acesso à equipe autorizada.

## 11. Próximos Passos Imediatos
1. Aprovar esta documentação.
2. Implementar migrations + parser + card HISCON (MVP).
3. Configurar cron (ou job scheduler) para o motor mensal.
4. Revisão conjunta com time comercial para ajustar regras.

## 12. Apêndices

### Apêndice A — Regras Finanto para Portabilidade e Refin
- **Escopos cobertos**: operações de portabilidade e refin de portabilidade vinculadas à Finanto.
- **Limites de idade**: regra geral até 69 anos e 10 meses; benefícios do tipo LOAS limitados a 66 anos e 10 meses. Aplicar restrições regionais (ver itens específicos) antes da aprovação.
- **Bancos proibidos**: rejeitar automaticamente contratos originados em QI, Inbursa, Safra, Pine, Facta, C6, BNP Paribas, PicPay ou Alfa (flag `eligible = false` independentemente do perfil).
- **Perfis de contrato** (avaliar total de parcelas, parcelas pagas ou restantes):
  1. *Perfil 1* — contratos com 1 a 12 parcelas pagas **ou** 83 a 72 parcelas restantes: aceitar apenas se `banco_origem` ∈ {Banrisul, Bradesco (237), Itaú (341), Itaú (029), Banco do Brasil, BMG, Digio, Caixa, Crefisa, PagBank, BRB, Sicoob, Inter, Nubank, Zema, Sicredi, Senff, Paulista}, `valor_parcela` ≥ 190, taxa de juros mensal ≥ 1,57%.
  2. *Perfil 2* — contratos com 12 a 20 parcelas pagas **ou** 72 a 64 parcelas restantes: aceitar apenas se `banco_origem` ∈ {Santander, Agibank, PAN, Daycoval, Paraná Banco, Mercantil, Parati}, `valor_parcela` ≥ 190, taxa de juros mensal ≥ 1,38%.
  3. *Perfil 3* — contratos com mais de 20 parcelas pagas **ou** menos de 64 parcelas restantes: aceitar bancos elegíveis de ambos os perfis anteriores (excluídos os bancos bloqueados), `valor_parcela` ≥ 97, taxa de juros mensal ≥ 1,17%.
- **Portabilidade pura**: aprovar somente quando o saldo devedor estimado for igual ou superior a R$ 8.000,00 e houver entre 80 e 95 parcelas restantes; exigir taxa mínima de 1,75% ao mês.
- **Portabilidade com refin**: permitir quando o contrato gerar troco mínimo equivalente a 5% do endividamento após refinanciamento. Dispensa taxa de entrada.
- **Tipos de tabela aceitos**: Seguro 25% (Power), Seguro 15% (Max) e Sem seguro. Persistir tipo escolhido no payload para auditoria.
- **Faixas de saldo e taxa**:
  - Saldo ≥ R$ 8.000,00: aceitar taxas entre 1,66% e 1,85% a partir de 1 parcela paga.
  - Saldo entre R$ 4.000,00 e R$ 7.999,99: exigir taxa mínima de 1,80% com pelo menos 12 parcelas pagas.
- **Bancos habilitados a partir de 12 parcelas**: Pan, Santander, Paraná Banco, Parati, Mercantil, Agibank e Daycoval; usar essa lista como filtro adicional para perfis com maior maturidade.
- **Restrições adicionais**:
  - Calcular idade sempre a partir de `lead.date_of_birth` na data de processamento (considerar aniversário no ano corrente). O motor deve rejeitar casos sem data válida.
  - UF do benefício em PB, AP, TO ou RR: só aprovar se idade <= 59 anos.
  - Benefício 32 ou 92 (invalidez previdenciária): aprovar apenas se idade >= 60 anos.
  - Benefício 21: reprovar se idade > 45 anos.
  - Validar sempre o limite de comprometimento de 5% do endividamento total antes de aprovar.
- **Interpretação da taxa**: os limiares “taxa a partir de” referem-se à taxa de juros mensal registrada no HISCON (`taxa_juros_mes`). O motor deve garantir que o contrato analisado tenha taxa maior ou igual ao mínimo exigido pelo perfil.
- **Saídas sugeridas**: ao aprovar, anexar ao payload da oportunidade o `perfil_finanto`, lista de bloqueios aplicados (quando houver), tipo de tabela selecionado e indicação se o caso foi aceito por portabilidade pura ou refin (dependendo do saldo liberado estimado).
- **Margem livre detectada**: quando `margem_disponivel` > 0, sugerir oportunidade de “empréstimo novo Finanto” com parcela alvo equivalente a 99% da margem livre. Se existir `margem_extrapolada`, subtrair esse valor antes de calcular a parcela sugerida. Bloquear casos em que a parcela resultante seja < R$ 20,00 (limite mínimo da Finanto).
- **Formato das indicações**:
  - **Operações imediatas**: exibir em lista (no card HISCON ou módulo de oportunidades) a frase “Indicação de operações imediatas — Contrato {contrato}, parcela R$ {valor_parcela}, banco original {banco_origem}, tipo de operação indicada: {tipo} para Finanto Bank”, acompanhada de botão “Gerar simulação” que pré-preenche a oportunidade com o payload calculado.
  - **Operações futuras**: para contratos que ainda não atendem as regras, mas cumprirã o critério em data projetada, exibir lista “Indicação de operações futuras — Contrato {contrato}, parcela R$ {valor_parcela}, banco original {banco_origem}, tipo de operação indicada: {tipo} para Finanto Bank (a partir de {data_prevista})”, também com ação “Gerar simulação” que agenda ou preenche a oportunidade.
  - **Status automático**: operações futuras identificadas devem ser criadas automaticamente como oportunidades com `status = agendada` e agendamento em `{data_prevista}`, permitindo disparo automático e antecipação via "Gerar simulação".
### Apêndice B — Cálculo de Parcelas Restantes (HISCON)
- **Campos necessários**: `data_inicio_desconto`, `data_fim_desconto`, `quantidade_parcelas` e `valor_parcela` presentes na seção de contratos ativos do JSON gerado pelo parser.
- **Referência temporal**: considerar a data de processamento (`now()`) ajustada para o corte da folha INSS (todo dia 28 já contempla o próximo ciclo). Caso o parser seja executado antes do dia 28, projetar parcelas futuras a partir do mês corrente; após o dia 28, incluir o próximo desconto já provisionado.
- **Algoritmo sugerido**:
  1. Converter `data_inicio_desconto` e `data_fim_desconto` em objetos `DateTimeImmutable` (assumir dia 1º do mês se o HISCON não trouxer dia específico).
  2. Calcular total de parcelas previstas usando `quantidade_parcelas`.
  3. Estimar parcelas pagas pela diferença entre `data_inicio_desconto` e `now()` (limitado ao intervalo do contrato) dividida por ciclos mensais completos.
  4. `parcelas_restantes = max(0, quantidade_parcelas - parcelas_pagas_calculadas)`.
  5. Se `now()` ultrapassar `data_fim_desconto`, zerar `parcelas_restantes`.
- **Validação**: sempre que o HISCON trouxer número de parcelas já pagas explicitamente, priorizar esse valor como “fonte oficial” e usar o cálculo acima apenas como fallback.
- **Uso no motor**: com `parcelas_restantes` e `parcelas_pagas` derivadas, o motor consegue classificar o contrato no perfil Finanto adequado e projetar saldo devedor e possibilidade de refin.

## 13. Plano de Implementação por Módulos

| Fase | Escopo | Entregáveis principais | Pré-requisitos | QA/Observações |
|------|--------|------------------------|----------------|----------------|
| **0. Preparação** | Setup de repositório, ambientes e dados de teste | Checklist de permissões, fixtures HISCON anonimizadas, definição de SLAs de parser | Aprovação desta documentação | Garantir controle de versão do layout HISCON (metadata `source`) |
| **1. Parser & Persistência** | Implementar `HisconParser`, migrations das tabelas e storage seguro | Serviço de parsing com testes unitários, migrations aplicadas, comandos de upload | Fase 0 concluída | Validar contra amostras reais; registrar falhas em log dedicado |
| **2. APIs & Upload** | Endpoints para ingestão e reprocessamento, ACL e logging | Rotas `POST /leads/{id}/hiscon`, reprocessamento, policies de acesso | Fases 0-1 | Testar fluxo com CSRF expirado, anexar eventos em `lead_hiscon_snapshots` |
| **3. UI do Lead** | Card HISCON, histórico, gatilho de simulação manual | Componentes Blade atualizados, UX responsiva, integração com Goal Dashboard quando aplicável | Fases anteriores | Revisar contraste/temas conforme perfis de usuário |
| **4. Motor de Regras Finanto** | `OpportunityRuleEngine` com regras Finanto e cálculo de parcelas | Engine com DSL mínima, scheduler `hiscon:scan`, oportunidades imediatas/futuras | Fases 1-3 | Cobrir perfis Finanto, idade, margem livre e status agendado nas operações futuras |
| **5. Simulações & Popups** | Modal de simulação, criação automática de oportunidades, popups de selo e leads atrasados | Serviço `HisconOpportunityService` expandido, popups reativos conforme requisitos do dashboard | Fases 3-4 | Ensaiar UX de popups para corretores/funcionários; validar acessibilidade |
| **6. Automação & Alertas** | Agendamentos, notificações internas, integrações futuras | Jobs no scheduler, notificações no painel e futuras integrações WhatsApp | Fases 4-5 | Garantir idempotência e registros em `opportunity_logs` |
| **7. QA Final & Implantação** | Testes integrados, performance, hand-off | Plano de testes por perfil (admin/corretor/funcionário), atualização do hand-off comercial, checklist LGPD | Todas as fases concluídas | Pilotar com subset de leads antes do rollout completo |

- **Governança**: cada fase deve encerrar com revisão técnica + validação do time comercial para garantir aderência às regras Finanto.
- **Dependências externas**: mapear eventual necessidade de atualização no módulo de agendamentos antes da Fase 4.
- **Métricas de sucesso**: taxa de parsing sem erro (>95%), tempo médio de sugestão automática < 1h pós-upload, conversão das oportunidades Finanto > baseline atual.


## 14. Orientacoes Complementares de Parsing
- Identificar cada valor de tabela combinando cabecalho de linha e coluna (ex.: margem_disponivel.rcc = linha 'Margem Disponivel*' / coluna 'RCC').
- Se qualquer cabecalho esperado nao for encontrado ou trouxer valor inconsistente, retornar status parser_failed e detalhar em errors.
- Validar margens por modalidade confrontando com o bloco 'Valores do Beneficio' antes de persistir o snapshot.

## 15. Diretrizes de UI para o Snapshop HISCON
- **Bloco “Informações do Benefício”**: cabeçalho com colunas `beneficio`, `especie`, `representante_legal`, `bloqueado_para_emprestimos`, `pensao_alimenticia`, `situacao`. Abaixo, sub-blocos com banco pagador (banco/meio pagamento/agencia/conta/DDB) e contribuição atual.
- **Cards de resumo**: sequência horizontal exibindo `valor_beneficio`, `base_de_calculo`, `margem_total_disponivel`, `margem_disponivel_aumento`, `margem_disponivel_rmc`, `margem_disponivel_rcc`. Cada card mostra título, valor formatado e tooltip opcional.
- **Tabela de contratos**: lista com colunas `Banco`, `Contrato`, `Averbação`, `Início/Final do desconto`, `Valor do contrato`, `Taxa`, `Parcela`, `Pagas/Total`. Incluir checkbox por linha para seleção manual e destaque da taxa (azul) e parcela (laranja) conforme print de referência.
- **Gatilhos**: manter botão “Atualizar margem” e ações contextuais no rodapé, reutilizando componentes padrões do dashboard para consistência visual.