[HU] Acortador de Enlaces para Laboratorios (Cloudflare Pages Functions)

[madmti]

Historia de Usuario

Yo como estudiante quiero generar un enlace corto y limpio al compartir mis configuraciones y scripts para evitar URLs sospechosamente largas, prevenir errores de truncado en apps de mensajería y mejorar la estética al compartir mi trabajo.

Criterios de Aceptación

• Generación de enlace corto: Dado un estudiante que ha diseñado un laboratorio con scripts y variables cuando presiona el botón "Compartir" entonces la app debe realizar una petición POST en background a una ruta de Cloudflare Pages Functions, almacenar el JSON en Cloudflare KV asociado a un ID único de 6 caracteres y devolverle al usuario la URL corta simplificada (ej: https://lab.ramolibre.app/?s=r8Xb2p).
• Hidratación asíncrona sin recarga: Dado un usuario que abre un enlace corto de Ramo Libre Lab cuando la SPA estática generada por adapter-static se monta en el navegador y detecta el parámetro ?s= en la URL entonces debe realizar un único fetch asíncrono a la Pages Function en segundo plano para recuperar el JSON desde KV e hidratar el laboratorio de inmediato, evitando redirecciones HTTP (302) que ralenticen la carga.
• Ciclo de vida autolimpiable (TTL): Dado un laboratorio guardado en Cloudflare KV cuando se registra su creación o cada vez que un usuario nuevo abre el enlace corto entonces la Pages Function de lectura debe configurar o renovar automáticamente el parámetro expirationTtl a 6 meses (180 días), asegurando que los enlaces inactivos se eliminen solos para no saturar el almacenamiento gratuito de 1 GB.
• Mecanismo de contingencia (Fallback): Dado que el volumen de compartición de enlaces agota la cuota mensual de escrituras gratuitas de Cloudflare KV cuando un usuario intente generar un enlace y la Pages Function retorne un error de límite excedido o error de red entonces la app cliente debe capturar el fallo de forma silenciosa y generar como fallback el enlace largo original encodeado en Base64, garantizando que la funcionalidad de compartir nunca se rompa.

Notas técnicas para el desarrollo

• Arquitectura de Archivos: La API dinámica de respaldo debe implementarse de forma externa al ciclo de vida de SvelteKit utilizando la carpeta nativa /functions/api/ en la raíz del proyecto para no alterar la configuración actual de adapter-static.
• Estructura del ID: El ID corto generado por la Pages Function debe usar caracteres alfa-numéricos seguros para URL (evitando colisiones utilizando un generador de entropía suficiente, como un hash recortado o un fragmento pseudoaleatorio seguro).
• Optimización de Lecturas: Al implementar la renovación del TTL en cada lectura (GET), asegúrate de retornar el JSON inmediatamente al cliente y realizar la extensión del .put() en segundo plano utilizando context.waitUntil(promise) en la función de Cloudflare para no bloquear ni añadir latencia a la respuesta que recibe el estudiante.