Revertir "Documentación Funcional nativa" → volver a VitePress externo

Date: 2026-07-25 Status: ✅ Implementado (los 2 pasos) — ver "Notas de implementación" al final para las decisiones tomadas donde la especificación original no alcanzaba a cubrir el caso real.

Contexto

El commit 113119f ("Documentación/Funcional: renderizado nativo de markdown+mermaid en Vue, no link externo") reemplazó el link externo a VitePress por un renderizado nativo del markdown dentro de la SPA. El cliente probó el resultado y no quedó bien — se pide volver al enfoque de link externo a VitePress.

Paso 1 — Revertir el commit

git revert 113119f

Es un commit único y acotado, no un merge — el revert debería aplicar limpio. Si hay conflicto (posible, porque feature/reportes-dashboard-auditoria, que se mergeó después, también puede haber tocado AppLayout.vue), resolverlo a mano: lo que hay que preservar son los cambios de reportes-dashboard-auditoria, y lo que hay que sacar es específicamente el componente/lógica de renderizado nativo de markdown que agregó 113119f.

Paso 2 — Aplicar el fix de VitePress externo

El archivo referenciado acá originalmente (doc/plans/2026-07-25-fix-link-funcional-vitepress-local.md) y su zip nunca llegaron a existir en el repo — se buscó en el working tree, todo el historial de git (todas las ramas) y en Downloads/Desktop del usuario, sin encontrarlo. Se reconstruyó el punto 2 desde la especificación de este documento (URL vía env var + traefik + VitePress real en dev), con el usuario confirmando explícitamente que procediera así (no bloquear a la espera del archivo).

Hecho:

• URL del link "Funcional" sale de VITE_DOCS_URL (frontend/.env.local / .env.example), con fallback al dominio de producción hardcodeado anterior si no está seteada.
• docker-compose.yml suma traefik (reverse proxy) + docs-vitepress (VitePress real, antes solo corría a mano con cd doc && npm run docs:dev), para que http://docs.soterex.localhost funcione sin puerto en dev.

Ver el detalle completo de las decisiones no cubiertas por la especificación original (naming, Docker socket) en "Notas de implementación" abajo.

Verificación final

• [x] git log ya no muestra ningún componente de renderizado nativo de markdown en uso (8272c7e, revert de 113119f limpio salvo package-lock.json, resuelto regenerando el lockfile).
• [x] El link "Funcional" del sidebar abre http://docs.soterex.localhost en una pestaña nueva, y ese sitio carga el VitePress real — verificado con curl (HTTP 200, bootstrap real de VitePress) y confirmando que el módulo servido de AppLayout.vue usa el valor real de VITE_DOCS_URL, no el fallback. Sin navegador en esta sesión — verificación visual final pendiente de que el usuario la confirme a mano.
• [x] docker compose up sigue levantando todo sin errores después del revert — docs (ReDoc, servicio preexistente) y backend verificados sin regresión.

Notas de implementación (decisiones no cubiertas por la especificación original)

1. Naming — docs-vitepress, no docs: ya existía un servicio docs en docker-compose.yml para un propósito completamente distinto (portal ReDoc de las 4 APIs de Soterex, doc/site/, puerto 8082 — ver doc/site/README.md). El sitio VitePress del proyecto (doc/.vitepress, Análisis Funcional/ADRs/planes/QA) es otra cosa; se agregó como docs-vitepress para no pisar el nombre existente. Ninguno de los dos se tocó/renombró.

2. traefik con provider de archivo, no de Docker: el diseño original ("traefik con labels") asume el provider de Docker (descubrimiento vía socket). En la práctica, con OrbStack (el runtime de Docker de esta máquina) el socket no se expone a contenedores de la misma forma que Docker Desktop — confirmado con una prueba independiente (un contenedor descartable intentando hablar con el socket, sin traefik de por medio, también falló). Como acá alcanza con una sola ruta estática (docs.soterex.localhost → docs-vitepress:5173), se usó el provider de archivo (infra/traefik/dynamic.yml) en vez de insistir con el socket — más simple, sin permisos especiales, y portable a cualquier runtime (Docker Desktop, Engine, OrbStack, Colima) sin configuración adicional.

3. .localhost sin tocar /etc/hosts: el sufijo .localhost resuelve a loopback en cualquier resolver moderno (RFC 6761) — no hizo falta ninguna configuración de DNS/hosts local.