Primer prototipo

docs/02-implementation-alternatives.md

@@ -0,0 +1,85 @@
+# Alternativas de implementación
+
+Este documento registra las decisiones técnicas tomadas y por qué. El criterio
+guía es **mínimo coste de mantenimiento** para una organización sin ánimo de
+lucro, siguiendo KISS y evitando YAGNI.
+
+## 1. Framework frontend
+
+| Opción | Pros | Contras |
+|---|---|---|
+| **React + Vite** (elegido) | Ecosistema enorme, fácil encontrar contribuidores, build rápido. | Requiere build step. |
+| Next.js | SSR, rutas, imágenes. | Demasiado para una SPA de una página; aumenta complejidad y coste de hosting. |
+| Vanilla JS | Sin dependencias. | Más código manual, menos contribuidores familiarizados. |
+
+**Decisión**: React + Vite. Es el stack más común y los contribuidores
+potenciales lo conocen. Vite mantiene la configuración mínima.
+
+## 2. Mapa
+
+| Opción | Pros | Contras |
+|---|---|---|
+| **Leaflet + OpenStreetMap** (elegido) | Open source, sin claves API, sin coste, tiles gratuitos. | Menos pulido que Mapbox. |
+| Mapbox GL | Más bonito, mejor rendimiento. | Requiere API key y tiene cuotas de pago. |
+| Google Maps | Familiar. | Requiere facturación activada, cuotas estrictas, no encaja con espíritu open source. |
+
+**Decisión**: Leaflet con tiles de OpenStreetMap. Cero coste, sin claves, y la
+librería `react-leaflet` lo hace trivial de integrar.
+
+## 3. Backend y almacenamiento de datos
+
+| Opción | Pros | Contras |
+|---|---|---|
+| **Backend-as-a-Service** (Supabase o similar) elegido | Sin servidor que mantener, base de datos gestionada, panel de moderación incluido en su dashboard. Plan gratuito generoso. | Dependencia de un proveedor. |
+| Backend propio (Node + Postgres) | Control total. | Hay que mantenerlo, pagarlo, securizarlo. Alto coste para una ONG. |
+| Archivo JSON en el repositorio | Sin backend, máxima simplicidad. | Las contribuciones tendrían que llegar como Pull Requests, fricción alta para no-técnicos. |
+
+**Decisión**: BaaS tipo Supabase. Para el prototipo, la capa de datos se
+abstrae en `src/services/businessRepository.js`, así que cambiar de proveedor
+después es localizado. El prototipo entregado usa un **mock en memoria** para
+no acoplar a un proveedor concreto antes de que la organización lo decida.
+
+## 4. Moderación
+
+| Opción | Pros | Contras |
+|---|---|---|
+| **Aprobación desde el dashboard del BaaS** (elegido) | Cero código extra. El revisor cambia un campo `status` de `pending` a `approved`. | Requiere acceso al dashboard. |
+| Panel de moderación dentro de la app | Más cómodo. | Requiere autenticación, roles, vistas extra: explosión de complejidad. |
+
+**Decisión**: La moderación vive fuera del frontend público. El modelo de
+datos incluye un campo `status` (`pending` / `approved` / `rejected`). El
+frontend solo lee los `approved`.
+
+## 5. Estilos
+
+| Opción | Pros | Contras |
+|---|---|---|
+| **CSS plano con variables** (elegido) | Cero dependencias, fácil de leer, los contribuidores con HTML/CSS básico pueden colaborar. | Sin utilidades. |
+| Tailwind | Productivo. | Cadena de build extra, curva de aprendizaje. |
+| CSS-in-JS | Componentes encapsulados. | Runtime extra, peor accesibilidad para nuevos contribuidores. |
+
+**Decisión**: CSS plano. La app es de una página; no se justifica más.
+
+## 6. Gestión de estado
+
+**Decisión**: `useState` y `useEffect` de React. No hay Redux, Zustand ni
+Context global. La app es pequeña; añadir una librería de estado sería YAGNI.
+
+## 7. Geocodificación de direcciones del formulario
+
+**Decisión para el prototipo**: el usuario hace clic en el mapa para fijar la
+ubicación, o introduce lat/lng. Geocodificación automática vía Nominatim
+(OpenStreetMap) queda como mejora futura con bajo coste de añadir.
+
+## 8. Tests
+
+**Decisión**: el prototipo no incluye suite de tests para no inflarlo, pero la
+estructura (servicios separados de componentes, funciones puras donde posible)
+facilita añadirlos. Cuando se incorporen, **Vitest** es la elección natural por
+integrarse con Vite sin configuración.
+
+## 9. Despliegue
+
+**Decisión recomendada**: **GitHub Pages** o **Cloudflare Pages** (gratuitos
+para open source). Una SPA estática construida con `vite build` se despliega
+sin coste y sin servidor. Ver `docs/06-github-setup.md`.