Verificado el codigo/README real de los dos unicos paquetes de Medusa
que aparecen buscando 'PayU' (@tax1driver/medusa-payu y
medusa-plugin-payu de rigby-sh, este ultimo archivado desde
2025-03-21): ambos usan la terminologia de la API de PayU Polonia/CEE
(clientId/posId/secondKey, OAuth), no la de PayU LatAm
(apiLogin/apiKey/accountId, developers.payulatam.com, la que cubre
Colombia). 'PayU' es una marca compartida por dos productos distintos.
La decision de negocio (PayU como proveedor) se mantiene -- cambia la
via tecnica: integracion via modulo de pago custom
(AbstractPaymentProvider de Medusa) contra la API real de PayU LatAm,
mismo tipo de esfuerzo que EnvioClick, no instalacion de plugin.
De paso, documenta las shipping options ya creadas y verificadas en
produccion (stock location, fulfillment set, service zone Colombia,
shipping option de 5.000 COP) incluyendo el paso no documentado que
las dejaba invisibles para el Store API (vinculo a sales channel).
Dato de negocio real del usuario: cuentas disponibles son Davivienda,
Lulo Bank y Banco de Bogota -- ninguna Bancolombia ni Nequi.
Verificado el mismo dia: Wompi exige cuenta Bancolombia o al menos
Nequi solo para REGISTRARSE como comercio (aunque la liquidacion
despues pueda ir a cualquier banco) -- ninguno de los bancos
disponibles califica sin abrir una cuenta nueva. PayU solo exige
cuenta bancaria colombiana a nombre del comercio, sin banco
especifico, y ya soporta PSE + Nequi + Daviplata para el cliente sin
importar el banco del comercio -- cubre exactamente lo que se pidio
(PSE + Nequi 'y demas bancos').
Estado pasa de propuesta a aceptada. Wompi se deja documentado como
deuda a reevaluar si en el futuro se abre cuenta Bancolombia/Nequi --
no se descarta por limitacion tecnica del plugin, solo por el
requisito de registro actual.
Propuesta, no aceptada: investiga el estado real de Medusa 2.18.0 para
soportar checkout de verdad (hoy el carrito cierra por WhatsApp).
Verificado contra codigo real y documentacion oficial de Medusa
(2026-08-28): cero shipping options configuradas (bloqueador
independiente del proveedor de pago), Stripe es de primera clase en
Medusa v2 pero no acepta comercios registrados en Colombia
(confirmado contra stripe.com/global), PayU tiene compatibilidad
declarada con Medusa 2.4.0+, Wompi no documenta version de Medusa ni
actividad reciente.
Deja la eleccion de proveedor de pago explicitamente pendiente de
decision de negocio del usuario -- no es algo que se pueda resolver
en el codigo.
hasTrustDialogAccepted vive en ~/.claude.json (archivo suelto en
/root), no dentro de ~/.claude/ que ya estaba montado -- se perdia en
cada recreacion del contenedor pese a que el login si persistia.
Fix: bind mount archivo-a-archivo, sembrado con el .claude.json ya
confirmado. Verificado en vivo: claude arranca sin re-pedir el
dialogo tras recrear el contenedor.
El comando docker run documentado no funcionaba realmente desde
dentro del contenedor: /DATA/AppData es un symlink absoluto a
/media/HDD-Storage/AppData, que queda roto si solo se monta /DATA.
Agrega el mount que falta, el git safe.directory necesario (baked en
el arranque, no persiste en el volumen de credenciales), y documenta
ambos gotchas con como se detectaron.
Explica el problema que resuelve (persistencia de sesion ante cortes
de red/dispositivo, distinto de limites de cuota), la arquitectura
del contenedor tmux-host, y por que Docker en vez de instalacion
nativa (squashfs read-only en ZimaOS).
Reemplaza ADR 0007 (Atelier calido, ciruela/carbon/cobre) tras dos
ciclos de implementar-y-descartar en produccion. Esta vez la direccion
se valido con mockups fuera de este entorno antes de tocar codigo.
- globals.css: paleta marino/coral/coral-claro + alias temporales de
los tokens de ADR 0007 (se resuelven ya contra la paleta nueva para
no dejar catalog-client/product-card/button.tsx sin estilo hasta que
cada sub-fase migre el nombre de clase; se eliminan en la sub-fase 5).
- layout.tsx: Poppins peso 700 reemplaza a Domine en --font-display.
- Nuevo isotipo (mariposa de 4 elipses) como logo-ari.svg (lockup) y
app/icon.svg (favicon reducido, convencion Next.js App Router);
favicon.png anterior eliminado por no estar referenciado.
- docs: ADR 0008 con la cronologia completa y el hallazgo de los
gradientes arcoiris nunca actualizados en navbar.tsx; ADR 0007
marcado como superseded sin borrar su contenido.
Validado con npm ci + typecheck + lint + build de produccion via
Docker (no hay node/npm en este shell) y verificando el CSS
compilado: los alias resuelven a la paleta nueva y las utilities
bg-ari-ciruela/text-ari-carbon/bg-ari-hueso se siguen generando.
Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01F8c83sjFBP7c4m4UVN5d3d
Identidad visual propia premium (ver docs-portal/docs/decisiones/0007-identidad-visual-propia.md,
revision 2). Correccion de proceso respecto al intento anterior
(v1.0.176, revertido): en vez de un token aislado en un solo boton,
esta pasada toca de punta a punta los componentes que se ven juntos en
la misma pantalla para que ninguna card quede a mitad de camino.
- globals.css: paleta ciruela/carbon-oscuro/cobre/hueso (reemplaza
cyan/magenta/yellow/blue, confirmado sin uso previo). Domine
(titulares/precio) + Inter (UI/cuerpo) via next/font/google -- antes
"Inter" era solo un fallback de CSS sin garantia real de carga.
- button.tsx: variant "magenta" renombrada a "primary" (ya no es
magenta, es ciruela solida) y su color redefinido -- renombrada en
los 8 archivos que la usaban para no dejar un nombre enganoso.
Radio base rounded-full -> rounded-lg, ring de foco retintado.
- product-card.tsx: badges NUEVO/TOP/descuento en la paleta nueva (no
mas fucsia/amarillo neon), precio en Domine, radio y sombra
consistentes con el boton.
- catalog-client.tsx: solo clases de color/radio en breadcrumb, filtro
de precio, pills de filtro y boton de reset -- cero cambios de
logica.
Header, footer, home y pagina de producto/drawers quedan con la
paleta anterior a proposito -- Sub-fases 2, 4 y 5 pendientes.
Validado con `docker build --target builder` (npm ci + next build con
typecheck completo) -- compila limpio.
Propuesta de rediseno visual del storefront, aprobada por el usuario
tras una correccion de direccion explicita: no clonar la estetica de
Amazon, adoptar los principios de UX del mercado (jerarquia visual,
densidad sin saturacion, senales de confianza, contraste) para
construir una identidad propia y distintiva -- paleta terracota/
espresso/pino/crema validada con contraste WCAG AA real, tipografia
Fraunces+Inter, lenguaje de forma propio, 3 detalles deliberados no
genericos.
Alcance: solo visual, no toca catalogo/backend/taxonomia ni la
estructura de navegacion ya construida en ADR 0005. Plan de
implementacion en 5 sub-fases (tokens -> header/footer -> product
card+catalog -> home -> product detail/drawers), sin codigo de
produccion tocado todavia.
Reemplaza los placeholders "TODO (fase 2+)" por narrativa completa,
grounded en el codigo/manifiestos/incidentes reales del lab (no
generico):
- ADR 0001 (por que k3d) y ADR 0002 (por que Argo CD): pasan de
template vacio a Contexto/Opciones/Decision/Consecuencias reales,
apoyados en known-issues.md (blackhole MTU) y en la config real de
ecommerce-app.yaml.
- vision-general.md: el "por que" de cada frontera de confianza del
diagrama.
- gitops-flujo.md: ejemplo real con hashes de commit (Fase 3b de
ADR 0006, v1.0.171 -> hotfix -> v1.0.172), selfHeal explicado con el
syncPolicy real del repo.
- red-y-exposicion.md: diagrama de terminacion TLS real, por que todo
va "proxied", patron de diagnostico "interno sano, publico roto".
- glosario.md: 9 terminos nuevos, cada uno con ejemplo real y
verificado del repo (Namespace, ResourceQuota, LimitRange,
NetworkPolicy, Deployment, Service, Ingress, StatefulSet, Init
container).
- notas-sueltas.md: MinIO/S3, limites reales del subscriber
revalidate-storefront.ts, que se automatizaria desde cero.
Validado con `docker build --target build` (mkdocs build --strict,
mismo paso que el pipeline real) -- cero links rotos, cero warnings.
Aprobada tras el diagnóstico de memoria del host (swap saturado
resuelto, ~500-700MiB liberados al desactivar monitoring). Agrega
nota de implementación con 3 desviaciones reales encontradas al
verificar el código fuente del plugin en el tag v1.4.1 antes de
escribir código: no hace falta subscriber propio (el plugin trae los
suyos), las rutas del plugin no devuelven facetDistribution (se
agrega una ruta Store API propia), y se conecta vía plugins: no
modules:. Ninguna cambia la decisión, solo el cómo.
Documenta el cambio a Telegram (silencioso para info, hilos al
recuperarse, log adjunto), la pausa nocturna 06:00-23:00 con su
tensión sin resolver con la ventana de medusa-deploy, la activación
del timer de systemd (60 min, bajado de 15 para reducir costo) con el
gotcha de Environment=HOME= para systemd --user, y el costo mensual
estimado actualizado.
17 corridas/día en vez de 68. Nota importante: el costo por corrida
sube al perder la ventaja del cache tibio de Claude Code (~1h TTL,
corridas espaciadas 60 min lo pierden casi siempre) -- el ahorro real
es ~1.5-2x, no 4x. También documenta el trade-off de latencia de
detección (~70 min en vez de ~25 min hasta detectar un problema).
Timer activo desde 2026-08-26. Documenta el hallazgo en vivo: el
manager de systemd --user de devops arranca con HOME=/DATA (el de
/etc/passwd), no con el override de /etc/profile.d/zz-devops-home.sh
que solo aplica a shells interactivas -- sin Environment=HOME=... en
la unidad, claude -p habría fallado la autenticación en cada corrida
del timer, silenciosamente. Se detectó y corrigió antes de activar,
corriendo el servicio manualmente vía systemctl --user start con el
entorno real como último paso de validación.
Actualiza la sección de Notificaciones: formato con íconos por tipo de
evento, log completo adjunto como documento, nivel "info" silencioso
(disable_notification), y respuestas en hilo cuando un recurso
accionado se recupera solo -- con la limitación conocida de que un
desbloqueo manual (borrando la entrada de state.json) pierde el
message_id y no queda threadeado. Validado en vivo con el canario.
Actualiza docs/arquitectura/agente-monitoreo.md: canal de notificación
cambiado de ntfy a Telegram Bot API (con la evidencia de la prueba de
entrega), horario activo 06:00-23:00 con su justificación de costo, la
tensión sin resolver con la ventana de medusa-deploy (00:00-06:00, no
se solapa con el horario activo del agente), y la estimación de costo
mensual (~US$60-65, basada en las corridas reales medidas).
Agrega docs/arquitectura/agente-monitoreo.md como referencia técnica y
documento de gobernanza del wrapper headless de diagnóstico/corrección
(scripts/lab-agent). Cubre la lista blanca de acciones automáticas
aprobada, por qué Claude corre con --allowedTools "" en vez de un Bash
tool con prefijo (coincidencia por prefijo permite inyección de
comandos, confirmado en vivo), el rediseño de autenticación a login de
suscripción en vez de API key, y la evidencia completa de la prueba
end-to-end del 2026-08-26 (DRY_RUN, ejecución real, rate limit/bloqueo,
2 bugs encontrados y corregidos).
Etapa 1 (auditoria/propuesta, sin codigo) de la Etapa 3 de Fase 5:
motor de busqueda y filtros facetados reales, reemplazando el
filtrado/conteo 100% client-side que dejo la sub-fase 3 de Etapa 2.
Verificado contra documentacion oficial vigente (no memoria de
entrenamiento):
- Medusa no tiene modulo de busqueda propio integrado con
Meilisearch; el Search Module nativo llego en Medusa 2.19, y el
plugin comunitario @rokmohar/medusa-plugin-meilisearch se conecta a
el solo desde su version ^2.0.0 (requiere Medusa >=2.19). Nuestro
backend corre Medusa 2.18.0 -- la version compatible es la linea
^1.4.1 del plugin (Medusa >=2.15 <2.19), documentada como deuda
tecnica explicita si se sube Medusa mas adelante.
- Impacto de recursos evaluado contra el estado real del host (swap
al 100%, mismo tipo de contencion que el incidente de Gitea):
Meilisearch recomendado sobre Typesense por menor huella de RAM y
por ser el unico con integracion Medusa mantenida para nuestra
version -- comparacion mantenida breve porque la diferencia es
clara, sin profundizar mas de lo necesario.
- Diseno de indexacion (campos buscables/filtrables/ordenables),
sincronizacion (mismo patron de subscriber por eventos que
revalidate-storefront.ts, sumando product-category.* al set de
eventos) y UI de facetas/autocompletado (reutiliza catalog-client.tsx
y CatalogProvider.searchProducts ya existentes, sin componentes
nuevos).
Cross-referencia agregada en ADR 0004 (que ya habia identificado
Meilisearch como paso natural) y entrada nueva en mkdocs.yml.
Etapa 2 (implementacion) NO arranca hasta aprobacion explicita de esta
propuesta.
Estado seguia diciendo "propuesta -- pendiente de aprobacion antes de
Etapa 2" aunque las 3 sub-fases (datos/categorias, navegacion,
componentes visuales -- PRs #29-#42) ya estan implementadas y en
produccion desde el 2026-08-25. Actualiza el header de estado y
reemplaza la seccion 6 (antes "Proximos pasos" pendiente de
aprobacion) por el resumen real de lo ejecutado, dejando explicito que
sigue pendiente borrar el usuario admin temporal de la auditoria y que
no hay Etapa 3 definida todavia.
Fase 5 Etapa 1: auditoria del catalogo actual (categorias/colecciones
de Medusa sin uso real, nav hardcodeado, bug de +categories en Store
API), decision de evolucionar el stack en vez de reescribirlo,
patrones UX de Amazon/eBay/Walmart y taxonomia de 21 categorias ya
creada en Medusa junto con 9 productos [DEMO] validados en vivo en
shop.cruzcloud.net como linea base pre-rediseno.
Con el runner corriendo 1 job a la vez (capacity: 1), cuando 2+
pipelines comparten el mismo commit disparador, el primero en terminar
deja su propio commit de GitOps en main -- los siguientes veian 'main
ya no es igual a mi commit' y se saltaban su propia promocion, aunque
era seguro promocionar. Visto en vivo: Frontend construyo, escaneo y
firmo v1.0.119 pero el manifiesto seguia en v1.0.104 (Promocion GitOps:
false). Fix en los 3 workflows: git merge-base --is-ancestor en vez de
comparacion exacta de SHA. Bump manual de frontend a v1.0.119 (la
version que ya estaba lista, sin desplegar). Documentado el limite
conocido de este fix en el playbook de la migracion.
Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_011FqYP3Wf1W63Qmh7qgXAAT
Los 3 pipelines (build.yaml, build-medusa.yaml, deploy-docs.yaml)
todavia apuntaban a las rutas viejas de deployment.yaml (borradas al
migrar cada app a un overlay de platform-templates) para el paso de
auto-actualizacion GitOps. Se rompio en vivo en el primer build real
post-migracion (docs-portal v1.0.117): la imagen se construyo, escaneo
y firmo bien, pero el ultimo paso (sed sobre el manifest) fallo con
'No such file or directory'. Se corrigen las 3 rutas a
patches/deployment.yaml, y se bumpea a mano el tag de docs-portal a
v1.0.117 (la imagen ya existe en el registry, firmada y verificada,
no hace falta reconstruirla).
Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_011FqYP3Wf1W63Qmh7qgXAAT
Nueva seccion 'Templates' con la pagina principal de platform-templates
(diagrama Mermaid del flujo codigo->produccion, los 3 arquetipos, el
hallazgo real de Gitea sobre uses: cross-repo). Nuevo playbook de la
migracion de docs-portal/frontend/medusa, con los 3 bugs reales
encontrados en produccion (runAsNonRoot sin imagen no-root, capabilities
rompiendo el chown de nginx, runAsNonRoot sin runAsUser numerico) y los
2 gotchas de Kustomize (rename via patch, anular un campo heredado).
Nota: el directorio se llama docs/plantillas/ y no docs/templates/ --
MkDocs excluye silenciosamente cualquier carpeta llamada 'templates'
del build (confirmado en vivo con mkdocs build --strict, sin ningun
error/warning que lo explique, solo un INFO 'excluded from built site').
Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_011FqYP3Wf1W63Qmh7qgXAAT
Detectado en vivo: el pod nuevo crasheaba con 'chown(...) Operation not
permitted' -- nginx:1.27-alpine necesita CAP_CHOWN en su propio
entrypoint. drop:[ALL] + add:[NET_BIND_SERVICE] no alcanzaba. Se saca
la restriccion de capabilities entera para este container (capabilities:
null en el patch, unica forma real de anular el drop:[ALL] heredado del
base -- omitir el campo u objeto vacio no alcanzan, confirmado en vivo).
No es peor que el estado actual en produccion; se resuelve del todo con
nginx-unprivileged.
Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_011FqYP3Wf1W63Qmh7qgXAAT
Reemplaza los manifiestos sueltos (deployment/service/ingress) por un
overlay de Kustomize sobre el base remoto de platform-templates. Agrega
readinessProbe/livenessProbe (no tenia ninguna) y securityContext
(ajustado: runAsNonRoot=false + NET_BIND_SERVICE, porque la imagen
actual de docs-portal corre como root en el puerto 80 -- se resuelve
del todo cuando docs-portal adopte dockerfiles/static-nginx.Dockerfile
de platform-templates, cambio de imagen aparte). Validado con kubectl
kustomize contra el manifiesto real desplegado antes de aplicar.
Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_011FqYP3Wf1W63Qmh7qgXAAT
Nuevo playbook del blackhole MTU cross-node (diagnostico + fix + validacion).
Actualiza el playbook de contencion de recursos Gitea/runner de 'pendiente'
a 'aplicado'. Actualiza cosign.md: firma por digest ya implementada, Rekor
como decision tomada (no TODO). Corrige 2 links que quedaron rotos al
renombrar la seccion de limitaciones (validado con mkdocs build --strict).
Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_011FqYP3Wf1W63Qmh7qgXAAT
5 playbooks nuevos en docs/playbooks/ del portal:
- SQLite en modo DELETE causando SQLITE_BUSY, por que WAL lo resuelve.
- Anchors YAML no soportados por el parser de Gitea Actions, incluido
el diagnostico equivocado inicial (indentacion) que se corrigio
despues -- documentado con honestidad como leccion de proceso.
- Docker-in-Docker vs sibling containers, y por que Semgrep corre
nativo en un venv en vez de como container aparte.
- El SNI/realm HTTP del tunel rompiendo especificamente a Cosign
(docker push funcionaba, cosign sign no), conectado con el
incidente ya documentado del 504 -- misma capa de ingress, dos
fallas distintas.
- Contencion de recursos entre Gitea y su runner: causa raiz real
confirmada en vivo durante esta misma sesion (ambos contenedores
reiniciados a mitad de un build, sin limites de CPU/memoria reales),
con fix propuesto (ver rama fix/gitea-runner-resource-limits en
scripts/) pendiente de aplicacion manual.
Se actualiza el playbook del 504 para linkear hacia el nuevo hallazgo
de contencion, cerrando el loop que habia quedado abierto ahi.
cosign.md: nueva seccion "Limitaciones conocidas y mejoras futuras"
con los dos TODO reales -- firma por tag en vez de digest (con el
warning real de Cosign visto en los logs) y transparency log de Rekor
deshabilitado, explicado en simple.
index.md: tabla resumen de los 3 pipelines (imagen + adaptacion de
Semgrep por stack), diagrama generalizado para reflejar que es el
mismo patron en los 3 workflows, y "que falta" actualizado.
Validado con mkdocs build --strict (0 errores, 0 warnings) antes de
commitear.
Run 144 de deploy-docs.yaml encontro un CVE CRITICAL real
(CVE-2026-31789, heap buffer overflow en OpenSSL) en libssl3/libcrypto3
de la base nginx:1.27-alpine, con fix ya publicado por Alpine
(3.3.3-r0 -> 3.3.7-r0). Se agrega apk upgrade puntual de esos dos
paquetes en el Dockerfile. Verificado localmente: docker build OK +
Trivy real en exit 0 (0 vulnerabilidades).
devops
gitea-actions