Añadir 00-vision-general.md
139
00-vision-general.md.-.md
Normal file
139
00-vision-general.md.-.md
Normal file
@@ -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)
|
||||||
Reference in New Issue
Block a user