Runbook único de homologação, checklist de evidências e ADR do ambiente
Havia dois runbooks sobrepostos, escritos para o piloto, e nenhum documento do ambiente de homologação. - `20-homologacao-runbook.md` consolida os dois e cobre DNS, TLS, Nginx, Supabase de homologação, banco com a decisão do shim, bucket privado, containers, worker, observabilidade, flag, rollback, diagnóstico e smoke. Os dois runbooks antigos ficam no repositório marcados como histórico, preservando o registro das decisões. - Rollback de imagem com comandos: identificar o que está no ar, listar tags, desligar a flag antes de trocar, subir só web e worker com `--no-deps`, conferir saúde, religar a flag. As migrations de segurança — RLS e auditoria append-only — estão declaradas sem caminho de volta: desfazê-las afrouxa o isolamento entre workspaces, então um rollback que precise disso está errado por definição. - `21-checklist-validacao.md` separa o que foi executado do que depende de infraestrutura, com a evidência de cada item e a tabela dos quatro defeitos encontrados. Nada está marcado PASS por inspeção de código. - ADR 0007 registra o ambiente lógico e a autenticação de homologação, com as alternativas descartadas e o motivo. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
camilafagundesandClaude Opus 5 committed
1 parent
a1ceef6c5f
commit
5b11496cd9
6 files changed
+644
-7
No files matched your search
@@ -1,17 +1,26 @@
|
||||
# Adaptador de Planilhas
|
||||
|
||||
Módulo do Elo Pro para validar planilhas XLSX/CSV, mapear colunas para um modelo e gerar um arquivo novo. Não há login, senha ou tabela de usuários própria.
|
||||
Módulo do Elo Pro para validar planilhas XLSX/CSV, mapear colunas para um modelo e gerar um arquivo novo. Não há login, senha ou tabela de usuários própria: a identidade é a do ecossistema.
|
||||
|
||||
| Ambiente | Host | `ADAPTER_ENV` | Autenticação |
|
||||
| --- | --- | --- | --- |
|
||||
| Desenvolvimento | `localhost:3000` | `development` | sessão local assinada, sem senha |
|
||||
| Homologação | `hml-ada.elopro.app` | `staging` | Supabase Auth do projeto de homologação |
|
||||
| Produção | `ada.elopro.app` | `production` | SSO do Elo Pro |
|
||||
|
||||
`ADAPTER_ENV` é independente de `NODE_ENV`: homologação roda com `NODE_ENV=production` (build otimizado) e política própria. Ver [ADR 0007](docs/decisions/0007-ambiente-logico-e-auth-de-homologacao.md).
|
||||
|
||||
## Desenvolvimento local
|
||||
|
||||
```bash
|
||||
npm install
|
||||
copy .env.example .env.local
|
||||
cp .env.example .env.local
|
||||
```
|
||||
|
||||
No `.env.local`, para o piloto sem o host do Elo Pro:
|
||||
No `.env.local`:
|
||||
|
||||
```
|
||||
ADAPTER_ENV=development
|
||||
ADAPTER_DEV_AUTH=1
|
||||
ADAPTER_DEV_AUTH_SECRET=um-segredo-local
|
||||
ADAPTER_JOB_MODE=inline
|
||||
@@ -21,15 +30,58 @@ ADAPTER_JOB_MODE=inline
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Abra `/login` e escolha uma identidade de desenvolvimento. Isso não pede senha: apenas assume um vínculo que o seed cria em `profiles` e `workspace_members`.
|
||||
Abra `/login` e escolha uma identidade de desenvolvimento. Não há senha: apenas assume um vínculo que o seed cria em `profiles` e `workspace_members`.
|
||||
|
||||
### Com Docker, igual ao artefato de homologação
|
||||
|
||||
Mesma imagem, dois processos, Postgres e Redis de verdade:
|
||||
|
||||
```bash
|
||||
docker compose up --build
|
||||
```
|
||||
|
||||
```bash
|
||||
docker compose exec web node node_modules/tsx/dist/cli.mjs scripts/migrate.ts
|
||||
```
|
||||
|
||||
Portas só em `127.0.0.1`: web `3000`, Postgres `55432`, Redis `56379`.
|
||||
|
||||
## Homologação
|
||||
|
||||
O procedimento completo — DNS, Nginx, Supabase, banco, bucket, containers, worker, observabilidade e rollback — está em **[docs/spreadsheet-adapter/20-homologacao-runbook.md](docs/spreadsheet-adapter/20-homologacao-runbook.md)**. O estado de validação está em [21-checklist-validacao.md](docs/spreadsheet-adapter/21-checklist-validacao.md).
|
||||
|
||||
Resumo:
|
||||
|
||||
```bash
|
||||
cp .env.staging.example .env.staging # preencher; não versionar
|
||||
npm run verify:config # recusa configuração incompleta
|
||||
npm run check:bucket # o bucket precisa existir e ser privado
|
||||
npm run migrate:check # mostra o que vai rodar
|
||||
npm run migrate # aplica (passo com aprovação manual)
|
||||
npm run seed:staging # liga identidades do Supabase a workspaces
|
||||
docker compose -f docker-compose.staging.yml --env-file .env.staging up -d --no-deps web worker
|
||||
ADAPTER_SMOKE_URL=https://hml-ada.elopro.app npm run smoke:staging
|
||||
npm run flag -- <workspace_id> on # último passo, depois do smoke
|
||||
```
|
||||
|
||||
`ADAPTER_APPLY_IDENTITY_SHIM` é obrigatória fora de development: `1` cria o shim local de identidade, `0` usa o schema existente do Elo Pro. Aplicar o shim sobre um schema real é destrutivo em potencial, por isso a escolha nunca é inferida.
|
||||
|
||||
## Produção
|
||||
|
||||
Obrigatórios: `DATABASE_URL`, `NEXT_PUBLIC_SUPABASE_URL`, `NEXT_PUBLIC_SUPABASE_ANON_KEY`, `SUPABASE_SERVICE_ROLE_KEY`, `SUPABASE_STORAGE_BUCKET`, `REDIS_URL`, `SPREADSHEET_TEMP_TTL_SECONDS`, `ELO_PRO_LOGIN_URL`.
|
||||
Além das variáveis de homologação, produção exige `SENTRY_DSN` e `ELO_PRO_LOGIN_URL`, e recusa `ADAPTER_STAGING_AUTH=1`. A feature flag `spreadsheet_adapter` nasce desligada e é ligada por workspace com `npm run flag`, usando a conexão de serviço, nunca pelo browser.
|
||||
|
||||
A feature flag `spreadsheet_adapter` nasce desligada. Habilite por workspace com `npm run flag -- <workspace_id> on` usando a conexão de serviço, nunca pelo browser.
|
||||
O processamento usa `ADAPTER_JOB_MODE=worker` e o processo `npm run worker`. `inline` é recusado fora de development.
|
||||
|
||||
O processamento de produção deve usar `ADAPTER_JOB_MODE=worker` e o processo `npm run worker`. O modo `inline` existe para desenvolvimento.
|
||||
Produção não é liberada sem smoke real e ensaio de rollback registrados no checklist.
|
||||
|
||||
## Saúde
|
||||
|
||||
| Rota | O que responde |
|
||||
| --- | --- |
|
||||
| `GET /api/health/live` | processo vivo, sem tocar dependência |
|
||||
| `GET /api/health/ready` | banco, migrations pendentes, Redis (PING), bucket, configuração e modo de job |
|
||||
|
||||
Configuração inválida encerra o processo com código diferente de zero, em vez de deixar o servidor no ar respondendo erro.
|
||||
|
||||
## Verificação
|
||||
|
||||
@@ -39,3 +91,13 @@ npm run typecheck
|
||||
npm test
|
||||
npm run build
|
||||
```
|
||||
|
||||
Suíte que exige Postgres e Redis reais (roda no CI, e localmente com os dois serviços em pé):
|
||||
|
||||
```bash
|
||||
ADAPTER_TEST_DATABASE_URL=postgres://... ADAPTER_TEST_REDIS_URL=redis://... npm run test:services
|
||||
```
|
||||
|
||||
Sem essas variáveis os casos são **ignorados**, nunca aprovados.
|
||||
|
||||
O CI tem três jobs: `verify` (lint, typecheck, testes, build), `services` (Postgres e Redis reais: as quatro migrations, shim explícito, `FORCE RLS`, isolamento) e `image` (build da imagem Linux, conteúdo, fail-fast dos dois processos, compose completo, jornada assíncrona entre processos e desligamento gracioso do worker).
|
||||
Reference in new issue
Block a user