[Provas Custom] Fluxo de provas personalizadas com CustomProvaFactory + criadorId/cursinhoId

[FernandoAlmeidaPinto]

Resumo da entrega. 5 cards no total. Cria a capacidade de fazer provas personalizadas: admin escolhe uma categoria custom: true (criada no CRUD da etapa 3), define nome livre e PDF opcional, e o backend gera 1 simulado (vs. 5/3 do ENEM) via CustomProvaFactory. Adiciona também criadorId (obrigatório) e cursinhoId (opcional, null no fluxo admin) em Prova/Simulado, preparando o terreno pra etapa 6.

Documento de fundação: docs/prova-customizada-factory.md
Posição na série: 4 de 10 · Mapa da série: #66

---

Status da entrega ✅

Todos os 5 cards implementados e validados ponta-a-ponta (prova custom e ENEM criadas com sucesso no ambiente local). PRs abertos:

Card	Repo	PR
01 · schema criadorId/cursinhoId + DTO + backfill	ms-simulado	#160
02 · CustomProvaFactory (1 simulado/prova)	ms-simulado	#160
03 · dispatcher + regra bloqueado nullable + sync custom	ms-simulado	#160
04 · injeção de criadorId/cursinhoId no POST /mssimulado/prova	api-vcnafacul	#504
05 · NewProva com fluxo condicional por categoria.custom	client-vcnafacul	#644

Cards 01+02+03 entregues juntos no PR #160 (deploy unit único do ms-simulado).

Por que essa etapa

Hoje toda prova é uma prova ENEM (Dia 1/2) — factory com regras rígidas, 5 simulados filhos, nome composto. Admin não conseguia criar uma prova simples "Simuladão Mensal Novembro" com questões a dedo.

Essa etapa introduz o fluxo custom: se a categoria tem custom: true, roteia pra CustomProvaFactory (1 simulado, nome livre, PDF opcional). Reaproveita 100% do fluxo de resposta, histórico e aproveitamento — o simulado custom é indistinguível dos oficiais depois de criado. Como bônus, persiste criadorId/cursinhoId, preparando o fluxo de cursinho da etapa 6.

Decisões cravadas

• Prova.criadorId obrigatório em toda prova nova (injetado pelo api-vcnafacul via JWT).
• Prova.cursinhoId opcional (default null); sempre null no admin, populado no fluxo cursinho futuro.
• CustomProvaFactory cria exatamente 1 simulado por prova custom.
• Dispatcher roteia por categoria.custom; assinatura passou a getFactory(categoria, ano).
• Simulado.bloqueado adaptado pra quantidadeTotalQuestao === null: desbloqueia quando todas as questões estão Approved (sem critério de quantidade). Helper atingiuQuantidade.
• executeSync adaptado pra provas custom: todas as questões vão pro simulado único (sem string matching no nome livre).
• NewProva condicional: categoria custom → nome/nomeSimulado obrigatórios, PDF opcional; select filtra por selecionavel.
• Sem permissão nova — reutiliza cadastrarProvas.
• Backfill criadorId = 'system' em provas legadas antes do deploy do schema.

Pré-requisitos

• [Categoria] (etapa 1, # [Categoria] Refatoração do modelo: TipoSimulado → Categoria #65), [Unificação] (etapa 2, [Unificação] Eliminar tela Simulados admin + vista interna no ShowProva + cleanup `criarSimulado` #68) e [CRUD Categoria] (etapa 3, [CRUD Categoria] Modal admin pra criar e excluir categorias personalizadas #71) — admin precisa ter conseguido criar categorias custom: true pra escolher no NewProva.

Cards desta etapa

• Card 01 · ms-simulado · Schema criadorId/cursinhoId + DTO estendido + backfill · PR #160
• Card 02 · ms-simulado · CustomProvaFactory (6 métodos, 1 simulado/prova, transações Mongo) · PR #160
• Card 03 · ms-simulado · Dispatcher branch custom + regra bloqueado nullable + adaptação do executeSync · PR #160
• Card 04 · api-vcnafacul · Injeção de criadorId (JWT) + cursinhoId: null; arquivos opcionais · PR #504
• Card 05 · client-vcnafacul · NewProva condicional por categoria.custom (nome livre + PDF opcional) · PR #644

Ajustes descobertos na implementação

• Card 02 — construtor de Prova é (item, categoria) (2 args); verifyNumberProva é chamado pelo service (não dentro de createQuestion); getByFilter herdado da BaseRepository; CategoriaRepository dispensado (categoria já injetada).
• Card 03 — getFactory recebe (categoria, ano), não (prova): em create() a prova ainda não existe (é criada pela própria factory).
• Card 04 — guard JwtAuthGuard, PermissionsGuard (o PermissionsGuard sozinho dá 403 sem token e não popula req.user); PDF opcional precisou entrar aqui também.
• Card 05 — o select já filtrava por selecionavel (o card citava nome.includes("Enem"), desatualizado).
• 🐛 Bug pré-existente corrigido (incluído no #160) — criar qualquer prova (ENEM ou custom) dava 400 "categoria não existe" mesmo com categoria válida: o CategoriaExistValidator nunca foi registrado como provider no categoria.module, então com useContainer(..., {fallbackOnErrors:true}) o class-validator instanciava sem injeção → categoriaRepository undefined → getById lançava → validador retornava false. Fix: registrar o validador nos providers. Descoberto testando o fluxo custom ponta-a-ponta.

Coordenação de deploy

⚠️ Ordem obrigatória:

1. npm run backfill:criador-id no ms-simulado (janela de manutenção) — antes do schema novo (criadorId é required).
2. Deploy ms-simulado (#160) → api-vcnafacul (#504) → client-vcnafacul (#644).

Próximas etapas

• [Provas Cursinho] (etapa 6) — consome tudo dessa etapa: cursinhoId populado, CustomProvaFactory reaproveitada pelo fluxo cursinho, tela dedicada.

Referências

• Resumo executivo da série: Refatoração do domínio Simulado — Resumo executivo #61 · Mapa de etapas: Refatoração do domínio Simulado — Mapa de etapas #66
• Etapa 1 [Categoria]: # [Categoria] Refatoração do modelo: TipoSimulado → Categoria #65 · Etapa 2 [Unificação]: [Unificação] Eliminar tela Simulados admin + vista interna no ShowProva + cleanup `criarSimulado` #68 · Etapa 3 [CRUD Categoria]: [CRUD Categoria] Modal admin pra criar e excluir categorias personalizadas #71