Design: Validação de conteúdo de unidade no pipeline de import Word
Status: approved (design), pending implementation plan
Branch: feat/unit-content-validation
Problema
O parser do arquivo Word (unit_parser.php, simulation_parser.php) monta o
conteúdo de cada unidade (tópicos, questões objetivas, V/F, escritas) sem
nenhuma validação estrutural. Quando o Word está mal formatado — ex.: opções
de uma questão objetiva não estão em formato de lista, ou falta o marcador
RESPOSTA:_X que indica a alternativa correta — o parser não falha e não
sinaliza nada. Pior: os Value Objects que consomem o array cru do parser
mascaram a ausência de dado com um default falso:
question_multiplechoice::from_array— sem marcadorRESPOSTA:, o campo crucorrectAnswerfica'', mas o VO default praanswer=0(primeira alternativa “correta” por acidente).question_truefalse::from_array— sem marcadorRESPOSTA:_V/F, o campo crucorrectAnswerficanull, e o VO faz(bool) null→answer=false.question_written::from_array— umtype/formato não reconhecido no Word cai no default'dissertative'viamap_format.
Ou seja: um erro de formatação no Word hoje vira silenciosamente um dado “válido” mas errado, sem nenhum sinal pro usuário. Isso só é detectável inspecionando o array cru do parser, antes da conversão pra VO/DTO — depois desse ponto a informação de “faltou” já foi perdida.
Objetivo
Antes de persistir uma nova versão de conteúdo de disciplina (upload/reprocessamento
de arquivo Word), validar estruturalmente todas as unidades do arquivo.
Se qualquer unidade tiver erro, bloquear o processamento inteiro (nada é
salvo) e expor, na tela /disciplinas, quais unidades falharam e por quê.
Ponto de injeção
unit_json_engine.php:99-103 é onde as 4 chamadas de parser (tópicos,
objetiva, V/F, escrita) são reunidas no array $unidade, antes de
unit_content_dto::to_item_dto converter pra VO/DTO. A validação roda
nesse ponto, sobre o array cru — não depois, sobre o dado já persistido
ou já convertido pra VO (onde os defaults falsos já mascararam o problema).
process_file_pipeline.php chama essa validação pra cada unidade do
arquivo. Só depois de todas as unidades passarem é que o pipeline segue
pro save (unit_content_dto::to_item_dto → unit_content_service::create).
Se qualquer unidade falhar, o pipeline aborta antes de qualquer persistência
— comportamento tudo-ou-nada, igual ao processamento normal de arquivo hoje
quando há erro de parsing.
Regras de validação
Todas as regras leem o array cru retornado pelos parsers (nomes de campo conforme parser, não conforme VO/schema renomeado).
| Tipo | Campo cru | Regra | Mensagem de erro |
|---|---|---|---|
| Tópico | title |
vazio ('') |
“Tópico sem título” |
| Tópico | summary |
vazio ('') |
“Tópico sem conteúdo” |
| Objetiva | statement |
vazio ('') |
“Questão objetiva sem enunciado” |
| Objetiva | alternatives |
count < 2 |
“Questão objetiva com menos de 2 alternativas (formato lista)” |
| Objetiva | correctAnswer |
'' (sem marcador RESPOSTA:_X) |
“Questão objetiva sem resposta correta marcada” |
| Objetiva | correctAnswer |
índice >= count(alternatives) |
“Questão objetiva com resposta apontando para alternativa inexistente” |
| V/F | statement |
vazio ('') |
“Questão V/F sem enunciado” |
| V/F | correctAnswer |
null (sem marcador RESPOSTA:_V/F) |
“Questão V/F sem gabarito marcado” |
| Escrita | statement |
vazio ('') |
“Questão escrita sem enunciado” |
| Escrita | correctionParams |
[] (vazio) |
“Questão escrita sem parâmetros de correção” |
| Escrita | type |
fora da lista conhecida de formatos | “Questão escrita com tipo inválido” |
Nota lateral (achado durante pesquisa, não faz parte desta validação): o
schema unit_content.api.schema.json (essay_item.format enum) não inclui
discursive, que é um valor válido de saída de map_format em
question_written.php:138. Mismatch de contrato pré-existente — vale um
ticket separado, fora de escopo aqui.
Armazenamento do resultado
Reaproveita a entidade já modelada e não conectada
classes/extensions/content/management/file_word/entity/file_word_validation.php
(validation_status, errors, validated_at). Um registro agregado por
arquivo validado:
validation_status:passed|failederrors: lista de mensagens (formato acima), vazia se válidovalidated_at: timestamp da validação
UI — /disciplinas
Sem tela nova. O campo error_message da disciplina (já existe em
discipline_service.php:244-256, já exibido como sublabel de erro no
disciplina_page_builder.php:91-97) passa a ser populado, quando o
processamento é bloqueado por validação, com a lista agregada de erros por
unidade, ex.:
Unidade 3: Questão objetiva sem resposta correta marcada
Unidade 5: Tópico sem título
Unidade 5: Questão V/F sem enunciadoFora de escopo
- Validação de regras pedagógicas/qualidade de conteúdo (só estrutura + presença de gabarito/resposta).
- Nova tela ou UI granular por unidade — reaproveita o
error_messagede disciplina existente. - Corrigir o mismatch de schema
discursive/enum (achado, não corrigido aqui). - Revalidação automática de unidades já salvas antes desta feature existir (validação só roda em novos processamentos de arquivo, a partir de agora).