# Levantamento de requisitos - Modelo Atual

### 1. Visão Geral e Escopo

****Objetivo:****<span style="white-space: pre-wrap;"> Automatizar a triagem de e-mails comerciais das empresas </span>****Autvix****<span style="white-space: pre-wrap;"> e </span>****Advix Soluções****<span style="white-space: pre-wrap;"> , utilizando LLM para classificar demandas contra uma base de serviços (BUS).</span>

****Principais Metas:****

- Triagem automática de solicitações via e-mail e anexos.
- Redução do tempo operacional e atrasos na resposta ao cliente.
- Persistência de dados para auditoria e análise via Metabase.

---

### 2. Requisitos Funcionais (RF)

<table id="bkmrk-iddescri%C3%A7%C3%A3orefer%C3%AAnci" style="margin-bottom: 32px;"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr><td style="border: 1px solid;">****ID****

</td><td style="border: 1px solid;">****Descrição****

</td><td style="border: 1px solid;">****Referência Técnica****

</td></tr><tr><td style="border: 1px solid;">****RF01****

</td><td style="border: 1px solid;">Capturar e-mails e anexos das caixas comerciais e salvar no OneDrive.

</td><td style="border: 1px solid;">Power Automate

</td></tr><tr><td style="border: 1px solid;">****RF02****

</td><td style="border: 1px solid;">Identificar o remetente e validar se o domínio já existe na base de contatos.

</td><td style="border: 1px solid;"><span style="white-space: pre-wrap;">Tabela </span>`<span class="editor-theme-code">contacts</span>`

</td></tr><tr><td style="border: 1px solid;">****RF03****

</td><td style="border: 1px solid;">Converter anexos (.pdf, .xlsx, .zip) para texto para processamento pelo LLM .

</td><td style="border: 1px solid;">Scripts Python

</td></tr><tr><td style="border: 1px solid;">****RF04****

</td><td style="border: 1px solid;">Classificar e-mails em categorias pré-definidas com nível de confiança e justificativa.

</td><td style="border: 1px solid;">LLM gpt-oss:120b

</td></tr><tr><td style="border: 1px solid;">****RF05****

</td><td style="border: 1px solid;">Monitorar a saúde dos serviços de ingestão e processamento.

</td><td style="border: 1px solid;"><span style="white-space: pre-wrap;">Tabela </span>`<span class="editor-theme-code">service_heartbeat</span>`

</td></tr><tr><td style="border: 1px solid;">****RF06****

</td><td style="border: 1px solid;">Armazenar o corpo do e-mail em HTML e texto plano para rastreabilidade.

</td><td style="border: 1px solid;"><span style="white-space: pre-wrap;">Tabela </span>`<span class="editor-theme-code">emails</span>`

</td></tr></tbody></table>

---

### 3. Requisitos Não Funcionais (RNF)

- ****RNF01 - Integridade Referencial:****<span style="white-space: pre-wrap;"> O sistema deve garantir que nenhum e-mail seja órfão de um contato ou de uma classificação através de chaves estrangeiras (</span>`<span class="editor-theme-code">FK</span>`).
- ****RNF02 - Desempenho de Busca:****<span style="white-space: pre-wrap;"> Utilização de índices (</span>`<span class="editor-theme-code">KEY</span>`<span style="white-space: pre-wrap;">) em campos críticos como </span>`<span class="editor-theme-code">tipo</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">recipient</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">domain</span>`<span style="white-space: pre-wrap;"> e </span>`<span class="editor-theme-code">received_at</span>`<span style="white-space: pre-wrap;"> para otimizar os dashboards.</span>
- ****RNF03 - Padronização de Caracteres:****<span style="white-space: pre-wrap;"> Todo o banco deve utilizar o charset </span>`<span class="editor-theme-code">utf8mb4_unicode_ci</span>`<span style="white-space: pre-wrap;"> para suportar caracteres especiais e emojis de e-mails.</span>
- ****RNF04 - Disponibilidade:****<span style="white-space: pre-wrap;"> O status do sistema deve ser reportado via </span>**heartbeat**<span style="white-space: pre-wrap;"> em intervalos regulares.</span>

---

### 4. Modelo de Dados (Arquitetura do Banco)

O banco de dados MySQL é o coração da persistência do EscopoVix, estruturado da seguinte forma:

#### ****A. Núcleo de Comunicação****

- **`<strong class="editor-theme-bold editor-theme-code">contacts</strong>`**<span style="white-space: pre-wrap;">: Gerencia os remetentes. Classifica o </span>`<span class="editor-theme-code">tipo</span>`<span style="white-space: pre-wrap;"> entre </span>`<span class="editor-theme-code">CLIENTE</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">PORTAL</span>`<span style="white-space: pre-wrap;"> ou </span>`<span class="editor-theme-code">DESCONHECIDO</span>`<span style="white-space: pre-wrap;"> e marca se o contato já está cadastrado no sistema legiado (</span>`<span class="editor-theme-code">is_cadastrado</span>`).
- **`<strong class="editor-theme-bold editor-theme-code">emails</strong>`**: Armazena os metadados da mensagem, o caminho da pasta no OneDrive (`<span class="editor-theme-code">folder_path</span>`), a contagem de anexos e o conteúdo textual.

#### ****B. Inteligência e Classificação****

- **`<strong class="editor-theme-bold editor-theme-code">classifications</strong>`**<span style="white-space: pre-wrap;">: Armazena o veredito do modelo </span>`<span class="editor-theme-code">gpt-oss:120b</span>`.
    - ****Tipos permitidos****<span style="white-space: pre-wrap;">: </span>`<span class="editor-theme-code">DENTRO_ESCOPO</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">FORA_ESCOPO</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">ANALISE_TECNICA</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">NAO_SOLICITACAO</span>`.
    - ****Campos de IA****<span style="white-space: pre-wrap;">: </span>`<span class="editor-theme-code">confidence</span>`<span style="white-space: pre-wrap;"> (0 a 1) e </span>`<span class="editor-theme-code">reasoning</span>`<span style="white-space: pre-wrap;"> (explicação lógica da IA para aquela decisão).</span>

#### ****C. Apoio e Monitoramento****

- **`<strong class="editor-theme-bold editor-theme-code">cliente</strong>`**: Tabela de referência para cruzamento de dados de domínio, CNPJ e Razão Social.
- **`<strong class="editor-theme-bold editor-theme-code">service_heartbeat</strong>`**<span style="white-space: pre-wrap;">: Registra se o serviço </span>`<span class="editor-theme-code">watcher</span>`<span style="white-space: pre-wrap;"> ou </span>`<span class="editor-theme-code">processor</span>`<span style="white-space: pre-wrap;"> está </span>`<span class="editor-theme-code">running</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">stopped</span>`<span style="white-space: pre-wrap;"> ou em </span>`<span class="editor-theme-code">error</span>`, incluindo metadados em JSON para diagnóstico.

---

### 5. Fluxo de Dados e Pipeline

1. ****Ingestão****: Power Automate salva e-mail no OneDrive.
2. ****Detecção****<span style="white-space: pre-wrap;">: O </span>`<span class="editor-theme-code">watcher</span>`<span style="white-space: pre-wrap;"> detecta a nova pasta.</span>
3. ****Identificação****<span style="white-space: pre-wrap;">: O sistema busca ou cria o registro em </span>`<span class="editor-theme-code">contacts</span>`<span style="white-space: pre-wrap;"> via domínio do e-mail.</span>
4. ****Processamento****<span style="white-space: pre-wrap;">: O LLM analisa o texto e gera um registro em </span>`<span class="editor-theme-code">classifications</span>`<span style="white-space: pre-wrap;"> com o </span>`<span class="editor-theme-code">reasoning</span>`.
5. ****Finalização****<span style="white-space: pre-wrap;">: O registro em </span>`<span class="editor-theme-code">emails</span>`<span style="white-space: pre-wrap;"> é atualizado com o </span>`<span class="editor-theme-code">classificacao_id</span>`<span style="white-space: pre-wrap;"> e marcado como processado.</span>