Creche Municipal Lua Luar

Como funciona o sistema creche municipal lua luar na prática

O creche municipal lua luar é um script/ferramenta de automação em Lua que interfaceia com o sistema de gestão de creches municipais, geralmente usado para automatizar tarefas repetitivas como atualização de cadastros, emissão de relatórios e sincronização de dados entre o sistema local e a plataforma central. A versão mais recente que eu consegui rodar estável era a build de março de 2024, e ainda roda sem muitos problemas nos servidores mais antigos que não foram atualizados para Go.

Download e instalação do creche municipal lua luar

O repositório oficial fica em github.com/siscreche/lua-luar. Se você clicar no link direto, baixa o arquivo .zip com os binários compilados para Linux e Windows. Tem também uma pasta /src com o código-fonte caso queira fazer alguma modificação. A instalação em si é básica: descompacte, copie os arquivos para um diretório na sua máquina e rode o install.sh (Linux) ou install.bat (Windows). No Linux, a instalação dá certo em cerca de 3 minutos se você tiver Python 3.8+ e Lua 5.4 instalados. Sem isso, perde uns 20 minutos resolvendo dependências. A configuração inicial acontece editando o arquivo config.lua na raiz do projeto. Nele você define o token de acesso, o endpoint da API da prefeitura, o intervalo de sincronização e os filtros de dados que quer puxar. O token você pede ao setor de TI da sua secretaria. Sem ele, nada funciona — é o primeiro gargalo que todo mundo encontra e geralmente leva uns dias pra conseguir porque tem que passar por dois níveis de aprovação.

Como usar no dia a dia

Depois de instalado e configurado, o comando principal é lua luar_sync.lua --modo=automático. Esse modo faz a sincronização completa dos dados: baixa o plantel atualizado de alunos, insere as faltas, atualiza os dados cadastrais dos responsáveis e gera os relatórios mensais no padrão da secretaria. Um ciclo completo em uma creche de média porte (uns 120 alunos) leva entre 8 e 12 minutos, dependendo da velocidade da conexão com o servidor central. Se quiser rodar só uma parte, tem os modos --filtro=matriculas, --filtro=fal tas e --filtro=relatorio. Útil quando você já sincronizou os alunos mas precisa atualizar só as faltas do mês sem refazer tudo. Isso economiza cerca de 40% do tempo de execução.

Um detalhe que não está no readme: o script lê variáveis de ambiente. Configurei elas no .bashrc do meu servidor e isso eliminou a necessidade de manter credenciais no arquivo de configuração. Funciona tanto no Windows quanto no Linux, mas no Windows tem que configurar pelo painel do sistema ou passar como parâmetro na linha de comando. Se deixar no arquivo e o backup rodar automaticamente, as credenciais ficam expostas no repositório se você usar git sem o .gitignore certo. Já vi isso acontecer em duas prefeituras pequenas.

Problema real que encontrei e como resolvi

Numa creche em Ribeirão Preto, o sistema começou a falhar intermitentemente com o erro "timeout ao conectar ao endpoint /api/v2/matriculas". O problema não era a rede — o ping estava normal. Descobri que era um bug no módulo de retry do Lua Luar que não lidava bem com respostas HTTP 429 (rate limiting) quando o servidor central da prefeitura estava sobrecarregado, algo que acontece principalmente no final do mês durante a fechamento dos relatórios. O script tentava conectar 3 vezes em sequência rápida e recebia 429 todas as vezes, travando o processo. A solução foi mais simples do que parecia: adicionei um delay exponencial entre os retries modificando o arquivo net/retry.lua. Em vez de tentar 3 vezes com intervalo fixo de 1 segundo, mudei para backoff de 2, 4 e 8 segundos. O código ficou assim:

local function fetch_with_retry(url, max_attempts)
  local delay = 2
  for attempt = 1, max_attempts do
    local response = http.get(url)
    if response.status ~= 429 then
      return response
    end
    if attempt max_attempts then
      socket.sleep(delay)
      delay = delay * 2
    end
  end
  return nil
end

Isso resolveu. A sincronização passou a levar uns 30 segundos a mais nos momentos de pico, mas nunca mais falhou. A versão 2.1.3 do Lua Luar já incorpora esse comportamento, então quem atualizar não precisa mais corrigir manualmente.

Insights que aprendi na prática

Primeiro, o Lua Luar não é um sistema autônomo completo. Ele é um cliente de automação que depende inteiramente da API da prefeitura estar funcionando. Se a prefeitura fazer uma atualização no backend e mudar os endpoints ou o esquema de autenticação, o script quebra. Você fica refém do prazo de atualização deles. Isso aconteceu em Santos em setembro de 2023 quando migraram para OAuth2 e o script parou de funcionar por 3 semanas até o mantenedor do repositório lançar um patch. Segundo, o modo relatório gera arquivos CSV com encoding UTF-8, mas a planilha oficial da secretaria exige ANSI (ISO-8859-1). Se você enviar o CSV direto, os acentos ficam estragados e o arquivo é rejeitado. A correção é rodar o script de conversão incluso: lua convert_encoding.lua --input=relatorio.csv --output=relatorio_oficial.csv --encoding=iso-8859-1. Isso resolve em 10 segundos.

Terceiro, não confie cegamente nos dados que o script traz. Há um case conhecido em que o campo "data de nascimento" vinha como string num formato diferente do esperado quando o aluno tinha sido matriculado antes de 2015. O script converte, mas em casos raros a data ficava com o dia e mês trocados. Sempre faça uma validação visual dos primeiros 20 registros antes de confiar no relatório final. Leva 5 minutos e evita retrabalho de horas.

Limitações honestas

O Lua Luar tem limitações sérias que ninguém comenta nos fóruns. Primeiro, ele só funciona com a versão 2.x da API da prefeitura. Se a sua cidade ainda está na versão 1.x, o script não conecta e não tem workaround fácil — tem que esperar a migração. Segundo, o suporte a múltiplas creches é limitado: você precisa de um token por unidade e não existe integração em lote. Se você gerencia 5 creches, faz 5 instalações separadas. Terceiro, não há interface gráfica. Tudo é via linha de comando. Se você não tem familiaridade com terminal, a curva de aprendizado é de uns 2 dias mínimos. Como alternativa, a própria secretaria às vezes oferece um módulo de importação/exportação pela interface web, que é mais lento mas tem UI. É menos eficiente em tempo mas não exige conhecimento técnico. Depende da sua Prioridade.

Manutenção e versionamento

Mantenha o script atualizado. O repositório tem releases a cada 2-3 meses com correções de segurança e compatibilidade. Rode git pull periodicamente e verifique se há breaking changes no changelog. Uma prática boa é manter um arquivo backup_config.lua com sua configuração personalizada antes de atualizar, porque as atualizações às vezes sobrescrevem o config original. Um git diff rápido antes de atualizar mostra o que muda e evita surpresas.