Reservas do Espaço no Jardim

O problema do síndico

O condomínio Jardim das Palmeiras tem três espaços que os moradores disputam toda semana: a churrasqueira, o salão de festas e a quadra poliesportiva. Até hoje as reservas eram feitas num grupo de WhatsApp, e sempre rola confusão de dois moradores marcando o mesmo espaço no mesmo horário. O síndico te contratou para construir a API que vai controlar essas reservas de forma organizada.

Os espaços reserváveis

Cada espaço deve ser modelado como uma classe que herda de uma classe base comum EspacoComum, com atributos como nome, capacidade máxima de pessoas e horário de funcionamento. As três subclasses têm regras próprias:

• Churrasqueira: reserva de no máximo 6 horas seguidas e cobra uma taxa fixa de limpeza.
• SalaoDeFestas: reserva de dia inteiro e cobra uma taxa proporcional ao número de convidados informado.
• QuadraPoliesportiva: reserva em blocos de 1 hora e não cobra taxa nenhuma.

Cada subclasse deve sobrescrever um método calcular_taxa() herdado da classe base, cada uma calcula o valor de um jeito diferente, o que exercita polimorfismo na prática. O atributo que guarda o valor da taxa deve ficar protegido por encapsulamento, só acessível através de métodos ou properties, nunca alterado diretamente de fora da classe.

O que a API precisa fazer

• Endpoints para criar, listar, atualizar e cancelar reservas.
• Endpoint para listar moradores e outro para os espaços comuns disponíveis.
• Um endpoint que retorne todas as reservas de um morador específico, cruzando as tabelas de reservas e moradores com um JOIN no banco.
• Toda requisição de criação ou atualização de reserva deve passar por validação de esquema: sem data no passado, sem horário fora do funcionamento do espaço, sem campo obrigatório vazio.
• Todas as respostas devem sair serializadas em JSON, no formato certo para o front-end consumir.

Impedindo choque de horários

Antes de confirmar qualquer reserva nova, a API precisa checar se já existe outra reserva conflitante para aquele espaço naquele intervalo de horário, usando uma consulta SELECT com as condições certas antes de decidir se faz o INSERT. Se houver conflito, a API deve recusar a reserva com uma resposta clara.

Relatório semanal do síndico

Crie uma função geradora (usando yield) que percorre as reservas da semana e vai "entregando" uma linha de relatório por vez, tipo "Segunda-feira: Churrasqueira reservada por Ana das 12h às 18h". Essa função deve alimentar um endpoint que devolve o relatório completo, sem montar a lista inteira na memória de uma vez.

Conceitos técnicos praticados

• POO com classes, objetos, atributos e métodos: modelagem de EspacoComum, Reserva e Morador.
• Herança, polimorfismo e encapsulamento: hierarquia de espaços comuns e cálculo de taxas.
• List e dict comprehensions: filtragem e formatação das reservas antes de retornar nas respostas.
• Generators e yield: geração do relatório semanal sob demanda.
• Ambientes virtuais (venv/Poetry): isolamento das dependências do projeto.
• Fundamentos de HTTP: uso correto de métodos, status codes e headers nas respostas.
• Conceitos de API REST: recursos, endpoints e verbos HTTP bem definidos.
• Framework web em Python: definição de rotas e execução do servidor.
• Validação e serialização: esquemas de entrada e saída das reservas.
• SQL (SELECT, INSERT, UPDATE, DELETE, JOIN): manipulação das tabelas de reservas, espaços e moradores.
• PostgreSQL: persistência dos dados do condomínio.
• Testes unitários com pytest: cobertura das regras de conflito de horário e cálculo de taxas.

Para ir além

• Adicionar um limite de reservas por morador por mês.
• Criar um endpoint que mostre qual espaço é o mais reservado no mês.
• Implementar uma lista de espera simples para quando um horário já estiver ocupado.