Ayuda

ToyGo es una aplicación Flutter que sigue Clean Architecture con BLoC para gestión de estado y Provider para inyección de dependencias.

┌─────────────────────────────────────┐
│           UI (Pages/Widgets)        │
│  modules/{feature}/view/            │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│          BLoC (State Management)    │
│  modules/{feature}/bloc/            │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│        Repositories                 │
│  repositories/{feature}/            │
│  Lógica de negocio + mapeo DTO→Model│
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│       API Services (Dio)            │
│  services/api/                      │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│        Backend REST API             │
└─────────────────────────────────────┘

Repositorios principales

Integraciones externas

• Stripe Connect — Onboarding de vendedores, pagos, ganancias
• Correos — Envíos, etiquetas, tracking, recogidas
• Firebase — Analytics, notificaciones push (FCM)
• Cloudflare R2 — Almacenamiento de imágenes

Idiomas soportados

Español (ES), Inglés (EN), Catalán (CA), Portugués (PT)

Métodos de login

Flujo de login (email)

LoginPage
  ├── Usuario introduce email + contraseña
  ├── POST /auth/login { email, password }
  ├── Respuesta: { accessToken, refreshToken, user }
  ├── Guarda tokens en LocalStorage
  ├── Registra device token para push notifications
  └── Navega a MainPage (home)

Login social (Google / Apple / Facebook)

LoginPage
  ├── SDK nativo abre flujo OAuth
  ├── Obtiene token del provider
  ├── POST /auth/{provider} { token, platform, deviceId }
  ├── Si usuario no existe → crea cuenta automáticamente
  ├── Respuesta: { accessToken, refreshToken, user }
  └── Navega a MainPage

Gestión de sesión

Token expirado (401)
  → POST /api/refresh-token { refreshToken }
  → Recibe nuevo accessToken + refreshToken
  → Reintenta request original

Tipos de producto

Estados físicos

• Nuevo — Artículo sin usar
• Buen estado — Usado pero en buenas condiciones
• Usado — Con marcas de uso visibles

Crear un producto

Botón "+" → ProductFormPage
  ├── Imágenes (upload via MediaApiService)
  ├── Título, Descripción
  ├── Categoría (ID numérico)
  ├── Estado físico (nuevo/buenEstado/usado)
  ├── Tipo (trueque/venta/donación)
  ├── Precio (solo si tipo == venta)
  ├── Tags opcionales
  ├── Wishlist (qué quiere a cambio, solo trueque)
  └── POST /products { title, description, categoryId, ... }

Buscar y filtrar

Los usuarios pueden filtrar por tipo, categoría, estado y búsqueda por texto con scroll infinito y paginación.

Estados del trueque

draft → proposed → countered ↔ accepted →
  agreementSigned → paymentPending → paid →
  shippingReady → completed

En cualquier punto: → rejected / canceled

Flujo paso a paso

ProductDetailPage → "Proponer intercambio"
  ├── Muestra el producto target
  ├── Selecciona productos a ofrecer
  ├── Nota opcional
  └── POST /trades { targetProductId, offeredProductIds[] }

POST /trades/{id}/checkout → { checkoutUrl, sessionId }
  ├── WebView con Stripe Checkout
  ├── Tasa de gestión + coste de envío ida+vuelta
  └── Pago confirmado → estado: paid

Estados de una orden

pending → paymentPending → paid → shipping → completed
                                                  ↓
                                               cancelled

Flujo de compra

1. Crear orden → POST /orders { productId, type, buyerAddressId }
2. Preview del checkout → GET /orders/{id}/estimate
   ├── productPriceCents (precio del producto)
   ├── shippingCostCents (envío Correos)
   ├── platformFeeCents (comisión plataforma)
   └── totalAmountCents (total)
3. Pago Stripe → POST /orders/{id}/checkout → WebView
4. Envío Correos → POST /orders/{id}/shipment → etiqueta + recogida
5. Completado → producto entregado

Comprador → Stripe Checkout (WebView) → Plataforma (comisión) → Vendedor

Onboarding de vendedor

Antes de recibir pagos, el vendedor debe completar el onboarding de Stripe Connect (KYC):

1. POST /stripe/connect/account → Crea cuenta Connect
2. POST /stripe/connect/onboarding → URL de onboarding
3. WebView donde completa datos KYC
4. chargesEnabled: true → puede recibir pagos

Ganancias del vendedor

• GET /stripe/connect/balance — Ver balance disponible y pendiente
• GET /stripe/connect/transactions — Historial de transacciones
• POST /stripe/connect/login — Acceso al dashboard de Stripe

Sistema de mensajería 1:1 entre usuarios. Las conversaciones se crean desde el detalle de un producto.

ProductDetailPage → "Contactar vendedor"
  ├── POST /messages/conversations { productId, otherUserId }
  └── Navega a ChatPage

ChatPage
  ├── Mensajes en tiempo real (polling)
  ├── Enviar: POST /messages/conversations/{id}/messages
  ├── Marcar leído: POST /messages/conversations/{id}/read
  └── Scroll infinito para mensajes antiguos

Integración completa con la API de Correos para gestionar envíos de órdenes y trueques.

Proceso de envío

1. Prerregistro → Se crea el envío en Correos
2. Etiqueta → Se genera el PDF con la etiqueta
3. Recogida → Se solicita la recogida a domicilio
4. Tracking → Seguimiento del paquete

Estados del envío

Perfil del usuario

Desde su perfil, el usuario puede acceder a:

• Mi inventario — productos publicados
• Mis trueques — inbox/outbox de intercambios
• Mis compras / Mis ventas
• Favoritos
• Mis direcciones
• Configuración de pago (Stripe)
• Ajustes (idioma, notificaciones, contraseña, eliminar cuenta)

Reportes / Denuncias

Los usuarios pueden reportar productos inapropiados o usuarios fraudulentos. Los reportes llegan a la sección Reportes del panel de administración para su revisión.

Notificaciones push vía Firebase Cloud Messaging (FCM). Se envían notificaciones para:

• Trueques — Nueva propuesta, contrapropuesta, aceptación, rechazo, pago, envío
• Órdenes — Nuevo pedido, pago confirmado, envío, entrega
• Mensajes — Nuevo mensaje en una conversación

El panel de administración de ToyGo está construido con Astro + React + Tailwind CSS. Permite gestionar todos los aspectos de la plataforma desde un único lugar.

Stack tecnológico

• Astro 5 — Framework web con SSR
• React 19 — Componentes interactivos
• Tailwind CSS 4 — Estilos
• React Query — Fetch y cache de datos
• Axios — Cliente HTTP
• Recharts — Gráficos del dashboard
• Lucide React — Iconos

Autenticación

Todas las páginas están protegidas con un guard de autenticación. Se requiere login con credenciales de administrador. La sesión usa JWT enviado como cookie.

La página principal muestra un resumen general de la plataforma:

• Estadísticas rápidas — Total de usuarios, productos activos, intercambios completados, transacciones pendientes
• Actividad reciente — Tabla con las últimas acciones en la plataforma
• Acciones rápidas — Accesos directos a las secciones más usadas

Desde la sección Usuarios puedes gestionar todas las cuentas registradas en la plataforma.

Funcionalidades

• Listar todos los usuarios con búsqueda y paginación
• Ver detalle de cada usuario (perfil, productos, actividad)
• Editar datos del usuario
• Desactivar o eliminar cuentas
• Ver el estado de verificación (email, Stripe)

Gestiona todos los productos publicados en la plataforma.

Funcionalidades

• Listar productos con filtros por tipo, categoría y estado
• Ver detalle completo (imágenes, descripción, propietario)
• Validar o rechazar productos pendientes
• Eliminar productos que infrinjan las normas
• Ver estadísticas: visualizaciones, favoritos

Gestión del catálogo de categorías de productos. Las categorías usan un ID numérico interno.

• Crear, editar y eliminar categorías
• Activar o desactivar categorías
• Las categorías se asignan a productos por categoryId

Supervisa todos los intercambios entre usuarios de la plataforma.

• Listar intercambios con filtros por estado
• Ver detalle completo: productos, usuarios, timeline de eventos
• Ver el estado del pago y envío
• Intervenir en caso de disputas o problemas

Gestiona todas las transacciones de compra-venta y donaciones.

• Listar órdenes con filtros por tipo y estado
• Ver desglose de costes (producto + envío + comisión)
• Verificar estado de pago en Stripe
• Verificar estado de envío en Correos
• Gestionar cancelaciones y reembolsos

Acceso a las conversaciones de la plataforma para moderación y soporte.

• Listar todas las conversaciones
• Ver mensajes dentro de cada conversación
• Identificar conversaciones con contenido reportado

Gestiona las direcciones registradas por los usuarios.

• Listar todas las direcciones
• Ver a qué usuario pertenece cada dirección
• Verificar datos para envíos (calle, ciudad, CP, provincia)

Revisa y gestiona las denuncias realizadas por los usuarios.

• Listar reportes pendientes y resueltos
• Ver detalle: tipo de reporte, motivo, descripción
• Ver el producto o usuario reportado
• Tomar acciones: advertir, desactivar producto, suspender usuario

Vista general de las finanzas de la plataforma.

• Resumen de ingresos por comisiones y tasas de gestión
• Gráficos de evolución de ingresos
• Desglose por tipo de transacción (trueques vs órdenes)
• Historial de transacciones

Configura las tarifas y comisiones que cobra la plataforma.

• Tasa de gestión — Comisión fija o porcentual por trueque
• Comisión de plataforma — Porcentaje sobre el precio de venta
• Costes de envío — Calculados dinámicamente según zonas de Correos

Configura las zonas de envío y sus tarifas asociadas para la integración con Correos.

• Definir zonas geográficas (peninsular, insular, etc.)
• Asignar tarifas de envío por zona
• Configurar tarifas de ida y vuelta para trueques
• Activar o desactivar zonas