fix(commerce-backend): regenerar package-lock.json con epayco-sdk-node

El commit anterior agregó epayco-sdk-node a package.json pero el
lockfile nunca se actualizó (se generó localmente con
--package-lock=false para evitar un problema no relacionado del
registry en este entorno) -- npm ci en el Dockerfile exige que el
lockfile esté sincronizado con package.json y rompió el build en CI.
Regenerado con npm install normal; confirmado que npm ci (el comando
real del Dockerfile) ahora sí instala limpio.

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

workloads/commerce-backend/Dockerfile

@@ -23,7 +23,17 @@ ENV CI=true \
     S3_BUCKET=ari-shopping \
     S3_ENDPOINT=http://127.0.0.1:9000 \
     MEILISEARCH_HOST=http://127.0.0.1:7700 \
-    MEILISEARCH_API_KEY=build-only-meili-key
+    MEILISEARCH_API_KEY=build-only-meili-key \
+    GOOGLE_CLIENT_ID=build-only-google-client-id \
+    GOOGLE_CLIENT_SECRET=build-only-google-client-secret \
+    GOOGLE_CALLBACK_URL=http://localhost:9000/auth/customer/google/callback \
+    EPAYCO_PUBLIC_KEY=build-only-epayco-public \
+    EPAYCO_PRIVATE_KEY=build-only-epayco-private \
+    EPAYCO_P_CUST_ID_CLIENTE=build-only-epayco-pcust \
+    EPAYCO_P_KEY=build-only-epayco-pkey \
+    EPAYCO_ENV=sandbox \
+    EPAYCO_RESPONSE_URL=http://localhost:8000/checkout/pse/return \
+    EPAYCO_NOTIFY_URL=http://localhost:9000/hooks/payment/epayco_pse
 
 COPY package.json package-lock.json .npmrc ./
 

workloads/commerce-backend/medusa-config.ts

@@ -157,6 +157,63 @@ module.exports = defineConfig({
         ],
       },
     },
+    {
+      resolve: "@medusajs/medusa/auth",
+      options: {
+        providers: [
+          // emailpass se declara explicito junto con google -- una vez
+          // que el modulo auth se customiza, la doc no deja claro si el
+          // provider default (emailpass) se sigue registrando solo.
+          {
+            resolve: "@medusajs/medusa/auth-emailpass",
+            id: "emailpass",
+            options: {},
+          },
+          {
+            resolve: "@medusajs/medusa/auth-google",
+            id: "google",
+            options: {
+              clientId: required("GOOGLE_CLIENT_ID"),
+              clientSecret: required("GOOGLE_CLIENT_SECRET"),
+              callbackUrl: required("GOOGLE_CALLBACK_URL"),
+            },
+          },
+        ],
+      },
+    },
+    // ADR 0009: proveedor de pago -- tercera vuelta. PayU LatAm fue la
+    // decision original, pero Rapyd compro ese negocio en 2023 y el
+    // registro real del usuario quedo con credenciales de Rapyd
+    // (incompatibles, API completamente distinta). Se evaluo Rapyd en
+    // vivo y se termino descartando: comision mas alta que otras
+    // opciones para el volumen real del usuario. ePayco elegido en su
+    // lugar -- 100% de Davivienda desde 2024, comision PSE mas baja,
+    // tarifa preferencial con cuenta Davivienda (que el usuario ya
+    // tiene), sin exigir Bancolombia/Nequi como si exige Wompi. Tampoco
+    // existe plugin real de Medusa para ePayco, modulo custom propio.
+    // Alcance inicial: solo PSE, no tarjetas/otros metodos.
+    // provider_id resultante: "pp_epayco_pse" (identifier "epayco" + id
+    // "pse", convencion de Medusa).
+    {
+      resolve: "@medusajs/medusa/payment",
+      options: {
+        providers: [
+          {
+            resolve: "./src/modules/epayco-pse",
+            id: "pse",
+            options: {
+              publicKey: required("EPAYCO_PUBLIC_KEY"),
+              privateKey: required("EPAYCO_PRIVATE_KEY"),
+              pCustIdCliente: required("EPAYCO_P_CUST_ID_CLIENTE"),
+              pKey: required("EPAYCO_P_KEY"),
+              env: process.env.EPAYCO_ENV || "sandbox",
+              responseUrl: required("EPAYCO_RESPONSE_URL"),
+              notifyUrl: required("EPAYCO_NOTIFY_URL"),
+            },
+          },
+        ],
+      },
+    },
   ],
 
   // ADR 0006 Etapa 2. Sin required(): a diferencia de S3/DB, Meilisearch

workloads/commerce-backend/package-lock.json

@@ -13,7 +13,8 @@
         "@medusajs/cli": "2.18.0",
         "@medusajs/framework": "2.18.0",
         "@medusajs/medusa": "2.18.0",
-        "@rokmohar/medusa-plugin-meilisearch": "^1.4.1"
+        "@rokmohar/medusa-plugin-meilisearch": "^1.4.1",
+        "epayco-sdk-node": "^1.4.4"
       },
       "devDependencies": {
         "@swc/core": "^1.7.28",
@@ -9200,6 +9201,15 @@
         "node": ">=4.0.0"
       }
     },
+    "node_modules/component-emitter": {
+      "version": "1.3.1",
+      "resolved": "https://registry.npmjs.org/component-emitter/-/component-emitter-1.3.1.tgz",
+      "integrity": "sha512-T0+barUSQRTUQASh8bx02dl+DhF54GtIDY13Y3m9oWTklKbb3Wv974meRpeZ3lp1JpLVECWWNHC4vaG2XHXouQ==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/compressible": {
       "version": "2.0.18",
       "resolved": "https://registry.npmjs.org/compressible/-/compressible-2.0.18.tgz",
@@ -9363,6 +9373,12 @@
       "integrity": "sha512-QADzlaHc8icV8I7vbaJXJwod9HWYp8uCqf1xa4OfNu1T7JVxQIrUgOWtHdNDtPiywmFbiS12VjotIXLrKM3orQ==",
       "license": "MIT"
     },
+    "node_modules/cookiejar": {
+      "version": "2.1.4",
+      "resolved": "https://registry.npmjs.org/cookiejar/-/cookiejar-2.1.4.tgz",
+      "integrity": "sha512-LDx6oHrK+PhzLKJU9j5S7/Y3jM/mUHvD/DeI1WQmJn652iPC5Y4TBzC9l+5OMOXlyTTA+SmVUPm0HQUwpD5Jqw==",
+      "license": "MIT"
+    },
     "node_modules/copy-to-clipboard": {
       "version": "3.3.3",
       "resolved": "https://registry.npmjs.org/copy-to-clipboard/-/copy-to-clipboard-3.3.3.tgz",
@@ -9372,6 +9388,12 @@
         "toggle-selection": "^1.0.6"
       }
     },
+    "node_modules/core-util-is": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/core-util-is/-/core-util-is-1.0.3.tgz",
+      "integrity": "sha512-ZQBvi1DcpJ4GDqanjucZ2Hj3wEO5pZDS89BWbkcrvdxksJorwUDDZamX9ldFkp9aw2lmBDLgkObEA4DWNJ9FYQ==",
+      "license": "MIT"
+    },
     "node_modules/cors": {
       "version": "2.8.6",
       "resolved": "https://registry.npmjs.org/cors/-/cors-2.8.6.tgz",
@@ -9434,6 +9456,13 @@
         "node": ">= 8"
       }
     },
+    "node_modules/crypto-js": {
+      "version": "4.2.0",
+      "resolved": "https://registry.npmjs.org/crypto-js/-/crypto-js-4.2.0.tgz",
+      "integrity": "sha512-KALDyEYgpY+Rlob/iriUtjV6d5Eq+Y191A5g4UqLAi8CyGP9N1+FdVbkc1SxKc2r4YAYqG8JzO2KGL+AizD70Q==",
+      "deprecated": "Active development of CryptoJS has been discontinued. This library is no longer maintained.",
+      "license": "MIT"
+    },
     "node_modules/crypto-random-string": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/crypto-random-string/-/crypto-random-string-2.0.0.tgz",
@@ -9806,6 +9835,35 @@
         "node": ">= 0.8"
       }
     },
+    "node_modules/epayco-sdk-node": {
+      "version": "1.4.4",
+      "resolved": "https://registry.npmjs.org/epayco-sdk-node/-/epayco-sdk-node-1.4.4.tgz",
+      "integrity": "sha512-i6SpQru6Hwp096yxAVaD4lsV76ASB0cqAbJsvXQoc0leCsePHRjetV/9C1AASw8ZFbnkmTajw9DhWsAvjdTEFw==",
+      "license": "MIT",
+      "dependencies": {
+        "axios": "^1.8.2",
+        "crypto-js": "^4.2.0",
+        "debug": "2.6.9",
+        "dotenv": "^16.3.1",
+        "node-fetch": "^2.6.0",
+        "superagent": "^3.7.0"
+      }
+    },
+    "node_modules/epayco-sdk-node/node_modules/debug": {
+      "version": "2.6.9",
+      "resolved": "https://registry.npmjs.org/debug/-/debug-2.6.9.tgz",
+      "integrity": "sha512-bC7ElrdJaJnPbAP+1EotYvqZsb3ecl5wi6Bfi6BJTUcNowp6cvspg0jXznRTKDjm/E7AdgFBVeAPVMNcKGsHMA==",
+      "license": "MIT",
+      "dependencies": {
+        "ms": "2.0.0"
+      }
+    },
+    "node_modules/epayco-sdk-node/node_modules/ms": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/ms/-/ms-2.0.0.tgz",
+      "integrity": "sha512-Tpp60P6IUJDTuOq/5Z8cdskzJujfwqfOTkrwIwj7IRISpnkJnT6SyJ4PCPnGMoFjC9ddhal5KVIYtAt97ix05A==",
+      "license": "MIT"
+    },
     "node_modules/es-define-property": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/es-define-property/-/es-define-property-1.0.1.tgz",
@@ -10099,6 +10157,12 @@
       "integrity": "sha512-A/AGNMFN3c8bOlvV9RreMdrv7jsmF9XIfDeCd87+I8RNg6s78BhJxMu69NEMHBSJFxKidViTEdruRwEk/WIKqA==",
       "license": "MIT"
     },
+    "node_modules/extend": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/extend/-/extend-3.0.2.tgz",
+      "integrity": "sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==",
+      "license": "MIT"
+    },
     "node_modules/fast-deep-equal": {
       "version": "3.1.3",
       "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
@@ -10292,6 +10356,16 @@
         "node": ">= 6"
       }
     },
+    "node_modules/formidable": {
+      "version": "1.2.6",
+      "resolved": "https://registry.npmjs.org/formidable/-/formidable-1.2.6.tgz",
+      "integrity": "sha512-KcpbcpuLNOwrEjnbpMC0gS+X8ciDoZE1kkqzat4a8vrprf+s9pKNQ/QIwWfbfs4ltgmFl3MD177SNTkve3BwGQ==",
+      "deprecated": "Please upgrade to latest, formidable@v2 or formidable@v3! Check these notes: https://bit.ly/2ZEqIau",
+      "license": "MIT",
+      "funding": {
+        "url": "https://ko-fi.com/tunnckoCore/commissions"
+      }
+    },
     "node_modules/forwarded": {
       "version": "0.2.0",
       "resolved": "https://registry.npmjs.org/forwarded/-/forwarded-0.2.0.tgz",
@@ -11207,6 +11281,12 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/isarray": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/isarray/-/isarray-1.0.0.tgz",
+      "integrity": "sha512-VLghIWNM6ELQzo7zwmcg0NmTVyWKYjvIeM83yjp0wRDTmUnrM678fQbcKBo6n2CJEF0szoG//ytg+TKla89ALQ==",
+      "license": "MIT"
+    },
     "node_modules/isexe": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz",
@@ -12164,6 +12244,26 @@
         "node": ">= 8.0.0"
       }
     },
+    "node_modules/node-fetch": {
+      "version": "2.7.0",
+      "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-2.7.0.tgz",
+      "integrity": "sha512-c4FRfUm/dbcWZ7U+1Wq0AwCyFL+3nt2bEw05wfxSz+DWpWsitgmSgYmy2dQdWyKC1694ELPqMs/YzUSNozLt8A==",
+      "license": "MIT",
+      "dependencies": {
+        "whatwg-url": "^5.0.0"
+      },
+      "engines": {
+        "node": "4.x || >=6.0.0"
+      },
+      "peerDependencies": {
+        "encoding": "^0.1.0"
+      },
+      "peerDependenciesMeta": {
+        "encoding": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/node-gyp-build-optional-packages": {
       "version": "5.2.2",
       "resolved": "https://registry.npmjs.org/node-gyp-build-optional-packages/-/node-gyp-build-optional-packages-5.2.2.tgz",
@@ -12924,6 +13024,12 @@
         "node": ">=6"
       }
     },
+    "node_modules/process-nextick-args": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/process-nextick-args/-/process-nextick-args-2.0.1.tgz",
+      "integrity": "sha512-3ouUOpQhtgrbOa17J7+uxOTpITYWaGP7/AhoR3+A+/1e9skrzelGi/dXzEYyvbxubEF6Wn2ypscTKiKJFFn1ag==",
+      "license": "MIT"
+    },
     "node_modules/prompts": {
       "version": "2.4.2",
       "resolved": "https://registry.npmjs.org/prompts/-/prompts-2.4.2.tgz",
@@ -14354,6 +14460,90 @@
         "node": ">= 6"
       }
     },
+    "node_modules/superagent": {
+      "version": "3.8.3",
+      "resolved": "https://registry.npmjs.org/superagent/-/superagent-3.8.3.tgz",
+      "integrity": "sha512-GLQtLMCoEIK4eDv6OGtkOoSMt3D+oq0y3dsxMuYuDvaNUvuT8eFBuLmfR0iYYzHC1e8hpzC6ZsxbuP6DIalMFA==",
+      "deprecated": "Please upgrade to superagent v10.2.2+, see release notes at https://github.com/forwardemail/superagent/releases/tag/v10.2.2 - maintenance is supported by Forward Email @ https://forwardemail.net",
+      "license": "MIT",
+      "dependencies": {
+        "component-emitter": "^1.2.0",
+        "cookiejar": "^2.1.0",
+        "debug": "^3.1.0",
+        "extend": "^3.0.0",
+        "form-data": "^2.3.1",
+        "formidable": "^1.2.0",
+        "methods": "^1.1.1",
+        "mime": "^1.4.1",
+        "qs": "^6.5.1",
+        "readable-stream": "^2.3.5"
+      },
+      "engines": {
+        "node": ">= 4.0"
+      }
+    },
+    "node_modules/superagent/node_modules/debug": {
+      "version": "3.2.7",
+      "resolved": "https://registry.npmjs.org/debug/-/debug-3.2.7.tgz",
+      "integrity": "sha512-CFjzYYAi4ThfiQvizrFQevTTXHtnCqWfe7x1AhgEscTz6ZbLbfoLRLPugTQyBth6f8ZERVUSyWHFD/7Wu4t1XQ==",
+      "license": "MIT",
+      "dependencies": {
+        "ms": "^2.1.1"
+      }
+    },
+    "node_modules/superagent/node_modules/form-data": {
+      "version": "2.5.6",
+      "resolved": "https://registry.npmjs.org/form-data/-/form-data-2.5.6.tgz",
+      "integrity": "sha512-Ogz/E85h9tlfJzpI6TuFpGcHZFhLrb9Gw8wq9v40CxSCPnv7ahKr6Xgtkn0KYCDQJ8DNn5VoMO8EXr9V5PadyA==",
+      "license": "MIT",
+      "dependencies": {
+        "asynckit": "^0.4.0",
+        "combined-stream": "^1.0.8",
+        "es-set-tostringtag": "^2.1.0",
+        "hasown": "^2.0.4",
+        "mime-types": "^2.1.35",
+        "safe-buffer": "^5.2.1"
+      },
+      "engines": {
+        "node": ">= 0.12"
+      }
+    },
+    "node_modules/superagent/node_modules/readable-stream": {
+      "version": "2.3.8",
+      "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-2.3.8.tgz",
+      "integrity": "sha512-8p0AUk4XODgIewSi0l8Epjs+EVnWiK7NoDIEGU0HhE7+ZyY8D1IMY7odu5lRrFXGg71L15KG8QrPmum45RTtdA==",
+      "license": "MIT",
+      "dependencies": {
+        "core-util-is": "~1.0.0",
+        "inherits": "~2.0.3",
+        "isarray": "~1.0.0",
+        "process-nextick-args": "~2.0.0",
+        "safe-buffer": "~5.1.1",
+        "string_decoder": "~1.1.1",
+        "util-deprecate": "~1.0.1"
+      }
+    },
+    "node_modules/superagent/node_modules/readable-stream/node_modules/safe-buffer": {
+      "version": "5.1.2",
+      "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz",
+      "integrity": "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g==",
+      "license": "MIT"
+    },
+    "node_modules/superagent/node_modules/string_decoder": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.1.1.tgz",
+      "integrity": "sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg==",
+      "license": "MIT",
+      "dependencies": {
+        "safe-buffer": "~5.1.0"
+      }
+    },
+    "node_modules/superagent/node_modules/string_decoder/node_modules/safe-buffer": {
+      "version": "5.1.2",
+      "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz",
+      "integrity": "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g==",
+      "license": "MIT"
+    },
     "node_modules/supports-color": {
       "version": "7.2.0",
       "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz",
@@ -14635,6 +14825,12 @@
         "node": ">=0.6"
       }
     },
+    "node_modules/tr46": {
+      "version": "0.0.3",
+      "resolved": "https://registry.npmjs.org/tr46/-/tr46-0.0.3.tgz",
+      "integrity": "sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw==",
+      "license": "MIT"
+    },
     "node_modules/triple-beam": {
       "version": "1.4.1",
       "resolved": "https://registry.npmjs.org/triple-beam/-/triple-beam-1.4.1.tgz",
@@ -15099,6 +15295,22 @@
         "defaults": "^1.0.3"
       }
     },
+    "node_modules/webidl-conversions": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-3.0.1.tgz",
+      "integrity": "sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ==",
+      "license": "BSD-2-Clause"
+    },
+    "node_modules/whatwg-url": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-5.0.0.tgz",
+      "integrity": "sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw==",
+      "license": "MIT",
+      "dependencies": {
+        "tr46": "~0.0.3",
+        "webidl-conversions": "^3.0.0"
+      }
+    },
     "node_modules/which": {
       "version": "2.0.2",
       "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",

workloads/commerce-backend/package.json

@@ -15,7 +15,8 @@
     "@medusajs/cli": "2.18.0",
     "@medusajs/framework": "2.18.0",
     "@medusajs/medusa": "2.18.0",
-    "@rokmohar/medusa-plugin-meilisearch": "^1.4.1"
+    "@rokmohar/medusa-plugin-meilisearch": "^1.4.1",
+    "epayco-sdk-node": "^1.4.4"
   },
   "devDependencies": {
     "@swc/core": "^1.7.28",

workloads/commerce-backend/src/admin/lib/sdk.ts

@@ -0,0 +1,9 @@
+import Medusa from "@medusajs/js-sdk";
+
+// baseUrl "/" -- esta pagina se sirve dentro del mismo dashboard admin
+// (mismo origen que la API), no hace falta apuntar a otra URL. auth
+// "session" reusa la cookie de sesion ya autenticada del dashboard.
+export const sdk = new Medusa({
+  baseUrl: "/",
+  auth: { type: "session" },
+});

workloads/commerce-backend/src/admin/routes/importacion/page.tsx

@@ -0,0 +1,148 @@
+import { defineRouteConfig } from "@medusajs/admin-sdk";
+import { ArrowDownTray, ArrowUpTray, CheckCircleSolid, XCircleSolid } from "@medusajs/icons";
+import { Badge, Button, Container, Heading, Text, toast } from "@medusajs/ui";
+import { useRef, useState } from "react";
+import { sdk } from "../../lib/sdk";
+
+// Importador masivo via CSV -- pensado para cargar varios productos de
+// una sola vez (comprados en Amazon/eBay/etc, no dropshipping
+// automatizado -- ver conversacion sobre por que se descarto raspar
+// tiendas de terceros). Las fotos se descargan del origen y se re-alojan
+// en el mismo MinIO/S3 del NAS que ya usa el resto del catalogo.
+
+type RowResult = {
+  row: number;
+  title: string;
+  ok: boolean;
+  action?: "created" | "updated";
+  error?: string;
+};
+
+function downloadTemplate() {
+  window.open("/admin/product-import", "_blank");
+}
+
+const ProductImportPanel = () => {
+  const inputRef = useRef<HTMLInputElement>(null);
+  const [loading, setLoading] = useState(false);
+  const [results, setResults] = useState<RowResult[] | null>(null);
+
+  async function handleFile(file: File) {
+    const csv = await file.text();
+    setLoading(true);
+    setResults(null);
+    try {
+      const data = await sdk.client.fetch<{ results?: RowResult[]; error?: string }>("/admin/product-import", {
+        method: "post",
+        body: { csv },
+      });
+      if (data.error) {
+        toast.error("No se pudo procesar el archivo", { description: data.error });
+        return;
+      }
+      setResults(data.results ?? []);
+      const okCount = data.results?.filter((r) => r.ok).length ?? 0;
+      const failCount = (data.results?.length ?? 0) - okCount;
+      if (failCount === 0) {
+        toast.success(`${okCount} productos importados`);
+      } else {
+        toast.warning(`${okCount} importados, ${failCount} con error`, {
+          description: "Revisa el detalle abajo.",
+        });
+      }
+    } catch (error) {
+      toast.error("No se pudo procesar el archivo", { description: (error as Error).message });
+    } finally {
+      setLoading(false);
+      if (inputRef.current) inputRef.current.value = "";
+    }
+  }
+
+  return (
+    <Container className="divide-y p-0">
+      <div className="flex items-center justify-between px-6 py-4">
+        <div>
+          <Heading level="h2">Importación de productos</Heading>
+          <Text size="small" className="text-ui-fg-subtle">
+            Carga varios productos a la vez desde un archivo CSV, con fotos, descripción y precio.
+          </Text>
+        </div>
+        <div className="flex gap-2">
+          <Button size="small" variant="secondary" onClick={downloadTemplate}>
+            <ArrowDownTray />
+            Descargar plantilla
+          </Button>
+          <Button size="small" variant="primary" isLoading={loading} onClick={() => inputRef.current?.click()}>
+            <ArrowUpTray />
+            Subir CSV
+          </Button>
+          <input
+            ref={inputRef}
+            type="file"
+            accept=".csv,text/csv"
+            className="hidden"
+            onChange={(event) => {
+              const file = event.target.files?.[0];
+              if (file) handleFile(file);
+            }}
+          />
+        </div>
+      </div>
+
+      <div className="px-6 py-4">
+        <Text size="small" className="text-ui-fg-subtle">
+          Columnas: <code>titulo, descripcion, precio, categoria, coleccion, cantidad, fotos</code>. Varias fotos se
+          separan con <code>;</code> dentro de la misma celda. Si <code>categoria</code>/<code>coleccion</code> no
+          coinciden con una ya existente, se crean nuevas. Si <code>titulo</code> coincide con un producto ya
+          importado, no se duplica: se le agregan las fotos nuevas y se actualiza la descripción si la fila trae una.
+          Cada foto se descarga y se guarda en el almacenamiento propio de la tienda (no queda enlazada al sitio de
+          origen).
+        </Text>
+      </div>
+
+      {results && (
+        <div className="px-6 py-4">
+          <table className="w-full text-sm">
+            <thead>
+              <tr className="border-b text-left text-ui-fg-subtle">
+                <th className="w-10 py-2" />
+                <th className="py-2 font-medium">Fila</th>
+                <th className="py-2 font-medium">Producto</th>
+                <th className="py-2 font-medium">Detalle</th>
+              </tr>
+            </thead>
+            <tbody>
+              {results.map((result) => (
+                <tr key={result.row} className="border-b last:border-0">
+                  <td className="py-2">
+                    {result.ok ? (
+                      <CheckCircleSolid className="text-ui-tag-green-icon" />
+                    ) : (
+                      <XCircleSolid className="text-ui-tag-red-icon" />
+                    )}
+                  </td>
+                  <td className="py-2">{result.row}</td>
+                  <td className="py-2">{result.title}</td>
+                  <td className="py-2">
+                    {result.ok ? (
+                      <Badge color="green">{result.action === "updated" ? "Actualizado (ya existía)" : "Importado"}</Badge>
+                    ) : (
+                      <span className="text-rose-600">{result.error}</span>
+                    )}
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      )}
+    </Container>
+  );
+};
+
+export const config = defineRouteConfig({
+  label: "Importación",
+  icon: ArrowUpTray,
+});
+
+export default ProductImportPanel;

workloads/commerce-backend/src/admin/routes/inventario/page.tsx

@@ -0,0 +1,194 @@
+import { defineRouteConfig } from "@medusajs/admin-sdk";
+import { Buildings } from "@medusajs/icons";
+import { Badge, Button, Checkbox, Container, Heading, Input, Switch, Text, toast } from "@medusajs/ui";
+import { useEffect, useState } from "react";
+import { sdk } from "../../lib/sdk";
+
+// Panel simplificado para alguien no tecnico (la esposa del dueno del
+// negocio) -- una fila por producto (este catalogo es 1 variante por
+// producto, confirmado en vivo), switch para activar seguimiento de
+// stock y un input de cantidad que guarda solo. La vista nativa de
+// Medusa Admin (Inventory) sigue disponible para el dueno, esto no la
+// reemplaza, es un atajo.
+
+const LOW_STOCK_THRESHOLD = 5;
+
+type Row = {
+  productId: string;
+  variantId: string | null;
+  title: string;
+  thumbnail: string | null;
+  sku: string | null;
+  managed: boolean;
+  quantity: number;
+};
+
+async function fetchRows(): Promise<Row[]> {
+  const data = await sdk.client.fetch<{ rows: Row[] }>("/admin/inventory-panel");
+  return data.rows;
+}
+
+async function saveRow(row: { productId: string; variantId: string; managed?: boolean; quantity?: number }) {
+  await sdk.client.fetch("/admin/inventory-panel", { method: "post", body: row });
+}
+
+const InventoryPanel = () => {
+  const [rows, setRows] = useState<Row[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [selected, setSelected] = useState<Set<string>>(new Set());
+  const [savingId, setSavingId] = useState<string | null>(null);
+
+  useEffect(() => {
+    fetchRows().then((data) => {
+      setRows(data);
+      setLoading(false);
+    });
+  }, []);
+
+  function toggleSelected(productId: string, checked: boolean) {
+    setSelected((prev) => {
+      const next = new Set(prev);
+      if (checked) next.add(productId);
+      else next.delete(productId);
+      return next;
+    });
+  }
+
+  async function updateManaged(row: Row, managed: boolean) {
+    if (!row.variantId) return;
+    setSavingId(row.productId);
+    try {
+      await saveRow({ productId: row.productId, variantId: row.variantId, managed });
+      setRows((prev) =>
+        prev.map((r) => (r.productId === row.productId ? { ...r, managed } : r)),
+      );
+    } catch {
+      toast.error("No se pudo guardar", { description: row.title });
+    } finally {
+      setSavingId(null);
+    }
+  }
+
+  async function updateQuantity(row: Row, quantity: number) {
+    if (!row.variantId || Number.isNaN(quantity) || quantity < 0) return;
+    setSavingId(row.productId);
+    try {
+      await saveRow({ productId: row.productId, variantId: row.variantId, quantity });
+      setRows((prev) =>
+        prev.map((r) => (r.productId === row.productId ? { ...r, quantity } : r)),
+      );
+      toast.success("Stock actualizado", { description: row.title });
+    } catch {
+      toast.error("No se pudo guardar", { description: row.title });
+    } finally {
+      setSavingId(null);
+    }
+  }
+
+  async function bulkSetManaged(managed: boolean) {
+    const targets = rows.filter((r) => selected.has(r.productId) && r.variantId);
+    for (const row of targets) {
+      await updateManaged(row, managed);
+    }
+    setSelected(new Set());
+  }
+
+  return (
+    <Container className="divide-y p-0">
+      <div className="flex items-center justify-between px-6 py-4">
+        <div>
+          <Heading level="h2">Inventario</Heading>
+          <Text size="small" className="text-ui-fg-subtle">
+            Activa el seguimiento de stock y ajusta la cantidad disponible por producto.
+          </Text>
+        </div>
+        {selected.size > 0 && (
+          <div className="flex gap-2">
+            <Button size="small" variant="secondary" onClick={() => bulkSetManaged(true)}>
+              Activar seguimiento ({selected.size})
+            </Button>
+            <Button size="small" variant="secondary" onClick={() => bulkSetManaged(false)}>
+              Desactivar seguimiento
+            </Button>
+          </div>
+        )}
+      </div>
+
+      {loading ? (
+        <div className="px-6 py-8">
+          <Text className="text-ui-fg-subtle">Cargando…</Text>
+        </div>
+      ) : (
+        <div className="overflow-x-auto">
+          <table className="w-full text-sm">
+            <thead>
+              <tr className="border-b text-left text-ui-fg-subtle">
+                <th className="w-10 px-6 py-3" />
+                <th className="px-3 py-3 font-medium">Producto</th>
+                <th className="px-3 py-3 font-medium">SKU</th>
+                <th className="px-3 py-3 font-medium">Trackear stock</th>
+                <th className="px-3 py-3 font-medium">Cantidad disponible</th>
+                <th className="px-3 py-3 font-medium" />
+              </tr>
+            </thead>
+            <tbody>
+              {rows.map((row) => (
+                <tr key={row.productId} className="border-b last:border-0">
+                  <td className="px-6 py-3">
+                    <Checkbox
+                      checked={selected.has(row.productId)}
+                      onCheckedChange={(checked) => toggleSelected(row.productId, checked === true)}
+                    />
+                  </td>
+                  <td className="flex items-center gap-3 px-3 py-3">
+                    {row.thumbnail ? (
+                      <img src={row.thumbnail} alt="" className="size-8 rounded object-cover" />
+                    ) : (
+                      <div className="size-8 rounded bg-ui-bg-subtle" />
+                    )}
+                    <Text>{row.title}</Text>
+                  </td>
+                  <td className="px-3 py-3">
+                    <Text className="text-ui-fg-subtle">{row.sku ?? "—"}</Text>
+                  </td>
+                  <td className="px-3 py-3">
+                    <Switch
+                      checked={row.managed}
+                      disabled={savingId === row.productId}
+                      onCheckedChange={(checked) => updateManaged(row, checked)}
+                    />
+                  </td>
+                  <td className="px-3 py-3">
+                    <Input
+                      type="number"
+                      min={0}
+                      defaultValue={row.quantity}
+                      disabled={!row.managed || savingId === row.productId}
+                      className="w-24"
+                      onBlur={(event) => {
+                        const value = Number(event.target.value);
+                        if (value !== row.quantity) updateQuantity(row, value);
+                      }}
+                    />
+                  </td>
+                  <td className="px-3 py-3">
+                    {row.managed && row.quantity <= LOW_STOCK_THRESHOLD && (
+                      <Badge color="red">Stock bajo</Badge>
+                    )}
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      )}
+    </Container>
+  );
+};
+
+export const config = defineRouteConfig({
+  label: "Inventario",
+  icon: Buildings,
+});
+
+export default InventoryPanel;

workloads/commerce-backend/src/api/admin/inventory-panel/route.ts

@@ -0,0 +1,152 @@
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework";
+import { ContainerRegistrationKeys } from "@medusajs/framework/utils";
+import {
+  createInventoryItemsWorkflow,
+  updateInventoryLevelsWorkflow,
+  updateProductVariantsWorkflow,
+} from "@medusajs/medusa/core-flows";
+import { attachInventoryItemToVariantWorkflow } from "../../../workflows/attach-inventory-item-to-variant";
+
+// Panel simplificado de inventario (pensado para un usuario no tecnico,
+// no reemplaza la vista nativa de Medusa Admin -- ver ADR/memoria del
+// bug de Firefox Android, tema aparte). Un producto = una variante en
+// este catalogo real (confirmado en vivo contra /store/products antes
+// de asumirlo), asi que la tabla trabaja a nivel de producto.
+
+const PRODUCT_FIELDS = [
+  "id",
+  "title",
+  "thumbnail",
+  "status",
+  "variants.id",
+  "variants.sku",
+  "variants.manage_inventory",
+  "variants.inventory_items.inventory_item_id",
+  "variants.inventory_items.inventory.location_levels.id",
+  "variants.inventory_items.inventory.location_levels.location_id",
+  "variants.inventory_items.inventory.location_levels.stocked_quantity",
+];
+
+async function defaultLocationId(req: MedusaRequest): Promise<string | null> {
+  const query = req.scope.resolve(ContainerRegistrationKeys.QUERY);
+  const { data: locations = [] } = await query.graph({
+    entity: "stock_location",
+    fields: ["id"],
+  });
+  return locations[0]?.id ?? null;
+}
+
+export async function GET(req: MedusaRequest, res: MedusaResponse) {
+  const query = req.scope.resolve(ContainerRegistrationKeys.QUERY);
+  const locationId = await defaultLocationId(req);
+
+  const { data: products = [] } = await query.graph({
+    entity: "product",
+    fields: PRODUCT_FIELDS,
+  });
+
+  const rows = products.map((product) => {
+    const variant = product.variants?.[0];
+    const inventoryItem = variant?.inventory_items?.[0];
+    const level = inventoryItem?.inventory?.location_levels?.find(
+      (candidate) => candidate?.location_id === locationId,
+    );
+    return {
+      productId: product.id,
+      variantId: variant?.id ?? null,
+      title: product.title,
+      thumbnail: product.thumbnail,
+      status: product.status,
+      sku: variant?.sku ?? null,
+      managed: variant?.manage_inventory ?? false,
+      quantity: level?.stocked_quantity ?? 0,
+    };
+  });
+
+  res.json({ rows, locationId });
+}
+
+type PanelUpdateBody = {
+  productId: string;
+  variantId: string;
+  managed?: boolean;
+  quantity?: number;
+};
+
+export async function POST(req: MedusaRequest<PanelUpdateBody>, res: MedusaResponse) {
+  const { productId, variantId, managed, quantity } = req.body;
+  if (!productId || !variantId) {
+    res.status(400).json({ error: "productId y variantId son obligatorios" });
+    return;
+  }
+
+  const query = req.scope.resolve(ContainerRegistrationKeys.QUERY);
+  const locationId = await defaultLocationId(req);
+  if (!locationId) {
+    res.status(400).json({ error: "No hay una bodega (stock location) configurada" });
+    return;
+  }
+
+  const { data: products = [] } = await query.graph({
+    entity: "product",
+    fields: PRODUCT_FIELDS,
+    filters: { id: productId },
+  });
+  const variant = products[0]?.variants?.find((v: { id: string }) => v.id === variantId);
+  const inventoryItem = variant?.inventory_items?.[0];
+  let inventoryItemId: string | undefined = inventoryItem?.inventory_item_id;
+
+  if (managed === true && !inventoryItemId) {
+    // Primera vez que se activa el seguimiento para esta variante -- no
+    // trae InventoryItem todavia (confirmado en vivo: togglear
+    // manage_inventory=true en una variante existente NO crea uno solo,
+    // a diferencia de crear un producto nuevo con manage_inventory
+    // desde el inicio). Se crea con el nivel de stock inicial y se
+    // vincula aparte.
+    const { result: items } = await createInventoryItemsWorkflow(req.scope).run({
+      input: {
+        items: [
+          {
+            title: variant?.sku ? undefined : products[0]?.title,
+            sku: variant?.sku ?? undefined,
+            location_levels: [{ location_id: locationId, stocked_quantity: quantity ?? 0 }],
+          },
+        ],
+      },
+    });
+    inventoryItemId = items[0]?.id;
+    if (inventoryItemId) {
+      await attachInventoryItemToVariantWorkflow(req.scope).run({
+        input: { inventoryItemId, variantId },
+      });
+    }
+    await updateProductVariantsWorkflow(req.scope).run({
+      input: { product_variants: [{ id: variantId, manage_inventory: true }] },
+    });
+  } else {
+    if (typeof managed === "boolean") {
+      await updateProductVariantsWorkflow(req.scope).run({
+        input: { product_variants: [{ id: variantId, manage_inventory: managed }] },
+      });
+    }
+    if (typeof quantity === "number" && inventoryItemId) {
+      const level = inventoryItem?.inventory?.location_levels?.find(
+        (candidate) => candidate?.location_id === locationId,
+      );
+      await updateInventoryLevelsWorkflow(req.scope).run({
+        input: {
+          updates: [
+            {
+              id: level?.id,
+              inventory_item_id: inventoryItemId,
+              location_id: locationId,
+              stocked_quantity: quantity,
+            },
+          ],
+        },
+      });
+    }
+  }
+
+  res.json({ ok: true });
+}

workloads/commerce-backend/src/api/admin/product-import/route.ts

@@ -0,0 +1,328 @@
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework";
+import { Modules } from "@medusajs/framework/utils";
+import type {
+  IFulfillmentModuleService,
+  IProductModuleService,
+  ISalesChannelModuleService,
+  IStockLocationService,
+} from "@medusajs/framework/types";
+import {
+  createCollectionsWorkflow,
+  createInventoryItemsWorkflow,
+  createProductCategoriesWorkflow,
+  createProductsWorkflow,
+  updateProductsWorkflow,
+  uploadFilesWorkflow,
+} from "@medusajs/medusa/core-flows";
+import { csvRowsToObjects, parseCsv } from "../../../lib/csv";
+
+// Importador masivo de productos via CSV -- para alguien que compra
+// producto fisico en Amazon/eBay/etc. y quiere cargarlo rapido a la
+// tienda, no para dropshipping automatizado (ver conversacion: se evaluo
+// y se descarto raspar catalogos de terceros sin autorizacion). Cada
+// fila se procesa independiente (una foto rota o categoria mal escrita
+// no tumba el resto del archivo).
+//
+// categoria/coleccion: si el nombre no matchea una categoria/coleccion
+// ya existente (case-insensitive), se crea nueva -- antes se descartaba
+// en silencio y el producto quedaba sin categoria/coleccion sin avisar
+// (confirmado en vivo: "Hello Kitty & Friends" nunca se creo como
+// coleccion). El handle de la nueva categoria/coleccion se genera con
+// el mismo slugify() ASCII-safe de mas abajo, por la misma razon que el
+// handle del producto: el default de Medusa no quita tildes/enies y
+// rompe la ruta publica.
+//
+// Re-importar el mismo titulo (ej. para agregar mas fotos o actualizar
+// la descripcion de un producto ya cargado) actualiza el producto
+// existente en vez de crear uno nuevo -- antes cada re-importacion
+// generaba un producto duplicado con handle distinto (confirmado en
+// vivo con "Hello Kitty & Friends": misma fila re-subida para sumar
+// fotos, dos productos con el mismo titulo en la tienda). El match es
+// por titulo exacto (case-insensitive/trim), igual que categoria y
+// coleccion; en un match, las fotos nuevas se agregan a las que ya
+// tenia (no se reemplazan) y la descripcion se actualiza si la fila
+// trae una. No toca precio/cantidad/categoria/coleccion del producto
+// existente -- eso se edita a mano en el admin si hace falta.
+//
+// Las fotos se descargan del origen y se re-alojan en el mismo
+// MinIO/S3 que ya usa el resto del catalogo (uploadFilesWorkflow ->
+// mismo File Module Provider de medusa-config.ts, ya corre en el NAS).
+// El bucket (S3_BUCKET=ari-products) es plano -- el provider de S3 de
+// Medusa descarta cualquier subcarpeta del filename (usa solo
+// path.parse().name + ulid, confirmado leyendo
+// @medusajs/file-s3/dist/services/s3-file.js), asi que no hay una
+// carpeta separada real para lo importado -- queda mezclado con el
+// resto de fotos del catalogo, mismo criterio de nombres unicos por
+// ulid que ya usa todo el sitio.
+
+const MAX_IMAGE_BYTES = 8 * 1024 * 1024;
+const IMAGE_FETCH_TIMEOUT_MS = 15000;
+const OPTION_TITLE = "Presentación";
+const DEFAULT_VARIANT_VALUE = "Estandar";
+
+type ImportRow = {
+  titulo: string;
+  descripcion: string;
+  precio: string;
+  categoria: string;
+  coleccion: string;
+  cantidad: string;
+  fotos: string;
+};
+
+type RowResult = {
+  row: number;
+  title: string;
+  ok: boolean;
+  action?: "created" | "updated";
+  error?: string;
+};
+
+// Medusa genera el handle por defecto solo en minusculas + espacios a
+// guiones, sin quitar tildes/enies -- confirmado en vivo: 3 productos
+// importados con titulo acentuado (ej. "niñas", "Lógicos") quedaron con
+// handle como "...niñas..." y daban 404 real al entrar por
+// shop.cruzcloud.net (el tunel/ingress publico rompe rutas con UTF-8
+// no-ASCII en el path, aunque el mismo request funciona perfecto pegandole
+// directo al servicio dentro del cluster). Se genera el handle nosotros
+// mismos, ASCII-only, en vez de dejarselo al default de Medusa. El sufijo
+// corto evita colisiones entre titulos parecidos/repetidos sin necesidad
+// de revisar unicidad antes de crear.
+function slugify(title: string, uniquePart: string): string {
+  const base = title
+    .normalize("NFD")
+    .replace(/[̀-ͯ]/g, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 80)
+    .replace(/-+$/g, "");
+  return `${base || "producto"}-${uniquePart}`;
+}
+
+function extensionFromContentType(contentType: string | null, url: string): string {
+  if (contentType?.includes("png")) return "png";
+  if (contentType?.includes("webp")) return "webp";
+  if (contentType?.includes("gif")) return "gif";
+  if (contentType?.includes("jpeg") || contentType?.includes("jpg")) return "jpg";
+  const match = url.match(/\.(jpe?g|png|webp|gif)(?:\?|$)/i);
+  return match ? match[1].toLowerCase().replace("jpeg", "jpg") : "jpg";
+}
+
+async function downloadImageAsBase64(url: string): Promise<{ content: string; mimeType: string; extension: string }> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), IMAGE_FETCH_TIMEOUT_MS);
+  try {
+    const response = await fetch(url, { signal: controller.signal });
+    if (!response.ok) {
+      throw new Error(`No se pudo descargar la imagen (${response.status})`);
+    }
+    const contentType = response.headers.get("content-type");
+    const buffer = Buffer.from(await response.arrayBuffer());
+    if (buffer.byteLength > MAX_IMAGE_BYTES) {
+      throw new Error(`Imagen supera ${MAX_IMAGE_BYTES / 1024 / 1024}MB`);
+    }
+    const extension = extensionFromContentType(contentType, url);
+    return {
+      content: buffer.toString("base64"),
+      mimeType: contentType?.split(";")[0] ?? `image/${extension === "jpg" ? "jpeg" : extension}`,
+      extension,
+    };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export async function GET(req: MedusaRequest, res: MedusaResponse) {
+  // Plantilla descargable -- misma fuente de verdad que valida el POST,
+  // asi que las columnas nunca quedan desincronizadas entre lo que se
+  // ofrece descargar y lo que realmente se procesa.
+  const header = "titulo,descripcion,precio,categoria,coleccion,cantidad,fotos";
+  const example =
+    '"Muñeco Buzz Lightyear","Figura articulada de 30cm, edición coleccionista.",89900,"Figuras de accion","Toy Story",3,"https://ejemplo.com/foto1.jpg;https://ejemplo.com/foto2.jpg"';
+  const csv = `${header}\n${example}\n`;
+  res.setHeader("Content-Type", "text/csv; charset=utf-8");
+  res.setHeader("Content-Disposition", 'attachment; filename="plantilla-importacion.csv"');
+  res.send(csv);
+}
+
+export async function POST(req: MedusaRequest<{ csv: string }>, res: MedusaResponse) {
+  const csvText = req.body?.csv;
+  if (!csvText || typeof csvText !== "string") {
+    res.status(400).json({ error: "Falta el contenido CSV" });
+    return;
+  }
+
+  const rows = csvRowsToObjects(parseCsv(csvText)) as unknown as ImportRow[];
+  if (rows.length === 0) {
+    res.status(400).json({ error: "El archivo no tiene filas de datos" });
+    return;
+  }
+
+  const stockLocationService = req.scope.resolve<IStockLocationService>(Modules.STOCK_LOCATION);
+  const fulfillmentService = req.scope.resolve<IFulfillmentModuleService>(Modules.FULFILLMENT);
+  const salesChannelService = req.scope.resolve<ISalesChannelModuleService>(Modules.SALES_CHANNEL);
+  const productService = req.scope.resolve<IProductModuleService>(Modules.PRODUCT);
+
+  const [locations, shippingProfiles, salesChannels, categories, collections, existingProducts] = await Promise.all([
+    stockLocationService.listStockLocations({}),
+    fulfillmentService.listShippingProfiles({}),
+    salesChannelService.listSalesChannels({}),
+    // select explicito -- sin el, name/title llegaban undefined (el
+    // default de estos module services no siempre trae todos los
+    // escalares, a diferencia de la capa HTTP del Admin API, confirmado
+    // en vivo: la ruta /admin/product-categories con fields=id,name si
+    // los trae completos).
+    productService.listProductCategories({}, { select: ["id", "name"] }),
+    productService.listProductCollections({}, { select: ["id", "title"] }),
+    productService.listProducts({}, { select: ["id", "title"], relations: ["images"] }),
+  ]);
+
+  const locationId = locations[0]?.id;
+  const shippingProfileId = shippingProfiles.find((p) => p.type === "default")?.id ?? shippingProfiles[0]?.id;
+  const salesChannelId = salesChannels[0]?.id;
+
+  if (!locationId || !shippingProfileId || !salesChannelId) {
+    res.status(400).json({
+      error: "Faltan datos base de la tienda (bodega, perfil de envío o canal de venta)",
+    });
+    return;
+  }
+
+  const categoryByName = new Map(
+    categories.filter((c) => c.name).map((c) => [c.name.toLowerCase().trim(), c.id]),
+  );
+  const collectionByName = new Map(
+    collections.filter((c) => c.title).map((c) => [c.title.toLowerCase().trim(), c.id]),
+  );
+  const productByTitle = new Map(
+    existingProducts.filter((p) => p.title).map((p) => [p.title.toLowerCase().trim(), p]),
+  );
+
+  const results: RowResult[] = [];
+
+  for (let index = 0; index < rows.length; index++) {
+    const rowNumber = index + 2; // +1 header, +1 base 1
+    const row = rows[index];
+    const title = row.titulo?.trim();
+    try {
+      if (!title) throw new Error("Falta el título");
+      const price = Number(row.precio);
+      if (!Number.isFinite(price) || price <= 0) throw new Error("Precio inválido");
+
+      const imageUrls = (row.fotos ?? "")
+        .split(";")
+        .map((u) => u.trim())
+        .filter(Boolean);
+      if (imageUrls.length === 0) throw new Error("Falta al menos una foto");
+
+      const downloaded = await Promise.all(imageUrls.map((url) => downloadImageAsBase64(url)));
+      const { result: uploadedFiles } = await uploadFilesWorkflow(req.scope).run({
+        input: {
+          files: downloaded.map((file, i) => ({
+            filename: `${Date.now()}-${index}-${i}.${file.extension}`,
+            mimeType: file.mimeType,
+            content: file.content,
+            access: "public" as const,
+          })),
+        },
+      });
+
+      const existingProduct = productByTitle.get(title.toLowerCase());
+      if (existingProduct) {
+        await updateProductsWorkflow(req.scope).run({
+          input: {
+            products: [
+              {
+                id: existingProduct.id,
+                description: row.descripcion?.trim() || undefined,
+                images: [...(existingProduct.images ?? []).map((image) => ({ url: image.url })), ...uploadedFiles.map((f) => ({ url: f.url }))],
+              },
+            ],
+          },
+        });
+        results.push({ row: rowNumber, title, ok: true, action: "updated" });
+        continue;
+      }
+
+      const quantity = Number(row.cantidad);
+      const { result: inventoryItems } = await createInventoryItemsWorkflow(req.scope).run({
+        input: {
+          items: [
+            {
+              title,
+              location_levels: [
+                { location_id: locationId, stocked_quantity: Number.isFinite(quantity) && quantity >= 0 ? quantity : 1 },
+              ],
+            },
+          ],
+        },
+      });
+      const inventoryItemId = inventoryItems[0]?.id;
+      if (!inventoryItemId) throw new Error("No se pudo crear el registro de inventario");
+
+      const categoryName = row.categoria?.trim();
+      let categoryId = categoryName ? categoryByName.get(categoryName.toLowerCase()) : undefined;
+      if (categoryName && !categoryId) {
+        const { result: createdCategories } = await createProductCategoriesWorkflow(req.scope).run({
+          input: {
+            product_categories: [
+              { name: categoryName, handle: slugify(categoryName, `${Date.now().toString(36)}${index}`) },
+            ],
+          },
+        });
+        categoryId = createdCategories[0].id;
+        categoryByName.set(categoryName.toLowerCase(), categoryId);
+      }
+
+      const collectionName = row.coleccion?.trim();
+      let collectionId = collectionName ? collectionByName.get(collectionName.toLowerCase()) : undefined;
+      if (collectionName && !collectionId) {
+        const { result: createdCollections } = await createCollectionsWorkflow(req.scope).run({
+          input: {
+            collections: [
+              { title: collectionName, handle: slugify(collectionName, `${Date.now().toString(36)}${index}`) },
+            ],
+          },
+        });
+        collectionId = createdCollections[0].id;
+        collectionByName.set(collectionName.toLowerCase(), collectionId);
+      }
+
+      await createProductsWorkflow(req.scope).run({
+        input: {
+          products: [
+            {
+              title,
+              handle: slugify(title, `${Date.now().toString(36)}${index}`),
+              description: row.descripcion || undefined,
+              status: "published",
+              thumbnail: uploadedFiles[0]?.url,
+              images: uploadedFiles.map((f) => ({ url: f.url })),
+              category_ids: categoryId ? [categoryId] : undefined,
+              collection_id: collectionId,
+              shipping_profile_id: shippingProfileId,
+              sales_channels: [{ id: salesChannelId }],
+              options: [{ title: OPTION_TITLE, values: [DEFAULT_VARIANT_VALUE] }],
+              variants: [
+                {
+                  title: DEFAULT_VARIANT_VALUE,
+                  options: { [OPTION_TITLE]: DEFAULT_VARIANT_VALUE },
+                  manage_inventory: true,
+                  inventory_items: [{ inventory_item_id: inventoryItemId }],
+                  prices: [{ amount: price, currency_code: "cop" }],
+                },
+              ],
+            },
+          ],
+        },
+      });
+
+      results.push({ row: rowNumber, title, ok: true, action: "created" });
+    } catch (error) {
+      results.push({ row: rowNumber, title: title || `Fila ${rowNumber}`, ok: false, error: (error as Error).message });
+    }
+  }
+
+  res.json({ results });
+}

workloads/commerce-backend/src/api/store/payments/pse-banks/route.ts

@@ -0,0 +1,52 @@
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework";
+import { createEpaycoClient, type EpaycoEnv } from "../../../../lib/epayco";
+
+// Lista de bancos PSE -- no hay forma de pedirle esto al modulo de pago
+// custom directamente (AbstractPaymentProvider no expone sus metodos
+// internos fuera del contrato de pago), asi que esta ruta llama a
+// ePayco con las mismas credenciales de medusa-config.ts. Cache en
+// memoria (sin Redis/cron), mismo criterio de simplicidad que ya usa la
+// seccion de Meilisearch en medusa-config.ts.
+//
+// El shape exacto de la respuesta de bank.getBanks() no quedo verificado
+// contra el sandbox real en esta sesion -- se prueban los nombres de
+// campo mas probables (bankCode/bankName y variantes) y se degrada a
+// lista vacia si no matchea nada, en vez de romper el checkout entero.
+const CACHE_TTL_MS = 6 * 60 * 60 * 1000;
+let cache: { banks: Array<{ pseCode: string; description: string }>; fetchedAt: number } | null = null;
+
+export async function GET(req: MedusaRequest, res: MedusaResponse) {
+  if (cache && Date.now() - cache.fetchedAt < CACHE_TTL_MS) {
+    res.json({ banks: cache.banks });
+    return;
+  }
+
+  try {
+    const client = createEpaycoClient({
+      publicKey: process.env.EPAYCO_PUBLIC_KEY ?? "",
+      privateKey: process.env.EPAYCO_PRIVATE_KEY ?? "",
+      pCustIdCliente: process.env.EPAYCO_P_CUST_ID_CLIENTE ?? "",
+      pKey: process.env.EPAYCO_P_KEY ?? "",
+      env: (process.env.EPAYCO_ENV as EpaycoEnv) || "sandbox",
+    });
+    const response = await client.bank.getBanks();
+    const rawBanks = (response.data ?? response.banks ?? response) as unknown;
+    const list = Array.isArray(rawBanks) ? rawBanks : [];
+
+    const banks = list
+      .map((bank) => {
+        const record = bank as Record<string, unknown>;
+        const pseCode = record.bankCode ?? record.bank_code ?? record.codigo ?? record.id;
+        const description = record.bankName ?? record.bank_name ?? record.nombre ?? record.name ?? record.description;
+        return typeof pseCode === "string" || typeof pseCode === "number"
+          ? { pseCode: String(pseCode), description: String(description ?? pseCode) }
+          : null;
+      })
+      .filter((bank): bank is { pseCode: string; description: string } => bank !== null);
+
+    cache = { banks, fetchedAt: Date.now() };
+    res.json({ banks });
+  } catch (error) {
+    res.json({ banks: cache?.banks ?? [], error: (error as Error).message });
+  }
+}

workloads/commerce-backend/src/lib/csv.ts

@@ -0,0 +1,70 @@
+// Parser CSV minimo (RFC4180: campos entre comillas, comillas escapadas
+// como "", comas y saltos de linea dentro de campos citados) -- se evita
+// sumar una dependencia nueva (papaparse/csv-parse) para un formato que
+// nosotros mismos controlamos via la plantilla descargable.
+export function parseCsv(text: string): string[][] {
+  const rows: string[][] = [];
+  let row: string[] = [];
+  let field = "";
+  let inQuotes = false;
+  let i = 0;
+  const normalized = text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+
+  while (i < normalized.length) {
+    const char = normalized[i];
+    if (inQuotes) {
+      if (char === '"') {
+        if (normalized[i + 1] === '"') {
+          field += '"';
+          i += 2;
+          continue;
+        }
+        inQuotes = false;
+        i += 1;
+        continue;
+      }
+      field += char;
+      i += 1;
+      continue;
+    }
+    if (char === '"') {
+      inQuotes = true;
+      i += 1;
+      continue;
+    }
+    if (char === ",") {
+      row.push(field);
+      field = "";
+      i += 1;
+      continue;
+    }
+    if (char === "\n") {
+      row.push(field);
+      rows.push(row);
+      row = [];
+      field = "";
+      i += 1;
+      continue;
+    }
+    field += char;
+    i += 1;
+  }
+  if (field.length > 0 || row.length > 0) {
+    row.push(field);
+    rows.push(row);
+  }
+  return rows.filter((r) => r.some((cell) => cell.trim().length > 0));
+}
+
+export function csvRowsToObjects(rows: string[][]): Record<string, string>[] {
+  const [header, ...body] = rows;
+  if (!header) return [];
+  const keys = header.map((h) => h.trim().toLowerCase());
+  return body.map((cols) => {
+    const obj: Record<string, string> = {};
+    keys.forEach((key, index) => {
+      obj[key] = (cols[index] ?? "").trim();
+    });
+    return obj;
+  });
+}

workloads/commerce-backend/src/lib/epayco.ts

@@ -0,0 +1,68 @@
+import { createHash } from "node:crypto";
+
+// ePayco (100% de Davivienda desde 2024, ver ADR 0009 -- tercer proveedor
+// evaluado tras PayU LatAm/Rapyd, elegido por comision PSE mas baja para
+// bajo volumen y tarifa preferencial con cuenta Davivienda, que el
+// usuario ya tiene). A diferencia de PayU/Rapyd, no llamamos la API REST
+// cruda nosotros: usamos el SDK oficial `epayco-sdk-node` (mantenido por
+// github.com/epayco, ultimo publish reciente) porque su protocolo real
+// -- leido del codigo fuente, no de la doc -- es bastante mas raro de lo
+// que parece en los ejemplos: cada campo del payload se cifra con
+// AES-CBC usando la private key como llave (IV fijo en cero) ANTES de
+// mandarse a secure.payco.co, ademas de un login previo a
+// api.secure.payco.co/v1/auth/login que da un bearer token que tambien
+// va en la request. Reimplementar esto a mano tiene mucho mas riesgo de
+// error que delegarlo al SDK del propio proveedor.
+export type EpaycoEnv = "sandbox" | "production";
+
+export interface EpaycoCredentials {
+  publicKey: string;
+  privateKey: string;
+  pCustIdCliente: string;
+  pKey: string;
+  env: EpaycoEnv;
+}
+
+// Sin tipos de TypeScript en el paquete (confirmado: package.json no
+// declara "types") -- se tipa manualmente el subset que usamos.
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const EpaycoSdk = require("epayco-sdk-node");
+
+export interface EpaycoClient {
+  bank: {
+    create(options: Record<string, unknown>): Promise<Record<string, unknown>>;
+    get(transactionId: string): Promise<Record<string, unknown>>;
+    getBanks(): Promise<Record<string, unknown>>;
+  };
+}
+
+export function createEpaycoClient(credentials: EpaycoCredentials): EpaycoClient {
+  return EpaycoSdk({
+    apiKey: credentials.publicKey,
+    privateKey: credentials.privateKey,
+    lang: "ES",
+    test: credentials.env === "sandbox",
+  });
+}
+
+// Firma del webhook de confirmacion (url_confirmation) -- formula
+// verificada contra la documentacion real de ePayco:
+// sha256(p_cust_id_cliente^p_key^x_ref_payco^x_transaction_id^x_amount^x_currency_code).
+// p_cust_id_cliente/p_key son valores propios del dashboard de ePayco
+// (Configuracion > Llaves secretas), distintos de publicKey/privateKey
+// -- confirmar contra el dashboard real antes de la primera prueba.
+// Falla cerrado: cualquier mismatch devuelve false, nunca se traga la
+// excepcion.
+export function verifyWebhookSignature(params: {
+  pCustIdCliente: string;
+  pKey: string;
+  refPayco: string;
+  transactionId: string;
+  amount: string;
+  currencyCode: string;
+  signature: string;
+}): boolean {
+  const raw = `${params.pCustIdCliente}^${params.pKey}^${params.refPayco}^${params.transactionId}^${params.amount}^${params.currencyCode}`;
+  const expected = createHash("sha256").update(raw).digest("hex");
+  return expected.toLowerCase() === params.signature.toLowerCase();
+}

workloads/commerce-backend/src/modules/epayco-pse/index.ts

@@ -0,0 +1,6 @@
+import { ModuleProvider, Modules } from "@medusajs/framework/utils";
+import EpaycoPseProviderService from "./service";
+
+export default ModuleProvider(Modules.PAYMENT, {
+  services: [EpaycoPseProviderService],
+});

workloads/commerce-backend/src/modules/epayco-pse/service.ts

@@ -0,0 +1,234 @@
+import { AbstractPaymentProvider, BigNumber } from "@medusajs/framework/utils";
+import type {
+  AuthorizePaymentInput,
+  AuthorizePaymentOutput,
+  CancelPaymentInput,
+  CancelPaymentOutput,
+  CapturePaymentInput,
+  CapturePaymentOutput,
+  DeletePaymentInput,
+  DeletePaymentOutput,
+  GetPaymentStatusInput,
+  GetPaymentStatusOutput,
+  InitiatePaymentInput,
+  InitiatePaymentOutput,
+  Logger,
+  ProviderWebhookPayload,
+  RefundPaymentInput,
+  RefundPaymentOutput,
+  RetrievePaymentInput,
+  RetrievePaymentOutput,
+  UpdatePaymentInput,
+  UpdatePaymentOutput,
+  WebhookActionResult,
+} from "@medusajs/framework/types";
+import { createEpaycoClient, verifyWebhookSignature } from "../../lib/epayco";
+import type { EpaycoPseInputData, EpaycoPseOptions, EpaycoPseSessionData } from "./types";
+
+type InjectedDependencies = {
+  logger: Logger;
+};
+
+// PSE via ePayco es asincrono igual que PayU/Rapyd: no hay confirmacion
+// real hasta que llega el webhook (url_confirmation), nunca en la
+// respuesta sincrona de bank.create(). authorizePayment/capturePayment
+// por eso son casi no-ops -- el estado real lo trae siempre el webhook.
+export default class EpaycoPseProviderService extends AbstractPaymentProvider<EpaycoPseOptions> {
+  static identifier = "epayco";
+
+  protected logger_: Logger;
+  protected options_: EpaycoPseOptions;
+
+  constructor(container: InjectedDependencies, options: EpaycoPseOptions) {
+    super(container, options);
+    this.logger_ = container.logger;
+    this.options_ = options;
+  }
+
+  static validateOptions(options: Record<string, unknown>): void {
+    for (const key of ["publicKey", "privateKey", "pCustIdCliente", "pKey", "env", "responseUrl", "notifyUrl"]) {
+      if (!options[key]) {
+        throw new Error(`epayco-pse: falta la opción "${key}" en medusa-config.ts`);
+      }
+    }
+  }
+
+  async initiatePayment(input: InitiatePaymentInput): Promise<InitiatePaymentOutput> {
+    const data = input.data as unknown as EpaycoPseInputData & { session_id: string };
+    const sessionId = data.session_id;
+    const amount = new BigNumber(input.amount).numeric;
+    const currency = input.currency_code.toUpperCase();
+
+    const client = createEpaycoClient(this.options_);
+
+    // Campos confirmados leyendo node_modules/epayco-sdk-node/lib/keylang.json
+    // y tests/bank.js directamente (no la documentacion publica -- esa
+    // mostraba "metodoconfirmacion", el codigo real que de verdad manda
+    // el SDK usa "method_confirmation"). El SDK cifra estos valores y
+    // agrega ip/test/auth por su cuenta, no hace falta hacerlo nosotros.
+    const response = await client.bank.create({
+      bank: data.bank_code,
+      invoice: sessionId,
+      description: `Orden ARI Shopping ${sessionId}`,
+      value: String(amount),
+      tax: "0",
+      tax_base: "0",
+      currency,
+      type_person: data.user_type,
+      doc_type: data.doc_type,
+      doc_number: data.doc_number,
+      name: data.first_name,
+      last_name: data.last_name,
+      email: data.email,
+      country: "CO",
+      city: data.city,
+      cell_phone: data.phone,
+      url_response: this.options_.responseUrl,
+      url_confirmation: this.options_.notifyUrl,
+      method_confirmation: "POST",
+    });
+
+    if (response.error) {
+      throw new Error(`ePayco rechazó la transacción para la sesión ${sessionId}: ${JSON.stringify(response).slice(0, 300)}`);
+    }
+
+    // El nombre real del campo con la URL de redirección al banco NO
+    // quedó verificado contra una respuesta real de sandbox en esta
+    // sesión (ni la doc ni los tests del SDK lo muestran) -- se prueban
+    // los candidatos más probables y, si ninguno aparece, se tira un
+    // error con el payload completo para poder leerlo en los logs y
+    // corregir esto en el primer intento real contra el sandbox.
+    const flat = (response.data ?? response) as Record<string, unknown>;
+    const bankUrlCandidates = ["urlbanco", "url_banco", "urlBanco", "url", "redirect_url"];
+    const bankUrl = bankUrlCandidates.map((key) => flat[key]).find((value) => typeof value === "string" && value);
+
+    if (typeof bankUrl !== "string" || !bankUrl) {
+      throw new Error(
+        `ePayco no devolvió una URL de banco reconocible para la sesión ${sessionId}. Respuesta completa (revisar para corregir el nombre del campo): ${JSON.stringify(response).slice(0, 500)}`,
+      );
+    }
+
+    const sessionData: EpaycoPseSessionData = {
+      ...data,
+      session_id: sessionId,
+      ref_payco: String(flat.ref_payco ?? flat.refPayco ?? ""),
+      transaction_id: String(flat.transactionID ?? flat.transaction_id ?? ""),
+      bank_url: bankUrl,
+      state: "PENDING",
+      amount,
+      currency,
+    };
+
+    return { id: sessionId, data: sessionData as unknown as Record<string, unknown>, status: "pending" };
+  }
+
+  // PSE es diferido: en el momento de completar el carrito, ePayco
+  // todavia no confirmo nada -- "pending_authorization" es el mecanismo
+  // documentado de Medusa para esto (la orden queda "awaiting" y el
+  // navegador ya puede redirigirse al banco).
+  async authorizePayment(input: AuthorizePaymentInput): Promise<AuthorizePaymentOutput> {
+    return { data: input.data, status: "pending_authorization" };
+  }
+
+  // Casi no-op: cuando el webhook reporta "captured", ePayco ya liquido
+  // el dinero de su lado -- solo persiste el data actualizado.
+  async capturePayment(input: CapturePaymentInput): Promise<CapturePaymentOutput> {
+    return { data: input.data };
+  }
+
+  async cancelPayment(input: CancelPaymentInput): Promise<CancelPaymentOutput> {
+    this.logger_.warn("epayco-pse: cancelPayment llamado, pero PSE no soporta cancelar una transacción ya enviada");
+    return { data: input.data };
+  }
+
+  async deletePayment(input: DeletePaymentInput): Promise<DeletePaymentOutput> {
+    return { data: input.data };
+  }
+
+  // Endpoint de reembolso de ePayco no quedó verificado en vivo en esta
+  // sesión -- con dinero real de por medio, mejor tirar un error
+  // explícito que fingir un reembolso que nunca se procesó.
+  async refundPayment(_input: RefundPaymentInput): Promise<RefundPaymentOutput> {
+    throw new Error(
+      "epayco-pse: refundPayment no está implementado todavía -- procesar el reembolso manualmente desde el panel de ePayco por ahora.",
+    );
+  }
+
+  // GET /validation/v1/reference/{ref_payco} -- endpoint de verificación
+  // server-to-server documentado por ePayco para consultar el estado
+  // real de una transacción.
+  async retrievePayment(input: RetrievePaymentInput): Promise<RetrievePaymentOutput> {
+    const data = input.data as unknown as EpaycoPseSessionData | undefined;
+    const refPayco = data?.ref_payco;
+    if (!refPayco) {
+      throw new Error("epayco-pse: retrievePayment necesita ref_payco, no está guardado en esta sesión.");
+    }
+    const response = await fetch(`https://secure.epayco.co/validation/v1/reference/${refPayco}`);
+    const json = await response.json();
+    return { data: json as Record<string, unknown> };
+  }
+
+  async updatePayment(input: UpdatePaymentInput): Promise<UpdatePaymentOutput> {
+    // ePayco no tiene concepto de "modificar" una transaccion ya
+    // enviada. El checkout solo llega al step de pago despues de fijar
+    // direccion y envio, asi que el total no deberia cambiar una vez que
+    // existe una sesion PSE.
+    return { data: input.data };
+  }
+
+  async getPaymentStatus(input: GetPaymentStatusInput): Promise<GetPaymentStatusOutput> {
+    const data = input.data as unknown as EpaycoPseSessionData | undefined;
+    const state = data?.state;
+    if (state === "1") return { status: "captured" };
+    if (state === "3") return { status: "pending" };
+    if (state === "PENDING") return { status: "pending" };
+    return { status: "canceled" };
+  }
+
+  // Unico punto real de confirmacion asincrona. Falla cerrado: si la
+  // firma no matchea, no se hace nada -- nunca se confia en un webhook
+  // sin firma valida.
+  async getWebhookActionAndData(payload: ProviderWebhookPayload["payload"]): Promise<WebhookActionResult> {
+    const body = payload.data as Record<string, unknown>;
+    const refPayco = String(body.x_ref_payco ?? "");
+    const transactionId = String(body.x_transaction_id ?? "");
+    const amount = String(body.x_amount ?? "");
+    const currencyCode = String(body.x_currency_code ?? "");
+    const codState = String(body.x_cod_transaction_state ?? "");
+    const signature = String(body.x_signature ?? "");
+    // session_id sale del invoice que nosotros mandamos -- ePayco lo
+    // devuelve como x_id_invoice (o x_extra1 si no viniera) segun el
+    // webhook real; se intentan ambos.
+    const sessionId = String(body.x_id_invoice ?? body.x_extra1 ?? refPayco);
+
+    const validSignature = verifyWebhookSignature({
+      pCustIdCliente: this.options_.pCustIdCliente,
+      pKey: this.options_.pKey,
+      refPayco,
+      transactionId,
+      amount,
+      currencyCode,
+      signature,
+    });
+
+    if (!validSignature) {
+      this.logger_.warn(`epayco-pse: webhook con firma inválida para x_ref_payco=${refPayco}, ignorado`);
+      return { action: "not_supported" };
+    }
+
+    // Solo "1" (Aceptada) es exito -- cualquier otro codigo (2 Rechazada,
+    // 4 Fallida, 6 Reversada, 9 caducada, 10 abandonada, 11 Cancelada,
+    // 3 Pendiente) se trata como fallido en vez de asumir un exito
+    // distinto. Un "failed" de mas es reintentable; un "captured" de mas
+    // (dinero que nunca se aprobo) no lo es.
+    const action = codState === "1" ? "captured" : "failed";
+
+    return {
+      action,
+      data: {
+        session_id: sessionId,
+        amount: new BigNumber(amount || 0),
+      },
+    };
+  }
+}

workloads/commerce-backend/src/modules/epayco-pse/types.ts

@@ -0,0 +1,54 @@
+import type { EpaycoEnv } from "../../lib/epayco";
+
+export interface EpaycoPseOptions {
+  publicKey: string;
+  privateKey: string;
+  // p_cust_id_cliente / p_key -- valores propios del dashboard de ePayco
+  // para verificar la firma del webhook, distintos de publicKey/privateKey.
+  pCustIdCliente: string;
+  pKey: string;
+  env: EpaycoEnv;
+  // A donde ePayco redirige al comprador de vuelta tras pagar en el
+  // banco (pagina propia del storefront, no confirma nada por si sola).
+  responseUrl: string;
+  // URL publica de confirmacion -- por-transaccion (a diferencia de
+  // Rapyd, que solo permite configurarlo una vez a nivel de cuenta),
+  // apunta a la ruta nativa de Medusa /hooks/payment/:provider.
+  notifyUrl: string;
+}
+
+export type EpaycoDocType = "CC" | "CE" | "NIT" | "TI" | "PP";
+// "0" persona natural, "1" persona juridica -- valores reales que espera
+// el campo type_person de ePayco.
+export type EpaycoUserType = "0" | "1";
+
+// Lo que el storefront manda como `data` al crear la sesion de pago PSE
+// (recolectado en el step "address" del checkout, mas el banco/tipo de
+// persona/documento del nuevo step "payment"). No viene de
+// `context.customer` porque el checkout es de invitado -- ver ADR 0009.
+export interface EpaycoPseInputData {
+  bank_code: string;
+  user_type: EpaycoUserType;
+  doc_type: EpaycoDocType;
+  doc_number: string;
+  first_name: string;
+  last_name: string;
+  email: string;
+  phone: string;
+  city: string;
+}
+
+// Lo que initiatePayment devuelve y queda guardado en `data` de la
+// PaymentSession -- publico para el storefront, nunca poner credenciales
+// acá. `bank_url`: nombre de campo AUN NO VERIFICADO contra una
+// respuesta real de sandbox (ver comentario en service.ts) -- primer
+// punto a confirmar en la primera prueba end-to-end.
+export interface EpaycoPseSessionData extends EpaycoPseInputData {
+  session_id: string;
+  ref_payco: string;
+  transaction_id: string;
+  bank_url: string;
+  state: string;
+  amount: number;
+  currency: string;
+}

workloads/commerce-backend/src/workflows/attach-inventory-item-to-variant.ts

@@ -0,0 +1,21 @@
+import { createWorkflow, WorkflowResponse } from "@medusajs/framework/workflows-sdk";
+import { attachInventoryItemToVariants } from "@medusajs/medusa/core-flows";
+
+// attachInventoryItemToVariants es un step suelto (no un workflow
+// exportado) -- confirmado leyendo el .js real instalado
+// (@medusajs/core-flows/dist/inventory/steps/attach-inventory-items.js):
+// internamente resuelve ContainerRegistrationKeys.LINK y crea el link
+// Product<->Inventory. El campo "tag" del input es el variant_id (nombre
+// generico del step, no documentado con ese detalle).
+type Input = { inventoryItemId: string; variantId: string };
+
+export const attachInventoryItemToVariantWorkflow = createWorkflow(
+  "attach-inventory-item-to-variant",
+  (input: Input) => {
+    return new WorkflowResponse(
+      attachInventoryItemToVariants([
+        { inventoryItemId: input.inventoryItemId, tag: input.variantId },
+      ]),
+    );
+  },
+);

workloads/docs-portal/docs/arquitectura/sesion-tmux-persistente.md

@@ -37,6 +37,9 @@ flowchart LR
     SSH["Cliente SSH<br/>(laptop / tablet / lo que sea)"] -->|docker exec| C["Contenedor tmux-host<br/>--network host, --restart unless-stopped"]
     C --> T["tmux server<br/>sesión 'lab'"]
     T --> CC["proceso claude<br/>(Claude Code)"]
+    C --> HC["healthcheck.sh (background)<br/>cada 30 min"]
+    HC -.->|curl| NET["gitea.cruzcloud.net"]
+    HC -.->|recrea si falta| T
     C -.->|bind mount| DATA["/DATA (host)<br/>repos y configs del lab"]
     C -.->|bind mount| SOCK["/var/run/docker.sock (host)<br/>control de Docker/k3d"]
     C -.->|bind mount| HOME["/DATA/AppData/k3d-lab-v3/claude-code-home (host)<br/>-> /root/.claude"]
@@ -49,7 +52,17 @@ reinicia.
 
 ## Contenedor: `tmux-host`
 
+La imagen se construye desde `scripts/tmux-host/Dockerfile` (antes era
+un `docker run ... alpine sh -c "apk add ..."` inline — mismo contenido,
+pero ahora como imagen versionada en vez de reinstalar todo en cada
+arranque). El Dockerfile fija `WORKDIR /DATA/AppData/k3d-lab-v3/lab-cruzcloud`
+(la raíz del lab, con `CLAUDE.md`, `apps-registry/`, `platform-infra/` y
+`scripts/`) y agrega `healthcheck.sh` (ver más abajo) como proceso en
+background del contenedor.
+
 ```bash
+docker build -t tmux-host:local scripts/tmux-host
+
 docker run -d \
   --name tmux-host \
   --restart unless-stopped \
@@ -59,9 +72,15 @@ docker run -d \
   -v /DATA/AppData/k3d-lab-v3/claude-code-home:/root/.claude \
   -v /DATA/AppData/k3d-lab-v3/claude-code-home.json:/root/.claude.json \
   --network host \
-  alpine sh -c "apk add --no-cache tmux docker-cli bash curl git kubectl nodejs npm && npm install -g @anthropic-ai/claude-code && git config --global --add safe.directory '*' && tail -f /dev/null"
+  tmux-host:local
 ```
 
+`WORKDIR` hace que `docker exec` (y por lo tanto `lab-session.sh`)
+arranquen ya posicionados en la raíz del lab sin tener que navegar a
+mano — `lab-session.sh` además pasa la ruta explícita vía `tmux new -c`
+por las dudas, para no depender de que `docker exec` herede el `WORKDIR`
+de la imagen.
+
 | Volumen | Destino | Por qué |
 |---|---|---|
 | `/DATA` | `/DATA` | Acceso a los repos (`apps-registry`, `platform-infra`, `scripts`) y configs del lab, mismos paths que en el host |
@@ -195,13 +214,47 @@ Si la sesión `lab` existe, se adjunta a ella (mismo shell, mismo
 ejemplo justo después de que el contenedor se recreó desde cero— la
 crea. No hay que recordar cuál de los dos casos aplica.
 
+## Chequeo de salud automático (cada 30 min)
+
+`scripts/tmux-host/healthcheck.sh` corre en background dentro del
+propio contenedor (lanzado por `entrypoint.sh`, el `ENTRYPOINT` de la
+imagen) y cada `HEALTHCHECK_INTERVAL_SEC` (1800s por defecto) hace dos
+chequeos independientes, con una respuesta distinta según el tipo de
+falla:
+
+- **Conectividad de red real** (`curl` a `https://gitea.cruzcloud.net/`):
+  si falla, **solo se registra** en el log y se notifica por Telegram —
+  el contenedor nunca intenta "arreglar" la red del host. Un problema de
+  red puede ser de hardware/BIOS (deuda técnica ya conocida, ver
+  `incidente-medusa-crashloop-2026-08.md`), fuera del alcance real de un
+  contenedor.
+- **Existencia de la sesión tmux `lab`** (`tmux has-session`): si no
+  existe, **sí se recrea automáticamente** (`tmux new-session -d -s lab
+  -c <WORKDIR>`) — es solo recuperar el propio entorno de trabajo del
+  contenedor, no tocar infraestructura externa, así que es seguro
+  hacerlo sin intervención humana.
+
+Todo evento (chequeo ok, falla de red, sesión recreada) queda en
+`/DATA/AppData/k3d-lab-v3/tmux-host/logs/health.log` — persistente en
+`/DATA`, no solo en el stdout del contenedor (que se pierde con
+`docker logs` al recrearlo). Las notificaciones de Telegram reusan el
+mismo bot/`chat_id` ya configurado para `scripts/lab-agent/`
+(`lab-agent.env`), en vez de duplicar credenciales entre los dos
+agentes del lab.
+
+Para probar el intervalo sin esperar 30 minutos, se puede levantar el
+contenedor con `-e HEALTHCHECK_INTERVAL_SEC=60` (solo para pruebas en un
+contenedor descartable — nunca cambiar esto en el `tmux-host` real sin
+volver a 1800 después).
+
 ## Qué sobrevive a qué
 
 | Evento | ¿Sobrevive la sesión tmux (`lab`)? | ¿Sobrevive el login de Claude Code? |
 |---|---|---|
 | Corte de SSH / cerrar la terminal / cambiar de dispositivo | Sí — es exactamente el caso que este setup resuelve | Sí |
-| `docker restart tmux-host` (reinicio del NAS) | **No** — el proceso `tmux server` muere con el contenedor; `lab-session.sh` crea una sesión nueva automáticamente | Sí, vía el volumen montado en `/root/.claude` |
-| `docker rm` + recrear el contenedor desde cero | No | Sí, vía el mismo volumen — no hace falta volver a autenticar ni reconfirmar el diálogo de confianza del folder (ver el mount de `claude-code-home.json`) |
+| `docker restart tmux-host` (reinicio del NAS) | **No al toque, pero se auto-recupera solo** — el proceso `tmux server` muere con el contenedor; `healthcheck.sh` la recrea en el próximo ciclo (máx. 30 min) sin intervención, o `lab-session.sh` la crea al instante si alguien se reconecta antes | Sí, vía el volumen montado en `/root/.claude` |
+| `docker rm` + recrear el contenedor desde cero | No, pero igual se auto-recupera sola (mismo mecanismo de arriba) | Sí, vía el mismo volumen — no hace falta volver a autenticar ni reconfirmar el diálogo de confianza del folder (ver el mount de `claude-code-home.json`) |
+| Falla de red real del host/NAS | N/A | N/A — `healthcheck.sh` la detecta y notifica, pero no la corrige (fuera de su alcance) |
 
 ## Validación en vivo
 

workloads/docs-portal/docs/decisiones/0008-identidad-navy-coral.md

@@ -1,9 +1,18 @@
 # ADR 0008 — Identidad visual "Navy & Coral" para ARI Shopping
 
-**Estado:** aceptada (implementación en curso, por sub-fases)
-**Fecha:** 2026-08-27
+**Estado:** aceptada, con enmienda de paleta (ver §8) — sub-fases 1 a 4
+completas, sub-fase 5 parcial (ver §9)
+**Fecha:** 2026-08-27 (enmendada 2026-09-06)
 **Reemplaza a:** [ADR 0007](0007-identidad-visual-propia.md) (Opción 2, "Atelier cálido")
 
+> **Nota de vigencia:** la paleta descrita en §4 ("Navy & Coral":
+> marino `#122844` / coral `#D85A30` / coral claro `#F0997B`) fue la
+> dirección **aprobada e implementada en las sub-fases 1-3**, pero fue
+> **reemplazada el mismo día** por una paleta azul/amarillo estilo
+> Walmart (rama `fix/adr0008-walmart-palette-blue-yellow`, ver §8). Los
+> valores reales en producción hoy están en §8, no en §4. Se deja §4
+> intacto como registro histórico de la decisión original.
+
 ## 1. Contexto
 
 Este es el tercer intento de identidad visual propia para ARI Shopping,
@@ -168,3 +177,66 @@ definitivo; los alias se eliminan por completo al cerrar la sub-fase
   `commerce-backend`, `platform-infra`, ni CI nuevo.
 - `docs-portal` se actualiza con capturas/descripción del resultado
   final una vez cada sub-fase esté validada en producción, no antes.
+
+## 8. Enmienda 2026-08-27 tarde: pivote de paleta a azul/amarillo
+
+Horas después de mergear la sub-fase 3 (product card + grid), se
+mergeó `fix/adr0008-walmart-palette-blue-yellow`: la paleta "Navy &
+Coral" de §4 se descartó en producción y se reemplazó por una paleta
+azul/amarillo (mismo patrón "estética Walmart" ya usado como
+referencia de UX en ADR 0007). Esta decisión **no quedó documentada
+como enmienda en su momento** — se detecta y se registra aquí recién
+el 2026-09-06, al auditar el estado real del código contra este
+documento.
+
+Valores reales en `globals.css` hoy (los nombres de token de §4 se
+conservan, pero apuntan a estos valores, no a los de la tabla
+original):
+
+| Token | Valor real | Uso |
+|---|---|---|
+| `--color-ari-marino` | `#0055B8` (azul) | ancla: header, footer, fondo de hero, botón de búsqueda |
+| `--color-ari-coral` | `#0055B8` (azul, mismo valor que marino) | CTA "Agregar al carrito", precio destacado |
+| `--color-ari-coral-claro` | `#FFC220` (amarillo) | badges de oferta/urgencia, acento del isotipo, botón "yellow" del hero |
+
+Nota: `ari-coral` y `ari-marino` son el mismo azul (`#0055B8`) — a
+diferencia de la especificación original de §4, donde marino y coral
+eran colores distintos. Cualquier lectura de este ADR para decisiones
+de diseño futuras debe partir de esta tabla, no de §4.
+
+El isotipo (mariposa de 4 elipses, §4) tampoco se implementó como se
+describe: el logo vigente es `logo-ari-circular.svg` (rama
+`adr0008-logo-circular-header`), un lockup circular distinto al
+descrito en la tabla de coordenadas de §4. `logo-ari.svg` (rectangular,
+el que sí sigue la spec original) quedó sin usarse en el header.
+
+## 9. Estado real por sub-fase (auditado 2026-09-06)
+
+Auditoría contra el código en `main`, no contra el plan de §6.
+
+| # | Sub-fase | Estado | Evidencia |
+|---|---|---|---|
+| 1 | Tokens base + logo | ✅ completa (con la paleta enmendada en §8, no la de §4) | `globals.css`, `logo-ari.svg` inicial, luego reemplazado por circular en sub-fase posterior |
+| 2 | Header + footer (incl. limpieza de §5) | ✅ completa | `navbar.tsx`, restos arcoíris (gradiente ámbar/lima, línea cian/violeta/fucsia de §5) eliminados |
+| 3 | Product card + grid + badges | ✅ completa | `product-card.tsx` en tokens `ari-*` |
+| 4 | Home (hero, tiles, secciones) | ✅ completa | `hero-carousel.tsx`, `category-tiles.tsx` (varias iteraciones: pastel → scrim → foto flotante → foto más grande, todas mergeadas) |
+| 5 | Página de producto + drawers de carrito/wishlist | ⚠️ **parcial** | `product-purchase.tsx`/página de producto sí migraron (rama `adr0008-product-purchase-mobile-y-badge`). **`cart-drawer.tsx` y `wishlist-drawer.tsx` no tienen ningún token `ari-*` — nunca se tocaron.** No hay rama mergeada que los mencione. |
+
+**Deuda abierta, no asumir resuelta:**
+
+- Los alias de compatibilidad de §6 (`ari-ciruela`, `ari-cobre`,
+  `ari-carbon`, `ari-carbon-oscuro`, `ari-terracota-oscuro`,
+  `ari-hueso`) **siguen en uso real en `button.tsx`**
+  (`focus-visible:ring-ari-cobre/40`, `bg-ari-ciruela`,
+  `hover:border-ari-cobre`) — la condición de cierre de §6 ("los alias
+  se eliminan por completo al cerrar la sub-fase 5") no se cumplió.
+  Confirma que la sub-fase 5 no está cerrada, más allá de los drawers.
+- Ramas mergeadas fuera del plan original de 5 sub-fases de §6, sin
+  enmienda que las registre: `adr0008-megamenu-mobile-overflow`,
+  `adr0008-club-ari-y-novedades`, `adr0008-club-ari-imagen-azul`. Son
+  trabajo real en producción, pero expanden el alcance de este ADR sin
+  quedar documentado como tal.
+- `docs-portal` (este documento) es la primera actualización desde el
+  cierre de la sub-fase 3 — la condición de §7 ("se actualiza con
+  capturas/descripción... una vez cada sub-fase esté validada") no se
+  vino cumpliendo sub-fase por sub-fase como se planeó.

workloads/docs-portal/docs/decisiones/0009-checkout-real.md

@@ -0,0 +1,227 @@
+# ADR 0009 — Checkout real (pago en línea + envíos) para ARI Shopping
+
+**Estado:** aceptada — proveedor de pago decidido (PayU, §3);
+implementación real (credenciales, shipping options, código) pendiente
+**Fecha:** 2026-08-28
+
+## Contexto
+
+El carrito hoy no completa una transacción real: arma el pedido en el
+cliente y lo cierra con un botón "Continuar por WhatsApp"
+(`components/layout/navbar.tsx`, `mobile-add-to-cart.tsx`) — un
+placeholder intencional, no un bug. El diálogo de cuenta ya lo admite
+explícitamente ("El inicio de sesión quedará conectado al backend
+headless. Mientras tanto..."). Ni checkout ni auth de clientes tienen
+ADR previo ni intento de implementación en el historial de git de
+ningún repo del lab — este es terreno nuevo.
+
+Investigación previa a este ADR (2026-08-28, confirmado contra código
+real y documentación oficial vigente, no memoria de entrenamiento —
+misma disciplina que ADR 0006):
+
+- **Pagos:** `commerce-backend/medusa-config.ts` no registra ningún
+  provider de pago — el único módulo configurado hoy es
+  `@medusajs/medusa/file` (storage S3).
+- **Envíos:** existe una sola región ("Colombia", COP), creada a mano
+  vía Admin API durante el incidente de precios de agosto
+  (`incidente-medusa-precios-region-id-2026-08.md`), no vía ningún
+  script de seed — no existe ningún script de seed en el repo. **No
+  hay ninguna shipping option configurada en ningún lado.** Sin esto
+  el checkout no puede completarse aunque el pago ya funcione — es un
+  prerequisito invisible, independiente del proveedor de pago elegido.
+- **Auth:** cero código de cliente/login en todo el storefront (grep
+  sobre `lib/`, `app/`, `components/` sin resultados para
+  `customer`/`login`/`useAuth`/`/store/customers`). El módulo de
+  auth/customer de Medusa viene incluido en el core — falta
+  enteramente el lado del storefront, no el backend. **Medusa soporta
+  checkout como invitado**, así que auth no bloquea checkout y puede
+  secuenciarse por separado — fuera de alcance de este ADR.
+
+## 1. Flujo de checkout real en Medusa v2 (Store API)
+
+Confirmado contra `docs.medusajs.com` (2026-08-28): el flujo son 7
+pasos encadenados — crear carrito → agregar items → dirección de envío
+→ **seleccionar método de envío** (`POST` a la ruta de shipping method
+del carrito, requiere que ya exista al menos una shipping option) →
+payment collection → payment session → completar orden. Ningún paso
+es opcional; el paso de método de envío es exactamente el que hoy no
+tiene ninguna shipping option que ofrecer.
+
+## 2. Estado real de soporte de pago en Medusa 2.18.0
+
+- **Stripe es de primera clase** (`@medusajs/medusa/payment-stripe`,
+  incluido en el core, no un plugin de terceros — a diferencia de la
+  situación de Meilisearch en ADR 0006). Configuración mínima
+  verificada:
+
+  ```ts
+  {
+    resolve: "@medusajs/medusa/payment",
+    options: {
+      providers: [{
+        resolve: "@medusajs/medusa/payment-stripe",
+        id: "stripe",
+        options: { apiKey: process.env.STRIPE_API_KEY },
+      }],
+    },
+  }
+  ```
+
+  Env vars: `STRIPE_API_KEY` (siempre) y `STRIPE_WEBHOOK_SECRET`
+  (obligatorio en producción). Tras configurar, hay que habilitar el
+  provider **en la región** desde el Admin — un paso manual aparte,
+  igual que ya pasó con la región misma.
+
+- **Bloqueador real de negocio, no técnico: Stripe no acepta cuentas
+  de comercio registradas en Colombia.** Confirmado contra
+  `stripe.com/global` (2026-08-28) — Brasil y México sí están en la
+  lista de países soportados para abrir cuenta, Colombia no aparece.
+  La única vía sería registrar una entidad de negocio en un país
+  soportado, fuera de alcance realista para este lab. Esto invalida a
+  Stripe como opción pese a ser la integración técnicamente más
+  simple y mejor documentada.
+- **Alternativas con presencia real en Colombia y algún plugin de
+  Medusa existente:**
+  - **PayU** (`@tax1driver/medusa-payu`): el propio repo declara
+    compatibilidad explícita con Medusa `v2.4.0+` — cubre nuestra
+    versión (2.18.0). Webhook auto-registrado en `/hooks/payment/payu`.
+  - **Wompi** (`medusa-payment-wompi-col`, respaldado por Bancolombia,
+    liquidación directa en COP): revisé el repo directamente
+    (2026-08-28) y **no documenta contra qué versión de Medusa se
+    probó, ni tiene releases/actividad reciente visible** — mayor
+    riesgo de compatibilidad no verificada que PayU, aunque el
+    encaje de negocio (banco local, moneda nativa) sea el más
+    directo. Antes de elegirlo habría que repetir el nivel de
+    verificación que ADR 0006 le hizo al plugin de Meilisearch: leer
+    el código fuente real, no confiar en el README.
+- **Riesgo de red ya conocido, no nuevo:** cualquier webhook de pago
+  entra por la misma cadena Cloudflare → NPM → Traefik que ya causó
+  un incidente real con otro servicio
+  (`incidente-cloudflared-504-quic-2026-08.md`). Validar la entrega de
+  webhooks en vivo antes de confiar en el flujo, no asumir que
+  "funciona igual que todo lo demás".
+
+## 3. Decisión de proveedor — PayU
+
+Dato de negocio real que decidió esto (aportado por el usuario,
+2026-08-28): las cuentas bancarias disponibles son Davivienda, Lulo
+Bank y Banco de Bogotá — **ninguna es Bancolombia ni Nequi**.
+
+Verificado contra fuentes reales el mismo día (no memoria):
+
+- **Wompi exige cuenta Bancolombia o, como mínimo, cuenta Nequi para
+  poder registrarse como comercio** (modelo Agregador) — confirmado
+  contra el reglamento de comercios de Wompi y su centro de soporte.
+  La liquidación de ventas sí puede ir después a cualquier banco
+  colombiano, pero la puerta de entrada al registro sigue siendo
+  Bancolombia/Nequi. Con los bancos disponibles hoy, esto exigiría
+  abrir una cuenta Nequi nueva solo para poder registrarse — paso
+  extra evitable.
+- **PayU solo exige "cuenta bancaria colombiana a nombre del
+  comercio"**, sin banco específico — Davivienda, Lulo Bank o Banco de
+  Bogotá califican igual, sin pasos previos. Además ya soporta **PSE**
+  (transferencia desde cualquier banco colombiano del cliente, sin
+  relación con el banco del comercio), **Nequi** y **Daviplata** como
+  métodos de pago para los clientes vía redirección — cubre exactamente
+  los métodos que se pidieron (PSE + Nequi "y demás bancos") sin que
+  la cuenta bancaria propia del comercio sea Bancolombia.
+
+**Decisión:** PayU como proveedor de pago (negocio) se mantiene. La vía
+técnica cambió el 2026-08-29 — ver nota de implementación al final de
+este documento: ningún plugin comunitario de Medusa sirve para PayU
+LatAm, hace falta un módulo de pago custom. Wompi queda descartado por
+el requisito de registro Bancolombia/Nequi, no por limitación técnica.
+
+**Pendiente antes de implementar (no resoluble en este ADR):**
+
+- Registro real de comercio en PayU (persona natural o jurídica —
+  jurídica pide NIT, representante legal y estados financieros
+  básicos) y credenciales reales (`apiLogin`, `apiKey`, `merchantId`,
+  `accountId` — terminología real de la API de PayU LatAm, ver nota de
+  implementación) — nunca generadas ni asumidas por mí.
+- Escribir el módulo de pago custom para PayU LatAm (no instalar un
+  plugin — no existe ninguno real para esta API, ver nota de
+  implementación).
+
+## Opciones consideradas
+
+| Opción | A favor | En contra |
+|---|---|---|
+| **Stripe** | Integración core de Medusa, mejor documentada, configuración mínima | No acepta comercios registrados en Colombia — bloqueador de negocio, no técnico |
+| **PayU** — **elegido** (proveedor de negocio; integración técnica ahora es custom, ver nota de implementación) | Solo exige cuenta bancaria colombiana a nombre del comercio, sin banco específico (encaja con Davivienda/Lulo Bank/Banco de Bogotá); soporta PSE + Nequi + Daviplata para el cliente sin importar el banco del comercio | Ningún plugin de Medusa real sirve para su API LatAm (`apiLogin`/`apiKey`/`accountId`) — los dos paquetes que parecían encajar por nombre son en realidad para PayU Polonia/CEE (`clientId`/`posId`/`secondKey`), uno de ellos archivado; requiere módulo de pago custom |
+| **Wompi** (`medusa-payment-wompi-col`) | Liquidación directa en COP vía Bancolombia | Exige cuenta Bancolombia o, como mínimo, Nequi solo para **registrarse** como comercio — ninguno de los bancos disponibles (Davivienda/Lulo Bank/Banco de Bogotá) califica sin abrir una cuenta nueva; además, sin versión de Medusa documentada ni actividad reciente visible en el plugin |
+| **Seguir con WhatsApp** (no pago en línea) | Cero riesgo nuevo, cero dependencia externa | No resuelve el objetivo real (transacción completa sin intervención manual); no es checkout, es lo que ya existe hoy |
+
+## Consecuencias
+
+- Las shipping options son un prerequisito independiente del proveedor
+  y deben configurarse primero — sin ellas ningún flujo de checkout
+  completa, sea cual sea el pago.
+- El pago de PayU se implementa como módulo custom (`AbstractPaymentProvider`
+  de Medusa) contra la API real de PayU LatAm, no como instalación de
+  un plugin de terceros — más superficie propia para mantener, mismo
+  patrón de esfuerzo que ya se identificó para EnvíoClick en §2.
+- Los webhooks de pago (a definir en el módulo custom, apuntando a la
+  URL de notificación real de PayU LatAm) deben validarse en vivo
+  contra la cadena de red real del lab antes de confiar en el flujo,
+  dado el precedente de `incidente-cloudflared-504-quic-2026-08.md`.
+- Se acepta como deuda: si en el futuro se abre una cuenta Bancolombia
+  o Nequi, Wompi (liquidación más directa en COP) vuelve a ser una
+  opción válida a reevaluar — no se descarta por limitación técnica,
+  solo por el requisito de registro actual.
+- Revertir esta decisión implica deshabilitar el provider en la región
+  y volver al botón de WhatsApp — el carrito y el catálogo no cambian
+  de forma, solo el paso final.
+
+## Nota de implementación (2026-08-29): shipping options creadas
+
+Bloqueador de §1 resuelto en producción, verificado extremo a extremo
+contra el Store API real (no solo creado en Admin):
+
+- Stock location "Bodega principal ARI Shopping" (`sloc_01M15G3D1336V8WQW3VZQRP6AN`).
+- Fulfillment set + zona de servicio "Colombia" (`geo_zone` tipo país, `co`).
+- Provider `manual_manual` habilitado en la ubicación.
+- Shipping option "Envío nacional estándar", tarifa fija $15.000 COP
+  (placeholder de negocio dentro del rango real de mercado
+  $12.000–$18.000 que dio el usuario, no un cálculo por peso/volumen —
+  eso es justamente lo que EnvíoClick resolvería más adelante),
+  vinculada al Default Shipping Profile y a la región Colombia/COP.
+- **Paso no documentado en ningún lado y que rompía todo en silencio:**
+  la stock location tiene que estar vinculada al Sales Channel
+  (`/admin/stock-locations/{id}/sales-channels`) para que el Store API
+  devuelva la shipping option — sin esto, `GET /store/shipping-options`
+  devolvía `[]` vacío pese a que el fulfillment set, la zona de
+  servicio y el provider ya estaban bien configurados. Confirmado con
+  un carrito de prueba real (dirección `co` + `cart_id`) antes y
+  después del vínculo.
+
+## Nota de implementación 2 (2026-08-29): corrección — no existe plugin real para PayU LatAm
+
+Antes de instalar nada se verificó el código/README real de los dos
+únicos paquetes de Medusa que aparecen buscando "PayU" — misma
+disciplina que ya aplicó ADR 0006 al plugin de Meilisearch, esta vez
+con un resultado distinto: **ninguno de los dos sirve.**
+
+- `@tax1driver/medusa-payu`: opciones de configuración `clientId`,
+  `clientSecret`, `merchantPosId`, `secondKey` — terminología exacta
+  de la API de **PayU Polonia/CEE** (OAuth + `posId`), no de PayU
+  LatAm.
+- `medusa-plugin-payu` (`rigby-sh/medusa-plugin-payu`): mismo problema
+  (`clientId`, `posId`, sandbox en `secure.snd.payu.com`, dominio de
+  PayU Europa) y además **archivado desde 2025-03-21** — sin
+  mantenimiento.
+- La API real que se necesita, PayU LatAm
+  (`developers.payulatam.com`, la que cubre Colombia junto con
+  Argentina/Brasil/Chile/México/Panamá/Perú), autentica con
+  `apiLogin`/`apiKey` en el objeto merchant y `accountId` en el
+  objeto order — un modelo de autenticación distinto, no solo nombres
+  de campo distintos.
+
+"PayU" es una marca compartida por dos productos/API históricamente
+separados (LatAm vs. Europa/CEE); un paquete que dice "PayU" a secas
+sin especificar LatAm es, con alta probabilidad, para el producto
+europeo. **Consecuencia:** la integración de pago se implementa como
+módulo custom de Medusa (`AbstractPaymentProvider`) contra
+`developers.payulatam.com` directamente — mismo tipo de esfuerzo que
+ya se había anticipado para EnvíoClick en §2, no una instalación de
+plugin como asumía la decisión original de este ADR.

workloads/docs-portal/mkdocs.yml

@@ -96,6 +96,7 @@ nav:
       - "0006 · Motor de búsqueda y facetas": decisiones/0006-motor-busqueda-facetas.md
       - "0007 · Identidad visual propia": decisiones/0007-identidad-visual-propia.md
       - "0008 · Identidad Navy & Coral": decisiones/0008-identidad-navy-coral.md
+      - "0009 · Checkout real": decisiones/0009-checkout-real.md
       - Plantilla ADR: decisiones/plantilla-adr.md
   - Playbooks:
       - Crashloop Medusa: playbooks/incidente-crashloop-medusa.md

workloads/docs-portal/patches/deployment.yaml

@@ -25,7 +25,7 @@ spec:
         runAsNonRoot: false
       containers:
         - name: app
-          image: gitea.cruzcloud.net/devops/docs-portal:v1.0.188
+          image: gitea.cruzcloud.net/devops/docs-portal:v1.0.224
           # El base saca TODAS las capabilities. Probado en vivo y
           # revertido: con drop: ALL (aunque se agregue NET_BIND_SERVICE
           # de vuelta) el propio entrypoint de nginx:1.27-alpine falla al

workloads/ecommerce/app/api/cart/address/route.ts

@@ -0,0 +1,14 @@
+import { setShippingAddress } from "@/lib/headless/providers/medusa-cart";
+
+export async function POST(request: Request) {
+  const { cartId, ...address } = await request.json();
+  if (!cartId || !address.firstName || !address.address1 || !address.city || !address.phone || !address.email) {
+    return Response.json({ error: "Faltan campos obligatorios de la dirección" }, { status: 400 });
+  }
+  try {
+    const cart = await setShippingAddress(cartId, address);
+    return Response.json(cart);
+  } catch (error) {
+    return Response.json({ error: (error as Error).message }, { status: 502 });
+  }
+}

workloads/ecommerce/app/api/cart/complete/route.ts

@@ -0,0 +1,14 @@
+import { completeCart } from "@/lib/headless/providers/medusa-payment";
+
+export async function POST(request: Request) {
+  const { cartId } = await request.json();
+  if (!cartId) {
+    return Response.json({ error: "Falta cartId" }, { status: 400 });
+  }
+  try {
+    await completeCart(cartId);
+    return Response.json({ ok: true });
+  } catch (error) {
+    return Response.json({ error: (error as Error).message }, { status: 502 });
+  }
+}

workloads/ecommerce/app/api/cart/items/[lineItemId]/route.ts

@@ -0,0 +1,31 @@
+import { removeLineItem, updateLineItemQuantity } from "@/lib/headless/providers/medusa-cart";
+
+interface RouteParams { params: Promise<{ lineItemId: string }> }
+
+export async function POST(request: Request, { params }: RouteParams) {
+  const { lineItemId } = await params;
+  const { cartId, quantity } = await request.json();
+  if (!cartId || typeof quantity !== "number") {
+    return Response.json({ error: "cartId y quantity son obligatorios" }, { status: 400 });
+  }
+  try {
+    const cart = await updateLineItemQuantity(cartId, lineItemId, quantity);
+    return Response.json(cart);
+  } catch (error) {
+    return Response.json({ error: (error as Error).message }, { status: 502 });
+  }
+}
+
+export async function DELETE(request: Request, { params }: RouteParams) {
+  const { lineItemId } = await params;
+  const cartId = new URL(request.url).searchParams.get("cartId");
+  if (!cartId) {
+    return Response.json({ error: "cartId es obligatorio" }, { status: 400 });
+  }
+  try {
+    const cart = await removeLineItem(cartId, lineItemId);
+    return Response.json(cart);
+  } catch (error) {
+    return Response.json({ error: (error as Error).message }, { status: 502 });
+  }
+}

workloads/ecommerce/app/api/cart/items/route.ts

@@ -0,0 +1,14 @@
+import { addLineItem } from "@/lib/headless/providers/medusa-cart";
+
+export async function POST(request: Request) {
+  const { cartId, variantId, quantity } = await request.json();
+  if (!cartId || !variantId) {
+    return Response.json({ error: "cartId y variantId son obligatorios" }, { status: 400 });
+  }
+  try {
+    const cart = await addLineItem(cartId, variantId, quantity ?? 1);
+    return Response.json(cart);
+  } catch (error) {
+    return Response.json({ error: (error as Error).message }, { status: 502 });
+  }
+}

workloads/ecommerce/app/api/cart/payment/banks/route.ts

@@ -0,0 +1,10 @@
+import { getPseBanks } from "@/lib/headless/providers/medusa-payment";
+
+export async function GET() {
+  try {
+    const banks = await getPseBanks();
+    return Response.json({ banks });
+  } catch (error) {
+    return Response.json({ error: (error as Error).message }, { status: 502 });
+  }
+}

workloads/ecommerce/app/api/cart/payment/session/route.ts

@@ -0,0 +1,15 @@
+import { createPaymentCollection, createPsePaymentSession } from "@/lib/headless/providers/medusa-payment";
+
+export async function POST(request: Request) {
+  const { cartId, ...pse } = await request.json();
+  if (!cartId || !pse.bankCode || !pse.docNumber || !pse.firstName || !pse.lastName || !pse.email || !pse.phone) {
+    return Response.json({ error: "Faltan campos obligatorios para el pago con PSE" }, { status: 400 });
+  }
+  try {
+    const paymentCollectionId = await createPaymentCollection(cartId);
+    const bankUrl = await createPsePaymentSession(paymentCollectionId, pse);
+    return Response.json({ bankUrl });
+  } catch (error) {
+    return Response.json({ error: (error as Error).message }, { status: 502 });
+  }
+}

workloads/ecommerce/app/api/cart/route.ts

@@ -0,0 +1,28 @@
+import { createCart, getCart } from "@/lib/headless/providers/medusa-cart";
+
+// cart-store.ts es "use client" y no puede pegarle directo a Medusa
+// (MEDUSA_BACKEND_URL es DNS interno del cluster, no resuelve desde el
+// navegador) -- mismo motivo que /api/search. Nunca cachear: es
+// estado mutable por sesion, no catalogo.
+
+export async function POST() {
+  try {
+    const cart = await createCart();
+    return Response.json(cart);
+  } catch (error) {
+    return Response.json({ error: (error as Error).message }, { status: 502 });
+  }
+}
+
+export async function GET(request: Request) {
+  const cartId = new URL(request.url).searchParams.get("cartId");
+  if (!cartId) {
+    return Response.json({ error: "cartId es obligatorio" }, { status: 400 });
+  }
+  try {
+    const cart = await getCart(cartId);
+    return Response.json(cart);
+  } catch (error) {
+    return Response.json({ error: (error as Error).message }, { status: 502 });
+  }
+}

workloads/ecommerce/app/api/cart/shipping-method/route.ts

@@ -0,0 +1,14 @@
+import { addShippingMethod } from "@/lib/headless/providers/medusa-cart";
+
+export async function POST(request: Request) {
+  const { cartId, optionId } = await request.json();
+  if (!cartId || !optionId) {
+    return Response.json({ error: "cartId y optionId son obligatorios" }, { status: 400 });
+  }
+  try {
+    const cart = await addShippingMethod(cartId, optionId);
+    return Response.json(cart);
+  } catch (error) {
+    return Response.json({ error: (error as Error).message }, { status: 502 });
+  }
+}

workloads/ecommerce/app/api/cart/shipping-options/route.ts

@@ -0,0 +1,14 @@
+import { getShippingOptions } from "@/lib/headless/providers/medusa-cart";
+
+export async function GET(request: Request) {
+  const cartId = new URL(request.url).searchParams.get("cartId");
+  if (!cartId) {
+    return Response.json({ error: "cartId es obligatorio" }, { status: 400 });
+  }
+  try {
+    const options = await getShippingOptions(cartId);
+    return Response.json({ options });
+  } catch (error) {
+    return Response.json({ error: (error as Error).message }, { status: 502 });
+  }
+}

workloads/ecommerce/app/api/customer/google/callback/route.ts

@@ -0,0 +1,14 @@
+import { handleGoogleCallback } from "@/lib/headless/providers/medusa-customer";
+
+export async function POST(request: Request) {
+  const { code, state } = await request.json();
+  if (!code || !state) {
+    return Response.json({ error: "Faltan parámetros de Google" }, { status: 400 });
+  }
+  try {
+    const customer = await handleGoogleCallback(code, state);
+    return Response.json(customer);
+  } catch (error) {
+    return Response.json({ error: (error as Error).message }, { status: 400 });
+  }
+}

workloads/ecommerce/app/api/customer/google/start/route.ts

@@ -0,0 +1,14 @@
+import { getGoogleAuthUrl } from "@/lib/headless/providers/medusa-customer";
+
+// Navegacion de pagina completa (no fetch/XHR) -- el boton "Continuar
+// con Google" enlaza directo aca, el browser sigue el 302 hasta la
+// pantalla real de consentimiento de Google.
+export async function GET(request: Request) {
+  try {
+    const location = await getGoogleAuthUrl();
+    return Response.redirect(location);
+  } catch (error) {
+    const message = encodeURIComponent((error as Error).message);
+    return Response.redirect(new URL(`/?googleAuthError=${message}`, request.url));
+  }
+}

workloads/ecommerce/app/api/customer/login/route.ts

@@ -0,0 +1,14 @@
+import { loginCustomer } from "@/lib/headless/providers/medusa-customer";
+
+export async function POST(request: Request) {
+  const { email, password } = await request.json();
+  if (!email || !password) {
+    return Response.json({ error: "Correo y contraseña son obligatorios" }, { status: 400 });
+  }
+  try {
+    const customer = await loginCustomer(email, password);
+    return Response.json(customer);
+  } catch (error) {
+    return Response.json({ error: (error as Error).message }, { status: 400 });
+  }
+}

workloads/ecommerce/app/api/customer/me/route.ts

@@ -0,0 +1,14 @@
+import { getCurrentCustomer } from "@/lib/headless/providers/medusa-customer";
+
+export async function GET(request: Request) {
+  const token = new URL(request.url).searchParams.get("token");
+  if (!token) {
+    return Response.json({ error: "token es obligatorio" }, { status: 400 });
+  }
+  try {
+    const customer = await getCurrentCustomer(token);
+    return Response.json(customer);
+  } catch (error) {
+    return Response.json({ error: (error as Error).message }, { status: 401 });
+  }
+}

workloads/ecommerce/app/api/customer/register/route.ts

@@ -0,0 +1,14 @@
+import { registerCustomer } from "@/lib/headless/providers/medusa-customer";
+
+export async function POST(request: Request) {
+  const { email, password, firstName, lastName } = await request.json();
+  if (!email || !password || !firstName || !lastName) {
+    return Response.json({ error: "Faltan campos obligatorios" }, { status: 400 });
+  }
+  try {
+    const customer = await registerCustomer(email, password, firstName, lastName);
+    return Response.json(customer);
+  } catch (error) {
+    return Response.json({ error: (error as Error).message }, { status: 400 });
+  }
+}

workloads/ecommerce/app/auth/google/callback/page.tsx

@@ -0,0 +1,10 @@
+import { Suspense } from "react";
+import { GoogleCallbackClient } from "@/components/account/google-callback-client";
+
+export default function GoogleCallbackPage() {
+  return (
+    <Suspense>
+      <GoogleCallbackClient />
+    </Suspense>
+  );
+}

workloads/ecommerce/app/checkout/page.tsx

@@ -0,0 +1,5 @@
+import { CheckoutClient } from "@/components/checkout/checkout-client";
+
+export default function CheckoutPage() {
+  return <CheckoutClient />;
+}

workloads/ecommerce/app/checkout/pse/return/page.tsx

@@ -0,0 +1,10 @@
+import { Suspense } from "react";
+import { PseReturnClient } from "@/components/checkout/pse-return-client";
+
+export default function PseReturnPage() {
+  return (
+    <Suspense fallback={null}>
+      <PseReturnClient />
+    </Suspense>
+  );
+}

workloads/ecommerce/app/page.tsx

@@ -1,3 +1,4 @@
+import Image from "next/image";
 import Link from "next/link";
 import { ArrowRight } from "lucide-react";
 import { CategoryTiles } from "@/components/home/category-tiles";
@@ -17,5 +18,24 @@ export const dynamic = "force-dynamic";
 export default async function HomePage() {
   const [products, categories] = await Promise.all([getProducts(), getCategories()]);
   const treasures = products.filter((product) => product.isNew || product.featured).slice(0, 8);
-  return <><HeroCarousel /><TrustBar /><div className="content-auto"><CategoryTiles categories={categories} /></div><section className="content-auto mx-auto max-w-7xl px-4 py-14"><div className="mb-8 flex items-end justify-between gap-5"><div><span className="text-xs font-black uppercase tracking-[.18em] text-fuchsia-600">Novedades</span><h2 className="mt-2 text-4xl font-black tracking-tight sm:text-5xl">Tesoros recién llegados</h2><p className="mt-3 text-slate-500">Desliza y encuentra nuevos favoritos.</p></div><Button asChild variant="outline" className="hidden sm:inline-flex"><Link href="/catalog">Ver catálogo <ArrowRight className="size-4" /></Link></Button></div><ProductCarousel products={treasures} /></section><section className="content-auto mx-auto max-w-7xl px-4 pb-20"><div className="grid overflow-hidden rounded-[2rem] bg-gradient-to-r from-cyan-500 via-blue-600 to-violet-600 text-white shadow-2xl lg:grid-cols-[1fr_.7fr]"><div className="p-8 sm:p-12"><span className="text-xs font-black uppercase tracking-[.18em] text-yellow-300">Club ARI</span><h2 className="mt-3 text-4xl font-black tracking-tight sm:text-6xl">Promociones, lanzamientos y mucha diversión.</h2><p className="mt-5 max-w-xl text-white/80">Únete a nuestra comunidad y recibe primero las novedades del catálogo.</p><Button variant="yellow" size="lg" className="mt-7">Quiero unirme</Button></div><div className="min-h-64 bg-[url('/images/promo/promo-backpacks.webp')] bg-cover bg-center" /></div></section></>;
+  return <><HeroCarousel /><TrustBar /><div className="content-auto"><CategoryTiles categories={categories} /></div><section className="content-auto mx-auto max-w-7xl px-4 py-14"><div className="mb-8 flex items-end justify-between gap-5"><div><span className="text-xs font-black uppercase tracking-[.18em] text-ari-coral">Novedades</span><h2 className="mt-2 text-4xl font-black tracking-tight sm:text-5xl">Tesoros recién llegados</h2><p className="mt-3 text-slate-500">Desliza y encuentra nuevos favoritos.</p></div><Button asChild variant="outline" className="hidden sm:inline-flex"><Link href="/catalog">Ver catálogo <ArrowRight className="size-4" /></Link></Button></div><ProductCarousel products={treasures} /></section><section className="content-auto mx-auto max-w-7xl px-4 pb-20"><div className="grid overflow-hidden rounded-[2rem] bg-ari-marino text-white shadow-2xl lg:grid-cols-[1fr_.7fr]"><div className="p-8 sm:p-12"><span className="text-xs font-black uppercase tracking-[.18em] text-ari-coral-claro">Club ARI</span><h2 className="mt-3 text-4xl font-black tracking-tight sm:text-6xl">Promociones, lanzamientos y mucha diversión.</h2><p className="mt-5 max-w-xl text-white/80">Únete a nuestra comunidad y recibe primero las novedades del catálogo.</p><Button variant="yellow" size="lg" className="mt-7">Quiero unirme</Button></div>{/* No hay herramienta de generacion de imagenes disponible para crear un
+    asset nuevo -- se reconstruye el mismo efecto (fondo punteado +
+    fotos estilo polaroid) con CSS y fotos reales de producto ya
+    existentes, en azul/amarillo de marca en vez del violeta original
+    de promo-backpacks.webp. */}
+<div className="relative min-h-64 overflow-hidden bg-ari-coral-claro">
+  <div className="absolute inset-0 [background-image:radial-gradient(rgba(0,85,184,0.35)_1.5px,transparent_1.5px)] [background-size:18px_18px]" />
+  <div className="absolute -bottom-12 -left-12 size-52 rounded-full bg-ari-marino" />
+  <div className="absolute inset-0 flex items-center justify-center gap-3 p-6">
+    <div className="relative size-28 -rotate-6 overflow-hidden rounded-xl border-4 border-white bg-white shadow-xl sm:size-32">
+      <Image src="/images/products/ari-011-mochila-escolar-de-spider-man-de-disney-.webp" alt="" fill sizes="128px" className="object-cover" />
+    </div>
+    <div className="relative size-28 rotate-3 overflow-hidden rounded-xl border-4 border-white bg-white shadow-xl sm:size-32">
+      <Image src="/images/products/ari-016-disney-mochila-iron-man-de-poliester-ult.webp" alt="" fill sizes="128px" className="object-cover" />
+    </div>
+    <div className="relative hidden size-28 -rotate-3 overflow-hidden rounded-xl border-4 border-white bg-white shadow-xl sm:block sm:size-32">
+      <Image src="/images/products/ari-009-mochilas-disney-coleccion-marvel.webp" alt="" fill sizes="128px" className="object-cover" />
+    </div>
+  </div>
+</div></div></section></>;
 }

workloads/ecommerce/commerce/configmap.yaml

@@ -24,3 +24,12 @@ data:
   # env var del plugin, no del servidor Meilisearch en si -- ver
   # MEILI_MASTER_KEY en secrets.template.yaml).
   MEILISEARCH_HOST: http://meilisearch-svc:7700
+
+  # ePayco (ADR 0009 -- tercer proveedor evaluado, ver medusa-config.ts
+  # para el historial completo) -- solo URLs/config no sensible,
+  # credenciales reales (publicKey/privateKey/pCustIdCliente/pKey) van en
+  # secrets.template.yaml. EPAYCO_ENV=sandbox hasta que haya credenciales
+  # de produccion reales.
+  EPAYCO_ENV: sandbox
+  EPAYCO_RESPONSE_URL: https://shop.cruzcloud.net/checkout/pse/return
+  EPAYCO_NOTIFY_URL: https://commerce.cruzcloud.net/hooks/payment/epayco_pse

workloads/ecommerce/commerce/medusa/patches/deployment.yaml

@@ -65,7 +65,7 @@ spec:
               memory: 64Mi
 
         - name: migrations
-          image: gitea.cruzcloud.net/devops/ecommerce-medusa:v1.0.168
+          image: gitea.cruzcloud.net/devops/ecommerce-medusa:v1.0.229
           imagePullPolicy: IfNotPresent
           command:
             - node
@@ -86,7 +86,7 @@ spec:
 
       containers:
         - name: app
-          image: gitea.cruzcloud.net/devops/ecommerce-medusa:v1.0.168
+          image: gitea.cruzcloud.net/devops/ecommerce-medusa:v1.0.229
           imagePullPolicy: IfNotPresent
           envFrom:
             - configMapRef:

workloads/ecommerce/commerce/secrets.template.yaml

@@ -35,6 +35,18 @@ stringData:
   # commerce-storefront: el subscriber de Medusa lo envía como header
   # x-revalidate-secret al invocar POST /api/revalidate en el storefront.
   REVALIDATE_SECRET: CAMBIAR
+
+  # ePayco (ADR 0009 -- tercer proveedor evaluado: PayU LatAm quedó
+  # inviable porque Rapyd compró ese negocio en 2023, Rapyd descartado
+  # por costo; ePayco es de Davivienda desde 2024, mejor tarifa PSE para
+  # el volumen real del usuario). Credenciales del comercio real, nunca
+  # hardcodeadas acá. p_cust_id_cliente/p_key son valores propios del
+  # dashboard de ePayco (Configuración > Llaves secretas), distintos de
+  # publicKey/privateKey.
+  EPAYCO_PUBLIC_KEY: CAMBIAR
+  EPAYCO_PRIVATE_KEY: CAMBIAR
+  EPAYCO_P_CUST_ID_CLIENTE: CAMBIAR
+  EPAYCO_P_KEY: CAMBIAR
 ---
 apiVersion: v1
 kind: Secret

workloads/ecommerce/components/account/account-dialog.tsx

@@ -0,0 +1,99 @@
+"use client";
+
+import Link from "next/link";
+import { LogOut, MessageCircle, PackageCheck } from "lucide-react";
+import { type FormEvent, useState } from "react";
+import { Button } from "@/components/ui/button";
+import { Dialog, DialogContent } from "@/components/ui/dialog";
+import { Input } from "@/components/ui/input";
+import { useCustomerStore } from "@/store/customer-store";
+
+type Mode = "login" | "register";
+
+function GoogleIcon() {
+  return (
+    <svg viewBox="0 0 48 48" className="size-4" aria-hidden="true">
+      <path fill="#FFC107" d="M43.6 20.5H42V20H24v8h11.3c-1.6 4.7-6.1 8-11.3 8-6.6 0-12-5.4-12-12s5.4-12 12-12c3.1 0 5.8 1.1 8 3l6-6C34 5.1 29.3 3 24 3 12.4 3 3 12.4 3 24s9.4 21 21 21 21-9.4 21-21c0-1.4-.1-2.7-.4-3.5z" />
+      <path fill="#FF3D00" d="M6.3 14.7l6.6 4.8C14.6 15.9 18.9 13 24 13c3.1 0 5.8 1.1 8 3l6-6C34 5.1 29.3 3 24 3 16.1 3 9.3 7.6 6.3 14.7z" />
+      <path fill="#4CAF50" d="M24 45c5.2 0 9.9-2 13.4-5.2l-6.2-5.2c-2 1.5-4.6 2.4-7.2 2.4-5.2 0-9.6-3.3-11.3-8l-6.5 5C9.2 40.3 16 45 24 45z" />
+      <path fill="#1976D2" d="M43.6 20.5H42V20H24v8h11.3c-.8 2.3-2.2 4.3-4.1 5.6l6.2 5.2C41.4 35.9 45 30.5 45 24c0-1.4-.1-2.7-.4-3.5z" />
+    </svg>
+  );
+}
+
+export function AccountDialog({ open, onOpenChange }: { open: boolean; onOpenChange: (open: boolean) => void }) {
+  const { customer, hasHydrated, loading, error, login, register, logout } = useCustomerStore();
+  const [mode, setMode] = useState<Mode>("login");
+  const [form, setForm] = useState({ email: "", password: "", firstName: "", lastName: "" });
+
+  async function submit(event: FormEvent) {
+    event.preventDefault();
+    const ok = mode === "login"
+      ? await login(form.email, form.password)
+      : await register(form.email, form.password, form.firstName, form.lastName);
+    if (ok) setForm({ email: "", password: "", firstName: "", lastName: "" });
+  }
+
+  const isLoggedIn = hasHydrated && customer !== null;
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="max-w-lg p-7">
+        <div className="pr-10">
+          {isLoggedIn ? (
+            <>
+              <span className="text-xs font-black uppercase tracking-[.16em] text-ari-coral">Tu cuenta</span>
+              <h2 className="mt-3 text-3xl font-black">Hola, {customer.firstName ?? customer.email}</h2>
+              <p className="mt-3 text-sm leading-6 text-slate-600">{customer.email}</p>
+              <div className="mt-6 grid gap-3">
+                <Button asChild variant="outline"><Link href="/catalog" onClick={() => onOpenChange(false)}><PackageCheck />Ver mis opciones de compra</Link></Button>
+                <Button variant="ghost" onClick={logout}><LogOut className="size-4" />Cerrar sesión</Button>
+              </div>
+            </>
+          ) : (
+            <>
+              <span className="text-xs font-black uppercase tracking-[.16em] text-ari-coral">Atención personalizada</span>
+              <h2 className="mt-3 text-3xl font-black">{mode === "login" ? "Inicia sesión" : "Crea tu cuenta"}</h2>
+              <form onSubmit={submit} className="mt-5 space-y-3">
+                {mode === "register" && (
+                  <div className="grid gap-3 sm:grid-cols-2">
+                    <Input placeholder="Nombre" required value={form.firstName} onChange={(event) => setForm({ ...form, firstName: event.target.value })} />
+                    <Input placeholder="Apellido" required value={form.lastName} onChange={(event) => setForm({ ...form, lastName: event.target.value })} />
+                  </div>
+                )}
+                <Input type="email" placeholder="Correo" required value={form.email} onChange={(event) => setForm({ ...form, email: event.target.value })} />
+                <Input type="password" placeholder="Contraseña" required minLength={8} value={form.password} onChange={(event) => setForm({ ...form, password: event.target.value })} />
+                {error && <p className="text-sm font-bold text-rose-600">{error}</p>}
+                <Button type="submit" variant="primary" size="lg" className="w-full" disabled={loading}>
+                  {loading ? "Un momento…" : mode === "login" ? "Iniciar sesión" : "Crear cuenta"}
+                </Button>
+              </form>
+              <div className="mt-3 flex items-center gap-3 text-xs font-bold uppercase tracking-wide text-slate-400">
+                <span className="h-px flex-1 bg-slate-100" />o<span className="h-px flex-1 bg-slate-100" />
+              </div>
+              <Button asChild variant="outline" size="lg" className="mt-3 w-full">
+                <a href="/api/customer/google/start">
+                  <GoogleIcon />Continuar con Google
+                </a>
+              </Button>
+              <button
+                type="button"
+                className="mt-3 text-sm font-bold text-ari-marino hover:underline"
+                onClick={() => setMode(mode === "login" ? "register" : "login")}
+              >
+                {mode === "login" ? "¿No tienes cuenta? Regístrate" : "¿Ya tienes cuenta? Inicia sesión"}
+              </button>
+              <div className="mt-6 border-t border-slate-100 pt-5">
+                <Button asChild variant="outline" className="w-full">
+                  <a href={process.env.NEXT_PUBLIC_WHATSAPP_URL ?? "https://wa.link/rvcqqc"} target="_blank" rel="noopener noreferrer">
+                    <MessageCircle />Hablar con ARI
+                  </a>
+                </Button>
+              </div>
+            </>
+          )}
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}

workloads/ecommerce/components/account/google-callback-client.tsx

@@ -0,0 +1,44 @@
+"use client";
+
+import { useRouter, useSearchParams } from "next/navigation";
+import { useEffect, useRef, useState } from "react";
+import { useCustomerStore } from "@/store/customer-store";
+
+export function GoogleCallbackClient() {
+  const router = useRouter();
+  const searchParams = useSearchParams();
+  const loginWithGoogle = useCustomerStore((state) => state.loginWithGoogle);
+  const [error, setError] = useState<string | null>(null);
+  const ran = useRef(false);
+
+  useEffect(() => {
+    // Guard contra el doble-mount de StrictMode -- el code de Google es
+    // de un solo uso, un segundo intento con el mismo code fallaria.
+    if (ran.current) return;
+    ran.current = true;
+
+    const code = searchParams.get("code");
+    const state = searchParams.get("state");
+    if (!code || !state) {
+      setError("Faltan parámetros de Google en la URL de retorno.");
+      return;
+    }
+
+    loginWithGoogle(code, state).then((ok) => {
+      router.replace(ok ? "/" : "/?googleAuthError=1");
+    });
+  }, [searchParams, loginWithGoogle, router]);
+
+  return (
+    <div className="flex min-h-[60vh] flex-col items-center justify-center gap-3 text-center">
+      {error ? (
+        <>
+          <p className="text-lg font-black text-rose-600">No se pudo iniciar sesión con Google</p>
+          <p className="text-sm text-slate-600">{error}</p>
+        </>
+      ) : (
+        <p className="text-sm font-bold text-slate-600">Conectando con Google…</p>
+      )}
+    </div>
+  );
+}

workloads/ecommerce/components/cart/cart-drawer.tsx

@@ -1,6 +1,7 @@
 "use client";
 
 import Image from "next/image";
+import Link from "next/link";
 import { Minus, Plus, ShoppingBag, Trash2 } from "lucide-react";
 import { Button } from "@/components/ui/button";
 import { Progress } from "@/components/ui/progress";
@@ -17,13 +18,6 @@ export function CartDrawer() {
   const progress = pricedItems ? Math.min(100, (subtotal / FREE_SHIPPING_THRESHOLD) * 100) : 0;
   const count = items.reduce((sum, item) => sum + item.quantity, 0);
 
-  const checkout = () => {
-    const lines = items.map((item) => `• ${item.quantity} x ${item.product.name}`).join("\n");
-    const message = `Hola Ari Shopping 👋\nQuiero consultar disponibilidad para:\n\n${lines}\n\nNombre:\nCiudad:\nForma de entrega:`;
-    void navigator.clipboard?.writeText(message);
-    window.open(process.env.NEXT_PUBLIC_WHATSAPP_URL ?? "https://wa.link/rvcqqc", "_blank", "noopener,noreferrer");
-  };
-
   return (
     <Sheet open={isOpen} onOpenChange={(open) => { if (!open) closeCart(); }}>
       <SheetContent>
@@ -49,7 +43,15 @@ export function CartDrawer() {
         <div className="space-y-4 border-t border-slate-100 p-6">
           <div><div className="mb-2 flex justify-between text-xs font-bold text-slate-600"><span>{pricedItems ? "Progreso para envío gratis" : "Cotización personalizada"}</span><span>{pricedItems ? `${Math.round(progress)}%` : "Por confirmar"}</span></div><Progress value={progress} /></div>
           <div className="flex items-center justify-between"><span className="font-bold text-slate-600">Subtotal</span><strong className="text-xl font-black">{pricedItems ? formatMoney(subtotal) : "Por confirmar"}</strong></div>
-          <Button variant="primary" size="lg" className="w-full" disabled={!items.length} onClick={checkout}>Continuar por WhatsApp</Button>
+          {/* Button asChild + disabled no funciona sobre un <a> (:disabled
+              es pseudo-clase de elementos de formulario, un Link nunca la
+              cumple) -- se ramifica en vez de confiar en el prop disabled
+              sobre un Link. */}
+          {items.length > 0 ? (
+            <Button asChild variant="primary" size="lg" className="w-full"><Link href="/checkout" onClick={closeCart}>Confirmar pedido</Link></Button>
+          ) : (
+            <Button variant="primary" size="lg" className="w-full" disabled>Confirmar pedido</Button>
+          )}
           <Button variant="ghost" className="w-full" disabled={!items.length} onClick={clearCart}>Vaciar carrito</Button>
         </div>
       </SheetContent>

workloads/ecommerce/components/catalog/catalog-client.tsx

@@ -352,7 +352,11 @@ export function CatalogClient({
       </div>
 
       <div className="grid gap-8 lg:grid-cols-[260px_1fr]">
-        <aside className="h-fit space-y-6 rounded-lg border border-slate-100 bg-white p-6 shadow-lg shadow-ari-marino/5 lg:sticky lg:top-44">
+        {/* overflow-y-auto + max-h propio en lg: sticky no le da scroll
+            propio al contenido, y con 30+ categorias mas marca/edad/precio
+            el panel se pasa del viewport sin forma de llegar al resto salvo
+            bajando el zoom del navegador (reportado en vivo). */}
+        <aside className="h-fit space-y-6 overflow-y-auto rounded-lg border border-slate-100 bg-white p-6 shadow-lg shadow-ari-marino/5 lg:sticky lg:top-44 lg:max-h-[calc(100vh-13rem)]">
           <div className="flex items-center justify-between">
             <strong className="flex items-center gap-2 text-lg font-black">
               <SlidersHorizontal className="size-5 text-ari-coral-claro" />

workloads/ecommerce/components/checkout/checkout-client.tsx

@@ -0,0 +1,313 @@
+"use client";
+
+import Image from "next/image";
+import Link from "next/link";
+import { ArrowLeft, Landmark, MapPin, MessageCircle, Truck } from "lucide-react";
+import { type FormEvent, useState } from "react";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { ciudadesPorDepartamento, departamentos } from "@/lib/data/colombia";
+import { formatMoney } from "@/lib/utils";
+import { useCartStore } from "@/store/cart-store";
+
+const SELECT_CLASS =
+  "h-12 w-full rounded-full border border-slate-200 bg-white px-5 text-sm text-slate-950 outline-none transition focus:border-cyan-500 focus:ring-4 focus:ring-cyan-300/30 disabled:opacity-50";
+
+// ADR 0009: direccion + envio + pago real, todo contra el Store API real.
+// El pago es ePayco/PSE (modulo custom del backend, ver
+// workloads/commerce-backend/src/modules/epayco-pse) -- redirige al banco
+// del comprador, la confirmacion real llega despues via webhook async
+// (nunca por esta pantalla). WhatsApp queda como respaldo manual si la
+// iniciacion del pago falla, ya no como camino principal.
+
+interface ShippingOption {
+  id: string;
+  name: string;
+  amount: number;
+}
+
+interface PseBank {
+  pseCode: string;
+  description: string;
+}
+
+type Step = "address" | "shipping" | "payment";
+
+async function postJson(url: string, body: unknown) {
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  return response.json();
+}
+
+export function CheckoutClient() {
+  const { cartId, items, hasHydrated } = useCartStore();
+  const [step, setStep] = useState<Step>("address");
+  const [form, setForm] = useState({
+    firstName: "",
+    lastName: "",
+    address1: "",
+    // Se guarda el id DIVIPOLA seleccionado, no el texto libre -- ver
+    // lib/data/colombia.ts. El nombre real se deriva de este id para
+    // mandarlo a Medusa (que solo espera texto en shipping_address).
+    departmentId: null as number | null,
+    cityId: null as number | null,
+    phone: "",
+    email: "",
+  });
+  const availableCities = form.departmentId ? ciudadesPorDepartamento(form.departmentId) : [];
+  const selectedDepartamento = departamentos.find((departamento) => departamento.id === form.departmentId);
+  const selectedCiudad = availableCities.find((ciudad) => ciudad.id === form.cityId);
+  const [shippingOptions, setShippingOptions] = useState<ShippingOption[]>([]);
+  const [selectedOptionId, setSelectedOptionId] = useState<string | null>(null);
+  const [shippingTotal, setShippingTotal] = useState(0);
+  const [total, setTotal] = useState(0);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [banks, setBanks] = useState<PseBank[]>([]);
+  const [bankCode, setBankCode] = useState("");
+  const [userType, setUserType] = useState<"0" | "1">("0");
+  const [docType, setDocType] = useState<"CC" | "CE" | "NIT" | "TI" | "PP">("CC");
+  const [docNumber, setDocNumber] = useState("");
+
+  const itemsSubtotal = items.reduce((sum, item) => sum + (item.product.price ?? 0) * item.quantity, 0);
+  const currency = items[0]?.product.currency;
+
+  async function submitAddress(event: FormEvent) {
+    event.preventDefault();
+    if (!cartId || !selectedCiudad || !selectedDepartamento) return;
+    setLoading(true);
+    setError(null);
+    try {
+      const cart = await postJson("/api/cart/address", {
+        cartId,
+        firstName: form.firstName,
+        lastName: form.lastName,
+        address1: form.address1,
+        city: selectedCiudad.name,
+        province: selectedDepartamento.name,
+        phone: form.phone,
+        email: form.email,
+      });
+      if (cart.error) throw new Error(cart.error);
+      const response = await fetch(`/api/cart/shipping-options?cartId=${cartId}`);
+      const data = await response.json();
+      const options: ShippingOption[] = data.options ?? [];
+      setShippingOptions(options);
+      setSelectedOptionId(options[0]?.id ?? null);
+      setStep("shipping");
+    } catch (submitError) {
+      setError((submitError as Error).message);
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  async function submitShipping() {
+    if (!cartId || !selectedOptionId) return;
+    setLoading(true);
+    setError(null);
+    try {
+      const cart = await postJson("/api/cart/shipping-method", { cartId, optionId: selectedOptionId });
+      if (cart.error) throw new Error(cart.error);
+      setShippingTotal(cart.shippingTotal ?? 0);
+      setTotal(cart.total ?? itemsSubtotal);
+      const banksResponse = await fetch("/api/cart/payment/banks");
+      const banksData = await banksResponse.json();
+      const bankList: PseBank[] = banksData.banks ?? [];
+      setBanks(bankList);
+      setBankCode(bankList[0]?.pseCode ?? "");
+      setStep("payment");
+    } catch (submitError) {
+      setError((submitError as Error).message);
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  async function submitPayment(event: FormEvent) {
+    event.preventDefault();
+    if (!cartId || !bankCode || !docNumber || !selectedCiudad || !selectedDepartamento) return;
+    setLoading(true);
+    setError(null);
+    try {
+      const session = await postJson("/api/cart/payment/session", {
+        cartId,
+        bankCode,
+        userType,
+        docType,
+        docNumber,
+        firstName: form.firstName,
+        lastName: form.lastName,
+        email: form.email,
+        phone: form.phone,
+        city: selectedCiudad.name,
+      });
+      if (session.error) throw new Error(session.error);
+      const completion = await postJson("/api/cart/complete", { cartId });
+      if (completion.error) throw new Error(completion.error);
+      // Navegacion completa, no iframe -- asi lo exige ePayco para el
+      // flujo de PSE. La confirmacion real llega despues via webhook,
+      // esta pagina nunca vuelve a cargar sola.
+      window.location.href = session.bankUrl;
+    } catch (submitError) {
+      setError((submitError as Error).message);
+      setLoading(false);
+    }
+  }
+
+  function continueOnWhatsApp() {
+    const lines = items.map((item) => `• ${item.quantity} x ${item.product.name}`).join("\n");
+    const message = `Hola Ari Shopping 👋\nQuiero confirmar mi pedido:\n\n${lines}\n\nSubtotal: ${formatMoney(itemsSubtotal, currency)}\nEnvío: ${formatMoney(shippingTotal, currency)}\nTotal: ${formatMoney(total, currency)}\n\nNombre: ${form.firstName} ${form.lastName}\nDirección: ${form.address1}, ${selectedCiudad?.name ?? ""}${selectedDepartamento ? `, ${selectedDepartamento.name}` : ""}\nTeléfono: ${form.phone}`;
+    void navigator.clipboard?.writeText(message);
+    window.open(process.env.NEXT_PUBLIC_WHATSAPP_URL ?? "https://wa.link/rvcqqc", "_blank", "noopener,noreferrer");
+  }
+
+  if (!hasHydrated) return null;
+
+  if (items.length === 0) {
+    return (
+      <div className="mx-auto max-w-lg px-4 py-24 text-center">
+        <p className="text-lg font-bold">Tu carrito está vacío.</p>
+        <Button asChild variant="primary" className="mt-6"><Link href="/catalog">Ver catálogo</Link></Button>
+      </div>
+    );
+  }
+
+  return (
+    <div className="mx-auto grid max-w-5xl gap-10 px-4 py-10 lg:grid-cols-[1fr_.8fr] lg:py-16">
+      <div>
+        <Link href="/" className="mb-6 inline-flex items-center gap-1.5 text-sm font-bold text-slate-500 hover:text-ari-marino"><ArrowLeft className="size-4" />Seguir comprando</Link>
+        <h1 className="text-3xl font-black tracking-tight sm:text-4xl">Confirmar pedido</h1>
+
+        {step === "address" && (
+          <form onSubmit={submitAddress} className="mt-8 space-y-4">
+            <div className="grid gap-4 sm:grid-cols-2">
+              <Input placeholder="Nombre" required value={form.firstName} onChange={(event) => setForm({ ...form, firstName: event.target.value })} />
+              <Input placeholder="Apellido" required value={form.lastName} onChange={(event) => setForm({ ...form, lastName: event.target.value })} />
+            </div>
+            <Input placeholder="Dirección" required value={form.address1} onChange={(event) => setForm({ ...form, address1: event.target.value })} />
+            <div className="grid gap-4 sm:grid-cols-2">
+              <select
+                required
+                value={form.departmentId ?? ""}
+                onChange={(event) => setForm({ ...form, departmentId: Number(event.target.value) || null, cityId: null })}
+                className={SELECT_CLASS}
+              >
+                <option value="" disabled>Departamento</option>
+                {departamentos.map((departamento) => <option key={departamento.id} value={departamento.id}>{departamento.name}</option>)}
+              </select>
+              <select
+                required
+                disabled={!form.departmentId}
+                value={form.cityId ?? ""}
+                onChange={(event) => setForm({ ...form, cityId: Number(event.target.value) || null })}
+                className={SELECT_CLASS}
+              >
+                <option value="" disabled>Ciudad</option>
+                {availableCities.map((ciudad) => <option key={ciudad.id} value={ciudad.id}>{ciudad.name}</option>)}
+              </select>
+            </div>
+            <div className="grid gap-4 sm:grid-cols-2">
+              <Input placeholder="Teléfono" required value={form.phone} onChange={(event) => setForm({ ...form, phone: event.target.value })} />
+              <Input type="email" placeholder="Correo" required value={form.email} onChange={(event) => setForm({ ...form, email: event.target.value })} />
+            </div>
+            {error && <p className="text-sm font-bold text-rose-600">{error}</p>}
+            <Button type="submit" variant="primary" size="lg" className="w-full" disabled={loading}>{loading ? "Guardando…" : "Continuar a envío"}</Button>
+          </form>
+        )}
+
+        {step === "shipping" && (
+          <div className="mt-8 space-y-4">
+            <p className="flex items-center gap-2 text-sm font-bold text-slate-500"><MapPin className="size-4" />{form.address1}, {selectedCiudad?.name}{selectedDepartamento ? `, ${selectedDepartamento.name}` : ""}</p>
+            <div className="space-y-3">
+              {shippingOptions.map((option) => (
+                <label key={option.id} className={`flex cursor-pointer items-center justify-between rounded-2xl border-2 p-4 transition ${selectedOptionId === option.id ? "border-ari-marino bg-ari-marino/5" : "border-slate-200"}`}>
+                  <span className="flex items-center gap-3 font-bold"><Truck className="size-5 text-ari-marino" />{option.name}</span>
+                  <span className="flex items-center gap-3">
+                    <span className="font-black">{formatMoney(option.amount, currency)}</span>
+                    <input type="radio" name="shipping" checked={selectedOptionId === option.id} onChange={() => setSelectedOptionId(option.id)} />
+                  </span>
+                </label>
+              ))}
+              {shippingOptions.length === 0 && <p className="text-sm text-slate-500">No hay opciones de envío disponibles para esta dirección.</p>}
+            </div>
+            {error && <p className="text-sm font-bold text-rose-600">{error}</p>}
+            <Button variant="primary" size="lg" className="w-full" disabled={loading || !selectedOptionId} onClick={submitShipping}>{loading ? "Guardando…" : "Continuar"}</Button>
+          </div>
+        )}
+
+        {step === "payment" && (
+          <form onSubmit={submitPayment} className="mt-8 space-y-4">
+            <div className="rounded-2xl border border-slate-200 p-5">
+              <p className="text-xs font-black uppercase tracking-wide text-slate-400">Entrega</p>
+              <p className="mt-1 font-bold">{form.firstName} {form.lastName}</p>
+              <p className="text-sm text-slate-500">{form.address1}, {selectedCiudad?.name}{selectedDepartamento ? `, ${selectedDepartamento.name}` : ""}</p>
+              <p className="text-sm text-slate-500">{form.phone}</p>
+            </div>
+
+            <p className="flex items-center gap-2 text-sm font-bold text-slate-700"><Landmark className="size-4" />Paga con PSE (transferencia desde tu banco)</p>
+
+            {banks.length > 0 ? (
+              <select required value={bankCode} onChange={(event) => setBankCode(event.target.value)} className={SELECT_CLASS}>
+                {banks.map((bank) => <option key={bank.pseCode} value={bank.pseCode}>{bank.description}</option>)}
+              </select>
+            ) : (
+              <p className="rounded-2xl bg-yellow-50 p-3 text-xs font-bold leading-5 text-yellow-800">No pudimos cargar la lista de bancos — probá de nuevo en un momento, o confirmá tu pedido por WhatsApp abajo.</p>
+            )}
+
+            <div className="flex gap-4 text-sm font-bold">
+              <label className="flex items-center gap-2"><input type="radio" name="userType" checked={userType === "0"} onChange={() => setUserType("0")} />Persona natural</label>
+              <label className="flex items-center gap-2"><input type="radio" name="userType" checked={userType === "1"} onChange={() => setUserType("1")} />Persona jurídica</label>
+            </div>
+
+            <div className="grid gap-4 sm:grid-cols-2">
+              <select
+                required
+                value={docType}
+                onChange={(event) => setDocType(event.target.value as typeof docType)}
+                className={SELECT_CLASS}
+              >
+                <option value="CC">Cédula de ciudadanía</option>
+                <option value="CE">Cédula de extranjería</option>
+                <option value="TI">Tarjeta de identidad</option>
+                <option value="PP">Pasaporte</option>
+                <option value="NIT">NIT</option>
+              </select>
+              <Input placeholder="Número de documento" required value={docNumber} onChange={(event) => setDocNumber(event.target.value)} />
+            </div>
+
+            {error && <p className="text-sm font-bold text-rose-600">{error}</p>}
+
+            <Button type="submit" variant="primary" size="lg" className="w-full" disabled={loading || banks.length === 0}>{loading ? "Redirigiendo a tu banco…" : "Pagar con PSE"}</Button>
+
+            <div className="flex items-center gap-3 text-xs font-bold uppercase tracking-wide text-slate-400">
+              <span className="h-px flex-1 bg-slate-200" />¿Prefieres otra vía?<span className="h-px flex-1 bg-slate-200" />
+            </div>
+            <Button type="button" variant="outline" size="lg" className="w-full" onClick={continueOnWhatsApp}><MessageCircle className="size-5" />Confirmar por WhatsApp</Button>
+          </form>
+        )}
+      </div>
+
+      <div className="h-fit rounded-3xl border border-slate-200 p-6">
+        <h2 className="font-black">Tu pedido</h2>
+        <div className="mt-4 space-y-3">
+          {items.map((item) => (
+            <div key={item.lineItemId} className="flex items-center gap-3">
+              <div className="relative size-14 shrink-0 overflow-hidden rounded-xl bg-slate-100"><Image src={item.product.thumbnail} alt={item.product.name} fill sizes="56px" className="object-cover" /></div>
+              <div className="flex-1"><p className="text-sm font-bold leading-5">{item.product.name}</p><p className="text-xs text-slate-500">Cantidad: {item.quantity}</p></div>
+              <p className="text-sm font-black">{formatMoney((item.product.price ?? 0) * item.quantity, item.product.currency)}</p>
+            </div>
+          ))}
+        </div>
+        <div className="mt-5 space-y-2 border-t border-slate-100 pt-4 text-sm">
+          <div className="flex justify-between"><span className="text-slate-500">Subtotal</span><span className="font-bold">{formatMoney(itemsSubtotal, currency)}</span></div>
+          {step === "payment" && <div className="flex justify-between"><span className="text-slate-500">Envío</span><span className="font-bold">{formatMoney(shippingTotal, currency)}</span></div>}
+          <div className="flex justify-between text-base"><span className="font-black">Total</span><span className="font-black">{formatMoney(step === "payment" ? total : itemsSubtotal, currency)}</span></div>
+        </div>
+      </div>
+    </div>
+  );
+}

workloads/ecommerce/components/checkout/pse-return-client.tsx

@@ -0,0 +1,38 @@
+"use client";
+
+import Link from "next/link";
+import { Clock } from "lucide-react";
+import { useSearchParams } from "next/navigation";
+import { Button } from "@/components/ui/button";
+
+// ePayco redirige aca despues de que el comprador paga en su banco --
+// esto NO confirma el pago. Los parametros de esta URL son solo
+// informativos; el estado real y definitivo llega por el webhook async
+// de ePayco al backend (getWebhookActionAndData en el modulo
+// epayco-pse), nunca por esta pantalla. Por eso el mensaje nunca afirma
+// exito, solo que estamos esperando la confirmacion.
+export function PseReturnClient() {
+  const searchParams = useSearchParams();
+  const referenceCode = searchParams.get("referenceCode") ?? searchParams.get("reference_sale");
+
+  return (
+    <div className="mx-auto max-w-lg px-4 py-24 text-center">
+      <Clock className="mx-auto size-12 text-ari-marino" />
+      <h1 className="mt-6 text-2xl font-black">Estamos confirmando tu pago</h1>
+      <p className="mt-3 text-slate-500">
+        Tu banco ya procesó la transferencia. ePayco nos avisa en unos minutos si quedó aprobada — te llegará la confirmación por correo.
+        {referenceCode && (
+          <>
+            {" "}Tu número de referencia es <strong>{referenceCode}</strong>.
+          </>
+        )}
+      </p>
+      <p className="mt-3 text-sm text-slate-400">
+        Si después de un rato no ves la confirmación, escribinos por WhatsApp con este número de referencia.
+      </p>
+      <Button asChild variant="primary" className="mt-8">
+        <Link href="/catalog">Volver al catálogo</Link>
+      </Button>
+    </div>
+  );
+}

workloads/ecommerce/components/home/category-tiles.tsx

@@ -4,7 +4,7 @@ import { ArrowUpRight } from "lucide-react";
 import type { Category } from "@/lib/headless/types";
 import { cn } from "@/lib/utils";
 
-type TileContent = { subtitle: string; image?: string; color: string; scrim?: string };
+type TileContent = { subtitle: string; image?: string; color: string };
 
 // No hay fotografia real todavia para las 6 categorias raiz de la taxonomia
 // (ver ADR 0005) -- solo se mapean imagen/subtitulo para las que ya tienen
@@ -15,8 +15,8 @@ type TileContent = { subtitle: string; image?: string; color: string; scrim?: st
 // un tono pastel distinto por categoria, no una escala de marca (serian
 // todos casi iguales), pero coordinados en la misma temperatura suave.
 const tileContent: Record<string, TileContent> = {
-  juguetes: { subtitle: "Personajes que inspiran", image: "/images/categories/figuras.webp", color: "bg-amber-100", scrim: "from-amber-100" },
-  "mochilas-y-morrales": { subtitle: "Estilo para cada aventura", image: "/images/categories/mochilas.webp", color: "bg-sky-100", scrim: "from-sky-100" },
+  juguetes: { subtitle: "Personajes que inspiran", image: "/images/categories/figuras.webp", color: "bg-amber-100" },
+  "mochilas-y-morrales": { subtitle: "Estilo para cada aventura", image: "/images/categories/mochilas.webp", color: "bg-sky-100" },
   "bebes-y-primera-infancia": { subtitle: "Primeros descubrimientos", color: "bg-rose-100" },
   educativos: { subtitle: "Aprender jugando", color: "bg-emerald-100" },
   "accion-y-aventura": { subtitle: "Para explorar sin límites", color: "bg-orange-100" },
@@ -37,15 +37,15 @@ export function PromoTile({ category, className = "" }: { category: Category; cl
       href={`/catalog?category=${encodeURIComponent(category.name)}`}
       className={cn(`group relative min-h-64 overflow-hidden rounded-[2rem] ${content.color} shadow-sm ring-1 ring-slate-900/5`, className)}
     >
+      {/* Patron Walmart: foto recortada (object-cover) llenando casi toda
+          la tarjeta, con solo un margen delgado del pastel como marco --
+          no flotando chica con espacio muerto alrededor (object-contain,
+          intento anterior, reportado como "no aprovecha el espacio"), ni
+          a pantalla completa sin marco (el intento antes de ese). */}
       {content.image && (
-        <>
-          <Image src={content.image} alt={category.name} fill sizes="(max-width: 640px) 100vw, (max-width: 1024px) 33vw, 16vw" className="object-cover transition duration-500 group-hover:scale-105" />
-          {/* Franja tintada con el pastel propio de la categoria (no
-              blanco generico) -- sin esto la tarjeta con foto se veia
-              desconectada de las tarjetas solidas vecinas, reportado
-              en produccion. */}
-          <div className={`absolute inset-x-0 bottom-0 h-3/5 bg-gradient-to-t ${content.scrim ?? "from-white"} via-white/50 to-transparent`} />
-        </>
+        <div className="absolute inset-3 bottom-24 overflow-hidden rounded-2xl">
+          <Image src={content.image} alt="" fill sizes="(max-width: 640px) 45vw, (max-width: 1024px) 25vw, 14vw" className="object-cover transition duration-500 group-hover:scale-105" />
+        </div>
       )}
       <div className="absolute inset-x-0 bottom-0 flex items-end justify-between p-6 text-slate-900">
         <div>

workloads/ecommerce/components/home/hero-carousel.tsx

@@ -61,6 +61,7 @@ export function HeroCarousel() {
   }, [reduceMotion]);
 
   const slide = slides[index];
+  if (!slide) return null;
   const Icon = slide.icon;
 
   return (

workloads/ecommerce/components/layout/navbar.tsx

@@ -2,14 +2,15 @@
 
 import Link from "next/link";
 import { usePathname, useSearchParams } from "next/navigation";
-import { ChevronDown, Heart, LayoutGrid, Menu, MessageCircle, PackageCheck, ShoppingCart, UserRound } from "lucide-react";
+import { ChevronDown, Heart, LayoutGrid, Menu, ShoppingCart, UserRound } from "lucide-react";
 import { Suspense, useEffect, useMemo, useRef, useState } from "react";
+import { AccountDialog } from "@/components/account/account-dialog";
 import { PredictiveSearch } from "@/components/search/predictive-search";
 import { Button } from "@/components/ui/button";
-import { Dialog, DialogContent } from "@/components/ui/dialog";
 import { Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle } from "@/components/ui/sheet";
 import type { Category, Product } from "@/lib/headless/types";
 import { useCartStore } from "@/store/cart-store";
+import { useCustomerStore } from "@/store/customer-store";
 import { useWishlistStore } from "@/store/wishlist-store";
 
 type CategoryNode = Category & { children: Category[] };
@@ -34,6 +35,9 @@ export function Navbar({ products, categories }: { products: Product[]; categori
   const openWishlist = useWishlistStore((state) => state.openWishlist);
   const count = cartHydrated ? items.reduce((sum, item) => sum + item.quantity, 0) : 0;
   const wishlistCount = wishlistHydrated ? wishlistProducts.length : 0;
+  const customer = useCustomerStore((state) => state.customer);
+  const customerHydrated = useCustomerStore((state) => state.hasHydrated);
+  const isLoggedIn = customerHydrated && customer !== null;
 
   const tree = useMemo(() => buildCategoryTree(categories), [categories]);
   // Derivado de los productos reales (no de un endpoint de colecciones):
@@ -62,7 +66,15 @@ export function Navbar({ products, categories }: { products: Product[]; categori
           </Link>
           <PredictiveSearch />
           <div className="flex items-center gap-2">
-            <Button variant="outline" size="icon" aria-label="Mi cuenta" className="hidden border-slate-300 bg-white text-slate-900 hover:border-ari-coral hover:bg-ari-coral/10 sm:inline-flex" onClick={() => setAccountOpen(true)}><UserRound /></Button>
+            {/* Antes escondido en mobile (solo alcanzable desde el menu
+                hamburguesa) -- pedido explicito del usuario: visible
+                siempre en el header, con un punto verde cuando hay sesion
+                iniciada (mismo patron que el badge de cantidad del
+                carrito/favoritos, pero de presencia, no de conteo). */}
+            <Button variant="outline" size="icon" aria-label={isLoggedIn ? "Mi cuenta (sesión iniciada)" : "Mi cuenta"} className="relative inline-flex border-slate-300 bg-white text-slate-900 hover:border-ari-coral hover:bg-ari-coral/10" onClick={() => setAccountOpen(true)}>
+              <UserRound />
+              {isLoggedIn && <span className="absolute -right-1 -top-1 size-3 rounded-full border-2 border-white bg-emerald-500" />}
+            </Button>
             <Button variant="outline" size="icon" aria-label={`Favoritos: ${wishlistCount}`} className="relative hidden border-slate-300 bg-white text-slate-900 hover:border-ari-coral hover:bg-ari-coral/10 sm:inline-flex" onClick={openWishlist}>
               <Heart />
               {wishlistCount > 0 && <span className="absolute -right-1.5 -top-1.5 grid size-5 place-items-center rounded-full bg-ari-marino text-[10px] font-black text-white">{wishlistCount}</span>}
@@ -108,19 +120,7 @@ export function Navbar({ products, categories }: { products: Product[]; categori
         </SheetContent>
       </Sheet>
 
-      <Dialog open={accountOpen} onOpenChange={setAccountOpen}>
-        <DialogContent className="max-w-lg p-7">
-          <div className="pr-10">
-            <span className="text-xs font-black uppercase tracking-[.16em] text-ari-coral">Atención personalizada</span>
-            <h2 className="mt-3 text-3xl font-black">Tu cuenta ARI</h2>
-            <p className="mt-3 text-sm leading-6 text-slate-600">El inicio de sesión quedará conectado al backend headless. Mientras tanto, puedes gestionar pedidos y disponibilidad directamente por WhatsApp.</p>
-            <div className="mt-6 grid gap-3">
-              <Button asChild variant="primary" size="lg"><a href={process.env.NEXT_PUBLIC_WHATSAPP_URL ?? "https://wa.link/rvcqqc"} target="_blank" rel="noopener noreferrer"><MessageCircle />Hablar con ARI</a></Button>
-              <Button asChild variant="outline"><Link href="/catalog" onClick={() => setAccountOpen(false)}><PackageCheck />Ver mis opciones de compra</Link></Button>
-            </div>
-          </div>
-        </DialogContent>
-      </Dialog>
+      <AccountDialog open={accountOpen} onOpenChange={setAccountOpen} />
     </header>
   );
 }
@@ -199,6 +199,24 @@ function CategoryNavBar({
 function DepartmentsMegaMenu({ tree, isActive }: { tree: CategoryNode[]; isActive: (name: string) => boolean }) {
   const [open, setOpen] = useState(false);
   const containerRef = useRef<HTMLDivElement>(null);
+  const closeTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const cancelClose = () => {
+    if (closeTimer.current) {
+      clearTimeout(closeTimer.current);
+      closeTimer.current = null;
+    }
+  };
+  // Delay corto en vez de cerrar al toque: aunque el gap entre el boton y
+  // el panel ya se elimino (antes era la causa real -- el panel es
+  // absolute y no suma a la altura del contenedor, asi que un mt-1 ahi
+  // dejaba una franja muerta que cerraba el menu a mitad de camino,
+  // reportado en vivo), este margen extra tolera movimientos rapidos o en
+  // diagonal cerca del borde sin reabrir nada raro.
+  const scheduleClose = () => {
+    cancelClose();
+    closeTimer.current = setTimeout(() => setOpen(false), 200);
+  };
 
   useEffect(() => {
     if (!open) return;
@@ -216,8 +234,15 @@ function DepartmentsMegaMenu({ tree, isActive }: { tree: CategoryNode[]; isActiv
     };
   }, [open]);
 
+  useEffect(() => () => cancelClose(), []);
+
+  const openNow = () => {
+    cancelClose();
+    setOpen(true);
+  };
+
   return (
-    <div ref={containerRef} className="shrink-0" onMouseEnter={() => setOpen(true)} onMouseLeave={() => setOpen(false)}>
+    <div ref={containerRef} className="shrink-0" onMouseEnter={openNow} onMouseLeave={scheduleClose}>
       <button
         type="button"
         onClick={() => setOpen((value) => !value)}
@@ -231,7 +256,7 @@ function DepartmentsMegaMenu({ tree, isActive }: { tree: CategoryNode[]; isActiv
       </button>
 
       {open && (
-        <div className="absolute left-0 top-full z-50 mt-1 max-h-[80vh] w-[min(92vw,64rem)] overflow-y-auto rounded-2xl border border-white/10 bg-ari-marino p-6 shadow-2xl">
+        <div className="absolute left-0 top-full z-50 max-h-[80vh] w-[min(92vw,64rem)] overflow-y-auto rounded-2xl border border-white/10 bg-ari-marino p-6 shadow-2xl">
           <div className="grid grid-cols-2 gap-x-6 gap-y-5 sm:grid-cols-3 lg:grid-cols-6">
             {tree.map((root) => (
               <div key={root.id}>

workloads/ecommerce/components/product/mobile-add-to-cart.tsx

@@ -7,5 +7,19 @@ import { useCartStore } from "@/store/cart-store";
 
 export function MobileAddToCart({ product }: { product: Product }) {
   const addItem = useCartStore((state) => state.addItem);
-  return <div className="fixed inset-x-0 bottom-0 z-40 border-t border-slate-200 bg-white/95 p-3 shadow-2xl backdrop-blur lg:hidden"><Button variant="primary" size="lg" className="w-full" onClick={() => addItem(product, product.variants[0]?.id)}><ShoppingBag />Añadir al carrito</Button></div>;
+  const outOfStock = product.variants[0]?.available === false;
+  return (
+    <div className="fixed inset-x-0 bottom-0 z-40 border-t border-slate-200 bg-white/95 p-3 shadow-2xl backdrop-blur lg:hidden">
+      <Button
+        variant="primary"
+        size="lg"
+        className="w-full"
+        disabled={outOfStock}
+        onClick={() => addItem(product, product.variants[0]?.id)}
+      >
+        <ShoppingBag />
+        {outOfStock ? "Agotado" : "Añadir al carrito"}
+      </Button>
+    </div>
+  );
 }

workloads/ecommerce/components/product/product-card.tsx

@@ -24,7 +24,9 @@ export function ProductCard({ product, priority = false }: { product: Product; p
 
   const [selectedVariantId, setSelectedVariantId] = useState(product.variants[0]?.id);
   const selectedVariant = product.variants.find((variant) => variant.id === selectedVariantId) ?? product.variants[0];
+  const outOfStock = selectedVariant?.available === false;
   const lowStock =
+    !outOfStock &&
     selectedVariant?.inventoryQuantity !== null &&
     selectedVariant?.inventoryQuantity !== undefined &&
     selectedVariant.inventoryQuantity > 0 &&
@@ -36,7 +38,8 @@ export function ProductCard({ product, priority = false }: { product: Product; p
     <article className="group flex h-full flex-col overflow-hidden rounded-lg border border-slate-100 bg-white shadow-lg shadow-ari-marino/5 transition duration-300 hover:-translate-y-1.5 hover:shadow-2xl hover:shadow-ari-coral/10">
       <div className="relative aspect-square overflow-hidden bg-white">
         <Link href={`/product/${product.slug}`} prefetch={false}><Image src={product.thumbnail} alt={product.name} fill priority={priority} sizes="(max-width: 640px) 82vw, (max-width: 1024px) 44vw, 280px" className="object-cover transition duration-500 group-hover:scale-[1.035]" /></Link>
-        <div className="absolute left-3 top-3 flex gap-2">{discountPercent && discountPercent > 0 && <Badge className="bg-ari-coral-claro text-ari-marino">-{discountPercent}%</Badge>}{product.isNew && <Badge className="bg-ari-marino text-white">Nuevo</Badge>}{product.featured && <Badge className="bg-ari-coral-claro text-ari-marino"><Sparkles className="mr-1 size-3" />Top</Badge>}</div>
+        <div className="absolute left-3 top-3 flex gap-2">{outOfStock && <Badge className="bg-rose-600 text-white">Agotado</Badge>}{discountPercent && discountPercent > 0 && <Badge className="bg-ari-coral-claro text-ari-marino">-{discountPercent}%</Badge>}{product.isNew && <Badge className="bg-ari-marino text-white">Nuevo</Badge>}{product.featured && <Badge className="bg-ari-coral-claro text-ari-marino"><Sparkles className="mr-1 size-3" />Top</Badge>}</div>
+        {outOfStock && <div className="pointer-events-none absolute inset-0 bg-white/40" />}
         <button type="button" aria-label={isFavorite ? "Quitar de favoritos" : "Agregar a favoritos"} aria-pressed={isFavorite} className={`absolute right-3 top-3 rounded-full p-2.5 shadow-lg backdrop-blur transition ${isFavorite ? "bg-ari-coral text-white" : "bg-white/95 text-slate-900 hover:text-ari-coral"}`} onClick={() => toggleProduct(product)}><Heart className={`size-4 ${isFavorite ? "fill-current" : ""}`} /></button>
       </div>
       <div className="flex flex-1 flex-col space-y-3 p-5">
@@ -67,12 +70,15 @@ export function ProductCard({ product, priority = false }: { product: Product; p
         {lowStock !== null && (
           <span className="flex items-center gap-1.5 text-xs font-bold text-amber-600"><TriangleAlert className="size-3.5" />Quedan {lowStock}</span>
         )}
+        {outOfStock && (
+          <span className="flex items-center gap-1.5 text-xs font-bold text-rose-600"><TriangleAlert className="size-3.5" />Sin stock</span>
+        )}
         <div className="mt-auto flex items-center justify-between gap-3 pt-1">
           <div className="flex flex-col">
             {product.compareAtPrice && <span className="text-xs font-bold text-slate-400 line-through">{formatMoney(product.compareAtPrice, product.currency)}</span>}
             <strong className="font-display text-base font-bold text-ari-marino">{formatMoney(product.price, product.currency)}</strong>
           </div>
-          <Button variant="primary" size="sm" onClick={() => addItem(product, selectedVariantId)}><ShoppingBag className="size-4" />Agregar</Button>
+          <Button variant="primary" size="sm" disabled={outOfStock} onClick={() => addItem(product, selectedVariantId)}><ShoppingBag className="size-4" />{outOfStock ? "Agotado" : "Agregar"}</Button>
         </div>
       </div>
     </article>

workloads/ecommerce/components/product/product-gallery.tsx

@@ -2,19 +2,36 @@
 
 import Image from "next/image";
 import { Maximize2, Minus, Plus, RotateCcw, ZoomIn } from "lucide-react";
-import { PointerEvent, WheelEvent, useRef, useState } from "react";
+import { MouseEvent, PointerEvent, WheelEvent, useRef, useState } from "react";
 import { Dialog, DialogContent, DialogTrigger } from "@/components/ui/dialog";
 
 interface Offset { x: number; y: number }
 interface DragState { pointerId: number; startX: number; startY: number; originX: number; originY: number }
+interface HoverZoomOrigin { x: number; y: number }
+
+// Zoom automatico al pasar el cursor (estilo lupa clasico de e-commerce)
+// sobre la imagen principal -- solo mouse (mousemove no dispara de forma
+// continua en touch, asi que en mobile simplemente no aparece el efecto,
+// sin romper nada). Independiente del zoom interactivo del modal
+// (click -> Dialog con scale/drag), que sigue igual.
+const HOVER_ZOOM_SCALE = 2.2;
 
 export function ProductGallery({ images, name }: { images: string[]; name: string }) {
   const [selected, setSelected] = useState(images[0] ?? "");
   const [open, setOpen] = useState(false);
   const [scale, setScale] = useState(1);
   const [offset, setOffset] = useState<Offset>({ x: 0, y: 0 });
+  const [hoverZoom, setHoverZoom] = useState<HoverZoomOrigin | null>(null);
   const drag = useRef<DragState | null>(null);
 
+  const trackHoverZoom = (event: MouseEvent<HTMLButtonElement>) => {
+    const rect = event.currentTarget.getBoundingClientRect();
+    setHoverZoom({
+      x: ((event.clientX - rect.left) / rect.width) * 100,
+      y: ((event.clientY - rect.top) / rect.height) * 100,
+    });
+  };
+
   const applyScale = (next: number) => {
     const value = Math.min(3, Math.max(1, Number(next.toFixed(2))));
     setScale(value);
@@ -44,8 +61,24 @@ export function ProductGallery({ images, name }: { images: string[]; name: strin
       </div>
       <Dialog open={open} onOpenChange={changeOpen}>
         <DialogTrigger asChild>
-          <button type="button" className="group relative order-1 aspect-square overflow-hidden rounded-[2rem] bg-slate-50 lg:order-2">
-            <Image src={selected} alt={name} fill priority sizes="(max-width: 1024px) 100vw, 50vw" className="object-cover transition duration-500 group-hover:scale-[1.03]" />
+          <button
+            type="button"
+            className="group relative order-1 aspect-square cursor-zoom-in overflow-hidden rounded-[2rem] bg-slate-50 lg:order-2"
+            onMouseMove={trackHoverZoom}
+            onMouseLeave={() => setHoverZoom(null)}
+          >
+            <Image
+              src={selected}
+              alt={name}
+              fill
+              priority
+              sizes="(max-width: 1024px) 100vw, 50vw"
+              className="object-cover transition-transform duration-150 ease-out"
+              style={{
+                transform: `scale(${hoverZoom ? HOVER_ZOOM_SCALE : 1})`,
+                transformOrigin: hoverZoom ? `${hoverZoom.x}% ${hoverZoom.y}%` : "center",
+              }}
+            />
             <span className="absolute bottom-5 right-5 inline-flex items-center gap-2 rounded-full bg-white px-4 py-2 text-xs font-black shadow-xl"><ZoomIn className="size-4" />Zoom interactivo</span>
           </button>
         </DialogTrigger>

workloads/ecommerce/components/product/product-purchase.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { CheckCircle2, ShoppingBag, TriangleAlert, Truck } from "lucide-react";
+import { CheckCircle2, ShoppingBag, TriangleAlert, Truck, XCircle } from "lucide-react";
 import { useState } from "react";
 import { Button } from "@/components/ui/button";
 import type { Product } from "@/lib/headless/types";
@@ -11,12 +11,68 @@ export function ProductPurchase({ product }: { product: Product }) {
   const [variantId, setVariantId] = useState(product.variants[0]?.id);
   const addItem = useCartStore((state) => state.addItem);
   const selectedVariant = product.variants.find((variant) => variant.id === variantId) ?? product.variants[0];
+  const outOfStock = selectedVariant?.available === false;
   const lowStock =
+    !outOfStock &&
     selectedVariant?.inventoryQuantity !== null &&
     selectedVariant?.inventoryQuantity !== undefined &&
     selectedVariant.inventoryQuantity > 0 &&
     selectedVariant.inventoryQuantity <= LOW_STOCK_THRESHOLD
       ? selectedVariant.inventoryQuantity
       : null;
-  return <div><div className="mb-5 flex flex-wrap gap-2">{product.variants.map((variant) => <button key={variant.id} onClick={() => setVariantId(variant.id)} className={`rounded-full border px-4 py-2 text-sm font-bold ${variantId === variant.id ? "border-ari-marino bg-ari-marino text-white" : "border-slate-200"}`}>{variant.value}</button>)}</div><div className="mb-6 flex items-end gap-3"><strong className="text-3xl font-black">{formatMoney(product.price, product.currency)}</strong>{product.compareAtPrice && <del className="text-slate-400">{formatMoney(product.compareAtPrice, product.currency)}</del>}</div>{/* oculto en mobile: MobileAddToCart (barra fija abajo, lg:hidden) ya cubre esa misma accion ahi -- sin el hidden aqui, ambos se mostraban a la vez. */}<Button variant="primary" size="lg" className="hidden w-full lg:inline-flex" onClick={() => addItem(product, variantId)}><ShoppingBag />Añadir al carrito</Button><div className="mt-5 grid gap-3 rounded-2xl bg-slate-50 p-4 text-sm">{lowStock !== null ? <span className="flex items-center gap-2 font-bold text-amber-600"><TriangleAlert className="size-4" />Quedan {lowStock} unidades</span> : <span className="flex items-center gap-2 font-bold"><CheckCircle2 className="size-4 text-emerald-500" />Disponibilidad por confirmar</span>}<span className="flex items-center gap-2 font-bold"><Truck className="size-4 text-cyan-600" />Envíos nacionales</span></div></div>;
+
+  return (
+    <div>
+      <div className="mb-5 flex flex-wrap gap-2">
+        {product.variants.map((variant) => (
+          <button
+            key={variant.id}
+            onClick={() => setVariantId(variant.id)}
+            className={`rounded-full border px-4 py-2 text-sm font-bold ${
+              variantId === variant.id ? "border-ari-marino bg-ari-marino text-white" : "border-slate-200"
+            } ${variant.available === false ? "opacity-40" : ""}`}
+          >
+            {variant.value}
+          </button>
+        ))}
+      </div>
+      <div className="mb-6 flex items-end gap-3">
+        <strong className="text-3xl font-black">{formatMoney(product.price, product.currency)}</strong>
+        {product.compareAtPrice && <del className="text-slate-400">{formatMoney(product.compareAtPrice, product.currency)}</del>}
+      </div>
+      {/* oculto en mobile: MobileAddToCart (barra fija abajo, lg:hidden) ya cubre esa misma accion ahi -- sin el hidden aqui, ambos se mostraban a la vez. */}
+      <Button
+        variant="primary"
+        size="lg"
+        className="hidden w-full lg:inline-flex"
+        disabled={outOfStock}
+        onClick={() => addItem(product, variantId)}
+      >
+        <ShoppingBag />
+        {outOfStock ? "Agotado" : "Añadir al carrito"}
+      </Button>
+      <div className="mt-5 grid gap-3 rounded-2xl bg-slate-50 p-4 text-sm">
+        {outOfStock ? (
+          <span className="flex items-center gap-2 font-bold text-rose-600">
+            <XCircle className="size-4" />
+            Agotado
+          </span>
+        ) : lowStock !== null ? (
+          <span className="flex items-center gap-2 font-bold text-amber-600">
+            <TriangleAlert className="size-4" />
+            Quedan {lowStock} unidades
+          </span>
+        ) : (
+          <span className="flex items-center gap-2 font-bold">
+            <CheckCircle2 className="size-4 text-emerald-500" />
+            Disponibilidad por confirmar
+          </span>
+        )}
+        <span className="flex items-center gap-2 font-bold">
+          <Truck className="size-4 text-cyan-600" />
+          Envíos nacionales
+        </span>
+      </div>
+    </div>
+  );
 }

workloads/ecommerce/frontend/patches/deployment.yaml

@@ -25,7 +25,7 @@ spec:
         runAsUser: 1001
       containers:
         - name: app
-          image: gitea.cruzcloud.net/devops/ecommerce-frontend:v1.0.197
+          image: gitea.cruzcloud.net/devops/ecommerce-frontend:v1.0.230
           env:
             - name: HEADLESS_PROVIDER
               value: medusa

workloads/ecommerce/lib/data/co-departamentos.json

@@ -0,0 +1,40 @@
+{
+  "data": [
+    { "id": 5, "name": "Antioquia" },
+    { "id": 8, "name": "Atlántico" },
+    { "id": 11, "name": "Bogotá D.C." },
+    { "id": 13, "name": "Bolívar" },
+    { "id": 15, "name": "Boyacá" },
+    { "id": 17, "name": "Caldas" },
+    { "id": 18, "name": "Caquetá" },
+    { "id": 19, "name": "Cauca" },
+    { "id": 20, "name": "Cesar" },
+    { "id": 23, "name": "Córdoba" },
+    { "id": 25, "name": "Cundinamarca" },
+    { "id": 27, "name": "Chocó" },
+    { "id": 41, "name": "Huila" },
+    { "id": 44, "name": "La Guajira" },
+    { "id": 47, "name": "Magdalena" },
+    { "id": 50, "name": "Meta" },
+    { "id": 52, "name": "Nariño" },
+    { "id": 54, "name": "Norte de Santander" },
+    { "id": 63, "name": "Quindío" },
+    { "id": 66, "name": "Risaralda" },
+    { "id": 68, "name": "Santander" },
+    { "id": 70, "name": "Sucre" },
+    { "id": 73, "name": "Tolima" },
+    { "id": 76, "name": "Valle del Cauca" },
+    { "id": 81, "name": "Arauca" },
+    { "id": 85, "name": "Casanare" },
+    { "id": 86, "name": "Putumayo" },
+    {
+      "id": 88,
+      "name": "Archipiélago de San Andrés, Providencia y Santa Catalina"
+    },
+    { "id": 91, "name": "Amazonas" },
+    { "id": 94, "name": "Guainía" },
+    { "id": 95, "name": "Guaviare" },
+    { "id": 97, "name": "Vaupés" },
+    { "id": 99, "name": "Vichada" }
+  ]
+}

workloads/ecommerce/lib/data/colombia.ts

@@ -0,0 +1,32 @@
+import departamentosData from "./co-departamentos.json";
+import ciudadesData from "./co-ciudades.json";
+
+// Dataset real de DIVIPOLA (Division Politico-Administrativa de Colombia,
+// codigos oficiales del DANE) -- 33 departamentos + 1123 municipios,
+// fuente: proyecto26/colombia (github.com/proyecto26/colombia), verificado
+// contra la codificacion oficial antes de incorporarlo (ej. id 5001 =
+// Medellin, departmentId 5 = Antioquia).
+//
+// Se usan los codigos (no solo los nombres) porque EnvioClick -- la
+// integracion de envios real que reemplazara la tarifa fija de ADR 0009 --
+// va a necesitar identificar la ciudad de forma inequivoca, y las
+// transportadoras colombianas en general referencian ciudades por su
+// codigo DIVIPOLA, no por texto libre.
+
+export interface Departamento {
+  id: number;
+  name: string;
+}
+
+export interface Ciudad {
+  id: number;
+  name: string;
+  departmentId: number;
+}
+
+export const departamentos: Departamento[] = departamentosData.data;
+export const ciudades: Ciudad[] = ciudadesData.data;
+
+export function ciudadesPorDepartamento(departmentId: number): Ciudad[] {
+  return ciudades.filter((ciudad) => ciudad.departmentId === departmentId);
+}

workloads/ecommerce/lib/headless/providers/medusa-cart.ts

@@ -0,0 +1,244 @@
+// ADR 0009: carrito real conectado a Medusa (Store API), en vez del
+// estado 100% local que existia antes. Archivo separado de medusa.ts
+// a proposito -- ese es de solo lectura (catalogo, cacheado con
+// revalidate/tags), este es de escritura (carrito, siempre no-store,
+// nunca debe cachearse).
+//
+// Formas de respuesta verificadas en vivo contra la API real
+// (2026-08-29), no asumidas contra documentacion:
+// - crear/agregar/actualizar linea: { cart: {...} }
+// - eliminar linea: { id, object, deleted, parent: {...} } -- el
+//   carrito actualizado viene en "parent", no en "cart".
+// - agregar el mismo variant_id dos veces hace merge de cantidad en la
+//   misma linea (confirmado con un carrito de prueba real), no crea
+//   una linea duplicada -- por eso addLineItem siempre manda
+//   quantity=1 sin revisar antes si ya existe.
+
+export interface CartLineProduct {
+  id: string;
+  name: string;
+  thumbnail: string;
+  price: number | null;
+  currency: string;
+}
+
+export interface CartLine {
+  lineItemId: string;
+  product: CartLineProduct;
+  quantity: number;
+  variantId: string;
+}
+
+export interface CartSummary {
+  cartId: string;
+  currency: string;
+  subtotal: number;
+  shippingTotal: number;
+  total: number;
+  items: CartLine[];
+}
+
+export interface ShippingAddressInput {
+  firstName: string;
+  lastName: string;
+  address1: string;
+  city: string;
+  province?: string;
+  phone: string;
+  email: string;
+}
+
+export interface ShippingOption {
+  id: string;
+  name: string;
+  amount: number;
+}
+
+function backendUrl(): string {
+  const value = process.env.MEDUSA_BACKEND_URL;
+  if (!value) {
+    throw new Error("MEDUSA_BACKEND_URL no está configurado.");
+  }
+  return value.replace(/\/$/, "");
+}
+
+function regionId(): string {
+  const value = process.env.MEDUSA_REGION_ID;
+  if (!value) {
+    throw new Error("MEDUSA_REGION_ID no está configurado.");
+  }
+  return value;
+}
+
+type MedusaLineItem = {
+  id: string;
+  product_id: string;
+  variant_id: string;
+  title?: string | null;
+  product_title?: string | null;
+  thumbnail?: string | null;
+  quantity: number;
+  unit_price?: number | null;
+  product?: { images?: Array<{ url?: string | null }> | null } | null;
+};
+
+type MedusaCart = {
+  id: string;
+  currency_code: string;
+  subtotal?: number | null;
+  shipping_total?: number | null;
+  total?: number | null;
+  items?: MedusaLineItem[] | null;
+};
+
+function mapCart(cart: MedusaCart): CartSummary {
+  return {
+    cartId: cart.id,
+    currency: cart.currency_code,
+    subtotal: cart.subtotal ?? 0,
+    shippingTotal: cart.shipping_total ?? 0,
+    total: cart.total ?? cart.subtotal ?? 0,
+    items: (cart.items ?? []).map((item) => ({
+      lineItemId: item.id,
+      variantId: item.variant_id,
+      quantity: item.quantity,
+      product: {
+        id: item.product_id,
+        name: item.product_title || item.title || "Producto",
+        // item.thumbnail viene null en la practica para todo el catalogo
+        // real (confirmado contra /store/products: product.thumbnail
+        // tambien es null ahi, incluso con fotos reales cargadas) -- el
+        // catalogo ya resuelve esto cayendo a images[0] (mapProduct() en
+        // medusa.ts), asi que la linea del carrito pide esa misma relacion
+        // explicita (no viene por defecto) y aplica el mismo fallback.
+        thumbnail: item.thumbnail || item.product?.images?.[0]?.url || "/images/brand/logo-ari.png",
+        price: typeof item.unit_price === "number" ? item.unit_price : null,
+        currency: cart.currency_code,
+      },
+    })),
+  };
+}
+
+// Exportado para medusa-payment.ts (mismo backend, mismo criterio de
+// no-store/x-publishable-api-key -- evita duplicar el fetch helper).
+export async function medusaCartFetch(
+  path: string,
+  init?: { method?: string; body?: unknown },
+): Promise<Record<string, unknown>> {
+  const publishableKey = process.env.MEDUSA_PUBLISHABLE_KEY;
+
+  const response = await fetch(`${backendUrl()}${path}`, {
+    method: init?.method ?? "GET",
+    headers: {
+      "Content-Type": "application/json",
+      ...(publishableKey ? { "x-publishable-api-key": publishableKey } : {}),
+    },
+    body: init?.body ? JSON.stringify(init.body) : undefined,
+    cache: "no-store",
+  });
+
+  if (!response.ok) {
+    const text = await response.text().catch(() => "");
+    throw new Error(`Medusa cart API ${response.status}: ${text.slice(0, 300)}`);
+  }
+
+  return response.json();
+}
+
+// *items.product.images no viene por defecto (verificado en vivo) y es
+// lo unico que necesitamos ademas del set por defecto -- *items ya trae
+// unit_price/product_title/variant_id/quantity sin pedirlos aparte.
+const ITEMS_FIELDS = "fields=*items,*items.product.images";
+
+export async function createCart(): Promise<CartSummary> {
+  const data = await medusaCartFetch("/store/carts", {
+    method: "POST",
+    body: { region_id: regionId() },
+  });
+  return mapCart(data.cart as MedusaCart);
+}
+
+export async function getCart(cartId: string): Promise<CartSummary> {
+  const data = await medusaCartFetch(`/store/carts/${cartId}?${ITEMS_FIELDS}`);
+  return mapCart(data.cart as MedusaCart);
+}
+
+export async function addLineItem(
+  cartId: string,
+  variantId: string,
+  quantity: number,
+): Promise<CartSummary> {
+  const data = await medusaCartFetch(`/store/carts/${cartId}/line-items?${ITEMS_FIELDS}`, {
+    method: "POST",
+    body: { variant_id: variantId, quantity },
+  });
+  return mapCart(data.cart as MedusaCart);
+}
+
+export async function updateLineItemQuantity(
+  cartId: string,
+  lineItemId: string,
+  quantity: number,
+): Promise<CartSummary> {
+  const data = await medusaCartFetch(`/store/carts/${cartId}/line-items/${lineItemId}?${ITEMS_FIELDS}`, {
+    method: "POST",
+    body: { quantity },
+  });
+  return mapCart(data.cart as MedusaCart);
+}
+
+export async function removeLineItem(cartId: string, lineItemId: string): Promise<CartSummary> {
+  const data = await medusaCartFetch(`/store/carts/${cartId}/line-items/${lineItemId}?${ITEMS_FIELDS}`, {
+    method: "DELETE",
+  });
+  // Forma distinta a las demas: el carrito actualizado viene en
+  // "parent", no en "cart" -- verificado en vivo, no documentado.
+  return mapCart(data.parent as MedusaCart);
+}
+
+export async function setShippingAddress(
+  cartId: string,
+  address: ShippingAddressInput,
+): Promise<CartSummary> {
+  const data = await medusaCartFetch(`/store/carts/${cartId}?${ITEMS_FIELDS}`, {
+    method: "POST",
+    body: {
+      email: address.email,
+      shipping_address: {
+        first_name: address.firstName,
+        last_name: address.lastName,
+        address_1: address.address1,
+        city: address.city,
+        province: address.province || undefined,
+        country_code: "co",
+        phone: address.phone,
+      },
+    },
+  });
+  return mapCart(data.cart as MedusaCart);
+}
+
+type MedusaShippingOption = {
+  id: string;
+  name: string;
+  amount?: number | null;
+  calculated_price?: { calculated_amount?: number | null } | null;
+};
+
+export async function getShippingOptions(cartId: string): Promise<ShippingOption[]> {
+  const data = await medusaCartFetch(`/store/shipping-options?cart_id=${cartId}`);
+  const options = (data.shipping_options as MedusaShippingOption[] | undefined) ?? [];
+  return options.map((option) => ({
+    id: option.id,
+    name: option.name,
+    amount: option.calculated_price?.calculated_amount ?? option.amount ?? 0,
+  }));
+}
+
+export async function addShippingMethod(cartId: string, optionId: string): Promise<CartSummary> {
+  const data = await medusaCartFetch(`/store/carts/${cartId}/shipping-methods?${ITEMS_FIELDS}`, {
+    method: "POST",
+    body: { option_id: optionId },
+  });
+  return mapCart(data.cart as MedusaCart);
+}

workloads/ecommerce/lib/headless/providers/medusa-customer.ts

@@ -0,0 +1,167 @@
+// Cuentas de cliente reales conectadas a Medusa (Store API), mismo patron
+// que medusa-cart.ts -- server-side, nunca cacheado (auth es estado
+// mutable por sesion, no catalogo).
+//
+// Flujo verificado en vivo (2026-08-29) antes de escribir este archivo,
+// no asumido contra documentacion: registro (auth/customer/emailpass/
+// register) da un token de registro; ese token crea el customer real
+// (POST /store/customers); pero ese token de registro NO sirve como
+// sesion del customer -- hay que loguear de nuevo para obtener el token
+// de sesion real. Mensajes de error exactos confirmados: registro con
+// correo repetido -> 401 "Identity with email already exists"; login con
+// credenciales invalidas -> 401 "Invalid email or password".
+
+export interface CustomerSummary {
+  token: string;
+  id: string;
+  email: string;
+  firstName: string | null;
+  lastName: string | null;
+}
+
+function backendUrl(): string {
+  const value = process.env.MEDUSA_BACKEND_URL;
+  if (!value) {
+    throw new Error("MEDUSA_BACKEND_URL no está configurado.");
+  }
+  return value.replace(/\/$/, "");
+}
+
+async function medusaAuthFetch(
+  path: string,
+  init?: { method?: string; body?: unknown; token?: string },
+): Promise<Record<string, unknown>> {
+  const publishableKey = process.env.MEDUSA_PUBLISHABLE_KEY;
+
+  const response = await fetch(`${backendUrl()}${path}`, {
+    method: init?.method ?? "GET",
+    headers: {
+      "Content-Type": "application/json",
+      ...(publishableKey ? { "x-publishable-api-key": publishableKey } : {}),
+      ...(init?.token ? { Authorization: `Bearer ${init.token}` } : {}),
+    },
+    body: init?.body ? JSON.stringify(init.body) : undefined,
+    cache: "no-store",
+  });
+
+  const data = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    const message = typeof data.message === "string" ? data.message : `Error ${response.status}`;
+    throw new Error(message);
+  }
+  return data;
+}
+
+type MedusaCustomer = {
+  id: string;
+  email: string;
+  first_name?: string | null;
+  last_name?: string | null;
+};
+
+export async function getCurrentCustomer(token: string): Promise<CustomerSummary> {
+  const data = await medusaAuthFetch("/store/customers/me", { token });
+  const customer = data.customer as MedusaCustomer;
+  return {
+    token,
+    id: customer.id,
+    email: customer.email,
+    firstName: customer.first_name ?? null,
+    lastName: customer.last_name ?? null,
+  };
+}
+
+export async function loginCustomer(email: string, password: string): Promise<CustomerSummary> {
+  let data: Record<string, unknown>;
+  try {
+    data = await medusaAuthFetch("/auth/customer/emailpass", {
+      method: "POST",
+      body: { email, password },
+    });
+  } catch (error) {
+    if ((error as Error).message === "Invalid email or password") {
+      throw new Error("Correo o contraseña incorrectos.");
+    }
+    throw error;
+  }
+  return getCurrentCustomer(data.token as string);
+}
+
+// Flujo Google verificado en vivo (2026-08-29) contra el pod real, no
+// solo contra la doc: GET /auth/customer/google funciona igual que el
+// POST documentado (sin body, no hace falta callback_url -- ya viene de
+// GOOGLE_CALLBACK_URL en el modulo); la respuesta no trae Set-Cookie, o
+// sea que el "state" que Google reenvia en el callback es autocontenido
+// (firmado), no depende de sesion de servidor -- confirmado con un
+// callback con code/state inventados: 401 "No state provided, or
+// session expired" (mismo mensaje que con state ausente, no un error de
+// sesion real). auth/token/refresh confirmado que exige Bearer valido
+// (401 "Unauthorized" con uno invalido, no 404).
+function decodeJwtPayload(token: string): Record<string, unknown> {
+  const payload = token.split(".")[1] ?? "";
+  const base64 = payload.replace(/-/g, "+").replace(/_/g, "/");
+  const json = Buffer.from(base64, "base64").toString("utf-8");
+  return JSON.parse(json || "{}");
+}
+
+export async function getGoogleAuthUrl(): Promise<string> {
+  const data = await medusaAuthFetch("/auth/customer/google");
+  return data.location as string;
+}
+
+export async function handleGoogleCallback(code: string, state: string): Promise<CustomerSummary> {
+  const query = new URLSearchParams({ code, state }).toString();
+  const data = await medusaAuthFetch(`/auth/customer/google/callback?${query}`, { method: "POST" });
+  const initialToken = data.token as string;
+  const payload = decodeJwtPayload(initialToken);
+  const actorId = payload.actor_id as string | undefined;
+
+  if (!actorId) {
+    // Primer login con Google -- todavia no existe el customer real.
+    const userMetadata = (payload.user_metadata as Record<string, unknown> | undefined) ?? {};
+    const email = userMetadata.email as string;
+    const firstName = (userMetadata.given_name as string) ?? (userMetadata.name as string) ?? email.split("@")[0];
+    const lastName = (userMetadata.family_name as string) ?? "";
+    await medusaAuthFetch("/store/customers", {
+      method: "POST",
+      token: initialToken,
+      body: { email, first_name: firstName, last_name: lastName },
+    });
+  }
+
+  // El token del callback (o el de recien crear el customer) todavia no
+  // sirve como sesion final -- hay que refrescarlo, tanto para usuarios
+  // nuevos como para los que ya existian (confirmado contra la doc: los
+  // dos casos convergen en el mismo paso de refresh).
+  const refreshed = await medusaAuthFetch("/auth/token/refresh", { method: "POST", token: initialToken });
+  return getCurrentCustomer(refreshed.token as string);
+}
+
+export async function registerCustomer(
+  email: string,
+  password: string,
+  firstName: string,
+  lastName: string,
+): Promise<CustomerSummary> {
+  let data: Record<string, unknown>;
+  try {
+    data = await medusaAuthFetch("/auth/customer/emailpass/register", {
+      method: "POST",
+      body: { email, password },
+    });
+  } catch (error) {
+    if ((error as Error).message === "Identity with email already exists") {
+      throw new Error("Ese correo ya está registrado — inicia sesión en vez de crear una cuenta nueva.");
+    }
+    throw error;
+  }
+  await medusaAuthFetch("/store/customers", {
+    method: "POST",
+    token: data.token as string,
+    body: { email, first_name: firstName, last_name: lastName },
+  });
+  // El token de registro crea el customer pero no queda como sesion real
+  // -- se loguea de nuevo para obtener el token de sesion (confirmado en
+  // vivo, no documentado explicitamente).
+  return loginCustomer(email, password);
+}

workloads/ecommerce/lib/headless/providers/medusa-payment.ts

@@ -0,0 +1,97 @@
+// ADR 0009: pago real via ePayco (PSE) -- tercer proveedor evaluado
+// (PayU LatAm descartado porque Rapyd compró ese negocio en 2023 y el
+// registro real quedó con credenciales incompatibles; Rapyd descartado
+// por costo). ePayco: 100% de Davivienda desde 2024, comisión PSE más
+// baja para el volumen real del usuario, tarifa preferencial con cuenta
+// Davivienda. Módulo custom del backend
+// (workloads/commerce-backend/src/modules/epayco-pse). Archivo separado
+// de medusa-cart.ts por el mismo motivo que ese archivo esta separado de
+// medusa.ts -- reutiliza su mismo fetch helper (medusaCartFetch), no
+// duplica la logica de headers/no-store.
+import { medusaCartFetch } from "./medusa-cart";
+
+export interface PseBank {
+  pseCode: string;
+  description: string;
+}
+
+// "0" persona natural, "1" persona juridica -- valores reales que espera
+// ePayco (campo type_person), no un codigo propio nuestro.
+export type PseUserType = "0" | "1";
+export type PseDocType = "CC" | "CE" | "NIT" | "TI" | "PP";
+
+export interface PsePaymentInput {
+  bankCode: string;
+  userType: PseUserType;
+  docType: PseDocType;
+  docNumber: string;
+  firstName: string;
+  lastName: string;
+  email: string;
+  phone: string;
+  city: string;
+}
+
+// "pp_{identifier}_{id}" -- convencion de Medusa, confirmada contra el
+// codigo fuente de @medusajs/payment (identifier "epayco" + id "pse" en
+// medusa-config.ts).
+const PSE_PROVIDER_ID = "pp_epayco_pse";
+
+export async function getPseBanks(): Promise<PseBank[]> {
+  const data = await medusaCartFetch("/store/payments/pse-banks");
+  const banks = (data.banks as Array<{ pseCode?: string; description?: string }> | undefined) ?? [];
+  return banks
+    .filter((bank): bank is { pseCode: string; description: string } => Boolean(bank.pseCode && bank.description))
+    .map((bank) => ({ pseCode: bank.pseCode, description: bank.description }));
+}
+
+export async function createPaymentCollection(cartId: string): Promise<string> {
+  const data = await medusaCartFetch("/store/payment-collections", {
+    method: "POST",
+    body: { cart_id: cartId },
+  });
+  const collection = data.payment_collection as { id: string };
+  return collection.id;
+}
+
+export async function createPsePaymentSession(paymentCollectionId: string, input: PsePaymentInput): Promise<string> {
+  const data = await medusaCartFetch(`/store/payment-collections/${paymentCollectionId}/payment-sessions`, {
+    method: "POST",
+    body: {
+      provider_id: PSE_PROVIDER_ID,
+      data: {
+        bank_code: input.bankCode,
+        user_type: input.userType,
+        doc_type: input.docType,
+        doc_number: input.docNumber,
+        first_name: input.firstName,
+        last_name: input.lastName,
+        email: input.email,
+        phone: input.phone,
+        city: input.city,
+      },
+    },
+  });
+  const collection = data.payment_collection as {
+    payment_sessions?: Array<{ provider_id: string; data?: { bank_url?: string } }>;
+  };
+  const session = collection.payment_sessions?.find((paymentSession) => paymentSession.provider_id === PSE_PROVIDER_ID);
+  const bankUrl = session?.data?.bank_url;
+  if (!bankUrl) {
+    throw new Error("ePayco no devolvió la URL del banco para completar el pago.");
+  }
+  return bankUrl;
+}
+
+// El carrito se completa (orden creada en estado "awaiting") ANTES de
+// redirigir al banco -- authorizePayment del modulo PSE devuelve
+// "pending_authorization" a proposito, que es justo el mecanismo de
+// Medusa para esto (ver AbstractPaymentProvider). La confirmacion real
+// llega despues via el webhook nativo de Medusa, no por esta llamada.
+export async function completeCart(cartId: string): Promise<void> {
+  const data = await medusaCartFetch(`/store/carts/${cartId}/complete`, { method: "POST" });
+  if (data.type === "cart") {
+    const error = (data as { error?: { message?: string } }).error;
+    throw new Error(error?.message || "No se pudo completar el pedido.");
+  }
+}

workloads/ecommerce/store/cart-store.ts

@@ -2,60 +2,117 @@
 
 import { create } from "zustand";
 import { createJSONStorage, persist } from "zustand/middleware";
-import type { Product } from "@/lib/headless/types";
+import type { CartLine } from "@/lib/headless/providers/medusa-cart";
 
-export interface CartItem {
-  product: Product;
-  quantity: number;
-  variantId?: string;
-}
+// ADR 0009: carrito real conectado a un cart_id de Medusa (Store API,
+// via /api/cart/*) en vez de estado 100% local -- precios y existencia
+// de linea son los que confirma el servidor, no un calculo optimista
+// en el cliente. Primer corte a proposito: sin UI de direccion/envio
+// todavia, el checkout sigue cerrando por WhatsApp (CartDrawer).
+export type CartItem = CartLine;
 
 interface CartState {
+  cartId: string | null;
   items: CartItem[];
   isOpen: boolean;
   hasHydrated: boolean;
   openCart: () => void;
   closeCart: () => void;
   setHasHydrated: (value: boolean) => void;
-  addItem: (product: Product, variantId?: string) => void;
-  removeItem: (productId: string) => void;
-  updateQuantity: (productId: string, quantity: number) => void;
-  clearCart: () => void;
+  addItem: (product: { id: string }, variantId?: string) => Promise<void>;
+  removeItem: (productId: string) => Promise<void>;
+  updateQuantity: (productId: string, quantity: number) => Promise<void>;
+  clearCart: () => Promise<void>;
+  syncCart: () => Promise<void>;
+}
+
+async function postJson(url: string, body: unknown) {
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  return response.json();
 }
 
 export const useCartStore = create<CartState>()(
   persist(
-    (set) => ({
+    (set, get) => ({
+      cartId: null,
       items: [],
       isOpen: false,
       hasHydrated: false,
       openCart: () => set({ isOpen: true }),
       closeCart: () => set({ isOpen: false }),
       setHasHydrated: (value) => set({ hasHydrated: value }),
-      addItem: (product, variantId) => set((state) => {
-        const existing = state.items.find(
-          (item) => item.product.id === product.id && item.variantId === variantId,
+
+      addItem: async (product, variantId) => {
+        set({ isOpen: true });
+        if (!variantId) return;
+
+        let cartId = get().cartId;
+        if (!cartId) {
+          const cart = await (await fetch("/api/cart", { method: "POST" })).json();
+          if (!cart.cartId) return;
+          cartId = cart.cartId;
+          set({ cartId, items: cart.items ?? [] });
+        }
+
+        const cart = await postJson("/api/cart/items", { cartId, variantId, quantity: 1 });
+        if (cart.items) set({ items: cart.items });
+      },
+
+      removeItem: async (productId) => {
+        const { cartId, items } = get();
+        const line = items.find((item) => item.product.id === productId);
+        if (!cartId || !line) return;
+        const response = await fetch(`/api/cart/items/${line.lineItemId}?cartId=${cartId}`, { method: "DELETE" });
+        const cart = await response.json();
+        if (cart.items) set({ items: cart.items });
+      },
+
+      updateQuantity: async (productId, quantity) => {
+        if (quantity <= 0) return get().removeItem(productId);
+        const { cartId, items } = get();
+        const line = items.find((item) => item.product.id === productId);
+        if (!cartId || !line) return;
+        const cart = await postJson(`/api/cart/items/${line.lineItemId}`, { cartId, quantity });
+        if (cart.items) set({ items: cart.items });
+      },
+
+      clearCart: async () => {
+        const { cartId, items } = get();
+        if (!cartId) return;
+        await Promise.all(
+          items.map((item) => fetch(`/api/cart/items/${item.lineItemId}?cartId=${cartId}`, { method: "DELETE" })),
         );
-        const items = existing
-          ? state.items.map((item) => item === existing ? { ...item, quantity: item.quantity + 1 } : item)
-          : [...state.items, { product, quantity: 1, variantId }];
-        return { items, isOpen: true };
-      }),
-      removeItem: (productId) => set((state) => ({
-        items: state.items.filter((item) => item.product.id !== productId),
-      })),
-      updateQuantity: (productId, quantity) => set((state) => ({
-        items: quantity <= 0
-          ? state.items.filter((item) => item.product.id !== productId)
-          : state.items.map((item) => item.product.id === productId ? { ...item, quantity } : item),
-      })),
-      clearCart: () => set({ items: [] }),
+        set({ items: [] });
+      },
+
+      // Al recargar la pagina, el cart_id guardado en localStorage puede
+      // llevar dias -- se refresca contra el servidor en vez de confiar en
+      // el ultimo snapshot local (precios/stock pudieron cambiar).
+      syncCart: async () => {
+        const cartId = get().cartId;
+        if (!cartId) return;
+        try {
+          const response = await fetch(`/api/cart?cartId=${cartId}`);
+          if (!response.ok) return;
+          const cart = await response.json();
+          if (cart.items) set({ items: cart.items });
+        } catch {
+          // Sin red: se queda con el ultimo estado local conocido.
+        }
+      },
     }),
     {
-      name: "ari-shopping-cart-v4",
+      name: "ari-shopping-cart-v5",
       storage: createJSONStorage(() => localStorage),
-      partialize: (state) => ({ items: state.items }),
-      onRehydrateStorage: () => (state) => state?.setHasHydrated(true),
+      partialize: (state) => ({ cartId: state.cartId, items: state.items }),
+      onRehydrateStorage: () => (state) => {
+        state?.setHasHydrated(true);
+        void state?.syncCart();
+      },
     },
   ),
 );

workloads/ecommerce/store/customer-store.ts

@@ -0,0 +1,123 @@
+"use client";
+
+import { create } from "zustand";
+import { createJSONStorage, persist } from "zustand/middleware";
+
+// Cuenta de cliente real conectada a Medusa (Store API, via
+// /api/customer/*), mismo patron que cart-store.ts: token + datos basicos
+// persistidos en localStorage, resincronizados contra el servidor al
+// rehidratar (el token puede llevar dias, o haber sido revocado).
+export interface Customer {
+  id: string;
+  email: string;
+  firstName: string | null;
+  lastName: string | null;
+}
+
+interface CustomerState {
+  token: string | null;
+  customer: Customer | null;
+  hasHydrated: boolean;
+  loading: boolean;
+  error: string | null;
+  setHasHydrated: (value: boolean) => void;
+  register: (email: string, password: string, firstName: string, lastName: string) => Promise<boolean>;
+  login: (email: string, password: string) => Promise<boolean>;
+  loginWithGoogle: (code: string, state: string) => Promise<boolean>;
+  logout: () => void;
+  syncCustomer: () => Promise<void>;
+}
+
+async function postJson(url: string, body: unknown) {
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  return response.json();
+}
+
+function toCustomer(data: Record<string, unknown>): Customer {
+  return {
+    id: data.id as string,
+    email: data.email as string,
+    firstName: (data.firstName as string | null) ?? null,
+    lastName: (data.lastName as string | null) ?? null,
+  };
+}
+
+export const useCustomerStore = create<CustomerState>()(
+  persist(
+    (set, get) => ({
+      token: null,
+      customer: null,
+      hasHydrated: false,
+      loading: false,
+      error: null,
+      setHasHydrated: (value) => set({ hasHydrated: value }),
+
+      register: async (email, password, firstName, lastName) => {
+        set({ loading: true, error: null });
+        const result = await postJson("/api/customer/register", { email, password, firstName, lastName });
+        if (result.error) {
+          set({ loading: false, error: result.error });
+          return false;
+        }
+        set({ loading: false, token: result.token, customer: toCustomer(result) });
+        return true;
+      },
+
+      login: async (email, password) => {
+        set({ loading: true, error: null });
+        const result = await postJson("/api/customer/login", { email, password });
+        if (result.error) {
+          set({ loading: false, error: result.error });
+          return false;
+        }
+        set({ loading: false, token: result.token, customer: toCustomer(result) });
+        return true;
+      },
+
+      loginWithGoogle: async (code, state) => {
+        set({ loading: true, error: null });
+        const result = await postJson("/api/customer/google/callback", { code, state });
+        if (result.error) {
+          set({ loading: false, error: result.error });
+          return false;
+        }
+        set({ loading: false, token: result.token, customer: toCustomer(result) });
+        return true;
+      },
+
+      logout: () => set({ token: null, customer: null, error: null }),
+
+      // El token guardado en localStorage puede llevar dias o haber sido
+      // revocado -- se refresca contra el servidor en vez de confiar en el
+      // ultimo snapshot local.
+      syncCustomer: async () => {
+        const token = get().token;
+        if (!token) return;
+        try {
+          const response = await fetch(`/api/customer/me?token=${encodeURIComponent(token)}`);
+          if (!response.ok) {
+            set({ token: null, customer: null });
+            return;
+          }
+          const result = await response.json();
+          if (result.id) set({ customer: toCustomer(result) });
+        } catch {
+          // Sin red: se queda con el ultimo estado local conocido.
+        }
+      },
+    }),
+    {
+      name: "ari-shopping-customer-v1",
+      storage: createJSONStorage(() => localStorage),
+      partialize: (state) => ({ token: state.token, customer: state.customer }),
+      onRehydrateStorage: () => (state) => {
+        state?.setHasHydrated(true);
+        void state?.syncCustomer();
+      },
+    },
+  ),
+);