🧸 ToyStore Fullstack

E-commerce fullstack con carrito de compras, pasarela de pagos MercadoPago, integración PUDO para envíos, panel administrativo y backend en Express + PostgreSQL.

---

🚀 Tecnologías utilizadas

• React + TypeScript + Vite
• Node.js + Express
• PostgreSQL + Sequelize
• MercadoPago API
• PUDO API
• Cloudinary
• Nodemailer
• JWT

---

📂 Estructura del proyecto

client/ # Frontend React + Vite + TypeScript
server/ # Backend Express + Sequelize + PostgreSQL

client/

• src/components/Shop → listado y filtros de productos
• src/components/Detail → detalle y agregar al carrito
• src/components/Carrito → vista del carrito, cotización PUDO y checkout
• src/components/MP → manejo del pago y estados success/failure
• src/components/auth/AdminLogin.tsx → ingreso de administrador
• src/components/Dashboard → panel admin para productos y banners

server/

• src/routes/ → definición de endpoints principales
• src/handlers/ → lógica de cada ruta
• src/middleware/ → verificación de JWT y webhook MercadoPago
• src/models/ → definiciones Sequelize de tablas
• src/config/pudoApiConfig.js → URLs de la API PUDO

---

📌 La aplicación sigue una arquitectura:

Frontend → Backend → Base de datos / API externas

Esto permite:

• Separar responsabilidades
• Integrar servicios externos (MercadoPago, PUDO, Cloudinary)
• Mantener el código limpio y escalable

---

🔐 Autenticación y autorización

• JWT para proteger rutas de administración
• checkToken → valida token Bearer en rutas protegidas
• mpMiddleware → verifica firma del webhook de MercadoPago con MP_CLIENT_SECRET
• Admin login con ADMIN_SECRET

---

✅ Validación de datos

• Validación en backend con lógica propia
• Verificación de firma en webhook de MercadoPago
• Manejo de estados de carrito (active, purchased, abandoned)

---

🧠 Lógica de negocio clave

Flujo de compra

1. El cliente navega productos y agrega al carrito
2. El carrito se actualiza con cantidades y totales
3. El usuario cotiza envío con PUDO y selecciona locker/destino
4. Se crea preferencia de pago en MercadoPago
5. El webhook de MercadoPago procesa el pago y actualiza el pedido

Integraciones externas

• MercadoPago: pasarela de pagos con webhook
• PUDO: cotización y creación de órdenes de envío
• Cloudinary: almacenamiento de imágenes
• Nodemailer: notificaciones por email

---

📌 Endpoints

👤 Productos

Método	Endpoint	Descripción	Acceso
GET	/product	Listar productos	Público
GET	/product/:id	Detalle por ID	Público
POST	/product	Crear producto	Solo admin
PUT	/product/:id	Actualizar producto	Solo admin
DELETE	/product/:id	Eliminar producto	Solo admin

🛒 Carrito

Método	Endpoint	Descripción	Acceso
POST	/cart	Crear carrito o agregar producto	Público
GET	/cart/:id	Obtener carrito por ID	Público
PATCH	/cart/:id	Actualizar cantidades	Público
DELETE	/cart/clean/:id	Limpiar carrito	Público
DELETE	/cart/:id	Eliminar carrito	Público
GET	/cart	Listar todos los carritos	Solo admin

💳 Checkout

Método	Endpoint	Descripción
POST	/checkout	Crear preferencia de pago MercadoPago
POST	/checkout/hook	Webhook MercadoPago (firma verificada)

🖼️ Banners

Método	Endpoint	Descripción	Acceso
GET	/banner	Listar banners	Público
GET	/banner/:id	Detalle por ID	Público
POST	/banner	Crear banner	Solo admin
PATCH	/banner/:id	Actualizar banner	Solo admin
DELETE	/banner/:id	Eliminar banner	Solo admin

📦 Envíos (PUDO)

Método	Endpoint	Descripción
GET	/pudo/locations	Ubicaciones de lockers
GET	/pudo/:zone	Lockers por zona
POST	/pudo/quote	Cotizar envío
POST	/pudo/order/:id	Crear orden en PUDO
GET	/pudo/orders	Listar órdenes
GET	/pudo/orders/:id	Orden por ID

🔧 Administración

Método	Endpoint	Descripción
POST	/admin/login	Login admin con ADMIN_SECRET
GET	/admin	Validar token admin
POST	/admin/init	Cargar datos iniciales de prueba

---

🧠 Conceptos aplicados

• Arquitectura fullstack (frontend + backend separados)
• Autenticación JWT para administración
• Webhooks con verificación de firma
• Integración con APIs externas (MercadoPago, PUDO, Cloudinary)
• ORM Sequelize para base de datos
• Envío de emails con Nodemailer
• Manejo de carrito de compras con estados
• Variables de entorno para configuración segura
• Documentación con README estructurado

---

⚙️ Instalación y ejecución

Backend

cd server
npm install
cp .env.example .env
npm run dev

🔒 Mejoras futuras

• Autenticación de usuarios finales (clientes)
• Persistencia de carritos por sesión
• Gestión de stock más robusta (reserva en carrito)
• Paginación y búsqueda avanzada en productos
• Pruebas unitarias e integración end-to-end
• Documentación Swagger/OpenAPI

---

📊 Progreso actual

Módulo	Estado
CRUD de productos	✅ Completado
Carrito de compras	✅ Completado
Pasarela de pagos MercadoPago	✅ Completado
Webhook de pagos	✅ Completado
Integración PUDO (envíos)	✅ Completado
Dashboard administrativo	✅ Completado
Banners promocionales	✅ Completado
Autenticación JWT para admin	✅ Completado

---

👨‍💻 Autor

Dario Fernando Gonzalez