MEMORIA FUNCIONAL — ShopifySync

Documento generado a partir del código real del proyecto (code/frontend/ React SPA + code/backend/ FastAPI). Fecha: 2026-08-05 · Live: https://shopify-sync.theboomer.dev

1. Introducción

ShopifySync es un SaaS que sincroniza productos entre tiendas Shopify y Google Sheets en ambas direcciones. El usuario conecta sus tiendas Shopify (dominio + access token) y sus hojas de cálculo de Google (spreadsheet ID + tokens), configura el mapeo de columnas (qué columna de la hoja corresponde a qué campo de Shopify) y ejecuta sincronizaciones manuales, con planes de pago vía Stripe (Free / Pro / Pro API).

Arquitectura real

Stack frontend real: App.tsx monta QueryClientProvider (react-query) + BrowserRouter + Toaster (sonner). La autenticación se guarda en Zustand con persist bajo la clave shopify-sync-auth. El API client (lib/api.ts) apunta a VITE_API_URL (default http://localhost:9100) y añade Authorization: Bearer <token>.

Nota: el backend eliminó los endpoints OAuth (# OAuth endpoints removed - using direct token input instead): el usuario pega los tokens de Google/Shopify directamente en los formularios.

2. Tipos de usuario

3. Funcionalidades

F3.1 — Autenticación (Login / Registro) — pages/Login.tsx

• Descripción: pantalla única con modo login/registro alternable.
• Flujo: 1. Por defecto modo Sign In (solo email). Toggle Need an account? Sign up muestra además el campo Name. 2. login(email) → POST /auth/login o register(email, name) → POST /auth/register. 3. Guarda {user, access_token} en el store Zustand (setAuth) → navigate("/"). 4. Si falla: muestra el mensaje del error (ApiError.detail o "Something went wrong") en un panel rojo.
• UI: email (type=email, required), name (required solo en registro), botón negro Sign In / Create Account con spinner mientras loading.
• Validaciones: HTML5 required en los campos; deshabilitado del botón mientras carga; error visible en banner rojo.

F3.2 — Layout de dashboard con guard de auth — components/DashboardLayout.tsx

• Descripción: shell de la app autenticada: sidebar oscura + contenido.
• Flujo: si !isAuthenticated → navigate("/login") y no renderiza nada. Si autenticado → sidebar con:
• Logo/título ShopifySync.
• Nav: Dashboard (/), Stores (/stores), Sheets (/sheets), Mapping (/mapping), Settings (/settings); el ítem activo se marca (bg-slate-800 text-white).
• Bloque de usuario: nombre + email, botón Logout (clearAuth() → /login).
• Contenido: <Outlet /> dentro de max-w-6xl mx-auto, fondo bg-slate-50.

F3.3 — Dashboard / Home — pages/Home.tsx

• Descripción: vista principal con estadísticas y acciones rápidas.
• Carga: Promise.all([getStores(), getSheets()]) al montar; spinner centrado mientras carga.
• Tarjetas de stats (grid 3 cols):
• Connected Stores — stores.length (icono azul).
• Connected Sheets — sheets.length (icono verde).
• Products Synced — lastSync?.products_synced || 0 (icono púrpura).
• Quick Actions:
• Si no hay tiendas u hojas: mensaje Connect at least one store and one sheet to start syncing. + enlaces Add Store → (/stores) y Add Sheet → (/sheets).
• Si hay: botón Sync Now (spinner mientras corre) + texto {stores[0].shopify_domain} → {sheets[0].spreadsheet_name}.
• handleSync → runSync(stores[0].id, sheets[0].id, "shopify_to_sheet"); resultado guardado en lastSync.
• Tras sincronizar: banner verde Synced {N} products successfully.
• Connected Services: lista de tiendas (dominio) y hojas (nombre) conectadas; si no hay ninguna: No services connected yet.
• Reglas reales del código: la sincronización rápida usa siempre la primera tienda y la primera hoja y dirección fija shopify_to_sheet.

F3.4 — Stores (tiendas Shopify) — pages/Stores.tsx

• Descripción: conexión y gestión de tiendas Shopify.
• Formulario "Add New Store":
• Shopify Domain (text, placeholder mystore.myshopify.com, required).
• Access Token (password, placeholder shpat_..., required).
• Botón + Add Store → createStore(domain, token) → POST /sync/store; limpia campos y recarga la lista.
• Lista "Connected Stores (N)":
• Cada tienda: dominio + shopify_location_id || "No location set".
• Botón papelera → confirm("Delete this store?") → deleteStore(id) → DELETE /sync/stores/{id}; spinner en el ítem borrado.
• Estados: loading (spinner central), empty (No stores connected), error (console.error, sin UI de error visible).

F3.5 — Sheets (hojas de Google) — pages/Sheets.tsx

• Descripción: conexión y gestión de Google Sheets.
• Formulario "Add New Sheet":
• Spreadsheet ID (text, placeholder 1abc..., required).
• Spreadsheet Name (text, placeholder My Inventory, required).
• Sheet Name (text, default Sheet1).
• Google Access Token (password, placeholder ya29..., required).
• Google Refresh Token (password, placeholder 1//..., required).
• Botón + Add Sheet → createSheet(...) → POST /sync/sheet; limpia campos y recarga.
• Lista "Connected Sheets (N):" cada hoja muestra spreadsheet_name + sheet_name • spreadsheet_id.slice(0,15)...; borrado con confirm("Delete this sheet?") → DELETE /sync/sheets/{id}.

F3.6 — Mapping de columnas — pages/Mapping.tsx

• Descripción: configuración del mapeo columna-de-hoja ↔ campo-de-Shopify y dirección de la sincronización.
• Lista de configuraciones (SyncConfigurations): botón + Add Configuration; cada config muestra storeName, sheetName → Shopify|Sheet según dirección; acciones Edit y papelera (delete con confirm).
• Modal Create/Edit (overlay bg-black/50, card max-w-2xl, scrollable):
• Shopify Store (input texto, placeholder mystore.myshopify.com).
• Google Sheet (input texto, placeholder Inventory).
• Sync Direction (select): Sheet → Shopify (sheet_to_shopify) / Shopify → Sheet (shopify_to_sheet).
• Column Mapping: filas [columna de la hoja] → [campo Shopify ▾] con botón + Add Mapping y papelera por fila.
  • Campo hoja: input texto con datalist de sugerencias: SKU, Product, Stock, Price, Barcode, Weight (kg), Category, Active.
  • Campo Shopify: select con SKU, Product Title, Price, Inventory Quantity, Barcode, Weight, Grams, Requires Shipping, Taxable (sku, title, price, inventory_quantity, barcode, weight, grams, requires_shipping, taxable).
• Acciones: Cancel / Save (spinner mientras guarda).
• Save: si la config tiene id → PATCH /sync/config/{id} (updateSyncConfig con direction+mapping); si no → POST /sync/config (createSyncConfig con storeId/sheetId). Tras guardar recarga y cierra el modal.
• Datos locales vs API: la UI trabaja con nombres (storeName, sheetName) pero la API espera store_id/sheet_id; al cargar se mapean los IDs a nombres (mostrando el ID como nombre) y al crear una config nueva se envían "" como store/sheet id (observación de comportamiento real).

F3.7 — Settings (cuenta y billing) — pages/Settings.tsx

• Descripción: plan actual, planes disponibles y datos de cuenta.
• Current Plan: nombre del plan (capitalizado, user?.plan || "free") + Billing active si hay stripe_customer_id o Free tier; si el plan no es free → botón Manage Billing → → createPortal() (POST /billing/portal) → redirige a result.url.
• Available Plans (grid 3 cols):
• Free — $0 — 1 store, 1 sheet, Manual sync.
• Pro — $7/mo — 5 stores, 5 sheets, Auto sync, Priority support.
• Pro API — $12/mo — Unlimited stores, Unlimited sheets, API access, Priority support.
• Botón Upgrade → createCheckout(planId, "monthly") (POST /billing/checkout) → window.location.href = result.url. El plan actual muestra botón Current deshabilitado.
• Account Information: Name y Email (read-only, del store de auth).

F3.8 — Sincronización (motor backend) — app/services/sync_engine.py + app/api/sync.py

• POST /sync/run {store_id, sheet_id, direction} → {status, store_id, sheet_id, direction, products_synced, errors}.
• Dirección shopify_to_sheet: paginación de productos Shopify (50 por página con cursor) → consulta inventory levels de todos los inventory_item_id → escribe en la hoja desde fila 2, columna A, columnas SKU y Stock (sheet_name="Sheet1").
• Dirección sheet_to_shopify: lee productos de la hoja (get_products_data), descarga productos actuales de Shopify (250), construye mapa por SKU y actualiza stock en Shopify.
• Cada dirección devuelve products_synced y lista de errors (si algo falla, se captura y se reporta sin romper la respuesta).

F3.9 — API de configuración de sync — app/api/sync_config.py

• GET /sync/config → lista de configs {id, store_id, sheet_id, direction, mapping: [{sheet_column, shopify_field}]}.
• POST /sync/config → crea (store_id, sheet_id, direction, mapping).
• PATCH /sync/config/{id} → actualiza direction y/o mapping.
• DELETE /sync/config/{id} → elimina.

F3.10 — Billing Stripe — app/api/billing.py + app/services/stripe.py

• POST /billing/checkout {plan, interval} → {url, session_id} (redirección del frontend al checkout de Stripe).
• POST /billing/portal → {url, session_id} (customer portal para gestionar la suscripción).
• Planes en backend alineados con la UI: free / pro / pro_api (mensual por defecto).

F3.11 — Webhooks y rate limiting (backend)

• Router webhooks (app/api/webhooks.py) registrado en la app.
• app/core/rate_limit.py existe en el núcleo (limitación de peticiones, usada por la API).

4. Pantallas (wireframes textuales)

P1 — Login (/login)

┌────────────────────────────────────────────────────┐
│          (centrado vertical/horizontal, bg-slate-50)│
│  ┌──────────────────────────────────────────────┐  │
│  │  [🛍 icono]  ShopifySync                     │  │
│  │                                              │  │
│  │  [banner rojo si error]                      │  │
│  │                                              │  │
│  │  Email                                      │  │
│  │  [________________________]                 │  │
│  │  Name  (solo en modo registro)              │  │
│  │  [________________________]                 │  │
│  │                                              │  │
│  │  [     Sign In / Create Account     ] (negro)│  │
│  │                                              │  │
│  │  Need an account? Sign up  (toggle azul)    │  │
│  └──────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────┘

P2 — Dashboard (/)

┌──────────────┬───────────────────────────────────────────┐
│ SIDEBAR      │  Dashboard                                │
│ (slate-900)  │  Manage your Shopify and Google Sheets sync│
│              │                                           │
│ ShopifySync  │  ┌──────────┐ ┌──────────┐ ┌──────────┐   │
│              │  │ [🛍] 2   │ │ [📋] 1   │ │ [📦] 0   │   │
│ ● Dashboard  │  │ Stores   │ │ Sheets   │ │ Synced   │   │
│   Stores     │  └──────────┘ └──────────┘ └──────────┘   │
│   Sheets     │                                           │
│   Mapping    │  Quick Actions                            │
│   Settings   │  [↻ Sync Now]  mistore.myshopify.com → Inv│
│              │  (o: Connect at least one store and one   │
│ ─────────────│     sheet… [Add Store →] [Add Sheet →])   │
│ 👤 Nombre    │  [banner verde: Synced N products ...]    │
│    email     │                                           │
│ [⏻ Logout]  │  Connected Services                       │
│              │  [🛍] mistore.myshopify.com                │
│              │  [📋] My Inventory                        │
└──────────────┴───────────────────────────────────────────┘

P3 — Stores (/stores)

┌──────────────┬───────────────────────────────────────────┐
│ SIDEBAR      │  Stores                                   │
│ (activa:     │  Connect your Shopify stores              │
│  Stores)     │                                           │
│              │  Add New Store                            │
│              │  Shopify Domain  [mystore.myshopify.com]  │
│              │  Access Token   [•••••••• (shpat_...)]    │
│              │  [＋ Add Store]                           │
│              │                                           │
│              │  Connected Stores (2)                     │
│              │  [🛍] mystore.myshopify.com       [🗑]     │
│              │      <location_id> / No location set      │
│              │  (vacío → "No stores connected")          │
└──────────────┴───────────────────────────────────────────┘

P4 — Sheets (/sheets)

┌──────────────┬───────────────────────────────────────────┐
│ SIDEBAR      │  Sheets                                   │
│ (activa:     │  Connect your Google Sheets               │
│  Sheets)     │                                           │
│              │  Add New Sheet                            │
│              │  Spreadsheet ID [1abc...]  Name [My Inv.] │
│              │  Sheet Name    [Sheet1]                   │
│              │  Google Access Token  [•••• (ya29...)]    │
│              │  Google Refresh Token [•••• (1//...)]     │
│              │  [＋ Add Sheet]                           │
│              │                                           │
│              │  Connected Sheets (1)                     │
│              │  [📋] My Inventory                [🗑]     │
│              │      Sheet1 • 1abc12345678901...          │
└──────────────┴───────────────────────────────────────────┘

P5 — Mapping (/mapping)

┌──────────────┬───────────────────────────────────────────┐
│ SIDEBAR      │  Column Mapping                           │
│ (activa:     │  Configure which columns in your Google   │
│  Mapping)    │  Sheet map to Shopify fields              │
│              │                                           │
│              │  Sync Configurations       [＋ Add Config] │
│              │  [⇄] <store_id>            [Edit] [🗑]    │
│              │      <sheet_id> → Shopify                 │
│              │  (vacío → "No sync configurations yet.")  │
│              │                                           │
│              │  ┌ MODAL (overlay) ────────────────────┐  │
│              │  │ Create/Edit Sync Configuration      │  │
│              │  │ Shopify Store [________]  Sheet [__]│  │
│              │  │ Sync Direction [Sheet → Shopify ▾]  │  │
│              │  │ Column Mapping        [+ Add Mapping]│  │
│              │  │ [SKU ▾] → [SKU ▾]              [🗑] │  │
│              │  │ [Stock ▾] → [Inventory Qty ▾] [🗑] │  │
│              │  │                      [Cancel][Save] │  │
│              │  └────────────────────────────────────┘  │
└──────────────┴───────────────────────────────────────────┘

P6 — Settings (/settings)

┌──────────────┬───────────────────────────────────────────┐
│ SIDEBAR      │  Settings                                 │
│ (activa:     │  Manage your account and billing          │
│  Settings)   │                                           │
│              │  Current Plan                             │
│              │  ┌─────────────────────────────────────┐  │
│              │  │ Pro            Billing active       │  │
│              │  │                   [Manage Billing →]│  │
│              │  └─────────────────────────────────────┘  │
│              │                                           │
│              │  Available Plans                          │
│              │  ┌ Free ──────┐ ┌ Pro ───────┐ ┌ Pro API ┐│
│              │  │ $0         │ │ $7/mo      │ │ $12/mo  ││
│              │  │ ✓1 store   │ │ ✓5 stores  │ │ ✓Unlim. ││
│              │  │ ✓1 sheet   │ │ ✓5 sheets  │ │ ✓API    ││
│              │  │ ✓Manual    │ │ ✓Auto sync │ │ ✓Priori ││
│              │  │ [Current]  │ │ [Current]  │ │[Upgrade]││
│              │  └────────────┘ └────────────┘ └─────────┘│
│              │                                           │
│              │  Account Information                      │
│              │  Name   Juan                             │
│              │  Email  juan@example.com                 │
└──────────────┴───────────────────────────────────────────┘

5. Flujos de trabajo

Flujo A — Primer uso (registro → conexión → sync)

1. El visitante accede a / → redirigido a /login (guard del layout).
2. Hace Sign up (email + nombre) o Sign In (email) → token guardado en Zustand persist → vuelve a /.
3. En /stores añade su tienda Shopify (dominio + shpat_...) → POST /sync/store.
4. En /sheets añade su hoja (spreadsheet ID/nombre, sheet name, tokens Google) → POST /sync/sheet.
5. En /mapping crea una configuración (store, sheet, dirección, mapeo de columnas) → POST /sync/config.
6. En el dashboard pulsa Sync Now → POST /sync/run (usa la 1ª tienda y 1ª hoja, shopify_to_sheet) → banner verde con nº de productos sincronizados.
7. Si el plan lo permite (Pro+), puede gestionar billing desde Settings.

Flujo B — Conexión de una tienda

1. Abrir /stores → rellenar Shopify Domain + Access Token (campos required).
2. Pulsar Add Store → POST; en error solo se loguea en consola (sin mensaje UI).
3. La tienda aparece en Connected Stores (N) con su location (o No location set).
4. Eliminación: papelera → confirm("Delete this store?") → DELETE → recarga.

Flujo C — Configurar un mapeo de columnas

1. Abrir /mapping → + Add Configuration.
2. En el modal: escribir store y sheet, elegir dirección (Sheet → Shopify o Shopify → Sheet).
3. Añadir filas de mapeo: columna de la hoja (con sugerencias SKU/Product/Stock/…) → campo Shopify (select SKU/Title/Price/Inventory…).
4. Save → POST (nuevo) o PATCH (existente) → la config aparece en la lista con su dirección.
5. Editar reabre el modal con los datos; borrar pide confirmación.

Flujo D — Sincronización Shopify → Sheet

1. Backend pagina los productos de Shopify (50/cursor) hasta agotar.
2. Recoge todos los inventory_item_id y consulta inventory levels.
3. Construye filas {SKU, Stock} y las escribe en la hoja desde fila 2, columna A.
4. Responde products_synced y errors (si hubo). El dashboard muestra el resultado.

Flujo E — Sincronización Sheet → Shopify

1. Backend lee los productos de la hoja.
2. Obtiene productos actuales de Shopify (250) y construye mapa por SKU.
3. Actualiza stock en Shopify según los valores de la hoja.
4. Devuelve products_synced/errors.

Flujo F — Upgrade de plan

1. /settings → ver plan actual + tarjetas de planes.
2. Upgrade en Pro o Pro API → POST /billing/checkout → redirección a Stripe Checkout.
3. Tras pagar, stripe_customer_id queda en el usuario → Settings muestra Billing active y Manage Billing → (portal).

Flujo G — Cierre de sesión

1. Botón Logout en la sidebar → clearAuth() (borra token/usuario del store persistido) → /login.

6. Reglas de negocio

1. Acceso restringido: toda ruta del dashboard requiere isAuthenticated; si no, redirección a /login.
2. Auth por email (magic/simple): login solo con email; registro con email + nombre; token Bearer almacenado en localStorage (Zustand persist).
3. Límites por plan (según UI de Settings): Free = 1 tienda, 1 hoja, sync manual; Pro = 5 tiendas, 5 hojas, auto sync, soporte prioritario; Pro API = ilimitado, acceso API. (Los límites se muestran en la UI; el enforcement efectivo depende del backend/Stripe.)
4. Conexiones por token directo: no hay OAuth en UI; el usuario pega shopify_access_token y los tokens de Google (access + refresh) en los formularios (los campos se muestran como password).
5. Sync rápido del dashboard: usa stores[0] y sheets[0] con dirección fija shopify_to_sheet; el mapeo avanzado se gestiona en /mapping.
6. Direcciones válidas de sync: sheet_to_shopify (Sheet → Shopify) y shopify_to_sheet (Shopify → Sheet).
7. Formato de la hoja: para sync se espera hoja llamada Sheet1 con columnas SKU y Stock (SKU/Stock a partir de fila 2 en shopify_to_sheet; en sheet_to_shopify se leen los productos de la hoja).
8. Campos mapeables de Shopify: sku, title, price, inventory_quantity, barcode, weight, grams, requires_shipping, taxable.
9. Eliminaciones con confirmación: tiendas, hojas y configuraciones piden confirm() antes de borrar.
10. Billing mensual: checkout y portal usan intervalo monthly; plan por defecto free; stripe_customer_id indica billing activo.
11. Tolerancia a errores de sync: los errores de Shopify/Sheets se capturan y se devuelven en errors (el sync no aborta con excepción).
12. Errores de API: el cliente lanza ApiError(status, detail) con el detail del backend (o "Request failed"); las páginas loguean en consola — solo Login muestra el error en pantalla.
13. Rate limiting y webhooks: la API incluye core/rate_limit.py y un router de webhooks (app/api/webhooks.py).