Contrato Estrutural do Word
Referência técnica
Esta página descreve a estrutura que o parser de importação reconhece. O detalhe de cada chave, com exemplos e a lista de validações, está no Guia Técnico do Arquivo Word.
Contexto
Este contrato define a especificação de interface que o Conteudista deve seguir ao elaborar o Arquivo de Disciplina (Word). Seu objetivo é garantir consistência pedagógica, previsibilidade editorial e rastreabilidade algorítmica entre o Word e a Base de Conteúdo.
Sem regras objetivas de estrutura, o material perde qualidade, a revisão exige retrabalho e a Sincronização Pedagógica SharePoint não consegue mapear corretamente o conteúdo para a plataforma.
Nome oficial do arquivo
| Campo | Regra | Exemplo |
|---|---|---|
| Padrão | [IDNUMBER] Nome da Disciplina.docx |
[DC_001] Direito Constitucional |
IDNUMBER |
Identificador da Disciplina, entre colchetes, só letras sem acento (A-Z), números, - e _, com pelo menos um _ |
DC_001 |
| Nome da Disciplina | Nome legível para equipe e auditoria. A extensão .docx é descartada. |
Direito Constitucional |
Nome fora do padrão é ignorado em silêncio
Um arquivo sem colchetes, com
IDNUMBERsem_(por exemplo[DC001]) ou com qualquer caractere fora de letras sem acento, números,-e_(espaço,º,°, acento,/,:,?,#…) não gera erro: a sincronização simplesmente o pula. Se a Disciplina não aparece depois de sincronizar, confira o nome primeiro.
Nunca altere o IDNUMBER após a primeira publicação
O
IDNUMBERé a chave que liga o arquivo à Disciplina. Um arquivo comIDNUMBERnovo cria outra Disciplina, sem vínculo com a Base de Conteúdo e com os Planos de Estudo da anterior. OIDNUMBERtambém compõe a chave de todo tópico e questão (DC_001_U1_T1,DC_001_OBJ_Q01). Dois arquivos com o mesmo nome (sem diferenciar maiúsculas) colocam a Disciplina em Conflito, e nenhum dos dois é processado.
Estrutura macro do documento
O arquivo é lido de cima para baixo, em três níveis: Unidade, Tópico e componentes.
Não existe capa informativa lida pelo sistema
Todo texto antes do primeiro
UNIDADE Nº né descartado. Capa, responsável e data de revisão podem existir para a equipe, mas o sistema não os lê nem os valida.
1) Unidade
Cada Unidade começa num parágrafo com o texto UNIDADE Nº <número> (por exemplo UNIDADE Nº 1). O sistema olha o texto do parágrafo, não o estilo: o título pode ser Heading 1, mas não precisa.
| Regra | Observação |
|---|---|
Aceito: UNIDADE Nº 1, Unidade nº 2, UNIDADE N° 03, UNIDADE N 4 |
Maiúsculas e minúsculas não importam; º, ° ou nenhum são aceitos. |
Não aceito: Unidade 3 |
Falta o N. |
Tudo abaixo do marcador pertence à Unidade até o próximo UNIDADE Nº n |
|
| Não repita a expressão em texto comum | O reconhecimento não exige que seja o parágrafo inteiro: uma frase como “ver unidade nº 2” abre uma Unidade nova. |
| Não repita o mesmo número de Unidade | O segundo bloco sobrescreve o primeiro. |
2) Tópicos de Conteúdo
Dentro da Unidade, cada Tópico de Conteúdo começa com um marcador [U<n>_T<n>]:
| Elemento | Como marcar | Resultado |
|---|---|---|
| Abertura do Tópico | Parágrafo [U1_T1] (também [U01_T02] ou [U1 T1]) |
Cria o Tópico com a chave <IDNUMBER>_U1_T1 |
| Título | Parágrafo com estilo Título 2 / Heading 2 |
title (obrigatório) |
| Subtítulo (opcional) | Parágrafo com estilo Título 3 / Heading 3 |
subtitle |
| Conteúdo | Demais parágrafos e imagens | summary (obrigatório) |
| Observações | Marcador [[OBSERVACOES_OU_COMENTARIO]], seguido do texto |
notes |
O marcador [U1_T1] e o Título 2 têm papéis diferentes: o marcador cria o tópico e define a chave; o estilo Título 2 define só o texto do título. Sem [U1_T1], o conteúdo fica solto e não é importado.
3) Seções de componentes pedagógicos (Tag-Colchete)
As demais seções são demarcadas por Tag-Colchete. O catálogo completo fica em Catálogo de Tags e Componentes.
4) Continuidade semântica do conteúdo
Depois de um marcador, todo conteúdo seguinte pertence a ele até o próximo marcador (colchete simples ou duplo). Parágrafos vazios e quebras de página são ignorados. Imagens contam como conteúdo.
Regras obrigatórias e dependências
| Regra | Tipo | Impacto se violada |
|---|---|---|
Nome do arquivo no padrão [ID_COM_UNDERSCORE] Nome.docx |
Obrigatória | Arquivo ignorado na sincronização, sem mensagem |
Toda Unidade abre com UNIDADE Nº n |
Obrigatória | Sem Unidade, o processamento falha com “Nenhum arquivo encontrado para o item.” |
Todo Tópico abre com [U<n>_T<n>] e tem Título 2 e conteúdo |
Obrigatória | A nova versão é bloqueada (“Tópico sem título” / “Tópico sem conteúdo”) |
Toda questão tem chave ([[VF_Qnn]], [[OBJ_Qnn]], [DISC_Qnn]…) única dentro da Unidade |
Obrigatória | Versão bloqueada (“sem chave do Word” / “chave duplicada”) |
| Marcador sozinho no parágrafo, sem texto na mesma linha | Obrigatória | O marcador não é reconhecido e o texto vira conteúdo |
| Tag-Colchete pertence ao catálogo oficial | Obrigatória | Marcador desconhecido não abre seção e não vira componente; o efeito sobre o texto ao redor varia por seção |
IDNUMBER não muda após a primeira Publicação Pedagógica |
Obrigatória | Cria Disciplina nova, sem vínculo com a anterior |
Quando a validação reprova, nenhuma versão é criada: a Disciplina fica com status de falha e a mensagem lista os erros por Unidade.
Estilos reconhecidos pelo parser
| Estilo Word | Função na importação | Observação |
|---|---|---|
Título 2 / Heading 2 |
Título do Tópico de Conteúdo | Obrigatório em cada Tópico |
Título 3 / Heading 3 |
Subtítulo do Tópico | Opcional |
Título 1 e Título 4+ |
Sem função | O parser não usa Heading 1 para delimitar Unidade |
| Item de lista (numerada ou com marcadores) | Alternativa da questão objetiva; critério da questão escrita | Texto digitado como A) não vale como alternativa |
| Normal | Corpo do conteúdo (texto, parágrafos) | Padrão |
| Negrito / Itálico | Ênfase editorial | Sem semântica estrutural para o parser |
| Tag-Colchete em linha | Delimitador de componente pedagógico | Ver catálogo |
O nome do estilo precisa ser Título N ou Heading N (N de 1 a 6). Só os níveis 2 e 3 são usados.
Erros comuns e mitigação
| Erro recorrente | Consequência | Mitigação |
|---|---|---|
IDNUMBER sem _ (ex.: [DC001]) |
Arquivo ignorado, sem erro | Usar [DC_001]; conferir o nome antes de sincronizar |
Iniciar Unidade sem UNIDADE Nº n |
Conteúdo descartado ou “Nenhum arquivo encontrado” | Checklist estrutural antes da publicação |
| Repetir “unidade nº n” em texto comum | Abre uma Unidade falsa e corta a anterior | Evitar a expressão fora do título da Unidade |
Tópico sem [U1_T1] |
Conteúdo não é importado | Revisão por mapa de marcadores |
Tópico sem Título 2 |
Versão bloqueada: “Tópico sem título” | Aplicar o estilo Título 2 ao título |
Texto na mesma linha do marcador (RESPOSTA: V (revisar)) |
Marcador não reconhecido | Marcador sozinho no parágrafo |
| Alternativas digitadas à mão | Versão bloqueada: “menos de 2 alternativas” | Usar lista do Word |
Alterar IDNUMBER de Disciplina já publicada |
Nasce uma Disciplina nova | Confirmar com o Gestor Pedagógico e com Desenvolvimento |
Rastreabilidade
O
IDNUMBERe as chaves de Tópicos e questões (U1_T1,VF_Q01,OBJ_Q07…) são a rastreabilidade entre o Word e a Base de Conteúdo. A chave identifica o item em reprocessamentos, então não a reutilize para outro conteúdo.
Pendência: versionamento semântico
O arquivo não carrega número de versão: o sistema cria uma nova versão da Disciplina quando o conteúdo processado muda. Falta decidir se a equipe quer registrar também uma versão explícita (v1, v2) fora do sistema, ou manter só a data de revisão e o Registro de Alteração Pedagógica.
FAQ local — Contrato Estrutural
Posso usar Heading 1 para o título da Unidade?
Pode, mas o parser não depende dele. O que abre a Unidade é o texto UNIDADE Nº n.
Posso usar Heading 4 para subtópico?
Não como padrão. O parser só usa Título 2 (título) e Título 3 (subtítulo). Níveis 4 em diante não têm função.
Posso criar uma seção textual sem Tag-Colchete?
Somente dentro de um Tópico de Conteúdo já aberto por [U<n>_T<n>]. Se for seção estrutural de componente, deve usar Tag-Colchete.
Preciso de uma capa com responsável e data de revisão?
O sistema não lê nem exige. Pode manter para a equipe, desde que fique antes do primeiro UNIDADE Nº n.