Initial commit

docs/MANUAL_USUARIO.md

@@ -0,0 +1,446 @@
+# Manual de usuario
+
+> Guía visual de Mi Ruta Limpia para los tres perfiles: ciudadano, empleado operativo y administrador.
+
+---
+
+## 1. Antes de empezar
+
+### ¿Cómo se entra a la app?
+
+1. Abre **Mi Ruta Limpia** desde el ícono en tu teléfono
+2. En la pantalla de inicio de sesión, escribe tu **correo** y tu **contraseña**
+3. Toca **Iniciar sesión**
+
+> 💡 También puedes entrar con tu cuenta de **Google** o **Facebook** si las vinculaste al registrarte.
+
+### ¿No tienes cuenta?
+Toca **"¿No tienes cuenta? Regístrate"** en la pantalla de login.
+Necesitarás:
+- Tu nombre completo
+- Un correo o teléfono
+- Una contraseña segura (mínimo 6 caracteres)
+
+### ¿Olvidaste tu contraseña?
+Toca **"¿Olvidaste tu contraseña?"** y sigue las instrucciones que llegarán a tu correo.
+
+---
+
+## 2. Vista CIUDADANO 🧑
+
+Después de iniciar sesión, verás 5 pestañas en la parte inferior:
+
+```
+[ Inicio ] [ Horarios ] [ 🌱 ] [ Reportes ] [ Perfil ]
+```
+
+### 2.1 Pestaña INICIO
+
+Es la pantalla principal. Muestra:
+
+- **Cabecera guinda** con "Mi Ruta Limpia"
+- **Logo del Gobierno de Celaya** centrado
+- **Selector de domicilio** (chips horizontales): toca el lugar del que quieres ver información
+- **Tarjeta de ETA**: tu próxima recolección
+  - Mensaje con la ventana horaria (ej. *"Entre las 7:20 y 7:35"*)
+  - Si faltan menos de 30 min, también muestra los minutos exactos
+  - Barra de progreso de la ruta
+  - Ícono de camión
+- **Botón "¿Ya pasó la basura? Sí"**: tócalo cuando confirmes que pasó
+
+#### Al confirmar que pasó:
+1. Aparece un **modal de calificación** (1-5 estrellas) con opción de comentario
+2. Al enviar, la tarjeta cambia a verde con **"Ruta completada para hoy"**
+3. Aparece un enlace **"↩ Deshacer confirmación"** por si te equivocaste
+
+> ⚠️ Mensaje de seguridad: *"Por tu seguridad, no persigas al camión. ¡Saca tu basura con tiempo!"*
+
+#### Generar reporte rápido
+Más abajo hay un botón **"Generación de reportes..."** que te lleva a la pestaña Reportes.
+
+#### Horarios de recolección
+Al final ves el horario aproximado de tu domicilio (días y rango horario).
+
+---
+
+### 2.2 Pestaña HORARIOS
+
+Muestra:
+
+- **Hero guinda** con el día actual: *"Sábado 23 de mayo"*
+- **Tarjeta por cada uno de tus domicilios** con:
+  - Etiqueta (Casa, Trabajo, etc.) y dirección
+  - Badge "Principal" si es tu domicilio default
+  - Días de la semana de recolección (Lunes · Miércoles · Viernes)
+  - Horario aproximado (06:00 - 08:00)
+  - Nombre de la ruta asignada
+- **Sección "Recuerda"** con 4 buenas prácticas:
+  - Saca tu basura máximo 30 min antes
+  - Separa orgánicos, reciclables y sanitarios
+  - En días festivos el servicio puede modificarse
+  - No persigas al camión
+
+---
+
+### 2.3 Pestaña EDUCACIÓN (la hojita verde central)
+
+La pestaña más rica en contenido. Tiene:
+
+#### Hero con foto eco
+Imagen borrosa de naturaleza con mensaje *"Tu basura, nuestro futuro"*
+
+#### Por qué importa
+4 tarjetas explicando el impacto:
+- 🌍 **Ambiental** — separar evita metano en rellenos
+- ❤️ **Salud pública** — evita fauna nociva y enfermedades
+- 💰 **Económico** — Celaya ahorra hasta $1,400 MXN por tonelada reciclada
+- 🏛️ **Celaya limpio** — calles limpias y vecinos saludables
+
+#### Tipos de residuos
+4 categorías que puedes tocar para ver detalle:
+
+| Categoría | Color | Bolsa |
+|-----------|-------|-------|
+| 🌱 **Orgánicos** | Verde | Bolsa verde |
+| ♻️ **Reciclables** | Azul | Bolsa azul/transparente |
+| 🩹 **Sanitarios** | Naranja | Bolsa roja/negra |
+| ⚡ **Especiales/RAEE** | Morado | Punto de acopio |
+
+Al tocar una categoría se abre un **modal con detalle**:
+- Descripción larga
+- ✅ Lista de "Sí va aquí"
+- ❌ Lista de "No va aquí"
+- 💡 Consejo práctico
+- 📊 Dato de impacto
+
+#### Datos que impactan
+4 estadísticas con números fuertes:
+- 60% es orgánico
+- 30% es reciclable
+- 450 años tarda una botella en degradarse
+- 17 árboles se salvan por tonelada de papel reciclado
+
+#### Tips prácticos
+5 consejos para implementar hoy:
+1. En casa: ten 2 botes mínimo
+2. Enjuaga envases primero
+3. Saca a tiempo (no antes, no después)
+4. No mezcles (pilas, medicamentos a puntos de acopio)
+5. Composta casera si tienes patio
+
+#### Puntos de acopio en Celaya
+Lista con lugares reales para:
+- 🔋 Pilas y baterías (Walmart, Soriana, Liverpool)
+- 📱 Electrónicos (Office Depot, Best Buy)
+- 💊 Medicamentos (SINGREM en farmacias)
+- 🛢️ Aceite de cocina (Punto Limpio Municipal)
+
+#### Preguntas frecuentes
+7 preguntas plegables (toca para abrir).
+
+#### Compromiso final
+Banner guinda: *"Si todos los hogares de Celaya separaran su basura, reduciríamos el relleno sanitario en un 70%"*
+
+---
+
+### 2.4 Pestaña REPORTES
+
+Para levantar quejas formales con folio oficial.
+
+#### Pantalla principal
+- **Hero guinda con foto borrosa** y mensaje motivador
+- **Estadísticas rápidas**: número de pendientes, en proceso, resueltos
+- **Botón "Levantar un reporte nuevo"** destacado
+- **Historial filtrable**: Todos / Pendientes / En proceso / Resueltos
+
+#### Crear un reporte (3 pasos)
+1. **Domicilio afectado** (chips para elegir)
+2. **Tipo de incidencia** (4 opciones):
+   - 🚛 El camión no pasó
+   - ⏰ Retraso en la ruta
+   - 🗑️ Acumulación de basura
+   - … Otro
+3. **Descripción** (opcional, 500 caracteres máx)
+
+Al enviar, recibes un **folio único** tipo `MRL-20260523-A4B5C6`.
+
+#### Confirmación
+Aparece una pantalla verde con:
+- ✓ "Reporte enviado con éxito"
+- Folio destacado
+- Estado (PENDIENTE)
+- Tipo de incidencia
+- Domicilio
+- Fecha
+- Tu descripción
+- Botón **"Compartir reporte"** que abre el menú nativo (WhatsApp, correo, copiar, etc.)
+
+#### Ver reportes anteriores
+- Toca cualquier reporte de la lista para ver el detalle
+- Puedes compartirlos cuando quieras desde el detalle
+
+---
+
+### 2.5 Pestaña PERFIL
+
+Para gestionar tus datos y domicilios.
+
+#### Hero guinda con tu identidad
+- Avatar circular con tu inicial
+- Tu nombre y correo
+
+#### Domicilios
+- Lista de tus lugares registrados
+- Cada uno con etiqueta, dirección y badge "Principal" si aplica
+- **Botón ⭐** para marcar como principal
+- **Botón 🗑️** para eliminar
+- **Botón "Agregar"** para añadir uno nuevo
+
+#### Agregar domicilio
+Modal con:
+- Etiqueta (Casa, Trabajo, Familia, Otro)
+- Calle y número
+- Colonia
+- Coordenadas (opcional, para asignar ruta automáticamente)
+
+#### Configuración
+Tres opciones (próximamente conectadas):
+- 🔔 Notificaciones
+- 🛡️ Privacidad
+- ❓ Ayuda y soporte
+
+#### Cerrar sesión
+Botón rojo al final.
+
+---
+
+## 3. Vista EMPLEADO 👮
+
+Después de iniciar sesión con una cuenta `EMPLEADO`, verás solo **3 pestañas**:
+
+```
+[ Inicio ] [ Reportes ] [ Cuenta ]
+```
+
+> ❌ Los empleados **NO** pueden ver ni gestionar reportes ciudadanos. Solo pueden levantar reportes operativos sobre el funcionamiento del camión y la ruta.
+
+### 3.1 Pestaña INICIO (Dashboard del empleado)
+
+#### Hero guinda con tu identidad
+- Avatar con casco
+- "¡Buen turno!" y tu nombre
+- Badge con tu desempeño: **EXCELENTE / MUY BUENO / BUENO**
+
+#### Racha de puntualidad
+Tarjeta naranja con:
+- 🔥 Días consecutivos puntuales (ej. *"19 días seguidos"*)
+- Mensaje motivador: *"¡Sigue así! No rompas la racha."*
+
+#### KPIs
+Dos tarjetas:
+- 🎯 **Puntualidad mensual** (porcentaje)
+- 💰 **Bono acumulado** (en pesos)
+
+#### Próximo bono
+Tarjeta amarilla destacada:
+- *"Te faltan **N días** puntuales para desbloquear **+$500 MXN**"*
+- Trofeo dorado
+
+#### Tu horario
+Tarjeta con:
+- Nombre del turno (Turno Matutino)
+- Horario completo (05:30 → 09:00)
+- Bloque de ruta destacado (06:00 - 08:00)
+- **Descansos preestablecidos**:
+  - ☕ Descanso técnico: 07:00 · 10 min
+  - 🧘 Pausa estiramiento: 08:00 · 5 min
+- Días de la semana (Lunes a sábado) y descanso (Domingo)
+- Nota motivacional sobre puntualidad
+
+#### Mensaje motivacional del día
+Tarjeta verde con una frase rotativa:
+- *"Tu puntualidad permite que miles de familias planifiquen su día"*
+- *"Cada salida a tiempo es un acto de servicio que transforma a Celaya"*
+- *"Eres la cara del Gobierno de Celaya en cada colonia"*
+
+#### Por qué importa tu puntualidad
+4 cards explicando el impacto cívico:
+- Cientos de vecinos planifican su día
+- Evita basura en la calle y fauna nociva
+- Hace más confiables las predicciones de la app
+- Eres la imagen del Gobierno de Celaya
+
+---
+
+### 3.2 Pestaña REPORTES (operativos)
+
+Para reportar incidentes con el camión o la ruta.
+
+#### Pantalla principal
+- Hero guinda con mensaje
+- Botón "Nuevo reporte operativo"
+- Lista de tus reportes anteriores con: folio, categoría, severidad, ruta, fecha y estado
+
+#### Crear un reporte operativo (4 pasos)
+
+**1. ¿Qué pasó?** Grid de 8 categorías con icono:
+- 🔧 No arrancó (camión)
+- ⚙️ Falla mecánica
+- 🚨 Accidente vial
+- 🚧 Obstáculo bloqueando ruta
+- 🚦 Tráfico intenso
+- ⛽ Combustible bajo
+- 🌧️ Clima adverso
+- ··· Otro
+
+**2. Severidad**:
+- 🟢 Baja
+- 🟡 Media
+- 🔴 Alta
+
+**3. Ruta y unidad** (opcional)
+- RUTA-XX
+- Número de unidad
+
+**4. Descripción** (500 caracteres)
+
+Al enviar, recibes un **folio operativo** tipo `OP-20260523-CC35B3`.
+
+#### Compartir reporte
+Igual que los reportes ciudadanos: botón **"Compartir folio"** abre el menú nativo del sistema.
+
+---
+
+### 3.3 Pestaña CUENTA
+
+Vista de perfil con:
+- Tarjeta de identidad con badge "EMPLEADO OPERATIVO"
+- **Tus permisos** (lista con ✓ verdes y ✗ grises):
+  - ✓ Ver dashboard y estadísticas (las tuyas)
+  - ✓ Gestionar reportes ciudadanos → **✗** (no permitido)
+  - ✓ Cambiar estado de incidencias → **✗** (no permitido)
+  - ✓ Gestionar usuarios y roles → **✗**
+- **Sistema** (API conectada, BD SQLite, versión)
+- Botón cerrar sesión
+
+---
+
+## 4. Vista ADMINISTRADOR 🛡️
+
+Después de iniciar sesión con una cuenta `ADMIN`, verás **4 pestañas**:
+
+```
+[ Dashboard ] [ Reportes ] [ Usuarios ] [ Cuenta ]
+```
+
+### 4.1 Pestaña DASHBOARD
+
+KPIs en vivo de toda la ciudad:
+
+#### Encabezado
+Logo de Celaya, tu nombre, badge "🛡️ Administrador"
+
+#### Resumen general
+6 tarjetas con números:
+- 👥 Ciudadanos totales
+- 🏠 Domicilios registrados
+- 📋 Reportes totales
+- ⏰ Reportes en últimas 24h
+- 🚛 Rutas activas
+- ⭐ Calificación promedio
+
+#### Reportes por estado
+Gráfica de barras con conteo y porcentaje:
+- PENDIENTE (naranja)
+- EN_PROCESO (azul)
+- RESUELTO (verde)
+- CERRADO (gris)
+
+#### Reportes por tipo
+Lista con conteo:
+- ACUMULACION
+- NO_PASO
+- OTRO
+- RETRASO
+
+---
+
+### 4.2 Pestaña REPORTES
+
+Gestión completa de reportes ciudadanos.
+
+#### Filtros (chips horizontales)
+- Todos | Pendientes | En proceso | Resueltos | Cerrados
+
+#### Lista de reportes
+Cada tarjeta muestra:
+- Folio
+- Tipo (ej. "El camión no pasó")
+- Badge de estado con color
+- 👤 Nombre del ciudadano
+- 📍 Domicilio + calle
+- 🚛 Ruta asignada
+- 💬 Descripción del ciudadano
+- 📅 Fecha y hora
+- **Botones de acción** (transición de estado):
+  - PENDIENTE → EN_PROCESO / CERRADO
+  - EN_PROCESO → RESUELTO / CERRADO
+  - RESUELTO → CERRADO
+
+Al tocar un botón, el estado cambia inmediatamente y el ciudadano ve la actualización en su app.
+
+---
+
+### 4.3 Pestaña USUARIOS (solo ADMIN)
+
+Para gestionar toda la base de usuarios.
+
+#### Filtros por rol
+- Todos | Ciudadanos | Empleados | Administradores
+
+#### Lista de usuarios
+Cada tarjeta muestra:
+- Avatar con ícono según rol
+- Nombre completo
+- Email
+- Badge con su rol
+- 🏠 Total domicilios · 📋 Total reportes
+
+#### Cambiar rol
+Al tocar un usuario (que no sea tú mismo), aparece un modal:
+- Su nombre y email
+- 3 opciones de rol con su ícono y color
+- Botón "Confirmar" para aplicar el cambio
+- Confirmación con alerta nativa
+
+> ⚠️ No puedes cambiar tu propio rol (medida de seguridad)
+
+---
+
+### 4.4 Pestaña CUENTA
+
+Igual que la del empleado pero con badge **ADMINISTRADOR**:
+- Todos los permisos en ✓ verde
+- Sistema (API, BD, versión)
+- Cerrar sesión
+
+---
+
+## 5. Recomendaciones finales
+
+### Para ciudadanos
+- 📅 Saca la basura **máximo 30 min antes** del horario indicado
+- 🌱 Separa **orgánicos, reciclables y sanitarios** en bolsas distintas
+- 🔋 Lleva pilas, electrónicos y medicamentos a **puntos de acopio**
+- 🚫 No persigas al camión ni saques basura fuera del horario
+- 📝 Si hay un problema, **levanta un reporte**: ayuda a mejorar el servicio
+
+### Para empleados
+- ⏰ Sé puntual: cada minuto cuenta para los vecinos
+- 🚧 Reporta cualquier incidencia (mecánica, vial, climática) al instante
+- 🤝 Eres la cara del Gobierno de Celaya — trato amable hace la diferencia
+
+### Para administradores
+- 📊 Revisa el dashboard diariamente
+- ⚡ Atiende los reportes pendientes en máximo 24-48h
+- 👥 Gestiona los roles con cuidado, no degradas administradores por error