# MICRO MÓDULO CORRETIVO 17 — Higiene de pacote, build final e estrutura de entrega

## Escopo fechado
Esta rodada corrigiu a camada final de build e empacotamento do pacote consolidado, sem alterar a arquitetura obrigatória da base:

- **portal** continua sendo a entrada oficial do produto;
- **NVR** continua integrado sob **`/nvr`**;
- **MariaDB/MySQL** permanece como contrato central;
- o empacotamento final agora gera um **único zip limpo, previsível e reexecutável**.

## Problemas estruturais atacados
O build anterior ainda zipava a árvore quase inteira e dependia apenas de exclusões pontuais. Com isso, vazavam para o pacote final:

- relatórios e manifests residuais de módulos antigos na raiz;
- `_diffs` e artefatos incrementais que não pertencem ao pacote operacional;
- sessões, logs, rate-limits e outros arquivos transitórios em `storage/`;
- placeholders como `.gitkeep` e sujeira típica de empacotamento;
- path anômalo com aspas em `gateway/"` gerado por runtime transitório anterior;
- ausência de um manifesto de build ordenado e verificável.

## Correções aplicadas
### `scripts/package.sh`
O empacotamento foi refeito para operar em **stage temporário limpo**, com estes comportamentos:

- sincroniza o portal real antes do stage;
- copia a árvore do pacote com exclusão explícita de runtime transitório;
- remove resíduos antigos da raiz e do `platform`;
- remove `_diffs`, `.gitkeep`, caches, sessões, logs, locks, temporários e gravações transitórias;
- recria apenas os diretórios operacionais vazios que devem existir no pacote final;
- gera `BUILD_MANIFEST.sha256` com a árvore final ordenada;
- produz zip com ordem determinística de diretórios e arquivos.

### `scripts/sync-real-portal.sh`
A sincronização do portal real foi endurecida para não importar sujeira operacional ou de IDE/build:

- exclusão de `.env`, `.git`, `.idea`, `.vscode`, `node_modules`, `__MACOSX`, `.DS_Store`, `Thumbs.db`;
- exclusão de `_diffs` e runtime transitório em `storage/`;
- limpeza final de logs, sessões e rate-limits após a cópia.

### `scripts/check-real-portal-package.php`
O validador do portal real passou a aceitar **path explícito**, permitindo validar também o stage final antes do zip.

### `scripts/check-package-hygiene.php`
Foi criado um validador específico desta rodada para garantir:

- presença da estrutura operacional mínima esperada;
- ausência de placeholders e resíduos de módulos antigos;
- ausência de logs, sessões, caches, temporários e gravações transitórias no pacote final;
- ausência de `.gitkeep`, `.DS_Store`, `Thumbs.db`, backups e diretórios de desenvolvimento;
- presença do `BUILD_MANIFEST.sha256`.

### `README.md`
A documentação principal foi atualizada para explicitar o novo fluxo de build limpo e o manifesto determinístico.

## Validações executadas
### Lint / sintaxe
Executado com sucesso:

- `bash -n scripts/package.sh scripts/build-final.sh scripts/sync-real-portal.sh`
- `php -l scripts/check-real-portal-package.php`
- `php -l scripts/check-package-hygiene.php`

Resultado: **ok**.

### Validação estrutural do portal real
Comando executado:

- `php scripts/check-real-portal-package.php`

Resultado: **ok**.

### Geração de pacote limpo em stage
Comando executado:

- `bash scripts/package.sh /mnt/data/module17_work/test_mod17.zip`

Resultado:

- `portal-real-package-check: ok`
- `package-hygiene-check: ok`

### Inspeção do zip gerado
Foi validado que o zip de teste **não contém**:

- `VALIDACAO_MODULO_13*`, `VALIDACAO_MODULO_14*`, `VALIDACAO_MODULO_15*`, `VALIDACAO_MODULO_16*` na raiz;
- `LISTA_ARQUIVOS_MODULO_15.txt`;
- `_diffs`;
- manifests incrementais dos módulos 11/12;
- `.gitkeep`, sessões, `app.log`, `mail.log` e JSON transitório de rate-limit.

Também foi validado que o zip **contém**:

- `PACOTE FINAL/BUILD_MANIFEST.sha256`;
- `PACOTE FINAL/portal/public/index.php`;
- `PACOTE FINAL/portal/public/nvr/_bridge.php`;
- `PACOTE FINAL/docker-compose.yml`.

### Suíte do portal
Comando executado:

- `cd portal && php tests/run.php`

Resultado final:

- **125 testes passando**
- **0 falhas**

### Suíte do gateway
Comando executado:

- `cd gateway && php tests/run.php`

Resultado final:

- **40 testes passando**
- **0 falhas**

## Observação objetiva
Esta rodada validou o eixo de **empacotamento, build, limpeza estrutural e previsibilidade do pacote final**. `docker compose up` não foi executado neste contêiner porque o ambiente não disponibiliza Docker.
