# Módulo Final 28 — contrato canônico da integração central

## Objetivo

Eliminar ambiguidade entre variáveis antigas e novas na integração central do NVR com o portal principal, preservando compatibilidade transitória apenas onde estritamente necessário.

## Convenção oficial consolidada

### Integração central / launch / SSO

Família canônica:

- `CENTRAL_APP_URL`
- `CENTRAL_API_URL`
- `CENTRAL_SHARED_SECRET`
- `CENTRAL_PRODUCT_CODE`
- `CENTRAL_TIMEOUT`
- `CENTRAL_SSO_ENABLED`
- `CENTRAL_INTROSPECTION_ENABLED`
- `CENTRAL_SSO_ISSUER`
- `CENTRAL_SSO_AUDIENCE`
- `CENTRAL_SSO_TTL_SECONDS`
- `CENTRAL_SSO_CLOCK_SKEW_SECONDS`
- `CENTRAL_SSO_AUTO_PROVISION_TENANT`
- `CENTRAL_SSO_AUTO_PROVISION_SITE`
- `CENTRAL_SSO_SYNC_PLATFORM_ADMIN`

Precedência documentada:

1. `CENTRAL_*` e `CENTRAL_SSO_*`
2. aliases deprecated `SSO_CENTRAL_*`
3. derivados explícitos documentados (`CENTRAL_API_URL` pode derivar de `CENTRAL_APP_URL + /api` quando omitida)

### Banco central

Família canônica:

- `DB_CONNECTION`
- `DB_HOST`
- `DB_PORT`
- `DB_DATABASE`
- `DB_USERNAME`
- `DB_PASSWORD`
- `DB_CHARSET`
- `DB_COLLATION`
- `DB_CONNECT_TIMEOUT`
- `DB_SESSION_TIMEZONE`

Precedência documentada:

1. `DB_*`
2. aliases deprecated `DB_CENTRAL_*`

## Aliases deprecated mantidos nesta rodada

- `SSO_CENTRAL_ENTRYPOINT_URL` → `CENTRAL_APP_URL`
- `SSO_CENTRAL_SHARED_SECRET` → `CENTRAL_SHARED_SECRET`
- `SSO_CENTRAL_ENABLED` → `CENTRAL_SSO_ENABLED`
- `SSO_CENTRAL_ISSUER` → `CENTRAL_SSO_ISSUER`
- `SSO_CENTRAL_AUDIENCE` → `CENTRAL_SSO_AUDIENCE`
- `SSO_CENTRAL_TTL_SECONDS` → `CENTRAL_SSO_TTL_SECONDS`
- `SSO_CENTRAL_CLOCK_SKEW_SECONDS` → `CENTRAL_SSO_CLOCK_SKEW_SECONDS`
- `SSO_CENTRAL_AUTO_PROVISION_TENANT` → `CENTRAL_SSO_AUTO_PROVISION_TENANT`
- `SSO_CENTRAL_AUTO_PROVISION_SITE` → `CENTRAL_SSO_AUTO_PROVISION_SITE`
- `SSO_CENTRAL_SYNC_PLATFORM_ADMIN` → `CENTRAL_SSO_SYNC_PLATFORM_ADMIN`
- `DB_CENTRAL_*` → `DB_*`

## O que foi removido do caminho principal

- fallback cruzado de `APP_URL` como se fosse origem canônica da central;
- fallback cruzado de `ERP_*` como se fosse contrato central do NVR;
- uso cru de aliases `SSO_CENTRAL_*` como fonte principal indefinida.

## Resultado esperado

- `.env.example`, docs, config e checks passam a apontar para uma única convenção oficial;
- aliases antigos continuam aceitos apenas como compatibilidade transitória explicitamente marcada;
- a resolução do runtime deixa claro qual variável é principal e qual é apenas legado.
