# Editor visual de regiões PDF

## Âmbito da versão 0.2.0

O módulo **Formulários PDF** permite criar modelos a partir de um PDF privado e definir campos visualmente sobre qualquer página. Esta versão cobre a autoria e a gestão integral do esquema do modelo. A geração de PDFs preenchidos pertence ao passo seguinte do roadmap.

## Funcionalidades

- upload e substituição segura do PDF original;
- análise automática do número e dimensões das páginas;
- renderização multipágina com PDF.js;
- criação por arrasto e redimensionamento com oito controlos;
- movimento por rato, toque, teclado e grelha configurável;
- zoom, ajuste à largura, navegação e pré-visualização sem contornos;
- campos de texto, texto longo, data, checkbox, seleção, imagem, assinatura, rubrica e texto fixo;
- propriedades de tipografia, alinhamento, cores, fundo, contorno, rotação e altura de linha;
- mapeamento para dados genéricos, organização, dossiê e módulo Educação;
- envio de imagens privadas para regiões fixas;
- atalhos de teclado, copiar/colar, duplicar, desfazer e refazer;
- gravação automática e manual;
- bloqueio otimista para impedir a sobreposição silenciosa de edições concorrentes;
- publicação, arquivo, duplicação, histórico de versões e restauro;
- importação e exportação do esquema em JSON;
- isolamento por organização, armazenamento privado e registo de auditoria.

## Instalação

Depois de atualizar o código:

```bash
composer install
php artisan migrate --force
php artisan db:seed --force
php artisan optimize:clear
```

O módulo `pdf_forms` tem de estar incluído no plano do cliente ou atribuído como add-on à organização.

## PDF.js local

O editor tenta primeiro carregar uma cópia local e usa o CDN fixado como fallback. Para uma instalação sem dependências externas no browser:

```bash
./scripts/vendor-pdfjs.sh
```

O comando instala a versão fixada em `public/vendor/pdfjs`. Estes ficheiros não são necessários para executar migrations ou comandos de backend.

## Modelo de coordenadas

As coordenadas são guardadas de forma normalizada entre `0` e `1`:

- `x` e `y`: posição relativa ao canto superior esquerdo;
- `width` e `height`: proporção da largura e altura da página;
- `page_number`: página do PDF, começando em 1.

Este modelo mantém as regiões alinhadas em diferentes resoluções e permite que o motor de geração posterior converta as coordenadas para pontos PDF.

## Segurança e concorrência

- PDFs e imagens são servidos por controladores autenticados e nunca por URL pública direta do storage.
- O início real do ficheiro é validado como `%PDF-`, para além da validação do upload.
- Imagens são limitadas a PNG, JPEG e WebP.
- Cada gravação exige o `lock_version` atual. Uma segunda sessão com uma versão antiga recebe HTTP 409.
- O modelo só pode ser publicado depois de o PDF ter sido analisado e existir pelo menos uma região.
- Acesso: superadministrador ou membro da organização com função `owner`, `admin` ou `editor` e licença ativa do módulo.

## Esquema JSON

A exportação contém:

```json
{
  "schema_version": 1,
  "template": {
    "name": "Ficha de inscrição",
    "page_count": 3,
    "page_dimensions": []
  },
  "regions": []
}
```

Na importação, as chaves são validadas, as coordenadas têm de permanecer dentro da página e as regiões recebem novos UUIDs. Imagens não são incorporadas no JSON; devem existir no modelo de destino.

## Limites atuais

- máximo de 2 000 páginas analisadas pela validação do backend;
- máximo de 1 000 regiões por modelo;
- máximo de 100 opções por campo de seleção;
- máximo de 50 revisões automáticas/manuais por modelo;
- o processamento de PDFs muito extensos deve futuramente ser transferido para um worker dedicado.

As localizações também podem ser alteradas no `.env`:

```dotenv
PDFJS_VERSION=6.2.108
PDFJS_LOCAL_BASE=/vendor/pdfjs/
PDFJS_CDN_BASE=https://cdn.jsdelivr.net/npm/pdfjs-dist@6.2.108/
```