Añadir README.md

2026-05-23 02:30:03 +00:00
commit 79afadba1b
1 changed files with 116 additions and 0 deletions
--- a/README.md.-.md
+++ b/README.md.-.md
@@ -0,0 +1,116 @@
+# HackOnLinces-2026 — Sistema de Notificación Inteligente de Recolección de Residuos
+
+> **Equipo:** Acapulquitos Boys  
+> **Problemática:** App móvil de notificación privada de ETA del camión de basura + guía de separación de residuos  
+> **Stack:** Flutter 3.44 + Python FastAPI + SQLite + WebSocket
+
+---
+
+## 📚 Índice de la Wiki
+
+### 🏗️ Arquitectura
+- [**Visión general del sistema**](arquitectura/00-vision-general.md) — diagrama de módulos y flujos de datos
+- [**Arquitectura del backend**](arquitectura/01-backend.md) — Clean Architecture en FastAPI
+- [**Arquitectura del frontend**](arquitectura/02-frontend.md) — Feature-first con Riverpod
+
+### 🚀 Setup y ejecución
+- [**Requisitos previos**](setup/00-requisitos.md) — Flutter, Python, Git, FVM
+- [**Configurar el backend (Módulo B)**](setup/01-backend.md) — instalar dependencias, correr servidor
+- [**Configurar Flutter (Módulos C y D)**](setup/02-frontend.md) — integrar módulos, correr app
+- [**Variables de entorno**](setup/03-env.md) — configuración de `.env` para desarrollo
+
+### 🔌 Contratos de API
+- [**Endpoints REST**](api/01-endpoints.md) — GET /eta, POST /alerts/breakdown, etc.
+- [**WebSocket**](api/02-websocket.md) — protocolo de eventos en tiempo real
+- [**Modelos de datos**](api/03-models.md) — JSON schemas de request/response
+- [**Integración entre módulos**](api/04-integracion.md) — cómo Persona A, B, C, D se conectan
+
+### 🔧 Troubleshooting
+- [**Errores comunes**](troubleshooting/01-errores-comunes.md) — CORS, WebSocket, pub get fails
+- [**Problemas de versiones**](troubleshooting/02-versiones.md) — Dart SDK, Java, dependencias
+- [**Debug del simulador**](troubleshooting/03-debug-simulador.md) — verificar estado del camión
+
+---
+
+## 🎯 Quick Start (5 minutos)
+
+### Backend (Persona B)
+```bash
+cd basura_backend
+pip install -r requirements.txt
+uvicorn app.main:app --reload
+# Servidor corriendo en http://localhost:8000
+```
+
+### Frontend (Persona C + D)
+```bash
+cd basura_app
+fvm use 3.44.0              # o 3.22.0 si bajaron versión
+fvm flutter pub get
+fvm flutter run
+```
+
+### Demo completo
+1. Arranca backend → `POST /admin/route/RUTA-01/start`
+2. Abre Flutter → navega a `/guia` (módulo D) o home (módulo C)
+3. WebSocket conecta automáticamente → recibes notificaciones cada 10s
+
+---
+
+## 👥 División de trabajo
+
+| Persona | Módulo | Responsabilidad |
+|---------|--------|-----------------|
+| **A** | Backend Auth | JWT, RBAC, alta de domicilios, validación de zona |
+| **B** | Backend Simulador | Ruta, ETA, WebSocket, notificaciones push |
+| **C** | Flutter UI principal | Login, home ETA, WebSocket, Riverpod |
+| **D** | Flutter Guía offline | Separación de residuos, búsqueda, tema compartido |
+
+---
+
+## 📦 Estructura del repo
+
+```
+hackathon-acapulquitos-boys/
+├── basura_backend/          # Módulo B — Python FastAPI
+│   ├── app/
+│   │   ├── domain/          # Entidades, interfaces
+│   │   ├── data/            # Repositories, datasources
+│   │   ├── services/        # Simulador, WebSocket Manager
+│   │   ├── use_cases/       # Lógica de negocio
+│   │   └── api/routes/      # Endpoints REST
+│   └── requirements.txt
+│
+├── basura_app/              # Flutter (Módulos C + D integrados)
+│   ├── lib/
+│   │   ├── core/theme/      # AppTheme compartido (Persona D)
+│   │   └── features/
+│   │       ├── auth/        # Login (Persona C)
+│   │       ├── eta/         # Home + WebSocket (Persona C)
+│   │       └── recycling_guide/  # Guía offline (Persona D)
+│   ├── assets/
+│   │   └── recycling_guide.json  # 4 categorías de residuos
+│   └── pubspec.yaml
+│
+└── docs/                    # Esta wiki
+```
+
+---
+
+## 🔐 Reglas de Git
+
+- **Branches:** `feature/<nombre>`, `bugfix/<nombre>`
+- **PR a `dev`** cuando algo funcione (compila sin errores)
+- **Commit cada 30 min** — evita perder trabajo
+- **Reunión rápida cada 2 hrs** — sincronizar progreso
+
+---
+
+## 📞 Contacto y soporte
+
+Si algo falla:
+1. Revisa [Errores comunes](troubleshooting/01-errores-comunes.md)
+2. Verifica [Versiones](troubleshooting/02-versiones.md)
+3. Pregunta en el chat del equipo
+
+**¡Éxito en el hackathon! 🚀**