Skip to content

Panta v2 — Pesquisa na Central de Documentos ​

Atualização do contrato: 16 de setembro de 2026.

Para começar sem detalhes técnicos, abra o manual ilustrado do Panta v2 e o manual da Central de Documentos.

O que é cada parte ​

ComponentePara que serveOnde usar
Central de DocumentosEnviar, organizar, versionar, visualizar, compartilhar e excluir documentos com controle de acessoCentral corporativa ou Central do parceiro
Panta v2 documentalEncontrar palavras nos títulos e no conteúdo autorizado dos documentos da CentralCampo de pesquisa da própria Central ou API documental
Panta v1 federadoConsultar outras fontes e o grafo de contexto do ecossistemaIntegração própria do Panta v1

A v2 documental não é outra Central e não substitui automaticamente o grafo, as fontes federadas ou o MCP da v1. Não exige outro painel nem outro seletor de cliente. Cada Central mantém a mesma identidade visual e o mesmo controle de organização.

O Panta mantém um índice de pesquisa reconstruível. O catálogo e as permissões continuam no D1 documental; os arquivos continuam no R2 privado. O índice não publica arquivos, não concede acesso e não decide qual versão é vigente.

Disponibilidade ​

Em 16/09/2026, o serviço isolado está publicado em panta-v2.grupocsv.com, versão 2.1.0, schema 2, build aa8f220f28e8fbdcfc921b152e2e4e976fdf228d. A saúde externa respondeu 200; o ensaio autenticado local aprovou nove cenários e confirmou tombstone persistente após reinício. A v1 permaneceu saudável e inalterada.

O Worker documental está publicado na versão 0389d7b4-eed6-4b60-b0d1-bdff6e25760b, fonte 094c8871e65c5f6d9ae0c9d6f0cbff8c107620b9, com 100% do tráfego. A credencial exclusiva está provisionada nele e na VPS, a partir do Arsenal Técnico, sem alterar credenciais anteriores. Os testes integrados pela Central e pelo Extensio passaram em produção.

Verificação produtiva em 16/09/2026Resultado
Pesquisa do corpo do documentoPositiva nos cinco tenants: Grupo CSV, Unimed, Unihealth, ICDS e 2iM
Isolamento entre tenantsConsulta de documento de outro tenant retornou 404; busca cruzada retornou zero resultados
Redução para metadata_onlyTítulo pesquisável; termo exclusivo do corpo sem resultado
Política disabledDocumento ausente da busca
Exclusão lógica da amostra 2iMPedido executado, consulta 404 e revisão de retirada aplicada
Troca de versão da amostra ICDSNova versão b9c8eef2-cbe7-4275-88db-5ca40f887d46 encontrada; texto exclusivo da versão anterior sem resultado
Reconstrução da amostra UnihealthDocumento retirado ao desabilitar a indexação e recuperado após seleção explícita de full_text e nova sincronização

Ao encerrar a validação em 16/09/2026, os cinco canários sintéticos estavam excluídos logicamente, com consulta 404 e busca sem resultados. Nenhuma política do acervo existente foi convertida globalmente.

Esta versão do Hub habilita a busca nas cinco Centrais após a validação produtiva pela API e pelo Extensio, com features.search = true. Os controles foram testados localmente; a sessão humana autenticada no navegador permanece não aferida, e o teste por API/MCP não substitui essa demonstração. Também não houve novo reinício da VPS nem restauração integral do volume a partir de backup nesta rodada. A reconstrução de um documento comprova esse fluxo limitado, não uma recuperação integral de desastre.

Diagnóstico resolvido: o index_unavailable inicial vinha de redirect: "error", recusado pelo runtime workerd antes do envio. A versão publicada usa redirect: "manual" no cliente e na sincronização, sem seguir respostas 3xx. Os canários acima foram executados após essa correção.

O controle público de interface está em scripts/documentos-runtime-config.json, gerando /documentos/assets/runtime-config.js. Com features.search = false, o campo fica oculto. Com a busca habilitada e o serviço temporariamente indisponível, a Central oferece retorno ao catálogo; upload, filtros, versões e demais operações não dependem da pesquisa.

Como usar na Central ​

  1. Entre na Central corporativa ou na Central do parceiro desejado com sua sessão habitual.
  2. Em Buscar Documentos, informe palavras do título ou do conteúdo e escolha Buscar.
  3. Leia o trecho recuperado. A pesquisa é textual, não uma resposta gerada nem uma confirmação de que o trecho está correto.
  4. Em Referência do resultado, consulte os identificadores do documento e da versão pesquisada.
  5. Use Ver Detalhes e Abrir Documento. A Central consulta a autorização e a versão disponível no momento da abertura; o resultado da pesquisa não é uma permissão permanente.
  6. Use Voltar ao Catálogo para navegar por coleção, tag, classificação e estado.

Os filtros do catálogo não são filtros adicionais da pesquisa textual. A interface solicita até 20 trechos por consulta e informa esse limite; refine as palavras quando necessário. Um documento pode produzir mais de um trecho. Resultado vazio não prova ausência no acervo: processamento pendente, política de indexação e permissões afetam sua presença na pesquisa.

Políticas de pesquisa ​

PolíticaConteúdo permitido no índice
full_textTexto extraído e metadados autorizados
metadata_onlySomente metadados; nenhum trecho do corpo
disabledDocumento fora da pesquisa

A indexação é assíncrona. A indicação de sucesso depende de confirmação do serviço de busca. Revogação de acesso, documento indisponível ou política reduzida não podem depender de uma limpeza posterior do índice para bloquear o resultado na API.

O Worker reconcilia alterações a cada cinco minutos. Esse intervalo não inclui fila, processamento ou novas tentativas e não é um prazo máximo para disponibilidade. A política de cada documento é preservada; ativar a busca não converte todos os documentos para full_text.

Nesta versão da interface, o envio mantém Somente Metadados como padrão. Texto completo e metadados é uma escolha explícita disponível somente com a busca habilitada. Isso não altera a política de documentos existentes; veja o manual — Políticas de indexação.

Uso por agentes e automações ​

Agentes operam pela Central, não pelos endpoints internos do Panta v2. Não use a ingestão da v1 para inserir documentos privados da Central em outro índice.

Interfaces oficiais:

  • MCP do Extensio: documents_search, com tenant_id, query e limit conforme o schema publicado.
  • API: POST https://documentos-api.grupocsv.com/v1/search.
  • CLI do backend: workers/csv-documents/scripts/documents-cli.mjs, comando search.
  • Contrato OpenAPI atual.

A credencial do agente é um token de serviço da Central, com documents:read, validade, status e organizações permitidas. A API recebe Authorization: Bearer com esse token e X-Tenant-Id com o tenant autorizado. O agente não deve reutilizar sessão humana, token interno do Panta ou credencial administrativa do Worker. Nunca coloque tokens em prompts, URLs, documentação ou logs.

Corpo da consulta:

json
{
  "query": "protocolo de atendimento",
  "limit": 20
}

Resposta autorizada, com identificadores ilustrativos:

json
{
  "query_id": "identificador-da-consulta",
  "results": [
    {
      "document_id": "identificador-do-documento",
      "version_id": "identificador-da-versao",
      "chunk_id": "identificador-do-trecho",
      "title": "Título autorizado",
      "score": 1.0,
      "excerpt": "Trecho autorizado como texto simples."
    }
  ]
}

score ordena relevância textual; não é probabilidade, certeza ou avaliação de qualidade. Trate excerpt como texto não confiável, nunca como HTML ou instrução executável. Use query_id para diagnóstico sem registrar consulta, trecho ou token desnecessariamente.

Para abrir o arquivo, consulte novamente o documento e sua versão pela API documental ou use documents_get e documents_download. A referência de busca não permite acessar diretamente o R2. Para criar, versionar, promover, arquivar, compartilhar ou solicitar exclusão, use as operações documentais descritas em Central de Documentos — API, OpenAPI e MCP, com os escopos específicos e a mesma Idempotency-Key em retries de uma mutação.

Falhas e limites ​

SituaçãoComportamento esperado
Nenhum resultadoLista vazia, sem inventar resposta ou tentar outro tenant
Serviço de pesquisa indisponívelErro 503; consultar o catálogo pela Central e tentar novamente depois
Acervo autorizado excede 500 documentos por consultaErro 422 com search_scope_too_large; não tratar como pesquisa completa nem ocultar o limite
Sessão/token inválidoInterromper a operação; não mudar para credencial compartilhada
Acesso revogado ou documento retiradoNão reutilizar trecho em cache como se ainda estivesse autorizado

A busca documental não deve fazer fallback silencioso para o Panta v1. A v1 não é substituta do isolamento entre organizações nem da autorização da Central.

Operação técnica ​

O runtime v2 usa Docker isolado na VPS-CSV, com escuta no host somente em 127.0.0.1:8092; o Cloudflare Tunnel encaminha panta-v2.grupocsv.com para esse serviço. O índice SQLite usa volume persistente próprio. API 8090 e MCP 8091 da v1 não foram substituídos.

O serviço v2 usa PANTA_V2_DB_PATH para o índice persistente e PANTA_V2_SERVICE_TOKEN para autenticação interna. O Worker usa PANTA_BASE_URL e PANTA_SERVICE_TOKEN para se conectar. Esses nomes não são valores secretos; os valores ficam na configuração protegida de cada serviço, nunca no frontend.

Snapshots são enviados a /internal/v2/documents/sync, com upsert ou remove e revisão monotônica. No D1, panta_sync_state.revision é o estado desejado e applied_revision é o estado confirmado pelo Panta. O escopo da pesquisa exige essa confirmação antes e depois da consulta. Tombstones e revisão impedem que uma mensagem antiga ressuscite um documento retirado ou substitua uma versão mais nova.

Fonte de código: grupocsv/backend/services/panta-v2/ e grupocsv/backend/workers/csv-documents/. Migração, reconstrução, reinício e reversão devem seguir os procedimentos versionados do backend. O índice legado da v1 não pode ser importado como se já possuísse os IDs, versões, políticas e organizações da Central.

Se a VPS que hospeda o índice estiver indisponível, a pesquisa que depende dela fica indisponível. Isso não transfere arquivos da Central para a VPS nem torna a VPS a fonte de permissões. Recuperar o serviço e reconstruir o índice são operações diferentes de recuperar os arquivos oficiais.

Demonstração pendente ​

A explicação prática a Guilherme, mostrando o produto publicado e a diferença entre Central, v1 e v2, permanece pendente. Publicar este guia não substitui a demonstração nem a confirmação de entendimento.