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, 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 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, data-dictionary.csv e table-catalog.csv.

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

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
• Casos de uso detalhados
• ERD do schema reconciliado
• Arquitectura e migrations
• Validação e auditoria de conclusão
• 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/