Endpoint GET /api/biblioteca/wiki — Help Widget

Cloudflare Pages Function que alimenta el Help Widget de CreaRack Pro con artículos de la wiki agrupados por categoría.

• Ruta: GET /api/biblioteca/wiki
• Handler: functions/api/biblioteca/wiki.ts
• Runtime: Cloudflare Pages Functions (Workers)
• Base de datos: D1 — tabla bib_wiki_pages

Descripción funcional

Devuelve las páginas wiki activas del Supercontexto agrupadas por categoría, listas para ser renderizadas en el panel de ayuda contextual de la aplicación.

Query principal

SELECT slug, title, file_path, tags
FROM bib_wiki_pages
WHERE status = 'active'
ORDER BY title

Parámetros de query string

Respuesta (JSON)

{
  "racks": {
    "label": "Rack Editor",
    "articles": [
      { "id": "crearack--racks--...", "title": "...", "slug": "...", "category": "racks", "product": "crearack", "path": "..." }
    ]
  },
  "monitoring": { ... },
  ...
}

Lógica de derivación de metadatos

Dado que bib_wiki_pages expone el slug canónico Supercontexto, la categoría y el producto se derivan del slug mediante regex, en lugar de leerlos de metadatos JSON (que era la causa del bug en bib_nodes).

deriveCategory(slug)

crearack--<category>--<rest>  →  category

Ejemplos: crearack--racks--modelo-rack → racks, crearack--monitoring--cns → monitoring.

deriveProduct(slug)

crearack-tech--...  →  "crearack-tech"
crearack--...       →  "crearack"
workspace--...      →  "workspace"
(otros)             →  "general"

La misma regla en los índices del sitio (09-09-2026)

Las páginas creadas por wiki_create_page y por el Ingest tampoco llevan product/category en el front-matter, y los índices Astro de la wiki (src/pages/wiki/*.astro) filtraban por el campo explícito: la Ayuda de usuario, que asumía crearack cuando faltaba, listaba 913 fichas internas del Supercontexto (998 artículos en vez de 86) y el índice del Supercontexto solo veía 36 de sus 914 páginas. Desde el PR #168 del workspace, src/lib/wikiMeta.ts aplica en los seis índices, la portada, el mapa y la página de detalle la misma regla que este endpoint: el campo explícito manda y, si falta, se deriva del slug (inferProduct; las fichas por tipo concept--, entity--, … → supercontext). La categoría solo se deriva cuando el slug es del mismo producto (inferCategory): una ficha concept--network--… etiquetada a mano como crearack-tech cae en general, no en una categoría inventada.

CATEGORY_LABELS (mapeo a etiquetas humanas)

Si una categoría derivada del slug no tiene entrada aquí, el fallback (CATEGORY_LABELS[cat] || cat) muestra el slug crudo como nombre de categoría en el panel — degradación silenciosa, no error. Las 3 claves ups/wireless/settings faltaban desde que existían páginas con esas categorías; se añadieron en el commit b58b7fb4 (23-08-2026, task #254) junto con un test de regresión (test/help-corpus-parity.test.ts) que ahora falla en CI si aparece una categoría sin etiquetar. Detalle del incidente: [[incident—20260823—help-corpus-parity-en-es]].

Historial: migración de bib_nodes a bib_wiki_pages

Bug detectado — sesión 38

El menú General Concepts del Help Widget mostraba slugs (crearack--conceptos--glosario.md) en lugar de títulos (Glosario).

Causa raíz: el endpoint leía de bib_nodes (tabla legacy del grafo de conocimiento) con el filtro metadata LIKE '%"wiki":true%'. En muchos nodos, category estaba vacío (fallback a general) y display_name contenía el nombre de fichero en lugar del título del frontmatter.

Por qué bib_nodes estaba desincronizado: bib_nodes se indexa con el crawler de la Biblioteca y no siempre refleja el frontmatter Supercontexto actualizado. En cambio, bib_wiki_pages se actualiza mediante wiki_index_metadata en cada ingest post-merge, por lo que siempre tiene title, status y file_path correctos.

Cambio aplicado (commit e65778d)

Nota: bib_nodes sigue siendo la tabla operativa del grafo de conocimiento (nodos indexados de código). Solo se descartó su uso como fuente de artículos wiki para este endpoint.

Dependencias

• D1 database: binding DB en el entorno CF Pages.
• Tabla: bib_wiki_pages — mantenida por wiki_index_metadata (ingest Supercontexto).
• Build: 334 páginas activas confirmadas en el build de deploy post-fix.

Véase también

• [[workspace—que-es-workspace]]
• [[incident—20260823—help-corpus-parity-en-es]]