Skip to content

Guia Técnico do Arquivo Word

Guia Técnico do Arquivo Word

Este guia descreve exatamente o que o processamento do Word do local_helico lê: do nome do arquivo até as chaves de cada simulado. Ele foi escrito a partir do código do parser, e não da metodologia.

Diferença em relação às outras páginas desta seção

O Contrato Estrutural e o Catálogo de Tags descrevem a intenção pedagógica (Heading 1 como Unidade, [QUESTOES_VF], [DC001]). O parser não usa essas marcações. Em caso de divergência, vale este guia. As tags [QUESTOES_VF], [QUESTOES_OBJETIVAS], [QUESTOES_SIMULADO_ESCRITO], [AUDIOS_DA_UNIDADE] e a capa informativa não são lidas pelo código.

Como o arquivo é processado

Nome do arquivo  →  idnumber + nome da disciplina
Documento .docx  →  divisão em Unidades  →  parse de cada Unidade  →  validação  →  nova versão
  1. O arquivo entra por sincronização (pasta do OneDrive/SharePoint) ou por upload manual.
  2. As imagens são sanitizadas e o .docx é lido pelo PhpWord (formato Word2007).
  3. O documento é dividido em Unidades. Cada Unidade passa por cinco parsers: informações gerais, tópicos, V/F, objetiva e escrita.
  4. O resultado é validado. Se houver qualquer erro, nenhuma versão é criada: a Disciplina vai para o status Failed e a mensagem lista os erros.
  5. Se o conteúdo for idêntico ao da última versão (hash do JSON), nada é criado e a Disciplina fica Completed.

1. Nome do arquivo

Padrão:

[IDNUMBER] Nome da Disciplina.docx

Regex aplicada: ^\[([A-Za-z0-9_-]+_[A-Za-z0-9_-]+)\]\s+(.+)$

Parte Regra
[ ... ] no início Obrigatório. O nome precisa começar com colchete.
IDNUMBER Só letras sem acento (A-Z), números, - e _, e com pelo menos um _. [DC001] é rejeitado; [DC_001] é aceito.
Espaço após o ] Obrigatório (um ou mais).
Nome da Disciplina Qualquer texto. O .docx final é removido.

Exemplos:

Nome do arquivo Resultado
[SC_001_9A] Matemática.docx OK. idnumber = SC_001_9A, disciplina Matemática.
[DC_001] Direito Constitucional.docx OK.
[DC001] Direito Constitucional.docx Ignorado em silêncio (idnumber sem _).
DC_001 Direito Constitucional.docx Ignorado em silêncio (sem colchetes).
[DC 001] Direito.docx Ignorado em silêncio (espaço no idnumber).
[EH_Direito_Penal_arts_1º_a_120_V1] Direito Penal.docx Ignorado em silêncio (º não é permitido). Use [EH_Direito_Penal_arts_1_a_120_V1].
[EH_Legislação_V1] Legislação.docx Ignorado em silêncio (acento no idnumber).
[EH_A/B_V1], [EH_A:B_V1], [EH_A?_V1] Ignorados em silêncio (/, :, ?, # e outros símbolos não são permitidos).

Regras adicionais:

  • Arquivo com nome fora do padrão não gera erro: é pulado na sincronização.
  • Dois arquivos com o mesmo nome (comparação sem diferenciar maiúsculas) marcam a Disciplina como Conflict. Nenhum dos dois é processado até o conflito sumir.
  • O idnumber identifica a Disciplina. Se já existir, o arquivo vira uma nova versão dela; se não, a Disciplina é criada. Não altere o idnumber depois de publicado.
  • O idnumber vira prefixo de todas as chaves de tópicos e questões (SC_001_9A_U1_T1, SC_001_9A_OBJ_Q01…).

2. Regras gerais de marcadores

  • Cada marcador fica sozinho no parágrafo. As regex são ancoradas (^...$). Texto extra na mesma linha invalida o marcador.
  • A comparação ignora maiúsculas, acentos e espaços: o texto é normalizado para maiúsculas, sem acento, e cada sequência de espaços vira _. [[Vídeo do Simulado]] equivale a [[VIDEO_DO_SIMULADO]].
  • Colchete simples [...] marca seção ou tópico. Colchete duplo [[...]] marca subcampo.
  • Parágrafos vazios e quebras de página são ignorados.
  • Imagens são aceitas no corpo. Um parágrafo só com imagem conta como conteúdo.
  • Tudo que vem antes do primeiro UNIDADE Nº n é descartado.

3. Unidades

Cada Unidade começa num parágrafo com o texto UNIDADE Nº <número>.

Regex: UNIDADE\s*N[º°]?\s*\d+ (sem diferenciar maiúsculas).

Aceito Não aceito
UNIDADE Nº 1, Unidade nº 2 Unidade 3 (falta o N)
UNIDADE N° 03, UNIDADE N 4

Atenção:

  • A regex não é ancorada. Qualquer parágrafo que contenha unidade nº 2 (por exemplo, numa referência cruzada) abre uma nova Unidade.
  • A chave da Unidade é o texto encontrado em maiúsculas. Dois títulos UNIDADE Nº 1 no mesmo arquivo fazem o segundo sobrescrever o primeiro.
  • O título da Unidade não precisa ser Heading 1. O parser olha o texto, não o estilo.
  • Se o arquivo não tiver nenhuma Unidade, o processamento falha com Nenhum arquivo encontrado para o item.

4. Conteúdo da Unidade

4.1 Informações gerais

Marcador Campo gerado
[QUADRO_GERAL_DE_INFORMACOES] generalInformation
[JURISPRUDENCIA] ou [[JURISPRUDENCIA]] jurisprudence
[LEGISLACAO] legislation
[VIDEO_DA_UNIDADE] video (só texto, tipicamente a URL)

O conteúdo vai do marcador até o próximo marcador de qualquer tipo ([U1_T1], [SIMULADO], [[...]]…).

4.2 Tópicos

Marcador Função
[U1_T1], [U01_T02], [U1 T1] Abre o tópico. Regex ^\[U\d{1,3}[_ ]?T\d{1,3}\]$. Chave: <idnumber>_U1_T1.
Parágrafo Título 2 / Heading 2 Título do tópico (title).
Parágrafo Título 3 / Heading 3 Subtítulo (subtitle).
Demais parágrafos Conteúdo (summary).
[[OBSERVACOES_OU_COMENTARIO]] O que vem depois vira notes.
  • O estilo do parágrafo precisa se chamar Título N ou Heading N (N de 1 a 6). Só os níveis 2 e 3 são usados.
  • A captura de tópicos termina em [SIMULADO_VF]. O conteúdo dos simulados nunca entra no tópico.

5. Simulados

Os três simulados ficam dentro da Unidade, nesta ordem: V/F, objetivo, escrito. Cada parser percorre a Unidade inteira, ignora o que não é dele e para ao encontrar o marcador do bloco seguinte.

5.1 Verdadeiro/Falso

Chave Função
[[VIDEO_DO_SIMULADO]] Tudo até a próxima questão vira o vídeo do simulado.
[[VF_Q1]] a [[VF_Q99]] Abre a questão (1 ou 2 dígitos). Chave: <idnumber>_VF_Q01.
Texto solto Enunciado.
FONTE: L / D / J Categoria: lei, doutrina, jurisprudencia. Outra letra vira lei.
RESPOSTA: V / F Gabarito.
[[COMENTARIO]] O que vem depois, até a próxima questão, é o comentário.

Para a leitura: [SIMULADO_OBJETIVO] (ou [SIMULADO OBJETIVO]) ou qualquer [[OBJ_Qnn]].

Exemplo:

[[VIDEO_DO_SIMULADO]]
https://exemplo.com/video-vf

[[VF_Q01]]
A competência para legislar sobre direito civil é privativa da União.
FONTE: L
RESPOSTA: V
[[COMENTARIO]]
Art. 22, I, da CF.

5.2 Objetivo

Chave Função
[[VIDEO_DO_SIMULADO]] ou [[VIDEO DO SIMULADO]] Vídeo. Só o próximo parágrafo é capturado.
[[OBJ_Q1]] a [[OBJ_Q99]] Abre a questão. Chave: <idnumber>_OBJ_Q01.
Texto solto Enunciado.
Itens de lista do Word Alternativas. Use lista numerada ou com marcadores do Word.
FONTE: L / D / J Categoria.
RESPOSTA: A a H Gabarito. Guardado como posição (A = 0 … H = 7).
[[COMENTARIO]] Comentário.
  • Alternativas digitadas à mão (A) texto) não contam. Precisam ser itens de lista do Word.
  • [[VF_Qnn]] dentro deste bloco só encerra a captura de vídeo.
  • Para a leitura: [DISCURSIVA], [DISSERTATIVA] ou [PECA_PRATICA].

Exemplo:

[[OBJ_Q01]]
Assinale a alternativa correta sobre o poder constituinte originário.
  A. É condicionado.            ← item de lista
  B. É ilimitado juridicamente. ← item de lista
  C. É derivado.                ← item de lista
FONTE: D
RESPOSTA: B
[[COMENTARIO]]
Explicação da alternativa correta.

5.3 Escrito

O bloco escrito só começa depois de um marcador de tipo. Nada antes dele é lido.

Chave Função
[DISCURSIVA], [DISSERTATIVA], [PECA_PRATICA] Liga o modo escrito e define o tipo das questões seguintes. Pode aparecer de novo para trocar o tipo.
[DISC_Q1], [DISSERT_Q1], [PP_Q1] Abre a questão (1 a 3 dígitos). Chave: <idnumber>_DISC_Q01.
Texto solto (e imagens) Enunciado.
[[ESPELHO_DE_CORRECAO]] O que vem depois é o espelho de correção.
[[PARAMETROS_ESPECIFICOS]] Abre os critérios de correção.
Item de lista Título de um critério.
[[AUTORRESPOSTA]] O que vem depois é a autorresposta do critério.
[[NOTA]] O próximo parágrafo que não for item de lista é a nota do critério.
[[VIDEO]] ou [[VÍDEO]] O que vem depois é o vídeo da questão.

Exemplo:

[DISCURSIVA]

[DISC_Q01]
Disserte sobre o princípio da legalidade.
[[ESPELHO_DE_CORRECAO]]
Resposta esperada...
[[PARAMETROS_ESPECIFICOS]]
  • Conceito de legalidade     ← item de lista
[[AUTORRESPOSTA]]
Texto de referência do critério.
[[NOTA]]
1,5

6. Validação

Depois do parse, cada Unidade é validada. Qualquer erro bloqueia a nova versão.

Seção Erro
Todas Item sem chave do Word, ou com chave duplicada na mesma Unidade.
Tópico Sem título (Título 2/Heading 2) ou sem conteúdo.
V/F Sem enunciado ou sem RESPOSTA.
Objetiva Sem enunciado; menos de 2 alternativas; sem RESPOSTA; RESPOSTA apontando para alternativa que não existe.
Escrita Sem enunciado; sem parâmetros de correção; tipo diferente de discursiva, dissertativa ou peca_pratica.

A mensagem final tem o formato Unidade UNIDADE Nº 1: Questão objetiva sem resposta correta marcada; ....

7. Checklist antes de publicar

  • Nome no padrão [ID_COM_UNDERSCORE] Nome.docx, sem outro arquivo de mesmo nome.
  • Cada Unidade abre com UNIDADE Nº n, e nenhum texto comum repete essa expressão.
  • Cada tópico: [U1_T1], depois um Título 2 e o conteúdo.
  • Todo marcador sozinho no parágrafo, sem texto na mesma linha.
  • V/F: [[VF_Qnn]], enunciado e RESPOSTA: V|F.
  • Objetiva: [[OBJ_Qnn]], enunciado, 2 ou mais alternativas em lista do Word e RESPOSTA: A-H válida.
  • Escrita: marcador de tipo, [DISC_Qnn] (ou [DISSERT_Qnn]/[PP_Qnn]), enunciado e ao menos um critério em [[PARAMETROS_ESPECIFICOS]].
  • Numeração de questões e tópicos sem repetição dentro da Unidade.

Código de referência

Assunto Arquivo (em classes/extensions/content/)
Nome do arquivo management/file_word/service/discipline_sync_service.php (check_filename)
Divisão em Unidades management/file_word/service/processing/engine/unit/parser/unit_splitter.php
Gerais e tópicos .../engine/unit/parser/unit_parser.php
Simulados .../engine/unit/parser/simulation_parser.php
Normalização e títulos .../engine/support/text_helper.php
Validação base/unit/unit_content/service/unit_content_validator.php
Navigation

Type to search…

↑↓ navigate↵ selectEsc close