# Camada assistiva InvestMoz — arquitectura e âmbito

Estado: implementação incremental para desenvolvimento, 26/09/2026. Não aprovada para produção. A base local não tem modelos de inferência nem pgvector instalados. Não existe benchmark generativo local que permita seleccionar um modelo final.

## 1. Diagnóstico anterior à implementação

Confirmados no repositório: Laravel 13.30.1, React 19.2.8, PostgreSQL 17/PostGIS, sessão Fortify, gate `manage-portal`, documentos canónicos, consentimentos, auditoria, CRM local e cliente SuiteCRM. Sem serviço de IA, tabela de fragmentos ou versão documental para RAG. `documents.version_no` e `sha256` são preservados como origem das versões indexadas; não criar outro cadastro de documentos.

Hardware observado: Windows ARM64/Parallels, cerca de 16 GiB RAM, seis processadores virtuais Apple Silicon, adaptador gráfico virtual com 2 GiB reportados (não constitui GPU de inferência), aproximadamente 183 GiB livres. Sem binários Docker, Ollama ou nvidia-smi identificados. O PostgreSQL instalado não tem os ficheiros de extensão pgvector.

Os benchmarks dos candidatos generativos/embeddings/reranker ficam **bloqueados por infraestrutura e modelos não provisionados**. Não descarregar dezenas de GB nem alterar o PostgreSQL partilhado para fingir compatibilidade. Executar uma linha de base determinística PT/EN, sem custo de API, e manter geração desactivada. A escolha final depende de medição no hardware de destino, dataset revisto e aprovação do custo operacional.

## 2. Componentes

```mermaid
flowchart LR
    React[React: assistência e revisão] --> Gateway[Laravel AI Gateway]
    Gateway --> Access[Finalidade, autorização, suspensão]
    Gateway --> Retrieval[Recuperação autorizada]
    Retrieval --> PG[PostgreSQL: documentos, versões, fragmentos, FTS]
    Retrieval -. opcional .-> Vector[pgvector e embeddings]
    Gateway --> Rules[Regras explicáveis e excertos]
    Gateway -. após benchmark .-> Model[Serviço substituível de modelos]
    Gateway --> Review[Resultados e revisão humana]
    Review --> Audit[Auditoria sem conteúdo confidencial]
    Review -. encaminhamento autorizado .-> CRM[CRM existente / SuiteCRM]
```

O React apenas comunica com Laravel. A primeira interface é interna, para gestores verificados; nenhuma fonte confidencial ou restrita é elegível para indexação nesta fase. A aprovação de uma fonte é autorização interna de uso, não validação jurídica ou acreditação oficial.

## 3. Linha de base dos sete casos

| Caso      | Execução inicial                                                                                               | Limite explícito                                                     |
| --------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| UC-IA-001 | Recuperar excertos autorizados com fonte, data, natureza e recusa sem resultados                               | Sem resposta generativa ou aconselhamento jurídico/financeiro        |
| UC-IA-002 | Full-text search PT/EN, filtros de fontes e acesso antes da recuperação                                        | Híbrido/embeddings/reranker exigem infraestrutura e benchmark        |
| UC-IA-003 | Correspondência estruturada com oportunidades publicadas, factores, lacunas de informação e regras versionadas | Sem previsão de retorno, pontuação financeira ou inferência sensível |
| UC-IA-004 | Regras sobre campos declarados da manifestação, sem usar nome/email/telefone                                   | Não altera lead, prioridade ou responsável oficial                   |
| UC-IA-005 | Alertas sobre campos, fontes expiradas e responsáveis                                                          | Nenhuma correcção automática de dados                                |
| UC-IA-006 | Prazos vencidos de tarefas CRM abertas                                                                         | Sem caminho crítico ou impacto orçamental inventado                  |
| UC-IA-007 | Excertos de documentos autorizados                                                                             | Não constitui resumo generativo completo nem acta oficial            |

## 4. Segurança e governação

- Finalidades enumeradas, feature flag global e suspensão por capacidade em base de dados, consultada a cada execução.
- Ingestão inicialmente apenas de texto UTF-8 canónico autorizado, com checksum verificado; PDF/OCR, Office e ficheiros activos não processados sem pipeline segura.
- Revisão por pessoa diferente da submissão antes de recuperar uma fonte. Revogação, eliminação, expiração e alteração de checksum/versão invalidam a recuperação.
- Minimização: não enviar conteúdo para modelos externos nesta fase. Identificadores de execução, modelos/regras, versão de prompt, fontes e latência são auditáveis; pergunta bruta não é registada em logs.
- Feedback categórico e pedido de revisão; resultados não alteram entidades oficiais ou geram comunicações externas.
- Não usar os dados para treino ou fine-tuning. Retenção operacional e política jurídica definitiva pendentes; activar em produção apenas depois da sua aprovação.
- Cache de conteúdo desactivada para evitar fontes ou permissões obsoletas. Não é necessário circuit breaker de rede na linha de base sem chamadas de modelo; um futuro adaptador deve ter timeout, limites, circuito e fallback sem evidência inventada.

## 5. Gates para a fase generativa

Fixar revisão/hash de cada modelo, licença, contexto, precisão e recursos. Avaliar PT-MZ/EN, perguntas sem resposta, fontes adversariais, revogação de acesso, fidelidade das citações, fuga de dados, latência p50/p95, RAM/VRAM, concorrência e custo por mil pedidos. Não usar resultados publicados como se fossem medições locais. Somente habilitar um adaptador após superar a linha de base e ter aprovação humana do corpus e dos limites.

Reutilizar SuiteCRM apenas após metadados, OAuth, permissões e reconciliação verificados. Nenhum resultado de IA deverá criar uma decisão oficial, rejeitar investidor ou escrever em SuiteCRM sem confirmação explícita no produto e contrato homologado.