📄 Documento de Execução — Card 19: [M4] Gestão de Turmas & Grade

🎯 1. O que foi implementado

O Card 19 entrega a gestão completa de turmas, salas e grade horária para o painel LOCAL. É a peça que conecta alunos (Card 18) e professores (M3) através das turmas e seus horários.

Backend — 3 sub-routers (20 procedures)

local.classes (7 procedures):

• list — Lista turmas com filtros (ano, turno, filial), contagem de alunos/professores/aulas, e % de ocupação
• detail — Ficha completa: professores atribuídos (ClassTeacher), alunos matriculados, grade horária
• create — Cria turma com código automático FILIAL-ANO-SEQ, valida sala na filial
• update — Edita nome, turno, capacidade, sala
• deactivate — Soft-delete
• assignTeacher — Vincula professor×turma×matéria (ClassTeacher), previne duplicatas
• removeTeacher — Remove atribuição com validação de escopo

local.rooms (4 procedures):

• list — Lista salas com contagem de turvas e slots
• create — Cria sala (nome, capacidade, tipo, andar, recursos JSON)
• update — Edita sala
• deactivate — Soft-delete

local.schedule (7 procedures):

• listByClass — Grade de uma turma específica
• listByTeacher — Grade de um professor
• listByBranch — Todos os slots da filial
• createSlot — Adiciona aula (matéria, professor, dia, horário, sala). Detecta conflitos e alerta, mas NÃO bloqueia (decisão cliente)
• updateSlot — Edita slot
• deleteSlot — Remove slot (soft-delete)
• detectConflicts — Varre TODA a grade da filial e retorna conflitos de professor (2 turmas mesmo horário), sala (2 turdas mesma sala) e turma (2 matérias mesmo horário)

Helper de sobreposição de horários

function timeOverlap(s1, e1, s2, e2): boolean {
  return s1 < e2 && s2 < e1;  // HH:MM string comparison funciona
}

Frontend — 4 páginas

1. /local/turmas (REESCRITA) — Grid de cards com barra de ocupação colorida (verde/amarelo/vermelho), badges de turno, contagem de professores/aulas, e botão de alerta de conflitos no header
2. /local/turmas/[id] (NOVA) — Detalhe com 4 cards de resumo, professores atribuídos (com botão remover), lista de alunos matriculados (link para ficha), grade resumida, modais de atribuir professor e editar turma
3. /local/grade (REESCRITA) — Grade visual em grid (dias × horários), cores por matéria (hash do nome), seletor de turma, modal "Adicionar Aula" com selects de matéria/professor/sala/dia/horário, e modal de conflitos com badges coloridos por tipo (PROFESSOR/SALA/TURMA)
4. /local/infraestrutura (NOVA) — CRUD de salas em cards, com recursos (projetor, ar, TV, computadores), capacidade, tipo, andar, e botões editar/desativar

Decisões do cliente aplicadas (7/7)

✅ Critérios de aceite validados

📁 2. Arquivos criados/modificados

Criados

Modificados

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

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

• Class (name, code, year, shift, maxStudents, branchId, roomId)
• Room (name, capacity, type, floor, resources JSON, branchId)
• ScheduleSlot (classId, subjectId, teacherId, dayOfWeek, startTime, endTime, roomId)
• ClassTeacher (classId, teacherId, subjectId — vínculo professor×turma×matéria)

🔌 4. Handoff para o próximo card

Procedures disponíveis (reutilizáveis)

• local.classes.* — CRUD turmas + atribuição professores
• local.rooms.* — CRUD salas
• local.schedule.* — Grade horária + detecção conflitos
• timeOverlap(s1,e1,s2,e2) — helper de sobreposição HH:MM

Integração com Card 18 (Alunos & Matrículas)

• O select de turmas no modal de transferência do Card 18 agora pode usar local.classes.list
• O enrollments.create valida vagas via class.maxStudents
• O enrollments.transfer valida turma de destino via local.classes.detail

Padrões estabelecidos

• Código de turma automático: FILIAL-ANO-SEQ (ex: ABCD-2026-01)
• Grade visual: grid table (dias × horários) com cor por matéria (hash determinístico)
• Conflitos: alerta (warning toast) sem bloquear criação — overlay visual no modal
• Recursos de sala: JSON flexível { projetor, arCondicionado, tv, computadores }

📋 5. Checklist do Trello — status

[Entregas] 4/4 ✅

• CRUD de turmas
• Atribuição de professores
• Grade horária visual
• Resolução de conflitos

[Especificação Técnica]

13 rotas/procedures marcadas ✅. Pendências futuras: Exportar grade PDF (Puppeteer — Card 33), auditoria schedule (Card 26), drag-and-drop visual (refinamento).

[Validar com Cliente] 7/7 ✅

Todas respondidas e aplicadas.

🚀 6. Deploy DEV

• Build: ✅ local + VPS
• Commit: 0889fd7
• VPS: git pull + build + pm2 reload
• Smoke test: HTTP 200 ✅
• URL: https://sistemaescolar.wellka.com.br/local/turmas (login: diretor@genioon.com.br)

🧠 7. Contexto gerado

1. Padrão de grade visual — reutilizável para agenda do aluno (Card 7c), calendário, e dashboards
2. Detecção de conflitos — algoritmo O(n²) por dia, suficiente para escolas de 10-30 unidades
3. ClassTeacher — agora com UI completa de atribuição; professores só veem matérias atribuídas (já enforced no M3)
4. Recursos JSON flexível — permite adicionar novos recursos sem migration

🎯 8. Próximo card

Card 20: [M4] Financeiro da Unidade — visão financeira do LOCAL: mensalidades, inadimplência, receita, e geração de cobranças. Reaproveita Enrollment.monthlyFee/discountPercent/dueDay e procedures de Payment.