Help Widget — Atajos FAQ, búsqueda local y whitelist product (I4)

Help Widget — Atajos FAQ, búsqueda local y whitelist product (I4)

Iniciativa I4 del plan post-audit Supercontexto (sesión 27, tag supercontext/sesion-27-i4-done). Completa el refactor del Help Widget contextual de CreaRack Pro añadiendo tres capacidades: atajos rápidos (FAQ chips), búsqueda local de títulos cliente-side, y filtrado por producto mediante whitelist server-side.

Contexto y motivación

El Help Widget existente sólo ofrecía el modo “Ask” (IA) y el Browse por categorías. Problemas detectados en el audit Supercontexto:

• Latencia percibida: cada consulta invocaba al asistente aunque el usuario sólo quisiera abrir un artículo concreto.
• Coste innecesario: queries triviales (“¿qué es el Map Editor?”) consumían tokens de IA.
• Contaminación del corpus: el endpoint /api/help/wiki servía también documentación interna (workspace-tech, crearack-tech) al usuario final.
• Ruido en UI: se mostraba la latencia del asistente (123ms) — dato técnico irrelevante para el usuario.

Cambios implementados

1. Atajos rápidos (FAQ chips)

Archivo: static/js/alpine-components.js — componente helpWidget

Se añade el array faqs[] con 7 accesos directos preseleccionados:

Flujo openFaq(slug):

1. Si total === 0, carga el catálogo wiki (loadWiki()).
2. Busca el artículo por slug dentro de categories.
3. Si encontrado y tiene path → abre el artículo inline (openArticle(path)). Latencia 0, coste 0.
4. Fallback: si el slug aún no está indexado en D1, cambia a tab “buscar” y lanza this.ask() con el label del FAQ como pregunta.

Los chips sólo se muestran cuando no hay categoría activa, no hay artículo abierto y no hay texto en el buscador (showFaqs getter).

CSP-safe: el handler global openHelpFaq(el) en base.js despacha el evento help-open-faq al componente Alpine, evitando onclick inline prohibidos por la Content Security Policy.

// base.js
function openHelpFaq(el) {
    var slug = el && el.dataset ? el.dataset.slug : '';
    if (slug) window.dispatchEvent(new CustomEvent('help-open-faq', { detail: { slug: slug } }));
}

<!-- base.html — Alpine listener -->
@help-open-faq.window="openFaq($event.detail.slug)"

2. Búsqueda local de títulos (cliente-side)

Archivos: alpine-components.js, templates/base.html, help.css

• Estado search: '' en el componente Alpine.
• Getter filteredCategoryList: filtra categoryList por title.toLowerCase().indexOf(q). Agrupa los resultados por categoría.
• Getter hasSearchResults: filteredCategoryList.length > 0.
• Método clearSearch(): resetea search a ''.

Comportamiento UI:

• Mientras search está vacío → se muestra el grid de categorías normal.
• Con texto en el buscador → se oculta el grid de categorías y se muestra help-search-results (lista plana agrupada por categoría).
• Si no hay coincidencias → mensaje “No articles match this search.”

Sin latencia ni coste: el filtrado opera sobre el catálogo ya cargado en memoria del navegador.

3. Whitelist por producto (server-side)

Archivo: core/api_help.py

Antes: filtrado por blacklist de categorías (_PRIVATE_CATEGORIES = {"workspace"}), eliminando categorías completas del response.

Después: whitelist por product:

_USER_FACING_PRODUCT = "crearack"

# En help_wiki():
resp = requests.get(
    f"{WORKSPACE_URL}/biblioteca/wiki",
    headers=_workspace_headers(),
    params={"product": _USER_FACING_PRODUCT},  # ← nuevo
    timeout=TIMEOUT,
)

El workspace filtra server-side: sólo devuelve pages con product == "crearack". Pages con product = workspace-tech, product = crearack-tech o sin product quedan excluidas del Help de usuario.

Companion changes en workspace (commit 96d5238):

• 3 pages nuevas: crearack--conceptos--primeros-pasos, crearack--monitoring--que-es-wireless, crearack--monitoring--que-es-ups.
• 2 pages editadas con sección “Como empezar”.
• Endpoint functions/api/biblioteca/wiki.ts acepta ?product=.

4. UI más limpia en respuestas de IA

// Antes
get answerMeta() { return ... + ' sources · ' + (this.answer.duration_ms || 0) + 'ms'; }
// Después
get answerMeta() { return ... + ' sources'; }

Se elimina la latencia (duration_ms) del texto visible al usuario. Sólo se muestra el número de fuentes consultadas.

Arquitectura de componentes

base.html (template)
  └─ Alpine helpWidget (alpine-components.js)
       ├─ faqs[]              → FAQ chips (openFaq)
       ├─ search              → estado búsqueda local
       ├─ filteredCategoryList → getter computed
       └─ openFaq(slug)       → resolve path o fallback ask

base.js (global handlers)
  └─ openHelpFaq(el)         → dispara CustomEvent 'help-open-faq'

core/api_help.py
  └─ GET /api/help/wiki      → proxy con ?product=crearack
       └─ workspace /biblioteca/wiki?product=crearack (CF Workers D1)

Trade-offs y deuda técnica

Clases CSS añadidas

Véase también

• [[entity—core—endpoint—api-help-wiki]]