Radar Escola

Aplicativo desktop local para escolas acompanharem necessidades operacionais.

Este repositorio e o projeto de produto e implementacao do Radar Escola dentro da organizacao OpenEduOps.

Estado Atual

O projeto esta em fase de primeiro fluxo funcional demonstravel, especificacao V1 e organizacao do ciclo de implementacao do MVP.

Ja existem:

• documentacao de produto V0 e V1;
• especificacao executavel V1;
• matriz de regras de dominio e modelo relacional em implementacao gradual;
• matriz de issues V1 com 85 issues cadastradas no GitHub;
• primeira rodada fundacional #4 a #23 implementada e fechada no GitHub;
• trilha transversal Docker com 9 issues concluidas para ambiente tecnico;
• app minimo Tauri + React + TypeScript;
• playground CRUD master-detail com persistencia SQLite local no desktop;
• testes unitarios do playground;
• teste E2E Playwright do playground, incluindo persistencia por reload;
• primeira fatia funcional do Radar com persistencia SQLite local no desktop;
• CI em main com checks de documentacao, higiene, frontend, testes, validacao Docker dev e guardrail de metadados publicos;
• workflow Desktop Release para gerar instalador Windows tecnico do scaffold;
• release tecnica v0.0.1 publicada com instalador Windows e checksum;
• dominio inicial do Radar com regras puras para escola, pessoas, primeiro acesso, permissoes, necessidades, envolvidos, andamento, resolucao, cancelamento, equipamentos, auditoria, plano de acao, sessao local e pacote de seguranca;
• migration SQLite inicial do MVP em src-tauri/migrations/001_initial_mvp.sql, aplicada no bootstrap Tauri e validada em banco vazio por teste automatizado;
• fluxo inicial utilizavel dentro da aplicacao para configurar escola, entrar, cadastrar pessoa, registrar necessidade, marcar envolvidos, atualizar andamento e marcar como resolvido;
• documento de projeto para dockerizacao do ambiente tecnico;
• .dockerignore e Dockerfile.dev;
• imagem Docker dev validada para typecheck, testes unitarios e build frontend.

O app atual ainda nao e o MVP funcional completo. Ele ja demonstra o fluxo principal do Radar e, no desktop, persiste essa primeira fatia em SQLite local via Tauri. O fallback em localStorage fica restrito ao navegador de desenvolvimento e aos testes E2E web. Ainda faltam recuperacao local completa, auditoria operacional, exportacao/restauracao e hardening de seguranca do MVP.

Direcao Do Produto

• Windows-first.
• Local-first.
• Tauri + React + TypeScript + SQLite.
• UX da pessoa usuaria final antes da tecnologia.
• Linguagem em Portugues Brasileiro.
• Sem internet obrigatoria na V0.

SQLite faz parte da arquitetura alvo. Ele ja foi implementado no playground de referencia, na primeira fatia funcional do Radar e na migration relacional inicial do MVP.

Por isso, o fluxo atual deve ser lido como primeira fatia de produto demonstravel, e o playground continua como referencia tecnica de CRUD, master-detail, estado, regras puras, comandos Tauri, SQLite e testes.

Fora Do MVP Implementado Hoje

Ainda nao existem de forma definitiva no app:

• recuperacao local de acesso;
• hashing forte no runtime nativo;
• telas/repositorios finais de equipamentos operacionais;
• auditoria persistida e consultavel pela direcao;
• exportacao/restauracao operacional de seguranca.

Proximo Passo

Evoluir o fluxo inicial para a arquitetura alvo, seguindo a ordem sugerida:

REQ -> DOM -> PER -> ENG -> APP -> VIEW -> QA

Na pratica, o proximo bloco tecnico deve seguir para PER-002 a PER-011, separando repositorios finais, conectando casos de uso ao banco relacional do MVP e endurecendo salvaguardas de acesso antes de expandir telas de equipamentos, auditoria e exportacao/restauracao.

A estrategia de o fundador tocar pessoalmente as issues fundacionais do MVP, sem fechar a entrada de colaboradores, esta registrada em FUNDADOR_TOCANDO_PRODUTO.md.

Como Contribuir

O backlog inicial da V1 esta aberto nas issues do GitHub.

Para comecar:

• leia CONTRIBUTING.md;
• escolha uma issue pequena e bem delimitada;
• para primeiras contribuicoes, procure labels como good first issue, documentation, qa, domain ou tests;
• mantenha branch, titulo de PR e commits focados no produto, na issue ou no comportamento alterado;
• atualize documentacao e testes quando a mudanca alterar comportamento, requisitos ou fluxo de validacao.

As regras de contribuicao permitem contribuicoes humanas ou assistidas por automacao, desde que sejam revisaveis e que os metadados publicos continuem focados no produto.

Como Rodar Localmente

Pre-requisitos para validar o frontend do scaffold:

• Node.js 24, mesma versao usada na CI;
• npm.

Pre-requisitos adicionais apenas para build desktop local:

• Rust/Cargo;
• Visual Studio Build Tools/MSVC com ferramentas C++ para Windows.

Instale as dependencias:

npm ci

Execute o frontend do scaffold em modo desenvolvimento:

npm run dev

Execute as verificacoes locais principais:

npm test
npm run test:e2e
npm run typecheck
npm run build

Esses comandos validam regras puras do playground, repositório persistente do playground no fallback web, regras iniciais do Radar, fluxo E2E do CRUD de referencia com persistencia por reload, fluxo E2E inicial do produto, TypeScript e build Vite.

Docker Para Desenvolvimento

Docker e opcional e existe apenas para desenvolvimento, QA tecnico e contribuicao OSS. Ele nao faz parte da experiencia final da escola.

Construa a imagem dev:

docker build -f Dockerfile.dev -t radar-escola-dev:local .

Execute as validacoes Node basicas:

docker run --rm radar-escola-dev:local npm run typecheck
docker run --rm radar-escola-dev:local npm test
docker run --rm radar-escola-dev:local npm run build

O teste E2E Playwright continua fora da imagem basica nesta fase. O caminho de instalador Windows continua sendo o workflow Desktop Release.

Estrutura Inicial Do Codigo

O scaffold ja segue a arquitetura planejada para evitar que regras de negocio, interface e infraestrutura fiquem misturadas.

Mapa rapido:

• src/app: composicao raiz da aplicacao;
• src/features: telas e fluxos de usuario;
• src/features/radar: primeiro fluxo utilizavel do Radar de Necessidades;
• src/features/playground: CRUD persistente de referencia do scaffold atual;
• src/application: casos de uso e orquestracao futura;
• src/domain: entidades e regras puras por dominio;
• src/domain/radar: dominio inicial demonstravel do fluxo principal;
• src/infrastructure: repositorios, ponte Tauri, hashing local, arquivos e CSV futuro;
• src/shared: UI e utilitarios reutilizaveis;
• src/testing: fixtures e helpers de teste;
• src-tauri/src: runtime nativo minimo do desktop, incluindo comandos SQLite do playground e da primeira fatia Radar.

Regra pratica: regra de negocio deve nascer testavel fora da interface, e tela nao deve acessar banco diretamente.

App Desktop Local

O projeto usa Tauri 2 como casca desktop.

Com a toolchain nativa instalada, o caminho esperado para build desktop local e:

npm run tauri -- build

No ambiente local usado ate aqui, Rust/Cargo e Visual Studio Build Tools/MSVC nao estavam instalados. Por isso, o instalador Windows foi gerado e validado pelo workflow Desktop Release no GitHub Actions.

Executavel Windows Validado

O workflow Desktop Release ja gerou e publicou a release tecnica v0.0.1 do scaffold atual.

Artefatos publicados:

• Radar.Escola_0.0.1_x64-setup.exe;
• Radar.Escola_0.0.1_x64-setup.exe.sha256.

Validacoes realizadas sobre o artefato:

• workflow concluido com sucesso;
• instalador .exe e arquivo .sha256 gerados;
• SHA-256 conferido localmente;
• instalacao silenciosa concluida com codigo 0;
• executavel instalado abriu sem crash imediato;
• executavel nao abre prompt atras da janela principal;
• janela principal abre maximizada;
• tela inicial renderizou no app instalado;
• menu nativo Playground > Iniciar playground foi acionado;
• tela Master detalhe do playground apareceu no executavel instalado;
• smoke Windows da CI tambem aciona o menu nativo do Playground.

O artefato atual e uma validacao tecnica do scaffold. Ele ainda nao deve ser tratado como release funcional para escola.

Leitura Recomendada

Para entender o produto antes de implementar:

• CONTEXTO_INICIAL.md;
• REQUISITOS_V0.md;
• ESCOPO_V0.md;
• FLUXO_E2E_V0.md;
• GUARDRAILS_V0.md.

Para implementar a V1:

• FUNDADOR_TOCANDO_PRODUTO.md;
• GUIA_ESPECIFICACAO_EXECUTAVEL_V1.md;
• DETALHAMENTO_REQUISITOS_V1.md;
• DETALHAMENTO_BLOCOS_TRANSVERSAIS_V1.md;
• REGRAS_DE_DOMINIO_V1.md;
• MATRIZ_ISSUES_V1.md;
• PROJETO_DOCKERIZACAO_AMBIENTE.md.

Para entender engenharia, CI e release:

• docs/architecture.md;
• docs/implementation-status.md;
• docs/ci.md;
• docs/development-docker.md;
• docs/desktop-release.md.

Documentacao

• CONTEXTO_INICIAL.md: contexto educacional, decisao Windows-first e filosofia inicial do produto.
• REQUISITOS_V0.md: requisitos funcionais, nao funcionais e criterios de aceite da V0.
• ESCOPO_V0.md: linha de corte do primeiro MVP executavel.
• FLUXO_E2E_V0.md: fluxo ponta a ponta esperado para uma escola.
• GUARDRAILS_V0.md: limites, riscos, privacidade, seguranca local e testes planejados.
• VISAO_PROTOTIPAL_V0.md: primeira visao prototipal em baixa fidelidade.
• VISAO_PROTOTIPAL_V1.md: rascunhos de tela em ASCII alinhados aos requisitos, dominios e matriz de issues da V1.
• DETALHAMENTO_REQUISITOS_V0.md: ordem recomendada para detalhar requisitos implementaveis da V0.
• DETALHAMENTO_BLOCOS_TRANSVERSAIS_V0.md: detalhamento de auditoria, sessao, equipamentos, transferencia de direcao, testes, acessibilidade e criterios globais de aceite.
• GUIA_ESPECIFICACAO_EXECUTAVEL_V1.md: guia inicial para transformar requisitos V0 em especificacao executavel, modelo relacional, regras de dominio e issues por camada.
• DETALHAMENTO_REQUISITOS_V1.md: casos de uso em estilo RUP simplificado, com fluxos principais, excecoes, regras, aceite, testes e tarefas minimas e modulares.
• DETALHAMENTO_BLOCOS_TRANSVERSAIS_V1.md: guardrails transversais da V1 para auditoria, sessao, seguranca local, privacidade, acessibilidade, exportacao/restauracao e testes.
• REGRAS_DE_DOMINIO_V1.md: modelo relacional, dominios, tabelas, operacoes CRUD, queries e regras de integridade.
• MATRIZ_ISSUES_V1.md: planejamento de 85 issues minimas e modulares do MVP, ja cadastradas no GitHub, e linha de corte separada para issues Docker transversais.
• FUNDADOR_TOCANDO_PRODUTO.md: decisao de direcao para o fundador tocar issues fundacionais do MVP enquanto o projeto mantem boas entradas para colaboradores.
• PROJETO_DOCKERIZACAO_AMBIENTE.md: documento de projeto para dockerizar o ambiente tecnico sem alterar a experiencia final desktop local Windows.
• CI_CD_OSS.md: estrategia de CI/CD OSS para o produto.
• docs/project-context.md: contexto duravel do projeto.
• docs/implementation-plan.md: fases de implementacao.
• docs/final-testable-delivery.md: linha de chegada testavel da V0.
• docs/implementation-status.md: estado atual de implementacao.
• docs/roadmap.md: roadmap navegavel.
• docs/desktop-release.md: esteira de release desktop para Windows.
• docs/architecture.md: arquitetura inicial de codigo, camadas e responsabilidades.
• docs/ci.md: funcionamento da CI do produto.
• docs/development-docker.md: guia operacional de Docker para desenvolvimento, subordinado ao documento de projeto e aos limites da UX desktop local Windows.
• CONTRIBUTING.md: orientacoes para contribuir e politica de metadados publicos.
• docs/permissions.md: politica de permissoes minimas dos workflows.
• docs/oss-guardrails.md: guardrails praticos para contribuicao OSS.