TRD - Rutas de Solidaridad

1Visión Técnica General

Objetivo: Construir una PWA robusta, escalable y offline-first para gestión de ayuda humanitaria en emergencias.

⚡ Principios: Offline First · Real Time · Mobile First · Seguridad RLS · Escalabilidad · Código Limpio

📦

Offline First

Funcionalidad sin conexión

⚡

Real Time

Actualizaciones en vivo

📱

Mobile First

Prioridad móvil

🔒

Seguridad

RLS + JWT + Zod

Restricciones Técnicas

Hosting: cPanel con recursos limitados
Equipo: Voluntarios sin experiencia técnica
Tiempo: Implementación urgente (días, no meses)
Presupuesto: Cero ($0) - Todo gratuito/open source

2Stack Tecnológico

Frontend

⚛️

React

18.3.1

Framework principal

⚡

Vite

5.0.0

Build tool rápido

🎨

Tailwind CSS

3.4.0

Estilos rápidos

🧭

React Router

6.23.0

Navegación SPA

🗺️

Leaflet

1.9.4

Mapas gratuitos

📝

React Hook Form

7.51.0

Formularios eficientes

✅

Zod

3.23.0

Validación TypeScript

📦

React Query

5.40.0

Caché y estado

Backend & Servicios

🗄️

Supabase

Postgres + Auth + Storage + Realtime

🐘

PostgreSQL

Base de datos relacional

🔐

Supabase Auth

JWT + Email/Password

🌍

OpenStreetMap

Mapas gratuitos sin límites

3Arquitectura de la Aplicación

Diagrama de Arquitectura

┌─────────────────────────────────────────────────┐ │ CLIENTE (PWA) │ │ ┌──────────────────────────────────────────┐ │ │ │ React SPA - Vite Build │ │ │ │ ┌────────┐┌────────┐┌────────┐┌──────┐ │ │ │ │ │Dashboard│Inventar│ Mapa │Report │ │ │ │ │ └────────┘└────────┘└────────┘└──────┘ │ │ │ │ ┌────────┐┌────────┐┌────────┐┌──────┐ │ │ │ │ │Afectado│Donacion│Voluntar│ Ayuda │ │ │ │ │ └────────┘└────────┘└────────┘└──────┘ │ │ │ └──────────────────────────────────────────┘ │ │ ▼ │ │ ┌──────────────────────────────────────────┐ │ │ │ React Query (Caché y Estado) │ │ │ └──────────────────────────────────────────┘ │ │ ▼ │ │ ┌──────────────────────────────────────────┐ │ │ │ Supabase Client (API) │ │ │ └──────────────────────────────────────────┘ │ └──────────────────────┼──────────────────────────┘ ▼ ┌─────────────────────────────────────────────────┐ │ SUPABASE (Backend) │ │ ┌──────────────────────────────────────────┐ │ │ │ PostgreSQL + RLS + Auth + Storage │ │ │ └──────────────────────────────────────────┘ │ └─────────────────────────────────────────────────┘

Estructura de Carpetas

src/
├── components/
│   ├── ui/            # Botones, inputs, cards
│   ├── layout/        # Navbar, Sidebar, Footer
│   ├── dashboard/     
│   ├── inventario/     
│   ├── afectados/     
│   ├── donaciones/    
│   ├── voluntarios/   
│   ├── asignaciones/  
│   └── mapas/         
├── lib/
│   ├── supabase.js    # Cliente Supabase
│   ├── queries.js     # Consultas
│   ├── mutations.js   # Mutaciones
│   └── helpers.js     
├── hooks/
│   ├── useAuth.js
│   ├── useInventario.js
│   └── useGeolocation.js
├── pages/
│   ├── Dashboard.jsx
│   ├── Afectados.jsx
│   ├── Inventario.jsx
│   ├── Donaciones.jsx
│   ├── Voluntarios.jsx
│   ├── Asignaciones.jsx
│   ├── Mapa.jsx
│   ├── Perfil.jsx
│   └── Login.jsx
├── context/
│   └── AuthContext.jsx
├── utils/
│   ├── validations.js # Zod schemas
│   ├── formats.js     
│   └── constants.js   
├── styles/
│   └── index.css      
└── App.jsx

4Frontend - Especificaciones Técnicas

Vite Configuration

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  build: {
    outDir: 'dist',
    sourcemap: true,
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['react', 'react-dom', 'react-router-dom'],
          supabase: ['@supabase/supabase-js'],
          maps: ['leaflet', 'react-leaflet']
        }
      }
    }
  },
  server: { port: 5173, host: true }
})

Cliente Supabase

import { createClient } from '@supabase/supabase-js'

const supabaseUrl = import.meta.env.VITE_SUPABASE_URL
const supabaseAnonKey = import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY

export const supabase = createClient(supabaseUrl, supabaseAnonKey, {
  auth: { persistSession: true, autoRefreshToken: true },
  realtime: { params: { eventsPerSecond: 10 } }
})

export const getCurrentUser = async () => {
  const { data: { user } } = await supabase.auth.getUser()
  return user
}

Tailwind Config

export default {
  content: ['./index.html', './src/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: {
      colors: {
        primary: { DEFAULT: '#EF4444', light: '#FCA5A5', dark: '#B91C1C' },
        success: '#10B981',
        warning: '#F59E0B',
        danger: '#EF4444'
      },
      fontFamily: { sans: ['Inter', 'sans-serif'] }
    }
  },
  plugins: []
}

5Backend - Especificaciones Técnicas

Configuración de Supabase

URL

https://nvxgygnrgjnddrtboskr.supabase.co

Región

Americas (us-east-1)

Auth

Email/Password + JWT

Sesión

7 días con refresh token

Roles de Usuario

Rol	Acceso
admin	Acceso total al sistema
voluntario	Acceso a datos operativos
public	Solo registro de afectados

Políticas RLS

-- Voluntarios pueden ver afectados
CREATE POLICY "Voluntarios ver afectados" ON afectados
  FOR SELECT USING (auth.role() IN ('admin', 'voluntario'));

-- Cualquiera puede registrar afectados
CREATE POLICY "Publico registrar afectados" ON afectados
  FOR INSERT WITH CHECK (true);

-- Solo admins pueden modificar voluntarios
CREATE POLICY "Admins gestionar voluntarios" ON voluntarios
  FOR ALL USING (auth.role() = 'admin');

6Base de Datos - Diseño Detallado

Tablas del Sistema

#	Tabla	Propósito
1	ubicaciones	Centros de acopio
2	categorias_productos	Categorías de productos
3	productos	Catálogo de productos
4	voluntarios	Datos de voluntarios
5	afectados	Datos de afectados
6	donaciones	Registro de donaciones
7	inventario_ubicacion	Stock por ubicación
8	movimientos_inventario	Historial de movimientos
9	asignaciones	Asignación de ayudas
10	alertas_inventario	Alertas automáticas
11	seguimiento_afectados	Historial de seguimiento

Triggers Automáticos

-- Actualizar inventario automáticamente
CREATE OR REPLACE FUNCTION actualizar_inventario()
RETURNS TRIGGER AS $$
BEGIN
  IF NEW.tipo_movimiento = 'ingreso' THEN
    INSERT INTO inventario_ubicacion (producto_id, ubicacion_id, cantidad)
    VALUES (NEW.producto_id, NEW.ubicacion_destino_id, NEW.cantidad)
    ON CONFLICT (producto_id, ubicacion_id) 
    DO UPDATE SET cantidad = inventario_ubicacion.cantidad + EXCLUDED.cantidad;
  ELSIF NEW.tipo_movimiento = 'salida' THEN
    UPDATE inventario_ubicacion
    SET cantidad = cantidad - NEW.cantidad
    WHERE producto_id = NEW.producto_id AND ubicacion_id = NEW.ubicacion_origen_id;
  END IF;
  RETURN NEW;
END;
$$ LANGUAGE plpgsql;

Datos Iniciales (Seed)

-- Categorías de productos
INSERT INTO categorias_productos (nombre, descripcion, unidad_medida, icono) VALUES
('Alimentos', 'Alimentos no perecederos', 'kg', '🥫'),
('Agua', 'Agua potable', 'litros', '💧'),
('Medicinas', 'Medicamentos', 'unidades', '💊'),
('Ropa', 'Ropa y calzado', 'prendas', '👕'),
('Higiene', 'Higiene personal', 'unidades', '🧴'),
('Bebés', 'Productos infantiles', 'unidades', '🍼');

-- Centros de acopio
INSERT INTO ubicaciones (nombre, direccion, tipo) VALUES
('Catia La Mar', 'Catia La Mar, La Guaira', 'centro_acopio'),
('Caraballeda', 'Caraballeda, La Guaira', 'centro_acopio'),
('Maiquetía', 'Maiquetía, La Guaira', 'centro_acopio');

7API - Diseño y Endpoints

Endpoints Principales

Método	Endpoint	Propósito
GET	/afectados	Listar afectados
POST	/afectados	Registrar afectado
PATCH	/afectados?id=eq.{id}	Actualizar afectado
GET	/inventario_ubicacion	Ver inventario
POST	/movimientos_inventario	Registrar movimiento
GET	/voluntarios	Listar voluntarios
POST	/donaciones	Registrar donación
GET	/asignaciones	Ver asignaciones
POST	/asignaciones	Crear asignación

Ejemplo: Registrar Afectado

const registrarAfectado = async (data) => {
  const { data: result, error } = await supabase
    .from('afectados')
    .insert([{
      cedula: data.cedula,
      nombre: data.nombre,
      latitud: data.latitud,
      longitud: data.longitud,
      adultos: data.adultos,
      ninos: data.ninos,
      necesidades: data.necesidades
    }])
    .select()
  return { result, error }
}

Tiempo Real (WebSockets)

const subscribeInventario = (callback) => {
  return supabase
    .channel('inventario')
    .on('postgres_changes', 
      { event: '*', schema: 'public', table: 'inventario_ubicacion' },
      callback
    )
    .subscribe()
}

8PWA - Configuración y Estrategia

Manifest

{
  "name": "Rutas de Solidaridad",
  "short_name": "RutasSolidaridad",
  "display": "standalone",
  "background_color": "#FFFFFF",
  "theme_color": "#EF4444",
  "orientation": "portrait",
  "icons": [
    { "src": "/icon-192.png", "sizes": "192x192" },
    { "src": "/icon-512.png", "sizes": "512x512" }
  ]
}

Estrategia Offline

Cache First

HTML, JS, CSS, imágenes

Stale While Revalidate

Datos de API

Network First

Operaciones dinámicas

Queue Offline

Sincronización al reconectar

const pendingOperations = []

const syncOffline = async () => {
  if (navigator.onLine) {
    for (const op of pendingOperations) {
      await supabase.from(op.table).insert(op.data)
    }
    pendingOperations = []
    localStorage.setItem('pendingOps', JSON.stringify(pendingOperations))
  }
}

9Seguridad - Implementación

🔐

Autenticación

Supabase Auth + JWT

🛡️

Autorización

RLS Row Level Security

✅

Validación

Zod en frontend y backend

🔒

HTTPS

Forzado en producción

Validación con Zod

import { z } from 'zod'

const afectadoSchema = z.object({
  cedula: z.string().min(6, 'Cédula inválida'),
  nombre: z.string().min(2, 'Nombre requerido'),
  telefono: z.string().optional(),
  adultos: z.number().min(0).default(0),
  ninos: z.number().min(0).default(0),
  necesidades: z.array(z.string()).default([])
})

const validarAfectado = (data) => {
  try {
    return afectadoSchema.parse(data)
  } catch (error) {
    return { error: error.errors }
  }
}

10Despliegue - Estrategia

Entornos

Entorno	URL	Propósito
Dev	localhost:5173	Desarrollo local
Staging	voluntariado.foresve.com/staging	Pruebas
Prod	voluntariado.foresve.com	Producción

Proceso de Despliegue

# 1. Build de producción
npm run build

# 2. Verificar localmente
npm run preview

# 3. Subir carpeta dist/ por FTP
# Usar FTP-Simple

# 4. Verificar despliegue
# Abrir https://voluntariado.foresve.com

.htaccess para SPA + Caché

  RewriteEngine On
  RewriteBase /
  RewriteRule ^index\.html$ - [L]
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule . /index.html [L]


"\.(js|css|png|jpg|jpeg|gif|svg|ico)$">
  Header set Cache-Control "max-age=31536000, public"

11Rendimiento - Optimizaciones

Área	Técnica	Impacto
Carga	Lazy loading de rutas	-40% carga inicial
Imágenes	Optimización con Vite	-50% tamaño
Código	Code splitting automático	-30% bundle
Caché	Service Worker	Carga instantánea
Data	React Query con caché	-70% llamadas API
Mapas	Carga bajo demanda	-60% tiempo

Métricas Objetivo

FCP

< 1.5s

LCP

< 2.5s

TTI

< 3s

Lighthouse

> 90

12Testing - Estrategia

Unit Testing

Componentes y funciones

Integration

Conexiones con Supabase

E2E

Flujos completos (opcional)

import { render, screen } from '@testing-library/react'
import { RegistroAfectado } from './RegistroAfectado'

test('renderiza formulario de afectado', () => {
  render()
  expect(screen.getByText('Registrar Afectado')).toBeInTheDocument()
})

13Monitoreo - Herramientas

Supabase Dashboard

BD y rendimiento

React DevTools

Debugging frontend

Sentry

Errores en producción

const logActivity = (action, data) => {
  console.log(`[${new Date().toISOString()}] ${action}:`, data)
}

15Roadmap Técnico

🔴 Semana 1 - Fundación

Días 1-3

Configurar proyecto Vite
Conectar con Supabase
Estructura de carpetas
Autenticación básica
Layout base

🟡 Semana 1 - Funcionalidad

Días 4-7

Registro de afectados
Dashboard básico
Inventario simple
CRUD de productos
Movimientos inventario

🟢 Semana 2 - Operaciones

Días 8-14

Gestión de donaciones
Asignación de ayudas
Mapa de necesidades
Seguimiento entregas
Perfil voluntarios

🔵 Semana 3 - PWA

Días 15-21

Configuración PWA
Modo offline
Sincronización
Notificaciones push
Reportes exportables

⚪ Semana 4 - Producción

Días 22-28

Testing completo
Optimización rendimiento
Documentación final
Despliegue a producción
Capacitación

📋 Checklist Técnico Final

Repositorio con estructura definida
Conexión a Supabase funcionando
Variables de entorno configuradas
Autenticación implementada
RLS configurado y probado
PWA configurada
Modo offline funcionando
Mapa integrado
Inventario en tiempo real
Registro de afectados funcionando
Sistema de donaciones completo
Asignaciones operativas
Reportes exportables
Documentación completa
Despliegue en producción