chore: add Kotlin directory structure, update registry.db and gitignore

Añade estructura inicial kotlin/functions/, actualiza registry.db con todos los cambios indexados, y ajusta .gitignore. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-06 23:47:27 +02:00
parent dede5e00af
commit 73d181f2b0
13 changed files with 1005 additions and 1 deletions
@@ -0,0 +1,99 @@
+---
+name: overpass_nearby_pois
+kind: function
+lang: kt
+domain: infra
+version: "1.0.0"
+purity: impure
+signature: "fun overpassNearbyPois(lat: Double, lon: Double, radiusM: Int = 500, categories: List<String>? = null): List<POI>"
+description: "Consulta la Overpass API (OpenStreetMap) para obtener POIs cercanos a una coordenada. Soporta 16 categorias mapeadas a tags OSM (amenity, tourism, historic, leisure, shop). Sin dependencias externas: solo Android SDK (HttpURLConnection + org.json)."
+tags: [overpass, openstreetmap, osm, poi, geospatial, location, android, infra]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports:
+  - "org.json.JSONObject"
+  - "org.json.JSONArray"
+  - "java.net.HttpURLConnection"
+  - "java.net.URL"
+  - "java.net.URLEncoder"
+tested: false
+tests: []
+test_file_path: ""
+file_path: "kotlin/functions/infra/overpass_nearby_pois.kt"
+params:
+  - name: lat
+    desc: "Latitud del punto central en WGS84 (ej: 40.4168 para Madrid)"
+  - name: lon
+    desc: "Longitud del punto central en WGS84 (ej: -3.7038 para Madrid)"
+  - name: radiusM
+    desc: "Radio de busqueda en metros. Default 500. Valores grandes aumentan el tiempo de respuesta."
+  - name: categories
+    desc: "Lista de categorias a filtrar: restaurant, cafe, bar, museum, monument, park, library, theatre, cinema, gallery, historic, tourism, shop, hotel, pharmacy, hospital. Null devuelve todas."
+output: "Lista de POI con id OSM, coordenadas (lat/lon), nombre, categoria y mapa completo de tags OSM. Lanza RuntimeException si la API devuelve error HTTP o la respuesta no es JSON valido."
+---
+
+## Ejemplo
+
+```kotlin
+// Restaurantes y museos en un radio de 300 metros
+val pois = overpassNearbyPois(
+    lat = 40.4168,
+    lon = -3.7038,
+    radiusM = 300,
+    categories = listOf("restaurant", "museum")
+)
+pois.forEach { poi ->
+    println("${poi.name} (${poi.category}) — lat=${poi.lat}, lon=${poi.lon}")
+}
+
+// Todos los POIs en 500 metros (null = todas las categorias)
+val all = overpassNearbyPois(lat = 48.8566, lon = 2.3522)
+println("Paris: ${all.size} POIs encontrados")
+```
+
+## Categorias soportadas
+
+| Categoria    | Tag OSM              |
+|--------------|----------------------|
+| restaurant   | amenity=restaurant   |
+| cafe         | amenity=cafe         |
+| bar          | amenity=bar          |
+| museum       | tourism=museum       |
+| monument     | historic=monument    |
+| park         | leisure=park         |
+| library      | amenity=library      |
+| theatre      | amenity=theatre      |
+| cinema       | amenity=cinema       |
+| gallery      | tourism=gallery      |
+| historic     | historic (wildcard)  |
+| tourism      | tourism (wildcard)   |
+| shop         | shop (wildcard)      |
+| hotel        | tourism=hotel        |
+| pharmacy     | amenity=pharmacy     |
+| hospital     | amenity=hospital     |
+
+## Query Overpass QL generada
+
+```
+[timeout:10][out:json];
+(
+  node["amenity"="restaurant"](around:500,40.4168,-3.7038);
+  node["tourism"="museum"](around:500,40.4168,-3.7038);
+);
+out body;
+```
+
+## Notas
+
+- Usa `java.net.HttpURLConnection` con POST y `data=<query_url_encoded>`.
+- Timeouts: 10 segundos de conexion y lectura. La query QL tambien declara `[timeout:10]`.
+- El tipo `POI` se define en el mismo archivo como `data class`.
+- El mapa `tags` contiene todos los tags OSM del nodo, no solo el de la categoria.
+- Si un nodo no tiene tag `name`, el fallback es la categoria y luego "Unknown".
+- Las categorias wildcard (historic, tourism, shop) usan `node["key"](around:...)` sin valor.
+- Lanza `RuntimeException` en caso de categorias invalidas, error HTTP, o JSON malformado.
+- Compatible con Android SDK >= 19 (API level 19 tiene org.json integrado).
+---