284 lines
12 KiB
Markdown
284 lines
12 KiB
Markdown
# 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.
|