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
- 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):
- dois cliques em
INSTALAR-SERVIDOR.cmd;
- responda a senha do banco e a do admin;
- 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
- Atualize os arquivos do projeto (
git pull)
- 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
Licença
Software proprietário — uso interno, todos os direitos reservados. Veja LICENSE.
Autor
Fernando Maffei
