# MICRO MÓDULO CORRETIVO 20 — previews reais, regressão completa e fechamento consolidado

## Objetivo deste corretivo

Fechar o ciclo de previews do catálogo de gravações com **materialização real em JPEG**, persistência de metadados coerente com o estado físico do arquivo e revalidação do pacote final consolidado do portal + NVR + gateway.

## Ajustes aplicados

### 1. Gateway: reconciliação real do estado do preview

O gerador de preview agora reconcilia o estado persistido com o estado físico do arquivo antes de servir, regenerar ou sincronizar o segmento.

O fluxo passa a cobrir explicitamente:

- preview marcado como `ready` no metadata, mas ausente no disco → o estado é corrigido para `preview_ready=false` e `preview_status=missing_asset`;
- preview já existente no disco, porém com metadata incompleto ou divergente → largura, altura, bytes, mime e timestamps são reidratados;
- preview recriado após drift → `generated_at` é renovado para o timestamp real da nova materialização.

### 2. Sync de gravações: verdade operacional antes do upload

Antes de montar o lote de `recordings/sync`, o gateway executa uma reconciliação limitada dos segmentos recentes com metadata de preview. Isso evita que o core central continue exibindo `preview_ready=true` quando o JPEG físico já não existe mais.

Novo parâmetro operacional:

- `RECORDING_PREVIEW_RECONCILE_SCAN_LIMIT` — limita a quantidade de segmentos recentes inspecionados por ciclo de sync, preservando estabilidade e sem competir com a gravação local.

### 3. Segurança operacional do pipeline

O corretivo foi mantido sem degradar a captura local:

- a reconciliação roda em janela limitada e apenas sobre segmentos recentes com metadata de preview;
- a materialização continua usando FFmpeg em arquivo derivado separado do `.mp4` local;
- o preview não interfere no worker de gravação contínua nem no worker de movimento;
- o fluxo on-demand continua disponível no detalhe do segmento, sem duplicar mídia no core central.

### 4. Catálogo, timeline e detalhe

A camada central continua consumindo o metadata de preview e exibindo:

- preview inline na listagem administrativa;
- preview inline na timeline horária;
- preview inline no catálogo do cliente;
- painel de preview no detalhe administrativo e no detalhe do cliente.

O módulo 20 reforça esse contrato com uma checagem estática consolidada (`scripts/check-preview-regression.php`) e com regressões adicionais no gateway.

## Arquivos principais tocados

- `gateway/src/Domain/Recording/RecordingPreviewGenerator.php`
- `gateway/src/Domain/Recording/RecordingSyncService.php`
- `gateway/src/Domain/Recording/RecordingSegmentIndex.php`
- `gateway/config/recording.php`
- `gateway/.env.example`
- `gateway/tests/Unit/RecordingPreviewLifecycleRegressionTest.php`
- `scripts/check-preview-regression.php`
- `scripts/test-regression.sh`
- `scripts/test.sh`

## Resultado esperado após o corretivo

- previews reais continuam sendo materializados como JPEG;
- `preview_ready` e `preview_status` passam a refletir o estado físico verdadeiro do asset;
- drift de preview volta para a fila de sync automaticamente;
- recriação do preview renova `generated_at` com o timestamp real da nova geração;
- o pacote final consolidado mantém portal oficial, NVR publicado sob `/nvr`, gateway local e contratos de deploy/documentação.
