Customer Back Office (Devoluciones)

1. Descripción general

customer-back-office-returns-portal es el back-office interno de devoluciones de Hawkers. El package.json lo nombra customer-back-office y no incluye campo description, por lo que esta descripción se basa en lo observado en el código.

Es el panel con el que los equipos internos gestionan las devoluciones que llegan desde el portal del cliente, desde tienda física o desde ATC. El menú lateral tiene cinco secciones (Devoluciones, Métodos, Motivos, Usuarios y Almacenes), con el alta manual colgando de la primera:

Área	Ruta	Qué permite
Devoluciones	/returns	Listado paginado con filtros y exportación a CSV; detalle con edición línea a línea, cambio de estados, historial de cambios y descarga del PDF en 7 idiomas
Alta manual	/returns/create	Crear una devolución en nombre del cliente en 4 pasos (pedido → artículos → método → confirmación)
Métodos	/methods	CRUD de métodos de devolución: países, precio, moneda, activación y textos traducidos con editor enriquecido
Motivos	/reasons	CRUD de motivos de devolución y sus traducciones
Usuarios	/users	Alta y edición de usuarios de Auth0 con su rol y almacén asignado
Almacenes	/warehouses	Asignación de sources (canales de venta) a cada almacén de devolución

La visibilidad de cada área depende del rol del usuario en Auth0 (ADMIN, ATC, STORE): ver Roles y control de acceso.

Igual que el portal del cliente, toda la lógica de negocio y la persistencia viven en robo-api. Este proyecto añade tres capacidades propias: autorización por rol, disparo de journeys de Marketing Cloud en los puntos de aprobación y creación, y la generación de enlaces firmados al PDF que renderiza el portal del cliente.

Repositorio: https://github.com/hawkersco/customer-back-office-returns-portal

:::info Relación con el portal del cliente Ambos proyectos son frontales de la misma API y comparten el secreto PDF_SIGNATURE_SECRET: el back-office firma la URL del PDF y la sirve el portal del cliente en https://returns.hawkersco.com/doc/…. Ver Integraciones. :::

2. Información técnica

Propiedad	Valor
Nombre del paquete	customer-back-office (el repositorio se llama customer-back-office-returns-portal)
Versión	0.1.0 (el versionado real es el BUILD_NUMBER de Jenkins)
Framework	Next.js ^16.0.8 — App Router con React Server Components
React	19.2.6
TypeScript	^6 (strict: true)
Node	.nvmrc → 22; imagen Docker node:22-alpine (coinciden)
Gestor de paquetes	npm — npm ci --legacy-peer-deps en la imagen
Autenticación	@auth0/nextjs-auth0 ^4.13.2 — sesión con cookie, roles en el ID token
Datos en cliente	SWR ^2.4.1 (useSWR + useSWRMutation) con fallbackData renderizado en servidor
Tablas	@tanstack/react-table ^8.21.2 — paginación y filtrado en servidor
Estilos	Tailwind CSS v4 + shadcn/ui (estilo new-york, base neutral) sobre Radix UI
Formularios	react-hook-form + zod v4 con superRefine para reglas de negocio
Editor de textos	react-simple-wysiwyg (negrita, cursiva, subrayado, lista, enlace y edición de HTML)
Fechas	date-fns + react-day-picker (filtro de rango de fechas)
Idioma de la UI	Español, fijo — un único diccionario en constants/dictionary.ts, sin next-intl
Tests	No hay tests en el repositorio. El markup expone atributos data-test-id para automatización
Formateo	Prettier (singleQuote: false, semi: true, trailingComma: "none") + ESLint 9
Puerto	80 en dev y start (next dev/start -p 80)

3. Estructura del proyecto

Alias de TypeScript: @/* → raíz del proyecto (las carpetas de dominio están al mismo nivel que app/, no dentro).

customer-back-office-returns-portal/
├── app/
│   ├── layout.tsx              # Root layout (Geist, Toaster)
│   ├── page.tsx                # Redirige a /returns
│   ├── role-provider.tsx       # RoleContext con los roles del usuario
│   ├── (dashboard)/            # Grupo de rutas con sidebar y sesión obligatoria
│   │   ├── layout.tsx
│   │   ├── returns/            # listado, [id], create/
│   │   ├── methods/            # listado, [id]
│   │   ├── reasons/            # listado, [id]
│   │   ├── users/              # listado, [id]
│   │   ├── warehouses/
│   │   └── unauthorized/
│   ├── api/                    # ~30 route handlers (BFF) + export CSV + token
│   └── test/page.tsx           # Página estática para el certificado de Google
├── actions/                    # Acceso a robo-api por dominio (returns, methods, reasons, users…)
├── components/
│   ├── admin/                  # sidebar, data-table genérica, badges, selectores
│   ├── returns/  methods/  reasons/  users/  warehouses/
│   ├── rich-text-editor/
│   └── ui/                     # primitivas shadcn
├── constants/                  # dictionary, roles, routes, links, origins, mc-actions…
├── context/RefundContext.tsx   # Estado del alta manual de devoluciones
├── hooks/                      # SWR + formularios (useReturns, useReturnForm, useEditMethod…)
├── lib/                        # auth0, fetchAuth, crypto, journeys, marketingCloud, utils
├── services/api.ts             # Fetchers de SWR (lado cliente)
├── types/                      # ~25 tipos de dominio
├── proxy.ts                    # Sesión Auth0 + roles + propagación del token
├── k8s/deployment.yaml
├── Dockerfile
└── Jenkinsfile

4. Documentación de esta sección

Página	Contenido
Roles y control de acceso	Auth0, proxy.ts, roles, rutas protegidas y propagación del token
Arquitectura	RSC + server actions + route handlers + SWR, diccionario y tablas
Gestión de devoluciones	Listado, filtros, CSV, detalle, matriz de editabilidad, acciones masivas y logs
Alta manual de devoluciones	El wizard de 4 pasos de /returns/create
Catálogos y administración	Métodos, motivos, usuarios y almacenes
Integraciones	robo-api, journeys de Marketing Cloud y PDF firmado compartido
Configuración y despliegue	Variables de entorno, local, Docker, Jenkins y GKE
Notas técnicas	Hallazgos, deuda técnica y consideraciones