📄 Documento de Execução — Card 6: [M1] Minhas Notas & Frequência

🎯 1. O que foi implementado

Portal de Notas e Frequência do aluno: tabela de notas por disciplina x período (com cores semânticas), média ponderada, evolução por período (LineChart), status Aprovado/Reprovado, barras de presença por disciplina e histórico recente de chamada.

Decisões do cliente aplicadas

• Média mínima: 7.0 (threshold de aprovação — não 6.0 como no schema default)
• Sistema de notas: AMBOS (numérico 0-10 E conceito A-E) — GradeCell mostra os dois
• Frequência mínima: 75% — AttendanceBar fica vermelho abaixo disso
• Só mostra notas publicadas (isPublished: true) — aluno não vê notas em rascunho
• RBAC: aluno só vê próprias notas (studentProcedure)

Páginas (2)

• /aluno/notas — Card de média geral + filtros por disciplina + GradeTable (notas coloridas) + EvolutionChart (LineChart)
• /aluno/frequencia — Cards de presença geral + faltas totais + AttendanceBar por disciplina + histórico recente com ícones de status

Componentes UI novos (4 reutilizáveis)

• GradeTable — Tabela notas por disciplina x período, com coluna de média + status Aprovado/Reprovado. Cada célula usa GradeCell.
• GradeCell — Célula de nota com cor semântica: vermelho <7.0, verde 7.0-7.9, azul destaque ≥8.0. Mostra valor numérico E conceito (A-E).
• EvolutionChart — LineChart (Recharts) mostrando evolução da média por período, com linha de referência tracejada no threshold de aprovação.
• AttendanceBar — Barra horizontal de % presença por disciplina, verde ≥75% ou vermelho <75%, com detalhes (presenças/faltas).

tRPC procedures novas (2)

• student.grades.summary — notas por disciplina (agrupadas) + média ponderada + evolução por período + status Aprovado/Reprovado. Filtra isPublished: true.
• student.attendance.summary — % presença por disciplina (PRESENT+JUSTIFIED+LATE contam como presente, só ABSENT conta contra) + faltas totais + histórico recente (20 registros).

Item realocado do Card 4 (MediaEvolutionMiniChart + Média geral)

Os itens MediaEvolutionMiniChart e a entrega "Média geral" foram realocadas do Card 4 para o Card 6 (onde os dados de notas existem). Implementados aqui:

• EvolutionChart (Recharts LineChart) — evolução da média por período
• Média geral calculada e exibida em card de destaque

✅ 2. Critérios de aceite validados

📁 3. Arquivos criados/modificados

Criados (8)

Modificados (4)

🗄️ 4. Schema do banco (mudanças)

Nenhuma mudança de schema. Todos os modelos já existiam:

• Grade (value, concept, weight, periodType, periodNumber, isPublished) — Card 2
• Attendance (status, date, lessonNumber, classId) — Card 2
• ClassTeacher (classId, subjectId, teacherId) — vinculo professor-disciplina-turma

Seed criado: scripts/seed_card6_demo.js — 3 ClassTeachers + 12 notas (4 bimestres x 3 disciplinas) + 20 presenças. Rodado na VPS Oracle (DEV).

🔌 5. Handoff para o próximo card

Componentes reutilizáveis prontos

• GradeTable / GradeCell — usados por Card 9 (Acompanhamento Pedagógico PARENT) e Card 27 (Relatórios)
• EvolutionChart — usado por Card 22 (Dashboard Master) e Card 27 (Relatórios)
• AttendanceBar — usado por Card 9 (PARENT) e Card 17 (Dashboard Unidade)

Endpoints tRPC novos

• student.grades.summary — usar em qualquer página /aluno/*
• student.attendance.summary — padrão para consulta de frequência

Padrão estabelecido (replicar no Card 7)

• 'use client' + trpc.student.*.useSuspenseQuery() (suspense) para dados
• Cores semânticas baseadas em threshold (verde/azul/vermelho)
• Recharts com ResponsiveContainer + tokens CSS para cores (dark mode automático)
• ErrorBoundary em torno de componentes com Recharts

📋 6. Checklist do Trello — status por item

Entregáveis (4/4)

• ✅ Notas 0-10 por disciplina
• ✅ Média ponderada
• ✅ Aprovado/Reprovado (threshold 7.0)
• ✅ Frequência %

Especificação Técnica (concluída)

• ✅ tRPC student.grades.summary
• ✅ tRPC student.attendance.summary
• ✅ Página /aluno/notas
• ✅ Página /aluno/frequencia
• ✅ Componente GradeTable
• ✅ Componente GradeCell (cores semânticas)
• ✅ Componente EvolutionChart (Recharts)
• ✅ Componente AttendanceBar
• ✅ Filtro por disciplina
• ✅ Empty state (sem notas)
• ✅ Loading skeleton
• ✅ Indicador Aprovado/Reprovado
• ✅ RBAC (aluno só vê próprias notas)
• ✅ Só mostra notas isPublished=true

Item realocado do Card 4

• ✅ EvolutionChart + "Média geral" — implementados (realocados do Card 4)

Itens realocados para outros cards (rastreabilidade)

🚀 7. Deploy DEV

• URL: https://sistemaescolar.wellka.com.br/aluno/notas (login STUDENT)
• Commit: d51650c
• PM2: genioon-dev restart ✓
• Smoke test: /api/health 200, /aluno/notas 307 (auth), build VPS ✓
• Dados demo: 12 notas (3 disciplinas x 4 bimestres) + 20 presenças (85% presença)
• Login: aluno@genioon.com.br

🧠 8. Contexto gerado para próximas etapas

Para Card 7 (Tarefas & Entregas)

• Padrão de página aluno com tabela + filtros + skeleton estabelecido
• student.*.summary é o padrão de procedure (retorna dados consolidados)

Para Card 9 (Acompanhamento Pedagógico PARENT)

• GradeTable reutilizável (pais veem notas dos filhos)
• AttendanceBar reutilizável
• Replicar parent.grades.summary e parent.attendance.summary

Para Card 12 (Diário de Classe Professor)

• O professor vai LANÇAR as notas que este card EXIBE
• Schema Grade já pronto (professor cria com isPublished=false → publica)

Lições aprendidas

1. Relation teachers em Class (não classTeachers) — o relation se chama teachers no model Class, apesar de ser do tipo ClassTeacher[]. Erro de TS revelou isso.
2. Recharts com tokens CSS: usar var(--accent-500) etc. nos strokes funciona e respeita dark mode. ResponsiveContainer obrigatório.
3. Média ponderada: calcular no backend (server) para evitar divergência entre client/server (consistência de cálculo).

🎯 9. Próximo card

Card 7 [M1] Tarefas & Entregas

• Spec: docs/execucao/07-m1-tarefas-entregas.md
• Trello: https://trello.com/c/2AnhCDm1
• Reuso: StudentShell, Skeleton, ErrorBoundary, padrão tRPC
• Foco: lista de tarefas pendentes, entrega (texto/arquivo/foto), feedback do professor
• Item realocado do Card 4: TaskCounter (tarefas pendentes)