Refatoração do domínio Simulado — Resumo executivo

[FernandoAlmeidaPinto]

Refatoração do domínio Simulado — Resumo executivo

Para: apresentação ao time
De: Fernando Almeida
Data: 2026-05-26

Documento curto pra discussão em reunião. Cada item aqui tem doc detalhado próprio na mesma pasta. Use esse como mapa.

---

Por quê

Objetivo final: permitir que o cursinho parceiro consiga criar sua própria prova/simulado, aplicar (online ou em papel via cartão), receber as respostas dos estudantes, e ver o desempenho deles.

Tudo o que está nessa série de docs é caminho pra esse objetivo. Quebrei em 7 entregas porque cada uma é um PR/release independente e algumas têm dependências entre si.

---

Os 10 docs em uma tabela

#	Doc	O que entrega	Bloqueia
1	[categoria-simulado.md](https://github.com/orgs/vcnafacul/discussions/65)	Renomeia TipoSimulado → Categoria. Embute exame e custom na categoria. Refatora o dispatcher de factories.	Todos os outros 9
2	unificacao-simulados-provas.md	Elimina a tela DashSimulado admin. Vista de simulados passa pra dentro do ShowProva. Remove permissão criarSimulado.	3, 4, 5, 6, 7, 8, 9, 10
3	crud-categoria-simulado.md	Modal pra admin criar/excluir categorias (sem edit).	nada — usa 2
4	prova-customizada-factory.md	CustomProvaFactory pra criar provas custom (1 simulado por prova). Adiciona criadorId e cursinhoId em Prova/Simulado.	6, 7, 8
5	simulado-janela-disponibilidade.md	Adiciona disponivelDe/disponivelAte no simulado. Janela temporal de disponibilidade.	nada
6	provas-cursinho.md	Tela de Provas do lado do cursinho (espelho da admin, filtrada por cursinhoId). Permissões visualizarProvasCursinho e cadastrarProvasCursinho.	7, 8
7	cartao-resposta.md	Geração e leitura de cartão de resposta (OMR). Novo microserviço ms-omr Python. Matrícula em StudentCourse.	nada
8	simulados-compartilhados.md	Cursinho Y descobre/favorita simulados criados por cursinho X. Aluno do Y vê na nova seção "Simulados do meu cursinho" em mainSimulate.	nada
9	questoes-em-multiplas-provas.md	Refactor profundo (Release A.5): numero sai de Questao e vai pro relacionamento (Prova.questoes e Simulado.questoes viram arrays de {questao, numero}). Habilita reuso de questão entre provas.	Bloqueia 10 (precisa do schema novo).
10	duplicacao-questoes.md	"Duplicar com lastro": admin gera cópia editável de questão. Nova Questao.origem (de onde veio) e Questao.copias[] (filhas que nasceram dela).	nada

---

Decisões transversais (atravessam vários docs)

Vale alinhar com o time logo de cara:

• TipoSimulado vira Categoria em todas as camadas. Renomeio massivo: schema, módulo, repository, DTOs, services, UI.
• Categoria carrega exame (ref) e custom (bool). A Prova aponta pra Categoria (mantém ref). Não tem mais Prova.exame ou Prova.custom separados.
• Categoria.selecionavel: boolean distingue categorias que aparecem no select de criação de prova (Enem Dia 1, Enem Dia 2, Personalizadas) das que são só classificador interno (Linguagens, Matemática, etc., usadas pelas factories ENEM).
• CRUD de Categoria é imutável — só criar e excluir, sem edit. Exclusão bloqueada se há simulado usando. Isso protege as 6 categorias seedadas (que sempre têm simulado).
• criadorId em toda prova (não só custom). Vem do JWT do usuário logado.
• cursinhoId persistido sempre — null no fluxo admin, preenchido no fluxo cursinho.
• Dispatcher do factory lê prova.categoria.custom pra decidir CustomProvaFactory vs ENEM, e prova.categoria.exame.nome + prova.ano pra escolher a versão da factory ENEM.
• Permissão criarSimulado é removida — com cuidado de migração. ⚠️ Pegadinha descoberta: no frontend essa permissão é apresentada com label "Visualizar Simulados" (RolesLabel em client-vcnafacul/src/enums/roles/roles.ts linhas 43-47). Quem hoje marca "Visualizar Simulados" no painel está marcando criarSimulado: true no banco. Antes de dropar a coluna, migrar: pra cada role com criar_simulado = true, garantir visualizar_provas = true. Senão admins perdem acesso aos simulados. Detalhes em doc 2 §8.1.
• visualizarSimulado não existe e não deve ser criada — verificado por grep com variações. visualizarProvas (admin) e visualizarProvasCursinho (cursinho) já cobrem, porque a visualização dos simulados acontece dentro do ShowProva. Registrado em doc 2 §8.2 pra evitar que alguém crie essa permissão por reflexo no futuro.
• Permissões do cursinho seguem convenção <acao><Recurso>Cursinho (visualizarProvasCursinho, cadastrarProvasCursinho, futuras gerenciarRespostasCursinho).
• Cartão de resposta é fluxo síncrono do ponto de vista do cliente (sem fila Redis entre api-vcnafacul e ms-omr na primeira release). Frontend orquestra envio serial de cartões.

---

Fluxo simplificado de implementação

A ordem certa minimiza retrabalho. Cada doc tem seu próprio plano de implementação detalhado; aqui é o sumário.

Etapa 1 — Fundação (doc 1)

Renomeio + remodelo.

• Rename TipoSimulado/ → Categoria/ no ms-simulado (PR só de naming, build verde antes de mexer em comportamento).
• Adicionar exame, custom, selecionavel, descricao em Categoria.
• Renomear Prova.tipo → Prova.categoria. Remover Prova.exame.
• Renomear Simulado.tipo → Simulado.categoria.
• Refatorar dispatcher ProvaFactory.getFactory(prova).
• Atualizar todos os callsites (~15 ocorrências nas factories ENEM).
• Migração de dados: script Python sobre os JSONs de homol/prod.
• Frontend: rename de getTipos → getCategorias, ITipoSimulado → ICategoria, ajuste em ~6 arquivos que leem simulado.tipo.x.

Etapa 2 — Limpeza de UX e cleanup de permissões (doc 2)

Antes do CRUD, porque adiciona um slot pra ele.

• Eliminar DashSimulado (arquivo e rota).
• Adicionar vista interna no ShowProva (state view: 'details' | 'simulados').
• Carregar prova completa (getProvaById) ao abrir modal.
• Slot pro botão "Gerenciar Categorias" na barra de ações.
• Cleanup do criarSimulado em 14 lugares (entity, DTO, service, seeds, frontend, modal de role, rotas).
• Migrar guard de DELETE /mssimulado/simulado/:id pra cadastrarProvas.

Etapa 3 — CRUD de Categoria (doc 3) — pode rodar em paralelo com 4 e 5

Plugga no slot da etapa 2.

• Modal ManageCategorias na DashProva (acessado pelo botão "Gerenciar Categorias").
• Backend: PATCH não existe, DELETE enriquecido com countByCategoria e bloqueio em uso.
• Formulário simplificado: Exame, qtd, duração, prefixo do nome (nome final auto-gerado).
• Proxies em api-vcnafacul.

Etapa 4 — Factory Custom (doc 4)

Adiciona criadorId/cursinhoId — pré-requisito pro cursinho (doc 6) e cartão (doc 7).

• CustomProvaFactory que cria 1 simulado por prova custom.
• criadorId em Prova (todas as provas, sempre setado) e Simulado (propagado).
• cursinhoId em Prova/Simulado (sempre persistido, null no admin).
• NewProva modal aprende a setar nome livre + PDF opcional quando categoria custom.
• Ajuste no sync (ProvaService.executeSync) pra não rodar string matching ENEM em provas custom.

Etapa 5 — Janela de disponibilidade (doc 5) — independente, pode entrar a qualquer momento depois de 1+2

Feature isolada.

• disponivelDe/disponivelAte em Simulado (nullable).
• Regra de disponibilidade: !bloqueado && (de==null || agora>=de) && (até==null || agora<=até).
• Endpoint PATCH /v1/simulado/:id/disponibilidade.
• Filtro em getAvailable e gate em getToAnswer.
• Edição inline na vista de simulados do ShowProva (datetime-local).
• Grace period: submit não checa janela (só abrir).

Etapa 6 — Tela de Provas do cursinho (doc 6)

Depende de 1, 2 e 4.

• Nova página pages/partnerPrepProvas/ (espelha DashProva).
• Endpoints cursinho-scoped (/mssimulado/cursinho/prova/*).
• Filtro por cursinhoId no GET /v1/prova do ms-simulado.
• 2 permissões novas (visualizarProvasCursinho, cadastrarProvasCursinho).
• Entrada no menu admin do cursinho.
• Cursinho cria prova → backend injeta cursinhoId resolvido via Collaborator + criadorId.

Etapa 7 — Cartão de resposta (doc 7)

O passo mais complexo. Depende de 1, 2, 4, 6.

• StudentCourse.matricula (8 dígitos YYYY0001, unique por cursinho).
• Historico ganha imageCartaoR2Key e origem.
• Novo microserviço ms-omr (Python + FastAPI + OMRChecker).
• Geração de PDF do cartão (api-vcnafacul) com QR + grids + fiducial markers.
• Upload síncrono single-card (POST /mssimulado/cartao-resposta) com frontend orquestrando serial.
• Sem persistência de "LeituraCartao" — relatório vive no state do frontend, baixável em CSV.
• Lacunas reconhecidas: UI de atribuição de matrícula, permissão dedicada de upload, design final do PDF.

Etapa 8 — Compartilhamento de simulados (doc 8)

Depende de 1, 4, 6. Pode rodar em paralelo com 7.

• Nova entidade SimuladoFavorito no ms-simulado: (cursinhoId, simulado, favoritadoPor) única.
• Endpoints novos: listar disponíveis pra favoritar, favoritar, desfavoritar, listar favoritos, listar combinada pro estudante.
• Cursinho Y descobre simulados de outros cursinhos via modal "Simulados compartilhados" na pages/partnerPrepProvas.
• Aluno do cursinho Y ganha nova seção "Simulados do meu cursinho" em pages/mainSimulate — vê próprios do cursinho + favoritados.
• Default: todo simulado criado por cursinho é compartilhável (opt-out fica como item futuro).
• Reaproveita permissões existentes (cadastrarProvasCursinho, visualizarProvasCursinho).

Etapa 9 — Questão em múltiplas provas (doc 9) — Release A.5

Refactor profundo. Depende de 1 e 2. Decidido executar entre Fundação e Catálogo Gerenciável.

• Questao perde prova e numero. Vira só "questão como ente" (conteúdo + classificação + status + estatísticas globais).
• Prova.questoes e Simulado.questoes viram arrays de subdocumentos { questao: ref, numero: number }.
• Mesma questão pode estar em N provas com numeração própria por prova. Mesma questão pode estar em N simulados com numeração própria.
• Caso ENEM (números 1-5 com Inglês/Espanhol competidos) passa a ser modelado naturalmente sem hack de frente1 como tiebreaker.
• ~30 referências em ms-simulado precisam ser refatoradas. Script de migração interno (Node + Mongoose), versionado no repo, com backup obrigatório (§8 do doc 9).
• Subdividido em 5 fases PR-sized (§9 do doc 9): schemas → migração de dados → read-side → write-side → cleanup. Cada fase shippa isoladamente, com double-write durante a transição.
• Doc 9 §6.6 detalha como cada regra de validação ENEM (idiomáticas 1-5/91-95, getMissingNumbers, verifyNumberProva, EnemService.validate) migra pro novo modelo preservando comportamento.

Etapa 10 — Duplicação de questão com linhagem (doc 10)

Depende de doc 9 finalizado. Roda após a Release A.5 completar.

• Novos campos em Questao: origem: ref<Questao> | null (de onde veio) e copias: ref<Questao>[] (filhas).
• Novo endpoint POST /v1/questao/:id/duplicar cria nova Questao editável independentemente, com lastro.
• Cópia começa órfã (sem prova), em Pending, com estatísticas zeradas, compartilhando refs de imagens com a original.
• Editar Q1 não afeta cópias; editar Q2 (cópia) não afeta Q1.
• Original soft-deletada → cópias continuam, badge mostra "Copiada de [questão excluída]".
• Frontend: botão "Duplicar" no modal de questão, badge "Cópia de Q[id]" + link "Ver original", contador + drawer "Ver cópias" na original.
• Pequena entrega, sem migração de dados, sem complexidade de schema. Naturalmente segue como Release H.

---

O que NÃO está sendo feito nesta série

Pra alinhar expectativa:

• App mobile — fora de escopo. Quando entrar, recebe anexo no doc 7 cobrindo captura via câmera.
• Permissões do cursinho consolidadas — doc separado a escrever. Por enquanto cada feature cria as suas inline.
• Histórico/relatório agregado do cursinho — já no planejamento da equipe, doc separado. Esse é o passo final do ciclo (cursinho cria → aplica → vê resultado).
• UI de atribuição de matrícula — campo StudentCourse.matricula é criado no doc 7, mas a UI de atribuição é doc separado.
• Tela de "cartões recusados" persistente — trade-off aceito; relatório vive na sessão frontend.
• Review/dispute manual de leitura de cartão — futura.
• Janelas recorrentes ou janelas por turma — só janela única na primeira versão (doc 5).

---

Decisões que precisam de OK do time

Pontos onde vale conferir alinhamento antes de codar:

1. Renomeação TipoSimulado → Categoria — afeta dezenas de arquivos. Vale fazer em PR único de naming.
2. Quem cria categorias? Só admin (alterarPermissao). Cursinho não tem acesso ao CRUD (admin gerencia o catálogo global).
3. Convenção de nome pra categorias personalizadas: auto-gerado "{Prefixo} {qtd}q {duracao}min" (ex.: "Personalizado 30q 60min"). Admin pode passar prefixo opcional.
4. Prova.custom: boolean foi descartado em favor de prova.categoria.custom (Leitura B). Uma fonte de verdade, sem snapshot.
5. Volume de cartões esperado: ~1000/mês. Arquitetura dimensionada pra isso. Se for muito maior, revisitar (fila Redis ms-omr, paralelismo).
6. OMRChecker (Python, open-source) é a escolha pra engine OMR. Alternativa comercial (Aspose etc.) descartada por custo recorrente.
7. cursinhoId sempre persistido, mesmo no fluxo admin (sempre null). Facilita o dia em que outros fluxos forem criados.
8. Migração do criarSimulado — confirmar com produto/operações se a estratégia "quem tinha criarSimulado=true ganha visualizarProvas=true automaticamente, e depois a coluna é dropada" está OK. Comunicar admins via release notes: "A permissão 'Visualizar Simulados' virou 'Visualizar Provas'".
9. Doc 9 (refactor questão-prova-simulado) será Release A.5 — decidido com o time. Subdividido em 5 fases internas (schemas → migração de dados → read-side → write-side → cleanup), permitindo shippar parcial. Confirmar com produto/operações o procedimento de migração com backup e janelas de manutenção curtas (~10min duas vezes).

---

Sequência de releases sugerida

Cada bullet é um conjunto de PRs que faz sentido ir junto:

1. Release A — Fundação: docs 1 + 2 (renomeação + UI base + cleanup permissões).
2. Release A.5 — Refactor questão-prova-simulado (doc 9). Recomendado executar aqui pra evitar retrabalho nas releases seguintes. Tecnicamente independente das releases B-G mas mexe em arquivos que elas vão tocar.
3. Release B — Catálogo gerenciável: doc 3 (CRUD Categoria).
4. Release C — Provas custom: doc 4 (factory custom + criadorId/cursinhoId).
5. Release D — Janela: doc 5 (independente, pode antecipar ou postergar).
6. Release E — Cursinho: doc 6 (tela do cursinho).
7. Release F — Cartão: doc 7 (cartão de resposta + ms-omr novo).
8. Release G — Compartilhamento: doc 8 (favoritos entre cursinhos + seção do aluno).
9. Release H — Duplicação: doc 10 (questão com lastro de cópias). Roda após A.5 estar completa.

Releases A, B, C fazem sentido próximas (não há valor pra usuário até a C). A.5 é tech-debt-buster + enabler; se postergar, retrabalho nos PRs subsequentes. D pode ir entre qualquer ponto após A. E pode ir após C. F precisa de C+E. G precisa de C+E e pode rodar em paralelo com F. H precisa de A.5 finalizada e pode ir em qualquer ponto depois.

---

Material de apoio

• docs/pendencias.md — meta-doc vivo com tudo que está em aberto.
• Detalhes de cada decisão: ler o doc correspondente. Cada um tem seção de Decisões, Plano de Implementação, Riscos e Itens Futuros.
• Diagramas/wireframes: dentro dos próprios docs (texto ASCII pra rascunhos).

Qualquer dúvida me chama — escrevi todos os 7 docs, então tenho contexto completo.

[FernandoAlmeidaPinto]

Pendências e Docs Futuros

Propósito: documento vivo com tudo que está em aberto na série de docs do domínio Simulado — itens que precisam virar doc novo, lacunas dentro de docs existentes, decisões em aberto, tech debt identificado.

Como usar:

• Ao escrever um doc novo: mover a entrada da seção "Docs ainda a escrever" pra "Histórico" (ou apagar).
• Ao descobrir nova lacuna: adicionar na seção correspondente.
• Ao tomar decisão pendente: mover pra um doc existente ou criar novo.

Última atualização: 2026-05-26

---

Visão geral da série

Ordem de execução atual:

#	Doc	Status
—	pendencias.md (este)	vivo
—	resumo-time.md	resumo executivo
1	categoria-simulado.md	escrito
2	unificacao-simulados-provas.md	escrito
3	crud-categoria-simulado.md	escrito
4	prova-customizada-factory.md	escrito
5	simulado-janela-disponibilidade.md	escrito
6	provas-cursinho.md	escrito
7	cartao-resposta.md	escrito (com lacunas explícitas)
8	simulados-compartilhados.md	escrito (com lacunas explícitas)
9	questoes-em-multiplas-provas.md	escrito (refactor profundo; Release A.5)
10	duplicacao-questoes.md	escrito (pequeno, roda após doc 9 finalizado)

Itens previstos sem doc ainda:

• Permissões do cursinho — modelo e catálogo (ver §1.1 abaixo)
• Histórico/relatório do cursinho (ver §1.2 — já no planejamento da equipe)
• UI de atribuição de matrícula (ver §1.3)

---

1. Docs ainda a escrever

1.1 Permissões do cursinho — modelo e catálogo

Por que: vários docs (6 introduz visualizarProvasCursinho/cadastrarProvasCursinho inline, 7 prevê uma gerenciarRespostasCursinho, futuros docs de cartões recusados/relatório/etc. também vão precisar) criam permissões dispersamente. Falta um doc consolidado que defina convenção, hierarquia e catálogo.

Escopo proposto:

• Convenção de naming (<acao><Recurso>Cursinho, mesma de gerenciarPermissoesCursinho).
• Lógica de hierarquia (cadastrar implica visualizar) — já aplicada em alguns lugares.
• Catálogo unificado: enumera todas as permissões cursinho-scoped, existentes e novas, com descrição clara do que cada uma libera.
• Migration consolidada pras colunas novas em roles.
• Seed strategy: quem do cursinho ganha o quê por default.

Bloqueado por: nada — pode entrar a qualquer momento.

Bloqueia (parcialmente):

• Doc 6 (já escrito) usa permissões inline — atualizar pra referenciar esse novo doc.
• Doc 7 (já escrito) tem lacuna explícita (§10.1) esperando gerenciarRespostasCursinho ser definida aqui.
• Qualquer doc futuro que precise de nova permissão.

Posição na série: seria #8 se entrar após os atuais, ou inserir antes de #6 e renumerar (mais coerente conceitualmente, mais trabalhoso pra renumeração — decidir na hora).

Status: planejado, sem prazo.

1.2 Histórico/relatório do cursinho

Por que: a tela de Provas do Cursinho (doc 6) e a leitura de Cartão de Resposta (doc 7) só fazem sentido pleno se o cursinho consegue ver o desempenho agregado dos alunos. Sem esse doc, o ciclo "criar prova → aplicar → ver resultado" fica incompleto. Provavelmente o objetivo final de toda essa série de docs.

Escopo proposto:

• Endpoint(s) de histórico agregado por (cursinho, simulado): aproveitamento médio, mediana, ranking interno, distribuição por questão.
• Endpoint(s) de histórico por (cursinho, aluno) e (cursinho, turma).
• Tela na área do cursinho mostrando esses dados visualmente.
• Filtros: turma, período, simulado específico, categoria.
• Export CSV/PDF do relatório.
• Possivelmente dashboards (gráficos).

Bloqueado por: doc 6 (provas-cursinho — escopo de cursinho), parcialmente doc 7 (cartão alimenta o mesmo Historico mas não bloqueia leitura).

Bloqueia: nenhum doc, mas é o objetivo final do ciclo.

Status: já no planejamento da equipe, conforme conversa de 12/2025. Doc não vai ser escrito por mim nesta série; espaço reservado aqui pra referência.

1.3 UI de atribuição de matrícula

Por que: doc 7 (Cartão de Resposta) adiciona StudentCourse.matricula mas não desenha onde o cursinho atribui matrículas aos alunos. Sem UI, ninguém consegue usar a feature de cartão.

Escopo proposto:

• Tab/modal em alguma tela de gerenciamento de alunos do cursinho (provavelmente pages/partnerClassWithStudents ou similar).
• Botão "Atribuir matrícula" por aluno (chama gerarProximaMatricula definido no doc 7).
• Bulk action: "Atribuir matrícula a todos os alunos do cursinho sem matrícula".
• Edição manual da matrícula (caso o cursinho prefira numerar diferente).
• Validação visual de unicidade.

Bloqueado por: doc 7 (precisa do campo matricula no schema).

Bloqueia: usabilidade completa do doc 7. Tecnicamente é parte do ciclo.

Posição: poderia ser doc separado (#9 ou similar) OU seção/anexo dentro de doc 7. Decisão pendente.

Status: lacuna conhecida, depende do doc 7.

---

2. Lacunas em docs existentes

Itens deixados em aberto dentro dos docs escritos. Quando o doc dependente for escrito ou a decisão for tomada, atualizar o doc original.

2.1 Tech debt — calcularMediaAproveitamento (doc 1)

Onde: notado durante exploração inicial. historico.service.calcularMediaAproveitamento tem média incremental que atualiza times numa variável local em alguns caminhos mas não persiste de volta no Map em outros.

Impacto: estatísticas agregadas com leve desvio. Não bloqueia features.

Como resolver: pequeno PR de bugfix, sem necessitar doc próprio. Pode acompanhar o PR da implementação do doc 1.

2.2 Cleanup do criarSimulado — endpoints protegidos (doc 2)

Onde: doc 2 §8.1 lista os endpoints protegidos pelo criarSimulado que precisam ser revisados durante o cleanup:

• POST /mssimulado/simulado (criar simulado direto): "investigar callers; se ninguém usa, remover endpoint".
• DELETE /mssimulado/simulado/:id: migrar guard para cadastrarProvasCursinho.

Status: decisão registrada no doc, execução na hora da implementação. Não bloqueia outros docs.

2.3 Permissão temporária pra upload de cartão (doc 7)

Onde: doc 7 §10.1. O endpoint POST /mssimulado/cartao-resposta cai temporariamente em Permissions.cadastrarProvasCursinho enquanto o doc de permissões cursinho não fica pronto.

Como resolve: quando doc §1.1 acima for escrito, definir gerenciarRespostasCursinho (ou nome similar) e atualizar o guard. Doc 7 menciona explicitamente que vai precisar dessa atualização.

2.4 UI de atribuição de matrícula (doc 7)

Onde: doc 7 §10.2 e §10.3. Doc 7 introduz o campo e o helper gerarProximaMatricula(), mas não desenha a UI.

Como resolve: doc §1.3 acima ou expansão do doc 7 com seção nova. Vide §1.3 pra detalhes.

2.5 Geração em batch de matrículas (doc 7)

Onde: doc 7 §10.3. Cursinho com 200 alunos legados precisa de bulk action.

Como resolve: parte da mesma entrega de §1.3.

2.6 Design visual final do cartão (doc 7)

Onde: doc 7 §10.8. Doc define O QUE o cartão contém (componentes), mas não o desenho final (fonte, espaçamentos exatos, paleta).

Como resolve: fase de design antes da implementação. Pode ser uma issue de design, não doc próprio. Atenção: PDF e template YAML do OMRChecker têm que ser co-desenvolvidos.

2.7 Tela de "cartões recusados" persistente (doc 7)

Onde: doc 7 §10.6. Decidimos não persistir; relatório vive na sessão do frontend. Se cursinho sai da tela perde.

Como resolve: doc futuro cartao-recusado-historico.md (ainda não planejado) introduz CartaoRecusado em api-vcnafacul + tela do cursinho. Não bloqueia primeira release; tradeoff aceito.

2.8 Cleanup automático de imagens órfãs no R2 (doc 7)

Onde: doc 7 §10.5. Imagens de cartões recusados ficam no R2 sem ponteiro de nenhuma entidade.

Como resolve: cron job mensal deletando cartoes/* mais antigos que N dias que não estão referenciados por Historico.imageCartaoR2Key. Tech debt, pode ir em PR separado depois do doc 7 implementado.

2.9 Review/dispute UX (doc 7)

Onde: doc 7 §10.7. Sem UI dedicada pro caso "aluno diz que OMR leu errado".

Workaround atual: colaborador baixa imagem do R2 manualmente e confere. Funciona mas é doloroso.

Como resolve: doc futuro (sem plano atual) introduz tela de revisão lado a lado com edição manual.

2.10 Métricas de uso do cartão (doc 7)

Onde: doc 7 §10.9.

Como resolve: logs estruturados no ms-omr + scraper Prometheus + Grafana (já existe no projeto). Não bloqueia primeira release.

2.11 Opt-in de compartilhamento (doc 8)

Onde: doc 8 §11.1. Decisão default: tudo criado por cursinho é compartilhável automaticamente. Se a equipe quiser opt-in explícito, adicionar Simulado.compartilhavel: boolean (default true em migração inicial) + filtro nos endpoints.

Como resolve: decisão na implementação. Mudança pequena se quiser opt-in.

2.12 Cursinho X vê quem favoritou seus simulados (doc 8)

Onde: doc 8 §11.2. Métrica "este simulado foi favoritado por N cursinhos" não escopada na primeira release. Útil pra motivar criadores.

Como resolve: item futuro pequeno; índice reverso { simulado: 1 } já existe.

2.13 Aproveitamento segmentado por cursinho (doc 8)

Onde: doc 8 §11.3. Hoje Simulado.aproveitamento é global (todas as respostas, de todos os cursinhos que favoritaram). Pra ranking interno do cursinho Y, seria útil segmentar.

Como resolve: endpoint agregado GET /v1/simulado/:id/aproveitamento?cursinhoId=Y. Item futuro.

2.14 Janela própria por cursinho favoritador (doc 8)

Onde: doc 8 §13. Cursinho Y favorita simulado de X mas quer janela própria. Hoje herda a janela do criador.

Como resolve: doc futuro pode adicionar campos disponivelDe/disponivelAte em SimuladoFavorito (e regra de disponibilidade lê eles em vez do simulado).

2.15 UI pra reaproveitar questão entre provas (doc 9)

Onde: doc 9 §11.1. O refactor abre infra pra mesma questão estar em N provas, mas não há UI pra "adicionar questão existente a esta prova". Admin continua criando questões só vinculadas a uma prova por vez.

Como resolve: doc futuro com tela de seleção (banco de questões com filtros), botão "Adicionar à prova X com numero N". Esta UI também é necessária pro doc 10 (cópias órfãs precisam ser adicionadas a provas via essa tela).

2.16 Versionamento de questão (doc 9)

Onde: doc 9 §11.2. Hoje editar uma questão afeta TODAS as provas onde aparece. Pode ser indesejado.

Como resolve: doc futuro complexo com Q-versions onde cada Prova.questoes[i] aponta pra uma versão específica.

2.17 Renumeração em massa de simulado (doc 9)

Onde: doc 9 §11.3. Tela "renumerar todas as questões deste simulado de 1 a N na ordem que escolher" — infra fica pronta após doc 9, falta UI.

2.18 Estatísticas globais vs por prova (doc 9)

Onde: doc 9 §11.4. Questao.acertos é global; após o refactor, fica difícil ter "taxa de acerto desta questão nesta prova específica".

Como resolve: agregar Historico (caro) ou adicionar campos derivados em Prova.questoes[i]. Item de evolução de analytics.

2.19 Decisão de ordem de execução do doc 9 — RESOLVIDA

Onde: doc 9 §10.

Decidida: doc 9 será Release A.5, entre Fundação (docs 1+2) e Catálogo Gerenciável (doc 3). Doc 9 §10 e resumo-time refletem isso. Doc 9 §9 detalha as 5 fases internas (PR-sized) da implementação.

Status: ✅ decisão tomada, sem mais ação pendente aqui.

2.20 Visualização em árvore genealógica de linhagem (doc 10)

Onde: doc 10 §10.1. Primeira release mostra só pai e filhos diretos. Cadeia profunda (Q1 → Q2 → Q3 → ...) exige navegação manual seguindo origem.

Como resolve: doc futuro com tela "árvore de linhagem" mostrando o grafo. Útil quando a feature ganhar tração.

2.21 Diff visual entre original e cópia (doc 10)

Onde: doc 10 §10.2. 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 resolve: componente de diff que recebe duas questões e compara campo a campo. Doc futuro.

2.22 Estatísticas agregadas pela linhagem (doc 10)

Onde: doc 10 §10.4. Cada cópia tem stats próprias. Métrica "família Q1: 80 acertos somados" não existe nativamente.

Como resolve: endpoint agregado ou cálculo on-demand no frontend.

2.23 Permissão dedicada "duplicarQuestao" (doc 10)

Onde: doc 10 §10.3. Hoje reaproveita criarQuestao. Se surgir caso "esse cargo pode duplicar mas não criar do zero", separa.

Como resolve: parte do doc futuro de permissões cursinho (§1.1 deste pendencias) ou doc próprio.

---

3. Decisões em aberto

(Nenhuma no momento — todas as decisões dos docs 1-7 estão fechadas e refletidas nos respectivos textos.)

---

4. Outros itens convergentes / contextuais

4.1 App mobile

O Vc na Facul tem app mobile, fora do repo deste contexto. Foi explicitamente omitido de todos os docs escritos.

Quando entrar em escopo:

• Doc 7 (Cartão de Resposta): anexo cobrindo captura via câmera (overlay de alinhamento, autofoco, qualidade), upload otimizado.
• Possivelmente: aluno responde simulados pelo app (não bloqueado por nenhum doc desta série).
• Possivelmente: cursinho gerencia provas/cartões pelo app.

Status: sem prazo. Reintroduzir quando relevante.

4.2 Fila Redis entre api-vcnafacul e ms-omr

Doc 7 §4 decide chamada HTTP direta (síncrona) entre api-vcnafacul e ms-omr. Vale a pena trocar pra fila Redis se:

• Volume virar muito maior (>10k cartões/mês).
• ms-omr virar fonte de instabilidade.
• Concorrência precisar subir acima de N=5.

A API entre api-vcnafacul e ms-omr é interna; trocar HTTP por fila não afeta o resto do sistema. Aceitável manter como tech debt latente.

4.3 PWA com getUserMedia

Alternativa ao app nativo pra captura via celular sem instalar app. Ficou fora do escopo da primeira release do doc 7. Pode entrar como entrega menor:

• Tela mobile-friendly no client-vcnafacul.
• navigator.mediaDevices.getUserMedia({ video: { facingMode: 'environment' } }).
• Overlay de alinhamento desenhado em CSS.
• Captura via canvas → upload pelo mesmo endpoint.

Quando faz sentido: se o app mobile não entrar em escopo logo. Ou se o caso de uso de "estudante tira foto do próprio cartão" emergir.

4.4 Geração de PDF — escolha técnica

Doc 7 §6.1 sugere pdf-lib (Node-native, leve) vs puppeteer (renderiza HTML→PDF, mais flexível pra design rico). Decisão delegada pra implementação. Vale registrar a escolha quando feita.

---

5. Itens removidos / arquivados

(Nenhum por enquanto. Seção fica disponível pra rastrear o que saiu de escopo ao longo do tempo.)