# Assistência InvestMoz — entrega incremental

Implementada uma base **interna, lexical e determinística**, com gateway Laravel, React, fontes, revisão e suspensão. Não é ainda a plataforma generativa/RAG híbrida completa solicitada. Nenhum modelo, embedding ou reranker está activo, e não há selecção final de fornecedor baseada em benchmark generativo local.

## Execução local confirmada — 26/09/2026

- Migration `2026_09_26_120000_investmoz_ai_foundation` aplicada à base local após backup, restauro isolado e reconciliação de 69 tabelas existentes.
- `INVESTMOZ_AI_ENABLED=true` confirmado no ambiente local; acesso a `/management/ai` limitado aos gestores já autorizados. Oito endpoints REST internos registados, além das rotas Inertia.
- Suite PHP completa: **118 testes, 1.080 verificações aprovadas**. Inclui nove testes dedicados à base assistiva/fusão. PHPStan, Pint, TypeScript e build aprovados.
- Benchmark FTS: oito casos sintéticos PT/EN, todos com resultado esperado. Medianas por caso entre 1,091 e 1,604 ms; estes números não são latência de geração nem SLA.
- Backup e manifesto: `storage/app/private/ai-backup-20260926-155758/`. A configuração anterior foi conservada nesse directório privado; não o publicar.
- Nenhum documento institucional foi inventado ou carregado na base local; os dados de teste foram usados apenas na base isolada e revertidos. Corpus autorizado deve ser fornecido pelos responsáveis.
- Sem benchmark Mistral/Qwen/BGE, integração SuiteCRM real ou teste visual em navegador. Produção continua não aprovada.

## Utilização

Após migrations e activação local `INVESTMOZ_AI_ENABLED=true`, aceder a `/management/ai` com conta gestora e email verificado. A página não concede novos privilégios a utilizadores registados.

1. Carregar um `.txt` UTF-8 autorizado, com até 195 KiB, ou seleccionar um documento activo do cadastro existente. A classificação gravada é interna; não importar documentos confidenciais/restritos nesta fase.
2. Registar fonte HTTPS, proprietário, evidência de autorização, idioma, natureza declarada e validade. Não se faz download do URL; é uma referência, não um mecanismo de importação remota.
3. Outra pessoa gestora confirma a autorização. Só depois a fonte entra na pesquisa. A autorização interna não valida juridicamente a fonte nem torna oficial o seu conteúdo.
4. Consultar excertos, comparar oportunidades por filtros ou executar regras de qualidade/prazos. Consulta sem evidência não produz uma conclusão.
5. Pedir revisão, dar feedback ou suspender capacidades. Feedback `unsafe` suspende a capacidade; o controlo de emergência não partilha o limite de consultas.

Os resultados são guardados encriptados com a chave Laravel. A auditoria contém identificadores, versões, modo e latência, sem pergunta ou texto dos fragmentos. Revogar uma fonte ou alterar a sua versão/checksum/classificação impede consultas e oculta resultados anteriores que dela dependam. A triagem exige consentimento específico existente em `consents`, com `subject_ref` igual à referência do pedido e `purpose=ai_assistance`; consentimento de contacto não é reutilizado como consentimento de IA.

## Artefactos

- [Arquitectura e limites](architecture.md)
- [Modelos, licenças e recursos](models.md)
- [Benchmark lexical sintético executado](benchmark-results.json)
- [Cobertura funcional e pipeline](coverage.md)
- [Contrato dos endpoints](api.md)
- [Esquema vectorial proposto, não executado](vector-proposal.sql)

## Validação e operação

Com uma base PostgreSQL isolada terminada em `_test`, migrations aplicadas e `APP_ENV=testing`:

```sh
php artisan ai:benchmark
php vendor/bin/phpunit --filter 'AiGateway|AiHybrid' --do-not-cache-result
```

O benchmark usa oito casos sintéticos PT/EN, cinco repetições por caso, e reverte os dados numa transacção. Não mede qualidade gerativa, PT-MZ validado por especialistas, carga, concorrência, recall sobre corpus real ou custo total de operação.

Migrations aplicacionais não instalam pgvector nem modelos. Fazer backup/restauro antes da activação no ambiente de destino. Para suspensão global, definir `INVESTMOZ_AI_ENABLED=false` e limpar cache de configuração; preservar fontes, documentos e revisões. O rollback das tabelas com dados é recusado.

Não activar em produção antes de validar corpus, mandatos, retenção, privacidade, acessibilidade, carga, recuperação, revisão por pares e fornecedor. Não houve envio a SuiteCRM, treino, fine-tuning ou chamadas pagas de modelos.