Pular para o conteúdo principal

Feature: Recuperação de Aula ao Vivo

Visão geral​

Feature de curso que habilita janela de recuperação de presença para encontros coletivos já encerrados. Quando ativa, o backend calcula prazo por turma/atividade e permite registrar presença de recuperação para o usuário logado.

Atores​

  • Participante (subscriber).
  • Facilitador/supervisor/administrador.
  • Admin de curso (configura flags e vídeos de recuperação).

Pré-condições​

  • Curso com is_recovery_enabled = 1. Fonte: we-dhedalos/functions/acfs/group_663b721c7c208.php.
  • Configuração de recuperação no curso com recovery_hours e opcionalmente recovery_videos. Fonte: we-dhedalos/functions/acfs/group_68810c2e9d8f1.php.
  • Turma vinculada a ciclo com collective_meetings e collective_meeting_time_slot. Fonte: we-dhedalos/functions/rest/cycles.php, we-dhedalos/functions/rest/classes.php.
  • Usuário autenticado para os endpoints de recuperação.

Fluxo principal​

  1. Cliente consulta status em GET /dhedalos/v1/cycles/recovery-status com class_idd.
  2. API identifica última atividade coletiva já encerrada no ciclo da turma.
  3. API verifica se o usuário já possui presença nessa atividade.
  4. API calcula prazo final de recuperação com base em recovery_hours + collective_meeting_time_slot.
  5. API retorna presence_confirmed ou presence_missing, com recovery_deadline, recovery_expired e time_remaining.
  6. Se elegível, usuário chama POST /dhedalos/v1/class/{class_id}/recovery-presence/{activity}.
  7. API grava post presence com metadados recovery_presence = true e reason.

Fluxos alternativos​

  • Usuário não logado em cycles/recovery-status: 401. Fonte: we-dhedalos/functions/rest/cycles.php (permission callback da rota).
  • class_idd ausente: 400 (invalid_class). Fonte: we-dhedalos/functions/rest/cycles.php:get_recovery_status.
  • Sem matrícula ativa na turma: 404 (no_active_enrollment).
  • Sem ciclo ou sem encontros coletivos: 404 (cycle_not_found / no_collective_meetings).
  • Em recovery-presence: turma inexistente, aluno fora da turma, fora de período permitido ou atividade inválida retornam 403. Fonte: we-dhedalos/functions/rest/classes.php:set_recovery_presence.

Regras de negócio​

  • Janela de recuperação depende de:
    • horário inicial por turno da turma;
    • duração de encontro coletivo (collective_meeting_time_slot);
    • horas adicionais configuradas em recovery_hours. Fonte: we-dhedalos/functions/rest/cycles.php:get_recovery_status, we-dhedalos/functions/rest/classes.php:get_recovery_deadline_data.
  • Vídeo de recuperação é selecionado por índice da última atividade coletiva em recovery_videos. Fonte: we-dhedalos/functions/rest/cycles.php:get_recovery_status.
  • Endpoint classes/subscriber passa a retornar:
    • has_pending_recovery;
    • has_expired_recovery (status e activity). Fonte: we-dhedalos/functions/rest/classes.php:get_classes_participant.
  • Controle de exibição de expiração usa usermeta.modal_recovery_showed para não repetir mesma atividade. Fonte: we-dhedalos/functions/rest/classes.php:has_expired_recovery.

Estados possíveis​

  • Curso: is_recovery_enabled = 0|1.
  • Recuperação calculada no status:
    • presence_confirmed
    • presence_missing
    • no_past_meetings
  • Prazo:
    • recovery_expired = false (dentro da janela)
    • recovery_expired = true (fora da janela)
  • Presença:
    • normal (recovery_presence ausente/falso)
    • recuperação (recovery_presence = true)

Endpoints envolvidos​

  • OpenAPI GET /dhedalos/v1/cycles/recovery-status
  • OpenAPI POST /dhedalos/v1/class/{class_id}/recovery-presence/{activity}
  • OpenAPI GET /dhedalos/v1/classes/subscriber

Tabelas/CPTs afetados​

  • model.md curso (is_recovery_enabled, recovery_hours, recovery_videos)
  • model.md ciclo (collective_meetings, collective_meeting_time_slot)
  • model.md presence (recovery_presence, reason)
  • model.md students (relação aluno/turma para elegibilidade)
  • model.md wp_usermeta (modal_recovery_showed)

Pendências/dúvidas​

  • O parâmetro de entrada da rota de status está registrado como class_idd (duplo d), validar se é intencional.
  • A lógica aplica now->modify('-3 hours') no cálculo de prazo; não há justificativa funcional versionada no repositório.
  • Em set_recovery_presence, o student_id é sempre o usuário logado, mesmo que o ator tenha papel administrativo.