Pular para o conteúdo
~/rafael-ferreira

Dois pacientes, um horário: como o Markmedi evita agendamento duplicado

Reserva temporária do horário, lock pessimista por clínica, chave de idempotência e testes de corrida contra MySQL de verdade: como resolvi a concorrência na agenda do Markmedi.

7 min de leitura #markmedi #laravel #mysql #concorrencia

Toda agenda online tem o mesmo pesadelo: duas pessoas olham o mesmo horário livre, as duas clicam em "confirmar" no mesmo segundo e a clínica descobre na segunda-feira de manhã que tem duas pacientes marcadas para as 9h com a mesma médica. No Markmedi isso fica mais delicado, porque o horário não é só a agenda do profissional. Uma consulta pode reservar uma sala e um equipamento, pode ser presencial ou teleconsulta, e a recepção também marca, remarca e faz check-in pelo painel enquanto o paciente agenda pela página pública.

Neste artigo conto como o problema foi resolvido em camadas, por que não confiei em uma única defesa e como provo que funciona.

Três camadas: reserva temporária de 15 minutos, transação com lock que decide e chave de idempotência

Por que um índice único não resolve

A primeira ideia de quase todo mundo é um índice único em (doctor_id, scheduled_at). Ele pega o caso mais óbvio, duas consultas começando exatamente no mesmo minuto, e deixa passar todo o resto. Consultas têm duração variável: uma avaliação de 30 minutos às 9h00 e um procedimento de 60 minutos às 9h15 não colidem no índice e colidem na vida real. Também existem bloqueios de agenda, eventos vindos do Google Agenda, consultas já em andamento que passaram do horário previsto e recursos físicos compartilhados entre médicos.

A pergunta certa é se dois intervalos se sobrepõem, e isso o MySQL não consegue garantir com um índice comum (não há exclusion constraint como no PostgreSQL). Então a garantia precisa vir de serialização: só uma transação por vez pode decidir sobre a agenda de uma clínica.

Linha do tempo: avaliação das 9h00 às 9h30 e procedimento das 9h15 às 10h15 se sobrepõem, mas o índice único não detecta

Camada 1: a reserva temporária do horário

Na página pública, o paciente escolhe o horário e ainda preenche dados, responde perguntas e às vezes paga. Para a experiência não virar uma corrida, quando ele escolhe o horário o sistema cria uma reserva de 15 minutos ligada a um token de sessão aleatório. Enquanto a reserva existe, aquele horário some da lista para os outros visitantes. Se alguém tenta reservar um horário já reservado, recebe um 409 e a interface oferece outro.

Essa reserva é deliberadamente consultiva. Ela melhora a experiência e reduz conflito, mas não é a fonte da verdade. Reservas expiradas são limpas por um comando agendado a cada minuto, e as rotas de reservar, liberar e agendar têm limite de requisições.

Camada 2: a decisão final acontece sob lock

A gravação do agendamento roda dentro de uma transação com retentativa automática em caso de deadlock. A primeira coisa que ela faz é travar os recursos da clínica com SELECT ... FOR UPDATE, sempre na mesma ordem: a linha da clínica, depois os médicos ordenados por id, depois as salas e os equipamentos.

DB::transaction(function () use ($clinic, $data) {
    $this->lockResources->execute($clinic); // clínica, médicos, salas, equipamentos

    if (! $this->window->isFree($data->doctor, $data->start, $data->end)) {
        throw new SlotTakenException(); // vira 409 para o cliente
    }

    return Appointment::create([...]);
}, attempts: 3);

Travar a linha da clínica funciona como um mutex por tenant. Duas clínicas diferentes nunca esperam uma pela outra, e dentro da mesma clínica as decisões sobre agenda ficam em fila. A ordem fixa dos locks é o que evita deadlock entre, por exemplo, uma remarcação e um check-in que precisam dos mesmos recursos. A ação que faz o lock também se recusa a rodar fora de uma transação: se alguém chamar sem transação, ela lança exceção em vez de dar uma falsa sensação de segurança.

Duas transações disputam o lock da clínica: a primeira grava, a segunda espera, revalida e recebe 409

Já sob o lock, o sistema verifica de novo se a janela está livre. A regra de sobreposição é a clássica, início_a < fim_b e fim_a > início_b, aplicada contra consultas que ainda ocupam a agenda (canceladas e faltas não contam), bloqueios (inclusive os que atravessam a meia-noite) e intervalos ocupados no calendário externo do médico. Para consultas em andamento, conta o tempo real: se a consulta começou atrasada, o fim considerado é o início real mais a duração, e nunca antes de agora.

Existe uma verificação antes da transação também, fora do lock, só para devolver erro rápido no caso comum. Ela não substitui a de dentro.

O preço também pode mudar no meio do caminho

Uma corrida menos óbvia é de preço. O paciente vê um valor, e enquanto ele preenche o formulário a clínica muda a tabela ou o horário passa a ter outro valor. O cliente envia a versão da cotação que viu, e dentro da transação o sistema confere se ela ainda é a vigente. É concorrência otimista aplicada a um dado que não precisa de lock: se a versão mudou, o agendamento é recusado e a tela mostra o valor novo.

Camada 3: idempotência para cliques duplos e redes ruins

O terceiro problema é o mesmo paciente criando dois agendamentos. Duplo clique, botão "voltar", rede móvel que reenvia a requisição. Para isso, o cliente gera uma chave de requisição e o servidor deriva um contexto com HMAC a partir de quem está agendando (o usuário da equipe, ou o visitante e sua sessão). O servidor também guarda um hash do payload canônico, com as chaves ordenadas.

  • Se a mesma chave chega de novo com os mesmos dados, o servidor devolve o agendamento que já existe, com o mesmo comprovante.
  • Se a mesma chave chega com dados diferentes, a resposta é 409, porque isso indica erro do cliente.

A checagem acontece antes e de novo dentro da transação, e o banco tem a palavra final com um índice único em (clinic_id, contexto, chave). Um teste de jornada pública confirma que repetir a requisição devolve o mesmo comprovante e deixa exatamente um agendamento e um paciente no banco.

O mesmo padrão em todas as ações da agenda

Agendar é só uma das portas. Remarcar, iniciar atendimento, mudar status, fazer check-in, reservar sala e aplicar mudanças que chegam do Google Agenda seguem a mesma receita: transação com retentativa, lock dos recursos da clínica, lock da própria consulta e revalidação. Iniciar um atendimento, por exemplo, devolve 409 se o médico já tem outra consulta em andamento. As mudanças de status passam por uma máquina de estados em enum, então uma consulta concluída não volta a ficar "agendada" por uma requisição atrasada.

Algumas garantias moram no banco porque ali elas são simples: cada consulta tem no máximo uma reserva de recursos, salas e equipamentos usam chaves compostas com clinic_id para nunca apontar para outro tenant, e a fila de espera usa uma coluna anulável como marcador de "registro ativo" dentro de um índice único, o que garante no máximo uma entrada ativa por paciente.

Como eu provo que funciona

Teste de concorrência com SQLite em memória não prova nada, porque não há duas conexões disputando lock. Por isso escrevi um harness que cria um banco MySQL descartável, roda as migrations e dispara workers com pcntl_fork. Cada worker abre a própria conexão, espera numa barreira no sistema de arquivos e, quando a barreira abre, todos executam a mesma ação ao mesmo tempo. No fim, cada um grava o resultado e o teste confere o placar.

it('only one of two simultaneous starts wins', function () {
    $results = $this->race(workers: 2, fn () => startAppointment($appointmentId));

    expect($results)->toHaveSuccesses(1)->toHaveConflicts(1);
    expect(Appointment::inProgress()->count())->toBe(1);
});

Os cenários cobrem dois inícios simultâneos para o mesmo médico (um sucesso, um 409), check-ins duplicados (uma única entrada na fila de espera e um único evento), disputa pela mesma sala ou equipamento e, como contraprova, unidades diferentes de um equipamento em salas diferentes, onde as duas reservas precisam passar. O mesmo harness cobre carteira do paciente, cashback e vale-presente, onde a corrida é por saldo.

Esses testes formam uma suíte dedicada, que roda sob demanda contra MySQL real e com a extensão pcntl, separada da suíte principal que roda em SQLite. Eu os executo sempre que mexo em lock, transação ou regra de disponibilidade.

O que eu levaria para outro projeto

A lição principal é separar a experiência da garantia. A reserva temporária deixa a interface agradável, a transação com lock é quem decide, e a idempotência protege contra o próprio usuário. Cada camada é simples sozinha, e nenhuma depende de as outras funcionarem. O resto é disciplina: ordem fixa de locks, revalidar sempre dentro da transação e testar com o banco que vai para produção.

Este texto faz parte da série sobre o Markmedi. Depois de gravado, o agendamento dispara eventos de domínio e jobs; isso está em arquitetura, DDD e eventos e em filas com Laravel Horizon.