Mapas y geolocalización

---
name: mapas-y-geolocalizacion
description: convertir direcciones imperfectas en ubicaciones, rutas y zonas operables.
---

# Mapas y geolocalización

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando
captures direcciones, muestres mapas, calcules rutas o delimites zonas de servicio.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- Una entrega, visita, propiedad o servicio depende de una ubicación física.
- Necesitas autocompletar o geocodificar direcciones de LATAM.
- El precio o la disponibilidad cambia dentro de una zona dibujada.
- Debes calcular distancia o tiempo real por calles, no en línea recta.

Si el mapa solo decora una ficha, usa una imagen estática o un enlace. No cargues un SDK,
consentimiento de ubicación y facturación por una chincheta sin interacción.

## Cómo armarla

Usa **Google Maps Platform** o **Mapbox** para mapa, lugares y rutas. Usa **PostGIS** para
guardar puntos y polígonos propios; el proveedor resuelve datos, tu base resuelve negocio.

1. Guarda la dirección tal como la escribió la persona y también componentes
   normalizados, coordenadas, id del proveedor, precisión y fecha de geocodificación.
2. Diseña el formulario para LATAM: calle, número exterior e interior, colonia o barrio,
   municipio, estado, código postal, país y referencias. No vuelvas obligatorio un campo
   que el país no usa de forma consistente.
3. Ofrece autocomplete, pero permite mover un pin y confirmar referencias. Una dirección
   aceptada por el proveedor puede caer en el centro del código postal.
4. Geocodifica desde el servidor, restringe las llaves por dominio o app y separa llaves
   públicas de servicios privados. Define cuotas y alertas de gasto.
5. Guarda zonas de entrega como polígonos válidos en PostGIS y consulta con la función
   espacial adecuada. Decide y prueba qué pasa exactamente en el borde.
6. Para distancia y ETA usa una API de rutas. Calcula en línea recta solo como filtro
   barato previo, nunca como promesa de kilómetros o minutos por carretera.
7. Cachea resultados respetando los términos del proveedor y conserva una estrategia de
   regeocodificación. No mezcles ids o datos derivados entre proveedores sin revisar licencias.
8. Pide ubicación del dispositivo solo tras una acción explícita y ofrece captura manual
   equivalente cuando se niegue el permiso.

## En qué te vas a trabar

- **Las direcciones de LATAM son datos humanos, no una clave exacta.** Barrios repetidos,
  calles sin número y referencias son normales; conserva confianza y permite corregir.
- **Mapa, autocomplete, geocoding y rutas se cobran distinto.** Revisa la tabla vigente
  del proveedor, limita llamadas por sesión y registra costo por pedido o búsqueda.
- **Los polígonos se rompen con geometrías inválidas.** Valida cruces, huecos, sentido y
  sistema de coordenadas al guardar, no cuando el checkout falla.
- **Una ubicación precisa es dato personal.** Reduce retención y acceso, especialmente
  para domicilios, menores, salud o ubicación en tiempo real.

## Qué NO hacer

- No uses código postal como coordenada exacta ni municipio como zona de entrega.
- No confíes solo en GPS: interiores, permisos y equipos baratos producen errores grandes.
- No expongas una llave con permisos de servidor dentro del bundle web.
- No prometas ETA con distancia euclidiana ni reutilices datos contra los términos del mapa.

## Checklist

- [ ] El formulario funciona con direcciones reales de al menos dos países objetivo.
- [ ] La persona puede corregir el pin y agregar referencias sin pelear con autocomplete.
- [ ] Llaves, cuotas, restricciones y alertas de gasto están configuradas.
- [ ] Zonas y bordes tienen pruebas espaciales en PostGIS.
- [ ] Distancia y ETA usan rutas cuando afectan precio o promesa de entrega.
- [ ] Denegar geolocalización no bloquea la captura manual.
- [ ] Retención y permisos para coordenadas precisas están documentados.