# AudioguidesApp — Almacenamiento público de audioguías **Dominio previsto:** https://data.audioguidesapp.com **Versión de lectura:** v1 **Estado:** estructura inicial; el contrato de datos completo está pendiente de validar con el desarrollador. **Uso:** catálogo público y ficheros estáticos para audioguidesapp.com, Android e iOS. ## 1. Estructura del servidor La carpeta donde está este README.md es la **raíz pública del subdominio**, no la de WordPress. ```text [document-root del subdominio]/ ├── index.html # Manual web en la home del subdominio ├── README.md # Esta documentación en texto ├── logo.webp # Identidad visual del manual └── v1/ ├── guias.json # Índice público de guías; empieza [] mientras no estén importadas ├── guias/ │ ├── 35/ # EJEMPLO PLANIFICADO: Retortillo de Soria │ │ ├── guia.json # Detalle con puntos; aún no existe │ │ ├── cover.jpg # Imagen; aún no existe │ │ └── puntos/ │ │ └── 001/ │ │ ├── foto-01.webp │ │ └── audio-es.mp3 │ └── 10/ # EJEMPLO PLANIFICADO: Centro de Madrid └── autores/ ``` **IMPORTANTE:** las carpetas `35` y `10` se muestran como ejemplo. No se crean ni se publican guías sin datos completos. ## 2. URLs públicas - Índice de audioguías: `GET https://data.audioguidesapp.com/v1/guias.json` - Detalle por ID: `GET https://data.audioguidesapp.com/v1/guias/{id}/guia.json` - Portada: `https://data.audioguidesapp.com/v1/guias/{id}/cover.jpg` (o la ruta indicada en el JSON) - Imagen de punto: `https://data.audioguidesapp.com/v1/guias/{id}/puntos/{puntoId}/foto-01.webp` - Audio de punto: `https://data.audioguidesapp.com/v1/guias/{id}/puntos/{puntoId}/audio-es.mp3` Las URLs de detalle y multimedia son una **convención propuesta** y devolverán 404 hasta que exista el contenido correspondiente. ## 3. IDs y relación entre ficheros - `id` es **único y estable** para cada audioguía, aunque varias pertenezcan a la misma ciudad. - Se recomienda conservar los IDs históricos (`35` para Retortillo de Soria, `10` para Centro de Madrid) al migrar los registros correspondientes. En el ejemplo nuevo recibido estaban renumerados como `1` y `2`; **hay que reconciliar esta diferencia antes de publicar**. - Los IDs se tratarán como cadenas en la API, por ejemplo `"35"`; la carpeta se llama `35`. - Los IDs de puntos también son estables; `orden` determina el orden de visita, por lo que cambiar el orden no debe obligar a renombrar carpetas. - Rutas relativas en los JSON: siempre se interpretan desde `https://data.audioguidesapp.com/v1/`. Ejemplo: `guias/35/cover.jpg`. La extensión puede ser `.jpg`, `.webp` o el formato real elegido; el campo JSON manda. ## 4. Catálogo (`v1/guias.json`) Es un **array JSON** de fichas resumidas para la búsqueda, listado y mapa. Se basa en el fichero `guias.json` facilitado en octubre de 2026. Campos vistos en el archivo original de ejemplo: - `id`: ID único de la audioguía. - `estado`: p. ej., `publicada`. - `autorId`: identificador del autor. - `ubicacion`: `{ ciudad, pais, lat, lng, geohash }`. - `idiomas`: lista de códigos como `es`. - `textos`: traducciones, por ejemplo `textos.es.nombre` y `textos.es.descripcionCorta`. - `imagen`: ruta de portada. - `modos`: medios de desplazamiento (`pie`, `bici`, `coche`). - `puntos`: número de paradas. - `distanciaKm`, `duracionMin`: valores opcionales que pueden ser `null`. - `acceso`: `{ tipo, productId, precio, moneda, descuentoPct }`. - `rating`: `{ media, n }`. - `version`, `creada`, `actualizada`. No se deben listar como publicadas audioguías cuyo `guia.json` o archivos esenciales no estén disponibles. Por ese motivo, el archivo de instalación contiene `[]`. ## 5. Detalle de una guía (`v1/guias/{id}/guia.json`) **Propuesta pendiente de aprobación por la persona que desarrolla las apps.** El archivo histórico de Firebase recuperado incluye fichas de guías, pero no los textos y audios de todos los puntos. Antes de fijar el esquema definitivo es necesario conseguir al menos una guía completa. Ejemplo únicamente **estructural** (sin datos reales): ```json { "id": "35", "version": 1, "puntos": [ { "id": "001", "orden": 1, "ubicacion": { "lat": null, "lng": null }, "textos": { "es": { "titulo": "", "contenido": "" } }, "imagenes": ["guias/35/puntos/001/foto-01.webp"], "audios": { "es": null } } ] } ``` En producción la ficha tendrá los metadatos generales de la audioguía (título, autor, coordenadas, portada, idioma, descripción, etc.) además de la colección completa de puntos. `puntos` en la ficha detallada será un array, mientras que en el catálogo general es un contador numérico. ### Reproducción / TTS - Si hay audio válido para el idioma elegido, reproducir ese fichero. - En ausencia de audio, usar la narración por texto a voz (TTS) a partir de `textos[idioma].contenido`. - Si falta el idioma solicitado, aplicar una política de idioma alternativo **que aún debemos acordar**. - La web puede ofrecer reproducción compatible con navegador; Android/iOS podrán añadir descargas sin conexión y geolocalización. ## 6. WordPress, Android e iOS Todos consultan el mismo catálogo. El objetivo es que la publicación de una audioguía actualice automáticamente la sección `https://audioguidesapp.com/audioguias-gratis/` y permita escucharla en la web, Android e iOS. **Fase actual:** JSON estático de lectura. **Fase futura:** gestor de audioguías en WordPress (o backend equivalente), base de datos y API autenticada de creación/edición con exportación del catálogo público. Los clientes nunca deben escribir directamente en los JSON ni en las carpetas públicas. ## 7. Seguridad y publicación - Aquí solo se publican datos de audioguías y multimedia de difusión pública. - **Nunca** subir exportaciones crudas de Firebase con comentarios/usuarios, credenciales, claves, tokens, backups ni borradores privados a esta raíz pública. - Conservar una copia de seguridad externa del contenido y controlar el espacio, tráfico y recursos del VPS. - Al publicar, validar JSON UTF-8, IDs, coordenadas, estados, rutas, referencias a imágenes/audios, tipos MIME y permisos. - Configurar HTTPS y, si la web hace peticiones `fetch` desde navegador, cabeceras CORS apropiadas para `https://audioguidesapp.com`. - No habilitar escritura anónima, subida pública sin moderación ni listado automático de directorios. - Planificar caché diferenciada: índice/JSON con actualizaciones rápidas; multimedia con URLs estables y estrategia de invalidación. ## 8. Lo que aún NO está fijado - Contrato definitivo de `guia.json` (esquema real de puntos y multidioma). - Si existen todos los archivos de fotos, audios y coordenadas de las guías recuperadas. - Autenticación, cuentas y permisos para que los usuarios creen y publiquen guías. - Descargas offline, monetización de guías, valoraciones y webhooks de sincronización. - Esquema de errores, paginación y API de escritura. Mantener la compatibilidad de `v1` al introducir cambios: usar `v2` para cambios incompatibles de contrato.