18 min de lectura

Metodología Scrum: DevMart E-Commerce

Documento de planificación ágil Scrum y justificación de decisiones de arquitectura y producto para DevMart E-Commerce.

📋 Metología Scrum: DevMart E-Commerce

Este documento presenta el marco de trabajo ágil Scrum aplicado al desarrollo de DevMart, una plataforma de comercio electrónico de alto rendimiento y omnicanal. La planificación se ha estructurado para justificar de forma profesional cada decisión de arquitectura y producto tomada a lo largo del ciclo de vida del proyecto.

1. Resumen del Producto

DevMart es un e-commerce minimalista especializado en la venta de productos y herramientas de hardware para desarrolladores. Su propuesta de valor central se basa en dos diferenciales clave:

  1. Fricción cero en el embudo de ventas: Permite a los usuarios armar su carrito de compras como visitantes sin necesidad de registro obligatorio inmediato, fusionando de forma transparente su sesión local con el servidor al iniciar sesión.
  2. Omnicanalidad conversacional con Inteligencia Artificial: Integra un chatbot interactivo en Telegram (ECode) capaz de interpretar el lenguaje natural mediante NLP, permitiendo a los usuarios buscar productos, ver sus cuentas, gestionar su carrito y registrarse (mediante una Mini App incrustada) directamente en la aplicación de chat.

Desde la perspectiva de Scrum, el desarrollo del proyecto se enfocó en liberar un MVP (Mínimo Producto Viable) en los primeros sprints, asegurando que las funciones centrales de catálogo y autenticación estuvieran estables, para luego iterar en la optimización de UX (carrito de invitados), el canal conversacional (bot de Telegram + Gemini NLP) y finalmente la resiliencia (rate limiting, seguridad y costos serverless).

2. Epics (Grandes Áreas Funcionales)

Identificamos 6 Epics que agrupan los entregables y definen las prioridades del negocio:

| ID | Nombre de la Epic | Objetivo de Negocio (Valor) | Criterio de Éxito General | | --- | --- | --- | --- | | EPC-01 | Gestión de Catálogo y Navegación | Presentar los productos tecnológicos de forma clara y permitir búsquedas rápidas para acelerar la decisión de compra. | Navegación fluida de categorías y carga de detalles de producto por SKU en menos de 100ms. | | EPC-02 | Sistema de Identidad y Autenticación | Proporcionar una autenticación segura y stateless que proteja los datos personales sin degradar la experiencia de usuario. | Registro e inicio de sesión funcional con JWT y renovación silenciosa de tokens vencidos. | | EPC-03 | Carrito de Compras Híbrido | Incrementar la tasa de conversión facilitando la acumulación de artículos antes de solicitar el registro formal. | Fusión de carrito local (localStorage) con el carrito de base de datos sin duplicar stock. | | EPC-04 | Comercio Conversacional (Telegram) | Habilitar un canal alternativo de ventas directo en la plataforma de chat preferida de los desarrolladores. | Procesamiento de intenciones en lenguaje natural y vinculación de cuentas web vía OTP. | | EPC-05 | Seguridad, Control de Abuso y Estabilidad | Blindar los datos de los usuarios y garantizar la disponibilidad de la API ante picos de demanda o ataques maliciosos. | Cero fugas de información, rate limiters activos por contexto y resiliencia ante fallos del API de Telegram. | | EPC-06 | Contenerización y Despliegue Serverless | Reducir el costo fijo de servidores a cero mientras el negocio no tiene tráfico y asegurar escalado elástico bajo demanda. | Despliegue automatizado en Cloud Run y Vercel con políticas de escalado a 0 instancias (minScale=0). |

3. Product Backlog Priorizado (User Stories & Tasks)

A continuación se desglosa el Product Backlog priorizado por valor de negocio y dependencias técnicas. Las estimaciones de esfuerzo utilizan la escala Fibonacci (1, 2, 3, 5, 8, 13) definidas bajo criterios acordados de complejidad técnica, incertidumbre e integraciones de terceros.

Epic 1: Gestión de Catálogo y Navegación (EPC-01)

📝 US-01: Listado de Productos en la Web (Catálogo)

  • Historia: Como usuario invitado o registrado, quiero ver una lista de todos los productos disponibles con sus precios y stock, para poder elegir qué comprar.
  • Story Points: 3 (Complejidad baja, requiere acceso básico a base de datos y diseño responsive simple).
  • Criterios de Aceptación:
    • [ ] El frontend renderiza una cuadrícula (grid) responsive con nombre del producto, precio, stock y categoría.
    • [ ] Los productos sin stock deben mostrar visualmente que no están disponibles para añadir al carrito.
    • [ ] El tiempo de respuesta de carga del catálogo desde el backend no debe superar los 200ms.
  • Tasks Técnicas:

📝 US-02: Detalle de Producto por SKU

  • Historia: Como usuario interesado, quiero ingresar a la página de detalle de un producto mediante su SKU único, para ver especificaciones técnicas completas y disponibilidad.
  • Story Points: 2 (Complejidad baja, enrutamiento dinámico).
  • Criterios de Aceptación:
    • [ ] La ruta del navegador debe ser amigable y basarse en el SKU (ej. /products/teclado-keychron).
    • [ ] Si el SKU no existe en la base de datos, la aplicación debe mostrar una pantalla de error 404 estructurada.
  • Tasks Técnicas:
    • [ ] Crear endpoint GET /products/:sku en el backend.
    • [ ] Implementar componente dinámico ProductDetail.jsx en el frontend.
    • [ ] Configurar el parámetro SKU en las rutas de App.jsx.

Epic 2: Sistema de Identidad y Autenticación (EPC-02)

📝 US-03: Registro e Inicio de Sesión Web Standard

  • Historia: Como nuevo usuario, quiero registrarme e iniciar sesión con mi correo y contraseña, para poder guardar mis pedidos y favoritos de forma permanente.
  • Story Points: 5 (Complejidad media; requiere encriptación de credenciales y generación segura de JWT).
  • Criterios de Aceptación:
    • [ ] La contraseña del usuario debe guardarse en la base de datos encriptada (con hash salt).
    • [ ] La API debe retornar un JWT válido por 24 horas y los datos básicos del usuario tras un login correcto.
    • [ ] Al registrar un usuario, se debe crear automáticamente un carrito de compras en estado ACTIVE asociado a su ID en la misma transacción de la base de datos.
  • Tasks Técnicas:

📝 US-04: Renovación Automática de Sesión (Silent Token Refresh)

  • Historia: Como usuario autenticado, quiero que mi sesión se mantenga activa de forma transparente mientras uso la web, para evitar que mi token expire a mitad de una transacción.
  • Story Points: 5 (Complejidad media-alta; requiere validación de expiración de token en el cliente e interceptores de red).
  • Criterios de Aceptación:
    • [ ] Al inicializar la app, si el token de localStorage está vencido, se debe llamar al endpoint de refresh en segundo plano.
    • [ ] Si la API del backend retorna un error 401 Unauthorized durante una consulta de carrito, el servicio debe renovar el token y reintentar la llamada de manera transparente para el usuario.
  • Tasks Técnicas:
    • [ ] Crear endpoint /auth/refresh que verifique la firma ignorando la expiración en auth.controller.js.
    • [ ] Implementar decodificador JWT nativo y detector de expiración en AuthContext.jsx.
    • [ ] Diseñar el envoltorio de peticiones fetchWithRefresh en cart.service.js.

Epic 3: Carrito de Compras Híbrido (EPC-03)

📝 US-05: Gestión de Carrito Local para Invitados (Offline-First)

  • Historia: Como visitante no registrado, quiero agregar productos al carrito y modificar sus cantidades, para poder acumular artículos antes de crear una cuenta.
  • Story Points: 5 (Complejidad media; requiere lógica de sincronización local/estado sin tocar la base de datos).
  • Criterios de Aceptación:
    • [ ] Las operaciones de añadir y eliminar elementos se deben almacenar en el localStorage del navegador.
    • [ ] La UI debe validar el stock máximo del catálogo en el lado del cliente y lanzar alertas si se excede.
    • [ ] El contador global del Navbar y el subtotal monetario deben reaccionar instantáneamente a cambios del carrito local.
  • Tasks Técnicas:
    • [ ] Implementar helpers getGuestCart, saveGuestCart y clearGuestCart en el servicio del cliente.
    • [ ] Adaptar la inicialización y formato en CartContext.jsx para leer del localStorage cuando isAuthenticated === false.
    • [ ] Diseñar vista responsive de desglose de carrito en Cart.jsx.

📝 US-06: Fusión Automática de Carritos (Cart Merge)

  • Historia: Como usuario registrado, quiero que los productos que agregué cuando era visitante se unan a mi carrito en la base de datos al iniciar sesión, para no tener que buscarlos otra vez.
  • Story Points: 8 (Complejidad alta; requiere verificar inventario dinámicamente y hacer operaciones atómicas en bucle).
  • Criterios de Aceptación:
    • [ ] Tras un login exitoso, el frontend debe enviar todos los items locales al backend y limpiar el localStorage.
    • [ ] Si un producto ya existe en el carrito del servidor, se debe sumar la cantidad del carrito de invitado atómicamente (upsert).
    • [ ] El backend debe topar la cantidad fusionada al stock físico disponible del producto, ignorando cantidades excedentes de forma silenciosa para evitar inconsistencias.
  • Tasks Técnicas:
    • [ ] Desarrollar endpoint /cart/merge en el backend utilizando upsert y validaciones con Math.min(quantity, Math.max(0, product.stock - currentQty)) en cart.controllers.js.
    • [ ] Configurar disparador de fusión basado en la transición de estado prevAuthRef en el ciclo de vida del CartContext.jsx.

Epic 4: Comercio Conversacional (Telegram) (EPC-04)

📝 US-07: Procesamiento de Lenguaje Natural (Intenciones de Compra)

  • Historia: Como cliente en Telegram, quiero chatear con el bot en lenguaje natural para pedir productos y gestionar mi carrito, para comprar sin salir del chat.
  • Story Points: 13 (Complejidad muy alta; integra API de terceros, latencia de IA, e interpretación sintáctica).
  • Criterios de Aceptación:
    • [ ] El bot de Telegram debe capturar el texto y llamar a la API de Gemini para clasificarlo en intenciones (buy, view_cart, list_products, help).
    • [ ] La IA debe extraer correctamente variables clave (nombre de producto, cantidad) y retornarlas en un JSON estrictamente estructurado.
    • [ ] Si la IA no logra interpretar el texto, el bot debe responder con una lista clara de comandos y capacidades de ayuda interactiva.
  • Tasks Técnicas:
    • [ ] Configurar llamada estructurada al modelo gemini-3.1-flash-lite con config JSON MimeType en nlp.service.js.
    • [ ] Implementar enrutador de intenciones en el controlador del webhook en telegram.controller.js.
    • [ ] Programar las consultas a base de datos de productos por concordancia insensitiva (usando el operador contains en Prisma).

📝 US-08: Vinculación Segura de Cuenta Web vía OTP (One-Time Password)

  • Historia: Como usuario registrado, quiero ingresar mi correo electrónico en el chat de Telegram para recibir un código de acceso temporal que vincule mi cuenta web al bot, garantizando que nadie más compre a mi nombre.
  • Story Points: 8 (Complejidad alta; requiere flujos de autenticación en dos canales e integración con servicios de correo).
  • Criterios de Aceptación:
    • [ ] Al recibir un email, el backend debe generar un código aleatorio de 6 dígitos con expiración a 30 minutos y enviarlo por correo usando Resend.
    • [ ] Al ingresar el código en Telegram, el bot debe validar que el código coincida con el chat emisor, vincular el telegramId al cliente e invalidar el OTP por seguridad.
    • [ ] Un usuario no vinculado no debe tener acceso a operaciones de consulta de carrito o compras en la API de Telegram.
  • Tasks Técnicas:
    • [ ] Crear el modelo OtpRequest en la base de datos con un índice único compuesto por [telegramId, email].
    • [ ] Implementar integración con la API de Resend en resend.service.js.
    • [ ] Implementar bloques de protocolo link_account y verify_otp dentro del controlador de Telegram.

📝 US-09: Registro en un Click mediante Telegram Mini App

  • Historia: Como usuario nuevo de Telegram, quiero poder abrir una pestaña de registro simplificado dentro del chat si mi correo no está registrado en la web, para crear una cuenta en segundos sin salir de la app de mensajería.
  • Story Points: 8 (Complejidad alta; requiere integrar capacidades UI nativas de Telegram con el flujo de registro Express).
  • Criterios de Aceptación:
    • [ ] Si un correo ingresado en el bot no existe en la base de datos, el bot debe responder con un botón de teclado en línea (inline_keyboard) con acción web_app.
    • [ ] La Mini App debe abrir un formulario web responsivo que envíe los datos al endpoint de registro del backend (/auth/telegram-signup), guardando automáticamente el telegramId.
  • Tasks Técnicas:
    • [ ] Implementar lógica de envío de payload estructurado con Inline Keyboard WebApp a la API de Telegram en el controlador del bot.
    • [ ] Crear el endpoint de base de datos especializado telegramSignUp en el controlador de autenticación del backend.

Epic 5: Seguridad, Rate Limiting y Resiliencia (EPC-05)

📝 US-10: Políticas de Rate Limiting por IP Diferenciadas

  • Historia: Como administrador de la plataforma, quiero limitar la cantidad de peticiones que una IP puede realizar a las rutas críticas de autenticación, webhooks y API, para proteger el servidor de sobrecargas y ataques de fuerza bruta.
  • Story Points: 5 (Complejidad media-alta; requiere configuración de middleware y control fino de respuestas de error).
  • Criterios de Aceptación:
    • [ ] Las rutas de inicio de sesión y registro deben estar limitadas estrictamente a 10 intentos cada 15 minutos.
    • [ ] Las llamadas al webhook de Telegram deben estar limitadas a 60 req/min por IP y responder HTTP 200 silencioso al ser limitadas para evitar bucles de reintento.
    • [ ] El API general de la web debe estar protegida con un límite amplio de 100 req/min por IP.
  • Tasks Técnicas:
    • [ ] Configurar middlewares utilizando express-rate-limit con políticas de aislamiento en rateLimiters.js.
    • [ ] Aplicar los limitadores de manera selectiva a los enrutadores en server.js.

📝 US-11: Aislamiento Seguro de Consultas y Prevención de Fugas de Datos

  • Historia: Como cliente registrado, quiero que el sistema me garantice que mis productos favoritos son totalmente privados y que ningún otro usuario (o petición anónima) pueda acceder a ellos.
  • Story Points: 5 (Complejidad media; requiere auditoría de consultas ORM y mitigación de fallos sintácticos en Prisma).
  • Criterios de Aceptación:
    • [ ] Si una llamada a /favorite carece de un token JWT válido o el customerId se evalúa como nulo/indefinido, el backend debe abortar y denegar el acceso.
    • [ ] Se debe comprobar activamente que Prisma no filtre todos los registros de la base de datos bajo condiciones de variables undefined.
  • Tasks Técnicas:
    • [ ] Auditar e implementar cláusulas de salvaguarda de nulidad de ID de usuario en favorites.controller.js.
    • [ ] Implementar pruebas manuales y unitarias para llamadas con tokens alterados.

Epic 6: Contenerización y Despliegue Serverless (EPC-06)

📝 US-12: Contenerización Multi-etapa y Configuración Serverless

  • Historia: Como dueño de la startup, quiero que la aplicación backend esté empaquetada en un contenedor liviano y desplegada en una plataforma serverless elástica, para minimizar los gastos de alojamiento web cuando la tienda no tenga visitantes.
  • Story Points: 5 (Complejidad media; requiere configuración DevOps y empaquetado Docker).
  • Criterios de Aceptación:
    • [ ] El contenedor Docker final de producción no debe incluir dependencias de desarrollo y debe pesar menos de 300MB.
    • [ ] La plataforma serverless debe auto-escalar a 0 instancias inactivas y a un máximo de 3 instancias activas para prevenir costos imprevistos.
  • Tasks Técnicas:
    • [ ] Diseñar el archivo Dockerfile usando Node 22 slim en dos etapas (builder y runner) y habilitando corepack para pnpm.
    • [ ] Configurar el archivo de orquestación de recursos de Cloud Run [.service.yaml] con políticas minScale: "0" y maxScale: "3".

4. Roadmap de Sprints y Velocity

Para un desarrollo ágil y ordenado, el proyecto se dividió en 5 Sprints de 2 semanas de duración cada uno.

Las dependencias se han respetado rigurosamente: la persistencia base y los productos se desarrollan primero (Sprint 1), luego la identidad estándar (Sprint 2), después el carrito y la UI reactiva (Sprint 3), el chatbot e IA conversacional después de tener la lógica de negocios lista (Sprint 4) y finalmente la seguridad cloud (Sprint 5).

📈 Tabla de Roadmap de Sprints

| Sprint | Enfoque Principal | Historias de Usuario Incluidas | Story Points Totales | Estado | | --- | --- | --- | --- | --- | | Sprint 1 | Catálogo Core & DB Setup (MVP 1) | US-01 (Catálogo Web), US-02 (Detalle SKU), Setup base de base de datos relacional (Prisma) | 8 SP | Completado | | Sprint 2 | Identidad & Carrito Persistente (MVP 2) | US-03 (Login/Registro Web), Implementación inicial de tabla de carritos en DB | 10 SP | Completado | | Sprint 3 | UX Minimalista & Carrito de Invitado | US-05 (Carrito Local Invitado), US-06 (Fusión de Carritos al Login), US-04 (Token Refresh en Caliente) | 18 SP | Completado | | Sprint 4 | Comercio Conversacional (AI ECode) | US-07 (Intenciones NLP Gemini), US-08 (Vinculación de Cuentas OTP), US-09 (Telegram Mini App SignUp) | 29 SP | Completado | | Sprint 5 | Estabilidad, Seguridad & DevOps | US-10 (Rate Limiters aislados), US-11 (Aislamiento de favoritos Prisma), US-12 (Docker & Google Cloud Run) | 15 SP | Completado |

Velocity Promedio Lograda: 16 Story Points por sprint (con picos en Sprints 3 y 4 debido a la estabilización de integraciones complejas como Gemini NLP y la API de Telegram).

5. Definition of Done (DoD)

Para que una User Story sea considerada completada (Done) por el equipo de Scrum, debe satisfacer la siguiente lista de verificación técnica:

  1. Diseño y Código:
    • [ ] El código pasa los validadores sintácticos (eslint) locales sin errores.
    • [ ] No existen dependencias de desarrollo compiladas en el bundle final de producción.
  2. Persistencia e Integridad:
    • [ ] Las mutaciones complejas en la base de datos (registro con carrito, fusión de carrito) se ejecutan dentro de una transacción atómica de Prisma.
    • [ ] Se han validado explícitamente los casos donde los parámetros ID de usuario son undefined para prevenir accesos no autorizados.
  3. Pruebas y Verificación:
    • [ ] Se verificaron manualmente todos los endpoints modificados mediante peticiones de REST Client y se documentaron los payloads de respuesta HTTP.
    • [ ] El diseño responsivo de la interfaz web se validó en emuladores de dispositivos móviles y navegadores de escritorio.
  4. Ops & Despliegue:
    • [ ] El contenedor de Docker se compila localmente de forma exitosa.
    • [ ] La rama de producción del frontend se despliega automáticamente en Vercel y el backend en Google Cloud Run de forma limpia.

6. Gestión de Riesgos Reales del Proyecto

Identificamos los siguientes riesgos de producto y tecnología basados en la arquitectura real de DevMart:

  1. Dependencia y Latencia del Webhook de Telegram:
    • Riesgo: Caídas en los servidores de la API de Telegram o retrasos en la generación de respuestas por parte del modelo Gemini NLP.
    • Mitigación: Se implementó la liberación inmediata del webhook con HTTP 200. De esta manera, aunque Gemini tarde 2 segundos en responder, Telegram no genera reintentos duplicados y la petición se procesa asíncronamente en segundo plano.
  2. Agotamiento de Stock por Condiciones de Carrera en la Fusión:
    • Riesgo: Que un usuario agregue productos a su carrito de invitado, y al iniciar sesión y fusionar, otro cliente haya comprado el stock disponible restante.
    • Mitigación: La lógica del backend en mergeCart calcula la diferencia en caliente contra la base de datos y aplica un tope dinámico safeQty basado en el stock de inventario real al momento exacto de la fusión.
  3. Pérdida de la caché de Idempotencia en Cloud Run:
    • Riesgo: Al utilizar múltiples instancias activas en Cloud Run y almacenar el set de idempotencia processedUpdates en memoria local, un reintento de Telegram enviado a una instancia distinta podría duplicar una acción de compra.
    • Mitigación: Se documentó la recomendación arquitectónica de migrar la caché en memoria a un almacén compartido de Redis en caso de que la tienda escale regularmente a más de 3 instancias.

7. Retrospectivas Simuladas (Lecciones de Proceso)

Retrospectiva Sprint 3 (Enfoque en la UX y Tokens)

  • ¿Qué pasó?: Los usuarios reportaban que su sesión expiraba súbitamente al estar navegando por la web tras 24 horas y el carrito aparecía vacío de golpe, lo que causaba quejas en soporte.
  • Causa raíz: El JWT expiraba en el cliente y el frontend no tenía un mecanismo de renovación interactivo, forzando un logout plano al detectar errores 401.
  • Acción Correctiva: Diseñamos e implementamos el endpoint /auth/refresh y el interceptor de red fetchWithRefresh en el Sprint 3. La renovación ahora ocurre de forma silenciosa en segundo plano sin interrumpir la navegación.

Retrospectiva Sprint 4 (Integración del Bot de Telegram)

  • ¿Qué pasó?: Telegram enviaba alertas de error en el webhook y volvía a procesar mensajes de compra en bucle, provocando la inserción de cantidades duplicadas de productos en los carritos de los clientes.
  • Causa raíz: El backend tardaba más de 30 segundos en procesar el parsing de Gemini NLP en mensajes largos, causando que Telegram considerara caída la petición HTTP e hiciera reintentos automáticos.
  • Acción Correctiva: Reestructuramos el controlador de Telegram. Ahora, el servidor Express responde 200 OK de forma inmediata apenas recibe el webhook, liberando a Telegram de la espera del timeout, y procesa la IA en segundo plano.

Tags

#Scrum#Agile#Scrum#MVP#Manage
Volver al Blog