# 10. Duplicação de questão com rastreamento de linhagem

[FernandoAlmeidaPinto]

Status: 🔒 Bloqueado por:

• docs/categoria-simulado.md — modelo Categoria estabilizado.
• docs/questoes-em-multiplas-provas.md (doc 9) — Questao já perdeu prova e numero; criar uma Questao independente "órfã" (sem vínculo a prova ainda) virou natural após o refactor. Doc 10 é uma evolução conceitual em cima do doc 9.

Recomendação de execução: após doc 9 estar completo (Fase 5 do §9 do doc 9). Não conflita com docs 4-8.

Serviços afetados: ms-simulado (schema + endpoint + service), api-vcnafacul (proxy), client-vcnafacul (botão de duplicar + badges de linhagem).

Autor: Fernando Almeida
Última atualização: 2026-05-26

---

1. Contexto

Após o doc 9, a mesma Questao pode estar em N provas com numerações independentes (Prova.questoes[i].numero). Isso cobre o caso "questão exata é reutilizável", mas não cobre "quero uma variante levemente modificada".

Cenário real: admin tem uma questão excelente de Matemática (Q1) na prova ENEM 2023. Quer criar uma variação dela — mesmo conceito, mas com números diferentes nas alternativas — pra usar numa prova nova (Personalizada Cursinho X). Hoje (e após doc 9) ele precisa:

1. Criar uma Questao nova do zero, copiando o texto manualmente.
2. Perde o lastro: ninguém sabe que essa variação nasceu da Q1.

Doc 10 introduz a primitiva "duplicar com lastro": a partir de uma questão existente, o admin gera uma cópia editável que registra sua origem e a original passa a saber quais cópias existem dela.

2. Objetivo

• Adicionar uma ação "Duplicar" na UI de questão que cria uma nova Questao editável independentemente.
• A nova questão guarda referência à questão de origem (origem).
• A questão original guarda lista das questões que nasceram dela (copias).
• Permitir navegação visual no lastro: "ver a original", "ver as cópias".

3. Escopo

Dentro do escopo

• Novo campo origem: ref<Questao> | null em Questao.
• Novo campo copias: ref<Questao>[] em Questao.
• Novo endpoint POST /v1/questao/:id/duplicar no ms-simulado.
• Proxy correspondente em api-vcnafacul, gated por Permissions.criarQuestao (já existente).
• Frontend:
  • Botão "Duplicar" no modal de visualização/edição de questão.
  • Badge "Copiada de Q[id]" no header da questão duplicada.
  • Link "Ver original" na cópia (abre a original).
  • Contador e link "Ver cópias (N)" na original.

Fora do escopo

• Visualização em árvore genealógica com múltiplos níveis de descendência. Primeira release mostra só pais e filhos diretos.
• Diff visual entre original e cópia (lado a lado destacando diferenças).
• Merge de questões (juntar duas em uma).
• Permissão dedicada "duplicarQuestao" — reaproveita criarQuestao.
• Estatísticas agregadas pelo lastro (somar acertos de toda a família).
• Auto-duplicação por trigger (ex.: "duplicar quando 80% dos alunos errar").

4. Decisões de design

Decisão	Escolha	Justificativa
Campos herdados pela cópia	Todos exceto: _id (novo), createdAt (now), status (= Pending), acertos (= 0), quantidadeResposta (= 0), quantidadeSimulado (= 0), origem (= sourceId), copias (= [])	Cópia é "nova" no sistema — precisa validação, sem estatísticas herdadas.
Cópia entra automaticamente em alguma prova/simulado?	Não. Começa órfã. Admin adiciona via fluxo do doc 9 ("adicionar questão existente a uma prova").	Separação de responsabilidades. "Duplicar" cria a Questao; adicionar a uma prova é outra ação.
Imagens / assets	Cópia compartilha as URLs (refs) — não duplica arquivos no R2	Storage não dobra. Edição de uma imagem na cópia precisaria upload novo (mesmo fluxo de edição comum).
Status inicial da cópia	Pending (precisa nova validação por admin)	Cópia é semanticamente uma questão "não-aprovada-ainda", mesmo que tenha sido copiada de uma aprovada. Aprovação re-feita garante revisão consciente.
Permissão	Reaproveita criarQuestao	Quem cria questão também duplica. Sem permissão nova.
Cópia da cópia	Permitida, sem limite hard de profundidade	Q1 → Q2 → Q3 forma cadeia. Doc 10 só registra o pai imediato em origem.
Original é deletada (soft delete)	Cópias continuam com origem apontando pra ID soft-deleted. UI mostra "Copiada de [questão excluída]"	Lastro não é destruído quando origem some.
copias array em questão muito copiada	Sem limite hard na primeira release	Improvável > 100 cópias. Se virar problema, paginar.
Loops no lastro	Não permitidos por construção — só copia "pra frente" (cópia nasce nova). Sem ciclos.	Q1 não pode virar cópia de Q2 que veio dela.
Numeração da cópia	Sem número (não tá em prova ainda)	Após doc 9, numero mora em Prova.questoes[i]. Cópia órfã não tem número até ser adicionada.
Cópia editável independentemente da original	Sim	Toda a graça da feature. Editar Q2 não afeta Q1.
Edição da original afeta cópias?	Não	Cópias são instâncias independentes.

5. Modelo de dados

5.1 Acréscimos em Questao

@Schema({ timestamps: true, versionKey: false })
class Questao extends QuestaoReview {
  // ... campos existentes (após doc 9: sem prova, sem numero)

  @Prop({ ref: Questao.name, type: ObjectId, required: false, default: null })
  origem?: Questao;                        // de onde veio. null se é original.

  @Prop({ type: [{ ref: 'Questao', type: ObjectId }], default: [] })
  copias: Questao[];                       // questões que nasceram desta.
}

5.2 Índices

• { origem: 1 } em Questao — pra reverse lookup eficiente (encontrar todas as cópias de uma questão). Mas como copias array já vive no documento da original, esse índice é menos crítico. Adicionar só se análise de performance pedir.

5.3 Migration

Sem migração de dados necessária. Os dois campos novos têm defaults (null e []); documentos existentes continuam válidos.

6. Endpoint de duplicação

6.1 POST /v1/questao/:id/duplicar

Body: vazio ({}).

Response 201:

{
  "_id": "new_questao_id",
  "textoQuestao": "... (copiado da original)",
  "pergunta": "...",
  "textoAlternativaA": "...",
  // ... todas as alternativas + imagens (mesmas refs)
  "alternativa": "B",
  "enemArea": "Matemática",
  "frente1": "...",
  "materia": "...",
  "status": "Pending",
  "acertos": 0,
  "quantidadeResposta": 0,
  "quantidadeSimulado": 0,
  "origem": "source_questao_id",
  "copias": [],
  "createdAt": "<now>",
  "updatedAt": "<now>"
}

Erros possíveis:

• 404 se a questão original não existir.
• 403 se o caller não tem criarQuestao.

6.2 Implementação no QuestaoService.duplicar(sourceId)

async duplicar(sourceId: string): Promise<Questao> {
  const source = await this.repository.getById(sourceId);
  if (!source) throw new NotFoundException();

  const novaQuestao = new Questao();
  // Copia campos relevantes
  Object.assign(novaQuestao, {
    textoQuestao: source.textoQuestao,
    pergunta: source.pergunta,
    textoAlternativaA: source.textoAlternativaA,
    imageAlternativaA: source.imageAlternativaA,
    // ... B, C, D, E
    alternativa: source.alternativa,
    enemArea: source.enemArea,
    frente1: source.frente1,
    frente2: source.frente2,
    frente3: source.frente3,
    materia: source.materia,
    imageId: source.imageId,
    files: source.files,
    contentFormat: source.contentFormat,
    assets: source.assets,
    // Não copia: status, acertos, quantidadeResposta, quantidadeSimulado, _id
    status: Status.Pending,
    acertos: 0,
    quantidadeResposta: 0,
    quantidadeSimulado: 0,
    origem: source._id,
    copias: [],
  });

  // Transação Mongo
  const session = await this.repository.startSession();
  session.startTransaction();
  try {
    const created = await this.repository.create(novaQuestao);
    // Atualiza a original adicionando esta nova nas cópias
    await this.repository.model.updateOne(
      { _id: source._id },
      { $push: { copias: created._id } },
      { session },
    );
    await session.commitTransaction();
    return created;
  } catch (err) {
    await session.abortTransaction();
    throw err;
  } finally {
    session.endSession();
  }
}

6.3 Controller

@Post(':id/duplicar')
@UseGuards(PermissionsGuard)
@SetMetadata(PermissionsGuard.name, Permissions.criarQuestao)
async duplicar(@Param('id') id: string) {
  return this.service.duplicar(id);
}

6.4 Proxy em api-vcnafacul

POST /mssimulado/questao/:id/duplicar, autenticado, permissão criarQuestao. Sem lógica de domínio — só proxy.

7. Frontend

7.1 Botão "Duplicar"

No modal de visualização da questão (ou na listagem), adicionar botão:

<Button
  disabled={!permissao[Roles.criarQuestao]}
  onClick={() => handleDuplicar(questao._id)}
>
  Duplicar
</Button>

Fluxo do handleDuplicar:

1. Confirmação ("Criar uma cópia editável desta questão? Você poderá editar a cópia sem afetar a original.").
2. POST /mssimulado/questao/:id/duplicar.
3. Recebe a nova questão.
4. Redireciona pro modal de edição da cópia (ou abre tab nova com a cópia).

7.2 Badge "Cópia de"

No header da questão (modal ou card), quando origem != null:

{questao.origem && (
  <Badge variant="info">
    Cópia de Q{shortId(questao.origem)}
    <Link onClick={() => abrirQuestao(questao.origem)}> Ver original →</Link>
  </Badge>
)}

7.3 Contador de cópias na original

Quando copias.length > 0:

<div>
  Tem {questao.copias.length} cópias derivada(s) desta questão.
  <Button onClick={() => abrirListaCopias(questao._id)}>
    Ver cópias
  </Button>
</div>

O botão abre um sub-modal ou drawer com a lista de cópias (cards compactos), permitindo navegar pra qualquer uma.

7.4 Tela / drawer "Ver cópias"

Layout simples, lista de cards:

┌─ Cópias derivadas de Q[id] ─────────────────────────────[×]──┐
│  3 cópias registradas                                        │
├──────────────────────────────────────────────────────────────┤
│  ┌────────────────────────────────────────────────────────┐  │
│  │ Q[id2]                                  [Pending]      │  │
│  │ Criada em 15/mar/2026 por <admin>                      │  │
│  │ Em provas: Personalizado Cursinho X                    │  │
│  │                                          [Abrir]       │  │
│  └────────────────────────────────────────────────────────┘  │
│  ┌────────────────────────────────────────────────────────┐  │
│  │ Q[id3]                                  [Approved]     │  │
│  │ ...                                                    │  │
│  └────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────┘

"Em provas" lista as provas que contêm essa cópia — combina com lookup reverso introduzido no doc 9 (questoes.questao: id).

7.5 Tipo TypeScript

IQuestao ganha:

origem?: string | null;          // id da original (ou populate parcial: { _id, textoQuestao })
copias?: string[];               // ids das cópias

8. Casos especiais

8.1 Questão original soft-deletada

Se a admin deletar (soft) a questão original, a cópia continua existindo. O origem continua apontando pro ID antigo.

Frontend: ao tentar abrir a original pelo botão "Ver original", o backend responde 410/404. UI mostra mensagem:

"A questão original (Q[id]) foi excluída. Esta cópia continua válida."

8.2 Cópia da cópia (cadeia)

Q1 → Q2 → Q3:

• Q1.copias contém [Q2._id]
• Q2.origem = Q1._id
• Q2.copias contém [Q3._id]
• Q3.origem = Q2._id

O lastro é só "pai imediato" — não tem campo "ancestral original". Pra visualizar a cadeia completa, o frontend faz traversal: começa em Q3, segue origem recursivamente até chegar em uma questão com origem == null (a original raiz).

8.3 Estatísticas

Cada cópia tem acertos, quantidadeResposta, quantidadeSimulado próprios. Não há agregação pela linhagem na primeira release.

Item futuro: endpoint GET /v1/questao/:id/lineage-stats que soma stats da família.

8.4 Aprovação independente

Cópia começa em Pending. Admin precisa aprovar (mesmo fluxo de qualquer questão nova). Aprovação da original não propaga pra cópias — cada uma é independente.

8.5 Edição da original

Editar Q1 (texto, alternativas, etc.) não afeta Q2 (que é cópia). As duas são instâncias independentes.

9. Plano de implementação

Backend ms-simulado

1. Adicionar origem e copias no schema Questao.
2. Implementar QuestaoService.duplicar(sourceId) com transação Mongo.
3. Implementar endpoint POST /v1/questao/:id/duplicar no QuestaoController.
4. Testes unitários (cópia gerada com campos corretos, original tem copias atualizado).
5. Teste de integração (cópia + edição + aprovação).

Backend api-vcnafacul

6. Proxy POST /mssimulado/questao/:id/duplicar com guard criarQuestao.
7. Atualizar QuestaoDTO (output) pra incluir origem e copias.

Frontend client-vcnafacul

8. Atualizar tipo IQuestao com novos campos.
9. Service duplicarQuestao.ts.
10. Botão "Duplicar" no modal de questão (gated por criarQuestao).
11. Badge "Cópia de" + link "Ver original".
12. Contador + drawer/modal "Ver cópias" na original.
13. Lookup reverso "em quais provas essa cópia está" (combina com doc 9).
14. Mensagem amigável quando original é soft-deletada.

Testes

15. Smoke test: criar Q1, duplicar pra Q2, editar Q2, adicionar Q2 a uma prova Personalizada, conferir lastro.
16. Cópia da cópia: Q1 → Q2 → Q3, conferir traversal.
17. Original deletada: Q1 soft-delete, conferir que Q2 continua acessível e UI mostra mensagem.

10. Lacunas e itens em aberto

10.1 Visualização em árvore genealógica

Primeira release mostra só pai e filhos diretos. Pra entender "Q5 veio de Q4 que veio de Q3 que veio de Q2 que veio de Q1", admin precisa navegar manualmente.

Como resolveria: tela dedicada de "árvore de linhagem" mostrando o grafo. Doc futuro.

10.2 Diff visual entre original e cópia

Pra admin entender O QUE mudou entre Q1 e Q2 (texto da pergunta, qual alternativa, etc.), faltaria um lado-a-lado com diffs destacados.

Como resolveria: componente de diff que recebe duas questões e compara campo a campo.

10.3 Permissão dedicada "duplicarQuestao"

Hoje reaproveita criarQuestao. Se algum dia surgir caso "esse cargo pode duplicar mas não criar do zero", separa.

10.4 Estatísticas agregadas pela linhagem

Q1.acertos = 50, Q2.acertos = 30 (Q2 é cópia). Métrica "família Q1: 80 acertos" não existe nativamente.

Como resolveria: endpoint agregado ou cálculo on-demand no frontend (sum em todas da linhagem).

10.5 Merge de questões (juntar Q2 em Q1)

Caso reverso: admin tem duas questões e quer "fundir" em uma. Não suportado.

10.6 Auto-duplicação por trigger

Caso: "questão com taxa de erro > 80% gera cópia automática pra revisão". Não suportado.

10.7 Provas em que a cópia foi inserida

A UI de "Ver cópias" mostra "Em provas: X, Y". Isso depende do lookup reverso do doc 9 (Prova.questoes.questao).

Se o doc 10 for shippado antes do doc 9 finalizar (improvável, dado o status de bloqueio), essa parte da UI fica vazia. Sequência correta evita problema.

11. Riscos

• Loops no lastro: impossível por construção (cópia nasce nova; não tem como original virar cópia retroativamente).
• copias array crescer demais: improvável > 100. Se acontecer, paginar essa visualização.
• Confusão "esta é original ou cópia?": badge "Cópia de" + link "Ver original" mitiga.
• Soft delete da original: lastro continua válido conceitualmente. UI lida com o caso.
• Cópia órfã esquecida: admin duplica e nunca adiciona em prova. Fica solta no banco. Não é problema (questão pode existir sem prova após doc 9), mas vale futuro: tela "questões sem prova" pra cleanup.
• Performance do drawer "Ver cópias" com lookup reverso de provas: query potencialmente cara se cópia tá em muitas provas. Aceitável pra primeira release.

12. Itens futuros

• Visualização em árvore genealógica multi-nível.
• Diff visual lado a lado entre questões da linhagem.
• Permissão dedicada duplicarQuestao.
• Estatísticas agregadas pela linhagem (família).
• Merge/fusão de questões.
• Auto-duplicação por trigger (taxa de erro, idade).
• Tela "questões sem prova" pra cleanup.
• Cópia em batch (duplicar 10 questões de uma vez).
• Templates de duplicação ("duplicar e já trocar a frente1 pra X").