Resolver la variante de media de Docs
Usa esta guía para comprobar cómo Antylogic elige el fichero de media devuelto para una petición de detalle de artículo de Docs. La acción es de solo lectura: normaliza locale, plataforma y tema, devuelve la URL del asset de docs coincidente y deja la media no disponible como metadatos planificados en lugar de hacer fallar el artículo.
En este artículo
Usa esta guía cuando un operador de soporte, QA, documentación o captura de demos necesite entender por qué un artículo de Docs muestra una imagen o vídeo concretos para el locale, dispositivo y tema actuales.
El resolutor solo se ejecuta al construir una respuesta de detalle de artículo. No cambia contenido de Docs, assets, usuarios, permisos ni datos de demo. Las peticiones de detalle públicas devuelven URLs de assets públicos, y las peticiones autenticadas de la app devuelven URLs de assets de la app.
Antes de empezar
- El contenido y los assets de docs están configurados para el entorno en ejecución.
- Abre una ruta de detalle de artículo, no solo el índice de Docs.
- El artículo solicitado existe tras la normalización del locale; `es-ES` se trata como `es`.
- La entrada de media tiene un `variantPublicSrc`, `themePublicSrc` o `publicSrc` utilizable cuando se espera media renderizada.
- Para `/api/app/docs`, inicia sesión con el usuario demo en la sesión demo de ES. `/api/public/docs` no requiere inicio de sesión.
Instrucciones
- 1.
Abre el detalle del artículo
Solicita el detalle del artículo con el locale, la plataforma y el tema requeridos. Para la superficie pública, usa `/api/public/docs/calendarios/es-ver-calendario-general?locale=es-ES&platform=tablet&theme=light`. Para la superficie de la app con sesión iniciada, abre `antylogic://docs/calendarios/es-ver-calendario-general` en la sesión de ES de Grupo Marea Demo.
- 2.
Comprueba los campos de media resueltos
Inspecciona `article.media[]`. El resolutor prueba primero la plataforma y el tema solicitados y después sigue el orden fijo de fallback. En el ejemplo actual de Calendarios, una petición tablet/light puede resolver a la variante de vídeo disponible de iPad en oscuro, así que `src`, `resolved_platform`, `resolved_theme`, `available_platforms` y `available_themes` explican el fichero seleccionado.
- 3.
Abre la URL del asset devuelta
Usa el `src` devuelto para obtener la media a través de la ruta de assets de docs. La URL debe mantener el mismo prefijo que la petición de detalle, por ejemplo `/api/public/docs/assets/ipad/dark/es/ver-calendario-general/calendars-view-general-overview-clip.mp4` para el ejemplo público.
- 4.
Trata la media planificada como pendiente
Si una entrada de media no tiene fuente utilizable, conserva la respuesta del artículo y trata la media como pendiente. Un `src` ausente no es un fallo del artículo; significa que la media está planificada o que la fuente seleccionada no pudo convertirse en una ruta segura de asset de docs.
Validaciones y límites
- La resolución de media es para respuestas `GET` de detalle de artículo; los métodos no soportados devuelven `405 metodo no permitido`.
- `locale` se normaliza a `en` o `es`; los valores no soportados o vacíos caen a `es` en el resolutor del backend.
- `platform` o `device` se normalizan a `mobile`, `tablet` o `web`; las peticiones tablet usan la plataforma de contenido `ipad`.
- `theme` resuelve a `dark` solo cuando se solicita `dark`; cualquier otro valor resuelve a `light`.
- El resolutor comprueba primero `variantPublicSrc`, después `themePublicSrc` y por último `publicSrc`.
- El `src` devuelto usa `/api/public/docs/assets/...` para el detalle público y `/api/app/docs/assets/...` para el detalle autenticado de la app.
- El handler de assets vuelve a limpiar la ruta y sirve ficheros solo desde la raíz de assets de docs configurada; un `404` posterior del asset es un hueco de disponibilidad del asset, no un fallo de resolución de media.
- No uses `auth-native-login` como ejemplo de fuente resuelta para el bundle actual porque sus entradas de media están planificadas con campos de fuente vacíos.
- El bundle de contenido actual se generó el 2026-06-18. Refresca el bundle antes de publicar si la actualización de documentación del 2026-06-24 cambió fuentes de media.
Resultado esperado
El operador puede confirmar qué asset de media seleccionó un artículo de Docs, qué fallback lo produjo y si alguna media ausente debe gestionarse como captura pendiente o hueco de disponibilidad de asset, no como un fallo de carga del artículo.