Feature: Home

Introdução ao documento

Este documento descreve a home autenticada do hub, que muda conforme o papel do usuário e habilita acessos rápidos para sala, agenda, atividades, quiz, recuperação e links externos. Evidências: src/app/(protected-routes)/home/page.tsx:18-67, src/components/Home/HomeAluno.component.tsx:127-224, src/components/Home/HomeFacilitador.component.tsx:83-163.

Versionamento

• Documento criado em 2026-03-20.
• Revisar quando mudarem home/page.tsx, HomeAluno, HomeFacilitador ou StatusService. Evidências: src/app/(protected-routes)/home/page.tsx:18-67, src/components/Home/HomeAluno.component.tsx:47-224, src/components/Home/HomeFacilitador.component.tsx:44-163, src/services/StatusService.ts:31-113.

Referencial teórico

O fluxo foi derivado da página protegida /home, do layout autenticado e dos dois componentes de home por perfil. Evidências: src/app/(protected-routes)/layout.tsx:21-74, src/app/(protected-routes)/home/page.tsx:18-67, src/components/Home/HomeAluno.component.tsx:47-224, src/components/Home/HomeFacilitador.component.tsx:44-163.

Visão geral

• A página exige sessão e redireciona para / quando o usuário não está autenticado. Evidências: src/app/(protected-routes)/home/page.tsx:19-23.
• O backend de tema pode colocar o hub em manutenção. Evidências: src/app/(protected-routes)/home/page.tsx:26-36.
• Participantes e facilitadores recebem dashboards diferentes com cards habilitados por settings e flags da turma. Evidências: src/app/(protected-routes)/home/page.tsx:58-64, src/components/Home/HomeAluno.component.tsx:133-185, src/components/Home/HomeFacilitador.component.tsx:95-149.

Atores

• Participante. Evidências: src/components/Home/HomeAluno.component.tsx:133-223.
• Facilitador e supervisor. Evidências: src/components/Home/HomeFacilitador.component.tsx:95-149.
• Serviços externos de turma, tema, agenda e recuperação. Evidências: src/app/(protected-routes)/home/page.tsx:25-55, src/services/StatusService.ts:46-90.

Pré-condições

• Sessão válida. Evidências: src/app/(protected-routes)/home/page.tsx:19-23.
• Dados de tema e de turma acessíveis. Evidências: src/app/(protected-routes)/home/page.tsx:25-27, src/app/(protected-routes)/layout.tsx:29-40.
• classId e classesData carregados no contexto para renderização client-side. Evidências: src/app/providers/UserProvider.tsx:86-139, src/components/Home/HomeAluno.component.tsx:114-118, src/components/Home/HomeFacilitador.component.tsx:58-60.

Fluxo principal

1. O servidor valida sessão, identifica papel do usuário e carrega settings. Evidências: src/app/(protected-routes)/home/page.tsx:19-27.
2. Se calendário estiver habilitado para o perfil, a página tenta localizar ou criar o usuário da agenda pelo CPF. Evidências: src/app/(protected-routes)/home/page.tsx:38-55.
3. A home renderiza HomeFacilitador para admin/supervisor e HomeAluno para participante. Evidências: src/app/(protected-routes)/home/page.tsx:58-64.
4. Os cards exibem links rápidos condicionados por flags de turma e tema. Evidências: src/components/Home/HomeAluno.component.tsx:133-185, src/components/Home/HomeFacilitador.component.tsx:95-149.

Fluxos alternativos

• Se settings.maintenance_mode estiver ativo, a home bloqueia o acesso com NotifyModal. Evidências: src/app/(protected-routes)/home/page.tsx:28-36.
• Se a turma tiver recuperação pendente, a home do participante exibe MeetingRecoverCard. Evidências: src/components/Home/HomeAluno.component.tsx:188-223.
• Se houver recuperação expirada ainda não mostrada, a home abre MeetingRecoverModal e marca has_expired_recovery_shown. Evidências: src/components/Home/HomeAluno.component.tsx:58-79, src/components/Home/HomeAluno.component.tsx:214-223.

Regras de negócio

• O card de sala ao vivo só aparece quando enable_room estiver ativo no tema e não estiver desabilitado na turma. Evidências: src/components/Home/HomeAluno.component.tsx:133-143, src/components/Home/HomeFacilitador.component.tsx:96-107.
• O card de mentorias/agenda só aparece quando enable_calendar estiver ativo no tema e na turma. Evidências: src/components/Home/HomeAluno.component.tsx:145-154, src/components/Home/HomeFacilitador.component.tsx:108-118.
• O card de atividades só aparece quando há atividades estratégicas habilitadas ou recuperação habilitada, conforme o perfil. Evidências: src/components/Home/HomeAluno.component.tsx:118-123, src/components/Home/HomeAluno.component.tsx:156-165, src/components/Home/HomeFacilitador.component.tsx:62-67, src/components/Home/HomeFacilitador.component.tsx:119-129.
• O card de quiz do participante usa o courses.slug da turma quando disponível. Evidências: src/components/Home/HomeAluno.component.tsx:123-125, src/components/Home/HomeAluno.component.tsx:177-185.

Estados possíveis

• manutencao: bloqueio da home. Evidências: src/app/(protected-routes)/home/page.tsx:28-36.
• participante: home com mentorias, atividades, jornada, quiz e recuperação. Evidências: src/components/Home/HomeAluno.component.tsx:127-224.
• facilitador: home com sala, agenda, gestão de atividades, turmas e quiz. Evidências: src/components/Home/HomeFacilitador.component.tsx:83-163.

Endpoints envolvidos

• Ver OpenAPI: GET /api/classes, GET /api/class/{id}, GET /api/cycles/recovery-status, GET /api/submissions, GET /api/submissions/status-sumary.
• A criação de usuário de agenda ocorre por serviço externo, sem rota App Router local dedicada nesta página.

Evidências: src/app/(protected-routes)/home/page.tsx:25-55, src/services/StatusService.ts:46-90, src/components/Home/HomeFacilitador.component.tsx:52-71.

Dados impactados

• Ver model.md: Class, Cycle, Submission, MeetingRecover e estado de turma atual no contexto.
• A home também altera o estado client-side has_expired_recovery_shown. Evidências: src/components/Home/HomeAluno.component.tsx:64-79.

Pendências

• O schema exato de settings e dos blocos participant/facilitator não está formalizado em documentação externa.
• A home depende de vários links externos via HomeLinks, mas o contrato desses links não está centralizado em um documento único.