# Gestão do portal

## Acesso

A página `/acesso-gestao`, ligada no rodapé do portal, permite configurar a conta
mais tarde. Apresenta entrada/registo, verificação pendente ou acesso à gestão
conforme a sessão. Não cria contas nem revela a lista de emails autorizados.
A verificação de email está activa no modelo User; o envio real depende da
configuração de correio do ambiente. Nenhuma conta é verificada automaticamente.

Configurar `PORTAL_MANAGER_EMAILS` no `.env` com os emails autorizados, separados
por vírgula. As contas devem existir e ter email verificado. A lista vazia bloqueia
o acesso de todos os utilizadores. O registo público não concede privilégios.
Após alterar a configuração, executar `php artisan config:clear` (ou reconstruir
o cache de configuração no ambiente de implantação).

Esta lista limita o acesso à gestão local; não substitui a futura matriz de
papéis e permissões de todos os domínios InvestMoz.

## Páginas

- `/management/history`: histórico protegido de criação/edição de sectores,
  oportunidades e revisão de pedidos. Guarda o responsável e os campos alterados;
  valores de textos livres e contactos não são copiados.

- `/dashboard`: resumo para gestores com pedidos por estado, oportunidades
  publicadas e em rascunho, sectores activos e os cinco pedidos mais recentes.
  As contas sem autorização recebem apenas orientações de configuração, sem
  indicadores internos. Os totais são consultados no carregamento da página.

- `/management/interests`: pesquisa por referência, nome e email; filtro por estado;
  paginação e consulta dos pedidos. A alteração de estado regista o utilizador
  autenticado e a data da última revisão.
- `/management/sectors`: criação e edição de sectores, ordem e activação.
- `/management/opportunities`: criação e edição, maturidade, moeda e valor,
  publicação, destaque e arquivo. Rascunhos e arquivos não aparecem na API pública.
- `/management/crm/leads`: leads, pesquisa, responsável, qualificação humana e tarefas.
  A ficha do pedido permite convertê-lo em lead, com identificação explícita do
  investidor e próxima acção obrigatória. Repetir a conversão abre o mesmo lead.
- `/management/crm/investors`: investidores e respectivos contactos. Um contacto
  partilhado entre investidores tem uma única ficha; a alteração reflecte-se nos vínculos.
- `/management/projects`: cadastro de projectos, orçamento e calendário.
- `/management/clusters`: cadastro de clusters, associação de projectos e etapas
  da cadeia de valor. Estes cadastros são internos; activar não publica nem aprova.
  Na ficha do cluster também é possível ligar etapas, retirar ligações preservando
  o histórico e gerir lacunas de investimento com localização, capacidade,
  justificação, estado e chamada para acção. A localização é descritiva; a chamada
  para acção ainda não constitui um formulário público de candidatura.

O histórico inclui também as alterações efectuadas nestes módulos. A cobertura
actual e as funcionalidades ainda pendentes estão em [upgrade-progress.md](upgrade-progress.md).

As rotas de alteração usam sessões e protecção CSRF do Laravel. O servidor valida
os dados e verifica a autorização em todas as rotas. Os formulários não aceitam
atribuição de privilégios. Não há eliminação definitiva de pedidos ou catálogo.
As alterações do catálogo invalidam o cache da página inicial nos dois idiomas.

O catálogo administrativo permite pesquisar nome/título, slug e referência,
filtrar por estado e, nas oportunidades, por sector. Os filtros ficam no URL,
são preservados na paginação e podem ser limpos. Os indicadores do painel abrem
as listas filtradas correspondentes. A pesquisa não distingue maiúsculas de
minúsculas. Os testes de gestão incluem combinação de filtros, paginação e
rejeição de parâmetros inválidos (7 testes, 120 verificações).

## Pedidos públicos

As novas referências usam `IR-ANO-ULID`, sem depender da contagem de linhas.
As referências antigas continuam válidas. A restrição única da base mantém-se.
Referências de oportunidades inexistentes, retiradas, eliminadas ou com publicação
futura são rejeitadas com 422. Pedidos gerais podem omitir a oportunidade.
Mensagens de excepção com SQL e dados pessoais não são escritas no log deste endpoint.

## Testes

`tests/Feature/PortalManagementTest.php` cobre autorização, edição, publicação,
arquivo, precisão monetária, cache, revisão, validação e persistência real de pedidos.
Usar exclusivamente uma base descartável terminada em `_test`: os testes usam
`RefreshDatabase`. Nunca apontar os testes para a base `investemoz`.
O teste de envio conserva a validação DNS do email e requer resolução DNS; não envia email.

Após a implementação do painel, passaram 49 testes PHP (290 verificações),
incluindo contagens reais, ausência de dados, limite e ordem dos pedidos recentes
e protecção dos indicadores contra acesso por contas sem autorização.

Validação em 25/09/2026: 45 testes PHP (205 verificações) e 12 testes JavaScript
passaram. TypeScript, lint e build passaram. No Edge foram verificados login,
criação de sector, publicação e arquivo com consulta da API real, revisão de pedido
e persistência após recarregar. Os testes de escrita usaram PostgreSQL isolado na
porta 55440; os dados da aplicação não foram alterados.

```powershell
# Configurar DB_HOST, DB_PORT, DB_USERNAME e DB_PASSWORD da instância isolada.
$env:DB_DATABASE = 'investmoz_test'
php vendor/bin/phpunit --filter PortalManagementTest --do-not-cache-result
```