onlinces/hackathon-v-escape-4ff8b5a65aeb460d8771b7f4962482c0
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Actualizar README.md

Browse Source
This commit is contained in:
hack_23030818_4519ad
2026-05-23 15:11:03 +00:00
parent 80dbd947e5
commit 5b5a763077
1 changed files with 135 additions and 213 deletions
Download Patch File Download Diff File Expand all files Collapse all files

326
README.md
View File

@@ -1,171 +1,108 @@
# Mi Ruta Limpia
> **Sistema de Notificación Inteligente y Privada de Recolección de Residuos**
> Hackathon LINCEHACK · Gobierno de Celaya
**Sistema de notificación inteligente y privada de recolección de residuos**
Hackathon LINCEHACK · Gobierno de Celaya · 2026
---
## 📑 Tabla de contenidos
## Descripción
1. [Problemática](#-problemática)
2. [Solución](#-solución)
3. [Características principales](#-características-principales)
4. [Stack tecnológico](#-stack-tecnológico)
5. [Arquitectura](#-arquitectura)
6. [Instalación rápida](#-instalación-rápida)
7. [Credenciales demo](#-credenciales-demo)
8. [Estructura del proyecto](#-estructura-del-proyecto)
9. [Privacidad por diseño](#-privacidad-por-diseño)
10. [Documentación adicional](#-documentación-adicional)
Mi Ruta Limpia es una aplicación móvil que resuelve un problema cotidiano en Celaya: la ciudadanía no sabe con certeza cuándo pasará el camión recolector por su domicilio, lo que genera basura acumulada en la vía pública, problemas de salud y molestias vecinales.
La solución ofrece estimaciones de llegada por ventana horaria, notificaciones de cambios operativos, reportes ciudadanos con folio oficial y educación ambiental integrada — todo bajo un principio innegociable de **privacidad por diseño**: el ciudadano solo ve la información de su zona, nunca la ubicación del camión ni las rutas de terceros.
---
## 🎯 Problemática
## Roles y funcionalidades
En Celaya, la ciudadanía no sabe con certeza cuándo el camión recolector pasará por su domicilio. Esto provoca:
### Ciudadano
- Registro de múltiples domicilios con etiquetas personalizadas
- ETA por ventana horaria (ej. "Entre 7:20 y 7:35") sin coordenadas del camión
- Barra de progreso de ruta sin exponer ubicación exacta
- Confirmación de paso del camión con opción de deshacer
- Calificación del servicio (1–5 estrellas)
- Reportes ciudadanos con folio único (`MRL-YYYYMMDD-XXXXXX`) exportables como comprobante
- Módulo de educación ambiental: 4 categorías, datos de impacto y puntos de acopio
- Basura sacada demasiado **temprano** o **tarde**
- Acumulación cuando el camión ya pasó
- Problemas de salud pública: fauna nociva, malos olores, infecciones
- Molestias vecinales por basura en la calle
### Empleado operativo
- Registro de incidencias operativas (falla mecánica, obstáculo, accidente, etc.) con folio `OP-YYYYMMDD-XXXXXX`
- Seguimiento de racha de puntualidad con sistema de bonos ($50 MXN/día puntual)
- Horario preestablecido con descansos técnicos
- Sin acceso a reportes ciudadanos (403 Forbidden por diseño)
**La solución no puede ser un GPS público:** exponer la ruta completa del camión es un riesgo operativo (gente persigue al camión) y de privacidad.
### Administrador
- Dashboard con KPIs en tiempo real: usuarios activos, domicilios, reportes en 24 h, calificación promedio
- Gestión del ciclo de vida de reportes: `PENDIENTE → EN_PROCESO → RESUELTO → CERRADO`
- Administración de usuarios y cambio de roles
- Vista de flotilla (62 camiones) y feedback ciudadano agregado
---
## 💡 Solución
## Stack tecnológico
Una aplicación móvil que:
| Capa | Tecnologías |
|------|-------------|
| Backend | Python 3.13, FastAPI 0.115, SQLAlchemy 2.0, SQLite, JWT (python-jose), bcrypt, Pydantic v2, PyTZ |
| Frontend | React Native 0.74, Expo SDK 51, React Navigation 6, expo-linear-gradient, AsyncStorage |
| DevOps | Watchman, Metro bundler (Expo CLI) |
- Indica **hora aproximada de llegada** del camión a tu domicilio registrado
- Envía **notificaciones** sobre cambios operativos y retrasos
- Educa sobre **separación de residuos**
- Permite **reportar incidencias** con folio oficial
- Tiene 3 vistas: **Ciudadano**, **Empleado operativo** y **Administrador**
Todo bajo un principio **innegociable de Privacidad por Diseño**:
**el ciudadano solo ve la información de su zona, nunca el mapa completo del camión ni rutas de otros.**
La base de datos es SQLite con capacidad de migración a PostgreSQL sin cambios en la capa de servicio.
---
## ✨ Características principales
### 👤 Vista Ciudadano
- 🏠 Múltiples domicilios con etiquetas (Casa, Trabajo, etc.)
- ⏰ ETA por ventana horaria (ej. *"Entre 7:20 y 7:35"*) — **sin coordenadas del camión**
- 📊 Barra de progreso de ruta sin exponer ubicación
- ✓ Confirmación *"¿Ya pasó la basura?"* con opción de deshacer
- ⭐ Calificación del servicio (1-5 estrellas)
- 📋 Reportes con **folio único** (`MRL-YYYYMMDD-XXXXXX`)
- 📤 Compartir reporte como comprobante
- 🌱 Educación ambiental con 4 categorías, datos de impacto y puntos de acopio
- 📅 Horarios por domicilio
### 👮 Vista Empleado Operativo
- 🚛 Reportes operativos (camión no arrancó, falla mecánica, accidente, obstáculo, etc.) con folio `OP-YYYYMMDD-XXXXXX`
- 🔥 **Racha de puntualidad** (días consecutivos)
- 💰 **Bonos** por puntualidad ($50 MXN/día puntual)
- 🏆 Próximo bono con cuenta regresiva
- 📅 Horario preestablecido con descansos técnicos
- 💬 Mensajes motivacionales rotativos
- ❌ **Sin acceso** a reportes ciudadanos (403 Forbidden)
### 🛡️ Vista Administrador
- 📊 Dashboard con KPIs en vivo (ciudadanos, domicilios, reportes 24h, calificación promedio)
- 📈 Gráficas de reportes por estado y por tipo
- 📋 Gestión de reportes ciudadanos (cambiar PENDIENTE → EN_PROCESO → RESUELTO → CERRADO)
- 👥 Gestión de usuarios y cambio de roles
- 🚛 Vista de flotilla (62 camiones)
- ⭐ Feedback ciudadano agregado
---
## 🛠️ Stack tecnológico
### Backend
- **Python 3.13** con **FastAPI 0.115**
- **SQLAlchemy 2.0** + **SQLite** (escalable a PostgreSQL)
- **JWT** (python-jose) + **bcrypt** para autenticación
- **Pydantic v2** para validación
- **PyTZ** para manejo correcto de zonas horarias (Celaya/CST)
### Frontend
- **React Native 0.74** con **Expo SDK 51**
- **React 18.2** + **React Navigation 6**
- **expo-linear-gradient**, **@expo/vector-icons**, **react-native-svg**
- **AsyncStorage** para persistencia local
- **react-native-url-polyfill** para compatibilidad WHATWG URL
### DevOps
- **Watchman** para file watching en macOS
- **Metro** bundler (Expo CLI)
- Migraciones manuales con SQL inline en seeds
---
## 🏗️ Arquitectura
## Arquitectura
```
┌─────────────────────────────────────────────────────────────────┐
┌──────────────────────────────────────────────────────────────────┐
│ FRONTEND (Expo) │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ CIUDADANO │ │ EMPLEADO │ │ ADMIN │ │
│ │ Ciudadano │ │ Empleado │ │ Admin │ │
│ │ 5 tabs │ │ 3 tabs │ │ 4 tabs │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │ │ │
│ └────────────────┼──────────────────┘ │
│ │ │
│ fetch + AsyncStorage (JWT) │
└──────────────────────────┼───────────────────────────────────────┘
│ HTTPS REST
▼
┌─────────────────────────────────────────────────────────────────┐
┌──────────────────────────────────────────────────────────────────┐
│ BACKEND (FastAPI) │
│ │
│ Routers: │
│ /api/v1/auth — login, register, OAuth, /me │
│ /api/v1/auth — login, registro, /me │
│ /api/v1/addresses — CRUD de domicilios + geo-routing │
│ /api/v1/eta — cálculo de ETA privado │
│ /api/v1/reports — reportes ciudadanos │
│ /api/v1/admin — endpoints restringidos a ADMIN │
│ /api/v1/staff — endpoints para EMPLEADO/ADMIN │
│ /api/v1/admin — restringido a ADMIN │
│ /api/v1/staff — restringido a EMPLEADO/ADMIN │
│ │
│ Middleware: │
│ - JWT auth (HTTPBearer) │
│ - RBAC (require_admin, require_staff) │
│ - CORS │
│ │
│ Services: │
│ - eta_service: simulación temporal de la flotilla │
│ - auth_service: hash, verify, JWT │
└──────────────────────────┼───────────────────────────────────────┘
│ Middleware: JWT (HTTPBearer) · RBAC · CORS │
└──────────────────────────┬───────────────────────────────────────┘
│
┌──────────┴───────────┐
┌───────────┴────────────┐
▼ ▼
┌──────────────┐ ┌───────────────┐
┌──────────────┐ ┌────────────────┐
│ SQLite │ │ routes.json │
│ │ │ (mock GPS) │
│ 6 tablas: │ │ │
│ - users │ │ 15 rutas con │
│ - addresses │ │ waypoints + │
│ - reports │ │ timestamps │
│ - op_reports│ └───────────────┘
│ - ratings │
│ - trucks │
│ users │ │ │
│ addresses │ │ 15 rutas con │
│ reports │ │ waypoints + │
│ op_reports │ │ timestamps │
│ ratings │ └────────────────┘
│ trucks │
└──────────────┘
```
Ver detalles en [`docs/ARQUITECTURA.md`](docs/ARQUITECTURA.md).
Para el análisis completo de decisiones técnicas, ver [`docs/ARQUITECTURA.md`](docs/ARQUITECTURA.md).
---
## 🚀 Instalación rápida
## Instalación
### Prerequisitos
- **Node.js 20 LTS** (NO usar 22+)
- **Python 3.11+**
- **macOS** o **Linux** (instrucciones probadas en macOS con Xcode + iOS Simulator)
### Requisitos previos
- Node.js 20 LTS (no compatible con Node 22+)
- Python 3.11 o superior
- macOS o Linux (probado en macOS con Xcode + iOS Simulator)
### Backend
@@ -176,140 +113,125 @@ source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# Poblar BD con datos demo + masivos
# Poblar la base de datos con datos demo
python seed_massive.py
# Arrancar API
# Iniciar el servidor
uvicorn main:app --reload --host 0.0.0.0 --port 8000
```
API disponible en `http://localhost:8000` · Docs interactivos en `http://localhost:8000/docs`
La API queda disponible en `http://localhost:8000`. La documentación interactiva en `http://localhost:8000/docs`.
### Frontend
```bash
cd frontend
ulimit -n 65536 # macOS file descriptors
ulimit -n 65536 # macOS: ampliar límite de file descriptors
npm install
npx expo start --clear
# Presiona 'i' para iOS simulator | 'w' para web | escanea QR con Expo Go
```
> ⚠️ La URL del backend está en [`frontend/src/constants/config.js`](frontend/src/constants/config.js). Cámbiala si tu IP local no es `10.82.68.125`.
Presiona `i` para iOS Simulator, `w` para web, o escanea el QR con Expo Go.
Ver guía completa en [`docs/INSTALACION.md`](docs/INSTALACION.md).
> La URL del backend se configura en [`frontend/src/constants/config.js`](frontend/src/constants/config.js). Actualízala si tu IP local difiere de `10.82.68.125`.
Para la guía paso a paso y troubleshooting, ver [`docs/INSTALACION.md`](docs/INSTALACION.md).
---
## 🔑 Credenciales demo
## Credenciales de demo
| Rol | Email | Contraseña | Acceso |
|-----|-------|-----------|--------|
| 🧑 Ciudadano | `demo@celaya.gob.mx` | `Celaya2026` | 5 pestañas: Inicio, Horarios, Educación, Reportes, Perfil |
| 👮 Empleado | `empleado@celaya.gob.mx` | `Empleado2026` | 3 pestañas: Inicio (puntualidad), Reportes operativos, Cuenta |
| 🛡️ Admin | `admin@celaya.gob.mx` | `Admin2026` | 4 pestañas: Dashboard, Reportes ciudadanos, Usuarios, Cuenta |
| Rol | Email | Contraseña |
|-----|-------|-----------|
| Ciudadano | `demo@celaya.gob.mx` | `Celaya2026` |
| Empleado | `empleado@celaya.gob.mx` | `Empleado2026` |
| Administrador | `admin@celaya.gob.mx` | `Admin2026` |
La BD tiene además **202 usuarios totales, 302 domicilios, 280 reportes ciudadanos, 150 reportes operativos, 220 calificaciones y 62 camiones** generados con `seed_massive.py`.
La base de datos de demo incluye 202 usuarios, 302 domicilios, 280 reportes ciudadanos, 150 reportes operativos, 220 calificaciones y 62 camiones generados con `seed_massive.py`.
---
## 📂 Estructura del proyecto
## Privacidad por diseño
Este principio es el núcleo del proyecto y responde directamente al reto planteado en el hackathon.
| Riesgo | Mitigación implementada |
|--------|------------------------|
| Ciudadanos persiguiendo camiones | El endpoint `/eta/address/:id` devuelve únicamente: status, mensaje, eta_minutes, window_start/end y progress%. Sin coordenadas. |
| Acceso a rutas de otros usuarios | El backend valida que `Address.user_id == JWT.user_id` en cada solicitud. |
| Exposición de información operativa | Las rutas de otros camiones son inaccesibles incluso con manipulación del request. |
| Incentivo a perseguir camiones | La interfaz incluye el aviso explícito: "Por tu seguridad, no persigas al camión." |
| Datos sensibles | Contraseñas con bcrypt · JWT firmado con HS256 · sin PII en logs. |
---
## Estructura del proyecto
```
mi-ruta-limpia/
├── README.md ← este archivo
├── README.md
├── docs/
│ ├── ARQUITECTURA.md ← decisiones técnicas
│ ├── MANUAL_USUARIO.md ← guía visual por pantalla
│ ├── API.md ← referencia REST
│ ├── INSTALACION.md ← guía paso a paso
│ └── PRESENTACION.md ← script de demo
│ ├── ARQUITECTURA.md # Decisiones técnicas y algoritmo ETA
│ ├── MANUAL_USUARIO.md # Guía visual por pantalla
│ ├── API.md # Referencia REST completa
│ ├── INSTALACION.md # Setup y troubleshooting
│ └── PRESENTACION.md # Script de demo para el pitch
│
├── backend/
│ ├── main.py ← entry point + CORS + routers
│ ├── main.py # Entry point, CORS y routers
│ ├── requirements.txt
│ ├── seed.py ← seed básico (3 usuarios)
│ ├── seed_massive.py ← seed con 200+ usuarios y datos
│ ├── seed.py # Seed básico (3 usuarios)
│ ├── seed_massive.py # Seed completo (200+ usuarios)
│ └── app/
│ ├── config.py ← settings (JWT, DB)
│ ├── database.py ← SQLAlchemy session
│ ├── models/ ← User, Address, Report, OperationalReport, Truck, ServiceRating
│ ├── schemas/ ← Pydantic v2
│ ├── routers/ ← auth, addresses, eta, reports, admin, staff
│ ├── services/ ← auth_service, eta_service
│ └── data/routes.json ← 15 rutas mock
│ ├── config.py
│ ├── database.py
│ ├── models/ # User, Address, Report, OperationalReport, Truck, ServiceRating
│ ├── schemas/ # Pydantic v2
│ ├── routers/ # auth, addresses, eta, reports, admin, staff
│ ├── services/ # auth_service, eta_service
│ └── data/routes.json # 15 rutas mock
│
└── frontend/
├── App.js
├── index.js ← polyfill + entry
├── index.js
├── package.json
├── babel.config.js
├── app.json
├── assets/ ← logos, hero-eco, splash, icons
├── assets/
└── src/
├── constants/ ← colors, config
├── context/ ← AuthContext (JWT + role)
├── navigation/ ← AppNavigator (routing por rol)
├── components/ ← AppHeader, GoogleGIcon
├── services/api.js ← fetch + interceptors
├── constants/ # colors, config
├── context/ # AuthContext (JWT + role)
├── navigation/ # AppNavigator (routing por rol)
├── components/ # AppHeader, GoogleGIcon
├── services/api.js # fetch + interceptors
└── screens/
├── auth/ ← Login, Register
├── HomeScreen.js ← ciudadano (5 tabs)
├── auth/ # Login, Register
├── HomeScreen.js
├── SchedulesScreen.js
├── ReportsScreen.js
├── ProfileScreen.js
├── EducationScreen.js
├── staff/ ← empleado (3 tabs)
│ ├── StaffDashboard.js
│ └── StaffReports.js
└── admin/ ← admin (4 tabs)
├── AdminDashboard.js
├── AdminReports.js
├── AdminUsers.js
└── AdminProfile.js
├── staff/ # StaffDashboard, StaffReports
└── admin/ # AdminDashboard, AdminReports, AdminUsers, AdminProfile
```
---
## 🔒 Privacidad por diseño
## Documentación
Este es el **principio innegociable** del reto del hackathon. Cumplimos así:
| Riesgo | Mitigación |
|--------|-----------|
| Ciudadanos persiguiendo camiones | El endpoint `/eta/address/:id` **nunca devuelve coordenadas del camión**. Solo: status, mensaje, eta_minutes, window_start/end, progress% |
| Snooping de otras rutas | El usuario solo puede consultar sus propios `address_id`. El backend valida `Address.user_id == JWT.user_id` |
| Exposición de información operativa | Las rutas de los demás camiones no son visibles ni siquiera con manipulación del request |
| Confianza en la app | La interfaz **desalienta explícitamente** perseguir al camión (`"Por tu seguridad, no persigas al camión"`) |
| Datos sensibles | Contraseñas con bcrypt · JWT firmado con HS256 · ningún PII se expone en logs |
Ver [`docs/ARQUITECTURA.md#privacidad-por-diseño`](docs/ARQUITECTURA.md) para el análisis completo.
| Documento | Audiencia | Contenido |
|-----------|-----------|-----------|
| [`docs/ARQUITECTURA.md`](docs/ARQUITECTURA.md) | Jueces técnicos | Decisiones de diseño, algoritmo ETA, RBAC, simulación de flotilla |
| [`docs/MANUAL_USUARIO.md`](docs/MANUAL_USUARIO.md) | Usuarios finales | Guía visual por pantalla y flujo completo |
| [`docs/API.md`](docs/API.md) | Desarrolladores | Referencia REST con ejemplos |
| [`docs/INSTALACION.md`](docs/INSTALACION.md) | Operaciones | Setup paso a paso y troubleshooting |
| [`docs/PRESENTACION.md`](docs/PRESENTACION.md) | Equipo presentador | Script de demo para los 5–10 min del pitch |
---
## 📚 Documentación adicional
## Licencia
| Documento | Para quién | Contenido |
|-----------|------------|-----------|
| [`docs/ARQUITECTURA.md`](docs/ARQUITECTURA.md) | Jueces técnicos | Decisiones de diseño, algoritmo ETA, RBAC, BD, simulación |
| [`docs/MANUAL_USUARIO.md`](docs/MANUAL_USUARIO.md) | Usuarios finales | Guía visual por pantalla y flujo |
| [`docs/API.md`](docs/API.md) | Desarrolladores | Referencia REST completa con ejemplos |
| [`docs/INSTALACION.md`](docs/INSTALACION.md) | Equipo de operaciones | Setup paso a paso, troubleshooting |
| [`docs/PRESENTACION.md`](docs/PRESENTACION.md) | Equipo presentador | Script de demo para los 5-10 min del pitch |
Proyecto desarrollado con fines educativos en el marco del hackathon LINCEHACK 2026. Los datos de Celaya son referenciales.
---
## 🏆 Equipo
**LINCEHACK 2026** — Hackathon Gobierno de Celaya
---
## 📝 Licencia
Proyecto desarrollado para fines educativos en el marco del hackathon LINCEHACK. Datos de Celaya son referenciales.
---
🌱 *Celaya, es la esperanza.*
*Celaya, es la esperanza.*