Investidor-V2/docs/investmoz/document-library-implementation-2026-10-05.md

# Biblioteca de Documentos e Formulários — entrega e validação

Data: 05/10/2026

## Estado

Implementação funcional no código; validação automatizada concluída numa base PostgreSQL isolada. A migração da biblioteca **não foi aplicada à base activa**. O catálogo público activo estava vazio na verificação de leitura. Não foram importados nem publicados documentos demonstrativos. A validação visual desktop foi satisfatória para o estado vazio; a captura móvel a 390 px apresenta corte horizontal e requer correcção/ensaio adicional antes de validar a apresentação móvel.

## Implementado

- Catálogo único em `/documentos`, aproveitando `portal_resources` e `documents`, com ligações estruturadas a módulos, actividades, fases e territórios.
- Pesquisa textual, filtros de metadados e território, paginação e inclusão de documentos nacionais. As relações são consultadas com `EXISTS` para evitar duplicações.
- Carregamento privado e quarentena por defeito, limite de 10 MiB, validação MIME, autoria/data, hash SHA-256, detecção de conteúdo duplicado e prevenção de publicação implícita.
- Edição versionada com controlo optimista, histórico de revisões e indicação de metadados/fontes em falta.
- Publicação separada do carregamento. Exige fonte identificada e direitos explicitamente autorizados; legislação exige também confirmação de fonte oficial. Propostas e situação jurídica por confirmar mantêm rótulos próprios.
- Recomendações documentais contextuais no dossier do simulador, sem bloquear o percurso quando não há documentos aplicáveis.
- Atalho para a biblioteca na página inicial.

## Ficheiros alterados/criados

- `database/migrations/2026_10_05_120000_extend_portal_document_catalogue.php`
- `app/Http/Controllers/PortalServicesController.php`
- `routes/api.php`, `routes/web.php`
- `resources/js/pages/PortalInvestidor.tsx`
- `resources/js/pages/portal/services.tsx`
- `resources/js/pages/portal/manage.tsx`
- `resources/js/components/simulation-form.tsx`
- `tests/Feature/PortalServicesTest.php`
- `docs/investmoz/document-library-inventory-2026-10-05.md`
- `docs/investmoz/document-library-implementation-2026-10-05.md`

## Evidências e comandos

Executados no projecto, usando PHP 8.5.11 e PostgreSQL QA em `127.0.0.1:55441`, base `investmoz_test`. O router web de QA fixa estes valores e interrompe a execução se a configuração divergir; não tem fallback para a base activa.

- `php artisan test --filter=PortalServicesTest` — 8 testes, 277 assertions, aprovados.
- `php artisan test` — 281 testes, 2.987 assertions, aprovados.
- `node --test tests/frontend/*.test.mjs` — 144 testes aprovados.
- `npm.cmd run types:check` — aprovado.
- `npm.cmd run build` — aprovado; avisos existentes de chunk acima de 500 kB e dependência opcional de fontes `fontaine` ausente.
- Lint PHP nos ficheiros PHP alterados — aprovado.
- `vp fmt --check` nos quatro TSX alterados — aprovado.
- Verificação direccionada `vp check --no-fmt` — zero erros e três avisos preexistentes em `simulation-form.tsx` sobre coerção de tipos de template, fora das alterações desta biblioteca. `npm.cmd run check` global reportou 202 problemas de formatação pelo repositório; não foi aplicado um format global.
- Consulta apenas de leitura à base activa — zero linhas que satisfaçam publicação, estado activo e classificação pública em `portal_resources`.
- Browser Edge headless, contra `http://127.0.0.1:18089/documentos`, com cabeçalho QA `investmoz_test:55441`: HTTP 200. Inspecção visual desktop confirma título, filtros, estado vazio e contagem 0. Capturas temporárias em `%TEMP%\investmoz-document-library-qa\documentos-desktop.png` e `documentos-mobile.png`. A captura móvel de 390 px corta conteúdo à direita; não foi aprovada visualmente.

Os testes PHP incluem fixtures para filtros positivos e negativos, hierarquia territorial, inclusão nacional, publicação explícita, permissões, revisão de metadados, duplicados, ausência de fundamento legal em requisitos obrigatórios e recomendações. Esses resultados são evidência em ambiente isolado; não representam documentos reais publicados.

## Inventário e dados

O inventário encontra-se em `document-library-inventory-2026-10-05.md`. Três PDFs no arquivo interno foram identificados por nome, tamanho e hash, mas o seu conteúdo, proveniência e direitos não foram validados para publicação; não foram importados. A base activa permanece sem alterações de esquema ou conteúdo nesta entrega.

## Pendências

1. Corrigir e revalidar o corte horizontal na apresentação de 390 px.
2. Rever documentalmente fonte, vigência e direitos dos documentos candidatos; depois, um gestor pode carregá-los em privado, completar metadados e publicá-los explicitamente.
3. Aplicar a migração aditiva à base activa apenas no procedimento operacional próprio, com backup e janela definidos. A migração não foi necessária para os testes QA e não foi aplicada à base activa.
4. A evidência browser com registos documentais reais publicados depende de candidatos autorizados e aprovados. Não usar dados demonstrativos públicos para simular esse resultado.

## Rollback

Antes de aplicar a migração em qualquer ambiente, fazer backup recuperável. O `down()` recusa remover estruturas se já houver ligações/revisões/metadados novos; portanto, após começar a usar o catálogo, a reversão segura é desactivar rotas/fluxo por deploy e preservar tabelas e dados até planeamento explícito de migração inversa. Os ficheiros carregados permanecem no armazenamento privado e não são apagados pela reversão do código.

## Validation update — 5 October 2026

- Corrected horizontal overflow at 390 px. Edge headless returned HTTP 200 at 1440 px and 390 px; document width equalled viewport width at both sizes, keyboard focus began at “Saltar para o conteúdo”, the empty state was coherent, and there were no JavaScript errors. Screenshots: `document-library-desktop-2026-10-05.png` and `document-library-mobile-2026-10-05.png`; measurements: `document-library-browser-2026-10-05.json`.
- The focused suite after antimalware integration passed: 20 tests, 437 assertions. Real ClamD and file limits were exercised; `queue:work --once` ran against the isolated database.
- Positive EICAR detection, socket timeouts, and encrypted documents remain pending; none is reported as approved. See `malware-scanning-2026-10-05.md`.
- Browser screenshots show the empty state because the active database has no approved public documents. Positive search fixtures are isolated tests, not real records or proof of authorised publication.

Final regression after the antimalware integration: `php artisan test` — 285 tests / 3,017 assertions passed; frontend — 144 passed; TypeScript, production build, PHP syntax checks, and the edited TSX formatter check passed. Scanner positive-pattern validation and remote-host setup are still open (see the separate antimalware report).

On Windows/Laragon, user-level Scheduled Tasks now start the loopback scanner on sign-in and refresh official signatures at sign-in/every two hours. This local operation does not configure the remote hosting target.