527 lines
18 KiB
Markdown
527 lines
18 KiB
Markdown
# 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
|
||
|
||
```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
|
||
```
|