Smart Delivery - Sistema de Gestión de Entregas

Un sistema integral de gestión de pedidos y entregas con autenticación de usuarios, roles diferenciados (admin/delivery), gestión de productos, seguimiento de órdenes y historial de entregas en tiempo real.

Construido con TypeScript, Next.js 16, React 19, TailwindCSS, shadcn/ui, y Convex.

🚀 Características Principales

👥 Sistema de Autenticación y Roles

• Autenticación segura con Lucia y @auth/core
• Roles diferenciados:
  • Admin: Gestión completa del sistema
  • Delivery: Gestión de entregas asignadas
  • Usuario: Acceso limitado
• Contraseñas hasheadas con bcryptjs

📦 Gestión de Productos

• Crear, leer, actualizar y eliminar productos
• Información detallada: nombre, descripción, SKU, precio, cantidad
• Categorización de productos
• Imágenes asociadas con almacenamiento en Convex
• Seguimiento de fechas de creación y actualización

📋 Gestión de Pedidos

• Crear y gestionar pedidos
• Estados de pedidos:
  • Pendiente
  • Confirmado
  • Listo
  • En tránsito
  • Entregado
  • Cancelado
• Información del cliente (nombre, email, teléfono)
• Dirección de entrega
• Cálculo automático de totales
• Asignación de personal de entrega

🚚 Gestión de Entregas

• Asignación de pedidos a personal de entrega
• Historial completo de entregas
• Seguimiento de ubicación
• Notas y estado en tiempo real
• Historial temporal de movimientos

📊 Panel de Control

• Dashboard para administradores con estadísticas
• Dashboard para personal de entrega con órdenes asignadas
• Visualización de datos con gráficos
• Tablas interactivas con TanStack React Table

🌍 Mapas Interactivos

• Integración con Leaflet para visualización de entregas
• Ubicación en tiempo real de entregas
• React Leaflet para componentes React

🎨 UI Moderno

• Componentes de shadcn/ui
• Diseño responsivo con TailwindCSS
• Tema claro/oscuro
• Notificaciones con Sonner
• Componentes reutilizables

📱 Funcionalidades Adicionales

• Validación de formularios con Zod y React Hook Form
• Componentes de carga y esqueletos
• Diálogos de confirmación
• Menús de navegación avanzados
• Soporte para múltiples dispositivos

🛠️ Stack Tecnológico

Frontend

• Next.js 16 - Framework React full-stack
• React 19 - Librería UI
• TypeScript - Tipado estático
• TailwindCSS 4 - Estilos CSS
• shadcn/ui - Componentes UI
• React Hook Form - Gestión de formularios
• Zod - Validación de esquemas
• TanStack React Table - Tablas avanzadas
• Leaflet & React Leaflet - Mapas interactivos
• Recharts - Gráficos y visualización
• Lucide React - Iconos
• Sonner - Sistema de notificaciones
• Next Themes - Soporte de temas

Backend

• Convex - Backend-as-a-Service
• Lucia - Autenticación
• @auth/core - Sistema de autenticación
• bcryptjs - Hashing de contraseñas

DevTools & Configuración

• Turborepo - Monorepo optimizado
• Biome - Linting y formateo (Ultracite preset)
• Husky - Git hooks para calidad de código
• pnpm - Package manager

📋 Requisitos Previos

• Node.js 18+ o superior
• pnpm 10.20.0 o superior
• Cuenta de Convex (gratuita en convex.dev)
• Git para control de versiones

🚀 Instalación y Configuración

1. Clonar el Repositorio

git clone <repository-url>
cd smart-delivery

2. Instalar Dependencias

pnpm install

3. Configurar Convex (Primera vez)

Este paso configura el backend en Convex y autentica tu aplicación:

pnpm run dev:setup

El script te pedirá que:

• Ingreses con tu cuenta de Convex (o crees una nueva)
• Selecciones o crees un nuevo proyecto
• Confirmes la configuración

4. Ejecutar en Desarrollo

Para ejecutar toda la aplicación (frontend + backend):

pnpm run dev

Esto iniciará:

• Frontend: localhost:3001 (Next.js)
• Backend: Convex Dev Server (sincronización automática)

La aplicación se abrirá automáticamente en tu navegador.

📦 Otros Scripts Disponibles

# Ejecutar solo la web
pnpm run dev:web

# Ejecutar solo el backend
pnpm run dev:server

# Compilar para producción
pnpm run build

# Verificar tipos TypeScript
pnpm run check-types

# Formatear y verificar código con Biome
pnpm run check

# Iniciar servidor de producción
pnpm run start

📁 Estructura del Proyecto

smart-delivery/
├── apps/
│   └── web/                          # Aplicación Next.js
│       ├── src/
│       │   ├── app/                 # Rutas de Next.js
│       │   │   ├── (app)/          # Rutas autenticadas
│       │   │   │   ├── admin/      # Panel de admin
│       │   │   │   │   ├── dashboard/
│       │   │   │   │   ├── orders/
│       │   │   │   │   ├── products/
│       │   │   │   │   └── staff/
│       │   │   │   └── delivery/   # Panel de delivery
│       │   │   └── (auth)/         # Rutas públicas
│       │   │       └── login/
│       │   ├── components/         # Componentes React
│       │   │   ├── shared/        # Componentes compartidos
│       │   │   ├── ui/            # Componentes shadcn/ui
│       │   │   └── layout files
│       │   ├── lib/               # Utilidades
│       │   ├── schemas/           # Esquemas Zod
│       │   └── utils/             # Funciones de utilidad
│       └── package.json
│
├── packages/
│   └── backend/                     # Backend Convex
│       ├── convex/
│       │   ├── schema.ts           # Definición de base de datos
│       │   ├── auth.ts            # Autenticación
│       │   ├── users.ts           # Gestión de usuarios
│       │   ├── products.ts        # Gestión de productos
│       │   ├── orders.ts          # Gestión de pedidos
│       │   ├── deliveryHistory.ts # Historial de entregas
│       │   ├── actions/           # Acciones personalizadas
│       │   ├── internal/          # Funciones internas
│       │   └── _generated/        # Archivos autogenerados
│       └── package.json
│
├── biome.json                       # Configuración Biome
├── turbo.json                       # Configuración Turborepo
├── pnpm-workspace.yaml             # Configuración del workspace
└── tsconfig.base.json              # Configuración TypeScript base

🔐 Sistema de Autenticación

Flujo de Login

1. Usuario ingresa email y contraseña
2. Sistema valida credenciales con bcryptjs
3. Si son válidas, se crea una sesión de Lucia
4. Usuario recibe rol (admin/delivery)
5. Se redirige según el rol

Rutas Protegidas

• Rutas bajo (app) requieren autenticación
• Rutas bajo (auth) son públicas (solo para no autenticados)

Roles y Permisos

Rol	Acceso
Admin	Todos los módulos (productos, pedidos, staff, dashboard)
Delivery	Panel de entregas, órdenes asignadas, historial
Sin autenticar	Solo login

💾 Modelos de Datos (Base de Datos)

Users

{
  email: string
  name: string
  image: string
  role: 'admin' | 'delivery' | ''
}

Products

{
  name: string
  description: string
  sku: string
  price: number
  quantity: number
  category: string
  imageStorageId: string (opcional)
  createdAt: timestamp
  updatedAt: timestamp
}

Orders

{
  orderNumber: string
  status: 'pending' | 'confirmed' | 'ready' | 'in_transit' | 'delivered' | 'cancelled'
  items: Array<{productId, quantity, price}>
  customerName: string
  customerEmail: string
  customerPhone: string
  deliveryAddress: string
  totalAmount: number
  assignedDeliveryId: string (opcional)
  createdAt: timestamp
  updatedAt: timestamp
  deliveredAt: timestamp (opcional)
}

Delivery History

{
  orderId: string
  deliveryPersonId: string
  status: string
  location: string (opcional)
  notes: string (opcional)
  timestamp: timestamp
}

🧑‍💻 Desarrollo

Estándares de Código (Ultracite/Biome)

Este proyecto usa Ultracite, un preset de Biome de cero configuración que mantiene altos estándares de calidad:

# Formatear código automáticamente
pnpm run check

Principios clave:

• TypeScript explícito
• Sin console.log en producción
• const por defecto, let cuando sea necesario
• Async/await en lugar de promesas
• Componentes funcionales en React
• Hooks correctamente utilizados

Más información: Ver .github/copilot-instructions.md

🚀 Deployment

Producción

1. Compilar la aplicación:

pnpm run build

1. Verificar tipos:

pnpm run check-types

1. Desplegar en Vercel (recomendado para Next.js):
   • Conectar tu repositorio en Vercel
   • Variables de entorno: Convex sincroniza automáticamente
   • Deploy automático en push a main

🆘 Troubleshooting

Error: "Convex project not found"

• Ejecuta pnpm run dev:setup nuevamente
• Verifica que tengas una sesión activa en Convex

Error: "Port 3001 already in use"

• Cambia el puerto: next dev --port=3002
• O libera el puerto existente

Problemas de autenticación

• Borra cookies del navegador (DevTools > Application > Cookies)
• Limpia caché: pnpm run dev (fuerza recarga)

📚 Recursos y Documentación

• Next.js Documentation
• Convex Documentation
• shadcn/ui Components
• TailwindCSS Documentation
• Biome Documentation
• React Documentation

🤝 Contribuir

1. Crear una rama para tu feature: git checkout -b feature/nueva-funcionalidad
2. Hacer commit de tus cambios: git commit -m "Agregar nueva funcionalidad"
3. Ejecutar formateo: pnpm run check
4. Push a la rama: git push origin feature/nueva-funcionalidad
5. Abrir un Pull Request

📝 Licencia

ISC

👨‍💼 Autor

Desarrollado como parte del stack Better-T con Convex

---

¿Necesitas ayuda? Revisa la documentación de Convex o abre un issue en el repositorio.