Inscrição Rápida — Processo Seletivo Fora do Calendário

[FernandoAlmeidaPinto]

1. Contexto e motivação

Hoje o fluxo de inscrição em um Processo Seletivo (InscriptionCourse) pressupõe um calendário tradicional de cursinho popular: o cursinho abre o PS, divulga, alunos se inscrevem via formulário público, passam por Em Análise → Convocado para matrícula → Declarou Interesse (com upload de docs/foto/survey) → Matriculado. O modelo cobre bem o caso "alto volume, seleção competitiva, recursos limitados".

O problema: alguns cursinhos fecham parceria com a Você na Facul fora desse calendário, já com a turma definida (ex.: 30 alunos que já frequentam o cursinho presencialmente). Para esses cursinhos, todo o funil de seleção é desnecessário — eles só precisam dar acesso à plataforma para que os alunos comecem a usar simulados, redações, chat, presença e demais funcionalidades.

Pedir que cada um desses alunos faça o cadastro público completo gera atrito alto (criação de conta, confirmação de email, formulário longo, espera por análise, declaração de interesse) para um cenário em que a "seleção" já aconteceu fora do sistema. O resultado prático é que esses cursinhos ou não usam a plataforma, ou o coordenador precisa fazer suporte 1-a-1 com cada aluno.

Hipótese de valor: se permitirmos que o cursinho insira em lote os alunos já selecionados e gere acesso direto, reduzimos o tempo de "parceria fechada → turma usando a plataforma" de semanas para o tempo de uma planilha + clique. Isso aumenta o engajamento desses parceiros excepcionais sem comprometer o rigor do funil regular.

---

2. Objetivos e não-objetivos

Objetivos (v1):

• Habilitar, sob curadoria do administrador da plataforma, um modo de inscrição em lote para cursinhos que iniciaram parceria fora do período convencional.
• Permitir que o cursinho cadastre N alunos a partir de uma planilha, gerando User + StudentCourse em um único passo.
• Garantir que o aluno conclua o mínimo de dados obrigatórios no primeiro acesso (onboarding), mantendo integridade do modelo de dados.
• Reaproveitar a entidade InscriptionCourse e o enum StatusApplication existentes — sem criar um caminho paralelo de dados.

Não-objetivos (v1):

• Não substitui o PS tradicional para cursinhos que fazem seleção.
• Não dá ao cursinho a capacidade de inscrever alunos retroativamente em PSs já encerrados.
• Não automatiza notificações em massa fora do email transacional de boas-vindas.
• Não cobre import de turmas, presenças ou histórico — apenas matrícula inicial.

---

3. Personas e jornadas

Admin da plataforma. Recebe contato de um cursinho parceiro que entrou fora do calendário. Avalia o caso, marca o cursinho como "autorizado a usar inscrição rápida". Pode revogar a qualquer momento.

Coordenador do cursinho (com permissão gerenciarProcessoSeletivo). Cria um PS marcado como "inscrição rápida", sobe a planilha de alunos, acompanha o resultado do import. Ao final do upload, tem na tela do PS todos os alunos do lote já como Declarou Interesse, restando apenas matriculá-los manualmente em turma (fluxo atual: criar CoursePeriod, criar Class, atribuir o aluno).

Aluno convidado. Recebe um email com link de primeiro acesso, define senha, preenche um onboarding mínimo e envia a foto da carteirinha. O onboarding não muda seu status — ele já entrou no sistema como Declarou Interesse no momento do import. Se o coordenador ainda não tiver feito a matrícula em turma, cai no dashboard como Declarou Interesse; se o coordenador já tiver matriculado antes do onboarding, cai já como Matriculado.

---

4. Fluxo proposto (alto nível)

4.1. Admin habilita o cursinho

Tela de admin já existente para gerenciar PartnerPrepCourse ganha um toggle "Permitir inscrição rápida". Sem isso, a opção não aparece na criação do PS do cursinho.

4.2. Cursinho cria PS com inscrição rápida

No modal de criação de PS (InscriptionInfoCreateEditModal.tsx), aparece o checkbox "Habilitar inscrição rápida" — apenas se o cursinho estiver autorizado. Quando marcado:

• O campo requestDocuments fica desabilitado (não faz sentido pedir documentos em fluxo simplificado — ver §6).
• A tela exibe um aviso explicando que esse PS não terá formulário público, e que a inscrição será via planilha.
• A validação hasActiveForm continua valendo apenas para PS regulares; para PS rápido, não criamos FormFull no vcnafacul-form (ou criamos um stub vazio — decisão a tomar, ver §10).

4.3. Cursinho sobe planilha

Após criar o PS rápido, abre-se a tela "Cadastrar estudantes em lote" com:

• Download do template .xlsx com colunas obrigatórias e exemplo.
• Upload do arquivo preenchido.
• Pré-visualização (parsing client-side ou server-side, ver §10) com validação linha-a-linha antes de gravar: email válido, CPF válido, duplicidades, alunos já cadastrados na plataforma.
• Botão "Confirmar e enviar convites".

Colunas mínimas sugeridas:

Coluna	Obrigatório	Observação
email	sim	usado para login; precisa ser único
nome	sim	primeira parte do nome (firstName)
sobrenome	sim	lastName
data_nascimento	sim	usado para validar idade ≥ 14 (regra atual do UserService) e detectar menor de idade

Campos como CPF, telefone, endereço, gênero, dados socioeconômicos, dados do responsável legal migram para o onboarding (§4.5) — pedir tudo na planilha torna o fluxo tão pesado quanto o tradicional.

4.4. Sistema processa o lote

Para cada linha válida:

1. Cria User com senha temporária aleatória (gerada server-side, hash com bcrypt) e emailConfirmSended = null (já considerado validado — o convite explícito do cursinho substitui o duplo opt-in).
2. Cria StudentCourse ligado ao InscriptionCourse e ao PartnerPrepCourse, com applicationStatus = StatusApplication.DeclaredInterest (estado terminal pré-matrícula — ver §6.a) e flag interna quickInscription = true.
3. Gera um JWT de primeiro acesso (CreateFlow.QUICK_INSCRIPTION_ONBOARDING, novo) com expiração mais longa (sugestão: 14 dias) e envia email transacional novo sendQuickInscriptionInvite.
4. Grava LogStudent com descrição "Inscrição rápida criada por <coordenador> via planilha" e LogPartner resumindo o lote.

O processamento deve ser assíncrono em background (job/queue) acima de N linhas (sugestão: 25), com status visível no frontend ("Processando 87 de 120..."). Abaixo desse limite, processa síncrono e devolve o resultado direto.

Resultado esperado do lote: o coordenador volta para a tela do PS e vê todos os alunos do lote já listados com status Declarou Interesse, restando apenas a matrícula manual de cada um (via fluxo de turma existente, §4.6).

Tela final do upload: tabela email | status (criado / erro) | mensagem + botão "Baixar relatório (.xlsx)".

4.5. Aluno faz primeiro acesso

Aluno recebe email com link /{FRONT_URL}/inscricao-rapida/onboarding?token=…. Ao abrir:

1. Tela de definição de senha (a senha temporária do email é descartada após esse passo).
2. Tela de onboarding com campos mínimos para satisfazer o modelo atual:
   • CPF (obrigatório no StudentCourse)
   • WhatsApp
   • Endereço (CEP + complementares, hoje no User)
   • Se menor de 18: bloco de LegalGuardian completo (regra atual do StudentCourseService.create)
3. Envio da foto da carteirinha (reaproveita o endpoint PATCH /student-course/declaration-photo e o BUCKET_PROFILE já existentes; grava student.photo e photoDone = true).
4. Confirmação → vai para o dashboard do aluno.

Importante: o onboarding NÃO altera applicationStatus. O estudante já entrou no sistema como DeclaredInterest no momento do import (§4.4). O onboarding só completa os dados pessoais e a foto da carteirinha; a transição para Enrolled é exclusivamente decisão do coordenador via §4.6.

Consequência prática:

• Se o coordenador ainda não matriculou o aluno em turma quando o aluno faz o onboarding → aluno cai no dashboard com status Declarou Interesse e mensagem "Aguarde o cursinho confirmar sua turma".
• Se o coordenador já matriculou o aluno em turma antes do aluno fazer o onboarding → aluno cai no dashboard já como Matriculado, com cod_enrolled válido.

Antes de concluir o onboarding (incluindo a foto), o aluno tem acesso restrito (sugestão: apenas tela de onboarding + logout). Sem isso, abrimos um buraco onde alunos meio-cadastrados navegam pela plataforma sem CPF/foto.

4.6. Coordenador matrícula em turma (fluxo atual, sem mudanças)

Matrícula segue exatamente o caminho que já existe:

1. Coordenador cria/usa um CoursePeriod (período letivo).
2. Cria Class (turmas) sob aquele período.
3. Para cada aluno em DeclaredInterest, atribui a uma Class e chama confirmEnrolled → status vira Enrolled, gera cod_enrolled.

Essa parte não é automatizada pela inscrição rápida — é decisão consciente, porque criar período letivo e turmas é trabalho que o coordenador precisa fazer com calma e que não tem como ser inferido a partir da planilha.

---

5. Mudanças de modelo

PartnerPrepCourse (api-vcnafacul):

• Nova coluna quick_inscription_enabled: boolean (default false). Setada apenas pelo admin.

InscriptionCourse:

• Nova coluna quick_inscription: boolean (default false). Imutável após criação.

StudentCourse:

• Nova coluna quick_inscription: boolean (default false). Útil para relatórios, filtros e auditoria.

StatusApplication: sem novos valores. Reaproveita DeclaredInterest → Enrolled. Pular para Enrolled direto também é viável (ver §6), mas adicionar um valor QuickInscription aumenta a complexidade do funil sem benefício claro.

CreateFlow: adicionar QUICK_INSCRIPTION_ONBOARDING.

Permissões (Role): nenhuma nova permission. A permission para criar PS rápido continua sendo gerenciarProcessoSeletivo; a permission para habilitar o cursinho como autorizado é validarCursinho ou gerenciarPermissoesCursinho (decidir qual encaixa melhor — recomendação: validarCursinho, pois é uma decisão de curadoria sobre o parceiro).

---

6. Decisões de design com trade-offs

Pontos onde o card original omite ou ambiguamente decide. Cada um precisa ser fechado antes do dev começar.

(a) Status inicial do aluno: DeclaredInterest. Decidido. O aluno entra direto como DeclaredInterest no momento do import. Ir para Enrolled exige criação de período letivo + turma + atribuição, que é decisão do coordenador e não é automatizada (§4.6). O onboarding feito pelo aluno (§4.5) não altera o status — apenas completa dados pessoais e foto da carteirinha.

(b) Senha temporária vs link mágico. Card original menciona "email com email e senha para login". Hoje o projeto usa link de confirmação com JWT 2h, não senha temporária. Trade-off:

• Senha temporária no email: pior em segurança (senha em texto plano em caixa de email), exige troca obrigatória no primeiro login.
• Link mágico sem senha: alinhado com sendCreateUser atual; mais seguro; usuário define senha na primeira sessão.

Recomendação: link mágico com JWT longo (14 dias) que cai em tela "definir senha". Mantém o padrão de segurança do projeto.

(c) Documentos. PS regular pode exigir documentos (requestDocuments boolean). Para PS rápido, isso é incoerente com o objetivo. Recomendação: forçar requestDocuments = false quando quickInscription = true.

(d) Formulário vcnafacul-form. PS regular exige hasActiveForm. PS rápido não tem formulário público. Opções:

1. Pular formService.createFormFull para PS rápido. Coerente, mas pode quebrar consumers que assumem FormFull sempre presente.
2. Criar um FormFull "vazio" (sem perguntas) só para satisfazer o invariante.

Recomendação: (1) pular, e adicionar guards explícitos nos consumers (submissionService, relatórios) que checam inscriptionCourse.quickInscription antes de procurar form.

(e) Vagas e expectedOpening. PS tem expectedOpening. Em PS rápido, isso é o tamanho da turma. O sistema deve impedir um lote que estoure as vagas? Recomendação: avisar mas não bloquear (cursinho ajusta expectedOpening ou prossegue assumindo o estouro), com warning visual e log.

(f) Idempotência por email. Se a planilha tem aluno@x.com e esse email já existe no User:

• Já é estudante deste cursinho em PS ativo? → erro na linha.
• Já é estudante de outro cursinho? → erro na linha (regra de negócio atual: um aluno pode estar em PSs de cursinhos diferentes? Verificar — se sim, criar StudentCourse adicional).
• Existe na plataforma mas nunca foi estudante? → criar StudentCourse ligado ao User existente, sem sobrescrever senha; enviar email "você foi inscrito em <cursinho>, clique para confirmar".

Recomendação: comportamentos diferenciados acima, todos explicitados na pré-visualização.

(g) Validação síncrona vs assíncrona. Excel parsing + criação de N usuários pode estourar timeout em lotes grandes. Recomendação: fila/job acima de 25 linhas, com status polling. Reaproveita padrão de cron já presente no InscriptionCourseService.

(h) Limites. Tamanho máximo de arquivo (sugestão: 1 MB), número máximo de linhas por upload (sugestão: 500), rate limit no endpoint (Throttle já em uso no projeto).

---

7. Regras de negócio explícitas

• Apenas cursinhos com PartnerPrepCourse.quickInscriptionEnabled = true veem a opção de criar PS rápido.
• Apenas usuários com Permissions.gerenciarProcessoSeletivo podem subir planilhas.
• Um PS regular não pode ser convertido em PS rápido depois de criado (e vice-versa).
• Em PS rápido, o cursinho não pode adicionar alunos manualmente um a um pela interface de planilha (mantém o caminho de cadastro coletivo único).
• Em PS rápido, a tela pública /inscription-course/to-inscription/:id retorna 404 ou redireciona — não há formulário público.
• Email duplicado dentro da própria planilha vira erro de linha (a linha duplicada falha; a primeira ocorrência segue).
• Aluno menor de 14 anos é rejeitado (regra de idade mínima atual no UserService.createUser).
• Token de primeiro acesso expirado pode ser regenerado pelo coordenador no detalhe do aluno (botão "Reenviar convite").
• Alunos criados via inscrição rápida aparecem normalmente em getSubscribers, getEnrolled, dashboards, e relatórios — com badge "Inscrição rápida" para distinção visual.

---

8. Segurança e LGPD

• Coordenador atesta, no momento do upload, que tem base legal para inscrever os alunos listados (consentimento prévio, contrato de matrícula, etc.). Modal com checkbox de confirmação obrigatório antes do upload.
• O termo de uso/política de privacidade da plataforma é apresentado ao aluno na tela de onboarding e o consentimento é registrado em LogStudent com IP e user-agent (já existe esse padrão em declaredInterest).
• Planilha enviada não é armazenada após o processamento — apenas o relatório de resultado, com hash dos emails para auditoria.
• Senha temporária jamais é registrada em log; o JWT é gerado com expiresIn longa mas pode ser revogado no botão "Reenviar convite".

---

9. Telemetria e observabilidade

• Métrica de produto: número de PS rápidos criados / mês, conversão "convite enviado → primeiro acesso → onboarding completo".
• Discord webhook em erro de import (discordWebhook.sendMessage, já em uso no InscriptionCourseService).
• Logs estruturados em LogStudent e LogPartner.

---

10. Critérios de aceite

Como admin:

• Vejo um toggle "Permitir inscrição rápida" no detalhe de cada PartnerPrepCourse.
• Ao ativar o toggle, o cursinho passa a ter a opção de criar PS rápido.
• Ao desativar, novos PS rápidos não podem ser criados, mas os existentes continuam funcionando.

Como coordenador de cursinho autorizado:

• Ao criar PS, vejo checkbox "Inscrição rápida" (não aparece se o cursinho não estiver autorizado).
• Em PS rápido, requestDocuments fica desabilitado.
• Após criar o PS rápido, vejo a tela "Cadastrar estudantes em lote" com download de template.
• Subo planilha com email/nome/sobrenome/data_nascimento; vejo pré-visualização com validação por linha.
• Linhas inválidas são sinalizadas com mensagem clara; linhas válidas mostram "será criado".
• Ao confirmar, recebo feedback de progresso e, no fim, posso baixar relatório .xlsx do lote.
• Ao retornar para a tela do PS, todos os alunos do lote aparecem listados com status Declarou Interesse — restando apenas a matrícula manual em turma.
• A matrícula em turma usa o mesmo fluxo já existente (criar CoursePeriod, criar Class, atribuir aluno via confirmEnrolled).
• Posso reenviar convite individualmente para um aluno cujo token expirou.

Como aluno convidado:

• Recebo email com link de primeiro acesso.
• Ao abrir, defino senha.
• Preencho onboarding mínimo (CPF, contatos, endereço; bloco de responsável legal se menor de idade).
• Envio a foto da carteirinha.
• Antes de concluir o onboarding (incluindo a foto), não consigo navegar para outras telas da plataforma.
• O onboarding não altera meu status na plataforma — apenas completa meus dados.
• Se o coordenador ainda não matriculou: caio no dashboard como Declarou Interesse, com aviso "Aguarde o cursinho confirmar sua turma".
• Se o coordenador já matriculou em turma antes do meu onboarding: caio no dashboard como Matriculado, com cod_enrolled válido.
• Posso usar plataforma normalmente após estar Matriculado.

Como sistema:

• PS rápido não cria FormFull no vcnafacul-form (ou cria stub conforme decisão final).
• PS rápido com expectedOpening < linhas válidas exibe warning mas permite prosseguir.
• Lote acima de 25 linhas processa em background com status polling.
• Token de primeiro acesso expira em 14 dias; expirado, requer reenvio.

---

11. Riscos e mitigações

• Aluno não consente. Mitigação: termo de uso na tela de onboarding + atestado do coordenador no upload + canal de descadastro fácil.
• Cursinho abusa do recurso para inscrever leads não consentidos. Mitigação: curadoria do admin (quickInscriptionEnabled é opt-in manual), revogação imediata, monitoramento de taxa de descadastro e reclamações.
• Email não chega (spam, typo). Mitigação: pré-visualização exibe avisos para emails com domínios suspeitos; botão de reenvio.
• Aluno nunca completa onboarding. Mitigação: dashboard do coordenador mostra "X alunos com convite pendente"; possibilidade de reenviar convite; eventualmente cancelar StudentCourse.
• Performance em lotes grandes. Mitigação: processamento assíncrono, limite máximo por upload, batching de envio de emails.

---

12. Fora de escopo (v1) — possível v2

• Importar dados completos do aluno via planilha (CPF, endereço etc.) e dispensar onboarding.
• Importar diretamente para uma Class específica.
• Importar histórico de presença/notas de turmas prévias.
• Permitir que o próprio admin (não o cursinho) suba a planilha em nome do cursinho.
• API pública/CSV-only sem interface gráfica.

---

13. Sugestão de quebra em sub-tarefas

1. Backend — modelo & permissões. Migration para PartnerPrepCourse.quickInscriptionEnabled, InscriptionCourse.quickInscription, StudentCourse.quickInscription. Endpoint admin para alternar o toggle.
2. Backend — criação de PS rápido. Extender CreateInscriptionCourseInput e InscriptionCourseService.create para aceitar quickInscription; validar autorização; pular criação de FormFull.
3. Backend — import & processamento. Novo endpoint POST /inscription-course/:id/quick-inscription/import (multipart), com parser via exceljs, validação linha-a-linha, job assíncrono, geração de JWT longo, email transacional sendQuickInscriptionInvite, criação de User + StudentCourse + logs.
4. Backend — onboarding e reenvio. Endpoint POST /quick-inscription/complete-onboarding (recebe CPF, contatos, endereço, legal guardian se menor, foto da carteirinha multipart) + endpoint POST /quick-inscription/:studentId/resend-invite. Não altera applicationStatus — apenas atualiza dados pessoais e marca photoDone = true. Reaproveita BUCKET_PROFILE e a mecânica de submitPhoto existentes.
5. Frontend — modal de criação de PS. Adicionar checkbox "Inscrição rápida" condicional, validações e textos de aviso.
6. Frontend — tela de upload. Template .xlsx, drag & drop, pré-visualização, polling de status, relatório final.
7. Frontend — onboarding do aluno. Rota nova /inscricao-rapida/onboarding, formulário, guard de rota até completar.
8. Frontend — admin. Toggle quickInscriptionEnabled no detalhe de PartnerPrepCourse.
9. Telemetria & docs. Atualizar CLAUDE.md, registrar webhook de erro, dashboard de uso.

---

14. Perguntas em aberto

Lista para discussão antes do refinamento técnico (não decididas aqui de propósito):

• (a) gerenciarPermissoesCursinho ou validarCursinho para autorizar quickInscriptionEnabled?
• (b) Aluno pode estar em PSs ativos de cursinhos diferentes simultaneamente?
• (c) Política exata de armazenamento da planilha pós-processamento (LGPD).
• (d) Em caso de email já cadastrado na plataforma, qual fluxo de "anexar" — exige confirmação manual do aluno antes de criar StudentCourse?
• (e) Texto definitivo do template de email de convite (precisa de aprovação do time de comunicação).
• (f) Métricas de sucesso pós-lançamento (qual % de conversão consideramos saudável?).