[ifelipelima]

Descrição

Implementação do fluxo completo de ocupação e movimentação de grupos entre terrenos, mantendo o histórico das movimentações e controlando o ciclo de ocupação, descanso e liberação dos terrenos.

A Occupation representa o período em que um grupo permaneceu em determinado terreno, utilizando started_at e ended_at. A ocupação atual é identificada pela ausência de ended_at, simplesmente.

Principais alterações

• Adiciona a entidade Occupation, relacionando Group e Terrain.
• Garante apenas uma ocupação ativa por grupo e por terreno através de índices únicos parciais.
• Implementa a primeira ocupação e a movimentação entre terrenos através do mesmo fluxo.
• Ao realizar uma movimentação:
  • encerra a ocupação anterior, quando existente;
  • inicia o período de descanso do terreno anterior;
  • cria a nova ocupação;
  • atualiza o terreno de destino para occupied.
• Permite movimentação para terrenos available ou resting.
• Impede movimentações para terrenos ocupados, inativos ou para o próprio terreno atual.
• Integra a inativação de grupos ao fluxo de ocupações, encerrando automaticamente uma ocupação ativa.
• Impede a inativação de terrenos que estejam ocupados.
• Adiciona histórico de ocupações por grupo e por terreno.
• Adiciona informações derivadas como grupo atual, terreno atual, última ocupação, dias livres e dias restantes de descanso.
• Implementa a liberação automática de terrenos cujo período de descanso foi concluído.
• Adiciona Sidekiq, Redis e sidekiq-cron para executar a verificação dos terrenos em descanso a cada 12 horas.

Estrutura adotada no módulo

Service Objects

As operações do domínio foram separadas em serviços com responsabilidades específicas.

Entre eles:

• Occupations::Open
• Occupations::Close
• Occupations::Move
• Terrains::Occupy
• Terrains::StartRest
• Terrains::Release
• Terrains::ReleaseResting

O Occupations::Move atua como orquestrador da movimentação, reutilizando os serviços menores para abertura e encerramento das ocupações e transições dos terrenos.

Policy Object

Foi criado o Occupations::MovementPolicy para concentrar as regras que determinam se uma movimentação pode ser realizada.

A policy valida situações como grupo ou terreno inativo, destino já ocupado e tentativa de movimentação para o mesmo terreno, mantendo essas verificações separadas da execução da movimentação.

Background Job

Foi criado o Terrains::ReleaseRestingJob para executar periodicamente a verificação dos terrenos em descanso.

O job delega a regra de negócio para Terrains::ReleaseResting, enquanto Sidekiq e sidekiq-cron ficam responsáveis apenas pela execução assíncrona e pelo agendamento a cada 12 horas.

Consistência das movimentações

As movimentações são executadas dentro de transações e utilizam locks nos registros envolvidos.

Além disso, restrições no PostgreSQL impedem que existam simultaneamente duas ocupações ativas para o mesmo grupo ou para o mesmo terreno.

Endpoint de movimentação

POST /api/v1/occupations

O mesmo endpoint é utilizado tanto para a primeira ocupação de um grupo quanto para movimentações posteriores entre terrenos.

Não existe um fluxo separado de movimentação forçada no backend. Terrenos em descanso podem receber uma nova ocupação através do mesmo endpoint, ficando a confirmação dessa decisão sob responsabilidade da interface.