Skip to content

desktop-release.md

Latest commit

 

History

History
279 lines (206 loc) · 8.78 KB

desktop-release.md

File metadata and controls

279 lines (206 loc) · 8.78 KB
Raw

Release Desktop do Radar Escola

Este documento define a esteira alvo de CI/CD ponta a ponta para o app desktop do Radar Escola.

Objetivo Final

O objetivo final da CI/CD e permitir que uma pessoa usuaria consiga:

  1. abrir a pagina de release do projeto;
  2. baixar o instalador Windows;
  3. instalar o Radar Escola na maquina desktop;
  4. abrir o aplicativo;
  5. usar um banco local;
  6. validar que a experiencia basica funciona sem depender de infraestrutura tecnica externa.

Essa e a materializacao da regra de UX definida para o produto:

A pessoa usuaria final deve ver instalar, abrir, cadastrar, acompanhar, marcar como resolvido, consultar historico e exportar seguranca.

Ela nao deve precisar saber que existem Tauri, React, TypeScript, Rust, SQLite, CI, GitHub Actions ou banco de dados.

Estado Atual

O repositorio OpenEduOps/radar-escola contem a documentacao de produto, o scaffold tecnico minimo executavel e uma primeira release tecnica publicada.

O workflow .github/workflows/desktop-release.yml ja consegue gerar um instalador Windows tecnico do scaffold atual por execucao manual e por tag v*.

A release tecnica atual e:

v0.0.1

Pagina da release:

https://github.com/OpenEduOps/radar-escola/releases/tag/v0.0.1

Esse instalador ainda nao representa a V0 funcional completa. Ele valida a casca desktop, o carregamento do frontend empacotado, o menu nativo Playground e o CRUD de referencia usado por pessoas desenvolvedoras.

Contrato Minimo do App

Para ativar a esteira desktop, o repositorio do app precisara conter:

package.json
package-lock.json
src-tauri/Cargo.toml
scripts/smoke-windows.ps1

Esses arquivos ja existem no scaffold minimo atual.

O projeto tambem deve expor scripts locais claros:

npm ci
npm run lint
npm run typecheck
npm test
npm run build
npm run tauri build

Scripts podem ser ajustados conforme o scaffold real, mas a intencao deve ser preservada: qualquer pessoa mantenedora precisa conseguir reproduzir localmente o que a CI executa.

Scaffold Atual

O scaffold atual contem:

  • interface React/TypeScript minima;
  • Vite para build frontend;
  • Tauri 2 como casca desktop;
  • janela inicial do Radar Escola;
  • janela principal configurada para abrir maximizada;
  • menu nativo Playground > Iniciar playground;
  • CRUD playground master-detail como referencia tecnica;
  • icone Windows exigido pelo empacotamento Tauri;
  • capability Tauri core:default para a janela principal;
  • script de smoke check para instalar, abrir e validar o menu nativo do app;
  • package-lock.json para dependencias npm reproduziveis.

Ele nao contem regra de negocio, banco local ou fluxos de usuario. Isso e intencional para manter o scaffold honesto.

Esteira Ponta a Ponta

O workflow Desktop Release deve cobrir:

  1. preflight do scaffold desktop;
  2. instalacao de Node e Rust;
  3. instalacao de dependencias;
  4. lint, typecheck, testes e build do frontend;
  5. cargo fmt, cargo clippy e cargo test na camada Tauri/Rust;
  6. build do instalador Windows;
  7. smoke test do instalador em runner Windows;
  8. coleta de .exe ou .msi;
  9. geracao de SHA-256;
  10. upload de artefato baixavel no GitHub Actions;
  11. publicacao em GitHub Release quando houver tag v*.

Smoke Test Windows

O arquivo scripts/smoke-windows.ps1 valida o minimo necessario para confiar que o instalador nao esta quebrado.

Ele testa hoje:

  • instalador encontrado;
  • instalacao sem erro;
  • executavel instalado usa o subsistema Windows GUI, nao Console;
  • aplicativo abre sem crash imediato;
  • janela principal e criada;
  • janela principal abre maximizada;
  • menu nativo Playground > Iniciar playground existe;
  • comando do menu nativo aciona o fluxo Playground;
  • aplicativo permanece aberto apos o comando;
  • desinstalacao ou limpeza do runner quando aplicavel.

Ele deve evoluir, quando o MVP funcional existir, para testar tambem:

  • banco local criado no local esperado;
  • fluxo minimo de primeiro uso;
  • criacao e consulta de uma necessidade;
  • exportacao/restauracao de seguranca em ambiente controlado.

O smoke test nao substitui teste de UX humano, mas reduz o risco de publicar um instalador que sequer abre.

Artefatos Esperados

Cada build de release deve produzir:

Radar.Escola_<versao>_x64-setup.exe
Radar.Escola_<versao>_x64-setup.exe.sha256

Enquanto nao houver assinatura de codigo, a documentacao da release deve avisar que o Windows pode exibir alerta de origem desconhecida.

Publicacao

Pull requests e pushes comuns devem validar qualidade e build.

Tags v* devem publicar release com artefatos baixaveis.

Release tecnica atual:

v0.0.1

Comportamento Enquanto o App Ainda E Scaffold

O workflow Desktop Release pode ser executado manualmente para conferir o estado da esteira. Tags v* tambem publicam release quando os checks e o smoke Windows passam.

O scaffold minimo do app ja existe no repositorio para validar a esteira sem criar funcionalidade falsa de MVP. Ele contem uma tela tecnica simples do Radar Escola, menu nativo Playground e CRUD playground de referencia, sem fluxo de cadastro escolar, banco local ou regras de negocio da V0.

Enquanto o app ainda for apenas scaffold, a esteira gera um instalador tecnico minimo, mas ele deve ser tratado apenas como validacao da casca desktop, do frontend empacotado e do pipeline de release.

Se alguem tentar publicar uma tag v* sem scaffold valido, o preflight deve falhar. Uma release versionada nao pode ser publicada sem artefato real.

Pendencias Que Dependem do App

Ainda nao e possivel entregar a experiencia completa de produto porque faltam:

  • fluxo funcional do MVP;
  • banco SQLite local;
  • persistencia real;
  • autenticacao local;
  • cadastro de pessoas/usuarios;
  • registro e acompanhamento de necessidades;
  • exportacao/restauracao de seguranca;
  • Cargo.lock gerado por ambiente Rust valido;
  • decisao futura sobre assinatura de codigo.

Essas pendencias devem ser resolvidas neste repositorio quando o app Radar Escola evoluir para alem do scaffold.

Limitacao Local Observada

No ambiente local atual, npm ci, npm run typecheck, npm run build e npm run tauri -- info foram executados.

O build Tauri completo nao foi executado localmente porque Rust, Cargo e Visual Studio Build Tools/MSVC nao estao instalados nesta maquina. O workflow de release usa runner Windows do GitHub Actions e instala Rust antes do build.

Mesmo assim, o contrato de CI/CD ja deixa claro qual sera o caminho de entrega do produto para a pessoa usuaria final.

Instalador Gerado Em CI

Como o ambiente local ainda nao tem toolchain Rust/MSVC, o instalador foi gerado pelo workflow Desktop Release em runner Windows do GitHub Actions.

Validacao realizada para v0.0.1:

  • workflow Desktop Release concluido com sucesso;
  • release publicada em https://github.com/OpenEduOps/radar-escola/releases/tag/v0.0.1;
  • artefato Radar.Escola_0.0.1_x64-setup.exe publicado;
  • artefato Radar.Escola_0.0.1_x64-setup.exe.sha256 publicado;
  • arquivo .sha256 gerado e conferido localmente;
  • SHA-256 do instalador: 4ff7f74dcfdce5a4dfb1728c16a10fe488210e9ef2f35bb2d57bd369f08b5c24;
  • instalacao silenciosa local executada com codigo 0;
  • executavel instalado em C:\Users\silva-dev\AppData\Local\Radar Escola\radar-escola.exe;
  • aplicativo abriu sem crash imediato;
  • executavel usa subsistema Windows GUI e nao abre prompt atras da janela;
  • janela principal abriu maximizada;
  • UI do Radar Escola renderizou no executavel instalado;
  • item nativo Playground > Iniciar playground foi acionado por comando Win32;
  • tela Master detalhe do playground apareceu no executavel instalado.

Correcoes aplicadas para chegar nesse estado:

  • adicionar src-tauri/icons/icon.ico;
  • configurar base: "./" no Vite para assets relativos no app empacotado;
  • adicionar capability Tauri core:default para permitir a ponte de eventos da janela principal.
  • compilar builds release do Tauri com subsistema Windows GUI para evitar que um prompt apareca atras da janela principal.
  • configurar a janela principal para abrir sempre maximizada e validar esse comportamento no smoke test Windows.

Tentativa Local De Build Tauri

O comando abaixo foi executado localmente:

npm run tauri -- build

Resultado:

failed to run 'cargo metadata' ... program not found

Conclusao:

  • o build frontend do scaffold esta valido;
  • os testes automatizados do CRUD passam;
  • o instalador pode ser gerado no GitHub Actions;
  • o instalador ainda nao pode ser gerado diretamente nesta maquina;
  • a pendencia local imediata e instalar Rust/Cargo;
  • a pendencia nativa seguinte e instalar Visual Studio Build Tools/MSVC com as ferramentas C++ exigidas pelo Tauri no Windows.

Quando a toolchain nativa estiver disponivel, o caminho esperado para gerar o instalador continua sendo:

npm run tauri -- build
scripts/smoke-windows.ps1