Manual de Usuario

Yavii es una red de seguridad comunitaria diseñada para comunidades que necesitan protegerse y mantenerse conectadas. Funciona con o sin internet, usa cifrado de grado militar, y está construida con el respaldo de las autoridades comunitarias.

Con Yavii puedes:

• 🗺️ Explorar sitios en un mapa satelital con marcadores comunitarios
• 🔍 Reportar hallazgos de flora, fauna, platillos y cultura local
• 🚨 Alertar a tu comunidad sobre emergencias, personas armadas, vehículos sospechosos o disparos
• 🛡️ Protegerte con el sistema anti-secuestro por palabra clave y reconocimiento de voz
• 🔗 Compartir datos con otros dispositivos sin necesidad de internet (P2P)
• ✉️ Enviar mensajes cifrados con el sistema de Cartero Digital
• 📊 Monitorear amenazas desde el dashboard de monitoreo

¿Cómo obtener una cuenta?

1. Acude con el agente municipal o administrador de tu comunidad
2. El administrador crea tu cuenta desde el panel de administración
3. Te entrega en persona tu nombre de usuario y contraseña
4. Inicias sesión en Yavii con esas credenciales

Una vez que tienes tu cuenta, puedes usarla en cualquier dispositivo. Tus datos están protegidos y solo tú puedes acceder a ellos.

Cómo iniciar sesión

1. Abre Yavii en tu navegador o como app instalada (PWA)
2. Ingresa tu nombre de usuario y contraseña
3. Haz clic en Entrar

¿Cuándo SÍ necesitas GPS?

• 📍 Registrar visitas a sitios en el mapa
• 🔍 Modo Detective — geolocalizar hallazgos
• 🚨 Emitir alertas de emergencia, observatorio o anti-secuestro
• 🚶 Patrullaje ambiental — tracking de ruta

Si intentas usar una de estas funciones sin GPS, la app te lo indicará y ofrecerá alternativas (ubicación aproximada por WiFi, última posición conocida o selección manual en el mapa).

¿Olvidaste tu contraseña?

Usa el enlace "¿Olvidaste tu contraseña?" para recibir un correo de recuperación. Si no tienes internet, puedes usar tu frase de respaldo de 12 palabras con la opción "📡 Sin conexión".

El mapa es la pantalla principal de Yavii. Muestra:

• 📍 Marcadores verdes: sitios de interés comunitario
• 🔵 Tu ubicación: representada con un círculo azul
• 👥 Otros exploradores: si han compartido su ubicación

Visitar un sitio

1. Toca un marcador verde en el mapa
2. Se abre una ventana con información del sitio
3. Si estás cerca del sitio (geofence), puedes registrarlo como descubierto
4. Ganas puntos por cada sitio descubierto

El Modo Detective te permite documentar la riqueza natural y cultural de tu comunidad:

Cómo reportar un hallazgo

1. Ve a la sección Detective en el menú
2. Selecciona la categoría
3. Toma una foto (opcional, hasta 3)
4. Escribe un nombre y una frase descriptiva
5. Guarda el hallazgo

Cada hallazgo se guarda localmente y se marca como 🟡 Pendiente hasta que lo subas manualmente con el botón ⬆ Subir. Los hallazgos incluyen marca de agua digital con tu identidad, timestamp y licencia Creative Commons.

El patrullaje te permite registrar recorridos GPS con seguimiento en tiempo real:

• 🚶 Iniciar patrullaje: comienza a grabar tu ruta GPS
• 📍 Polilínea en el mapa: tu recorrido se dibuja como una línea sobre el mapa
• ⚠️ Registrar amenazas: durante el patrullaje puedes marcar puntos de amenaza
• 🌿 Puntos de Interés (POI): registra hongos, ríos, flora, fauna, paisajes, árboles, manantiales
• ⏹️ Finalizar: guarda el patrullaje completo con estadísticas

El Observatorio es un sistema de alerta temprana para reportar situaciones de riesgo. También incluye el Radar Táctico de Misiones para operativos de búsqueda en equipo (ver 🎯 Misiones de Búsqueda).

Cómo reportar

1. Selecciona el tipo de amenaza
2. La app obtiene automáticamente tu ubicación GPS
3. Opcionalmente graba un mensaje de audio
4. Envía el reporte — se propaga a todos los usuarios cercanos

Los reportes llegan al Dashboard de Monitoreo donde los agentes pueden atenderlos.

🎤 Detección por Voz

La app escucha permanentemente (usando el micrófono). Solo tienes que:

1. Desbloquear tu celular (huella o rostro)
2. Abrir Yavii
3. Decir tu palabra clave secreta

La app reconoce tu voz, obtiene tu ubicación GPS y la envía a los agentes y a la comunidad sin mostrar ninguna alerta en pantalla.

⌨️ Detección por Texto

Si puedes escribir, la palabra clave también se detecta al escribirla en cualquier campo de texto de la app.

🎓 Modo Práctica / Simulacro

Para que puedas practicar sin miedo a falsas alarmas:

1. Ve a Perfil → Anti-Secuestro → Configurar
2. Haz clic en el botón 🎓 Practicar palabra clave
3. La app entra en modo simulacro (badge azul en pantalla)
4. Di o escribe tu palabra clave
5. La app te confirma: "✅ Se habría enviado una alerta. Esto fue una práctica, nadie fue notificado."

El botón de pánico vecinal envía una alerta inmediata a todos los dispositivos cercanos. A diferencia del sistema anti-secuestro, esta alerta sí es visible y sonora — está diseñada para emergencias donde necesitas ayuda inmediata de tus vecinos.

Para usarlo: presiona el botón S.O.S. Vecinal en la sección de emergencias. Tu ubicación y un mensaje de auxilio se propagan instantáneamente.

Las alertas de emergencia se propagan a todos los dispositivos cercanos (hasta 1 km a la redonda). Tipos de alerta:

• 🫃 Personas armadas
• 🚗 Vehículos sospechosos
• 🔫 Disparos
• 🛡️ Secuestro (activado por palabra clave o voz)

Cuando recibes una alerta, puedes ver la ubicación en el mapa, el tipo de amenaza y hace cuánto tiempo se reportó. Las alertas tienen corroboración comunitaria: si varios dispositivos reportan lo mismo, la alerta se marca como verificada.

Encuentra personas con oficios tradicionales en tu comunidad:

• 🔍 Busca por voz o texto
• 👤 Cada entrada muestra nombre, oficio, descripción y ubicación
• 📝 Si tienes un oficio, puedes registrarte en el directorio

El directorio funciona offline con datos guardados localmente.

Tablero Comunitario

Publica objetos perdidos o encontrados. Los avisos viajan entre dispositivos vía P2P para que lleguen a toda la comunidad.

Tablón de Avisos

Publica anuncios sobre trabajo, trámites, eventos comunitarios. Los anuncios caducan automáticamente a los 7 días.

Compra, vende e intercambia productos dentro de tu comunidad:

• 🛒 Productos en venta: publica lo que quieras vender con foto, precio y descripción
• 🔄 Trueque: ofrece intercambiar productos sin dinero
• ⚡ Ventas Rápidas: publicaciones que caducan rápido para ventas urgentes

El mercado funciona offline. Tus publicaciones se sincronizan cuando hay conexión.

Yavii puede intercambiar datos directamente entre dispositivos sin necesidad de internet:

• 📡 WiFi Direct: los dispositivos se descubren en la misma red WiFi
• 📷 Código QR: escanea el código de otro dispositivo para conectar
• 🔵 Bluetooth BLE: requiere hardware adicional (ESP32/Raspberry Pi)

Cómo sincronizar vía P2P

1. Un dispositivo actúa como Host (comparte sus datos)
2. El otro dispositivo escanea el código QR del Host
3. Los datos se transfieren directamente — hallazgos, alertas, avisos, etc.

La sincronización P2P usa WebRTC con cifrado de extremo a extremo.

El Cartero es un sistema de mensajería cifrada de extremo a extremo que funciona como un "teléfono comunitario":

• 🔐 Cifrado ECDSA: cada mensaje se cifra con la llave pública del destinatario
• 📱 Recados de voz: envía mensajes de audio cifrados
• 🔄 Propagación P2P: los mensajes viajan entre dispositivos hasta llegar al destinatario
• 📞 Llamadas de voz: comunicación por voz vía WebRTC

El sistema de Comunidad permite cifrar datos sensibles con la llave pública de tu cultura y define qué puede ver y hacer cada persona según su rol.

🔑 Matriz de Roles

Cifrado

• 🔑 RSA-4096: cada comunidad tiene un par de llaves pública/privada
• 🔒 Datos cifrados: nombres y frases del modo detective se cifran con la llave de tu comunidad antes de guardarse
• 🔓 Desbloqueo: necesitas ingresar la contraseña de la comunidad para descifrar los datos

Cómo unirse a una comunidad

1. Ve a la sección Comunidad en el menú
2. Selecciona una comunidad disponible y solicita unirte
3. Un colaborador o admin de esa comunidad debe aceptar tu solicitud
4. Una vez aceptado, recibes las llaves para cifrar/descifrar datos

Para crear una comunidad nueva, contacta al administrador general de Yavii.

El panel de vigilancia (/vigilancia/) es para agentes y operadores:

• 📹 Cámaras: streaming en tiempo real vía WebRTC
• 📊 Métricas KPI: alertas activas, atendidas hoy, tiempo de respuesta
• 💬 Chat: comunicación en tiempo real entre operadores y agentes
• 📜 Timeline: actividad cronológica de todas las cámaras y alertas
• 🔔 Notificaciones sonoras: alertas con tonos distintos por tipo de amenaza

El dashboard tiene autenticación propia separada de la app principal.

El panel de monitoreo (/monitoreo/) visualiza todas las amenazas reportadas:

• 🗺️ Mapa de calor: 5 capas — amenazas, visitas, hallazgos, patrullajes, moneda
• 📈 Gráficas Chart.js: tendencias temporales con comparativas
• 📋 Tabla filtrable: búsqueda por tipo, fecha, usuario
• 📥 Exportación: descarga los datos en JSON o CSV
• 🏆 Top usuarios: los más activos de la semana

Reporta cortes de luz a la CFE directamente desde la app:

• ⚡ Reporte rápido: envía tu ubicación y datos del servicio
• 📱 Compartir por WhatsApp: envía el reporte a tus contactos
• 💾 Guardado local: tus reportes se guardan sin conexión

Tu perfil

En la sección Perfil puedes:

• 📷 Cambiar tu foto de perfil
• 🔑 Cambiar tu contraseña
• 🌐 Elegir modo de residencia (local o embajador)
• 🔐 Configurar PIN de seguridad para secciones sensibles
• 🛡️ Configurar el sistema anti-secuestro
• 💾 Ver el uso de almacenamiento local

Identidad Digital

Yavii te permite crear una identidad digital ECDSA que funciona como tu firma digital personal. Con ella puedes:

• 📝 Firmar digitalmente tus hallazgos y reportes
• 🔐 Cifrar mensajes en el sistema de Cartero
• 🗝️ Exportar tu frase de respaldo de 12 palabras — ¡guárdala bien!

Yavii está diseñada para funcionar completamente sin internet:

• 📦 Datos guardados localmente: todos tus hallazgos, visitas y reportes se almacenan en tu dispositivo (IndexedDB)
• 🔄 Sincronización automática: cuando recuperas internet, todo se sube al servidor
• ⬆ Subida manual: tú decides cuándo subir cada elemento con el botón ⬆
• 🔗 P2P: intercambia datos con otros dispositivos cercanos sin internet
• 📡 Indicador de estado: un badge en la parte superior te muestra si estás offline

Yavii guarda tus datos en el almacenamiento local del navegador (IndexedDB). Esto tiene límites que varían según el dispositivo y navegador, típicamente entre 50 MB y 2 GB del espacio total del disco.

¿Qué ocupa espacio?

• 📸 Fotos del Modo Detective: cada foto puede ocupar 1-5 MB. Si acumulas muchas sin subir, es lo que más espacio consume.
• 🎤 Audios del Observatorio: grabaciones de voz, ~500 KB por minuto.
• 🗺️ Caché del mapa: tiles de Leaflet guardados para uso offline.
• 📋 Datos de la app: hallazgos, visitas, avisos, productos del mercado, etc. (muy poco espacio).

¿Qué pasa si se llena?

• 🟡 Al 80%: la app te muestra una advertencia en la sección de Perfil → Almacenamiento.
• 🔴 Al 95%: se activa la limpieza automática: borra fotos y audios de hallazgos que ya subiste al servidor (sincronizados).
• 🛑 Al 100%: no podrás guardar nuevas fotos hasta que liberes espacio. La app te sugerirá subir pendientes o borrar datos viejos.

Cómo liberar espacio

1. Ve a Modo Detective y usa el botón ⬆ Subir todos para enviar los hallazgos pendientes al servidor
2. Una vez subidos, los archivos locales se marcan como sincronizados y el sistema de limpieza los borrará automáticamente tras 7 días
3. En Perfil → Almacenamiento puedes ver cuánto espacio estás usando y forzar una limpieza manual

Yavii es una PWA (Progressive Web App). Esto significa que se instala en tu teléfono como una app normal, pero se actualiza desde internet. El Service Worker guarda una copia en caché para que funcione offline.

¿Tengo la última versión?

• 🔢 El número de versión aparece en la consola del navegador al cargar: [App] v32 loaded
• 📱 Si instalaste la app en tu pantalla de inicio, abre el navegador (Chrome/Edge) y ve a yavii → menú ⋮ → Información para ver la versión
• 🔄 La app intenta actualizarse sola cada vez que abres y hay internet. El service worker descarga la nueva versión en segundo plano y la aplica al cerrar y reabrir

Si la app se ve rara o no funcionan cosas nuevas

1. Cierra la app completamente (desliza hacia arriba en Android o doble clic home + deslizar en iPhone)
2. Abre de nuevo — el service worker debería cargar la última versión
3. Si sigue igual: ve a Ajustes del teléfono → Apps → Yavii → Almacenamiento → Borrar caché
4. Como último recurso: abre Yavii en el navegador (Chrome), ve a Configuración del sitio → Borrar datos, y vuelve a entrar

Actualizaciones sin internet

Si no tienes internet constante:

• La app funciona normalmente con la versión cacheada
• Cuando te conectas a cualquier WiFi, el service worker automáticamente busca actualizaciones
• También puedes recibir actualizaciones vía P2P de otro dispositivo que tenga una versión más reciente

Paso 1: Revocar tu llave desde otro dispositivo

1. Consigue otro teléfono o computadora con internet
2. Entra a Yavii con tu usuario y contraseña
3. Ve a Perfil → Identidad Digital
4. Selecciona "Revocar llave anterior" — esto invalida la llave del teléfono perdido
5. Genera una nueva identidad con tu frase de respaldo de 12 palabras

Paso 2: Avisar al administrador

1. Contacta al agente municipal o administrador de Yavii en tu comunidad
2. Pide que invaliden tus sesiones activas y roten las llaves de tu comunidad
3. El administrador puede forzar un cierre de sesión en todos los dispositivos desde el panel

Paso 3: Restaurar tu identidad

Tu frase de respaldo de 12 palabras es la llave para recuperar todo:

• 🔑 Con la frase puedes regenerar tu llave privada ECDSA en un dispositivo nuevo
• 📝 La frase NO se guarda en ningún servidor — solo tú la tienes (por eso debes guardarla en papel, en un lugar seguro)
• 🏘️ Si eras parte de una comunidad con llaves RSA, el administrador deberá re-emitir tus llaves comunitarias

¿Qué pasa con mis datos?

• ✅ Datos ya subidos al servidor: tus hallazgos, visitas, puntos y mensajes están a salvo. Al iniciar sesión en otro dispositivo, se sincronizan de nuevo.
• ❌ Datos solo locales (🟡 Pendiente): fotos y hallazgos que no subiste se pierden con el teléfono. Por eso insistimos en subir con frecuencia.
• 🔒 Mensajes del Cartero: los mensajes cifrados solo pueden leerse con tu llave privada. Al revocar la llave anterior, los mensajes viejos se vuelven ilegibles (incluso para el ladrón).

Yavii implementa múltiples capas de protección:

• 🖼️ Watermarking: las fotos del modo detective incluyen metadatos EXIF con tu identidad y licencia
• 📜 Licencia Biocultural: CC-BY-NC-SA 4.0 + Triqui Community Consent
• 🛡️ Rate Limiting: máximo 100 solicitudes por minuto por IP para tráfico normal. Las rutas de emergencia (anti-secuestro, pánico vecinal, observatorio) tienen su propio carril con 500 req/min para que nunca se bloqueen por tráfico normal. Alertas del mismo tipo en la misma zona (200m, 60s) se agrupan como corroboración comunitaria en vez de contar por separado.
• 🔏 Cifrado E2EE: el sistema de Comunidad usa RSA-4096 + AES-GCM
• ✍️ Identidad ECDSA: firma digital para todos tus reportes
• 📋 Logs de acceso: toda actividad queda registrada para auditoría

Tus datos personales nunca se comparten con terceros. La información comunitaria se protege con el consentimiento de las autoridades tradicionales.

El Radar de Misiones es una herramienta de búsqueda en equipo. Permite que un grupo de personas se vean entre sí en tiempo real sobre un radar circular, compartiendo su ubicación GPS sin necesidad de internet.

¿Cómo funciona?

1. Abre la sección Observatorio Comunitario — el radar táctico está arriba de los botones de reporte.
2. En la barra 🎯 MISIÓN, escribe un código secreto de misión o usa el botón 🎲 para generar uno aleatorio.
3. Presiona ▶ Entrar a la misión. Acepta el aviso de consentimiento.
4. Comparte el código con tu equipo. Todos los que ingresen con el mismo código aparecerán en el radar de los demás.

Arquitectura P2P — sin internet

El radar usa WebRTC P2P como ruta principal. Los teléfonos del equipo se conectan directamente entre sí por WiFi Direct. Si hay internet disponible, el servidor central funciona como respaldo.

• 🔗 Mesh multi-salto: si A está conectado con B, y B con C, A puede ver a C aunque estén fuera de rango directo. Los mensajes rebotan automáticamente hasta 2 saltos.
• 📡 Pi Comunitario: si el equipo carga un Raspberry Pi con hotspot, todos los teléfonos se conectan a su WiFi y el Pi maneja el descubrimiento de peers sin tocar internet.

GPS Suavizado

En bosque cerrado o cañón, el GPS civil tiene error de 5-30 metros. El radar aplica promedio móvil de 4 lecturas para que los blips no salten.

Batería Adaptativa

El GPS ajusta su frecuencia automáticamente:

• 🔋 2 segundos — cuando hay compañeros cerca o te estás moviendo (búsqueda activa).
• 🔋 10 segundos — cuando estás solo y quieto (ahorro de batería).

Pantalla Bloqueada y Wake Lock

Si bloqueas la pantalla durante la búsqueda, el GPS y las conexiones P2P se pausan (el sistema operativo congela las apps en segundo plano). Yavii maneja esto de dos formas:

• 🔆 Wake Lock: al iniciar una misión, la app solicita mantener la pantalla encendida automáticamente (si tu navegador lo soporta — Chrome, Edge, Opera). La pantalla se atenúa pero no se bloquea.
• 🔄 Reconexión automática: si bloqueaste manualmente o el Wake Lock no está disponible (Safari, Firefox), al desbloquear la pantalla la app reanuda el GPS, reconecta el P2P y retoma la misión donde la dejaste. Tus compañeros verán tu última posición como fantasma mientras tanto.

Recomendación para búsquedas largas: usa Wake Lock + batería externa. Si no tienes batería externa, bloquea la pantalla entre revisiones y confía en la reconexión automática al desbloquear.

Última Posición Fantasma

Si un compañero pierde señal, su blip no desaparece de golpe. Se vuelve un fantasma que se desvanece durante 60 segundos, anclado al borde del radar en la última dirección conocida.

Alerta de Proximidad

Dos modos para no alejarte del equipo:

• 📍 GPS: configuras un rango máximo (ej. 50m). Si te alejas más que eso del compañero más cercano, el teléfono vibra. Doble pulso al acercarte al límite, triple largo si te pasaste.
• 📶 Bluetooth: alternativa cuando el GPS falla. El líder emite un beacon BLE. Los demás miden la intensidad de señal (RSSI). Si se debilita, vibra.

✅ Botón ENCONTRADO

Cuando alguien encuentra el objetivo de la búsqueda, presiona ◆ ENCONTRADO. Al instante, todos los radares del equipo muestran una superposición OBJETIVO LOCALIZADO con quién reportó. La misión se cierra automáticamente a los 10 segundos.

📍 Marcadores Compartidos

Tres tipos de marcadores que se comparten con todo el equipo vía P2P:

• 👣 Huella — señal de presencia (círculo amarillo punteado en el radar).
• 🔄 Buscado — zona ya revisada (círculo azul punteado).
• ⚠️ Peligro — barranca, animal, riesgo (círculo rojo punteado).

Se colocan en tu posición GPS actual con un solo toque.

📻 Mensajes Rápidos

Cuatro botones predeterminados. Sin escribir, sin ver la pantalla. El mensaje aparece 3 segundos en el radar de todos los compañeros con una vibración corta:

• DESPEJADO — zona revisada, sin novedad.
• REGRESO — volviendo al punto base.
• APOYO — necesito refuerzo.
• PAUSA — alto temporal.

Modo Nocturno

El botón 🌙 cambia todo el radar a rojo sobre negro. La barra de barrido se detiene para no delatar tu posición en la oscuridad. Ideal para operativos nocturnos.

Privacidad

• 🔒 Solo quien tenga el código exacto de misión verá las ubicaciones del equipo.
• 🗑️ Al salir de la misión, tu posición se borra inmediatamente del servidor y del mesh P2P.
• ⏱️ Si no sales manualmente, tu posición expira a los 60 segundos de inactividad.
• ⚠️ Antes de entrar, la app pide consentimiento explícito informando que compartirás tu ubicación en tiempo real.

El Raspberry Pi Comunitario es un dispositivo portátil que actúa como centro de señalización local. Permite que los teléfonos del equipo se descubran entre sí y formen la red P2P sin necesidad de internet ni torres de celular.

¿Cómo funciona?

1. El Pi se configura como hotspot WiFi portátil.
2. Ejecuta un servidor WebSocket de señalización (incluido en pi-signaling/server.js).
3. Todos los teléfonos del equipo se conectan a la red WiFi del Pi.
4. Los teléfonos detectan automáticamente al Pi y lo usan para intercambiar señales WebRTC.
5. Una vez conectados, los datos van directo entre teléfonos (WebRTC P2P), sin pasar por el Pi.

Ventajas

• 🌐 Cero dependencia de internet — ideal para el monte.
• 📱 Multiplataforma — funciona con Android y iPhone.
• 🔋 Batería externa — una powerbank de $300 pesos alimenta el Pi por horas.
• 🔊 Altavoz USB opcional — para disparar alarmas audibles en el punto base.

Sin Pi también funciona

Si no hay Pi disponible, el sistema usa automáticamente la señalización normal vía internet (si hay) o QR/BLE (sin infraestructura). El Pi es opcional, no obligatorio.