Pular para o conteúdo principal

Feature: Agenda

Introdução ao documento​

Este documento descreve a agenda do facilitador/supervisor: carregamento semanal, agrupamento de compromissos, bloqueios e visualização responsiva de slots. Evidências: src/app/(protected-routes)/agenda/page.tsx:131-155, src/app/providers/ScheduleProvider.tsx:67-209, src/components/Schedule/Schedule.component.tsx:84-167.

Versionamento​

  • Documento criado em 2026-03-20.
  • Revisar quando mudarem ScheduleProvider, Schedule ou as rotas /api/schedule/*. Evidências: src/app/providers/ScheduleProvider.tsx:67-209, src/components/Schedule/Schedule.component.tsx:84-167, src/app/services/bff/ScheduleService.ts:14-80.

Referencial teórico​

O fluxo foi derivado da página /agenda, do contexto ScheduleContext e dos serviços BFF de agenda. Evidências: src/app/(protected-routes)/agenda/page.tsx:131-155, src/app/providers/ScheduleProvider.tsx:49-229, src/app/services/bff/ScheduleService.ts:14-80.

Visão geral​

  • A página monta a experiência com ScheduleProvider e Schedule. Evidências: src/app/(protected-routes)/agenda/page.tsx:139-150.
  • O provider busca a agenda por semana via BFF e normaliza compromissos em ScheduleEvent[]. Evidências: src/app/providers/ScheduleProvider.tsx:67-83, src/app/providers/ScheduleProvider.tsx:86-209.
  • A UI alterna entre visão diária e semanal conforme a largura da tela. Evidências: src/components/Schedule/Schedule.component.tsx:130-147.

Atores​

  • Facilitador e supervisor com calendário habilitado. Evidências: src/components/Schedule/Schedule.component.tsx:119-126, src/app/services/bff/ScheduleService.ts:14-17.
  • Serviço de agenda externo acessado via BFF. Evidências: src/app/services/bff/ScheduleService.ts:14-17.

Pré-condições​

  • Sessão válida na página /agenda. Evidências: src/app/(protected-routes)/agenda/page.tsx:133-137.
  • class_id em localStorage para supervisor quando o endpoint exige turma. Evidências: src/app/providers/ScheduleProvider.tsx:68-83, src/components/Schedule/Schedule.component.tsx:97-103.
  • A turma corrente não pode estar com enable_calendar === false. Evidências: src/components/Schedule/Schedule.component.tsx:119-126.

Fluxo principal​

  1. A página autenticada renderiza ScheduleProvider e Schedule. Evidências: src/app/(protected-routes)/agenda/page.tsx:139-150.
  2. O provider lê class_id do navegador e chama getSchedule(weekNumber, class_id, role). Evidências: src/app/providers/ScheduleProvider.tsx:67-83, src/app/providers/ScheduleProvider.tsx:86-90.
  3. O provider agrupa mentorias em grupo (type_id == 4) e converte os demais compromissos para ScheduleEvent. Evidências: src/app/providers/ScheduleProvider.tsx:98-163, src/app/providers/ScheduleProvider.tsx:165-207.
  4. A UI exibe cabeçalho, slots e loader/erro conforme o estado do contexto. Evidências: src/components/Schedule/Schedule.component.tsx:128-167.

Fluxos alternativos​

  • Se o usuário não tiver sessão, a página atual retorna vazia. Evidências: src/app/(protected-routes)/agenda/page.tsx:133-137.
  • Se o calendário da turma estiver desabilitado, a UI redireciona para /home. Evidências: src/components/Schedule/Schedule.component.tsx:119-126.
  • Se a agenda não puder ser carregada e loading for falso, a UI mostra NotifyModal. Evidências: src/components/Schedule/Schedule.component.tsx:158-165.

Regras de negócio​

  • Supervisores usam endpoint /schedule/calendar/{week}/class/{class_id}; demais perfis usam /schedule/calendar/{week}. Evidências: src/app/services/bff/ScheduleService.ts:14-17.
  • Compromissos de grupo são consolidados por start_time + finish_time + class_id + employee_id. Evidências: src/app/providers/ScheduleProvider.tsx:98-128.
  • Compromissos type_id == 3 desserializam additional_fields para perguntas da mentoria. Evidências: src/app/providers/ScheduleProvider.tsx:182-202.
  • Tipos de agenda são mapeados para Bloqueio, Encontro Coletivo, Mentoria Individual e Mentoria em Grupo. Evidências: src/app/providers/ScheduleProvider.tsx:26-31.

Estados possíveis​

  • loading: busca da agenda em andamento. Evidências: src/app/providers/ScheduleProvider.tsx:56, src/components/Schedule/Schedule.component.tsx:166.
  • carregado: schedule preenchido. Evidências: src/app/providers/ScheduleProvider.tsx:72-74, src/components/Schedule/Schedule.component.tsx:141-156.
  • erro_sem_agenda: schedule vazio e loading falso. Evidências: src/components/Schedule/Schedule.component.tsx:158-165.

Endpoints envolvidos​

  • Ver OpenAPI: GET /api/schedule/calendar/{id}, GET /api/schedule/calendar/{id}/class/{id}, POST /api/schedule/block/{id}, POST /api/schedule/unblock/{id}, POST /api/schedule/appointment/delete/{id}.

Evidências: src/app/services/bff/ScheduleService.ts:14-39, src/app/api/schedule/appointment/delete/[id]/route.ts:6-37.

Dados impactados​

  • Ver model.md: Appointment, GroupAppointment, turma corrente e disponibilidade semanal.
  • O fluxo também depende do class_id persistido no navegador. Evidências: src/components/Schedule/Schedule.component.tsx:97-103.

Pendências​

  • A página /agenda injeta um array events de exemplo, mas a renderização real consome schedule do contexto; o papel desse mock local não está documentado.
  • Não há política explícita de paginação ou retenção de compromissos antigos.