# 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 - [x] 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). - [x] Revisar matcher do middleware para incluir rotas protegidas reais (`/admin/*`, `/dashboard/*`). - [x] Garantir bloqueio de acesso nas paginas sensiveis antes de carregar dados. - [x] Corrigir verificacao de role inconsistente (`role` vs `roles`). - [x] Revisar regra de arquivos legados: negar por padrao quando nao houver metadado de permissao. - [x] Remover/encerrar fluxo duplicado de auth (uma unica fonte de verdade do NextAuth). - [x] 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) - [x] Criadas Server Actions de pagamentos e dependentes. - [x] Auth/autorizacao centralizadas nas Actions de pagamentos. - [x] Telas de pagamentos de aluno/responsavel migradas de `fetch('/api/...')` para Actions. - [x] Formularios de registro de pagamento migrados para Actions. - [x] Retorno padronizado nas novas Actions (`success`, `data`, `message`, `fieldErrors`). - [x] Revalidacao aplicada para dashboards de pagamento apos envio. - [x] Fluxo admin de pagamentos migrado para Actions (criacao de obrigacao, aprovacao/rejeicao, consulta por obrigacao). - [x] Fallback temporario mantido: APIs antigas continuam disponiveis por compatibilidade e remocao gradual. ### Progresso atual (dominio: Turmas e atribuicoes/provas) - [x] Criadas Server Actions para fluxo operacional de provas (listar atribuicoes por turma, iniciar tentativa, listar tentativas, detalhar tentativa, corrigir resposta). - [x] Componentes de aluno migrados para Actions (`AvailableExams`, `TakeExam`) sem dependencia de `/api/classes/*` e `/api/assignments/*` nesses fluxos. - [x] Componente de resultados para professor/admin migrado para Actions (`ExamResults`) sem dependencia de `/api/attempts/*`. - [x] Mantido fallback temporario: rotas API de provas continuam existentes para compatibilidade durante transicao. ### Progresso atual (dominio: Arquivos e categorias) - [x] Criada Server Action para carregamento de categorias com migracao de `colorIndex` quando necessario. - [x] Formulario de upload de arquivos do admin migrado para Action de categorias, removendo dependencia de `/api/categories` no cliente. - [x] Ajuste de navegacao pos-upload para `router.push` em componentes cliente de upload (evitando uso indevido de `redirect`). - [x] Eliminadas chamadas `fetch('/api/...')` no frontend protegido; fluxo interno agora opera via Server Actions. ### Progresso atual (dominio: Usuarios/guardian/wards) - [x] Criadas Server Actions de usuarios para dependentes (`getWardsAction`) e listagem admin (`getUsersForAdminAction`). - [x] Fluxo de pagamentos do responsavel desacoplado do dominio de pagamentos para usar Action de usuarios no carregamento de dependentes. - [x] Painel admin de usuarios passou a consumir Action de usuarios (sem dependencia de rota API interna). - [x] 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 - [x] Criar backup do `globals.css` atual. - [x] Reescrever `globals.css` em blocos minimos: - tokens CSS (`:root`, `.dark`) - reset basico - utilitarios realmente necessarios - [x] Extrair classes de componentes para componentes reais (Button, Input, Badge, Card, Alert). - [x] Remover gradualmente classes legadas utilitarias customizadas. - [x] Garantir fonte definida no layout e aplicada de forma unica. - [x] Revisar contraste, foco e estados disabled/hover. ### Progresso atual (Fase 3) - [x] `globals.css` reduzido e sem `!important`. - [x] Removidos overrides manuais de utilitarios Tailwind (`.bg-*`, `.text-*`, `.border-*`). - [x] `Label` e `RoleCheckbox` migrados para variantes no componente (sem classes de tema globais acopladas). - [x] 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 - [x] Criar base `components/ui` (Button, Input, Select, Textarea, Badge, Card, Dialog, Table). - [x] Adotar utilitario `cn` para composicao de classes. - [x] Adotar estrategia de variantes (ex.: cva) para reduzir classes repetidas. - [x] Padronizar espacamento, raio, sombras, tipografia e cores semanticas. - [x] Migrar telas mais usadas primeiro (login, register, dashboard admin/teacher/student). ### Progresso atual (Fase 4) - [x] Estrutura inicial criada em `src/components/ui` com componentes base (Button, Input, Select, Textarea, Badge, Card, Alert). - [x] Utilitario `cn` criado e aplicado na base dos componentes UI. - [x] Primeira migracao pratica feita em formularios criticos (registro de estudante e pagamento aluno/responsavel). - [x] Migracao aplicada em login/register com padrao `components/ui` (Card/Input/Button/Alert) e layout alinhado. - [x] 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) - [x] Melhorado feedback de permissao no registro/edicao de aula (403 com mensagem clara no UI). - [x] Reduzido ruido de console no cliente para erros esperados (4xx) em `LessonForm`. - [x] 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.