PARSE_STRUCTURED - Extração Estruturada de HTML

O que é este Node?

O PARSE_STRUCTURED é o node responsável por extrair a estrutura organizada de documentos HTML, separando títulos, parágrafos, listas e tabelas em um formato JSON estruturado e fácil de processar.

Por que este Node existe?

HTML mistura conteúdo e estrutura de forma complexa. O PARSE_STRUCTURED existe para:

Organização: Separar diferentes tipos de conteúdo (headings, parágrafos, listas, tabelas) de forma estruturada
Análise: Facilitar processamento automatizado de documentos HTML complexos
Navegação: Permitir acesso programático a partes específicas de um documento
Indexação: Preparar conteúdo HTML para indexação e busca estruturada

Como funciona internamente?

Quando o PARSE_STRUCTURED é executado, o sistema:

Carrega o HTML: Usa Cheerio para parsear o documento HTML
Limpa o conteúdo: Remove scripts, estilos e elementos de navegação
Extrai título: Busca em <title> ou primeiro <h1>
Coleta headings: Extrai todos os h1-h6 com nível hierárquico e id
Captura parágrafos: Extrai parágrafos relevantes (> 20 caracteres)
Processa listas: Extrai listas (ul/ol) com seus itens
Analisa tabelas: Extrai tabelas com headers e rows
Retorna JSON: Converte tudo para objeto JSON estruturado

Código interno (html-parser-executor.service.ts:305-374):

private parseStructured($: CheerioAPI, config: HTMLParserNodeData): any {
  const structure: any = {
    title: $('title').text().trim() || $('h1').first().text().trim(),
    headings: [],
    paragraphs: [],
    lists: [],
    tables: []
  };

  // Extract headings hierarchy
  $('h1, h2, h3, h4, h5, h6').each((index, element) => {
    const level = parseInt(element.tagName.substring(1));
    const text = $(element).text().trim();
    if (text) {
      structure.headings.push({
        level,
        text,
        id: $(element).attr('id')
      });
    }
  });

  // Extract paragraphs
  $('p').each((index, element) => {
    const text = $(element).text().trim();
    if (text.length > 20) { // Only meaningful paragraphs
      structure.paragraphs.push(text);
    }
  });

  // Extract lists
  $('ul, ol').each((index, element) => {
    const listItems: string[] = [];
    $(element).find('> li').each((i, li) => {
      listItems.push($(li).text().trim());
    });
    if (listItems.length > 0) {
      structure.lists.push({
        type: element.tagName,
        items: listItems
      });
    }
  });

  // Extract tables
  $('table').each((index, element) => {
    const headers: string[] = [];
    const rows: string[][] = [];

    $(element).find('thead th').each((i, th) => {
      headers.push($(th).text().trim());
    });

    $(element).find('tbody tr').each((i, tr) => {
      const row: string[] = [];
      $(tr).find('td').each((j, td) => {
        row.push($(td).text().trim());
      });
      if (row.length > 0) {
        rows.push(row);
      }
    });

    if (headers.length > 0 || rows.length > 0) {
      structure.tables.push({ headers, rows });
    }
  });

  return structure;
}

Quando você DEVE usar este Node?

Use PARSE_STRUCTURED sempre que precisar de acessar partes específicas de um documento HTML:

Casos de uso

Extração de documentação: "Extrair índice de uma página de docs (todos os headings)"
Análise de conteúdo: "Separar e contar parágrafos de artigos para métricas"
Processamento de tabelas: "Extrair dados tabulares de relatórios HTML"
Indexação semântica: "Criar índice estruturado de documentos para busca"

Quando NÃO usar PARSE_STRUCTURED

Precisa apenas texto: Use parse_text para conteúdo simples sem estrutura
Precisa Markdown: Use parse_markdown para converter e manter formatação
Precisa elementos específicos: Use parse_custom com seletores CSS personalizados