Resolver configuración Docs
Valida que Antylogic haya cargado al arrancar el backend el bundle de documentación, la raíz de assets y las políticas Cache-Control que comparten la documentación pública y la pantalla autenticada Docs.
En este artículo
Usa esta guía después de un despliegue o cambio de bundle para comprobar que la ayuda servida en la landing y en la app sale de la misma configuración runtime.
No hay una pantalla para editar DOCS_*: la resolución ocurre durante el arranque del backend y queda fija hasta reiniciar el proceso. La comprobación se hace con los endpoints de Docs, la pantalla autenticada y, si procede, una revisión técnica de cabeceras.
Antes de empezar
- El backend debe arrancar y ejecutar config.Load() antes de registrar rutas.
- Debe existir un bundle con articles.json en DOCS_CONTENT_PATH o en la ruta por defecto ./docs-content.
- Los assets enlazados por los artículos deben estar bajo DOCS_ASSETS_PATH o bajo la ruta por defecto ../frontend/landingpage/public/product-screenshots/docs.
- Para validar /api/app/docs, usa una sesión autenticada de la demo ES, por ejemplo Grupo Marea Demo en Marea Gran Via.
Instrucciones
- 1.
Confirmar la configuración efectiva
Revisa DOCS_CONTENT_PATH, DOCS_ASSETS_PATH, DOCS_CACHE_CONTROL_DEFAULT y DOCS_CACHE_CONTROL_ASSETS antes de probar la ayuda. Si no se definen, el backend usa ./docs-content, ../frontend/landingpage/public/product-screenshots/docs, public, max-age=60 y public, max-age=31536000, immutable. Los valores vacíos o solo con espacios no sustituyen la configuración base.
- 2.
Validar el índice público
Abre GET /api/public/docs?locale=es&platform=mobile sin iniciar sesión. La respuesta debe mostrar version, article_count y sections; esto confirma que DOCS_CONTENT_PATH resuelve un articles.json legible para la documentación pública.
- 3.
Abrir la pantalla Docs autenticada
Con la sesión de Demo Marea activa, abre antylogic://docs. La pantalla DocumentationPage consume /api/app/docs, requiere autenticación por requireAuthMiddleware y debe presentar el mismo bundle que el índice público, sin un permiso granular adicional de Docs.
- 4.
Comprobar artículos y assets
Desde el índice, abre un artículo y verifica que sus medios se resuelven hacia /api/public/docs/assets/{path} o /api/app/docs/assets/{path}. El backend limpia el path, lo une a DOCS_ASSETS_PATH y solo sirve archivos que permanezcan dentro de esa raíz.
- 5.
Interpretar refrescos y caché
El servicio reutiliza articles.json mientras su ModTime no avance y vuelve a leerlo cuando detecta una modificación más reciente. Si el JSON no trae version, expone el ModTime UTC en formato RFC3339. Cambiar variables DOCS_* requiere reiniciar el backend; cambiar el archivo puede refrescar el contenido por ModTime.
Validaciones y límites
- Solo GET y HEAD son métodos válidos para handleDocs; otros métodos devuelven 405 metodo no permitido.
- Si DOCS_CONTENT_PATH apunta a un directorio, se busca articles.json dentro; si apunta a un archivo .json, se usa ese archivo directamente.
- Si falta articles.json, los GET devuelven 503 documentacion no configurada; si el JSON no decodifica, devuelven 500 documentacion no disponible.
- DOCS_CACHE_CONTROL_DEFAULT se aplica a índice y detalle; DOCS_CACHE_CONTROL_ASSETS se aplica a assets.
- Un asset inexistente o un directorio devuelve 404; una ruta vacía, . o con ../ se rechaza y no sirve archivos fuera de DOCS_ASSETS_PATH.
- HEAD en una ruta no asset responde 200 después de validar método y servicio, sin leer articles.json ni devolver cuerpo.
- Los Dockerfiles fijan DOCS_CONTENT_PATH y DOCS_ASSETS_PATH en rutas runtime de imagen; las políticas de caché quedan en defaults salvo override de despliegue.
- El bundle inspeccionado backend/docs-content/articles.json declara version 2026-06-18 y generated_at 2026-06-18T10:44:34.592Z; no lo uses como prueba de cambios posteriores sin regenerar el bundle.
Resultado esperado
La documentación pública y la autenticada quedan validadas contra un único servicio Docs compartido: mismo articles.json, misma raíz de assets y políticas Cache-Control separadas para contenido JSON y archivos multimedia.