Files
Investidor-V2/docs/investmoz/casos-de-uso-aplicacao-actual.md
T
Nelson_Matsinhe a1b553372e
tests / ci (push) Canceled after 0s
ajuste do tamanho da navbar
2026-10-22 15:26:56 +02:00

18 KiB
Raw Blame History

Casos de uso da aplicação actual

Este documento descreve os processos actualmente implementados ou previstos pelas rotas, controladores, serviços e migrations existentes no projecto. Não substitui regras legais nem autoriza publicação de dados.

1. Actores

Actor Responsabilidade
Visitante Consulta o portal, oportunidades, negócios, zonas e documentos públicos.
Utilizador registado Mantém perfil, rascunhos, submissões, favoritos e mensagens.
Investidor Pesquisa oportunidades, manifesta interesse e acompanha candidaturas.
Gestor Trata interesses, leads, tarefas, oportunidades e catálogo.
Revisor documental Verifica documentos, malware, versões e autorização de divulgação.
Gestor territorial Gere projectos, clusters, corredores, geografia e zonas.
Gestor fiscal Gere fontes legais, versões de regras e parâmetros do simulador.
Gestor de educação Gere competências, necessidades, cursos e propostas.
Parceiro institucional Participa em parcerias, salas, mensagens, documentos e marcos.
Administrador Gere utilizadores, permissões, configurações e instalação de módulos.
Sistema externo Recebe/envi­a eventos através de outbox, inbox e sincronizações.

2. Visão geral do ciclo da aplicação

Portal público
  -> consulta de catálogo
  -> interesse, apoio ou simulação
  -> autenticação/conta quando necessário
  -> candidatura ou submissão
  -> documentos e validação
  -> CRM, tarefas e comunicação
  -> decisão, parceria ou acompanhamento

Os principais agregados são opportunities, existing_businesses, interest_requests, investment_submissions, documents, investment_zones e simulations.

3. UC-01 — Consultar a página inicial e serviços

Actor: Visitante.

Pré-condições: O portal está disponível.

Fluxo principal:

  1. O visitante abre /.
  2. O sistema apresenta a página inicial e os serviços publicados.
  3. O visitante escolhe oportunidades, negócios, zonas, simulador, documentos, apoio ou parcerias.
  4. O sistema aplica apenas dados que estejam disponíveis para o público.

Dados: portal_resources, documents, opportunities, sectors, existing_businesses, investment_zones.

Resultado: O visitante é encaminhado para o processo escolhido.

4. UC-02 — Pesquisar sectores e oportunidades

Actor: Visitante ou investidor.

Fluxo principal:

  1. O actor consulta /oportunidades ou a API de oportunidades.
  2. O sistema filtra por sector, localização, slug, estado e outros critérios.
  3. O detalhe da oportunidade mostra perfil, território, relações, documentos públicos e informação de investimento.
  4. O actor pode iniciar uma manifestação de interesse ou guardar a oportunidade.

Dados: sectors, opportunities, opportunity_profiles, opportunity_facets, opportunity_clusters, opportunity_corridors, opportunity_projects, opportunity_locations, opportunity_favourites.

Resultado: Consulta pública ou início de UC-05/UC-06.

5. UC-03 — Consultar um negócio existente

Actor: Visitante ou investidor.

Fluxo principal:

  1. O actor consulta /negocios.
  2. O sistema lista negócios cujo estado e autorização permitem divulgação.
  3. O actor abre o detalhe pelo slug.
  4. O sistema apresenta apenas título, descrição, modalidade, localização, objectos e documentos autorizados.
  5. O actor pode iniciar uma manifestação de interesse.

Dados: existing_businesses, existing_business_objects, existing_business_locations, existing_business_document_links, documents, interest_requests.

Regra: Dados privados, mandatos e documentos não autorizados não são expostos pelo portal público.

6. UC-04 — Criar conta, autenticar e recuperar acesso

Actor: Visitante/utilizador.

Fluxo principal:

  1. O visitante cria uma conta com nome, email e palavra-passe.
  2. O sistema cria users.
  3. O utilizador confirma o email quando aplicável.
  4. O utilizador inicia sessão.
  5. O sistema aplica as políticas de autenticação, confirmação de palavra-passe e, para operações protegidas, segundo factor.

Dados: users, passkeys, sessions, password_reset_tokens.

Alternativas: Registo rejeitado por email existente; palavra-passe incorrecta; recuperação por token; desafio de dois factores.

7. UC-05 — Manifestar interesse numa oportunidade

Actor: Visitante ou investidor.

Fluxo principal:

  1. O actor abre o formulário de interesse.
  2. Informa contacto, oportunidade, modalidade, valor e mensagem.
  3. O sistema valida os dados, consentimentos e alvo.
  4. É criado interest_requests.
  5. O sistema regista recibo/idempotência quando aplicável.
  6. O sistema envia notificação ou evento de tratamento.

Dados: interest_requests, consents, interest_submission_receipts, notifications, outbox_events.

Estado inicial: received, submitted ou equivalente configurado.

Resultado: O interesse fica disponível para tratamento no CRM.

8. UC-06 — Manifestar interesse num negócio existente

Actor: Investidor.

Fluxo principal:

  1. O investidor escolhe um existing_business publicado.
  2. Selecciona a modalidade e, se aplicável, percentagem e intervalo de valor.
  3. O sistema verifica que o negócio pode receber interesse.
  4. Cria interest_requests.existing_business_id.
  5. Regista consentimento para contacto e partilha da informação.
  6. O caso passa para tratamento interno.

Dados: existing_businesses, interest_requests, investors, consents.

Regra: Um pedido não pode apontar simultaneamente para uma oportunidade e para um negócio existente.

9. UC-07 — Guardar uma oportunidade e manter espaço do investidor

Actor: Utilizador autenticado.

Fluxo principal:

  1. O utilizador abre uma oportunidade.
  2. Escolhe guardar/iniciar no espaço do investidor.
  3. O sistema regista a relação em opportunity_favourites ou inicia uma submissão/dossier.
  4. O utilizador consulta os seus itens em /investidor ou /carteira.

Dados: users, opportunity_favourites, investment_dossiers, investor_accounts, investment_accounts.

10. UC-08 — Criar e manter uma submissão de investimento

Actor: Investidor.

Pré-condições: Utilizador autenticado e verificado.

Fluxo principal:

  1. O investidor cria uma submissão.
  2. O sistema cria investment_submissions com estado draft.
  3. O investidor grava o payload e as necessidades específicas.
  4. Pode adicionar anexos e mensagens.
  5. O sistema cria eventos e revisões para manter histórico.
  6. O investidor consulta ou actualiza a submissão.

Dados: investment_submissions, investment_specific_needs, investment_submission_attachments, investment_submission_events, investment_submission_revisions, investment_messages, documents.

11. UC-09 — Submeter candidatura

Actor: Investidor.

Fluxo principal:

  1. O investidor confirma os dados da submissão.
  2. O sistema verifica campos obrigatórios, alvo e anexos.
  3. A submissão muda de draft para submitted.
  4. É associado ou criado o pedido de interesse, quando exigido.
  5. O sistema cria evento de submissão e notifica a gestão.

Resultado: A candidatura deixa de ser apenas rascunho e entra na fila de tratamento interno.

12. UC-10 — Gerir um negócio existente

Actor: Investidor, proprietário ou gestor.

Fluxo principal:

  1. O actor cria ou actualiza o negócio.
  2. Regista modalidade, descrição, objectos, localização e documentos.
  3. O sistema cria revisões e mantém o snapshot anterior.
  4. Um gestor pode solicitar informação, rever ou rejeitar.
  5. O negócio percorre o workflow configurado.
  6. Apenas após validação e autorização poderá ser publicado.

Dados: existing_businesses, existing_business_objects, existing_business_revisions, existing_business_reviews, business_workflow_transitions, existing_business_mandates, documents.

Estados possíveis: draft, submitted, in_review, needs_information, approved, published, suspended, rejected, withdrawn, archived.

13. UC-11 — Tratar interesses no CRM

Actor: Gestor.

Fluxo principal:

  1. O gestor abre a fila de interesses.
  2. Consulta o pedido, consentimentos e alvo.
  3. Atribui o caso a um responsável.
  4. Converte o interesse em leads, quando aplicável.
  5. Cria tarefas e actividades.
  6. Actualiza o estado e regista o resultado.
  7. Pode associar um crm_opportunity e continuar a negociação.

Dados: interest_requests, leads, investors, contacts, crm_opportunities, tasks, activities, consents.

Estados de interesse: recebimento, qualificação, contacto, diligência, negociação, conversão, recusa, cancelamento ou encerramento.

14. UC-12 — Gerir catálogo territorial

Actor: Gestor territorial.

Fluxo principal:

  1. O gestor cria ou actualiza projectos, clusters e corredores.
  2. Liga projectos a locais.
  3. Liga projectos a clusters e corredores.
  4. Cria cadeias de valor e lacunas de investimento.
  5. Regista a fonte e o estado da relação.
  6. Outro gestor pode validar ou revogar a relação.

Dados: projects, economic_clusters, value_chains, value_chain_links, development_corridors, cluster_projects, corridor_projects, corridor_clusters, investment_gaps, geo_locations.

15. UC-13 — Gerir zonas de investimento

Actor: Gestor territorial com permissão e MFA quando exigido.

Fluxo principal:

  1. Regista a fonte legal em investment_legal_sources.
  2. Cria a zona em investment_zones.
  3. Associa operador, categoria e localização.
  4. Adiciona geometria, anexos e relações com projectos, clusters ou corredores.
  5. Um revisor valida a informação.
  6. A zona é publicada, suspensa ou revogada.
  7. O sistema mantém revisões imutáveis.

Estados: draft, published, suspended; validação pending, validated, historical.

Dados: investment_zones, investment_legal_sources, investment_zone_geometries, investment_zone_relations, investment_zone_links, investment_zone_attachments, investment_zone_revisions.

16. UC-14 — Carregar, verificar e publicar documento

Actor: Gestor documental.

Fluxo principal:

  1. O gestor carrega o ficheiro.
  2. O sistema preserva o original e calcula o hash.
  3. Detecta duplicados e conflitos de versão.
  4. Regista documents e, quando necessário, document_versions.
  5. Executa análise antimalware.
  6. O gestor revê classificação, datas, fonte e autorização.
  7. O documento é associado ao negócio, candidatura, zona, projecto ou portal.
  8. Só então pode ser disponibilizado publicamente.

Dados: documents, document_versions, document_malware_scans, portal_resources, portal_resource_revisions e tabelas *_documents.

Estados documentais: pendente, limpo, infectado, rejeitado, privado, publicável, publicado ou revogado.

17. UC-15 — Criar rascunho de simulação

Actor: Visitante ou utilizador.

Fluxo principal:

  1. O actor abre o simulador.
  2. O sistema cria ou recupera um cookie de recuperação.
  3. Guarda os dados em simulation_form_drafts.
  4. O actor pode continuar mais tarde.
  5. Um utilizador autenticado pode reclamar o rascunho.
  6. O rascunho pode ser ligado a um negócio existente, mediante autorização.

Resultado: Dados incompletos permanecem como rascunho e não são tratados como cálculo fiscal executado.

18. UC-16 — Executar simulação

Actor: Visitante ou utilizador.

Fluxo principal:

  1. O actor submete os dados do simulador.
  2. O sistema escolhe a versão do questionário.
  3. Resolve os parâmetros fiscais elegíveis.
  4. Cria simulations e simulation_scenarios.
  5. Executa o cálculo através de job.
  6. Guarda resultados, obrigações e fontes.
  7. Gera relatório quando solicitado.
  8. Regista auditoria e idempotência.

Dados: questionnaire_versions, simulations, simulation_scenarios, simulation_results, simulation_obligations, simulation_reports, simulation_jobs, simulation_result_sources, simulation_audit_events.

19. UC-17 — Gerir regra fiscal

Actor: Autor, revisor, aprovador ou publicador fiscal.

Fluxo principal:

  1. O autor cria uma versão da regra.
  2. Associa a regra a uma fonte legal.
  3. O revisor verifica expressão, datas e parâmetros.
  4. O aprovador decide.
  5. O publicador disponibiliza a versão.
  6. O sistema regista cada transição.

Dados: simulation_tax_rule_versions, simulation_tax_rule_events, investment_legal_sources, users.

Regra: Importar ou publicar um documento não activa automaticamente um cálculo fiscal.

20. UC-18 — Gerir educação e competências

Actor: Gestor de educação.

Fluxo principal:

  1. Mantém catálogo de competências, profissões, instituições e cursos.
  2. Regista necessidades de formação de projectos.
  3. Associa ocupações e competências.
  4. Regista capacidades e oportunidades educativas.
  5. Analisa lacunas.
  6. Cria proposta de investimento educativo.

Dados: skills, occupations, training_needs, training_providers, courses, education_opportunities, investment_gaps, education_investment_proposals e tabelas skills_edu.

21. UC-19 — Abrir e tratar assistência de terra

Actor: Investidor e gestor de assistência.

Fluxo principal:

  1. O investidor cria um caso de assistência.
  2. Regista localização, necessidade e documentos.
  3. O gestor analisa o caso.
  4. São registadas revisões, eventos e pedidos adicionais.
  5. O caso é encaminhado ou encerrado.

Dados: land_assistance_cases, land_assistance_revisions, land_assistance_events, land_assistance_documents, documents, users.

22. UC-20 — Criar e gerir parceria

Actor: Investidor, organização ou parceiro institucional.

Fluxo principal:

  1. O actor cria um rascunho de parceria.
  2. Regista origem, sector, local e objectivo.
  3. Outro actor manifesta interesse.
  4. A candidatura é aceite ou recusada.
  5. É aberta uma sala de parceria.
  6. Os participantes trocam mensagens e documentos.
  7. São definidos marcos, pagamentos ou acordo.
  8. O sistema regista eventos e notificações.

Dados: portal_partnerships, partnership_origins, partnership_locations, partnership_interests, partnership_rooms, partnership_messages, partnership_documents, partnership_milestones, partnership_events, partnership_notifications.

23. UC-21 — Usar o balcão virtual

Actor: Utilizador autenticado e agente de atendimento.

Fluxo principal:

  1. O utilizador abre um pedido no balcão.
  2. O sistema cria um caso e associa o serviço.
  3. O agente recebe o pedido.
  4. São trocadas mensagens e solicitados documentos.
  5. O caso passa por estados e revisões.
  6. Eventos, notificações e pagamentos são registados.
  7. O caso é resolvido ou encerrado.

Dados: desk_service_versions, desk_cases, desk_requests, desk_documents, desk_events, desk_revisions, desk_messages, desk_notifications, desk_institutional_links, desk_payments.

24. UC-22 — Usar inteligência artificial com evidência

Actor: Gestor autorizado.

Fluxo principal:

  1. O gestor activa a capacidade em ai_controls.
  2. Regista uma fonte ou documento.
  3. O sistema cria chunks da fonte.
  4. O gestor inicia uma execução de IA.
  5. O sistema grava ai_runs.
  6. O resultado pode ser revisto ou receber feedback.
  7. A aplicação mantém a fonte que suporta a resposta.

Dados: ai_controls, ai_sources, ai_chunks, ai_runs, ai_feedback, documents, users.

25. UC-23 — Sincronizar com sistemas externos

Actor: Sistema externo ou processo de integração.

Fluxo principal:

  1. A aplicação gera um evento em outbox_events.
  2. Um worker publica o evento.
  3. O sistema externo responde ou envia evento para inbox_events.
  4. A aplicação cria sync_runs.
  5. Falhas ou divergências são registadas em reconciliation_issues.
  6. O processo pode ser repetido de forma idempotente.

26. UC-24 — Auditoria e controlo de alterações

Actor: Sistema, gestor ou auditor.

Fluxo principal:

  1. Uma operação protegida é executada.
  2. O sistema identifica actor, entidade, acção e correlação.
  3. Regista evento de auditoria.
  4. Alterações de entidades versionadas geram revisão/snapshot.
  5. O auditor consulta o histórico sem alterar o registo original.

Dados: audit_events, simulation_audit_events, investment_zone_revisions, existing_business_revisions, investment_submission_revisions, desk_revisions, outbox_events.

27. Regras transversais da aplicação

  • Dados privados exigem autenticação e autorização.
  • Divulgação pública depende do estado de publicação e autorização registada.
  • Documentos originais devem ser preservados.
  • Hash, versão e proveniência devem permanecer associados ao documento.
  • Relações jurídicas ou territoriais não validadas ficam pendentes.
  • Rascunho não é submissão aprovada.
  • Importação não é publicação.
  • Publicação de documento não é activação de regra fiscal.
  • Cálculos fiscais devem usar fonte e parâmetro identificados.
  • Histórico e auditoria não devem ser apagados por rollback destrutivo.
  • Operações de migração e testes devem usar base QA isolada.

28. Mapa resumido dos processos

Visitante
  -> consulta catálogo
  -> interesse / apoio / simulação

Investidor
  -> conta
  -> favoritos / dossier
  -> submissão
  -> documentos
  -> mensagens

Gestor
  -> interesse
  -> lead
  -> tarefas
  -> oportunidade CRM
  -> decisão

Gestor territorial
  -> projecto / cluster / corredor
  -> zona
  -> geometria
  -> fonte legal
  -> validação / publicação

Gestor fiscal
  -> regra
  -> revisão
  -> aprovação
  -> publicação
  -> parâmetro usado pelo simulador

Parceiros
  -> parceria
  -> candidatura
  -> sala
  -> mensagens / documentos / marcos