Sistema de Monedas - ThreeTrackr

Resumen

El sistema de monedas de ThreeTrackr permite manejar múltiples monedas de manera unificada, con conversión automática y formateo inteligente. El sistema está diseñado para ser escalable y fácil de mantener.

Arquitectura

Backend (Almacenamiento)

  • Principio Los precios se almacenan en su moneda original
  • Ejemplo Órdenes de Shopify en USD se guardan en USD, órdenes locales en COP se guardan en COP
  • Base de datos Campo currency en cada entidad que maneja precios

Frontend (Visualización)

  • Principio Conversión y formateo centralizado en el componente CurrencyDisplay
  • Configuración Cada proyecto tiene una moneda configurada (projectCurrency)
  • Comportamiento
    • Si la moneda original = moneda del proyecto entonces Solo formateo
    • Si la moneda original != moneda del proyecto entonces Conversión + formateo

Componente Principal: CurrencyDisplay

Ubicación

packages/ui/src/components/shared/currency.tsx

Props

El componente CurrencyDisplay acepta las siguientes propiedades:

  • value - Valor numérico del precio
  • sourceCurrency - Moneda del precio original
  • targetCurrency - Moneda de destino (moneda de la app)
  • exchangeRate - Tasa de cambio opcional
  • showDecimals - Mostrar decimales
  • className - Clases CSS adicionales
  • showCurrencySymbol - Mostrar símbolo de moneda
  • size - Tamaño del texto (xs, sm, md, lg, xl)

Uso Básico

Para mostrar un precio en la moneda del proyecto:

  • Importa el componente desde @packages/ui/src/components/shared/currency
  • Pasa el valor, sourceCurrency y targetCurrency
  • El componente manejará la conversión automáticamente

Monedas Soportadas

Principales

  • USD - Dólar estadounidense - Moneda principal para comercio internacional
  • EUR - Euro - Para mercados europeos
  • COP - Peso colombiano - Moneda local para mercado colombiano

Regionales

  • MXN - Peso mexicano - Para mercado mexicano
  • BRL - Real brasileño - Para mercado brasileño
  • ARS - Peso argentino - Para mercado argentino

Tasas de Cambio

Tasas Fijas (Actuales)

  • USD: 1 (base)
  • EUR: 1.08
  • COP: 4200
  • MXN: 18.5
  • BRL: 5.2
  • ARS: 850

Nota Las tasas de cambio son fijas por simplicidad. En el futuro se implementará integración con APIs de cambio en tiempo real.

Ejemplos de Uso

Ejemplo 1: Orden de Shopify en USD

Cuando importas una orden de Shopify en USD a un proyecto configurado en COP, el componente automáticamente convertirá el precio de USD a COP usando la tasa de cambio configurada.

Ejemplo 2: Producto local en COP

Para productos creados localmente en COP, no se realizará conversión ya que la moneda original coincide con la moneda del proyecto.

Ejemplo 3: Múltiples monedas

El sistema puede manejar listas de órdenes con diferentes monedas, convirtiendo cada una a la moneda del proyecto para mostrar un total unificado.

Configuración

1. Configurar Moneda del Proyecto

En la configuración del proyecto, establece la moneda principal que se usará para todas las conversiones y visualizaciones.

2. Usar en Componentes

En cualquier componente que muestre precios, importa CurrencyDisplay y úsalo pasando el valor, sourceCurrency y targetCurrency. El componente manejará automáticamente la conversión y formateo.

Consideraciones Importantes

Almacenamiento Siempre almacena precios en su moneda original. La conversión se hace solo en la visualización.

Performance Las conversiones son cálculos simples y no afectan el rendimiento significativamente.

Precisión Los decimales se manejan según las convenciones de cada moneda (USD: 2 decimales, COP: 0 decimales).

¿Necesitas más detalles? Explora los ejemplos detallados o la guía de migración.