Product Requirements Document (PRD)¶

Version: 0.1.0 Last Updated: 2026-05-15 Status: Draft - MVP Planning

1. Visión del Producto¶

Objetivo¶

SaaS para agencias de courier latinoamericanas que operan con viajeros y vuelos comerciales.

El sistema gestiona la complejidad de enviar paquetes a través de pasajeros que viajan en vuelos comerciales, permitiendo: - Registro y tracking de paquetes - Asignación a viajeros/maletas - Consolidación en warehouses de destino - Trazabilidad completa del envío

Contexto del Negocio¶

Elemento	Descripción
Courier social/Latina	Agencias que usan viajeros como "mensajeros informales"
Vuelos comerciales	Los paquetes viajan en maletas de pasajeros reales
Multi-leg	Un paquete puede pasar por múltiples vuelos/couriers
Consolidación	Paquetes se agrupan en destino antes de entrega

Funcionalidades Core¶

Envíos físicos: Paquetes, documentos, electrónicos
Scanning y tracking: En warehouses a lo largo de la cadena
Flujo financiero multi-moneda: Operaciones España ↔ Perú
Netting y optimización de caja: Compensación de saldos entre mercados
Facturación y reportes: Documentación y métricas financieras
Multi-tenant configurable: Cada agencia tiene su propia configuración

Alcance MVP¶

Geografía: España ↔ Perú
Agencias: Soporte inicial para 2 agencias (tenants)
Usuarios por agencia: Múltiples admins, couriers y warehouses

2. Reglas de Negocio¶

RB-001: Splitting y Consolidación de Paquetes¶

Regla: Un envío puede dividirse (split) - los paquetes NO siempre viajan juntos. Se consolidan en el warehouse de destino.

Comportamiento: - Un shipment puede tener múltiples packages - Los packages pueden dividirse en grupos (splits) antes del envío - Cada grupo puede viajar en不同的maletas/couriers/vuelos - En el warehouse de destino, todos los paquetes se consolidan para entrega final

Flujo de Split:

Shipment "SHP_001"
    ├── Package "PKG_001" ──┐
    ├── Package "PKG_002" ──┼──► Split A (Vuelo MAD→LIM, Bag "BAG_A")
    └── Package "PKG_003" ──┘

Shipment "SHP_001" (continuación)
    ├── Package "PKG_004" ──────────────────► Split B (Vuelo MAD→LIM, Bag "BAG_B")
    └── Package "PKG_005" ──────────────────► Split C (Vuelo MAD→LIM, Bag "BAG_C")

[DESTINO - Lima Warehouse]
    Bag A + Bag B + Bag C ──► CONSOLIDACIÓN ──► Entrega final

Implicaciones: - Tracking debe mostrar splits parciales y su estado individual - Consolidación es un evento crítico en el workflow (PACKAGE_RECONCILED) - Un shipment puede tener múltiples "partidas" de salida - El receptor recibe todos los paquetes al final (o en entregas parciales si decide)

Estados de Split: | Estado | Descripción | |--------|-------------| | PENDING_SPLIT | Paquetes aún no agrupados | | SPLIT_CREATED | Grupos de envío creados | | IN_TRANSIT | Paquetes en diferentes vuelos | | CONSOLIDATED | Todos los paquetes llegaron al warehouse destino | | PARTIALLY_DELIVERED | Algunos paquetes entregados | | FULLY_DELIVERED | Todos los paquetes entregados |

RB-002: Multi-Tenancy Flexible¶

Regla: Cada tenant puede tener múltiples admins, couriers y warehouses.

Implicaciones: - Jerarquía: Tenant → Admin → Couriers/Warehouses - Aislamiento de datos por tenant (RLS en PostgreSQL) - Configuración independiente de pricing, FX, notificaciones

RB-003: Empresas Inscritas por País¶

Regla: Cada agencia (tenant) opera con una empresa inscrita legalmente en cada país donde tiene operaciones.

Comportamiento: - Un Tenant tiene N Companies (una por país de operación) - Cada Company tiene: CIF/RUC/DNI-NIE, dirección fiscal, moneda local, bancos - Para tenants que inician sin empresa constituida, se usa DNI/NIE como identificador - Los shipments se registran bajo el Tenant (que engloba las Companies) y la Company del país de origen - La Company del país de destino puede intervenir en la entrega

Jerarquía:

Tenant (Agencia)
├── Company España (CIF/DNI-NIE, EUR, banco ES)
├── Company Perú (RUC/DNI-NIE, PEN, banco PE)
├── Company Colombia (NIT/DNI-NIE, COP, banco CO)
└── ...

Implicaciones: - Facturas se emiten desde la Company del país correspondiente - Impuestos (IVA, IGV) se calculan según país de origen - Balances contables por Company/país - Cada país tiene su propia configuración de pricing (FX, fees) - El shipment siempre se asocia al Tenant y a la Company origen para trazabilidad fiscal

RB-004: Sistema de Pagos¶

Regla: El pago del envío se realiza en efectivo y puede hacerse al recoger o al entregar el paquete.

Características del pago: | Aspecto | Descripción | |---------|-------------| | Método | Efectivo | | Timing | Al recoger el paquete O al entregar el paquete | | Moneda | Moneda del país donde se realiza el pago |

Implicaciones: - El sistema debe registrar el estado del pago (PENDING, PAID) - El pricing se calcula en la moneda del país de origen - No hay integración con pasarelas de pago (PayPal, tarjeta, etc.) en MVP

RB-005: Tracking Público¶

Regla: El tracking es público y anónimo - cualquier persona puede consultar el estado de un shipment con solo el número de tracking.

Características del tracking público: | Aspecto | Descripción | |---------|-------------| | Acceso | Anónimo (sin cuenta necesaria) | | Identificador | Número de tracking (QR code) | | Información visible | Estado actual + timeline de eventos previos | | Límite de consultas | Rate limited para evitar ataques DoS | | Disponibilidad | Solo 3 días después de la entrega del paquete |

Implicaciones: - No se requiere registro/login para consultar tracking - El sistema debe sanitizar outputs para evitar info leaks - Después de 3 días post-entrega, el tracking deja de estar disponible

RB-006: Recepción de Paquetes sin Pre-registro¶

Regla: El sistema permite recibir paquetes que no fueron pre-registrados vía web. El Warehouse Operator puede crear el shipment in-situ.

Flujo: 1. Paquete llega al warehouse sin QR registrado 2. Warehouse Operator crea shipment manualmente 3. Se genera QR para el paquete 4. Paquete entra al flujo normal

Implicaciones: - Todo paquete debe tener un shipment y QR para ser trackeado - El warehouse puede recibir paquetes "cold" sin registro previo

RB-007: Consolidación y Notificaciones¶

Regla: El sistema realiza verificación automática de consolidación. Cuando todos los packages de un shipment han llegado al warehouse destino, se notifica automáticamente al cliente.

Flujo de consolidación:

1. Bags llegan al warehouse destino
2. Sistema compara: Packages esperados vs Packages recibidos
3. Si todos llegaron → Notificación automática al cliente
4. Si faltan packages → Espera 24h por posible extravío
5. Después de 24h → Courier decide qué hacer (reenviar, devolver, almacenar)

Notificaciones: | Evento | Notificación | |--------|--------------| | Todos packages llegaron | Cliente recibe notificación de consolidación lista | | Faltan packages (24h) | Courier recibe alerta para decisión | | Decisión tomada | Cliente recibe update con próxima acción |

RB-008: Scheduling de Flights¶

Regla: Los flights pueden ser creados por ambos (Admin y Courier). Las bags se asignan al courier previo al check-in y se permite modificación por incidencias de vuelo.

Flujo: 1. Admin o Courier crea/registra flight 2. Admin asigna bags al courier antes del viaje 3. En warehouse, se confirma asignación de packages a bags 4. Courier realiza check-in en aeropuerto 5. Se obtiene código IATA de la aerolínea 6. Bag se actualiza con airline_tag_code

Modificaciones: - Se permite cambiar courier/vuelo hasta check-in - Se permite cambios por incidencias (retrasos, cancelaciones)

RB-009: Courier No-show¶

Regla: Si un courier no puede viajar, el Admin reasigna manualmente los bags. Esto afecta el rating/estadísticas del courier con la causa registrada.

Impacto en Courier: | Campo | Descripción | |-------|-------------| | flights_completed | No incrementa (penalización) | | no_show_count | Se incrementa | | rating | Puede bajar según historial | | causes | Se registra la causa (enfermedad, emergencia, otro) |

Notificaciones: - Solo se notifica al cliente si el envío se cancela - Admin debe tomar decisión de reasignación o cancelación

RB-010: Confirmación de Entrega¶

Regla: La entrega se confirma con acknowledgment verbal del receptor (o persona autorizada). Se captura foto como evidencia.

Proceso: 1. Courier/Warehouse entrega paquete 2. Receptor confirma verbalmente 3. Se captura foto del momento (evidencia) 4. PackageEvent DELIVERED se registra

Autorización: - Receptor registrado en shipment - O cualquier persona con autorización del receptor (delegación)

RB-011: Paquetes No Recogidos¶

Regla: Los paquetes tienen tiempo de almacenamiento configurable por warehouse. El Admin decide costos y destino final. Se notifica al remitente automáticamente tras X días (configurable).

Configuración por Warehouse: | Variable | Descripción | |----------|-------------| | storage_days | Días máximos de almacenamiento | | storage_fee_per_day | Costo diario (0 = gratis) | | notification_days | Días antes de notificar al remitente | | default_action | Devolver/Destruir/Almacenar indefinidamente |

Acciones posibles: - Devolver al remitente (costo adicional) - Destruir (para items perishables) - Almacenar indefinidamente (costo acumulado) - Admin decide caso por caso

RB-012: KYC y Monitoreo de Clientes¶

Regla: No se requiere verificación KYC para clientes. Sin límites de uso, pero existe monitoreo activo de actividad sospechosa.

Política: | Aspecto | Descripción | |---------|-------------| | KYC Required | No | | Límite shipments | Sin límite | | Límite valor | Sin límite | | Monitoreo | Activo para detectar patrones sospechosos |

Alertas de monitoreo: - Volumen anómalo de shipments - Patrones de uso inusuales - Dirección de entrega inconsistente

RB-013: Aduanas y Documentación¶

Regla: El sistema no maneja información aduanera en MVP. Solo se genera el QR en cada paquete como identificación. Las incidencias de retención se reportan manualmente.

MVP incluye: - QR único por package - tracking en tiempo real

Futuro (post-MVP): - Registro básico de contenido - Declaración jurada - HS codes para categorías

RB-014: Setup de Nuevo Tenant¶

Regla: Un nuevo tenant requiere configuración mínima: Companies + Pricing + 1 Warehouse + 1 User. Se puede empezar sin Companies (agregar después).

Setup mínimo: | Componente | Requerido | Opcional | |------------|-----------|----------| | Tenant | ✅ | - | | Companies | Opcional | ✅ Agregar después | | Pricing Rules | ✅ | - | | Warehouse | ✅ Mínimo 1 | ✅ Más adelante | | Users | ✅ Mínimo 1 | ✅ Más adelante |

No incluye datos demo - el tenant comienza vacío.

3. Modelo de Datos¶

Jerarquía de Entidades¶

Tenant (Agencia)
├── Companies                  # Empresas inscritas por país
│     ├── Company España       # CIF/DNI-NIE, EUR, banco ES
│     ├── Company Perú        # RUC/DNI-NIE, PEN, banco PE
│     └── Company Colombia    # NIT/DNI-NIE, COP, banco CO
├── Users                     # Usuarios del tenant
│     └── Roles: Admin, Warehouse Operator
├── Couriers                  # Viajeros que llevan paquetes
│     ├── Flights             # Vuelos asignados al courier
│     └── Bags                # Maletas que lleva el courier
├── Shipments (1:N)           # 1 envío puede tener N paquetes
│     ├── Packages (N:1)      # N paquetes pertenecen a 1 envío
│     │     ├── PackageEvents # Histórico de eventos (scan, status)
│     │     ├── BagAssignments (N:N)  # Relación packages a bags
│     │     └── Documents     # Documentos asociados (fotos, PDFs)
│     └── Contacts           # Remitente y destinatario
├── Warehouses               # Almacenes del tenant
├── PricingRules            # Reglas de pricing por tenant
└── TenantConfig            # Configuración del sistema

Descripción de Entidades¶

Entidad	Descripción	Relaciones
Tenant	Agencia courier	Raíz del modelo, contiene Companies, Users, Couriers, Shipments
Companies	Empresas inscritas por país	Cada país tiene Company (CIF/DNI-NIE, RUC/NIT)
Users	Usuarios administrativos	Roles: Admin, Warehouse Operator (no Courier)
Couriers	Viajeros que llevan paquetes	Tiene User link, pasaporte, estadísticas, bags asignados
Shipments	Envío completo (grupo de paquetes)	1:N con Packages, pertenece a Tenant + Company origen
Packages	Paquetes individuales de un envío	N:1 con Shipment, N:N con Bags, tienen QR único
BagAssignments	Relación packages a bags	Tabla intermedia N:N
Bags	Maletas que llevan los couriers	Código IATA post check-in, status, flight info
PackageEvents	Eventos de tracking	Historial de estados del paquete
Documents	Documentos adjuntos	Fotos del paquete, facturas, guías
Contacts	Remitente y destinatario	Sender y Receiver de cada Shipment
Warehouses	Almacenes	Cada Tenant puede tener múltiples warehouses
PricingRules	Tarifas por tenant	Fee base, FX margin, discounts
TenantConfig	Configuración del sistema	Monedas, umbrales, integraciones

PricingRules - Modelo de Precios por Tenant¶

Cada agencia (tenant) tiene reglas de pricing completamente configurables según sus necesidades.

Características del Pricing¶

Aspecto	Descripción
Volumen variable	Cada tenant tiene volumen MUY variable (días altos/bajos)
Costos operativos reales	Cada envío tiene costos: vuelos, personal, riesgo
Reglas personalizadas	Cada agencia define sus propias reglas

Variables de Pricing¶

Variable	Descripción	Ejemplo
KG_RATE	Tarifa por kilogramo	€/kg según categoría
BASE_FEE	Tarifa base por envío	Costo fijo mínimo
FX_MARGIN	Margen sobre tipo de cambio	% sobre EUR/PEN
MIN_CHARGE	Cargo mínimo por envío	Tarifa base si peso bajo
VOLUME_DISCOUNT	Descuento por volumen	% según cantidad mensual
CATEGORY_RULES	Reglas por categoría	% electrónicos, documentos, fragile

Categorías de Paquetes¶

Categoría	Descripción	Reglas ejemplo
Documents	Documentos, papeles	Tarifa mínima, sin peso
General	Ropa, accesorios	Tarifa estándar por kg
Electronics	Equipos, móviles	% adicional por seguro
Fragile	Frágiles, objetos valiosos	% adicional por manejo especial
Hazardous	Materiales especiales	Reglas de regulación

Ejemplo de Configuración por Tenant¶

tenant: "RoundAway Express"
pricing:
  base_fee: 15.00          # EUR
  kg_rate:
    documents: 0.00         # Documentos no se cobran por kg
    general: 8.50           # EUR/kg
    electronics: 12.00      # EUR/kg (con seguro)
    fragile: 15.00          # EUR/kg (manejo especial)
  min_charge: 10.00         # EUR (si peso < 1kg)
  fx_margin: 0.03           # 3% sobre tipo de cambio
  volume_discount:
    - >100_shipments: 0.05  # 5% descuento
    - >500_shipments: 0.10 # 10% descuento

Regla de negocio: El pricing debe ser configurable por tenant sin cambios en código.

Couriers - Viajeros que Llevan Paquetes¶

Los couriers/viajeros son una entidad separada para permitir seguimiento, estadísticas y asignación de maletas.

Atributo	Descripción	Ejemplo
`id`	UUID
`user_id`	FK hacia User (login/auth)
`full_name`	Nombre completo	Juan Pérez
`passport_number`	Número de pasaporte	AA1234567
`nationality`	Nacionalidad	Peruana
`phone`	Teléfono de contacto	+51123456789
`email`	Email de contacto
`flights_completed`	Contador de vuelos	45
`packages_delivered`	Contador de paquetes	234
`rating`	Rating del courier (1-5)	4.8
`status`	ACTIVE, INACTIVE, SUSPENDED	ACTIVE
`home_country`	País de residencia	Perú
`preferred_routes`	Rutas frecuentes	MAD→LIM, LIM→MAD

Asignación de Bags en Warehouse: 1. En el warehouse, al courier se le asignan los packages que viajará 2. Los packages se agrupan en Bags (maletas) 3. Se genera un Bag provisional 4. En el check-in del aeropuerto, se obtiene el código IATA (etiqueta oficial de la aerolínea) 5. El Bag se actualiza con el airline_tag_code

Bags - Maletas con Paquetes¶

Atributo	Descripción	Ejemplo
`id`	UUID
`courier_id`	FK hacia Courier
`flight_id`	FK hacia Flight (asignado)
`warehouse_id`	FK hacia Warehouse (origen)	MAD-WH-01
`status`	OPEN, SEALED, CHECKED_IN, IN_TRANSIT, DELIVERED
`airline_tag_code`	Código IATA post check-in	AMC1234567890
`airline`	Aerolínea	Iberia
`flight_number`	Número de vuelo	IB6251
`estimated_arrival`	Fecha estimada de llegada
`actual_arrival`	Fecha real de llegada
`total_packages`	Número de paquetes en la maleta	12

Relación con Packages: - Un Bag puede contener N Packages (N:N) - Un Package puede estar en N Bags (split shipping) - La tabla BagAssignments registra la relación con timestamps

BagAssignments - Relación Packages-Bags¶

Atributo	Descripción
`id`	UUID
`package_id`	FK hacia Package
`bag_id`	FK hacia Bag
`added_at`	Timestamp de asignación
`added_by`	User que realizó la asignación
`position`	Posición en la maleta (opcional)
`removed`	Boolean (si se removió de la maleta)

Flights - Vuelos Comerciales¶

Atributo	Descripción	Ejemplo
`id`	UUID
`flight_number`	Número de vuelo	IB6251
`airline`	Aerolínea	Iberia
`departure_airport`	Aeropuerto de salida	MAD
`arrival_airport`	Aeropuerto de llegada	LIM
`scheduled_departure`	Hora programada salida
`scheduled_arrival`	Hora programada llegada
`actual_departure`	Hora real de salida
`actual_arrival`	Hora real de llegada
`status`	SCHEDULED, BOARDING, DEPARTED, ARRIVED, CANCELLED
`courier_id`	FK hacia Courier asignado
`max_weight_kg`	Peso máximo permitido	23
`available_weight_kg`	Peso disponible	18.5

PackageEvents - Eventos de Tracking (Unificados)¶

Cada acción en warehouse genera un evento rastreable. Esta es la lista unificada de eventos:

Evento	Descripción	MVP1	Transición típica
`PACKAGE_CREATED`	Paquete registrado en el sistema	✅	Inicio del tracking
`QR_GENERATED`	QR generado para el paquete	✅	Sistema genera código único
`PHOTO_UPLOADED`	Foto de evidencia capturada	✅	Worker captura evidencia
`PACKAGE_SCANNED`	Paquete escaneado en warehouse	⚠️	Post-MVP1: requiere hardware scanner
`PACKAGE_PACKED`	Paquete empaquetado y listo	✅	Preparado para asignación
`ASSIGNED_TO_BAG`	Paquete asignado a maleta	✅	Agrupación para transporte
`BAG_SEALED`	Maleta sellada/ cerrada	✅	Todos los packages agregados
`BAG_CHECKED_IN`	Check-in en aeropuerto (código IATA asignado)	⚠️	Post-MVP1: se obtiene código de aerolínea
`BAG_LOADED`	Maleta cargada en bodega del avión	✅	Courier entrega maleta
`FLIGHT_DEPARTED`	Vuelo ha despegado	✅	Confirmación de salida
`FLIGHT_ARRIVED`	Vuelo ha aterrizado	✅	Confirmación de llegada
`BAG_UNLOADED`	Maleta descargada en destino	✅	Extracción de bodega
`CONSOLIDATED`	Paquetes consolidados en warehouse destino	✅	Reagrupación para entrega
`READY_FOR_PICKUP`	Paquete listo para recojo	✅	Disponible en warehouse destino
`DELIVERED`	Paquete entregado al destinatario	✅	Fin del ciclo
`RETURNED`	Paquete devuelto	✅	Excepción, requiere acción

Nota MVP1: Los eventos marcados con ⚠️ (SCANNED, BAG_CHECKED_IN) requieren hardware específico o integración con aerolíneas que puede implementarse en fases posteriores.

Nota: El estado RETURNED puede aplicarse en cualquier punto del flujo si el paquete no puede continuar su curso normal.

Regla de trazabilidad: Cada PackageEvent debe incluir: - Timestamp del evento - User/Actor que realizó la acción - Ubicación (Warehouse ID) - Evidencia adjunta (foto URL, documento) - Metadata adicional (opcional)

Contacts - Personas (Remitente / Receptor)¶

Tipo	Rol	Descripción
Sender (Remitente)	Quien envía el paquete	Cliente que inicia el envío
Receiver (Destinatario)	Quien recibe el paquete	Cliente final que recibe el envío

Regla de negocio: El remitente y el receptor pueden ser la misma persona (envío a uno mismo).

Flujos de Warehouse¶

Flujo de Entrada (Recepción de Paquete)¶

1. Worker recibe paquete en warehouse
2. Abre Flet app (escaner)
3. Escanea QR del paquete
4. Backend registra evento SCAN
5. Sistema genera etiqueta con QR
6. Printer imprime etiqueta QR
7. Captura foto del paquete (evidencia)
8. Worker asigna paquete a bag/flight

Flujo de Salida (Carga a Vuelo)¶

1. Scanner agrupa paquetes
2. Imprime Bag QR (etiqueta de maleta)
3. Asigna Courier al flight
4. Sistema cambia estado a LOADED_TO_FLIGHT

Flujo Técnico de Scanning¶

[Worker abre app]
        ↓
[Escanea QR]
        ↓
Flet captura string: "PKG_839201"
        ↓
POST /api/v1/scan-event
        ↓
FastAPI valida:
  - tenant (del usuario auth)
  - package (existe en DB)
  - warehouse (pertenece al tenant)
        ↓
Redis publish:
  channel: "package.scanned"
  event: { package_id, warehouse_id, timestamp }
        ↓
Webhook/API notifica:
  - Cliente (si subscribed)
  - Dashboard admin
        ↓
DB UPDATE:
  PackageEvents(scanned, timestamp, warehouse_id)
        ↓
Optional: Printer genera etiqueta

API Endpoint - Scan Event¶

POST /api/v1/scan-event
Authorization: Bearer <token>
Content-Type: application/json

Request:
{
  "qr_code": "PKG_839201",
  "warehouse_id": "uuid",
  "action": "SCAN",
  "photo_url": "https://s3.../photo.jpg",  // opcional
  "evidence": {}  // metadata adicional
}

Response (200):
{
  "event_id": "uuid",
  "package_id": "uuid",
  "status": "SCANNED",
  "next_actions": ["PRINT_LABEL", "ASSIGN_TO_BAG"],
  "warehouse_current": "MAD-WH-01"
}

4. Actores del Sistema¶

Actor	Descripción	Funciones principales
Cliente final	Persona que envía paquetes	Crear envíos, elegir moneda de destino, ver tracking
Agencia Tenant	Empresa courier (tenant)	Gestión de envíos, pricing, usuarios, warehouse, FX
Admin de tenant	Administrador interno de la agencia	Configuración, reportes, usuarios, warehouses
Courier / viajero	Usuario con rol de courier	Lleva bags de origen a destino, tiene tracking de estadísticas (vuelos completados, paquetes entregados, rating)
Warehouse operator	Operador de warehouse	Recepción, verificación, empaquetado, entrega

Nota sobre Roles: Un mismo usuario puede tener múltiples roles. Por ejemplo, una persona puede ser Admin de la agencia y también hacer de Courier cuando viaja. El sistema permite que un User tenga los roles: Admin, Courier, Warehouse Operator.

5. Features Core¶

Las siguientes funcionalidades son el enfoque del sistema:

#	Feature	Descripción
F1	Registrar envíos	Formulario de registro con datos de remitente/destinatario, contenido, peso
F2	Escanear QR/barcode	App móvil para escanear códigos de paquetes
F3	Visualizar estado de paquetes	Tracking en tiempo real para clientes
F4	Dashboard admin por tenant	Panel de control con métricas y gestión
F5	Notificaciones push	Alertas de estado del envío

6. Warehouse Operating System (WOS)¶

Sistema integral para gestionar operaciones de warehouse:

┌─────────────────────────────────────────────────────────────┐
│                    WAREHOUSE OPERATING SYSTEM               │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────┐  ┌──────────────────┐  ┌────────────┐ │
│  │ LABELING SYSTEM │  │   MOBILE SCAN    │  │   PHOTO    │ │
│  │   QR / Barcode  │  │   SYSTEM         │  │  EVIDENCE  │ │
│  └─────────────────┘  └──────────────────┘  └────────────┘ │
│  ┌─────────────────┐  ┌──────────────────┐                  │
│  │ MULTI-PACKAGE   │  │  MULTI-CARRIER   │                  │
│  │ SHIPMENT GRP    │  │  HANDLING        │                  │
│  └─────────────────┘  └──────────────────┘                  │
├─────────────────────────────────────────────────────────────┤
│  OPERACIONES:                                               │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │
│  │Recepción │ │Etiquetado│ │Picking/  │ │ Tracking │       │
│  │          │ │          │ │ Packing   │ │          │       │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘       │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              EVIDENCIA VISUAL                         │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Módulos del WOS¶

Módulo	Descripción	Funcionalidades
Labeling System	Sistema de etiquetas QR/Barcode	Generación automática, impresión, re-etiquetado
Mobile Scanning System	App móvil para escanear	Captura QR, validación, registro de eventos
Multi-Package Shipment Grouping	Agrupación de paquetes	Consolidar N packages en 1 shipment, separar shipments
Photo Evidence System	Sistema de evidencia fotográfica	Captura, almacenamiento S3, adjuntar a eventos
Multi-Carrier Handling	Manejo de maletas/viajeros/vuelos	Asignación carrier, tracking de vuelos, gestión bags

Flujo de Operaciones WOS¶

RECEPCIÓN          ETIQUETADO          PICKING/PACKING         TRACKING
     │                  │                    │                     │
     ▼                  ▼                    ▼                     ▼
┌──────────┐     ┌──────────┐        ┌──────────┐        ┌──────────┐
│  Scan    │────▶│  Generate│───────▶│  Group   │───────▶│  Real-time│
│  QR      │     │  Label   │        │  Package │        │  Events  │
└──────────┘     └──────────┘        └──────────┘        └──────────┘
     │                  │                    │                     │
     ▼                  ▼                    ▼                     ▼
┌──────────┐     ┌──────────┐        ┌──────────┐        ┌──────────┐
│  Photo   │     │  Print   │        │  Assign  │        │  Status  │
│  Evidence │     │  Label   │        │  to Bag  │        │  Update  │
└──────────┘     └──────────┘        └──────────┘        └──────────┘

Beneficios del WOS¶

Trazabilidad end-to-end: Desde recepción hasta entrega
Reducción de errores: Validación por QR elimina confusión
Evidencia auditiva: Fotos para disputas y calidad
Operaciones eficientes: Mobile app para workers en piso
Consolidación inteligente: Agrupar paquetes optimiza espacio

7. MVP Fases y Epics¶

MVP 1 — Básico¶

Objetivo: Registro de envíos y tracking simple.

Dependencias: Ninguna

Features incluidas: F1, F2, F3, F4, F5

Epic	User Stories	Backend	Frontend
Registro de paquete	Como cliente quiero registrar un paquete con remitente/destinatario, contenido, peso, fotos	API `POST /shipments`, DB shipments	Formulario registro paquete, subida de fotos, asignación QR
Generación de QR/Barcode	Como sistema quiero generar un QR para cada paquete	Generación QR en backend, almacenamiento en S3	Mostrar QR en app y PDF para imprimir
Tracking de bags y consolidación	Como cliente quiero ver en qué bags/vuelos están mis paquetes y el estado de consolidación en destino	API `GET /shipments/{id}/bags`, consolidación events	Dashboard de tracking con timeline de bags, estado de llegada
Asignación Bag-Courier	Como admin quiero asignar packages a bags y asignar un courier al bag para un vuelo	API `POST /bags`, `POST /bags/{id}/assign-courier`, `BagAssignments`	Formulario de asignación, lista de couriers disponibles
Dashboard admin	Como admin quiero ver métricas de envíos por tenant	API dashboard aggregations	Dashboard con KPIs básicos
Notificaciones push	Como cliente quiero recibir alertas de estado	WebSocket + FCM push	Configuración de notificaciones

MVP 2 — Intermedio¶

Objetivo: Multi-warehouse, contabilidad básica, pricing configurado.

Dependencias: MVP 1 completado

Epic	User Stories	Backend	Frontend
Warehouse management	Como admin quiero registrar recepciones y entradas	API warehouse events, DB warehouse_events	Dashboard warehouse, scanning app
Pricing por tenant	Como admin quiero configurar fee + FX margin	DB tenant_pricing, API `POST/GET /pricing`	Formulario de configuración de tarifas
Ledger básico	Como admin quiero registrar ingresos y operaciones FX	DB ledger, API `POST/GET /ledger`	Visualización de operaciones por tenant
Facturación PDF	Como admin quiero generar PDF de envíos	Generación PDF en backend, API	Descarga PDF y envío por email/WhatsApp

MVP 3 — Avanzado¶

Objetivo: Netting bidireccional, optimización de liquidez, reportes financieros avanzados.

Dependencias: MVP 2 completado

Epic	User Stories	Backend	Frontend
Netting bidireccional	Como admin quiero compensar saldos entre España y Perú	Algoritmo netting, DB settlements, API `POST /settlements`	Dashboard financiero con saldo neto
Integración pagos locales	Como admin quiero registrar operaciones de Yape/Plin	API webhooks pagos, DB ledger	Mostrar estado de pagos locales
Reporting avanzado	Como admin quiero KPIs de envíos, fees, cashflow	API reportes, agregaciones DB	Dashboard financiero completo

8. Roadmap¶

Placeholder: Dates and milestones to be defined.

Fase	Alcance	Target Date	Status
MVP 1	Básico	TBD	Planning
MVP 2	Intermedio	TBD	Pending MVP 1
MVP 3	Avanzado	TBD	Pending MVP 2

9. Dependencias entre MVPs¶

MVP 1 (Básico) ──→ MVP 2 (Intermedio) ──→ MVP 3 (Avanzado)
      │                    │                      │
      ▼                    ▼                      ▼
  Registro          Warehouse               Netting
  QR/Tracking       Ledger                  Reporting
  Dashboard         Pricing                 Pagos locales
  Notifications     Facturación

10. Información Pendiente¶

[ ] Fechas target para cada MVP
[ ] Presupuesto y recursos asignados
[ ] Priorización interna de features MVP 1
[ ] Detalles de integración con bancos para netting
[ ] Requisitos de compliance (KYC,AML) por mercado

11. Notas de Implementación¶

Infraestructura¶

Componente	Función	Descripción
PostgreSQL	Base de datos	Almacenamiento principal con RLS para multi-tenancy
Redis	Event bus + Realtime	Pub/Sub para eventos en tiempo real, cache de sesiones
S3/R2	Storage	Almacenamiento de PDFs, fotos, documentos
FCM	Push notifications	Notificaciones push a dispositivos móviles
FastAPI	Backend API	Lógica de negocio, validación, eventos
Flet	Frontend (UI)	UI, navegación, formularios, tracking visual

Arquitectura de la Aplicación (DDD/CQRS)¶

┌─────────────────────────────────────────────────────────────────────┐
│                         ARQUITECTURA DEL SISTEMA                     │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│   ┌─────────────┐        ┌─────────────┐        ┌─────────────┐   │
│   │             │        │             │        │             │   │
│   │    FLET     │◄──────►│   FastAPI   │◄──────►│   Postgres  │   │
│   │             │        │             │        │             │   │
│   │ Thin Client │        │ Bounded    │        │ Truth       │   │
│   │             │        │ Context     │        │ System       │   │
│   │  - UI       │        │ (Core)      │        │              │   │
│   │  - Forms    │        │  - Commands │        │  - State    │   │
│   │  - Display  │        │  - Queries  │        │  - Events   │   │
│   │             │        │  - Domain   │        │              │   │
│   └─────────────┘        └──────┬───────┘        └─────────────┘   │
│                                 │                                 │
│                                 │                                 │
│                          ┌──────▼───────┐                        │
│                          │              │                        │
│                          │    Redis     │                        │
│                          │              │                        │
│                          │  Event Bus   │                        │
│                          │              │                        │
│                          │ - Pub/Sub    │                        │
│                          │ - Real-time  │                        │
│                          │ - Cache      │                        │
│                          └──────────────┘                        │
│                                                                      │
└──────────────────────────────────────────────────────────────────────┘

Componentes Core¶

Componente	Rol	Responsabilidad
Flet	Thin Client	UI, formularios, navegación, display. Sin lógica de negocio.
FastAPI	Bounded Context (Core System)	Lógica de negocio, comandos, queries, validación, eventos
Redis	Event Bus	Pub/Sub para eventos, real-time subscriptions, cache
PostgreSQL	Truth System	Estado único, persistencia, RLS para multi-tenancy

[Worker/Flet]              [FastAPI]              [Redis]           [Postgres]
    │                        │                       │                  │
    │ POST /scan-event       │                       │                  │
    │───────────────────────>│                       │                  │
    │                        │ Validate & Process    │                  │
    │                        │──────────────────────>│                  │
    │                        │                       │ PUBLISH event    │
    │                        │                       │─────────────────>│
    │                        │                       │                  │ STORE event
    │                        │                       │                  │
    │                        │<────── ACK ──────────│<─────────────────│
    │                        │                       │                  │
    │<─── Response ─────────│                       │                  │
    │                        │                       │                  │
    │                        │ Pub/Sub notifications │                  │
    │                        │─────────────────────>│                  │
    │                        │                       │───► Dashboard    │
    │                        │                       │───► WebSocket    │
    │                        │                       │───► FCM push     │

Responsabilidades por Componente¶

Componente	Rol DDD	Qué hace	Qué NO hace
Flet	Thin Client	UI, Forms, Display, Navigation	Lógica, validación, estado
FastAPI	Bounded Context	Domain logic, Commands, Queries, Events	UI, almacenamiento local
Redis	Event Bus	Pub/Sub, Real-time, Cache	Lógica de negocio
PostgreSQL	Truth System	State, Events, Persistence	UI, lógica de presentación

Consideraciones técnicas¶

Multi-tenancy: Tenant como entidad raíz, RLS en PostgreSQL, Companies por país
Consolidación de paquetes: Shipments → Packages → BagAssignments → Bags → Flights
Bags: Gestión de maletas con código IATA post check-in, tracking de peso disponible
Couriers: Seguimiento de viajeros con estadísticas (flights_completed, packages_delivered, rating)
Companies: Setup fiscal multi-país (CIF, RUC, NIT), monedas locales, impuestos por país
PricingRules: Configurable por tenant para fee + FX margin + categoría de paquete
TenantConfig: Monedas (EUR/PEN/COP), umbrales, integraciones (Yape/Plin, FCM)
Contacts: Sender y Receiver almacenados en Shipment para trazabilidad
Documents: Almacenamiento en S3 para fotos y PDFs de paquetes
Split Shipping: Packages pueden estar en múltiples Bags (N:N relationship)
Multi-leg Tracking: Un paquete puede pasar por múltiples flights/couriers

Este documento es vivo y se actualizará según evolucione el producto.