SLOTGUARD / ENGINEERING LAB
Do núcleo Python
à primeira
demonstração pública.
O SlotGuard ganhou uma interface, uma API e um endereço para experimentar. Esta etapa conecta uma regra de agendamento a uma aplicação publicada — com testes, decisões explícitas e espaço para continuar evoluindo.
Demonstração no Render Free: o primeiro acesso após um período sem uso pode demorar cerca de um minuto. A agenda ainda é mantida na memória da página.
SLOTGUARD EM VÍDEO / ETAPA 02
Veja esta etapa em vídeo
Da regra à aplicação: consulta, reserva real, rejeição de conflitos e publicação.
Narração sintética masculina em português e legendas visíveis. Demonstração em evolução: agenda em memória, sem persistência, autenticação ou garantia transacional entre usuários.
Ler a transcrição
O SlotGuard saiu do núcleo de regras e ganhou uma aplicação no ar. Agora você pode consultar, reservar e acompanhar a agenda na tela.
A interface apresenta os horários e conversa com a API. As regras de negócio continuam concentradas no domínio Python.
A agenda começa com uma reserva das nove às dez. Consultar das dez às onze confirma que horários consecutivos são permitidos.
Ao reservar, a API devolve a agenda atualizada. A lista passa a mostrar os dois intervalos, com a confirmação na interface.
Uma nova tentativa para o mesmo horário recebe uma resposta de conflito. A mensagem explica a rejeição, e as reservas aceitas são preservadas.
Durante a reserva, os campos e os dois botões ficam bloqueados. Ao editar horários, a consulta descarta respostas antigas e limpa a mensagem.
A etapa publicada reúne cento e quatorze testes automatizados. Eles cobrem o domínio, a interface e a comunicação com a API real.
Interface e API são empacotadas juntas em um contêiner. O fluxo de verificação testa esse pacote no Linux antes da publicação.
A demonstração está no Render gratuito, mas a agenda ainda fica em memória. Recarregar restaura o início. Persistência e concorrência são os próximos desafios.
Experimente o SlotGuard e conheça as decisões no artigo. O projeto continua evoluindo, um comportamento verificável de cada vez.
Este projeto mostra meu processo de engenharia: entender a regra, escrever testes, integrar as camadas e entregar algo verificável. Se sua empresa enfrenta conflitos de agendamento ou busca desenvolvimento de APIs em Python, podemos conversar sobre o problema e avaliar os próximos passos.
Uma reserva termina às 10h. Outra começa às 10h. O sistema precisa permitir essa sequência. Se a segunda começar às 09h30, precisa reconhecer o conflito.
Foi com esse problema que comecei o SlotGuard, meu laboratório de engenharia de software para estudar agendamentos. No primeiro registro deste diário, apresentei o núcleo Python: intervalos, agendas imutáveis e 43 testes. Agora essa base está conectada a uma interface TypeScript por uma API FastAPI, empacotada em Docker e publicada no Render.
Um problema pequeno, com perguntas que crescem.
A intenção do projeto é exercitar o caminho completo entre uma regra de negócio e uma aplicação que outra pessoa consiga usar. Representar horários, separar responsabilidades, testar as fronteiras, apresentar erros com clareza e publicar um pacote reproduzível são partes desse trabalho.
O SlotGuard também é um portfólio aberto de decisões. O código pode ser consultado, a demonstração pode ser experimentada e os próximos passos são registrados conforme saem do planejamento e passam a funcionar.
Reserve. Tente de novo.
Observe a regra.
A aplicação começa com uma reserva das 09:00 às 10:00. Os campos iniciam em 10:00 e 11:00.
- Consulte 10:00–11:00.O horário deve aparecer como disponível: começar no fim da reserva anterior é permitido.
- Reserve esse intervalo.A confirmação aparece e a agenda passa a mostrar os dois horários.
- Tente reservar 10:00–11:00 novamente.A API rejeita o conflito e a lista mantém as reservas aceitas.
- Recarregue a página.A agenda volta à reserva inicial. Esse é o limite atual de persistência, explicado adiante.
Use horários fictícios. A demonstração não solicita dados pessoais e ainda não representa uma agenda operacional compartilhada.
Python decide.
TypeScript torna visível.
Uma decisão importante desta etapa foi reaproveitar o motor Python. O TypeScript adapta a entrada, faz as chamadas HTTP e apresenta os resultados. As regras de intervalo, disponibilidade e criação de reserva continuam no domínio Python.
Horários editáveis, agenda e mensagens.
Entrada validada, respostas e categorias de erro.
Intervalos imutáveis, disponibilidade e agendamento.
Os horários são representados em minutos desde a meia-noite. O intervalo inclui o início e exclui o fim: [início, fim). Essa convenção explica por que 09:00–10:00 e 10:00–11:00 podem ser consecutivos sem conflito.
O que o contrato HTTP comunica
POST /disponibilidade- Responde se o intervalo está disponível na agenda informada.
201 · Reserva aceitaPOST /reservasdevolve a agenda atualizada.409 · Conflito- O horário está ocupado; as reservas existentes são preservadas.
422 · Entrada inválida- Por exemplo, um intervalo com início e fim iguais.
O cuidado também está na interação.
A agenda aparece em ordem de início, sem modificar a lista recebida. Há orientação para campos vazios, indicação de espera e recuperação após erros. Durante uma reserva, os campos e os dois botões ficam bloqueados até a conclusão.
Durante uma consulta, os campos permanecem editáveis. Ao mudar um horário, a mensagem anterior é limpa. Se a resposta da consulta chegar depois da edição, ela é descartada, inclusive em caso de erro. Isso evita apresentar uma conclusão sobre valores que já mudaram.
Pequenos ciclos.
Evidências acumuladas.
O desenvolvimento seguiu ciclos de TDD: escrever um teste para o próximo comportamento, observar a falha esperada, implementar o necessário, confirmar o resultado e revisar. Quando uma implementação já atendia a um novo cenário, o teste servia para consolidar esse contrato.
A revisão revelou riscos que a primeira versão da interação ainda não cobria: uma resposta atrasada poderia substituir uma mensagem mais recente, e os horários poderiam mudar durante uma reserva pendente. Esses casos viraram testes e orientaram o bloqueio dos controles e o descarte de respostas de consultas antigas.
| Camada | Casos | O que verifica |
|---|---|---|
| Python | 54 | Domínio e HTTP, incluindo a entrega do HTML e do JavaScript. |
| Cliente TypeScript | 17 | Requisições, respostas, erros e validação do JSON recebido. |
| Interface | 38 | Interações, mensagens, agenda e estados durante a espera. |
| Integração real | 5 | Comunicação entre o cliente TypeScript e a API Python. |
| Total | 114 | Casos automatizados aprovados neste checkpoint. |
Os testes Python incluem exemplos e propriedades com Hypothesis. Ruff, BasedPyright e a checagem de tipos TypeScript complementam a suíte. No GitHub Actions, os workflows Python Quality e TypeScript Quality foram concluídos com sucesso no commit desta publicação.
A contagem é uma fotografia da etapa. Seu valor está nos contratos que protege: fronteiras entre horários, preservação da agenda, distinção entre conflito e validação, e comunicação efetiva entre as camadas.
Quero conseguir explicar uma decisão, verificar seu efeito e continuar evoluindo sem perder o que já funciona.
Um link que funciona
com meu computador desligado.
Para publicar, defini uma restrição concreta: uma demonstração acessível, simples de executar e compatível com serviços gratuitos. Essa escolha passou a orientar o empacotamento e a futura persistência.
O Dockerfile tem duas etapas. A primeira usa Node para compilar a interface. A segunda executa a aplicação Python e recebe apenas os arquivos necessários. O mesmo servidor entrega a interface, os arquivos estáticos e as rotas da API.
A construção acontece a partir do repositório, sem copiar minha .venv, meu node_modules ou uma pasta dist preparada à mão. No CI, a imagem é construída no Linux, o contêiner é iniciado, o HTML e a documentação são verificados e os cinco testes de integração voltam a rodar contra essa aplicação empacotada.
O serviço foi publicado no Render Free, com a configuração versionada em render.yaml. As próximas publicações automáticas estão configuradas para aguardar a aprovação do CI. O plano pode suspender a aplicação por inatividade e tem cotas de uso; a proposta atual é uma demonstração de baixo tráfego.
Evidências: Python Quality ↗ · TypeScript Quality e contêiner ↗ · Limites do Render Free ↗
O que a demonstração
ainda não garante.
- Persistência: a agenda fica na memória da página. Recarregar restaura o estado inicial; a API não salva as reservas.
- Agenda compartilhada: cada requisição envia a agenda considerada. Não há sincronização entre abas ou usuários.
- Concorrência: bloquear os botões na tela evita operações sobrepostas naquela interface. Ainda não há garantia transacional contra duas pessoas reservando o mesmo horário ao mesmo tempo.
- Escopo de negócio: os intervalos representam um único dia. Cadastro, autenticação, cancelamento, datas e fusos horários ainda não foram implementados.
- Hospedagem: o plano gratuito pode demorar para responder após inatividade e interromper o serviço ao atingir limites. Esta etapa não oferece garantia de disponibilidade de um sistema comercial.
A próxima etapa começa
com uma fonte confiável para a agenda.
A direção escolhida para persistência é PostgreSQL gerenciado no Neon, mantendo a aplicação no Render. Essa integração está planejada e ainda não foi implementada. O empacotamento e a publicação da versão atual vieram primeiro para validar o caminho de entrega antes de introduzir armazenamento.
Com persistência, a responsabilidade muda: a API precisará carregar a agenda do banco e coordenar verificação e gravação para enfrentar conflitos concorrentes. Também precisaremos definir como as agendas serão identificadas e como separar os dados de demonstração.
Cancelamento é uma evolução possível depois dessa base. Java e Quarkus continuam no horizonte do laboratório para investigar modelagem, contratos, persistência e concorrência em outras tecnologias. São trilhas de estudo, sem prazo ou entrega prometida neste registro.
O objetivo do SlotGuard é tornar cada etapa verificável e compreensível: do algoritmo à interação, da interação à API e da API a uma publicação que outras pessoas possam explorar.
Experimente.
Leia o código.
Converse comigo.
Se você está acompanhando a construção, avaliando meu trabalho ou estudando um problema parecido, a demonstração e o repositório são os próximos pontos de partida. Sugestões sobre a experiência e perguntas sobre as decisões são bem-vindas.
Conversar sobre o projeto →