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

527 lines
18 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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
```text
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
```text
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
```