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

scripts/migrations/.gitignore

@@ -0,0 +1,5 @@
+# Dumps exportados/gerados pelas migrations (dados reais — nunca commitar).
+# Só os scripts (*.sh) e docs (*.md) são versionados.
+*.json
+*.log
+backup-*/

scripts/migrations/0001-questoes-em-multiplas-provas/README.md

@@ -0,0 +1,75 @@
+# Migração 0001 — Questão Multi-Prova (Fase 2)
+
+Popula `Prova.questoesNovo` e `Simulado.questoesNovo` a partir do modelo antigo
+(`Questao.prova` + `Questao.numero`). Arrays antigos (`questoes`) permanecem
+intactos — os dois coexistem após esta fase. Nenhum consumer lê `questoesNovo`
+ainda (Fase 3+). Reversível (`$unset questoesNovo`).
+
+Os scripts NÃO conectam ao Mongo: operam sobre JSON exportado localmente.
+
+## Pré-requisitos
+
+`jq` (>=1.6), `openssl`, `bash`, e o Mongo Database Tools (`mongodump`,
+`mongoexport`, `mongoimport`). `$MONGODB` = URI do banco alvo.
+
+## Procedimento (homol primeiro, depois prod)
+
+### 1. Backup obrigatório (restore safety)
+
+```bash
+DATE=$(date +%Y%m%d-%H%M%S)
+mongodump --uri="$MONGODB" --collection=questoes  --out="./backup-$DATE/"
+mongodump --uri="$MONGODB" --collection=provas    --out="./backup-$DATE/"
+mongodump --uri="$MONGODB" --collection=simulados --out="./backup-$DATE/"
+du -sh "./backup-$DATE/"            # confirmar tamanho não-zero
+# subir ./backup-$DATE/ para R2/S3 com retenção >=90 dias; documentar o caminho no PR
+```
+
+Backup apenas destas 3 collections (NÃO `historico`).
+
+### 2. Exportar as collections (JSON array, Extended JSON relaxado = default)
+
+```bash
+mongoexport --uri="$MONGODB" --collection=questoes  --jsonArray --out=questoes.json
+mongoexport --uri="$MONGODB" --collection=provas    --jsonArray --out=provas.json
+mongoexport --uri="$MONGODB" --collection=simulados --jsonArray --out=simulados.json
+```
+
+> Caso o modelo precise de outras collections no futuro, exportá-las aqui e
+> ajustar o `migrate.sh`. Hoje só estas 3.
+
+### 3. Rodar a migração
+
+```bash
+bash migrate.sh .            # gera provas.out.json e simulados.out.json
+bash validate.sh .           # deve terminar com "✅ Validação OK" (exit 0)
+```
+
+Se `validate.sh` sair com código 1, NÃO reimportar — investigar os logs.
+
+### 4. Smoke em homol (antes de reimportar em prod)
+
+Reimporte (passo 5) em homol e confira no frontend — tudo ainda lê do array
+antigo, então deve estar idêntico:
+- DashProva abre; abrir 1 prova; abrir 1 simulado.
+- Responder 1 simulado → histórico funciona.
+
+### 5. Reimportar (drop + import — backup já salvo)
+
+```bash
+mongosh "$MONGODB" --eval 'db.provas.drop(); db.simulados.drop();'
+mongoimport --uri="$MONGODB" --collection=provas    --jsonArray --file=provas.out.json
+mongoimport --uri="$MONGODB" --collection=simulados --jsonArray --file=simulados.out.json
+```
+
+`questoes` **não muda** nesta fase — não reimportar.
+
+### 6. Produção
+
+Repetir 1→5 em janela de manutenção (~10min), sem deploys/writes concorrentes.
+Guardar logs (`bash migrate.sh . > migrate-prod-$DATE.log 2>&1`). Backup
+obrigatório antes. Se algo falhar → `rollback.md`.
+
+## Idempotência
+
+`migrate.sh` sobrescreve `questoesNovo`; rodar 2x = mesmo resultado.

scripts/migrations/0001-questoes-em-multiplas-provas/migrate.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+#
+# Migração 0001 — Questão Multi-Prova (Fase 2).
+# Popula Prova.questoesNovo e Simulado.questoesNovo a partir do modelo antigo
+# (Questao.prova + Questao.numero). Arrays antigos ("questoes") intactos.
+#
+# Uso:  bash migrate.sh [dir]   (dir default = diretório atual)
+# Entrada (mongoexport --jsonArray, Extended JSON):
+#   <dir>/questoes.json  <dir>/provas.json  <dir>/simulados.json
+# Saída:
+#   <dir>/provas.out.json  <dir>/simulados.out.json
+#
+# Idempotente: sobrescreve questoesNovo. Não conecta ao Mongo.
+set -euo pipefail
+
+DIR="${1:-.}"
+QUESTOES="$DIR/questoes.json"
+PROVAS="$DIR/provas.json"
+SIMULADOS="$DIR/simulados.json"
+
+for f in "$QUESTOES" "$PROVAS" "$SIMULADOS"; do
+  [ -f "$f" ] || { echo "❌ Arquivo não encontrado: $f" >&2; exit 1; }
+done
+
+# Gera N ObjectIds (24-hex) como array JSON de strings.
+gen_ids() {
+  n="$1"
+  if [ "$n" -eq 0 ]; then echo "[]"; return; fi
+  i=0
+  while [ "$i" -lt "$n" ]; do
+    openssl rand -hex 12
+    i=$((i + 1))
+  done | jq -R . | jq -s .
+}
+
+# ============ PROVA ============
+nq=$(jq '[.[] | select(.prova != null and (.numero != null))] | length' "$QUESTOES")
+echo "[STEP 1] Questoes com prova+numero: $nq" >&2
+prova_ids=$(gen_ids "$nq")
+
+jq -n \
+  --slurpfile questoes "$QUESTOES" \
+  --slurpfile provas "$PROVAS" \
+  --argjson idpool "$prova_ids" '
+  ($questoes[0]) as $qs
+  | ($provas[0]) as $ps
+  | ( [ $qs[]
+        | select(.prova != null and (.numero != null))
+        | { provaId: (.prova | if type == "object" then .["$oid"] else . end), questao: {"$oid": ._id["$oid"]}, numero: .numero } ]
+      | to_entries
+      | map(.value + { _id: {"$oid": $idpool[.key]} }) ) as $entries
+  | ( $entries
+      | group_by(.provaId)
+      | map({ key: .[0].provaId, value: (map({_id, questao, numero})) })
+      | from_entries ) as $byProva
+  | $ps | map(.questoesNovo = ($byProva[._id["$oid"]] // []))
+' > "$DIR/provas.out.json"
+
+total_prova=$(jq '[.[] | .questoesNovo | length] | add // 0' "$DIR/provas.out.json")
+echo "[STEP 2] Entries em provas.out.json: $total_prova" >&2
+
+orfas=$(jq -n --slurpfile q "$QUESTOES" --slurpfile p "$PROVAS" '
+  ($p[0] | map(._id["$oid"])) as $ids
+  | [ $q[0][]
+      | select(.prova != null and (.numero != null))
+      | select(((.prova | if type == "object" then .["$oid"] else . end)) as $pid | ($ids | index($pid)) | not) ] | length')
+echo "[STEP 2b] Questoes órfãs (prova fora do dump): $orfas" >&2
+
+# ============ SIMULADO ============
+ns=$(jq -n --slurpfile q "$QUESTOES" --slurpfile s "$SIMULADOS" '
+  ($q[0] | map(select(.numero != null)) | INDEX(._id["$oid"])) as $qidx
+  | [ $s[0][] | (.questoes // [])[] | .["$oid"] | select($qidx[.] != null) ] | length')
+echo "[STEP 3] Refs de simulado com numero: $ns" >&2
+sim_ids=$(gen_ids "$ns")
+
+jq -n \
+  --slurpfile questoes "$QUESTOES" \
+  --slurpfile simulados "$SIMULADOS" \
+  --argjson idpool "$sim_ids" '
+  ($questoes[0] | map(select(.numero != null)) | INDEX(._id["$oid"])) as $qidx
+  | ($simulados[0]) as $ss
+  | ( [ $ss | to_entries[]
+        | .key as $si | .value as $sim
+        | ($sim.questoes // [])[]
+        | .["$oid"] as $ref
+        | select($qidx[$ref] != null)
+        | { si: $si, questao: {"$oid": $ref}, numero: $qidx[$ref].numero } ]
+      | to_entries
+      | map(.value + { _id: {"$oid": $idpool[.key]} }) ) as $entries
+  | ( $entries
+      | group_by(.si)
+      | map({ key: (.[0].si | tostring), value: (map({_id, questao, numero})) })
+      | from_entries ) as $bySim
+  | [ $ss | to_entries[]
+      | .value + { questoesNovo: ($bySim[(.key | tostring)] // []) } ]
+' > "$DIR/simulados.out.json"
+
+total_sim=$(jq '[.[] | .questoesNovo | length] | add // 0' "$DIR/simulados.out.json")
+echo "[STEP 3b] Entries em simulados.out.json: $total_sim" >&2
+
+echo "[DONE] provas.out.json ($total_prova entries), simulados.out.json ($total_sim entries)." >&2

scripts/migrations/0001-questoes-em-multiplas-provas/rollback.md

@@ -0,0 +1,27 @@
+# Rollback — Migração 0001 (Fase 2)
+
+O sistema continua lendo do array antigo (`questoes`), que permanece intacto.
+Rollback é trivial nesta fase.
+
+## Se algo deu errado durante/logo após a migração
+
+```bash
+mongosh "$MONGODB" --eval '
+  db.provas.updateMany({}, { $unset: { questoesNovo: "" } });
+  db.simulados.updateMany({}, { $unset: { questoesNovo: "" } });
+'
+```
+
+Reverter o PR do Card 01 (schemas) só se necessário.
+
+## Se a migração corrompeu dado antigo (não deveria — só adiciona campo)
+
+Restaurar do backup:
+
+```bash
+mongorestore --uri="$MONGODB" --drop --collection=provas    ./backup-<DATE>/<db>/provas.bson
+mongorestore --uri="$MONGODB" --drop --collection=simulados ./backup-<DATE>/<db>/simulados.bson
+mongorestore --uri="$MONGODB" --drop --collection=questoes  ./backup-<DATE>/<db>/questoes.bson
+```
+
+Backup fica arquivado por precaução (retenção >=90 dias).

scripts/migrations/0001-questoes-em-multiplas-provas/validate.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+#
+# Validação da migração 0001. Roda sobre os JSONs (input + output), sem Mongo.
+# Uso: bash validate.sh [dir]   (default = diretório atual)
+# Requer: questoes.json, provas.out.json, simulados.out.json
+# Exit 0 = ok, 1 = falha.
+set -euo pipefail
+
+DIR="${1:-.}"
+QUESTOES="$DIR/questoes.json"
+PROVAS_OUT="$DIR/provas.out.json"
+SIMULADOS_OUT="$DIR/simulados.out.json"
+
+for f in "$QUESTOES" "$PROVAS_OUT" "$SIMULADOS_OUT"; do
+  [ -f "$f" ] || { echo "❌ Arquivo não encontrado: $f" >&2; exit 1; }
+done
+
+fail=0
+
+# [1] Total estrito: sum(prova.questoesNovo) == count(questoes com prova+numero
+#     cuja prova EXISTE no dump). Órfãs (prova fora do dump) são descontadas —
+#     elas têm prova+numero mas corretamente não entram em nenhum questoesNovo.
+expected=$(jq -n --slurpfile q "$QUESTOES" --slurpfile p "$PROVAS_OUT" '
+  ($p[0] | map(._id["$oid"])) as $ids
+  | [ $q[0][] | select(.prova != null and (.numero != null))
+      | select(((.prova | if type == "object" then .["$oid"] else . end)) as $pid | ($ids | index($pid))) ] | length')
+got=$(jq '[.[] | .questoesNovo | length] | add // 0' "$PROVAS_OUT")
+if [ "$expected" = "$got" ]; then
+  echo "✓ [1] Total prova entries = $got (esperado $expected)"
+else
+  echo "✗ [1] Total prova entries = $got, esperado $expected" >&2; fail=1
+fi
+
+# [2] Idiomáticas preservadas: nº de grupos (prova,numero) com >=2 igual input vs output
+exp_pairs=$(jq -n --slurpfile q "$QUESTOES" '
+  [ $q[0][] | select(.prova != null and (.numero != null))
+    | ((.prova | if type == "object" then .["$oid"] else . end) + "|" + (.numero | tostring)) ]
+  | group_by(.) | map(select(length >= 2)) | length')
+got_pairs=$(jq '
+  [ .[] | (.questoesNovo // [])
+    | group_by(.numero) | map(select(length >= 2)) | length ] | add // 0' "$PROVAS_OUT")
+if [ "$exp_pairs" = "$got_pairs" ]; then
+  echo "✓ [2] Grupos idiomáticos (>=2 mesmo numero) = $got_pairs"
+else
+  echo "✗ [2] Idiomáticas: esperado $exp_pairs grupos, obtido $got_pairs" >&2; fail=1
+fi
+
+# [3] Simulado: questoesNovo.length == count(refs com numero!=null)
+sim_bad=$(jq -n --slurpfile q "$QUESTOES" --slurpfile s "$SIMULADOS_OUT" '
+  ($q[0] | map(select(.numero != null)) | INDEX(._id["$oid"])) as $qidx
+  | [ $s[0][]
+      | ( [ (.questoes // [])[] | .["$oid"] | select($qidx[.] != null) ] | length ) as $exp
+      | select((.questoesNovo | length) != $exp)
+      | ._id["$oid"] ]')
+sim_bad_count=$(echo "$sim_bad" | jq 'length')
+if [ "$sim_bad_count" = "0" ]; then
+  echo "✓ [3] Todos os simulados com questoesNovo.length correto"
+else
+  echo "✗ [3] $sim_bad_count simulados com contagem errada: $(echo "$sim_bad" | jq -c '.[0:5]')" >&2; fail=1
+fi
+
+# [4] Órfãs (warn, não falha)
+orfas=$(jq -n --slurpfile q "$QUESTOES" --slurpfile p "$PROVAS_OUT" '
+  ($p[0] | map(._id["$oid"])) as $ids
+  | [ $q[0][] | select(.prova != null and (.numero != null))
+      | select(((.prova | if type == "object" then .["$oid"] else . end)) as $pid | ($ids | index($pid)) | not) ] | length')
+echo "ℹ [4] Questoes órfãs (prova fora do dump): $orfas (warn)"
+
+if [ "$fail" -eq 0 ]; then
+  echo "✅ Validação OK"; exit 0
+else
+  echo "❌ Validação falhou"; exit 1
+fi

scripts/migrations/0002-cleanup-questoes-antigas/README.md

@@ -0,0 +1,96 @@
+# Migração 0002 — Cleanup Questões Antigas (Etapa 9, final)
+
+Cleanup final da Etapa 9. Dropa o array antigo de refs (`questoes`), renomeia o
+subdoc `questoesNovo` → `questoes` em `Prova`/`Simulado`, e em `Questao` renomeia
+`prova` → `provaBase` (ponteiro pra prova de origem) e **remove** `numero` — o
+número passa a viver só no relacionamento (`Prova.questoes[].numero`). No dash,
+casa-se `provaBase` com `provasContendo` pra obter prova+número. Questão sem prova
+fica sem `provaBase`.
+
+Como a **0001**, os scripts de transformação **NÃO conectam ao Mongo**: operam
+sobre JSON exportado localmente e geram `*.out.json` para reimportar.
+
+A **derrubada/criação de índices** é a única parte que precisa do banco (não sai
+no `mongoexport` nem entra no `mongoimport`) e por isso fica num script final
+separado, `indices.sh`, rodado por último.
+
+Os scripts:
+
+| Script | Conecta ao Mongo? | O que faz |
+|--------|:-:|-----------|
+| `cleanup.sh`  | não | rename `questoesNovo`→`questoes`; `prova`→`provaBase` + remove `numero` → `*.out.json` |
+| `validate.sh` | não | valida os `*.out.json` |
+| `indices.sh`  | **sim** | dropa índices legados e cria os índices reversos finais |
+
+## Pré-requisitos
+
+`jq` (>=1.6), `bash`, o Mongo Database Tools (`mongodump`, `mongoexport`,
+`mongoimport`) e `mongosh` (só para `indices.sh`). `$MONGODB` = URI do banco alvo.
+
+## Procedimento (homol primeiro, depois prod)
+
+Rodar **somente** após a 0001 ter sido aplicada (reimportada) e o deploy do
+código anterior (Card 05) estar validado.
+
+### 1. Backup obrigatório (restore safety)
+
+```bash
+mongodump --uri="$MONGODB" \
+  --collection=provas \
+  --collection=simulados \
+  --collection=questoes \
+  --out=./backup-0002
+du -sh ./backup-0002            # confirmar tamanho não-zero
+# subir ./backup-0002 para R2/S3 com retenção >=90 dias; anotar o caminho no PR
+```
+
+### 2. Exportar as collections (JSON array, Extended JSON relaxado = default)
+
+```bash
+mongoexport --uri="$MONGODB" --collection=provas    --jsonArray --out=provas.json
+mongoexport --uri="$MONGODB" --collection=simulados --jsonArray --out=simulados.json
+mongoexport --uri="$MONGODB" --collection=questoes  --jsonArray --out=questoes.json
+```
+
+### 3. Rodar o cleanup
+
+```bash
+bash cleanup.sh .            # gera provas.out.json, simulados.out.json, questoes.out.json
+bash validate.sh .           # deve terminar com "✅ validate 0002 OK" (exit 0)
+```
+
+O pré-check do `cleanup.sh` **aborta** se achar prova/simulado com `questoesNovo`
+vazio mas `questoes` antigo populado (sinal de que a 0001 não rodou, ou de que o
+dump já foi migrado). Se sair com código 1, NÃO reimportar — investigar os logs.
+
+### 4. Reimportar (drop + import — backup já salvo)
+
+```bash
+mongosh "$MONGODB" --eval 'db.provas.drop(); db.simulados.drop(); db.questoes.drop();'
+mongoimport --uri="$MONGODB" --collection=provas    --jsonArray --file=provas.out.json
+mongoimport --uri="$MONGODB" --collection=simulados --jsonArray --file=simulados.out.json
+mongoimport --uri="$MONGODB" --collection=questoes  --jsonArray --file=questoes.out.json
+```
+
+### 5. Índices (conecta ao banco) — logo após reimportar
+
+```bash
+MONGODB='...' bash indices.sh    # deve terminar com "indices 0002 OK"
+```
+
+### 6. Deploy do código do Card 07a — imediatamente
+
+O código do Card 07a lê `questoes` no shape novo `[{questao, numero}]`. Fazer o
+deploy logo após reimportar + `indices.sh`, para não deixar o banco no shape novo
+com código antigo em execução.
+
+### 7. Produção
+
+Repetir 1→6 em janela de manutenção, sem deploys/writes concorrentes. Backup
+obrigatório antes. Se algo falhar → `rollback.md`.
+
+## Idempotência
+
+`cleanup.sh` reescreve os `*.out.json` sem tocar nos `.json` de entrada — rodar
+2x sobre o mesmo dump dá o mesmo resultado. `indices.sh` também é idempotente
+(`dropIndex` ignora índice inexistente; `createIndex` é no-op se já existe).