ArqSystem

Aparência

Busca Full-Text ​

Este guia detalha o sistema de busca full-text do ArqSystem powered by Sonic.

Visão Geral ​

O ArqSystem utiliza o Sonic como motor de busca, proporcionando:

  • Busca extremamente rápida (sub-milissegundo)
  • Tolerância a erros de digitação (fuzzy search)
  • Busca em todos os campos de texto
  • Resultados ordenados por relevância
  • Sugestões de busca automáticas

Tecnologia Sonic ​

O que é Sonic? ​

Sonic é um motor de busca leve e rápido, escrito em Rust, otimizado para:

  • Alta performance
  • Baixo consumo de memória
  • Busca fuzzy nativa
  • Tokenização avançada
  • Suporte a múltiplos idiomas

Características Técnicas ​

Performance:

  • Busca: < 1ms para maioria das consultas
  • Indexação: ~100-200 documentos/segundo
  • Memória: ~1MB por 10.000 documentos
  • Limite de resultados: Top 100 (configurável)

Recursos:

  • Fuzzy matching com tolerância a erros
  • Stemming para português
  • Stop words configuráveis
  • Sugestões de autocompletar
  • Sinônimos (futuro)

Interface de Busca ​

Campo de Busca Global ​

Disponível na página /documents:

┌─────────────────────────────────────────────┐
│ 🔍 Buscar por título, número ou palavras... │
└─────────────────────────────────────────────┘

Características:

  • Placeholder indicativo
  • Ícone de lupa
  • Debounce de 400ms
  • Busca em tempo real

Busca na Homepage ​

Campo de busca público na página inicial:

┌─ Buscar Documentos Públicos ───────────────┐
│ 🔍 Digite para buscar...                    │
└─────────────────────────────────────────────┘

Sugestões:
[relatório] [ata] [ofício] [decreto]

Sugestões dinâmicas:

  • Baseadas no índice Sonic
  • Atualizam conforme conteúdo indexado
  • Clicar na sugestão inicia busca

Campos Pesquisáveis ​

O sistema indexa todos os campos de texto dos documentos:

Campos Principais ​

Identificação:

  • Título do documento
  • ID Digital (UUID)
  • Número do documento físico

Metadados:

  • Autor
  • Descrição
  • Palavras-chave

Dados Relacionados:

  • Nome do Tipo Documental
  • Nome do Órgão Vinculado

Campos Adicionais:

  • Notas internas
  • Observações
  • Proveniência
  • Organização interna
  • Parlamentares relacionados

Formato de Indexação ​

Todos os campos são concatenados em um texto único:

typescript
// Exemplo de texto indexado
"Relatório Anual de Atividades 2024 relatorio-anual-2024 f47ac10b-58cc-4372-a567-0e02b2c3d479 Relatório João Silva Relatório das atividades desenvolvidas durante o ano de 2024 atividades, relatório, 2024, anual Secretaria Municipal de Educação"

Funcionalidades de Busca ​

Busca Simples ​

Digite um termo para buscar em todos os campos:

Busca: "relatório"

Resultados:
- Relatório Anual 2024
- Relatório de Atividades
- Relatório Técnico de Engenharia

Busca com Múltiplos Termos ​

Digite vários termos separados por espaço:

Busca: "relatório anual 2024"

Resultados (ordenados por relevância):
1. Relatório Anual de Atividades 2024 (100%)
2. Relatório Geral Anual 2024 (95%)
3. Relatório de Gestão 2024 (80%)

Busca Fuzzy (Tolerância a Erros) ​

Sonic corrige automaticamente erros de digitação:

Busca: "relatorio" (sem acento)
Encontra: "Relatório" (com acento)

Busca: "momorando" (erro de digitação)
Encontra: "Memorando"

Busca: "dcreto" (letra faltando)
Encontra: "Decreto"

Busca por ID Digital ​

Busque diretamente por UUID:

Busca: "f47ac10b"
Resultado: Documento com ID Digital f47ac10b-58cc-4372-a567-0e02b2c3d479

Busca por Número ​

Busque por número do documento:

Busca: "2024/0045"
Resultado: Documento nº 2024/0045

Busca Parcial ​

Digite parte de uma palavra:

Busca: "rel"
Resultados:
- Relatório
- Relação
- Relaçãodocumentos

Sugestões de Busca ​

Sugestões Automáticas ​

Na homepage, o sistema exibe sugestões baseadas no índice:

typescript
// API endpoint
GET /api/trpc/document.getSearchSuggestions?word=doc&limit=5

// Resposta
["documento", "documentação", "documentos", "documental"]

Características:

  • Baseadas em termos indexados
  • Atualizam conforme conteúdo
  • Máximo 5 sugestões por padrão
  • Mínimo 1 caractere

Uso das Sugestões ​

  1. Sugestões aparecem abaixo do campo de busca
  2. Clique em uma sugestão
  3. Campo de busca é preenchido
  4. Busca é executada automaticamente
┌─ Campo de Busca ───────────────────────────┐
│ doc                                         │
└─────────────────────────────────────────────┘

Sugestões:
[documento] [documentação] [documental]

Integração com Filtros ​

A busca pode ser combinada com filtros:

Exemplo de Uso ​

Busca: "relatório"
Filtros:
- Tipo: Relatório
- Acesso: Público
- Data: 01/01/2024 - 31/12/2024

Resultado: Relatórios públicos de 2024 contendo "relatório" no texto

Ordem de Aplicação ​

1. Sonic busca por "relatório" → 100 IDs
2. Prisma filtra por tipo → 50 IDs
3. Prisma filtra por acesso → 30 IDs
4. Prisma filtra por data → 15 IDs
5. Paginação → 10 documentos/página

Resultados de Busca ​

Ordenação ​

Resultados ordenados por relevância:

Critérios de relevância:

  1. Correspondência exata no título (maior peso)
  2. Correspondência em palavras-chave
  3. Correspondência em descrição
  4. Correspondência em outros campos

Exemplo:

Busca: "relatório anual"

Resultados (ordenados):
1. "Relatório Anual 2024" (título exato)
2. "Relatório de Atividades Anuais" (título parcial)
3. "Relatório Técnico com dados anuais" (descrição)

Destaque de Termos ​

Termos buscados são destacados nos resultados (futuro):

Relatório Anual de Atividades
        ^^^^^ ^^^^^

Limite de Resultados ​

Sonic: Retorna top 100 documentos mais relevantes

Paginação: Frontend exibe 10-100 por página (configurável)

Indexação de Documentos ​

Indexação Automática ​

Documentos são indexados automaticamente em:

Criação:

typescript
// Após criar documento
await createProcessor(QUEUE.INDEX_DOCUMENT, {
  documentId: document.id,
  action: "index"
});

Atualização:

typescript
// Após atualizar documento
await createProcessor(QUEUE.INDEX_DOCUMENT, {
  documentId: document.id,
  action: "index" // Re-indexa com dados atualizados
});

Exclusão:

typescript
// Após soft-delete
await createProcessor(QUEUE.INDEX_DOCUMENT, {
  documentId: document.id,
  action: "remove"
});

Processamento em Background ​

Fila: INDEX_DOCUMENT (BullMQ)

Worker: Processa jobs de indexação assincronamente

Retry Policy:

  • Máximo 3 tentativas
  • Backoff: 5s, 10s, 20s

Estrutura de Indexação ​

Collection: documentsBucket: defaultObject ID: {id}:{digitalId} (composição)

Exemplo:

Object ID: "42:f47ac10b-58cc-4372-a567-0e02b2c3d479"
Texto: "Relatório Anual 2024 relatorio-anual-2024 ..."
Idioma: por (português)

Reindexação Manual ​

Quando Reindexar ​

Situações comuns:

  • Após importação em massa
  • Busca não retorna resultados esperados
  • Após atualização do Sonic
  • Após alteração em campos indexados
  • Índice corrompido

Como Reindexar ​

Via Interface (apenas ADMIN/SUPER):

  1. Acesse /settings?tab=parametros
  2. Seção "Configurações de Busca"
  3. Clique em "Reindexar Documentos"
  4. Confirme a ação
  5. Aguarde conclusão

Modal de progresso:

┌─ Reindexando Documentos ───────────────────┐
│                                             │
│  Processando documentos...                  │
│                                             │
│  [████████████░░░░] 75%                     │
│                                             │
│  750 de 1000 documentos indexados           │
│                                             │
└─────────────────────────────────────────────┘

Via API:

bash
curl -X POST http://localhost:4000/api/trpc/document.reindexSearch \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"

Processo de Reindexação ​

1. Flush da collection inteira no Sonic
2. Busca todos os documentos não-deletados
3. Processa em lotes de 50 documentos
4. Para cada documento:
   - Constrói texto de busca
   - Envia para Sonic
   - Atualiza contador
5. Conclusão e notificação

Fallback para Busca Prisma ​

Estratégia de Fallback ​

Se Sonic não estiver disponível, o sistema usa busca Prisma:

typescript
try {
  // Tenta busca com Sonic
  const results = await sonicSearch.query(...);
  where.id = { in: results };
} catch (error) {
  // Fallback para Prisma
  where.OR = [
    { title: { contains: search, mode: "insensitive" } },
    { digitalId: { contains: search, mode: "insensitive" } },
    { documentType: { name: { contains: search } } },
    // ... outros campos
  ];
}

Desvantagens do fallback:

  • Busca mais lenta
  • Sem fuzzy matching
  • Sem ordenação por relevância
  • Case-insensitive simples

Monitoramento ​

Status do Sonic ​

Verifique se Sonic está conectado:

bash
# Via netcat
echo "PING" | nc localhost 1491
# Resposta: PONG

# Via Docker
docker-compose ps sonic

Logs de Busca ​

Logs de busca são registrados no console:

[Sonic Search] Query: "relatório"
[Sonic Search] Results: 45 documents
[Sonic Search] Time: 0.8ms

Logs de Indexação ​

[Sonic Index] Indexing document 42
[Sonic Index] Text length: 543 characters
[Sonic Index] Success

Otimização ​

Dicas de Busca ​

Para usuários:

  1. Use termos específicos: "relatório anual 2024" em vez de "documento"
  2. Não se preocupe com acentos: Sistema encontra ambos
  3. Use palavras-chave: Termos do campo "palavras-chave" têm peso maior
  4. Combine com filtros: Refine resultados usando filtros

Para administradores:

  1. Incentive uso de palavras-chave: Campo importante para busca
  2. Preencha descrições: Aumenta pontos de busca
  3. Use títulos descritivos: Título tem maior peso na relevância
  4. Monitore índice: Reindexe periodicamente

Performance ​

Otimizações aplicadas:

  • Índice em memória (Sonic)
  • Cache de consultas recentes
  • Paginação eficiente
  • Batch processing na indexação

Limites recomendados:

  • Até 100.000 documentos: Performance ótima
  • 100.000 - 1.000.000: Performance boa
  • Acima de 1 milhão: Considerar sharding

Troubleshooting ​

Busca não retorna resultados ​

Causas:

  • Documento não indexado
  • Sonic desconectado
  • Índice vazio

Soluções:

  1. Verifique status do Sonic
  2. Execute reindexação manual
  3. Verifique logs do worker de indexação

Resultados inesperados ​

Causas:

  • Índice desatualizado
  • Fuzzy match muito agressivo
  • Documentos duplicados

Soluções:

  1. Reindexe documentos
  2. Verifique se documento foi atualizado recentemente
  3. Aguarde processamento do worker

Performance lenta ​

Causas:

  • Sonic sobrecarregado
  • Índice muito grande
  • Muitas conexões simultâneas

Soluções:

  1. Aumente recursos do Sonic (memória)
  2. Considere reduzir limite de resultados
  3. Implemente cache de buscas frequentes

Próxima Etapa ​

Continue para Campos Dinâmicos para aprender sobre o sistema de campos personalizados.

Sistema de Gestão de Arquivos Digitais

Copyright © 2024-presente ArqSystem