Merge: documentar resultados de pruebas con navegador real (ADR 0010)

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01THZFwPzrwv6VAbuwmaf5vR

workloads/docs-portal/docs/decisiones/0010-pago-envio-reales-y-storefront.md

@@ -244,9 +244,12 @@ reubicó su contenedor según el breakpoint.
 ## Consecuencias
 
 - Checkout real de punta a punta (pago + envío calculado) queda
-  desplegado y verificado a nivel API/backend, pero **ambos proveedores
+  desplegado y verificado con navegador real hasta la redirección al
-  siguen en modo sandbox** — no se ha completado ni un pago real ni un
+  banco de PSE (ver nota de implementación 2026-09-10 abajo), pero
-  envío real todavía. Ver checklist de pruebas abajo.
+  **ambos proveedores siguen en modo sandbox** — no se ha completado ni
+  un pago real ni un envío real todavía, y el login bancario de PSE
+  tampoco se completó (falta credencial de prueba). Ver checklist
+  ampliado abajo.
 - La precisión de la tarifa de envío depende de cargar peso/dimensiones
   reales por producto — deuda de datos explícita, no de código; candidato
   natural a extender el importador CSV existente con columnas nuevas.
@@ -262,37 +265,92 @@ reubicó su contenedor según el breakpoint.
 
 ## Checklist de pruebas reales desde el storefront (pendiente, no ejecutado en este ADR)
 
-Todo lo de arriba se verificó a nivel API/backend con llamadas directas
+Todo lo de arriba se verificó primero a nivel API/backend con llamadas
-o carritos de prueba armados por API — **no** todavía manejando el
+directas o carritos de prueba armados por API, sin manejar el
-storefront real como lo haría un comprador. Pendiente, con la próxima
+storefront real como lo haría un comprador. Esa parte del checklist se
-sesión que tenga acceso a un navegador real:
+cerró el 2026-09-10 (ver nota de implementación abajo) usando un
+navegador real de verdad, no curl.
 
-1. **Pago PSE completo:** agregar un producto real al carrito → checkout
+### RESUELTO (2026-09-10) — navegador real vía Docker en la NAS
-   → elegir PSE → seleccionar un banco del listado real (sandbox) →
+
-   confirmar que la redirección al banco ocurre (esto es justo lo que
+El shell donde corren los comandos de esta sesión tiene su propia red
-   nunca se probó — el nombre del campo de URL de `bank.create()` está
+restringida para `npm` (un proxy interno que rompe algunas descargas de
-   manejado a la defensiva y podría no matchear ningún candidato) →
+paquetes — no relacionado con la red real del lab). **Docker en la NAS
-   volver a `/checkout/pse/return` → confirmar que la orden queda en
+sí sale a internet real, sin ese filtro** — confirmado en vivo
-   estado correcto.
+(`docker pull` normal, un contenedor de Node golpeando
-2. **Envío calculado real:** en el paso de dirección del checkout,
+`registry.npmjs.org` sin problema). Se armó un harness reutilizable con
-   confirmar que el precio de envío mostrado ya no es el fijo de
+la imagen oficial `mcr.microsoft.com/playwright:v1.51.1-jammy`
-   $15.000 sino el que devuelve EnvíoClick en vivo para esa dirección
+(Chromium real) corrida puntualmente contra `shop.cruzcloud.net`,
-   (visible también sin completar el pago, solo llegando al paso de
+guardado en `.browser-scratch/` en la raíz del lab (`checks.mjs` +
-   shipping).
+`README.md` con el comando exacto para reactivarlo — no hace falta
-3. **Resiliencia del fallback de envío:** si es posible, forzar una
+ningún contenedor corriendo de forma persistente, la imagen y las
-   dirección o producto que haga fallar la cotización real (por ejemplo,
+dependencias ya quedan cacheadas localmente en la NAS).
-   un DANE code inválido) y confirmar que el checkout sigue avanzando
+
-   con el precio de respaldo en vez de romperse — el comportamiento
+**Hallazgo no obvio:** el daemon de Docker de la NAS ve un filesystem
-   documentado en `calculatePrice()`, nunca ejercitado con un fallo real.
+distinto al que ve el shell de esta sesión (que corre en su propio
-4. **Banner dinámico:** confirmar en `/` que el carrusel muestra
+sandbox, aunque monte los mismos repos git) — un volumen `-v` apuntando
-   productos reales del catálogo (no las tres imágenes viejas
+a un path de `/tmp` del shell no tira error pero monta un directorio
-   hardcodeadas) y que cada slide lleva al producto correcto al hacer
+vacío del lado del contenedor. Hay que usar un path bajo
-   clic.
+`/media/HDD-Storage/AppData/k3d-lab-v3/lab-cruzcloud/` (montaje real
-5. **Buscador:** en un viewport mobile real (no solo devtools), confirmar
+compartido) para que el contenedor vea los archivos de verdad.
-   que el buscador ya no se ve recortado y que el autocompletado
+
-   despliega bien debajo de la fila nueva a todo el ancho.
+**Resultados, con capturas reales:**
-6. **Webhook de ePayco con un pago real de sandbox:** confirmar que,
+
-   tras completar un pago PSE de prueba desde el banco sandbox, el
+1. **Pago PSE completo — FUNCIONA.** Carrito → dirección Bogotá →
-   webhook mueve la orden a completada sin intervención manual (hoy solo
+   envío calculado → banco PSE (sandbox) → **la redirección real
-   se confirmó que el endpoint responde `200` a un `POST` sintético, no
+   funcionó**: el nombre de campo manejado a la defensiva en
-   con un webhook real disparado por ePayco).
+   `bank.create()`/`initiatePayment` matcheó al primer intento, y el
+   navegador llegó a la página real de autorización de PSE
+   (`registro.desarrollo.pse.com.co`, ambiente de desarrollo/sandbox
+   de PSE Colombia). No se completó el login bancario (requiere
+   credenciales de prueba específicas de PSE que no se tenían a mano) —
+   sigue pendiente confirmar el webhook con un pago sandbox completado
+   de principio a fin (ver checklist nuevo abajo).
+2. **Envío calculado real — FUNCIONA.** El paso de pago mostró
+   `Envío $8.941` (mismo valor ya visto en la verificación por API de
+   la sección anterior) en vez del fijo de $15.000, para una dirección
+   real de Bogotá.
+3. **Banner dinámico — funciona, pero destapó un bug real:** un
+   producto marcado `featured: true` pero **sin stock**
+   (`available: false`, "Toy Story 5 - Rex") salía primero en el
+   carrusel con botón "Comprar ahora" hacia una página donde en
+   realidad no se puede comprar. Corregido en el mismo commit que este
+   hallazgo (filtro adicional `&& product.available` en
+   `app/page.tsx`).
+4. **Buscador mobile — funciona.** El buscador ya no se ve recortado,
+   y el autocompletado despliega bien debajo de la fila nueva a todo el
+   ancho (probado con el viewport de un iPhone 13 real, no devtools).
+5. **Bug adicional encontrado, no buscado:** el sandbox real de ePayco
+   (`bank.getBanks()`) devuelve un primer elemento placeholder
+   (`bankCode: "0"`, `"A continuación seleccione su banco..."` con el
+   texto mal decodificado — unicode escapado literal) mezclado con los
+   bancos reales, mostrado como una opción más, seleccionable, en el
+   `<select>` del checkout. Ningún banco PSE real tiene código "0" —
+   se filtra explícitamente en `pse-banks/route.ts`.
+
+### Pendiente — checklist ampliado para la próxima sesión con navegador
+
+3. **Resiliencia del fallback de envío:** forzar una dirección o
+   producto que haga fallar la cotización real de EnvíoClick (ej. un
+   DANE code inválido) y confirmar que el checkout sigue avanzando con
+   el precio de respaldo ($15.000) en vez de romperse — comportamiento
+   documentado en `calculatePrice()`, nunca ejercitado con un fallo
+   real.
+6. **Webhook de ePayco con un pago real de sandbox completado:**
+   conseguir credenciales de prueba reales de PSE (persona/clave de
+   algún banco del ambiente `desarrollo`), completar el login bancario
+   de punta a punta, y confirmar que el webhook mueve la orden a
+   completada sin intervención manual — hoy solo se confirmó que el
+   endpoint responde `200` a un `POST` sintético y que la redirección
+   al banco ocurre, no el ciclo completo con notificación real.
+7. **Login/registro de cliente real** (Google OAuth y con contraseña) —
+   nunca ejercitado con un navegador real en ninguna sesión.
+8. **Bug conocido de Firefox Android** (ver memoria de proyecto,
+   `known-bug-firefox-android-layout`): el layout se corta/desplaza
+   solo en Firefox Android — Playwright puede emular Android/Chrome
+   pero no Firefox; si se necesita reproducir esto específicamente hace
+   falta `playwright-firefox` o un dispositivo real.
+9. **Otros viewports** (tablet, desktop grande) para el banner y el
+   buscador — solo se probaron mobile (iPhone 13) y desktop 1280px.
+10. **Flujo de wishlist/favoritos y el diálogo de cuenta** — no
+    ejercitados todavía con navegador real.