Skip to content

Design: Validação de conteúdo de unidade no pipeline de import Word

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 marcador RESPOSTA:, o campo cru correctAnswer fica '', mas o VO default pra answer=0 (primeira alternativa “correta” por acidente).
  • question_truefalse::from_array — sem marcador RESPOSTA:_V/F, o campo cru correctAnswer fica null, e o VO faz (bool) null → answer=false.
  • question_written::from_array — um type/formato não reconhecido no Word cai no default 'dissertative' via map_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 | failed
  • errors: lista de mensagens (formato acima), vazia se válido
  • validated_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 enunciado

Fora 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_message de 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).
Navigation

Type to search…

↑↓ navigate↵ selectEsc close