Pular para conteúdo

Checklist de migração limpa

Use este checklist somente depois de revisar a arquitetura de schema e migrações e backup/restore.

--dry-run é seguro e read-only. --apply altera o banco local e exige decisão humana. Não execute com chaves em arquivos do diretório de dados.

1. Pré-condições

  • Confirmar que nenhuma chave exposta será usada em teste ou migração.
  • Revogar qualquer chave que tenha aparecido em prompt, screenshot ou log.
  • Confirmar branch, commit e status do repositório.
  • Encerrar API, frontend, Local Companion e outros processos que possam gravar em data/.
  • Confirmar espaço livre para pelo menos duas cópias do diretório de dados.
  • Identificar o diretório correto (data/ ou SOTUHIRE_DATA_DIR).
  • Não apagar nem mover JSON/JSONL antes da verificação final.
git status
git rev-parse HEAD
python -c "from modules.storage.database import default_data_dir; print(default_data_dir())"

2. Scan de segredos

  • Verificar arquivos rastreados.
  • Verificar manualmente arquivos locais não rastreados que estejam dentro do diretório de dados.
  • Remover o segredo da origem e rotacioná-lo antes de continuar.
git grep -n -I -E "(AIza[0-9A-Za-z_-]{20,}|sk-[A-Za-z0-9_-]{20,}|sk-proj-[A-Za-z0-9_-]{20,})" .

O criador de backup exclui arquivos textuais com aparência de segredo, mas isso é defesa adicional, não autorização para manter credenciais no diretório.

3. Health check inicial

  • Executar health check read-only.
  • Guardar contagens e issues.
  • Tratar error antes da migração.
  • Revisar warnings; healthy=true não significa ausência de warnings.
python scripts/check_data_health.py

Se o banco ainda não existir, database_missing é informativo.

4. Dry-run da migração

  • Executar sem --apply.
  • Confirmar que data/sotuhire.db não foi criado pelo dry-run.
  • Confirmar que data/backups/ não foi criado pelo dry-run.
  • Comparar found por tabela com os stores conhecidos.
  • Revisar duplicates, rejected e cada warning.
  • Confirmar original_files_preserved=true.
python scripts/migrate_local_data.py --dry-run

O exit code é diferente de zero quando há rejeições. Isso não deve ser contornado sem examinar arquivo e linha informados.

Perguntas antes de autorizar

  • IDs confirmados permanecem os mesmos?
  • Duplicatas usam URL/referência forte ou conteúdo exato?
  • merged_legacy_ids, source_refs e legacy_source_paths serão preservados?
  • Candidaturas sem anúncio foram reportadas sem snapshot inventado?
  • Capturas com texto produzirão snapshot?
  • Há JSON/JSONL corrompido que precisa ser corrigido ou aceito como rejeição explícita?

5. Backup explícito

  • Criar backup antes da migração, mesmo que --apply também crie um.
  • Confirmar que o ZIP existe.
  • Inspecionar manifest.json.
  • Confirmar schema_version real do banco, max_supported_schema_version, lista de arquivos e excluded_files.
  • Confirmar que não há chave, token, cookie ou storage da extensão.
python scripts/backup_data.py

Validar sem restaurar:

python scripts/restore_data.py data/backups/NOME-DO-BACKUP.zip
  • dry_run=true.
  • files_restored=0.
  • files_validated igual ao número de arquivos do manifesto.

6. Aplicação autorizada

Somente continue após revisão humana do dry-run e do backup.

  • Registrar quem autorizou e em qual commit.
  • Manter os processos escritores encerrados.
  • Executar uma única vez e guardar o relatório completo.
python scripts/migrate_local_data.py --apply
  • Registrar backup_path retornado.
  • Comparar imported com found - duplicates - rejected considerando entidades derivadas.
  • Confirmar que rejeições permanecem explícitas.
  • Confirmar que nenhum JSON/JSONL foi apagado ou alterado.

Este item permanece pendente enquanto não houver execução real autorizada. Testes em tmp_path não contam como migração do ambiente.

7. Verificação pós-migração

  • Validar schema, migrations, FKs e integridade.
  • Executar health check novamente.
  • Comparar contagens pré/pós.
  • Confirmar schema atual esperado.
  • Revisar candidaturas, snapshots, origem e traces incompletos.
python scripts/migrate_local_data.py --verify
python scripts/check_data_health.py
  • --verify retorna success=true e sem warnings de validação.
  • PRAGMA foreign_key_check não produz violações.
  • Não há schema_version_mismatch.
  • Warnings legados estão explicados e aceitos, não ocultados.

8. Idempotência

  • Executar novo dry-run e comparar identidades.
  • Se uma segunda aplicação for autorizada, confirmar que o mesmo checksum não reinsere os registros.
  • Confirmar que novos itens são apenas dados criados após o primeiro relatório.

legacy_migration_history usa arquivo + checksum + tipo + ID. Alterar o arquivo muda o checksum e exige nova revisão.

9. Restore drill isolado

Não teste restore sobre o diretório ativo.

  • Escolher um diretório vazio fora de data/.
  • Validar o backup novamente.
  • Restaurar no diretório isolado.
  • Rodar health check sobre a cópia.
  • Comparar manifesto, arquivos e contagens.
python scripts/restore_data.py data/backups/NOME-DO-BACKUP.zip --destination ../sotuhire-restore-validation
python scripts/restore_data.py data/backups/NOME-DO-BACKUP.zip --destination ../sotuhire-restore-validation --apply
python scripts/check_data_health.py --data-dir ../sotuhire-restore-validation
  • files_restored corresponde ao manifesto.
  • O banco restaurado passa em schema/FK/integridade.
  • Nenhum segredo aparece na cópia.
  • Remover o diretório de validação somente depois de registrar o resultado necessário.

10. Plano de rollback

Se a verificação falhar:

  • Parar processos que usam o diretório.
  • Não editar o backup original.
  • Validar o backup com restore dry-run.
  • Registrar a falha e o relatório da migração.
  • Restaurar somente após autorização.
  • Rodar health check depois do rollback.
  • Manter os JSON/JSONL antigos até confirmar recuperação.
python scripts/restore_data.py data/backups/NOME-DO-BACKUP-PRE-MIGRACAO.zip
python scripts/restore_data.py data/backups/NOME-DO-BACKUP-PRE-MIGRACAO.zip --apply
python scripts/check_data_health.py

11. Conferência final

  • Migração aplicada ou explicitamente adiada.
  • Resultado real do dry-run registrado.
  • Resultado real do apply registrado, se executado.
  • Backup e restore drill registrados.
  • Dados rejeitados e warnings documentados.
  • Arquivos antigos preservados.
  • Nenhum segredo em banco, ZIP, logs ou relatórios.
  • git status sem artefatos de dados acidentalmente rastreados.
  • Secret scan final sem ocorrência.

Até que os itens de execução real sejam preenchidos, a migração deve ser descrita como disponível e testada com fixtures — não como aplicada aos dados reais.