[Etapa 9] Questão Multi-Prova — backend ms-simulado (cutover)

[FernandoAlmeidaPinto]

Etapa 9 — Questão Multi-Prova (Release A.5) · backend ms-simulado

Refactor profundo do domínio Simulado: numero sai de dentro da Questao e vai pro relacionamento (Prova.questoes[] / Simulado.questoes[] = [{ questao, numero }]), e Questao.prova/numero são removidos. Habilita reuso da mesma questão entre N provas, idiomáticas ENEM naturais (2 questões mesmo número) e stats globais.

Entregue via cutover single-write (não double-write): o modelo novo entrou como campo paralelo questoesNovo (Card 01), foi populado por migração em janela (Card 02, script 0001), o código passou a ler/escrever só o novo array (Cards 03-05), e o cleanup final (Cards 07a) renomeou questoesNovo→questoes e removeu o legado.

O que mudou (cards 01→07a nesta cadeia)

• Schemas: Prova.questoes/Simulado.questoes viram subdoc [{questao,numero}]; Questao sem prova/numero.
• Single-write: helper question-container.helpers.ts (add/remove/updateNumero); repositories/services/factories leem e escrevem só o novo array.
• Factories ENEM/Custom: regras A-F preservadas bit-a-bit (idiomáticas 1-5 / 91-95); updateQuestion reconcilia número no subdoc.
• Readers legados → reverse-lookup em Prova.questoes (injeta ProvaModel no QuestaoRepository): canInsertQuestion, delete, updateStatus, getAll (→ provasContendo), updateClassificacao, processAnswer (ano), GetSimuladoById.
• Removido executeSync + endpoints POST /prova/sync e GET /prova/sync/report (reconstruía os arrays a partir de Questao.prova; obsoleto no novo modelo).
• Banco de questões: getAll retorna provasContendo: [{provaId, provaNome, numero}]; sort default updatedAt.

Migração de dados — ⚠️ IRREVERSÍVEL

Script scripts/migrations/0002-cleanup-questoes-antigas/ (bash + mongosh): $unset array antigo → $rename questoesNovo→questoes → $unset Questao.prova/numero + índices reversos. Rodado pelo time, em janela, com backup mongodump obrigatório (R2/S3 ≥90d). Rollback = restaurar backup.

⚠️ Ordem de deploy (lockstep, todas as 3 cadeias juntas)

backup → rodar 0002 (mongosh) → validate.sh → deploy ms → deploy api → deploy client. O contrato de saída muda (provasContendo, answer sem prova), então não pode ir sozinho.

Testes

npm run build verde; suíte 24 suites / 140 testes verde (mock-style). Migração/validate testados por script (sem harness de CI).

PRs relacionados (mesma etapa, deploy conjunto): api-vcnafacul e client-vcnafacul.

🤖 Generated with Claude Code