feadulta/docs/plan-buscador-typesense.md

Plan de implementación — Buscador con Typesense (feadulta #8, fase 2)

Estado: plan para ejecutar (pensado para que lo ejecute un agente Sonnet). Fase 1 (MVP nativo) ya está en producción — ver feadulta-buscador-8 / issue #8: barra de búsqueda visible en móvil (mu-plugins/fea-search.php) + resultados en rejilla (scripts/set_search_template.php). Esta fase 2 sustituye el motor por Typesense manteniendo/мejorando esa UI, y añade búsqueda por autor (faceta).

DECISIÓN PENDIENTE (Rafa) — dónde corre Typesense en producción. Todo lo demás se puede construir y validar en local sin esa decisión (Typesense en Docker local). Opciones de despliegue público (decidir luego): (a) PC + Cloudflare Tunnel search.feadulta.com (coste 0, atado al PC encendido, fallback al buscador nativo); (b) VPS pequeño dedicado ~4-6€/mes (fiable); (c) Typesense Cloud (gestionado). El hosting actual (cPanel compartido, sin Docker/systemd/root) no sirve para el motor.

Decisiones ya tomadas

• Integración: Custom InstantSearch (indexador propio + UI InstantSearch.js), NO plugin.
• Motor: Typesense self-host en Docker.
• Fallback: si Typesense no responde, mantener el buscador nativo (/?s=) ya desplegado.

Arquitectura

Navegador del usuario
   └── InstantSearch.js (typesense-instantsearch-adapter)  ── HTTPS ──►  Typesense
          (página /buscar en WP, search-only API key)                    (Docker)
                                                                            ▲
WP (wp-nuevo)  ── indexador (wp-cli/PHP) admin API key ──────────────────────┘
   └── hook publish_post / cron: reindexa incremental

Pasos (ejecutables por Sonnet)

A. Typesense local de desarrollo (no depende de la decisión de infra)

1. Añadir servicio typesense a docker-compose.yml (imagen typesense/typesense:27.x), volumen de datos, --api-key admin de desarrollo, puerto 8108 solo en localhost.
2. Levantar y verificar salud: GET http://localhost:8108/health → {"ok":true}.

B. Schema de la colección feadulta_posts

Campos: id(post_id), title, content (texto plano, sin HTML), excerpt, author_id(int32, facet), author_name(string, facet), date(int64, sort), url, lang(string, facet: es/en/fr/it/pt), categories(string[], facet), thumbnail(opcional). default_sorting_field: date.

C. Indexador (scripts/typesense_index.php, wp-cli wp eval-file)

1. Recorre posts publish (post), excluye los template/feedback CPT.
2. Por cada post construye el documento (content = wp_strip_all_tags, author_name = display_name del post_author, lang vía Polylang pll_get_post_language, categories por slugs). Sube en lotes (import JSONL, action=upsert).
3. Idempotente, reanudable, con --since para incremental. ~24.778 posts.
4. Reindexado en caliente: hook publish_post/save_post → upsert de ese documento; before_delete_post → delete. (Encolar para no penalizar el guardado.)

D. UI InstantSearch (sustituye/mejora la página de resultados)

1. Página /buscar (o el propio template search) con InstantSearch.js + typesense-instantsearch-adapter, apuntando a la URL pública de Typesense y la search-only key (nunca la admin) — ambas configurables (constantes en un mu-plugin fea-search-typesense.php, vacías hasta decidir la infra → fallback nativo).
2. Widgets: searchbox, hits (tarjetas con la estética actual fea-archive-card), refinement por autor (faceta author_name), por idioma y por categoría, paginación. Resaltado de coincidencias.
3. Multiidioma: filtrar lang = idioma actual por defecto; textos de UI por idioma.
4. Mantener la barra móvil de fase 1 como entrada; en desktop, integrar con el buscador del menú.

E. Seguridad de claves

• Admin API key: solo en el servidor (indexador), nunca en el front.
• Search-only key: restringida a la colección, embebida en el front (es segura por diseño).
• CORS de Typesense limitado al dominio del sitio.

F. Exposición pública (BLOQUEADO por la decisión de infra)

• Opción PC+Tunnel: cloudflared → search.feadulta.com → localhost:8108.
• Opción VPS: Typesense en el VPS + Caddy/HTTPS en search.feadulta.com.
• Opción Cloud: usar el endpoint y keys que da Typesense Cloud.
• En los tres casos, la UI solo necesita la URL pública + search-only key.

Verificación

• Local: /health ok; typesense_index.php indexa N docs; la página /buscar devuelve resultados relevantes y la faceta de autor filtra (probar «González Amaro», «Pagola»).
• Comparar relevancia vs buscador nativo en consultas reales del feedback («reflexiones», búsqueda por autor).
• Prod: tras exponer el motor, repetir desde un navegador (Cloudflare bloquea headless).

Riesgos / notas

• Disponibilidad si corre en el PC: caídas → debe degradar al buscador nativo, no a error.
• RAM: Typesense mantiene el índice en memoria; 24.778 posts de texto entran de sobra en <1 GB, pero dimensionar el host en consecuencia.
• Reindexado masivo inicial puede tardar; hacerlo por lotes y fuera de hora punta.
• No exponer nunca la admin key; CORS restringido.