# Integração do portal com a API

## Ligações públicas

O catálogo abre em `/oportunidades`, as fichas em `/oportunidades/{slug}` e os
sectores em `/sectores/{slug}`. O formulário geral abre em `/manifestar-interesse`;
acrescentar `/{slug}` selecciona uma oportunidade publicada. As rotas podem ser
abertas directamente ou recarregadas. A navegação usa o histórico do Inertia.
O servidor devolve 404 para oportunidades indisponíveis e sectores inactivos.
O teste `PublicPortalNavigationTest` cobre estes contratos (52 verificações).

Verificação no Edge concluída em 25/09/2026: abertura pela ficha, recarregamento,
formulário contextual, Voltar/Avançar, ligação de sector e regresso ao início.
As verificações no browser não gravaram pedidos.

Foi corrigida uma falha no cache persistente: colecções PHP podiam regressar como
objectos incompletos, causando uma página em branco. O cache `portal_home_v2_*`
guarda apenas arrays e valores simples, e é invalidado nas alterações do catálogo.
O teste de regressão verifica a serialização com classes desactivadas, a segunda
leitura e a invalidação. Os testes de navegação/cache e gestão passaram em conjunto
(9 testes, 180 verificações).

A página pública `PortalInvestidor` consulta `/api/v1/home` para os sectores,
estatísticas e destaques. O catálogo usa `/api/v1/opportunities`, com pesquisa,
filtros e paginação no servidor. A ficha consulta a oportunidade pelo slug.

O formulário envia `POST /api/v1/interest-requests`, incluindo `fullName`,
consentimento e a referência da oportunidade seleccionada. A confirmação só
aparece quando a API devolve sucesso e uma referência. Erros de validação são
apresentados junto dos campos; falhas de rede e limites de pedidos preservam os
dados preenchidos. Envios simultâneos são bloqueados durante o processamento.

## Verificação

Executar os 12 testes do cliente HTTP e dos contratos com Node 24:

```powershell
node --test tests/frontend/portal-api.test.mjs
npm run types:check
npm run build
```

Em 24/09/2026, passaram os testes acima e a verificação de lint dos ficheiros
alterados. Foi também verificada a navegação em Edge: início, catálogo, pesquisa
sem distinção de maiúsculas, filtros e ficha consultaram a API local real.
O formulário foi verificado com respostas simuladas 422, 429 e 201, incluindo
retenção de dados, referência devolvida pelo servidor e prevenção de envio
duplicado. Nenhum pedido fictício foi persistido nesses testes de navegador.
O formulário foi inspeccionado num ecrã de 390 px, sem transbordamento horizontal.