BCANGST
Arroio do Sal · RS
← Caderno aberto05 NOV 2026 · DIÁRIO DE DESENVOLVIMENTO
O projeto avançou. Este é o registro histórico do primeiro núcleo. Leia a continuação de 9 de novembro: SlotGuard: do núcleo Python à primeira demonstração pública →
SLOTGUARD / ENGINEERING LAB / 01

Um horário.
Duas tentativas.
Uma regra clara.

Hoje avancei no primeiro núcleo do SlotGuard. Um problema pequeno de agendamento virou um exercício de modelagem, testes e decisões que precisam continuar fazendo sentido quando o projeto crescer.

43testes aprovados
Pythonnúcleo funcional
3 fasesplanejadas a seguir

Comecei com uma pergunta simples: o que acontece quando alguém tenta reservar um horário que já está ocupado?

O SlotGuard é meu laboratório para investigar essa pergunta em diferentes tecnologias. Nesta primeira etapa, trabalhei no núcleo Python: representar horários, reconhecer sobreposições e criar uma nova agenda quando uma reserva pode ser aceita.

Este texto registra o estágio de hoje. A base já permite experimentar as regras e verificar seus resultados. As próximas etapas vão levar esse mesmo problema para TypeScript, Java e Quarkus.

Primeiro, tornar o problema visível.

Uma reserva das 09h às 10h bloqueia outra das 09h30 às 10h30. Mas deixa livre uma reserva que começa exatamente às 10h. Essa fronteira importa: terminar e começar no mesmo instante não significa ocupar o mesmo intervalo.

SLOTGUARD EM VÍDEO / ETAPA 01

Veja esta etapa em vídeo

O primeiro núcleo Python: conflitos, intervalos consecutivos, imutabilidade e TDD.

Narração sintética masculina em português e legendas visíveis. Registro histórico da primeira etapa. A interface e a API aparecem no segundo registro.

Ler a transcrição

Como um sistema decide se pode aceitar uma reserva? Foi com essa pergunta que comecei o SlotGuard.

Uma reserva ocupa das nove às dez da manhã. Outra, das nove e meia às dez e meia, precisa ser rejeitada.

Mas uma reserva das dez às onze pode ser aceita. O fim de um intervalo não ocupa o início do próximo.

O núcleo usa horários em minutos e modelos imutáveis. Os intervalos têm duração positiva e ficam dentro de um único dia.

Ao aceitar uma reserva, o domínio devolve uma nova agenda. A agenda anterior continua intacta, e o conflito sinaliza um erro.

O desenvolvimento avança em pequenos ciclos de testes. Primeiro observo a falha. Depois implemento, verifico e reviso.

Esta primeira etapa reúne quarenta e três testes automatizados. Exemplos e testes de propriedades verificam limites e preservação da agenda.

Nesse registro, ainda não havia interface, API ou persistência. A proposta era consolidar o domínio antes de conectar novas camadas.

No artigo, compartilho o processo, as decisões e os próximos passos. Essa base abre caminho para a segunda etapa do SlotGuard.

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.

01 / A REGRA EM CENAILUSTRAÇÃO DO COMPORTAMENTO PYTHON

Onde um horário termina,
outro pode começar.

Cliente A09:00–10:00 · Confirmado
Reserva existente
Cliente B09:30–10:30 · Rejeitado
Sobreposição
Cliente C10:00–11:00 · Disponível
Sem conflito

A linha do tempo é uma explicação visual dos casos do núcleo. O simulador TypeScript será uma etapa futura.

O trabalho de hoje,
por dentro.

01

Representar o domínio

Intervalo guarda início e fim em minutos desde a meia-noite. Agenda reúne as reservas em uma tupla. Os dois modelos usam dataclasses imutáveis, com frozen=True e slots=True.

02

Definir os limites

Os horários precisam ser números inteiros, ter duração positiva e ficar entre 0 e 1440 minutos. A validação também rejeita tipos inválidos na criação dos modelos.

03

Separar as perguntas

tem_conflito compara dois intervalos; existe_conflito percorre a agenda; esta_disponivel responde sobre a possibilidade de reservar; agendar aplica a decisão.

04

Preservar a agenda anterior

Uma reserva aceita retorna uma nova Agenda com as reservas anteriores e o novo intervalo. A original permanece intacta. Quando há conflito, HorarioIndisponivelError sinaliza a rejeição.

O avanço foi transformar uma regra intuitiva em um comportamento explícito, que pode ser testado e explicado.

Testar também o que eu não pensei em escolher.

A suíte combina exemplos com pytest e testes baseados em propriedades com Hypothesis. Além dos casos escritos à mão, o Hypothesis gera combinações de intervalos para verificar propriedades do domínio e do agendamento.

Os testes cobrem validações, sobreposições, disponibilidade e a preservação da agenda original. Na conferência desta publicação, os 43 testes passaram, executados numa cópia do código local.

python -m pytest -q
...........................................
43 passed

Qualidade também faz parte da entrega.

O projeto ganhou configuração de Ruff para formatação e verificações de código, BasedPyright para análise estática de tipos e um fluxo de verificação no GitHub Actions. A documentação registra o propósito, os exemplos, a estrutura e os limites da implementação.

A passagem pelo analisador trouxe ajustes concretos: organizar imports, uniformizar formatação e explicitar retornos descartados nos testes. As validações de tipos em tempo de execução continuam importantes mesmo com anotações estáticas.

O resultado de testes apresentado aqui foi conferido localmente. A configuração de integração contínua é parte do projeto; sua execução remota não é atestada por esta publicação.

03 / O MESMO PROBLEMA, NOVAS PERGUNTAS

Uma base para
continuar aprendendo.

01 · IMPLEMENTADO

Python

Modelos, validação, conflitos, disponibilidade e agendamento. Testes de exemplos e propriedades.

02 · PLANEJADO

TypeScript

Construir um simulador visual para experimentar as regras e tornar os casos de uso mais claros.

03 · PLANEJADO

Java

Reimplementar o domínio e comparar modelagem, contratos e tipagem em outra linguagem.

04 · PLANEJADO

Quarkus

Evoluir para uma API e investigar persistência, transações e solicitações simultâneas.

O limite faz parte do registro.

Hoje o núcleo trabalha com intervalos dentro de um único dia, em memória. Ainda não há persistência, API, interface de reservas ou controle transacional para duas solicitações simultâneas. Detectar conflitos numa agenda recebida é uma parte do problema; garantir exclusividade sob concorrência será outra.

A versão Python é o primeiro recorte funcional de um projeto em evolução. Publicar esse processo me ajuda a mostrar o que estou fazendo, quais decisões tomei e quais perguntas permanecem abertas.

Quero que este blog também sirva para isso: acompanhar o trabalho real, as experiências e o aprendizado à medida que acontecem.