Pular para o conteúdo principal

Guia do Desenvolvedor — Publicar uma nova versão

Como lançar uma nova versão do sistema desktop pelo painel (Atualizações → Migração de Bancos), cobrindo os três tipos de conteúdo: migrates de banco, binário (SAIKOO.exe) e arquivos.

Regra de ouro: migre os bancos ANTES de publicar o binário/arquivos. Publicar é o que libera os clientes para baixar; se o .exe novo chegar antes do banco estar migrado, quebra.

Visão geral — o ciclo de uma release​

1. Criar a versão            (ex.: 4.3.0.0)
2. Adicionar os migrates     (SQL do SQL Server)
3. Subir o binário .exe      (fica em RASCUNHO)
4. Adicionar arquivos        (qualquer tipo/pasta) — opcional
5. Migrar os bancos          (Rollout → Disparar: canário, depois todos)
6. PUBLICAR a versão         (escreve o latest.json → clientes atualizam)

Enquanto a versão está em rascunho, nada é distribuído. Só o passo 6 (Publicar) torna a versão "a atual" para os clientes.

Conceitos​

  • Versão: uma linha em "Versões" (SemVer, ex.: 4.3.0.0). É o guarda-chuva que agrupa migrates + binário + arquivos.
  • Baseline (4.0.0.0): a versão de entrada no novo mecanismo.
  • Migrate: um script SQL (SQL Server) que altera o schema. Roda uma vez por banco.
  • Binário: o SAIKOO.exe. Versionado; o cliente baixa quando muda.
  • Arquivo: qualquer outro arquivo (DLL, .rtm, .exe auxiliar, .txt...), em qualquer pasta.
  • Publicar: grava o latest.json no S3/CDN. É a fonte que o atualizador do cliente lê. Publicar = tornar a versão a "última" para todos.
  • Manifesto (latest.json): estado cumulativo publicado (exe + todos os arquivos, último-por-caminho). O cliente reconcilia contra ele.

Passo a passo​

1. Criar a versão​

Migração de Bancos → card "Nova versão": informe a versão (ex.: 4.3.0.0) e uma observação. Salvar.

2. Adicionar os migrates (banco)​

card "Adicionar migrate": escolha a versão, uma descrição curta (vira o nome AAAAMMDDHHMM_descricao.sql), e cole o SQL ou envie um arquivo .sql. Marque "Exige janela de manutenção" só se o migrate for pesado/disruptivo (o app bloqueia o cliente enquanto roda).

Regras dos migrates:

  • SQL Server (T-SQL) — é o dialeto dos bancos dos clientes (SQL Server 2019).
  • Aditivos (expand/contract): adicione colunas/tabelas; não drope/renomeie algo que a versão antiga do app ainda usa. Remoções só um ciclo depois (o app antigo pode rodar por um tempo no banco novo).
  • Idempotentes quando possível (IF NOT EXISTS ...) — mais seguros para reprocessar.
  • A ordem é automática (ordem de cadastro dentro da versão). Cada migrate roda uma vez por banco (controlado por __schema_migrations).

3. Subir o binário (.exe)​

card "Binário do app (.exe)": escolha a versão, envie o SAIKOO.exe, marque "Update obrigatório" se quiser forçar. Vai para o S3, o SHA-256 é calculado. Fica em RASCUNHO até você publicar.

4. Adicionar arquivos (opcional — qualquer tipo/pasta)​

card "Arquivos da versão (além do .exe)": escolha a versão, informe o caminho de destino relativo e envie o arquivo. Exemplos de caminho:

  • Raiz: EmissorNotaServico.exe
  • Subpasta: Relatorios/ComissaoProfissional.rtm

Para remover um arquivo no cliente: preencha o caminho, marque "Remover no cliente" e não envie arquivo.

Como funciona o cumulativo (importante): você só anexa o arquivo na versão em que ele muda. O manifesto junta automaticamente o último de cada caminho. Ex.: x.txt na 4.1 e y.txt na 4.2 → um cliente que pulou da 4.0 para a 4.2 recebe os dois. Não precisa repetir arquivos em cada versão.

5. Migrar os bancos (ANTES de publicar)​

Atualizações → Rollout de Versão:

  1. Selecione a versão.
  2. Marque os clientes liberados (comece com um canário — poucos), Salvar rollout.
  3. Disparar migração → o worker aplica os migrates nos bancos liberados (com backup + transação).
  4. Acompanhe em Status da Migração. Validado o canário, volte, libere todos e dispare de novo (é idempotente: quem já migrou é pulado).

A migração roda por versão e respeita o rollout (canário). Só migra clientes que já fizeram o cutover (estão na v4). O worker roda a cada ~30 min.

6. Publicar a versão​

Na listagem "Versões e migrates", na versão desejada, clique Publicar (confirme). Isso regenera o latest.json com o exe + arquivos cumulativos da maior versão publicada. A partir daí, ao abrir, os clientes baixam a nova versão.

Faça isso só depois de migrar os bancos dos clientes que vão receber essa versão.

(rollback) Despublicar​

Se algo saiu errado, clique Despublicar na versão — o latest.json volta para a versão publicada anterior. Os clientes deixam de pegar a versão problemática.

Como o cliente recebe (resumo técnico)​

O atualizador (launcher) roda antes do app e lê o latest.json na CDN:

  • Binário: baixa o SAIKOO.exe só se o SHA mudou (não rebaixa à toa).
  • Arquivos: reconcilia por SHA-256 — baixa o que falta/mudou, cria subpastas, e apaga os marcados como remover. Como o manifesto é cumulativo, pulo de versão é resolvido sozinho.
  • Tudo com o app parado (sem travar arquivo). Se algo falhar, abre a versão atual mesmo assim.

Regras de ouro (não esqueça)​

  1. Migrar o banco antes de publicar. Sempre.
  2. Migrates aditivos — nada de dropar/renomear o que o app antigo usa na mesma versão.
  3. Baseline (4.0.0.0) não roda migrate — é só a foto do schema atual. Mudança nova = versão acima.
  4. Anexe cada arquivo só na versão que o altera — o cumulativo cuida do resto.
  5. Rascunho não afeta ninguém — só Publicar libera.
  6. Canário primeiro — migre poucos, valide no Status, depois todos.
  7. Deu ruim? Despublicar (reverte o binário) e/ou avaliar restaurar backup do banco (o worker faz backup pré-lote).

Referência rápida​

Quero...Onde
Criar versãoMigração de Bancos → Nova versão
Adicionar SQL de bancoMigração de Bancos → Adicionar migrate
Subir o .exeMigração de Bancos → Binário do app
Subir/remover outros arquivosMigração de Bancos → Arquivos da versão
Migrar os bancosRollout de Versão → liberar + Disparar migração
Tornar a versão a atualMigração de Bancos → Publicar (na versão)
ReverterMigração de Bancos → Despublicar
AcompanharStatus da Migração (estado por cliente + fila)

Exemplo completo (lançar a 4.3.0.0)​

  1. Nova versão 4.3.0.0.
  2. Adicionar migrate: adiciona_coluna_comissao → ALTER TABLE dbo.profissional ADD comissao_percentual DECIMAL(5,2) NULL;
  3. Binário: envia o SAIKOO.exe novo.
  4. Arquivos: envia Relatorios/ComissaoProfissional.rtm.
  5. Rollout: canário (3 clientes) → Disparar → conferir Status → liberar todos → Disparar.
  6. Publicar a 4.3.0.0. Clientes atualizam ao abrir (exe + o .rtm).