📄 Documento de Execução — Card 18: [M4] Gestão de Alunos & Matrículas

🎯 1. O que foi implementado

O Card 18 entrega o módulo completo de gestão de alunos e matrículas para o painel da direção (LOCAL/SUPERVISOR/MASTER). Esta é a primeira peça do M4 (Painel Direção/Unidade) e estabelece os padrões de cadastro que serão reutilizados nos cards 19-21.

Backend — local.students (CRUD de alunos)

Foram criados 5 procedures no sub-router local.students:

1. students.list — Lista paginada (20/pg) com busca por nome/RA, filtros por status (ativo/inativo), curso e filial. Respeita branchWhere(ctx): LOCAL vê só própria filial, SUPERVISOR suas filiais, MASTER todas.
2. students.detail — Ficha completa com dados pessoais, médicos (criptografados), responsáveis, últimas 5 notas, últimas 5 frequências, contadores agregados (_count). Mapeamento explícito para garantir tipos no cliente tRPC.
3. students.create — Cria User + Student em transação. Gera RA automático (AAAA-NNNNN = ano + sequencial de 5 dígitos por filial). Valida idade mínima (5 anos) e CPF (check digit DV1+DV2). Encripta CPF, RG, alergias, medicações e observações de saúde com AES-256-GCM.
4. students.update — Atualiza campos; reencripta dados sensíveis quando alterados.
5. students.deactivate — Soft-delete (LGPD): marca isActive=false + cancela matrículas ativas com motivo.

Backend — local.enrollments (funil de matrículas)

5 procedures no sub-router local.enrollments:

1. enrollments.list — Lista matrículas agrupadas por status para o Kanban. Busca por aluno, filtra por curso/filial.
2. enrollments.create — Cria matrícula (LEAD ou PRE_ENROLLED). Valida: aluno pertence à filial, turma pertence à filial, curso ativo para filial, vagas disponíveis (maxStudents=10).
3. enrollments.updateStatus — Avança matrícula no funil. Define enrolledAt ao ativar, cancelledAt+cancelReason ao cancelar, graduatedAt ao formar.
4. enrollments.transfer — Transfere entre turmas sem custo (decisão cliente). Marca matrícula atual como TRANSFERRED + cria nova ACTIVE preservando termos financeiros (mensalidade, desconto, vencimento, bolsa). Valida vagas na turma de destino.
5. enrollments.history — Timeline completa de matrículas do aluno.

Frontend — 4 páginas reescritas/criadas

1. /local/alunos (REESCRITA) — Lista em tabela com cards de resumo (Total/Ativos/Inativos), busca, filtros (status, curso), paginação, e navegação para ficha. Antes usava dados mock (@/data/mock); agora é tRPC real.
2. /local/alunos/novo (NOVA) — Cadastro completo em 2 colunas: formulário (dados pessoais, contato, médicos, responsável) + lateral com foto webcam e ações. Campos sensíveis marcados com badge "Criptografado". Validação client-side de idade mínima.
3. /local/alunos/[id] (NOVA) — Ficha completa: cabeçalho com avatar + badges de status, dados pessoais, responsáveis, informações médicas, notas recentes, frequência recente, resumo acadêmico, e timeline de histórico de matrículas. Modais de transferência e desativação.
4. /local/matriculas (REESCRITA) — Kanban do funil com 6 colunas ativas (LEAD → PRE_ENROLLED → PENDING_DOCS → PENDING_PAYMENT → PENDING_SIGNATURE → ACTIVE) + seção colapsável de estados terminais (TRANSFERRED, GRADUATED, CANCELLED, DROPPED_OUT). Botão "Avançar" em cada card abre modal de transição.

Decisões de segurança aplicadas

• RBAC hierárquico via branchWhere(ctx): LOCAL só vê/manipula alunos da própria filial; SUPERVISOR das suas filiais; MASTER vê todas.
• AES-256-GCM em CPF, RG, alergias, medicações, observações de saúde (padrão SEGURANCA_LGPD §2.1).
• Validação CPF com check digit (DV1 + DV2) — rejeita CPFs com dígitos iguais.
• Idade mínima 5 anos (confirmado pelo cliente).
• Soft-delete (LGPD): dados nunca excluídos, apenas isActive=false.
• Transferência sem custo (decisão cliente confirmada).

✅ 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 necessários já existiam:

• Student (userId, fullName, birthDate, cpf, rg, branchId, registrationNumber, dados médicos)
• User (email, role, status, branchId)
• Enrollment (studentId, classId, courseId, status, monthlyFee, discountPercent, scholarshipType)
• Guardian + StudentGuardian (vínculo responsável↔aluno)

A criptografia AES-256-GCM usa ENCRYPTION_KEY do .env (formato iv:authTag:ciphertext).

🔌 4. Handoff para o próximo card

Variáveis de ambiente novas

• Nenhuma (usa ENCRYPTION_KEY já existente).

Procedures disponíveis (reutilizáveis)

• local.students.list/detail/create/update/deactivate — CRUD de alunos
• local.enrollments.list/create/updateStatus/transfer/history — funil de matrículas
• isValidCPF(raw) — helper de validação de CPF (check digit)
• branchWhere(ctx) — filtro de filial por role (reutilizado do Card 17)

Padrões estabelecidos (reutilizáveis no M4/M5)

• RA automático: formato AAAA-NNNNN (ano + sequencial por filial)
• Webcam capture: getUserMedia → canvas → toDataURL (reutilizável para foto de professores, responsáveis)
• Kanban pattern: columns agrupado por status + seção colapsável de terminais
• Timeline pattern: histórico vertical com linha conectora e badges coloridos por status
• Mapeamento explícito de tipos: inferência do Prisma include não propaga para cliente tRPC — sempre mapear campos no return

Hooks/utilidades disponíveis

• trpc.local.students.* e trpc.local.enrollments.* prontos para uso

📋 5. Checklist do Trello — status por item

[Entregas] 4/4 ✅

• Cadastro de aluno (com foto/webcam)
• Funil de matrícula
• Histórico do aluno
• Transferência entre turmas

[Especificação Técnica] — implementado

[Validar com Cliente] 10/10 ✅

Todas as 10 perguntas respondidas (8 já estavam + 2 defaults adotados neste card).

🚀 6. Deploy DEV

• Build: npm run build ✅ (local + VPS)
• Commit: b61bb5d em main
• VPS: git pull + build + pm2 reload genioon-dev (id 3)
• Smoke test: HTTP 200 em /login, título "GENIOON — Sistema Escolar Unificado" ✅
• URL DEV: https://sistemaescolar.wellka.com.br/local/alunos (login LOCAL: diretor@genioon.com.br)

🧠 7. Contexto gerado para próximas etapas

1. Padrão Kanban estabelecido — reutilizável no Card 30 (CRM Funil de Leads) que tem funil similar (Novo→Contatado→Qualificado→Visita→Proposta→Matriculado).
2. Webcam + crypto — padrão de captura de foto + criptografia de dados sensíveis pronto para professores (Card 12 já feito) e responsáveis (Card 25).
3. Transferência sem custo — a lógica de "marcar anterior + criar nova preservando termos" é reutilizável para transferência entre filiais (se solicitado futuramente).
4. Mapeamento explícito de tipos Prisma→tRPC — lição importante: a inferência de include do Prisma 7 não propaga automaticamente para o cliente tRPC; sempre mapear campos no return do procedure.
5. GuardianLinker parcial — os campos de responsável estão no form, mas a vinculação completa (criar User Guardian + StudentGuardian) fica para o Card 25 (Gestão de Usuários RBAC), onde o fluxo de convite/ativação de responsáveis será implementado.

🎯 8. Próximo card

Card 19: [M4] Gestão de Turmas & Grade — CRUD de turmas (Class), grade horária (ScheduleSlot), e vinculação professor×turma×matéria (ClassTeacher). O select de turmas no modal de transferência (atualmente vazio) será populado por este card.