# [Categoria] Refatoração do modelo: TipoSimulado → Categoria

[FernandoAlmeidaPinto]

Resumo da entrega. 7 cards no total (6 obrigatórios + 1 opcional). Coloca o sistema em um modelo de domínio mais limpo, com Categoria carregando exame + custom + selecionavel, e remove a duplicação e ambiguidade que existia ao longo dos schemas de Prova/Simulado.

Documento de fundação: docs/categoria-simulado.md
Posição na série: 1 de 10 (fundação — todos os outros docs dependem desta)

---

Por que essa etapa

Hoje o TipoSimulado carrega só nome, duracao e quantidadeTotalQuestao. A relação com Exame está espalhada (cada Prova tem seu próprio exame, separado do tipo). O dispatcher de factories funciona por convenção de nome e ano, sem uma fonte única de verdade. E a permissão criarSimulado é uma legada do passado que confunde devs novos.

Essa etapa consolida o modelo: TipoSimulado vira Categoria (nome mais natural), absorve o exame como referência obrigatória, e ganha o discriminador custom que prepara o terreno pro fluxo de provas personalizadas (etapas futuras). O dispatcher passa a receber a Prova direto e lê tudo da categoria embutida. Prova.exame deixa de existir como campo separado.

Decisões cravadas

• Renomear TipoSimulado → Categoria em todas as camadas.
• Categoria.exame: ref<Exame> obrigatório.
• Categoria.custom: boolean (default false) — sinaliza fluxo customizado (consumido em etapas futuras).
• Categoria.selecionavel: boolean (default true) — distingue categorias usáveis no nível de Prova (Enem Dia 1, Enem Dia 2, Personalizadas) das que são só classificador interno (Linguagens, Matemática, Humanas, Natureza).
• Categoria.descricao: string (opcional, default '').
• Categoria.quantidadeTotalQuestao passa a ser nullable (cobre futuro tipo "Personalizado livre").
• Prova.tipo → Prova.categoria; remove Prova.exame (vem de categoria.exame).
• Simulado.tipo → Simulado.categoria.
• Dispatcher ProvaFactory.getFactory(prova) recebe a prova populada e lê prova.categoria.custom, prova.categoria.exame.nome, prova.ano.
• Seed do novo Exame "Personalizado".
• Migração de dados: script Python que mapeia tipos seedados conhecidos com seus exame/custom/selecionavel corretos.

Pré-requisitos

Nenhum. Esta é a fundação da série.

Cards desta etapa

Ordem de execução obrigatória: 1 → 2 → 3 → 4 → 5 (sequencial por dependência).
Em paralelo: Card 6 (migração) pode ser desenvolvido em paralelo com 3-5, mas roda em produção junto do deploy do código.
Independente: Card 7 (bugfix opcional) pode ir em qualquer momento.

• Card 01 · ms-simulado · Rename do módulo TipoSimulado → Categoria (naming puro)

  • PR só de naming, sem mudança de schema. Build verde antes do próximo PR mexer no que importa.
  • Estimativa: S
  • Bloqueia: 02, 03

• Card 02 · ms-simulado · Adicionar campos novos em Categoria + seed Exame "Personalizado"

  • exame, custom, selecionavel, descricao + tornar quantidadeTotalQuestao nullable. Seed do Exame "Personalizado".
  • Estimativa: S-M
  • Bloqueia: 03
  • Bloqueado por: 01

• Card 03 · ms-simulado · Refactor da relação Prova/Simulado/Categoria + dispatcher + factories ENEM

  • PR mais pesado da etapa. Renomeia campos, remove Prova.exame, refatora dispatcher, atualiza ~15 callsites nas factories ENEM e no sync.
  • Estimativa: L
  • Bloqueia: 04, 05
  • Bloqueado por: 01, 02

• Card 04 · api-vcnafacul · DTOs espelho + contratos atualizados

  • Atualiza DTOs do proxy e garante contratos alinhados com ms-simulado refatorado. Renomeia rota tipos → categoria.
  • Estimativa: S
  • Bloqueia: 05
  • Bloqueado por: 03

• Card 05 · client-vcnafacul · Rename services + tipos + ajuste das 6 telas

  • Renomeio em massa no frontend. Ajusta as ~6 telas que leem simulado.tipo.x ou historico.simulado.tipo.x.
  • Estimativa: M
  • Bloqueado por: 04

• Card 06 · scripts · Script Python de migração de dados (MongoDB)

  • Script standalone que recebe JSON dumps das collections e gera os JSONs migrados. Procedimento documentado (mongodump → backup → script → validar → mongorestore).
  • Estimativa: M
  • Pode rodar em paralelo com Cards 3-5; execução em prod junto do deploy do código.

• Card 07 · ms-simulado · Bugfix calcularMediaAproveitamento (OPCIONAL)

  • Tech debt detectado durante a exploração inicial. Não bloqueia features; corrige cálculo de média ponderada em estatísticas agregadas.
  • Estimativa: XS
  • Totalmente independente — pode ir em qualquer momento.

Coordenação de deploy

O deploy desta etapa exige coordenação porque envolve 3 projetos + migração de dados:

1. Backup das 3 collections (tiposimulados, provas, simulados) com mongodump. Arquivar intocado.
2. Rodar script de migração (Card 06) sobre o dump → gera collections migradas.
3. Aplicar collections migradas com mongorestore --drop.
4. Deploy do ms-simulado (Cards 01, 02, 03) — código novo lê o banco migrado.
5. Deploy do api-vcnafacul (Card 04) imediatamente após — contratos alinhados com ms-simulado.
6. Deploy do client-vcnafacul (Card 05) — consome a API atualizada.

Janela de manutenção curta (~10-20min). Idealmente em homol primeiro pra validar end-to-end.

Riscos consolidados

• Naming pass quebra build em algum lugar exótico (string literal, mensagem de erro). Mitigação: grep agressivo + smoke test.
• Populate de categoria.exame esquecido em algum service → undefined.nome em runtime. Cobertura por testes.
• Migration sem backup = inrreversível. Procedimento explícito blinda.
• Timing entre deploys: api-vcnafacul antes de ms-simulado → quebra temporária. Coordenar.

Próximas etapas (referência)

Depois de Categoria, a série segue:

Etapa	Label	Doc	Status
2	[Unificação]	unificacao-simulados-provas.md	escrito
3	[CRUD Categoria]	crud-categoria-simulado.md	escrito
4	[Provas Custom]	prova-customizada-factory.md	escrito
5	[Janela Simulado]	simulado-janela-disponibilidade.md	escrito
6	[Provas Cursinho]	provas-cursinho.md	escrito
7	[Cartão Resposta]	cartao-resposta.md	escrito
8	[Compartilhamento]	simulados-compartilhados.md	escrito
9	[Questão Multi-Prova]	questoes-em-multiplas-provas.md	escrito (Release A.5)
10	[Duplicação Questão]	duplicacao-questoes.md	escrito

Referências

• Doc completo de design: docs/categoria-simulado.md
• Resumo executivo de toda a série: docs/resumo-time.md
• Pendências e itens em aberto: docs/pendencias.md