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 1como 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- O arquivo entra por sincronização (pasta do OneDrive/SharePoint) ou por upload manual.
- As imagens são sanitizadas e o
.docxé lido pelo PhpWord (formato Word2007). - O documento é dividido em Unidades. Cada Unidade passa por cinco parsers: informações gerais, tópicos, V/F, objetiva e escrita.
- O resultado é validado. Se houver qualquer erro, nenhuma versão é criada: a Disciplina vai para o status
Failede a mensagem lista os erros. - 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.docxRegex 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
idnumberidentifica 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
idnumbervira 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º 1no 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 NouHeading 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,56. 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 umTítulo 2e o conteúdo. - Todo marcador sozinho no parágrafo, sem texto na mesma linha.
- V/F:
[[VF_Qnn]], enunciado eRESPOSTA: V|F. - Objetiva:
[[OBJ_Qnn]], enunciado, 2 ou mais alternativas em lista do Word eRESPOSTA: A-Hvá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 |