Como a regra funciona por trás da interface e da API.
Um resumo técnico da lógica de escalas, da API FastAPI, da persistência em JSON/PostgreSQL
e da arquitetura em camadas usada no projeto.
Na consulta pessoal, informe uma vez a data real de início da sequência. Ela permanece fixa quando você muda a data consultada, navega pelo calendário ou escolhe a vista de 3 dias, 7 dias ou mês. A vista escolhida é lembrada neste dispositivo. Antes da referência, as datas são projeções; uma escala 12x36 pode mudar de trabalho para folga no mesmo dia, por isso o detalhe mostra o horário observado e os intervalos.
Use Minhas escalas para cadastros e Mais para comparar, gerar relatório e fazer backup. A origem pública calcula tudo no navegador e não acessa a API local. O repositório contém um plano de dados e custos para possibilidades futuras; contas e equipes não estão ativas.
Ciclo por dias
Usa a soma dos dias trabalhados e dos dias de folga para formar um ciclo.
A posição da data consultada dentro desse ciclo define se o status será trabalho ou folga.
ciclo = dias_trabalho + dias_folga
dias_passados = data_consulta - data_inicio
posicao = dias_passados % ciclo
status = "Trabalhando" se posicao < dias_trabalho
status = "Folga" caso contrário
Exemplos atendidos por esse tipo: 6x3, 5x2 e 4x2.
Ciclo por horas
Segue o mesmo princípio do ciclo por dias, mas calcula a posição usando data e hora.
É útil para escalas como 12x36.
ciclo = horas_trabalho + horas_folga
horas_passadas = data_hora_consulta - data_hora_inicio
posicao = horas_passadas % ciclo
status = "Trabalhando" se posicao < horas_trabalho
status = "Folga" caso contrário
Na API, esse modelo exige hora_inicio e hora_consulta
para calcular corretamente o status.
Turno rotativo
Usa uma sequência personalizada. Cada posição da lista representa um dia do ciclo.
O sistema calcula em qual posição a data consultada cai.
A tela Comparador calcula os dois lados pelo mesmo núcleo de calendário usado pelo simulador. Cada escala tem âncora e parâmetros independentes; a data selecionada e o horário observado são comuns.
É possível ajustar uma configuração sem salvá-la. O resumo do mês conta apenas os status no horário selecionado, não dias completos nem horas trabalhadas. Em ciclos por horas, os detalhes da data mostram também os intervalos reais entre trabalho e folga.
No GitHub Pages, escalas salvas vêm do armazenamento do navegador e a página não consulta a API local. No servidor estático local, pode listar escalas do navegador ou da API local disponível. A API é demonstrativa, sem autenticação ou separação por usuário.
Relatório mensal
A tela Relatório mostra um calendário mensal de uma escala ou compara duas, com inícios de ciclo independentes. O mês exibido só muda para o mês do início quando o botão correspondente é acionado. Modelos e escalas salvas podem receber ajustes temporários que não alteram os dados originais.
Calendário, tabela detalhada, impressão, XLSX e CSV vêm do mesmo resultado calculado pelo núcleo compartilhado. Para ciclos por dias não há horário obrigatório. Se uma escala usa horas, o horário selecionado é o instante observado em cada data; os totais não representam dias inteiros nem horas trabalhadas. Em 12x36 pode haver troca de trabalho e folga dentro da mesma data.
O XLSX traz calendário, legenda, resumo e aba de registros; seu gerador local report-xlsx.js não usa dependência externa nem CDN. A impressão usa o navegador. O CSV sem formatação traz metadados e os registros da prévia em UTF-8 com BOM e separador ;; se o Excel abrir tudo em uma coluna, importe usando esse separador. Textos que poderiam virar fórmulas são protegidos. No GitHub Pages, a página usa somente escalas deste navegador e não consulta a API local. A API de demonstração não tem autenticação nem isolamento por usuário e deve continuar restrita ao uso local.
API FastAPI
A API expõe parte das funcionalidades do simulador por HTTP.
A demo pode usar essa API local para modelos e escalas salvas; sem backend, o cálculo e os cadastros funcionam no navegador.
GET /health
GET /api/v1/modelos
GET /api/v1/escalas
POST /api/v1/escalas
DELETE /api/v1/escalas/{nome}
POST /api/v1/simulacao/status
POST /api/v1/simulacao/proximos-dias
Para testar a integração local, execute:
uvicorn api.app:app --reload
Persistência
A API usa JSON em data/escalas.json por padrão. PostgreSQL existe como alternativa para a aplicação CLI e não é necessário para executar a API ou a demo pública.
O projeto separa interface, validação, regra de negócio, API e persistência.
Isso facilita manutenção, testes e evolução para versões futuras.
CLI / Demo web
↓
API FastAPI
↓
Routes
↓
EscalaService
↓
EscalaRepository
├── JsonEscalaRepository
└── PostgresEscalaRepository
↓
JSON ou PostgreSQL
USO NO CELULAR
Instalação, uso offline e proteção dos dados
Depois de uma visita online completa, as páginas do simulador, comparador e relatório ficam disponíveis sem conexão. No Android, use a opção de instalação oferecida pelo Chrome ou seu menu. No iPhone, abra no Safari e escolha Compartilhar → Adicionar à Tela de Início.
As escalas salvas neste navegador ficam neste dispositivo, sem sincronização. Informe a Data de início da sequência (data e hora para ciclos por horas), confira a prévia e confirme. A referência fixa é guardada separadamente da definição da escala: a API local não a persiste. Ao aplicar a mesma escala ou abrir comparador e relatório, a referência confirmada volta; cadastros antigos sem referência pedem confirmação uma vez. Uma data consultada anterior ao início aparece como projeção não confirmada, fora dos totais mensais.
Em Dados locais, o backup JSON v2 inclui cadastros locais e referências confirmadas. Cada referência leva nome, tipo e parâmetros da escala para validação, inclusive se vier da API local; o arquivo não copia o catálogo completo da API nem a consulta ativa. Antes de importar, confira a prévia do efeito sobre as referências. Backups v1 são aceitos e preservam referências de cadastros idênticos. Para o protótipo Android, use a exportação v1 compatível e digite a referência manualmente. Limpar os dados do navegador ou desinstalar pode apagar escalas e referências.
Quando uma versão nova estiver pronta e houver conexão, todas as telas mostram Atualização disponível. Você pode escolher Atualizar agora ou Mais tarde; a segunda opção oculta o aviso nesta aba por até uma hora. Antes de atualizar, confirme o aviso se houver campos alterados; a página recarrega somente após sua escolha. Em duas abas, a outra não recarrega sozinha: conclua o que estiver preenchendo e atualize-a quando quiser. As escalas e a consulta guardada permanecem no dispositivo.
Para passar da versão anterior, que ainda não tinha esse botão, feche todas as janelas da PWA e abas da demo e abra novamente com conexão. O worker em espera poderá assumir sem limpar dados. O manifesto usa o ícone 3D v5 em versões comum e maskable; as fontes SVG editáveis e os PNGs estão em icons/, enquanto os arquivos v2 continuam acessíveis. O ícone instalado no Android pode depender de uma confirmação do Chrome e não necessariamente muda ao tocar no botão de atualização. No GitHub Pages não há chamadas para a API em localhost; em um servidor estático local, a API continua opcional.
Fluxo técnico atual
A v0.14.0 oferece modo local e integração com API para demonstrar interface, backend e persistência.
A demo deixa de ser apenas uma página visual e passa a testar uma integração real
com o backend local.
Demo web
Interface visual para simular modelos prontos e gerenciar escalas salvas.
FastAPI
Backend local responsável por expor modelos, simulações e CRUD de escalas.
Service
Camada que centraliza regras de negócio relacionadas às escalas salvas.
Repository
Camada de persistência desacoplada, com suporte a JSON e PostgreSQL.