# Release readiness — evidências verificadas

Auditoria executada em 2026-09-14 para transformar o checklist final do `ROADMAP.md` em gates baseados em evidência, sem marcar como concluído o que depende de infraestrutura ou operação externa.

## Escopo desta entrega

Esta entrega fecha somente gates que podem ser comprovados pelo estado atual de `main` e por regressões reproduzíveis. Ela não declara CI verde, não declara rotação VAPID concluída e não declara existência de backup/rollback externo sem evidência operacional.

## Gates concluídos

### 1. All P0 items merged

O único bloco P0 atualmente definido no roadmap é **Automatic NF-e XML → Purchase Order matching**. Todos os nove itens do escopo estão marcados como concluídos e fazem parte de `main`.

A conclusão deste gate não depende de uma nova feature: ele apenas reconcilia o checklist de release com o estado já mergeado.

### 2. No destructive migration required for deployment

A estratégia atual de deploy não exige `DROP`, remoção de coluna ou exclusão destrutiva de dados.

A revisão de tabelas legadas definiu explicitamente que:

- `payable_attachments` continua preservada até reconciliação, soak, backup e release destrutivo separado;
- a compatibilidade de Helpdesk permanece ativa;
- nenhum backfill destrutivo é disparado automaticamente;
- qualquer remoção física futura deve ocorrer em release isolado, depois das gates documentadas em `docs/architecture/legacy-table-removal-plan.md`.

Os `dropColumn`/`dropIfExists` existentes em migrations históricas aparecem majoritariamente em métodos `down()` de rollback e não constituem requisito do caminho normal de `php artisan migrate` desta release.

### 3. No high-risk N+1 issue in main operational dashboards

O P2 de performance foi encerrado depois de auditoria dos read paths de Service Orders, Purchasing, Chat, Projects, Helpdesk, Tenant administration, Technical Assistance, Finance, Sales, Prospecting e WMS.

Foram entregues, entre outras medidas:

- paginação bounded para históricos e listas operacionais crescentes;
- agregações SQL para evitar consultas por linha;
- eager loading/`withCount` onde necessário;
- índices alinhados aos filtros reais;
- read models compactos para Purchasing e Service Orders;
- query-budget regression para Service Orders;
- harness de carga para Stock Map, Supplier Performance, Purchasing Financial Consolidation e Service Orders.

O roadmap já registra explicitamente que não restou N+1 de alto risco nos principais dashboards operacionais.

### 4. Permission migrations cover existing production installations

A auditoria de paridade compara mecanicamente as permissões literais exigidas por `authorizePermissions([...])` nos controllers com o catálogo do `RoleAndPermissionSeeder`.

A migration `2026_09_14_151100_sync_current_permissions_for_existing_installations.php` adiciona um catch-up idempotente para a release atual:

- todas as permissões do catálogo são garantidas via `Permission::findOrCreate()`;
- `Super-Admin` recebe o catálogo completo quando o papel existe;
- `Admin` recebe somente permissões não `tenants.*`, preservando a fronteira landlord;
- grants customizados não são removidos;
- o rollback não exclui permissões nem vínculos;
- o snapshot da migration é comparado automaticamente com o catálogo do seeder.

A política para permissões futuras permanece inalterada: novas permissões devem continuar recebendo migration própria para instalações existentes. Evidência detalhada em `docs/security/permission-production-parity.md`.

### 5. Swagger/OpenAPI reflects all current external/internal contracts

A auditoria de paridade passa a comparar a tabela de rotas efetivamente registrada pelo Laravel com o documento produzido por `php artisan l5-swagger:generate`.

`SwaggerRouteParityTest` cobre método, path e segurança de transporte para todas as rotas `api/*` relevantes. A regressão:

- exige uma operação OpenAPI para cada `GET`, `POST`, `PUT`, `PATCH` e `DELETE` real;
- resolve `PathItem.$ref` usado pelos aliases de compatibilidade;
- deriva segurança do middleware efetivo (`auth:api`, `auth:client`, `signed`);
- trata múltiplas rotas com o mesmo método/path como alternativas válidas de segurança;
- exige os schemes `bearerAuth`, `clientBearerAuth` e `signedUrl`.

A auditoria também tornou explícitos aliases antes mencionados apenas em texto e documentou corretamente downloads por URL temporária assinada. Evidência detalhada em `docs/release/swagger-route-parity.md`.

### 6. Critical money/stock flows have transaction + concurrency tests

A matriz final está documentada em `docs/release/critical-money-stock-concurrency.md` e cobre Accounts Payable, Accounts Receivable, crédito do cliente, gateway, WMS, reservas de OS e recebimento de Pedido de Compra/NF.

Além das proteções já existentes, a auditoria corrigiu três gaps concretos:

- cancelamento de conta a pagar passa a recarregar e bloquear o título dentro da transação, impedindo que estado obsoleto sobrescreva pagamento parcial/quitado;
- retry do mesmo `gateway_id` passa a ser idempotente sob `lockForUpdate()` do recebível, inclusive quando o primeiro evento gerou apenas pagamento parcial;
- movimentações do mesmo produto são serializadas e o custo médio ponderado deixa de contar a quantidade da entrada corrente duas vezes quando ela já está refletida no saldo físico.

As regressões novas (`PayableConcurrencyIntegrityTest`, `GatewaySettlementIdempotencyTest` e `ProductCostConcurrencyIntegrityTest`) complementam as suítes existentes de crédito, estoque reservado, rollback de auditoria, lifecycle de OS, recebimento parcial de Pedido de Compra e duplicidade de NF.

## Gates que permanecem abertos

### Secrets/configuration review for production

A parte de código remove o material VAPID versionado, bloqueia reutilização do par comprometido por fingerprint e valida as invariantes com `config:audit-production`.

A entrega de Release Verification 03 acrescenta evidência estruturada com:

`php artisan config:audit-production --json --evidence`

O artifact é persistido em storage privado e contém somente IDs/status/mensagens dos controles, environment, timestamp e SHA de release — nunca valores de APP_KEY, JWT_SECRET, VAPID ou credenciais de integração.

O gate continua aberto até existir execução `passed` no runtime real de produção e preservação externa do artifact no change/release record.

### PHPUnit CI enabled and green

O workflow atual é `API Quality`. A análise histórica confirma que o problema antecede qualquer seleção dinâmica de runner: desde o primeiro run observado, os jobs encerram antes do primeiro step (`steps=null`, sem checkout, PHP, Composer ou PHPUnit).

A entrega de Release Verification 03 torna o diagnóstico determinístico:

- PR/push usam explicitamente `ubuntu-latest`;
- nenhuma `vars.CI_RUNNER` pode redirecionar silenciosamente o quality gate automático;
- runner alternativo só pode ser informado em `workflow_dispatch`;
- há teste de contrato versionado para essa regra.

Isso elimina ambiguidade de configuração do workflow, mas **não** transforma indisponibilidade de runner em CI verde.

Evidência desta entrega:

- após corrigir o parsing YAML, o GitHub voltou a reconhecer o workflow pelo nome `API Quality`;
- PR #48 / run #111 usou o contrato automático com `ubuntu-latest`;
- o job `quality` ainda encerrou com `steps=null`, sem checkout e sem logs;
- portanto parsing do workflow e `CI_RUNNER` foram eliminados como causa desse run.

O gate só fecha quando um runner real executar PHPUnit com sucesso.

### Production backup/rollback procedure documented outside application code

Este é deliberadamente um gate operacional. Não pode ser fechado a partir do repositório da aplicação sem evidência de runbook/backup externo válido.

## Regra de contabilização

Somente checkboxes mergeados em `main` contam como evolução real. Esta branch representa um gate adicional sobre o `main` atual e não deve ser somada ao percentual real enquanto a PR permanecer aberta.


## Evidência adicional — Fluxo PDV corporativo

A etapa API-12.3 introduz um gate funcional independente para o PDV:

`.github/workflows/pdv-release.yml`

Ele executa MySQL 8 e, sem depender do step sequencial de `composer audit`
do workflow genérico, valida:

- cadeia completa de migrations + seed;
- geração L5 Swagger;
- auditoria estrutural de isolamento tenant;
- paridade global rota × OpenAPI;
- contratos OpenAPI específicos do PDV;
- suítes de PosSale, caixa, pagamentos e offline sync;
- devices e balanças;
- comandas e realtime;
- fiscal/outbox/reconciliação;
- reservas/Stock Map/movimentações críticas do WMS;
- matriz de segurança cross-tenant;
- fila/backlog/retry;
- contrato do perfil de carga k6.

O comando local/CI equivalente é:

`composer verify:pdv-release`

O `API Quality` permanece responsável pelo dependency audit e pela regressão
global. O novo gate não ignora nem transforma advisories em warning; ele evita
somente que uma falha de segurança independente impeça a obtenção de evidência
funcional específica do PDV.

A ordem operacional de deploy e rollback está documentada em
`docs/release/pdv-api-app-deploy-rollback.md`, com API primeiro, App depois,
compatibilidade expand/contract e rollback de schema nunca automático.