Customer Returns Portal
1. Descripción general
customer-returns-portal es el portal público de devoluciones dirigido al cliente final de Hawkers. El package.json no incluye campo description, por lo que esta descripción se basa en lo observado en el código.
Es una aplicación Next.js (App Router) que permite al cliente, sin necesidad de cuenta ni login, gestionar por sí mismo el ciclo completo de una devolución:
- Localizar su pedido con el número de pedido y el email de compra.
- Seleccionar los artículos a devolver y el motivo de cada uno (con información extra opcional).
- Elegir el método de devolución disponible para el país del pedido (con su precio, que se descuenta del importe a reembolsar).
- Confirmar la devolución, lo que crea el caso en el backend y devuelve el identificador
HWRETxxxxx. - Descargar el PDF de la devolución (con QR e instrucciones del método elegido) y recibir el email correspondiente vía Salesforce Marketing Cloud.
- Consultar el estado de una devolución ya creada en
/info, con su línea temporal de estados y el PDF de situación.
Toda la lógica de negocio y la persistencia viven en robo-api; este portal es un frontal que consume esa API con un token de Auth0 de scope customer y añade tres capacidades propias: internacionalización (7 idiomas), generación de PDF firmado y disparo de journeys en Marketing Cloud.
Su contrapartida interna es el Customer Back Office, con el que ATC, tiendas y administración gestionan esas devoluciones. Ambos comparten el secreto de firma de los PDFs: los enlaces que genera el back-office los sirve este proyecto en /doc/….
URL pública: https://returns.hawkersco.com (valor usado al construir el pdfUrl que se envía a Marketing Cloud en ThankYouPage.tsx).
Repositorio: https://github.com/hawkersco/customer-returns-portal
2. Información técnica
| Propiedad | Valor |
|---|---|
| Nombre del paquete | customer-returns-portal |
| Versión | 0.1.0 (no se versiona el paquete; el versionado real es el BUILD_NUMBER de Jenkins) |
| Framework | Next.js ^16.2.6 — App Router |
| React | 19.2.6 |
| TypeScript | ^6.0.3 (strict: true) |
| Node | .nvmrc → 22 (la imagen Docker usa node:20-alpine, ver Notas técnicas) |
| Gestor de paquetes | npm (package-lock.json) |
| Renderizado | Híbrido: layout y route handlers en servidor; el wizard (app/page.tsx) es cliente ('use client') |
| Estilos | Tailwind CSS v4 (@tailwindcss/postcss) + shadcn/ui (estilo new-york, base neutral) sobre Radix UI |
| i18n | next-intl ^4.11.0 — 7 idiomas, sin prefijo de idioma en la URL |
| Formularios | react-hook-form + zod v4 (@hookform/resolvers) |
@react-pdf/renderer ^4.3.0 + qrcode (servidor) / next-qrcode (cliente) | |
| Notificaciones UI | sonner (toasts) |
| Iconos | lucide-react |
| Tests | No hay tests en el repositorio. La cobertura E2E vive en Playwright Tests y se apoya en las clases qa-* del markup |
| Formateo | Prettier (prettier-plugin-tailwindcss) + ESLint 10 (eslint-config-next) |
| Puerto | 80 en dev y start (next dev/start -p 80) |
3. Estructura del proyecto
Alias de TypeScript: @/* → app/* (no hay carpeta src/).
customer-returns-portal/
├── app/
│ ├── layout.tsx # Root layout: providers, Header, Footer, Toaster
│ ├── page.tsx # Wizard de 4 pasos + pantalla final (carga dinámica)
│ ├── globals.css # Tailwind v4 + tokens shadcn
│ ├── info/page.tsx # Consulta de estado de una devolución existente
│ ├── test/page.tsx # Página estática para validar el certificado de Google
│ ├── doc/[data]/route.ts # PDF de la devolución (URL firmada)
│ ├── status/[data]/route.ts # PDF de estado de la devolución (URL firmada)
│ ├── api/ # 10 route handlers (BFF)
│ ├── components/ # Componentes de negocio + components/ui (shadcn)
│ ├── context/ # Order, Refund, ReturnMethod, Step, Language
│ ├── hooks/ # useReturnReasons, use-toast
│ ├── lib/ # auth, crypto, marketingCloud, pdf, utils, returns/
│ ├── services/api.ts # fetchAuth: fetch con Bearer de Auth0
│ ├── types/ # Tipos de dominio (Order, Return, Refund…)
│ ├── constants/languages.ts # Idiomas soportados
│ └── utils/server/ # getPngBase64 (logo para el PDF)
├── i18n/request.tsx # Resolución de locale de next-intl
├── messages/ # de, el, en, es, fr, it, pt (102 claves cada uno)
├── public/ # fonts/ (NotoSans), images/ (logos), robots.txt
├── proxy.tsx # Basic Auth (antes middleware.ts)
├── k8s/deployment.yaml
├── Dockerfile
└── Jenkinsfile
4. Documentación de esta sección
| Página | Contenido |
|---|---|
| Arquitectura | Providers, gestión de estado, flujo de datos y diagrama de la aplicación |
| Flujo de devolución | Los 4 pasos del wizard, validaciones y cálculo del importe |
| Consulta de estado | Página /info, estados de devolución y línea temporal |
| API routes e integraciones | Los 10 route handlers, robo-api, Auth0 y Marketing Cloud |
| PDFs y URLs firmadas | Firma HMAC, rutas /doc y /status, QR, fuentes y locale del PDF |
| Internacionalización | Resolución de idioma, cookies, ficheros de mensajes y traducciones remotas |
| Configuración y despliegue | Variables de entorno, Basic Auth, Docker, Jenkins, GKE y ejecución en local |
| Notas técnicas | Hallazgos, deuda técnica y consideraciones a tener en cuenta |