Añadir 00-vision-general.md

2026-05-23 02:53:41 +00:00
parent 2894c91c4d
commit cd9b9226d9
1 changed files with 139 additions and 0 deletions
--- a/00-vision-general.md.-.md
+++ b/00-vision-general.md.-.md
@@ -0,0 +1,139 @@
+# Visión General del Sistema
+
+## Diagrama de arquitectura
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      FLUTTER APP (Mobile)                        │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  ┌──────────────────┐    ┌──────────────────┐                  │
+│  │   Login Screen   │    │  Recycling Guide │                  │
+│  │   (Persona C)    │    │   (Persona D)    │                  │
+│  │                  │    │                  │                  │
+│  │  - Auth JWT      │    │  - 4 categorías  │                  │
+│  │  - Alta usuario  │    │  - Búsqueda      │                  │
+│  └────────┬─────────┘    │  - Offline       │                  │
+│           │              └──────────────────┘                  │
+│           │                                                     │
+│  ┌────────▼──────────────────────────────────┐                 │
+│  │       ETA Home Screen                     │                 │
+│  │       (Persona C)                         │                 │
+│  │                                            │                 │
+│  │  - Ventana horaria (7:20 pm - 7:35 pm)   │                 │
+│  │  - WebSocket listener                     │                 │
+│  │  - Notificaciones push                    │                 │
+│  │  - Riverpod state management              │                 │
+│  └────────┬──────────────────────────────────┘                 │
+│           │                                                     │
+└───────────┼─────────────────────────────────────────────────────┘
+            │
+            │ HTTP REST + WebSocket
+            │
+┌───────────▼─────────────────────────────────────────────────────┐
+│                    FASTAPI BACKEND (Python)                      │
+├──────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  ┌──────────────────┐    ┌──────────────────┐                  │
+│  │   Auth Module    │    │  ETA + Simulator │                  │
+│  │   (Persona A)    │    │   (Persona B)    │                  │
+│  │                  │    │                  │                  │
+│  │  - JWT tokens    │    │  - Simulador     │                  │
+│  │  - RBAC          │    │  - WebSocket     │                  │
+│  │  - Alta domicilio│    │  - Notificaciones│                  │
+│  │  - Validar zona  │    │  - ETA calc      │                  │
+│  └────────┬─────────┘    └────────┬─────────┘                  │
+│           │                       │                             │
+│           └───────────┬───────────┘                             │
+│                       │                                         │
+│              ┌────────▼────────┐                                │
+│              │   SQLite DB     │                                │
+│              │                 │                                │
+│              │  - users        │                                │
+│              │  - addresses    │                                │
+│              │  - rutas        │                                │
+│              │  - puntos_ruta  │                                │
+│              │  - truck_status │                                │
+│              │  - notificaciones│                               │
+│              └─────────────────┘                                │
+│                                                                  │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Principios de diseño
+
+### 🔒 Privacidad por Diseño
+- **El usuario NO ve el mapa completo de la ruta**
+- Solo recibe: ETA + ventana horaria + mensaje de acción
+- El backend **nunca envía coordenadas GPS al cliente**
+- Visión de "túnel": solo su domicilio, cero colonias vecinas
+
+### 🏗️ Clean Architecture
+- **Dominio:** Entidades puras (Ruta, PuntoRuta, Notificación)
+- **Data:** Repositories + Datasources (SQLite, JSON local)
+- **Use Cases:** Lógica de negocio aislada
+- **Presentation:** UI (Flutter) y API (FastAPI) desacopladas
+
+### 🔄 Separación de responsabilidades
+- **Persona A:** Gestión de identidad y domicilios
+- **Persona B:** Simulación de ruta y notificaciones en tiempo real
+- **Persona C:** Experiencia de usuario principal (login + ETA)
+- **Persona D:** Módulo educativo offline (guía de residuos)
+
+---
+
+## Flujos principales
+
+### 1. Alta de usuario (Persona A)
+```
+Usuario → POST /register → Backend valida email/teléfono
+                        → Crea usuario en BD
+                        → Retorna JWT token
+Usuario → POST /addresses → Backend valida lat/lng
+                         → Asigna route_id según zona
+                         → Guarda domicilio
+```
+
+### 2. Consulta de ETA (Persona B + C)
+```
+Flutter → GET /eta/{address_id} → Backend calcula distancia
+                                → Devuelve ventana horaria
+                                → Flutter muestra "7:20 pm – 7:35 pm"
+```
+
+### 3. Notificación en tiempo real (Persona B + C)
+```
+Flutter → WS connect /ws/{address_id}
+Backend Simulador → cada 10s actualiza truck_status
+                 → si ETA ≤ 10 min → broadcast WebSocket
+Flutter → recibe JSON evento → muestra alerta push
+```
+
+### 4. Guía de separación (Persona D)
+```
+Usuario → navega a /guia → Lee assets/recycling_guide.json
+                         → Renderiza 4 categorías
+                         → Buscador offline funciona sin backend
+```
+
+---
+
+## Tecnologías clave
+
+| Capa | Tecnología | Por qué |
+|------|------------|---------|
+| **Frontend** | Flutter 3.44 | Multiplataforma, UI rápida |
+| **Estado** | Riverpod 2.6 | Type-safe, sin BuildContext |
+| **Backend** | FastAPI 0.111 | Async nativo, WebSocket, validación Pydantic |
+| **BD** | SQLite | Ligero, sin servidor externo, suficiente para MVP |
+| **WebSocket** | uvicorn + APScheduler | Push real-time sin polling |
+
+---
+
+## Siguiente paso
+
+Lee las arquitecturas detalladas:
+- [Backend (Persona B)](01-backend.md)
+- [Frontend (Persona C + D)](02-frontend.md)