[Janela Simulado] Disponibilidade temporal do simulado (disponivelDe/disponivelAte)

[FernandoAlmeidaPinto]

Resumo da etapa. 4 cards no total. Adiciona janela de disponibilidade opcional por simulado (disponivelDe / disponivelAte), complementar ao bloqueado atual. Admin edita as datas inline na vista de simulados do ShowProva; aluno só vê o que está dentro da janela (via getAvailable); backend faz gate em getToAnswer (403 se fora). POST /answer não é gated — grace period pra quem começou dentro da janela.

Documento de fundação: docs/simulado-janela-disponibilidade.md
Posição na série: 5 de 10 · Mapa da série: #66

---

Status

📋 Planejada — os 4 cards já estão no GitHub Project #2 na coluna To Do. Ainda não implementada.

Card	Repo	Issue
01 · schema disponivelDe/disponivelAte + availability + índice	ms-simulado	#161
02 · PATCH /disponibilidade + filtro getAvailable + gate getToAnswer	ms-simulado	#162
03 · proxy PATCH /disponibilidade + DTOs	api-vcnafacul	#505
04 · vista de simulados: edição inline + status visual + toast 403	client-vcnafacul	#645

Por que essa etapa

Hoje o único gate de disponibilidade é o Simulado.bloqueado (questões cadastradas + aprovadas). Uma vez desbloqueado, fica disponível pra sempre — impede "simuladão agendado" (cursinhos parceiros e o VNF não conseguem dizer "abre dia X às 8h, fecha dia Y às 23:59").

Essa etapa adiciona a janela temporal como camada complementar ao bloqueado. Retrocompatibilidade total — legados ficam null/null e continuam disponíveis como hoje.

Decisões cravadas

• Ambos os campos nullable (Date | null). Combos: null/null (sempre), só de, só até, de + até (janela fechada).
• Regra: !bloqueado && (de==null || agora>=de) && (ate==null || agora<=ate), em função pura isSimuladoAvailable.
• Companion getAvailabilityStatus → enum de 4 valores (disponivel | bloqueado | antes_da_janela | depois_da_janela) pra UI (🟢🟡🔴🔒⚪).
• Datetime (não só data). UTC no banco, local na UI.
• Edição na vista de simulados do ShowProva (não no NewProva).
• Permissão: cadastrarProvas (sem permissão nova).
• Gate em getToAnswer com 403 { message, status }.
• POST /answer NÃO gated — grace period intencional (quem abriu dentro pode submeter fora).
• Filtro em getAvailable aplica a regra completa. Índice composto { categoria, bloqueado, disponivelDe, disponivelAte }.

Pré-requisitos

• [Categoria] (etapa 1, # [Categoria] Refatoração do modelo: TipoSimulado → Categoria #65) e [Unificação] (etapa 2, [Unificação] Eliminar tela Simulados admin + vista interna no ShowProva + cleanup `criarSimulado` #68) — a vista de simulados do ShowProva (onde as datas são editadas) já existe. Independente das demais etapas.

Cards desta etapa

Ordem obrigatória por dependência: 01 → 02 → 03 → 04 (estritamente sequencial).

• Card 01 · ms-simulado · Schema disponivelDe/disponivelAte + funções puras (isSimuladoAvailable, getAvailabilityStatus) + índice composto. Prep, sem mudança comportamental. · #161
• Card 02 · ms-simulado · PATCH /disponibilidade (validação cross-field) + filtro em getAvailable + gate 403 em getToAnswer. POST /answer intocado. · #162
• Card 03 · api-vcnafacul · Proxy PATCH /disponibilidade gated por cadastrarProvas + DTO espelho + as 2 datas no SimuladoDTO. · #505
• Card 04 · client-vcnafacul · Vista de simulados: edição inline via datetime-local + coluna de status (5 estados) + toast amigável no 403 do aluno. · #645

Coordenação de deploy

Sem migration SQL. Ordem: ms-simulado (01+02, schema + índice composto na inicialização) → api-vcnafacul (03) → client-vcnafacul (04). Documentos legados nascem null/null (disponíveis como hoje).

Riscos consolidados

• Timezone: UTC no banco, local na UI — testar fora de UTC-3.
• Cross-field validation: disponivelDe >= disponivelAte → 400.
• Race listar↔abrir: janela fecha entre ver e clicar → getToAnswer revalida → 403 → toast (comportamento correto).
• Duplicação de lógica backend (isSimuladoAvailable) vs frontend (getStatus) — manter em sync; backend é fonte de verdade.

Próximas etapas

Independente — pode ser executada em qualquer ponto após [Categoria] + [Unificação]. Não é pré-requisito das próximas etapas.

Referências

• Resumo executivo da série: Refatoração do domínio Simulado — Resumo executivo #61 · Mapa de etapas: Refatoração do domínio Simulado — Mapa de etapas #66
• Etapa 1 [Categoria]: # [Categoria] Refatoração do modelo: TipoSimulado → Categoria #65 · Etapa 2 [Unificação]: [Unificação] Eliminar tela Simulados admin + vista interna no ShowProva + cleanup `criarSimulado` #68 · Etapa 3 [CRUD Categoria]: [CRUD Categoria] Modal admin pra criar e excluir categorias personalizadas #71 · Etapa 4 [Provas Custom]: [Provas Custom] Fluxo de provas personalizadas com CustomProvaFactory + criadorId/cursinhoId #72