erp-retail-backend-v2/docs/SPRINT-4-SUMMARY.md

Sprint 4: Motor de Precios - Resumen

Objetivo

Implementar el motor de precios completo para el vertical de Retail, incluyendo gestión de promociones, cupones y cálculo dinámico de precios.

Componentes Implementados

1. Servicios

PriceEngineService (src/modules/pricing/services/price-engine.service.ts)

Motor central de cálculo de precios con las siguientes capacidades:

• calculatePrices(): Calcula precios para un conjunto de líneas de pedido

  • Aplica promociones automáticas activas
  • Soporta múltiples tipos de promoción
  • Gestiona stackability (promociones acumulables)
  • Aplica cupones si se proporciona código

• getActivePromotions(): Obtiene promociones activas para sucursal/canal

• applyCoupon(): Aplica un cupón al resultado de precios

• validateCoupon(): Valida un código de cupón sin aplicarlo

Tipos de Promoción Soportados:

Tipo	Descripción
percentage_discount	Descuento porcentual
fixed_discount	Descuento de monto fijo
buy_x_get_y	Compra X, lleva Y
bundle	Precio especial por paquete
flash_sale	Venta relámpago
quantity_discount	Descuento por volumen
free_shipping	Envío gratis
gift_with_purchase	Regalo con compra

PromotionService (src/modules/pricing/services/promotion.service.ts)

Servicio CRUD para gestión de promociones:

• createPromotion(): Crear promoción con validación de código único
• updatePromotion(): Actualizar promoción (solo en estado draft/scheduled)
• listPromotions(): Listar con filtros paginados
• activatePromotion(): Activar promoción
• pausePromotion(): Pausar promoción activa
• endPromotion(): Finalizar promoción
• cancelPromotion(): Cancelar promoción
• addProducts(): Agregar productos a promoción
• removeProduct(): Remover producto de promoción
• updatePromotionStatuses(): Actualizar estados automáticamente según fechas

Flujo de Estados:

draft → scheduled → active → ended
                  ↓
                paused
                  ↓
              cancelled

CouponService (src/modules/pricing/services/coupon.service.ts)

Servicio completo para gestión de cupones:

• createCoupon(): Crear cupón individual
• generateBulkCoupons(): Generar cupones en lote (hasta 1000)
• updateCoupon(): Actualizar cupón
• activateCoupon(): Activar cupón
• deactivateCoupon(): Desactivar cupón
• redeemCoupon(): Canjear cupón con validación completa
• reverseRedemption(): Revertir un canje (devolución)
• getRedemptionHistory(): Historial de canjes paginado
• getCouponStats(): Estadísticas del cupón

Tipos de Cupón:

• percentage: Descuento porcentual
• fixed_amount: Monto fijo
• free_shipping: Envío gratis
• free_product: Producto gratis

2. Validación Zod (src/modules/pricing/validation/pricing.schema.ts)

Schemas completos para:

Promociones:

• createPromotionSchema: Creación con todas las opciones
• updatePromotionSchema: Actualización parcial
• addPromotionProductsSchema: Agregar productos
• listPromotionsQuerySchema: Filtros de listado

Cupones:

• createCouponSchema: Creación con opciones completas
• updateCouponSchema: Actualización parcial
• generateBulkCouponsSchema: Generación en lote
• redeemCouponSchema: Canje de cupón
• validateCouponSchema: Validación de código
• reverseRedemptionSchema: Reversión de canje
• listCouponsQuerySchema: Filtros de listado

Motor de Precios:

• calculatePricesSchema: Entrada para cálculo
• lineItemSchema: Línea de producto

3. Controladores (src/modules/pricing/controllers/pricing.controller.ts)

Endpoints del Motor de Precios (3):

Método	Ruta	Descripción
POST	/api/pricing/calculate	Calcular precios
POST	/api/pricing/validate-coupon	Validar cupón
GET	/api/pricing/active-promotions	Promociones activas

Endpoints de Promociones (11):

Método	Ruta	Descripción
GET	/api/pricing/promotions	Listar promociones
GET	/api/pricing/promotions/:id	Obtener promoción
POST	/api/pricing/promotions	Crear promoción
PUT	/api/pricing/promotions/:id	Actualizar promoción
POST	/api/pricing/promotions/:id/activate	Activar
POST	/api/pricing/promotions/:id/pause	Pausar
POST	/api/pricing/promotions/:id/end	Finalizar
POST	/api/pricing/promotions/:id/cancel	Cancelar
POST	/api/pricing/promotions/:id/products	Agregar productos
DELETE	/api/pricing/promotions/:id/products/:productId	Remover producto
DELETE	/api/pricing/promotions/:id	Eliminar (soft)

Endpoints de Cupones (14):

Método	Ruta	Descripción
GET	/api/pricing/coupons	Listar cupones
GET	/api/pricing/coupons/:id	Obtener cupón
GET	/api/pricing/coupons/code/:code	Obtener por código
POST	/api/pricing/coupons	Crear cupón
POST	/api/pricing/coupons/bulk	Generar lote
PUT	/api/pricing/coupons/:id	Actualizar cupón
POST	/api/pricing/coupons/:id/activate	Activar
POST	/api/pricing/coupons/:id/deactivate	Desactivar
POST	/api/pricing/coupons/:id/redeem	Canjear por ID
POST	/api/pricing/coupons/redeem	Canjear por código
POST	/api/pricing/coupons/redemptions/:id/reverse	Revertir canje
GET	/api/pricing/coupons/:id/redemptions	Historial canjes
GET	/api/pricing/coupons/:id/stats	Estadísticas
DELETE	/api/pricing/coupons/:id	Eliminar (soft)

Total: 28 endpoints

4. Rutas (src/modules/pricing/routes/pricing.routes.ts)

Configuración de rutas con:

• Autenticación JWT requerida
• Middleware de sucursal donde aplica
• Validación Zod de entrada
• Control de permisos granular

Permisos Requeridos:

• pricing:calculate, pricing:validate, pricing:view
• promotions:view, promotions:create, promotions:update, promotions:activate, promotions:delete
• coupons:view, coupons:create, coupons:update, coupons:activate, coupons:redeem, coupons:reverse, coupons:delete

Características Destacadas

Restricciones de Promociones

• Por fechas (inicio/fin)
• Por días de la semana
• Por horarios específicos
• Por monto mínimo de orden
• Por cantidad mínima de productos
• Por categorías incluidas/excluidas
• Por productos excluidos
• Por sucursales específicas
• Por niveles de cliente
• Solo nuevos clientes
• Solo miembros de lealtad

Stackability (Acumulabilidad)

• Promociones pueden ser acumulables o exclusivas
• Lista de promociones con las que puede combinarse
• Prioridad numérica para resolver conflictos

Tracking de Cupones

• Límite de usos totales
• Límite de usos por cliente
• Tracking de canjes con orden y canal
• Posibilidad de reversión con razón

Estructura de Archivos

src/modules/pricing/
├── controllers/
│   ├── index.ts
│   └── pricing.controller.ts
├── entities/
│   ├── index.ts
│   ├── promotion.entity.ts
│   ├── promotion-product.entity.ts
│   ├── coupon.entity.ts
│   └── coupon-redemption.entity.ts
├── routes/
│   ├── index.ts
│   └── pricing.routes.ts
├── services/
│   ├── index.ts
│   ├── price-engine.service.ts
│   ├── promotion.service.ts
│   └── coupon.service.ts
├── validation/
│   ├── index.ts
│   └── pricing.schema.ts
└── index.ts

Dependencias

• TypeORM 0.3.x
• Zod para validación
• Express para routing
• Entidades existentes: Promotion, Coupon, PromotionProduct, CouponRedemption

Próximos Pasos

El Sprint 5 cubrirá CFDI/Facturación según el roadmap:

• Integración con PAC para timbrado
• Generación de XML CFDI 4.0
• Cancelación de facturas
• Notas de crédito