Pular para o conteúdo principal

Feature: Agendamento

Introdução ao documento​

Este documento cobre o fluxo de agendamento de mentoria: escolha de data, horário, preenchimento de perguntas, confirmação e criação da reserva. Evidências: src/app/(protected-routes)/agendar/[id]/page.tsx:18-79, src/components/Consultorias/Consultorias.component.tsx:123-259, src/components/AppointmentModal/AppointmentModal.component.tsx:78-137.

Versionamento​

  • Documento criado em 2026-03-20.
  • Revisar quando mudarem as páginas /agendar, Consultorias, AppointmentModal ou /api/schedule/appointment/*. Evidências: src/app/(protected-routes)/agendar/page.tsx:7-17, src/app/(protected-routes)/agendar/[id]/page.tsx:18-79, src/app/api/schedule/appointment/create/route.ts:10-77.

Referencial teórico​

O fluxo foi derivado das páginas /agendar e /agendar/[id], do componente de passos Consultorias, do modal de confirmação e do BFF de agenda. Evidências: src/app/(protected-routes)/agendar/page.tsx:7-17, src/app/(protected-routes)/agendar/[id]/page.tsx:35-61, src/components/Consultorias/Consultorias.component.tsx:136-259, src/app/services/bff/ScheduleService.ts:47-80.

Visão geral​

  • /agendar só redireciona o usuário para /agendar/{classId}. Evidências: src/app/(protected-routes)/agendar/page.tsx:7-17.
  • A página detalhada carrega tipo de reunião e agendamentos atuais da turma. Evidências: src/app/(protected-routes)/agendar/[id]/page.tsx:35-43.
  • O fluxo client-side é dividido em 3 passos: data, horário e perguntas. Evidências: src/components/Consultorias/Consultorias.component.tsx:136-149, src/components/Consultorias/Consultorias.component.tsx:170-210.

Atores​

  • Participante agendando mentoria. Evidências: src/app/(protected-routes)/agendar/[id]/page.tsx:27-43.
  • Facilitador associado à turma, resolvido pelo backend. Evidências: src/app/api/schedule/appointment/create/route.ts:38-52.
  • Serviços externos de agenda e turma. Evidências: src/app/services/bff/ScheduleService.ts:47-80, src/app/(protected-routes)/agendar/[id]/page.tsx:35-43.

Pré-condições​

  • Sessão válida. Evidências: src/app/(protected-routes)/agendar/[id]/page.tsx:27-31.
  • classId e classesData presentes no contexto de usuário. Evidências: src/components/Consultorias/Consultorias.component.tsx:77-89, src/components/Consultorias/Consultorias.component.tsx:123-125.
  • O calendário da turma precisa estar habilitado e a lista individual_meetings não pode ser vazia. Evidências: src/components/Consultorias/Consultorias.component.tsx:127-130, src/components/Consultorias/Consultorias.component.tsx:151-164.

Fluxo principal​

  1. O usuário entra em /agendar/{classId}; a página busca meetingType e os agendamentos já existentes. Evidências: src/app/(protected-routes)/agendar/[id]/page.tsx:35-43.
  2. A UI lista datas disponíveis e, ao escolher uma data, busca slots livres. Evidências: src/components/Consultorias/Consultorias.component.tsx:136-144.
  3. O usuário escolhe o horário e avança para o formulário de perguntas. Evidências: src/components/Consultorias/Consultorias.component.tsx:146-149, src/components/Consultorias/Consultorias.component.tsx:204-209.
  4. Ao concluir, o modal valida os campos obrigatórios e chama createAppointment. Evidências: src/components/AppointmentModal/AppointmentModal.component.tsx:78-110.
  5. Em sucesso, a lista local de agendamentos é atualizada e a UI muda para confirmação. Evidências: src/components/AppointmentModal/AppointmentModal.component.tsx:110-120.

Fluxos alternativos​

  • Se classId não existir no contexto, o fluxo fica em Loader. Evidências: src/components/Consultorias/Consultorias.component.tsx:123-125.
  • Se o calendário estiver desabilitado, a feature redireciona para /home. Evidências: src/components/Consultorias/Consultorias.component.tsx:127-130.
  • Se não houver datas de agenda, a UI mostra Não há agendamentos disponíveis.. Evidências: src/components/Consultorias/Consultorias.component.tsx:151-164.
  • Se a página não conseguir carregar os dados da turma/agendamento, exibe NotifyModal. Evidências: src/app/(protected-routes)/agendar/[id]/page.tsx:64-79.

Regras de negócio​

  • A data escolhida sempre limpa o horário previamente selecionado. Evidências: src/components/Consultorias/Consultorias.component.tsx:136-139.
  • Reuniões em grupo usam getAvaliableGroupMeetingsSlots; reuniões individuais usam getAvailableSlots. Evidências: src/components/Consultorias/Consultorias.component.tsx:139-142.
  • O payload final define type_id 4 para grupo e 3 para individual. Evidências: src/components/Consultorias/Consultorias.component.tsx:241-243.
  • O modal bloqueia a criação se faltar main_topic, social_network, specific_questions, class_id, course_name ou start_time. Evidências: src/components/AppointmentModal/AppointmentModal.component.tsx:78-99.
  • O endpoint BFF só cria compromisso se houver sessão, class_id e facilitador para a turma. Evidências: src/app/api/schedule/appointment/create/route.ts:11-22, src/app/api/schedule/appointment/create/route.ts:27-52.

Estados possíveis​

  • carregando: falta de contexto ou consulta em andamento. Evidências: src/components/Consultorias/Consultorias.component.tsx:123-125.
  • selecionando_data: sem consultancyDate. Evidências: src/components/Consultorias/Consultorias.component.tsx:180-183.
  • selecionando_horario: com data definida e sem horário. Evidências: src/components/Consultorias/Consultorias.component.tsx:194-197.
  • preenchendo_perguntas: startTime definido. Evidências: src/components/Consultorias/Consultorias.component.tsx:194-210.
  • confirmado: contentControl invertido no modal de confirmação. Evidências: src/components/AppointmentModal/AppointmentModal.component.tsx:119, src/components/AppointmentModal/AppointmentModal.component.tsx:175-199.

Endpoints envolvidos​

  • Ver OpenAPI: GET /api/schedule/appointment/class/{id}, GET /api/courses/{id}, GET /api/schedule/slot/{slug}/class/{id}, POST /api/schedule/slot, POST /api/schedule/appointment/create, POST /api/schedule/appointment/delete/{id}, POST /api/participant-mode-log.

Evidências: src/app/(protected-routes)/agendar/[id]/page.tsx:35-43, src/app/services/bff/ScheduleService.ts:47-80, src/components/AppointmentModal/AppointmentModal.component.tsx:121-135, src/app/api/participant-mode-log/route.ts:6-50.

Dados impactados​

  • Ver model.md: Appointment, Class, Course, facilitador e contexto de participação.
  • O fluxo também grava logs de modo participante quando isParticipantMode === true. Evidências: src/components/AppointmentModal/AppointmentModal.component.tsx:121-135.

Pendências​

  • O limite máximo de agendamentos simultâneos depende de hooks/client e não está centralizado em um contrato explícito.
  • A política de remarcação/cancelamento aparece em texto de UI, mas não existe documento normativo versionado.