Investidor-V2/docs/investmoz/levantamento-funcional-e-eventos.md

# Levantamento funcional, entidades e eventos — InvestMoz

**Data do levantamento:** 9 de Outubro de 2026  
**Âmbito:** aplicação Laravel/React presente neste repositório.  
**Base de evidência:** README, rotas, controladores, modelos, migrations e documentação em `docs/investmoz/`. A existência de uma tabela, rota ou documento não prova que a função esteja activa em produção.

## 1. Resumo executivo

O projecto é uma plataforma de investimento com área pública e área autenticada. Abrange descoberta de oportunidades e negócios, manifestações de interesse, gestão de candidaturas e carteira, CRM local, geografia e zonas de investimento, simulador e governação fiscal, catálogo documental, educação, assistência de terra, parcerias, balcão virtual, IA com fontes e integrações preparadas.

O README apresenta a base inicial do portal (sectores, oportunidades e manifestações). O código actual e os documentos de domínio registam a extensão funcional posterior. Para o inventário detalhado dos fluxos, consultar [casos-de-uso-aplicacao-actual.md](casos-de-uso-aplicacao-actual.md), que identifica 24 casos de uso. Este documento complementa-o com uma visão de domínio, um diagrama resumido de relações e a frequência observável dos eventos.

## 2. Âmbito e método

Foi feito inventário dos caminhos acessíveis no repositório: **981 ficheiros** por `rg --files`, excluindo dependências geradas `vendor` e `node_modules`. Dentro da aplicação foram consultados, em particular, `routes/`, `app/Models/`, `app/Http/Controllers/`, `database/migrations/`, `database/seeders/` e `docs/investmoz/`. O número é uma contagem do inventário local nessa data, não um inventário de anexos externos ou de dados de produção.

Classificação usada:

- **Implementado no código:** rota, controlador, job, comando ou schema identificável.
- **Documentado/planeado:** descrito em documentação, sem prova suficiente de execução integrada.
- **Frequência de negócio desconhecida:** não há amostra de eventos de produção nem telemetria para calcular volume por hora/dia/mês.
- **Cadência técnica explícita:** periodicidade configurada no scheduler ou no mecanismo de fila.

## 3. Actores e sistemas

| Actor | Objectivo principal | Áreas usadas |
|---|---|---|
| Visitante | Consultar conteúdos públicos e iniciar pedidos | Portal, oportunidades, negócios, zonas, documentos, simulador |
| Investidor/utilizador | Manter perfil, favoritos, rascunhos, submissões, documentos e mensagens | Espaço do investidor, carteira, assistência, parcerias |
| Gestor de portal/CRM | Rever interesses, gerir leads, tarefas, catálogo e publicação | CRM local, gestão de portal |
| Gestor territorial | Manter projectos, clusters, corredores, relações, geografia e zonas | Catálogo territorial, GIS, zonas |
| Revisor documental | Conferir proveniência, versão, hash, autorização e análise antimalware | Biblioteca documental |
| Gestor fiscal | Rever fontes, parâmetros e versões das regras fiscais | Governação fiscal, simulador |
| Gestor de educação | Manter competências, necessidades, cursos, capacidades e propostas | Educação |
| Gestor/agente de assistência | Tratar pedidos de terra e pedidos do balcão virtual | Assistência de terra, balcão |
| Parceiro institucional | Participar em oportunidades/parcerias e colaborar em salas | Parcerias |
| Administrador | Gerir autenticação, segurança, configurações e permissões | Administração |
| Sistema externo/worker | Receber/enviar mensagens ou executar trabalho assíncrono | Outbox/inbox, filas, integrações |

Papéis são uma leitura funcional dos fluxos. A autorização efectiva depende das policies, middleware e permissões implementadas, não apenas desta tabela.

## 4. Catálogo de casos de uso

O documento [Casos de uso da aplicação actual](casos-de-uso-aplicacao-actual.md) detalha pré-condições, fluxos e dados para cada caso. Índice consolidado:

| ID | Caso de uso | Actor principal | Resultado |
|---|---|---|---|
| UC-01 | Consultar página inicial e serviços | Visitante | Entrada no serviço público autorizado |
| UC-02 | Pesquisar sectores e oportunidades | Visitante/investidor | Lista/detalhe e possível favorito/interesse |
| UC-03 | Consultar negócio existente | Visitante/investidor | Consulta da oferta divulgável |
| UC-04 | Criar conta, autenticar e recuperar acesso | Utilizador | Sessão autenticada/verificada |
| UC-05 | Manifestar interesse numa oportunidade | Visitante/investidor | Pedido recebido para tratamento |
| UC-06 | Manifestar interesse num negócio existente | Investidor | Pedido ligado ao negócio e consentimento |
| UC-07 | Guardar oportunidade e manter espaço do investidor | Utilizador | Favorito, dossier ou item na carteira |
| UC-08 | Criar e manter submissão de investimento | Investidor | Submissão em rascunho com histórico |
| UC-09 | Submeter candidatura | Investidor | Entrada em fila de tratamento |
| UC-10 | Gerir negócio existente | Proprietário/gestor | Registo revisto e eventualmente publicável |
| UC-11 | Tratar interesses no CRM | Gestor | Qualificação, lead, tarefa e seguimento |
| UC-12 | Gerir catálogo territorial | Gestor territorial | Projectos, clusters, corredores e relações |
| UC-13 | Gerir zonas de investimento | Gestor territorial/revisor | Zona validada, publicada ou suspensa |
| UC-14 | Carregar, verificar e publicar documento | Revisor documental | Documento preservado com estados independentes |
| UC-15 | Criar/retomar rascunho de simulação | Visitante/utilizador | Rascunho recuperável, sem cálculo implícito |
| UC-16 | Executar simulação | Visitante/utilizador | Resultado, obrigações, fontes e relatório |
| UC-17 | Gerir regra fiscal | Gestor fiscal | Versão de regra passa por revisão/aprovação |
| UC-18 | Gerir educação e competências | Gestor de educação | Catálogo, análise de lacunas e proposta |
| UC-19 | Abrir/tratar assistência de terra | Investidor/gestor | Caso acompanhado até encaminhamento/fecho |
| UC-20 | Criar e gerir parceria | Investidor/parceiro | Interesse, sala, mensagens, documentos e marcos |
| UC-21 | Usar balcão virtual | Utilizador/agente | Pedido de serviço acompanhado até resolução |
| UC-22 | Usar IA com evidência | Gestor autorizado | Execução rastreável ligada a fontes e feedback |
| UC-23 | Sincronizar sistemas externos | Worker/sistema externo | Eventos recebidos/enviados e divergências registadas |
| UC-24 | Auditar alterações | Sistema/gestor/auditor | Histórico e correlação para operações relevantes |

## 5. Diagrama de entidades e relações

Diagrama lógico resumido por domínios. As cardinalidades representam a estrutura documentada; algumas relações polimórficas, opcionais ou em tabelas de junção estão simplificadas. Para o ERD de schema detalhado, consultar [erd.mmd](erd.mmd), [data-dictionary.csv](data-dictionary.csv) e [table-catalog.csv](table-catalog.csv).

```mermaid
erDiagram
    USER ||--o{ INVESTOR : possui
    USER ||--o{ SUBMISSION : cria
    USER ||--o{ SIMULATION : executa
    USER ||--o{ AUDIT_EVENT : origina
    SECTOR ||--o{ OPPORTUNITY : classifica
    OPPORTUNITY ||--o{ INTEREST_REQUEST : recebe
    EXISTING_BUSINESS ||--o{ INTEREST_REQUEST : recebe
    INVESTOR ||--o{ INTEREST_REQUEST : manifesta
    INTEREST_REQUEST ||--o| LEAD : converte
    LEAD ||--o{ CRM_TASK : acompanha
    OPPORTUNITY ||--o{ SUBMISSION : referencia
    SUBMISSION ||--o{ SUBMISSION_REVISION : versiona
    SUBMISSION ||--o{ SUBMISSION_EVENT : regista
    SUBMISSION ||--o{ DOCUMENT_LINK : anexa
    PROJECT }o--o{ ECONOMIC_CLUSTER : associa
    PROJECT }o--o{ DEVELOPMENT_CORRIDOR : associa
    PROJECT ||--o{ INVESTMENT_GAP : identifica
    INVESTMENT_ZONE ||--o{ ZONE_REVISION : versiona
    INVESTMENT_ZONE ||--o{ ZONE_RELATION : liga
    INVESTMENT_ZONE ||--o{ ZONE_ATTACHMENT : documenta
    DOCUMENT ||--o{ DOCUMENT_VERSION : versiona
    DOCUMENT ||--o{ MALWARE_SCAN : analisa
    DOCUMENT }o--o{ PORTAL_RESOURCE : disponibiliza
    SIMULATION ||--o{ SIMULATION_SCENARIO : contém
    SIMULATION_SCENARIO ||--o{ SIMULATION_RESULT : produz
    SIMULATION_RESULT ||--o{ SIMULATION_OBLIGATION : discrimina
    SIMULATION_RESULT ||--o{ RESULT_SOURCE : fundamenta
    TAX_RULE_VERSION }o--o{ LEGAL_SOURCE : fundamenta
    PROJECT ||--o{ TRAINING_NEED : requer
    SKILL }o--o{ OCCUPATION : relacionada
    TRAINING_PROVIDER ||--o{ COURSE : oferece
    USER ||--o{ LAND_ASSISTANCE_CASE : requer
    PARTNERSHIP ||--o{ PARTNERSHIP_INTEREST : recebe
    PARTNERSHIP ||--o| PARTNERSHIP_ROOM : abre
    PARTNERSHIP_ROOM ||--o{ PARTNERSHIP_MESSAGE : contém
    DESK_CASE ||--o{ DESK_EVENT : regista
    AI_SOURCE ||--o{ AI_CHUNK : divide
    AI_SOURCE ||--o{ AI_RUN : suporta
    OUTBOX_EVENT }o..|| SYNC_RUN : processa
    SYNC_RUN ||--o{ RECONCILIATION_ISSUE : detecta
```

### 5.1 Domínios e entidades nucleares

| Domínio | Entidades nucleares | Relações principais |
|---|---|---|
| Identidade e acesso | `users`, `passkeys`, sessões, organizações, memberships | Utilizador possui perfil e inicia operações protegidas |
| Catálogo público | `sectors`, `opportunities`, catálogos de referência, recursos do portal | Sector classifica oportunidades; publicação controla exposição |
| Negócios existentes | `existing_businesses`, objectos, locais, revisões, mandatos | Negócio tem objectos/locais/documentos e workflow próprio |
| Investidor e CRM | `investors`, `interest_requests`, `leads`, `contacts`, oportunidades CRM, tarefas | Interesse pode converter-se em lead e gerar tarefas/actividades |
| Carteira e submissões | dossiers, `investment_submissions`, necessidades, revisões, eventos, mensagens, anexos | Submissão pertence a utilizador e liga-se a oportunidade/negócio |
| Território e GIS | `projects`, `economic_clusters`, `development_corridors`, `geo_locations`, `value_chains`, `investment_gaps` | Relações muitos-para-muitos documentam associação territorial/económica |
| Zonas de investimento | `investment_zones`, fontes legais, geometrias, relações, anexos, revisões | Zona tem localização, evidência, relações e estado de validação/publicação |
| Documentos | `documents`, versões, scans, associações por domínio, recursos do portal | Documento pode ser associado a várias entidades; disponibilidade, estado documental e uso em cálculo são independentes |
| Simulação e fiscalidade | rascunhos, `simulations`, cenários, resultados, obrigações, fontes, regras versionadas | Execução usa versões/parâmetros elegíveis e preserva as fontes do resultado |
| Educação | skills, occupations, providers, courses, training needs/capacity, propostas | Projectos expressam necessidades relacionadas com competências e formação |
| Serviços e colaboração | casos de terra, balcão virtual, parcerias, salas, mensagens, documentos, marcos | Casos e salas mantêm eventos e participantes próprios |
| IA e governação | controlos, fontes/chunks, execuções, feedback, auditoria | Execução de IA deve poder ser rastreada às fontes e ao actor |
| Integrações | `outbox_events`, `inbox_events`, `sync_runs`, reconciliações | Eventos são idempotentes/correlacionáveis; desenho de schema não prova integração activa |

## 6. Eventos e frequência

### 6.1 Frequência explicitamente configurada

| Evento/processo | Gatilho | Frequência/cadência no código | Natureza e observação |
|---|---|---|---|
| Escalar tarefas vencidas (`investmoz:escalate-overdue-tasks`) | Scheduler Laravel | **A cada 15 minutos**, com `withoutOverlapping()` | Única periodicidade de scheduler encontrada em `routes/console.php`; execução real requer scheduler/cron activo |
| Executar simulação (`RunSimulation`) | Pedido de cálculo aceite | Por submissão, via fila, `afterCommit` | Assíncrono; frequência depende da procura e de workers activos |
| Analisar documento (`ScanDocumentForMalware`) | Upload/solicitação de scan em fluxos suportados | Por documento, via fila, `afterCommit`; job único por identidade configurada | Cadência sob procura; requer worker e scanner configurados. Upload/publicação não confirma scan limpo |
| Comparar compatibilidade MNE (`CompareMneBusiness`) | Alteração de negócio que agenda comparação | Por alteração aplicável, em fila específica e `afterCommit` | Trabalho assíncrono/sombra; volume real desconhecido |
| Notificar recepção de interesse (`NotifyInterestReceived`) | Disparo esperado após recepção de interesse | Job existe, mas não foi localizada chamada a `dispatch()` no código consultado; frequência de execução não confirmada | Tratar como capacidade prevista até localizar/activar o disparo; entrega efectiva também depende de configuração e worker |
| Auditoria, revisões e eventos de domínio | Acção de utilizador/sistema | No momento da operação que os gera | Orientado a evento; não há taxa histórica neste levantamento |
| Outbox/inbox e sincronização externa | Evento de domínio ou mensagem externa | Sem periodicidade operacional confirmada neste código/documentação consultada | Estrutura preparada; documentação aponta sincronização externa real como pendente/não activada |

### 6.2 Frequência por categoria de actividade

| Categoria | Frequência funcional esperada | O que é possível afirmar |
|---|---|---|
| Leituras públicas (home, catálogo, oportunidade, negócio, mapas/referências) | Sob procura do visitante | Há endpoints/páginas; sem logs ou analytics não se quantificam consultas |
| Escritas de investidor (interesses, favoritos, submissões, mensagens, perfil) | Sob acção do utilizador | São iniciadas por pedido explícito; não há volume observado disponível |
| Gestão (revisão, publicação, CRM, regras, zonas, catálogo) | Sob trabalho de gestores autorizados | Fluxos e protecções documentados; frequência por papel não medida |
| Simulação e rascunhos | Sob utilização do simulador; rascunhos podem ser actualizados/retomados | Rota e jobs encontrados; não assumir execução periódica nem cálculo fiscal por guardar rascunho |
| Uploads e análise documental | Sob envio/reanálise de documento | Job de scan é disparado por fluxos suportados; scan e publicação são estados distintos |
| Auditoria | Sob operações auditadas | A frequência acompanha as operações instrumentadas; cobertura total precisa de confirmação por fluxo |
| Regras fiscais e fontes | Sob processo de revisão/aprovação e alteração normativa | Não há calendário fixo; fonte publicada não activa automaticamente cálculo |
| Integrações externas | Não determinável/activação pendente | Tabelas de integração e documentação não são prova de entrega ou sincronização real |

### 6.3 Frequência observada versus frequência de execução

Não foram disponibilizados logs, contagens de `audit_events`, filas, analytics, pedidos HTTP ou exportação da base activa. Por isso, **não é possível apresentar eventos por hora/dia/mês, sazonalidade, taxa de falhas ou utilizadores activos**. A cadência de 15 minutos é apenas o intervalo configurado para o comando agendado. Para apurar frequência real, recolher métricas autorizadas por tipo de evento, intervalo temporal e resultado, sem expor dados pessoais; documentar período da amostra, filtros, retenção e origem. Não inferir métricas a partir de seeders, testes, screenshots ou schema.

## 7. Sequência de alto nível

```text
Visita pública
  -> pesquisa catálogo/oportunidades/negócios/território
  -> interesse, candidatura, assistência ou simulação
  -> autenticação e consentimento quando exigidos
  -> gravação do pedido/rascunho e histórico
  -> trabalho assíncrono quando aplicável (scan, cálculo, notificação)
  -> revisão por responsável autorizado
  -> decisão, comunicação ou publicação com autorização
  -> auditoria e eventual integração externa homologada
```

## 8. Regras transversais que afectam os fluxos

- Disponibilidade para consulta, situação jurídica/documental e uso em regra/cálculo são estados independentes.
- Importar ou publicar documento não activa regra nem cálculo fiscal.
- Relações sem citação/evidência verificada devem ficar pendentes e identificadas.
- Guardar um rascunho não equivale a submeter ou aprovar.
- A divulgação obedece à autorização registada e ao seu âmbito.
- Documento original, proveniência, identificador, edição/data, hash e histórico devem ser preservados; não marcar autenticidade, vigência, direitos ou scan como confirmados sem evidência.
- Integração desenhada (outbox/inbox) não equivale a sincronização activa.
- Alterações a dados activos exigem confirmação de backup/restauro e acção autenticada necessária; testes/migrações devem usar exclusivamente base QA isolada, conforme `AGENTS.md`.

## 9. Limitações e pontos para validação

1. A cobertura implementada de cada UC varia; alguns documentos descrevem trabalho parcial, proposto ou bloqueado. Consultar `docs/investmoz/validation.md`, `completion-audit-2026-10-04.md`, `delivery-gaps.md` e os README de cada domínio antes de declarar operação concluída.
2. O ERD resumido não substitui constraints/FKs, cardinalidades exactas, escopos de acesso ou estados enumerados no schema e OpenAPI.
3. A frequência real de utilização e dos eventos de negócio permanece **indeterminada** sem telemetria operacional.
4. Execução do scheduler, workers, ClamAV, notificações, SuiteCRM e restantes conectores depende de configuração e operação externa verificável.
5. O inventário desta tarefa é do repositório, não dos ficheiros/anexos em armazenamento externo nem da base de dados de produção.

## 10. Fontes locais principais

- [README do projecto](../../README.md)
- [Casos de uso detalhados](casos-de-uso-aplicacao-actual.md)
- [ERD do schema reconciliado](erd.mmd)
- [Arquitectura e migrations](architecture-and-migrations.md)
- [Validação](validation.md) e [auditoria de conclusão](completion-audit-2026-10-04.md)
- Rotas: `routes/web.php`, `routes/api.php`, `routes/investment.php`, `routes/partnerships.php`, `routes/land-assistance.php`, `routes/investment-zones.php`, `routes/territorial-registry.php`
- Cadência: `routes/console.php`; trabalhos assíncronos em `app/Jobs/`