course-plat/plans/refatoracao-fases.md

Plano de Refatoracao por Fases

Este documento organiza a correcao do projeto em fases pequenas, verificaveis e sem ruptura grande.

Objetivo principal:

• estabilizar build e seguranca
• migrar gradualmente de API Routes para Server Actions
• eliminar conflitos de CSS global (sem !important)
• aproximar o frontend de um estilo tipo shadcn (componentes reutilizaveis + tokens consistentes)

---

Visao Geral das Fases

1. Fase 0 - Baseline e congelamento
2. Fase 1 - Build, auth e seguranca minima
3. Fase 2 - Migracao API -> Server Actions
4. Fase 3 - Reset de CSS global e fim de conflitos
5. Fase 4 - Base de design system estilo shadcn
6. Fase 5 - Refino visual da plataforma de ingles
7. Fase 6 - Limpeza final e hardening

Cada fase tem: escopo, tarefas, definicao de pronto e risco.

Status consolidado (fev/2026)

• Fase 1: concluida.
• Fase 2: concluida nos dominios planejados para fluxo interno (APIs legadas mantidas como fallback temporario).
• Fase 3: concluida no objetivo principal (globals enxuto, sem !important, sem overrides globais agressivos).
• Fase 4: concluida no escopo principal (base ui ativa + login/register + dashboards principais migrados).
• Fase 5: pendente (refino visual mais amplo ainda nao iniciado de forma sistematica).
• Fase 6: em andamento parcial (melhorias de feedback ao usuario e tratamento de erros em fluxos criticos).

---

Fase 0 - Baseline e congelamento

Escopo

Criar um ponto de partida confiavel antes de alterar arquitetura.

Tarefas

• Registrar o estado atual (erros conhecidos, rotas criticas, telas criticas).
• Salvar relatorio de build/lint/testes E2E atuais.
• Definir branch de refatoracao (ex.: refactor/phases).
• Congelar novas features ate concluir Fase 2.

Definicao de pronto

• Baseline documentado e reproduzivel.
• Time alinhado sobre prioridades e ordem de execucao.

Risco

• Baixo. Sem mudanca de codigo de negocio.

---

Fase 1 - Build, auth e seguranca minima

Escopo

Resolver problemas que quebram producao/deploy e vazamentos de autorizacao.

Tarefas

• Corrigir middleware para nao importar auth/db de runtime Edge.
  • Opcao recomendada: middleware apenas para roteamento simples.
  • Verificacao de permissao real fica no server (Server Components/Server Actions).
• Revisar matcher do middleware para incluir rotas protegidas reais (/admin/*, /dashboard/*).
• Garantir bloqueio de acesso nas paginas sensiveis antes de carregar dados.
• Corrigir verificacao de role inconsistente (role vs roles).
• Revisar regra de arquivos legados: negar por padrao quando nao houver metadado de permissao.
• Remover/encerrar fluxo duplicado de auth (uma unica fonte de verdade do NextAuth).
• Padronizar variavel de ambiente do Mongo (MONGODB_URI ou MONGO_URI) e alinhar docs.

Definicao de pronto

• npm run build passa sem erro.
• Rotas protegidas retornam 401/403 corretamente.
• Fluxo de login/logout unico e consistente.

Risco

• Medio. Pode impactar acesso de usuarios se a regra de permissao nao for validada com cuidado.

---

Fase 2 - Migracao API -> Server Actions

Escopo

Migrar gradualmente endpoints de API para Server Actions, priorizando fluxo interno do app.

Principios

• Evitar big-bang. Migrar por dominio funcional.
• Manter API somente quando houver necessidade real externa (webhook, integracao de terceiros, upload streaming, callback externo).
• Toda Action deve validar sessao e permissao no servidor.

Ordem recomendada de migracao

1. Pagamentos
2. Turmas e atribuicoes/provas
3. Arquivos e categorias
4. Usuarios/guardian/wards

Tarefas por dominio (template)

• Criar actions/ por dominio com funcoes server-only.
• Mover validacoes de auth/autorizacao para as Actions.
• Substituir chamadas fetch('/api/...') por invocacao direta de Action.
• Padronizar retorno { success, data, message, fieldErrors }.
• Revalidar cache (revalidatePath/revalidateTag) quando necessario.
• Manter fallback temporario para rotas antigas e remover ao final da fase.

Progresso atual (dominio: Pagamentos)

• Criadas Server Actions de pagamentos e dependentes.
• Auth/autorizacao centralizadas nas Actions de pagamentos.
• Telas de pagamentos de aluno/responsavel migradas de fetch('/api/...') para Actions.
• Formularios de registro de pagamento migrados para Actions.
• Retorno padronizado nas novas Actions (success, data, message, fieldErrors).
• Revalidacao aplicada para dashboards de pagamento apos envio.
• Fluxo admin de pagamentos migrado para Actions (criacao de obrigacao, aprovacao/rejeicao, consulta por obrigacao).
• Fallback temporario mantido: APIs antigas continuam disponiveis por compatibilidade e remocao gradual.

Progresso atual (dominio: Turmas e atribuicoes/provas)

• Criadas Server Actions para fluxo operacional de provas (listar atribuicoes por turma, iniciar tentativa, listar tentativas, detalhar tentativa, corrigir resposta).
• Componentes de aluno migrados para Actions (AvailableExams, TakeExam) sem dependencia de /api/classes/* e /api/assignments/* nesses fluxos.
• Componente de resultados para professor/admin migrado para Actions (ExamResults) sem dependencia de /api/attempts/*.
• Mantido fallback temporario: rotas API de provas continuam existentes para compatibilidade durante transicao.

Progresso atual (dominio: Arquivos e categorias)

• Criada Server Action para carregamento de categorias com migracao de colorIndex quando necessario.
• Formulario de upload de arquivos do admin migrado para Action de categorias, removendo dependencia de /api/categories no cliente.
• Ajuste de navegacao pos-upload para router.push em componentes cliente de upload (evitando uso indevido de redirect).
• Eliminadas chamadas fetch('/api/...') no frontend protegido; fluxo interno agora opera via Server Actions.

Progresso atual (dominio: Usuarios/guardian/wards)

• Criadas Server Actions de usuarios para dependentes (getWardsAction) e listagem admin (getUsersForAdminAction).
• Fluxo de pagamentos do responsavel desacoplado do dominio de pagamentos para usar Action de usuarios no carregamento de dependentes.
• Painel admin de usuarios passou a consumir Action de usuarios (sem dependencia de rota API interna).
• Harden de cadastro de estudante por responsavel: validacao de sessao/role, vinculo seguro de guardian e verificacao de unicidade (email/username).

Definicao de pronto

• Fluxos internos principais sem dependencia de API Route.
• Reducao significativa de codigo duplicado entre page/API.
• Permissoes centralizadas em camada server.

Risco

• Medio/alto. Erros de cache e invalidacao podem causar dados desatualizados.

---

Fase 3 - Reset de CSS global e fim de conflitos

Escopo

Reduzir globals.css ao minimo necessario e eliminar conflitos causados por regras globais.

Regras obrigatorias

• Sem !important.
• Sem redefinir utilitarios Tailwind manualmente (.bg-*, .text-*, etc.).
• Sem estilos globais agressivos para button, a, table, input que mudem componentes inteiros.

Tarefas

• Criar backup do globals.css atual.
• Reescrever globals.css em blocos minimos:
  • tokens CSS (:root, .dark)
  • reset basico
  • utilitarios realmente necessarios
• Extrair classes de componentes para componentes reais (Button, Input, Badge, Card, Alert).
• Remover gradualmente classes legadas utilitarias customizadas.
• Garantir fonte definida no layout e aplicada de forma unica.
• Revisar contraste, foco e estados disabled/hover.

Progresso atual (Fase 3)

• globals.css reduzido e sem !important.
• Removidos overrides manuais de utilitarios Tailwind (.bg-*, .text-*, .border-*).
• Label e RoleCheckbox migrados para variantes no componente (sem classes de tema globais acopladas).
• Continuar extracao para componentes de base (Button/Input/Badge/Card/Alert) e reduzir classes globais remanescentes.

Definicao de pronto

• Arquivo global enxuto e previsivel.
• Sem conflitos visuais entre telas por efeito colateral global.
• Nenhum !important no codigo do app.

Risco

• Medio. Pode quebrar aparencia de telas antigas sem componentes padronizados.

---

Fase 4 - Base de design system estilo shadcn

Escopo

Padronizar UI com componentes reutilizaveis, variantes e tokens.

Tarefas

• Criar base components/ui (Button, Input, Select, Textarea, Badge, Card, Dialog, Table).
• Adotar utilitario cn para composicao de classes.
• Adotar estrategia de variantes (ex.: cva) para reduzir classes repetidas.
• Padronizar espacamento, raio, sombras, tipografia e cores semanticas.
• Migrar telas mais usadas primeiro (login, register, dashboard admin/teacher/student).

Progresso atual (Fase 4)

• Estrutura inicial criada em src/components/ui com componentes base (Button, Input, Select, Textarea, Badge, Card, Alert).
• Utilitario cn criado e aplicado na base dos componentes UI.
• Primeira migracao pratica feita em formularios criticos (registro de estudante e pagamento aluno/responsavel).
• Migracao aplicada em login/register com padrao components/ui (Card/Input/Button/Alert) e layout alinhado.
• Dashboards principais ajustados para consistencia de componentes e estilos-base (admin/teacher/student/guardian).

Definicao de pronto

• Componentes principais usados pela maioria das telas.
• Queda relevante de duplicacao de classes Tailwind.
• Visual consistente entre areas publicas e protegidas.

Risco

• Medio. Requer disciplina para evitar voltar ao estilo ad-hoc por pagina.

---

Fase 5 - Refino visual da plataforma de ingles

Escopo

Dar identidade visual propria da escola, sem perder legibilidade e performance.

Tarefas

• Definir direcao visual unica (paleta, tipografia, acentos, ilustracoes/fotos).
• Revisar landing page e fluxo de autenticacao com hierarquia visual clara.
• Melhorar componentes de conteudo educacional (cards de nivel, progresso, tarefas, feedback).
• Garantir responsividade real (mobile-first) nas paginas criticas.
• Revisar acessibilidade (foco visivel, contraste, labels, erros de formulario).

Definicao de pronto

• Interface coerente com proposta de plataforma de ingles.
• Melhor legibilidade e consistencia de interacao.

Risco

• Baixo/medio. Principal risco e retrabalho visual sem criterios definidos.

---

Fase 6 - Limpeza final e hardening

Escopo

Fechamento tecnico para estabilidade de longo prazo.

Tarefas

• Remover codigo morto (rotas API legadas, helpers nao usados, estilos antigos).
• [~] Reduzir logs de debug e padronizar logger por ambiente.
• [~] Revisar tratamento de erros (mensagem para usuario vs log tecnico).
• Atualizar README e documentacao de arquitetura nova (Server Actions-first).
• Validar testes E2E por papel (admin/teacher/student/guardian).
• Revisar seguranca de upload/acesso a arquivos.

Progresso atual (Fase 6)

• Melhorado feedback de permissao no registro/edicao de aula (403 com mensagem clara no UI).
• Reduzido ruido de console no cliente para erros esperados (4xx) em LessonForm.
• Ajustados fluxos de navegacao que causavam 404 silencioso (links de upload/historico/resultados entre contextos admin/teacher).
• Consolidar padrao unico de erros para todos os formularios com Server Actions e APIs legadas restantes.

Definicao de pronto

• Build estavel, testes principais passando e documentacao atualizada.
• Arquitetura mais simples para manutencao.

Risco

• Baixo.

---

Criterios tecnicos transversais (todas as fases)

• Nao quebrar fluxo de login, registro e dispatcher.
• Toda regra de permissao deve existir no servidor.
• Alteracoes pequenas por PR, com escopo fechado.
• Sempre validar com build + fluxo manual das telas afetadas.

---

Checklist de execucao por fase

Use este mini-checklist ao iniciar cada fase:

1. Definir escopo exato da fase (o que entra e o que nao entra).
2. Criar tarefas tecnicas pequenas (max 1-2 dias cada).
3. Implementar em branch dedicada.
4. Rodar npm run lint e npm run build.
5. Validar fluxo funcional manual.
6. Atualizar este documento marcando itens concluidos.

---

Proxima acao recomendada

Fechar a Fase 4 (migracao de login/register/dashboards para componentes ui + padrao visual), e em seguida executar um passe objetivo da Fase 6 para remover logs legados e fallbacks de API nao utilizados.