adaptador-planilhas/docs/spreadsheet-adapter/07-deployment-runbook.md

Deploy e operação

Ordem

1. Conferir envs sem colar segredo no repositório.
2. npm run migrate na DATABASE_URL do ambiente.
3. Subir a aplicação com a flag ainda desligada.
4. Subir npm run worker e o Redis do ambiente.
5. Confirmar bucket privado. Não criar bucket público.
6. Smoke test no workspace piloto e só então npm run flag -- <workspace_id> on.

Variáveis

Nome	Uso
NEXT_PUBLIC_SUPABASE_URL	Auth no browser/servidor
NEXT_PUBLIC_SUPABASE_ANON_KEY	Chave pública do Auth
SUPABASE_SERVICE_ROLE_KEY	Storage no servidor. Nunca NEXT_PUBLIC_
SUPABASE_STORAGE_BUCKET	Bucket privado
DATABASE_URL	PostgreSQL. Obrigatório em produção
REDIS_URL	Lock. Sem ela o processamento recusa iniciar
SENTRY_DSN / NEXT_PUBLIC_SENTRY_DSN	Observabilidade
SENTRY_ENVIRONMENT / SENTRY_RELEASE	Ambiente e release
ELO_PRO_LOGIN_URL	Login central
SPREADSHEET_TEMP_TTL_SECONDS	Retenção. Obrigatório em produção; valor de produto ainda aberto
ADAPTER_JOB_MODE	worker em produção, inline em desenvolvimento
ADAPTER_DEV_AUTH	Só fora de produção
ADAPTER_DEV_AUTH_SECRET	Assina o cookie local. Não é senha de usuário

O cookie de workspace lido pela aplicação chama-se elo_pro_workspace_id.

Rollback

• Aplicação: voltar o deploy anterior.
• Flag: npm run flag -- <workspace_id> off.
• Schema: migrations/down/0002_spreadsheet_adapter_down.sql remove só tabelas do módulo.
• Jobs: parar o worker. Jobs queued não avançam. Jobs processing sem lock viram INTERRUPTED na próxima varredura.

Smoke

Login Elo Pro sem segunda senha; workspace piloto com flag ligada; upload de modelo; fonte; aba ou cabeçalho se preciso; mapeamento; prévia; download XLSX, CSV e PDF; workspace sem flag recebe bloqueio; download sem sessão recebe 401.

Runbook

• Job travado em processing: confirmar se o lock Redis ainda existe. Se expirou, o worker marca INTERRUPTED. O usuário pode tentar de novo.
• Redis indisponível: APIs de leitura seguem; processamento responde REDIS_UNAVAILABLE e não grava saída.
• Storage indisponível: upload falha com STORAGE_FAILURE ou 503 e não deixa modelo sem arquivo.
• Migration parcial: schema_migrations só registra arquivo aplicado por completo. Reexecutar npm run migrate continua do próximo arquivo. Não editar migration já aplicada.
• Limpeza: npm run cleanup apaga blobs em chaves /tmp/ expiradas e não mexe em /models/.