18 KiB
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/envia 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:
- O visitante abre
/. - O sistema apresenta a página inicial e os serviços publicados.
- O visitante escolhe oportunidades, negócios, zonas, simulador, documentos, apoio ou parcerias.
- 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:
- O actor consulta
/oportunidadesou a API de oportunidades. - O sistema filtra por sector, localização, slug, estado e outros critérios.
- O detalhe da oportunidade mostra perfil, território, relações, documentos públicos e informação de investimento.
- 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:
- O actor consulta
/negocios. - O sistema lista negócios cujo estado e autorização permitem divulgação.
- O actor abre o detalhe pelo
slug. - O sistema apresenta apenas título, descrição, modalidade, localização, objectos e documentos autorizados.
- 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:
- O visitante cria uma conta com nome, email e palavra-passe.
- O sistema cria
users. - O utilizador confirma o email quando aplicável.
- O utilizador inicia sessão.
- 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:
- O actor abre o formulário de interesse.
- Informa contacto, oportunidade, modalidade, valor e mensagem.
- O sistema valida os dados, consentimentos e alvo.
- É criado
interest_requests. - O sistema regista recibo/idempotência quando aplicável.
- 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:
- O investidor escolhe um
existing_businesspublicado. - Selecciona a modalidade e, se aplicável, percentagem e intervalo de valor.
- O sistema verifica que o negócio pode receber interesse.
- Cria
interest_requests.existing_business_id. - Regista consentimento para contacto e partilha da informação.
- 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:
- O utilizador abre uma oportunidade.
- Escolhe guardar/iniciar no espaço do investidor.
- O sistema regista a relação em
opportunity_favouritesou inicia uma submissão/dossier. - O utilizador consulta os seus itens em
/investidorou/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:
- O investidor cria uma submissão.
- O sistema cria
investment_submissionscom estadodraft. - O investidor grava o payload e as necessidades específicas.
- Pode adicionar anexos e mensagens.
- O sistema cria eventos e revisões para manter histórico.
- 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:
- O investidor confirma os dados da submissão.
- O sistema verifica campos obrigatórios, alvo e anexos.
- A submissão muda de
draftparasubmitted. - É associado ou criado o pedido de interesse, quando exigido.
- 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:
- O actor cria ou actualiza o negócio.
- Regista modalidade, descrição, objectos, localização e documentos.
- O sistema cria revisões e mantém o snapshot anterior.
- Um gestor pode solicitar informação, rever ou rejeitar.
- O negócio percorre o workflow configurado.
- 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:
- O gestor abre a fila de interesses.
- Consulta o pedido, consentimentos e alvo.
- Atribui o caso a um responsável.
- Converte o interesse em
leads, quando aplicável. - Cria tarefas e actividades.
- Actualiza o estado e regista o resultado.
- Pode associar um
crm_opportunitye 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:
- O gestor cria ou actualiza projectos, clusters e corredores.
- Liga projectos a locais.
- Liga projectos a clusters e corredores.
- Cria cadeias de valor e lacunas de investimento.
- Regista a fonte e o estado da relação.
- 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:
- Regista a fonte legal em
investment_legal_sources. - Cria a zona em
investment_zones. - Associa operador, categoria e localização.
- Adiciona geometria, anexos e relações com projectos, clusters ou corredores.
- Um revisor valida a informação.
- A zona é publicada, suspensa ou revogada.
- 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:
- O gestor carrega o ficheiro.
- O sistema preserva o original e calcula o hash.
- Detecta duplicados e conflitos de versão.
- Regista
documentse, quando necessário,document_versions. - Executa análise antimalware.
- O gestor revê classificação, datas, fonte e autorização.
- O documento é associado ao negócio, candidatura, zona, projecto ou portal.
- 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:
- O actor abre o simulador.
- O sistema cria ou recupera um cookie de recuperação.
- Guarda os dados em
simulation_form_drafts. - O actor pode continuar mais tarde.
- Um utilizador autenticado pode reclamar o rascunho.
- 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:
- O actor submete os dados do simulador.
- O sistema escolhe a versão do questionário.
- Resolve os parâmetros fiscais elegíveis.
- Cria
simulationsesimulation_scenarios. - Executa o cálculo através de job.
- Guarda resultados, obrigações e fontes.
- Gera relatório quando solicitado.
- 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:
- O autor cria uma versão da regra.
- Associa a regra a uma fonte legal.
- O revisor verifica expressão, datas e parâmetros.
- O aprovador decide.
- O publicador disponibiliza a versão.
- 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:
- Mantém catálogo de competências, profissões, instituições e cursos.
- Regista necessidades de formação de projectos.
- Associa ocupações e competências.
- Regista capacidades e oportunidades educativas.
- Analisa lacunas.
- 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:
- O investidor cria um caso de assistência.
- Regista localização, necessidade e documentos.
- O gestor analisa o caso.
- São registadas revisões, eventos e pedidos adicionais.
- 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:
- O actor cria um rascunho de parceria.
- Regista origem, sector, local e objectivo.
- Outro actor manifesta interesse.
- A candidatura é aceite ou recusada.
- É aberta uma sala de parceria.
- Os participantes trocam mensagens e documentos.
- São definidos marcos, pagamentos ou acordo.
- 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:
- O utilizador abre um pedido no balcão.
- O sistema cria um caso e associa o serviço.
- O agente recebe o pedido.
- São trocadas mensagens e solicitados documentos.
- O caso passa por estados e revisões.
- Eventos, notificações e pagamentos são registados.
- 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:
- O gestor activa a capacidade em
ai_controls. - Regista uma fonte ou documento.
- O sistema cria chunks da fonte.
- O gestor inicia uma execução de IA.
- O sistema grava
ai_runs. - O resultado pode ser revisto ou receber feedback.
- 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:
- A aplicação gera um evento em
outbox_events. - Um worker publica o evento.
- O sistema externo responde ou envia evento para
inbox_events. - A aplicação cria
sync_runs. - Falhas ou divergências são registadas em
reconciliation_issues. - O processo pode ser repetido de forma idempotente.
26. UC-24 — Auditoria e controlo de alterações
Actor: Sistema, gestor ou auditor.
Fluxo principal:
- Uma operação protegida é executada.
- O sistema identifica actor, entidade, acção e correlação.
- Regista evento de auditoria.
- Alterações de entidades versionadas geram revisão/snapshot.
- 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