Regras de Funcionamento — Busca Geral do OLA

1. Finalidade

Esta página define as regras de funcionamento do subsistema Busca Geral do OLA. Seu objetivo é orientar como a busca deve ser gerada, atualizada, usada e evoluída dentro da arquitetura do OLA.

3. Regra de escopo

A busca deve localizar apenas arquivos públicos e úteis para consulta, aprendizagem, navegação e recuperação de conhecimento no OLA.

4. Regra da fonte da verdade

A fonte primária da busca deve ser a estrutura física real do OLA, isto é, suas pastas e arquivos.

Estrutura física do OLA
        ↓
gerar_busca_index.py
        ↓
busca_index.json
        ↓
busca.html

Portanto, a busca não deve depender de cadastro manual item a item.

5. Regra de geração do índice

O arquivo busca_index.json deve ser gerado automaticamente por um script local, executado no Mac, antes da publicação.

python3 gerar_busca_index.py

O script deve percorrer as pastas autorizadas, identificar os arquivos permitidos e montar um índice consultável pela página busca.html.

6. Regra de atualização

Sempre que houver inclusão, exclusão ou alteração relevante de páginas, imagens ou PDFs, o índice deve ser atualizado.

7. Regra de nomenclatura

Os nomes dos arquivos devem favorecer a recuperação. O nome do arquivo também é informação de busca.

8. Regra de classificação automática

Cada item indexado deve receber informações derivadas automaticamente do próprio caminho e da extensão do arquivo.

{
  "titulo": "OLA como Organismo Vivo",
  "caminho": "demandas/ola_organismo_vivo/ola_como_organismo_vivo.png",
  "area": "demandas",
  "formato": "imagem",
  "extensao": "png"
}

9. Regra de recuperação

A busca deve considerar, no mínimo, os seguintes elementos:

• nome do arquivo;
• caminho do arquivo;
• área ou pasta principal;
• tipo de arquivo;
• extensão do arquivo.

Exemplo: a busca por organismo vivo deve recuperar arquivos cujo nome ou caminho contenha esses termos, mesmo que o usuário não saiba o nome completo.

10. Regra de abertura dos resultados

Todo resultado encontrado deve possuir link clicável para abertura do arquivo.

• Páginas HTML devem abrir como páginas navegáveis.
• Imagens devem abrir em nova aba ou painel do navegador.
• PDFs devem abrir no visualizador do navegador.

11. Regra de miniaturas

Quando o resultado for uma imagem, a busca deve mostrar uma miniatura clicável.

Resultado de imagem:
- título
- miniatura clicável
- caminho clicável
- área
- extensão

12. Regra de exclusão da indexação

O gerador deve ignorar arquivos e pastas que não devem aparecer para o usuário final.

.DS_Store
.git/
__pycache__/
node_modules/
backup/
rascunhos/
arquivos_temporarios/
*.tmp
*.bak

14. Regra de responsividade

A página de busca deve funcionar em celular, tablet, desktop e TV, respeitando o padrão visual do OLA.

• No desktop, pode usar filtros e resultados em área ampla.
• No celular, os resultados devem aparecer em cards empilhados.
• Miniaturas não devem ultrapassar a largura da tela.
• Caminhos longos devem quebrar linha ou ter rolagem controlada.

15. Regra de funcionamento sem back-end

Na primeira versão, a busca deve funcionar apenas com:

HTML
CSS
JavaScript
JSON

Ela não deve depender de banco de dados, login, PHP, Node.js ou Python no servidor. O Python será usado apenas localmente para gerar o índice.

16. Regra de publicação

Após gerar o índice no Mac, devem ser publicados na Hostinger:

busca.html
busca_index.json
novas páginas
novas imagens
novos PDFs

O arquivo gerar_busca_index.py pode permanecer no Mac e não precisa ser publicado, a menos que seja desejado como documentação técnica.

17. Regra para testes e TDD

Para cada regra importante da busca, deve existir pelo menos um caso de teste.

18. Regra de evolução

A busca deve começar simples, mas preparada para evoluir.

• Versão 1: busca por nome, caminho, área e extensão.
• Versão 2: extração de título das páginas HTML.
• Versão 3: busca em conteúdo textual das páginas.
• Versão 4: filtros por demanda, entrega, domínio, fundamento e tipo de artefato.
• Versão 5: busca semântica ou apoio por IA.

20. Rastreabilidade entre requisitos e regras