🚗 Viaje Rentable AR — Asistente gratuito para conductores de apps de viaje

---

---

Viaje Rentable AR es una app Android gratuita y open source que ayuda a conductores de apps de viaje en Argentina a evaluar rápidamente si una solicitud conviene o no, usando OCR, cálculo local de rentabilidad y una recomendación visual superpuesta.

---

⚠️ Estado del proyecto

Este proyecto se encuentra en etapa alpha experimental.

La app ya cuenta con una base funcional, pero todavía requiere validación real prolongada, mejoras de documentación, ajustes de precisión OCR y pruebas en distintos dispositivos Android.

---

🎯 Objetivo

Ayudar al conductor a tomar una decisión más informada durante una solicitud de viaje.

La app analiza datos visibles en pantalla, como:

• tarifa ofrecida;
• distancia hasta el pasajero;
• distancia del viaje;
• minutos hasta el pasajero;
• minutos del viaje;
• posibles zonas o textos relevantes.

Con esos datos calcula métricas locales como:

• $ / km;
• $ / hora;
• costo estimado;
• ganancia neta estimada.

Luego muestra una recomendación visual:

Decisión	Significado
🟢 ACEPTAR	El viaje parece rentable según la configuración actual.
🟡 REVISAR	Hay datos grises o condiciones que conviene mirar manualmente.
🔴 RECHAZAR	El viaje parece poco conveniente según las reglas configuradas.
⚪ DATOS INCOMPLETOS	El OCR no pudo leer toda la información necesaria.

---

✅ Qué hace

• Lee información visible en pantalla con permiso explícito del usuario.
• Usa OCR local mediante ML Kit Text Recognition.
• Calcula rentabilidad estimada del viaje.
• Muestra una tarjeta flotante con la recomendación.
• Permite configurar costos y mínimos de rentabilidad.
• Procesa los datos localmente en el dispositivo.
• Ayuda a comparar viajes con criterios más consistentes.

---

🚫 Qué NO hace

• No acepta viajes automáticamente.
• No rechaza viajes automáticamente.
• No toca botones de Uber, DiDi, Cabify ni ninguna otra app.
• No usa APIs privadas de plataformas de viaje.
• No modifica tarifas.
• No oculta ubicación.
• No manipula otras aplicaciones.
• No guarda capturas de pantalla.
• No vende datos.
• No reemplaza la decisión final del conductor.

La app es solo un asistente visual e informativo.

---

🔗 Accesos rápidos

Recurso	Enlace
📲 Instalación	docs/INSTALLATION.md
🤝 Cómo contribuir	CONTRIBUTING.md
🔐 Privacidad	docs/PRIVACY.md
🧱 Arquitectura	docs/ARCHITECTURE.md
🗺️ Roadmap	docs/ROADMAP.md
⚖️ Licencia	LICENSE
🐞 Reportar un problema	Issues

---

🧠 Qué demuestra

Este proyecto también funciona como caso de portfolio técnico Android.

Demuestra:

• desarrollo Android nativo con Kotlin;
• UI moderna con Jetpack Compose y Material 3;
• captura autorizada de pantalla con MediaProjection;
• OCR con ML Kit;
• procesamiento eficiente de frames;
• parser defensivo para textos imperfectos de OCR;
• cálculo de rentabilidad aislado y testeable;
• overlay flotante con foreground service;
• configuración local con DataStore;
• arquitectura simple por responsabilidades;
• tests unitarios para reglas críticas;
• uso de IA y agentes de código como apoyo al desarrollo, validación y documentación.

---

✨ Features principales

• 📲 Monitoreo de pantalla autorizado

  • Usa MediaProjection con consentimiento explícito del usuario.

• 🔎 OCR local

  • Extrae texto visible de solicitudes de viaje.

• 🧮 Motor de rentabilidad

  • Calcula $ / km, $ / hora, costo estimado y ganancia neta.

• 🧠 Reglas de decisión

  • Recomienda aceptar, rechazar o revisar.

• 🪟 Overlay flotante

  • Muestra la recomendación sobre otras apps sin bloquear toda la pantalla.

• ⚙️ Configuración editable

  • Permite ajustar mínimos y costos según el criterio del conductor.

• 🧪 Diagnóstico

  • Incluye herramientas internas para probar OCR, overlay y última decisión.

• 🧱 Base testeable

  • Tests unitarios para parser, cálculo, frame gate, buffer y pipeline.

---

🛠️ Stack técnico

📱 Android & UI

🧠 OCR & Procesamiento

🧱 Arquitectura & Persistencia

---

🧩 Cómo funciona

Captura autorizada
        ↓
Preprocesamiento de imagen
        ↓
OCR con ML Kit
        ↓
Parser defensivo de solicitud
        ↓
Reglas de zonas / datos incompletos
        ↓
Cálculo de rentabilidad
        ↓
Overlay visual

El procesamiento se realiza localmente y busca minimizar consumo de CPU/memoria mediante:

• reducción de tamaño de captura;
• OcrFrameGate para evitar OCR en frames estables;
• buffer liviano de candidatos OCR;
• preprocesamiento controlado;
• reciclado de bitmaps procesados;
• logs de diagnóstico con traceId.

---

📐 Configuración actual

La app permite configurar criterios locales como:

Parámetro	Descripción
Mínimo $ / km	Rentabilidad mínima esperada por kilómetro.
Mínimo $ / hora	Rentabilidad mínima esperada por tiempo.
Ganancia neta mínima	Piso estimado luego de costos.
Costo por km	Costo operativo estimado por distancia.
Costo por minuto	Costo operativo estimado por tiempo.
Tolerancia de revisión	Margen para enviar casos grises a REVISAR.
Rechazo por tarifa no detectada	Define si una solicitud sin tarifa debe rechazarse.
Rechazo por distancia no detectada	Define si una solicitud sin distancia debe rechazarse.
Zonas a evitar	Textos o zonas que pueden activar revisión/rechazo.

---

🚀 Cómo compilar

# Clonar el repo
git clone https://github.com/Zibete/viaje-rentable-ar.git

# Entrar al proyecto
cd viaje-rentable-ar

# Build de debug
./gradlew :app:assembleDebug

# Tests unitarios
./gradlew :app:testDebugUnitTest

En Windows:

.\gradlew.bat :app:assembleDebug
.\gradlew.bat :app:testDebugUnitTest

---

📲 Instalación

Conductores / usuarios finales

La primera alpha pública se distribuye como APK experimental para instalación manual:

➡️ Descargar desde GitHub Releases

Pasos básicos:

1. Abrir el enlace de Releases.
2. Descargar el archivo APK desde la sección Assets.
3. Instalarlo manualmente en Android.

⚠️ Esta es una versión alpha experimental. Android puede mostrar advertencias porque la instalación se realiza fuera de Play Store.

La app no está publicada en Google Play. Ver la guía completa en docs/INSTALLATION.md.

Desarrolladores

También se puede compilar localmente desde Android Studio o Gradle.

./gradlew :app:assembleDebug

En Windows:

.\gradlew.bat :app:assembleDebug

El APK debug generado queda en:

app/build/outputs/apk/debug/app-debug.apk

Para esta primera alpha, si no existe una firma release configurada, ese APK debug se renombra para publicación manual como:

viaje-rentable-ar-v0.1.0-alpha.apk

---

🗂️ Estructura del proyecto

📦 app/
├─ 📂 src/
│  ├─ 📂 main/
│  │  ├─ 📂 java/com/zibete/driverassistant/
│  │  │  ├─ 🧮 calculator/  ← cálculo puro de rentabilidad
│  │  │  ├─ 📸 capture/     ← MediaProjection, monitoreo, frame gate y buffer
│  │  │  ├─ ⚙️ config/      ← configuración local con DataStore
│  │  │  ├─ 🪵 debug/       ← logs y trazabilidad
│  │  │  ├─ 🔎 ocr/         ← OCR, parser, sanitización y pipeline
│  │  │  ├─ 🪟 overlay/     ← servicio y estado del overlay flotante
│  │  │  ├─ 🎨 ui/          ← pantalla principal en Compose
│  │  │  └─ 🗺️ zones/       ← reglas por zonas/textos detectados
│  │  └─ 📂 res/            ← recursos Android
│  └─ 🧪 test/              ← tests unitarios JVM
└─ ⚙️ build.gradle.kts

---

🧪 Tests

El proyecto incluye tests unitarios para reglas críticas:

• cálculo de rentabilidad;
• parser OCR;
• detección de presencia de oferta;
• frame gate;
• buffer de candidatos OCR;
• pipeline de decisión;
• configuración local;
• estado visual del overlay.

Comando principal:

./gradlew :app:testDebugUnitTest

---

🗺️ Roadmap

Corto plazo

• Mejorar documentación para usuarios y desarrolladores.
• Agregar capturas reales de la app.
• Crear guía de instalación.
• Agregar templates de Issues y Pull Requests.
• Validar consumo de memoria/CPU en uso prolongado.
• Ajustar OCR con casos reales anonimizados.
• Consolidar modo diagnóstico.

Mediano plazo

• Historial local de viajes analizados.
• Estadísticas por día, semana o mes.
• Exportación CSV.
• Mejor onboarding para conductores.
• Mejor explicación de cada decisión.
• Configuraciones sugeridas por tipo de uso.

Fuera de alcance

• Automatizar aceptación o rechazo de viajes.
• Usar AccessibilityService para operar apps externas.
• Usar APIs privadas.
• Crear backend obligatorio.
• Guardar capturas sin consentimiento.
• Copiar diseño, marca o textos propietarios de apps comerciales.

---

🤝 Contribuir

Este proyecto está abierto a colaboración.

Se aceptan PRs para:

• mejorar OCR/parser;
• agregar tests con textos anonimizados;
• optimizar memoria o CPU;
• mejorar UI/UX;
• mejorar documentación;
• reportar falsos positivos o falsos negativos;
• proponer configuraciones más claras para conductores.

No se aceptan PRs que busquen:

• automatizar clicks;
• aceptar o rechazar viajes automáticamente;
• manipular otras apps;
• usar APIs privadas;
• guardar capturas sin consentimiento;
• copiar assets, marca o UI exacta de terceros.

➡️ Ver: CONTRIBUTING.md

---

🔐 Privacidad

La app está pensada para funcionar de forma local.

Principios actuales:

• no requiere login;
• no usa backend;
• no sube capturas a servidores;
• no guarda imágenes;
• no vende datos;
• la configuración queda en el dispositivo.

➡️ Ver: docs/PRIVACY.md

---

⚖️ Licencia

MIT — ver LICENSE

---

👤 Autor

Matías Abel Peralta

---

🙌 Nota final

Viaje Rentable AR nace como una herramienta comunitaria, gratuita y transparente para conductores.

La idea no es reemplazar la experiencia del conductor, sino aportar una referencia rápida y configurable para decidir mejor.