Central de Escalas

Sistema web para gestão de escalas de trabalho, colaboradores, ausências e plantões. Uma máquina roda o servidor; qualquer dispositivo da rede acessa pelo navegador, sem instalar nada.

Índice

• Funcionalidades
• Tecnologias
• Início rápido
• Testes e qualidade
• Estrutura do código
• Implantação
• Login e primeiro acesso
• Configuração inicial do banco
• Usuários do sistema
• Backup
• Atualização
• Versionamento
• Documentação
• Licença

Funcionalidades

• Cadastro de colaboradores com horários de trabalho e almoço
• Lançamento de ausências, férias e folgas
• Calendário mensal com feriados e eventos
• Escala diária com timeline visual e resumo por horário
• Plantões de sábado, domingo e feriado
• Relatórios e exportação de dados (PDF)
• Autenticação com perfis de usuário e controle de acesso
• Backup automático (inclusive antes de restaurações)
• Tema claro e escuro
• Instalável como aplicativo (PWA)

Tecnologias

Camada	Stack
Frontend	HTML, CSS e JavaScript
Backend	Node.js 22+ e Express
Banco de dados	SQL Server

Início rápido (desenvolvimento)

Com Docker

Sobe o servidor e o banco juntos, sem instalar Node nem SQL Server na máquina (exige o Docker Desktop e a máquina virtual do WSL 2, que ocupa alguns GB de RAM):

cp .env.docker.example .env

docker compose up -d --build

Acesse http://localhost:4450. O banco SoftwareEscalas, as tabelas e o administrador são criados automaticamente na primeira subida — se ADMIN_PASSWORD ficar vazio, a senha aparece uma única vez em docker compose logs app. Os dados ficam em volumes e sobrevivem a reinícios; com restart: always os containers voltam sozinhos quando a máquina liga.

O app conecta com um login próprio, escalas_app, dono só do banco do app (senha em APP_DB_PASSWORD no .env); o sa fica só para o passo que cria banco e login. A porta 1433 do SQL só aceita conexão desta máquina. Quem já usava o Docker com o sa segue o passo a passo de atualização em docs/DOCKER.md.

O app roda sem root (usuário node da imagem). Ele só grava em /data (volume app-data) e na pasta de backup — que deve ficar dentro de /data (ex.: /data/backups) ou num volume montado. Um passo curto do compose (app-permissoes) acerta o dono de /data antes de o app subir, o que também migra volumes criados por versões antigas. Se atualizar só o app com docker compose up -d --no-deps app, rode antes docker compose run --rm app-permissoes.

docker compose down

Sem Docker

Requer Node 22.12+ e um SQL Server na máquina (o Express serve). O app conecta por TCP/IP, que o SQL Server Express traz desabilitado; o script abaixo, rodado uma vez no PowerShell como Administrador, habilita o TCP/IP numa porta fixa, cria o banco e um login próprio do app e libera a porta 4450 no firewall:

powershell -ExecutionPolicy Bypass -File scripts\preparar-sql-server.ps1

npm install
npm start

Acesse http://localhost:4450. Configure a conexão com o SQL Server pela própria tela de configuração inicial (veja Configuração inicial do banco). Um arquivo .env na raiz do projeto (modelo em .env.example) é lido na subida — útil para PORT e ADMIN_PASSWORD. O passo a passo completo está em docs/SERVIDOR-COMO-INSTALAR.md.

Testes e qualidade

Uma verificação completa antes de abrir um Pull Request (o CI roda o mesmo):

npm run verificar

Ela executa, em ordem:

Comando	O que faz
npm run smoke	Checagem de sintaxe de todos os .js
npm run lint	ESLint. O frontend é analisado como módulos ES sem nenhum global do projeto: nome que não é import, local ou API do navegador é erro, e função sem uso também
npm run typecheck	TypeScript em modo checkJs sobre backend, scripts e testes
npm run format:check	Prettier (por enquanto só nos arquivos novos — ver .prettierignore)
npm test	Testes unitários das regras de negócio, sem banco

Testes de integração (SQL Server de verdade)

Sobem o servidor em processo contra um SQL Server descartável em Docker e exercitam as rotas por HTTP: login e permissões, colaboradores, lançamentos, folgas de domingo, limite de setores e backup/restauração.

npm run integracao:banco:subir

npm run test:integracao

O banco de teste fica em 127.0.0.1:14339 (container escalas-integracao-db) e é apagado e recriado a cada execução. Por segurança, os testes só aceitam banco com "Integracao" no nome — nunca tocam a produção (porta 4450/1433). npm run integracao:banco:derrubar remove o container.

Para conferir telas no navegador com dados de exemplo, sem tocar na produção:

npm run integracao:servidor

Abra http://127.0.0.1:4480 (login admin / Admin!Integracao1).

Prova de equivalência em refatorações grandes

tests/integracao/golden-master.js executa um roteiro fixo por todas as rotas de dados e fotografa todas as tabelas. Gere antes da mudança e compare depois (no mesmo dia):

node tests/integracao/golden-master.js gerar antes.json

node tests/integracao/golden-master.js comparar antes.json

Robô de testes de tela (Playwright)

npm run e2e:demo

Clica aleatoriamente pelas telas da demo (sem backend). Para rodar contra uma instância com banco, use npm run teste:subir e npm run e2e:teste (detalhes em docs/ROBO-DE-TESTES.md).

Código morto no frontend

npm run analisar:codigo-morto

Junta os imports de todos os módulos do frontend e acusa exports que nenhum módulo importa (o ESLint já pega o que nem é exportado) e imports de algo que o módulo de destino não exporta — que no navegador impediria a página de carregar. Roda dentro do npm run verificar.

Comparação A/B do frontend

Antes de refatorar uma tela, tests/e2e/comparar-ab/ roda o mesmo roteiro (todas as telas, editar, excluir, relatórios) na demo de um commit anterior e na atual e compara texto, formulários e erros passo a passo. O passo a passo está no cabeçalho do roteiro.js.

Estrutura do código

backend/
  server.js            sobe e derruba o servidor HTTP
  app.js               aplicação Express: portões (banco pronto, login,
                       permissão), rotas, tratamento de erro
  routes/              uma rota por recurso; coordena, não calcula
  services/            regras de negócio (escala, banco de horas, plantões,
                       backup/, horas-em-carteira, exclusão de colaborador...)
  auth/                sessões, permissões, limite de setores, rate limit
  db/                  conexão, transação, bootstrap do schema
  lib/                 validação, domínio, erros, CORS, IP, cabeçalhos
database/migrations/   scripts SQL, cada um aplicado uma vez por banco
                       (registro em dbo.SchemaMigrations)
frontend/              HTML/CSS/JS sem bundler, em módulos ES nativos
  js/main.js           ponto de entrada (<script type="module">)
  js/core/estado.js    estado compartilhado entre as telas
  js/core/acoes-html.js funções chamadas por onclick="..." (as únicas em window)
demo/                  modo demonstração (mock da API) usado pelo robô
tests/unit|integracao|e2e

A auditoria técnica completa, com o que foi corrigido e o que está pendente, está em AUDITORIA.md.

Implantação

O modelo é um servidor central na rede; o time acessa pelo navegador, sem instalar nada. Na máquina servidor (Windows, com SQL Server Express instalado e a pasta do app em C:\CentralEscalas, fora do OneDrive):

1. dois cliques em INSTALAR-SERVIDOR.cmd;
2. responda a senha do banco e a do admin;
3. passe para o time o endereço que aparece no final (http://IP:4450) e o CRIAR-ATALHO.cmd, que cria em cada computador o ícone que abre o sistema em janela própria (dois cliques, sem instalar nada).

O instalador prepara o SQL Server, grava a configuração, liga o backup automático e registra o sistema para subir junto com o Windows, sem ninguém logar. Versão nova: dois cliques em ATUALIZAR-SERVIDOR.cmd (faz backup antes). Passo a passo e problemas comuns: docs/SERVIDOR-COMO-INSTALAR.md. Guia do time (acesso e ícone do app): docs/README-TIME.md.

O Docker (docs/DOCKER.md) continua como alternativa, ao custo da máquina virtual do WSL 2.

Login e primeiro acesso

A partir da versão 1.3.0 o sistema exige login. Na primeira execução com um banco novo, se a tabela Usuarios estiver vazia, um administrador é criado automaticamente:

• Usuário: valor de ADMIN_USERNAME (padrão admin)
• Senha: valor de ADMIN_PASSWORD se definido no .env (mínimo de 8 caracteres); caso contrário — ou se for curta demais — uma senha aleatória é gerada e exibida uma única vez (na tela de configuração inicial ou no console do servidor), com troca obrigatória no primeiro login.

Enquanto a senha provisória não for trocada, o servidor recusa as rotas de dados. Para trocar a senha é preciso informar a senha atual; a troca encerra as outras sessões abertas da conta.

Com um proxy reverso na frente do app (nginx, IIS), configure TRUST_PROXY para o limite de tentativas de login enxergar o IP real do cliente (ver .env.example).

Veja .env.example para ADMIN_USERNAME, ADMIN_PASSWORD e a lista de origens liberadas em CORS_ORIGINS.

Configuração inicial do banco

A partir da versão 1.5.0, numa máquina sem banco configurado (sem backend/config/database.local.json e sem .env), abrir o sistema no navegador mostra direto a tela Configuração inicial: informe servidor, instância, banco e credenciais do SQL Server, teste e salve. O sistema cria as tabelas e o administrador na hora — sem editar nenhum arquivo. Depois de configurado, tudo volta a exigir login.

Usuários do sistema

Administradores gerenciam contas em Configurações → Usuários: criar usuário (com senha temporária e troca obrigatória no primeiro acesso), ativar/desativar, promover/remover administrador e resetar senha. Usuários comuns não veem essa tela. O sistema impede desativar ou rebaixar a própria conta e o último administrador ativo.

Uma conta pode ter setores permitidos: nesse caso ela só vê colaboradores desses setores — e as ausências, plantões, banco de horas, jornadas e folgas deles — em todas as telas e na API.

Backup

Em Configurações → Banco de dados é possível gerar backups na pasta do servidor, agendar backups automáticos e restaurar um arquivo. Exportar Dados baixa o mesmo backup completo; Importar Dados restaura o sistema a partir dele. Antes de restaurar, um backup de segurança do estado atual é salvo automaticamente. O arquivo de backup não contém contas nem sessões. Em Manter os últimos backups automáticos dá para limitar quantos backups automáticos ficam na pasta (0 = todos); só os automáticos (backup-escalas-auto-*.json) são apagados, nunca os manuais nem os de segurança.

Atualização

1. Atualize os arquivos do projeto (git pull)
2. Suba novamente:
   • Servidor instalado pelo INSTALAR-SERVIDOR.cmd: dois cliques em ATUALIZAR-SERVIDOR.cmd (faz backup, atualiza e confere sozinho)
   • Com Docker: docker compose up -d --build (o --build é o que leva as mudanças de backend para dentro da imagem)

As configurações de banco e backup ficam em backend/config/, fora do código, e não são afetadas pela atualização.

Versionamento

Versão atual: 1.7.0. O histórico completo fica em CHANGELOG.md. Segue SemVer: correção (1.0.1), funcionalidade (1.1.0), mudança que quebra fluxo (2.0.0).

Desde a versão 1.4.0 o sistema deixou de ser distribuído como aplicativo desktop (Electron/.exe). O modelo atual é um servidor web acessado pelo navegador.

Documentação

• docs/SERVIDOR-COMO-INSTALAR.md — montar o servidor central
• docs/README-TIME.md — guia do time (acesso e instalação do app)
• CONTRIBUTING.md — fluxo de branches, commits e testes
• SECURITY.md — política de segurança
• CHANGELOG.md — histórico de versões

Licença

Software proprietário — uso interno, todos os direitos reservados. Veja LICENSE.

Autor

Fernando Maffei