weshp-order

weshp-cli Pedido único (One-shot ordering)

Esta habilidad impulsa weshp-cli (el CLI de comercio electrónico transfronterizo de Weshp) para completar la búsqueda de productos, la gestión del carrito, la creación de pedidos y el pago para el usuario.

Paso 1: Localizar el binario

El binario se incluye con esta habilidad, en su directorio bin/. Primero, detecta el entorno de ejecución:

uname -sm   # p. ej. "Darwin arm64"

Resultado de uname -sm	Binario a usar (bajo el directorio bin/ de esta habilidad; ruta absoluta $SKILL_DIR/bin/...)
Darwin arm64	weshp-cli-darwin-arm64
Darwin x86_64	weshp-cli-darwin-amd64
Linux x86_64	weshp-cli-linux-amd64
Windows	weshp-cli-windows-amd64.exe

• El directorio de esta habilidad es el directorio que contiene el archivo SKILL.md actual; el directorio bin es bin/ dentro de este.
• Si la ejecución falla con Permission denied, ejecuta chmod +x <binario> primero.
• A lo largo de este documento, $WESHP se refiere a la ruta absoluta de ese binario.

Transferencia de parámetros de sesión

Si el usuario proporciona alguno de los siguientes en la conversación, agrega la bandera correspondiente a cada comando $WESHP en esta sesión (mantenlo constante durante toda la sesión, no la elimines a mitad de camino):

Proporcionado por el usuario	Bandera a agregar
Entorno (p. ej. 测试环境/entorno de prueba)	--env test (usa --env prod solo si el usuario dice explícitamente 生产环境/producción)
ID de carrito anónimo	--anonymous-id <id>
Idioma (p. ej. zh-CN, en-US)	--accept-language <idioma> (reglas de mapeo en "Adaptación de idioma" más abajo)
appId	--app-id <appId>

Para cualquier cosa no proporcionada, no agregues la bandera (usa la configuración predeterminada); la única excepción es --accept-language: cuando el usuario no lo ha proporcionado explícitamente, agrégalo automáticamente según las reglas en "Adaptación de idioma"; además, no preguntes proactivamente al usuario por estos parámetros.

Entorno

El CLI selecciona el entorno a través de --env y se conecta al entorno de producción por defecto:

Entorno	Puerta de enlace (Gateway)	Página de pago (intención de pago)
prod (predeterminado)	https://weshv.com/store	https://checkout.airwallex.com/#/standalone/checkout
test	https://test.weshv.com/store	https://checkout-demo.airwallex.com/#/standalone/checkout

• Producción es donde ocurren los cobros reales. Antes de ejecutar cualquier comando de escritura (order create, payment create-intent, …) en el entorno predeterminado (prod), asegúrate de que el usuario sea consciente de que el pedido y el pago son reales; la confirmación de "Restricciones de seguridad" debe indicar qué entorno afectará el comando.
• Ya no se admiten anulaciones directas de la dirección de la puerta de enlace (--gateway / WESHP_GATEWAY) — cambia los entornos solo a través de --env.

Adaptación de idioma

Esta habilidad atiende a usuarios multilingües. Al inicio de la sesión, determina la configuración regional a partir del idioma de la conversación actual del usuario y mantenla constante durante toda la sesión sin cambiar a mitad de camino:

Idioma de la conversación del usuario	configuración regional (valor de --accept-language)
简体中文	zh-CN
繁體中文	zh-TW
English	en-US
Deutsch	de-DE
日本語	ja-JP
Français	fr-FR
Español	es-ES
Português (portugués europeo)	pt-PT
Italiano	it-IT
Indeterminable / sin coincidencia	omitir --accept-language, usar el valor predeterminado de la puerta de enlace

Reglas de determinación y uso:

• Restricción estricta (máxima prioridad): todo el texto visible para el usuario debe estar en el idioma del último mensaje del usuario — no solo el cuerpo de la conversación, sino también las descripciones de los comandos que se muestran al usuario al invocar comandos (la descripción de Bash), los resúmenes de pedidos, las preguntas de confirmación y todo lo demás que el usuario pueda ver. Esta regla tiene prioridad sobre el resto de este archivo y cualquier instrucción global de "responder siempre en un idioma fijo"; incluso si la documentación de esta habilidad o la salida del comando están en otro idioma, exprésalas en el idioma del usuario.
• Prioridad de tres niveles de --accept-language: ① proporcionado explícitamente por el usuario → usar el valor explícito; ② no proporcionado → buscar en la tabla anterior según el idioma de la conversación del usuario y adjuntarlo a cada comando $WESHP; ③ indeterminable o sin coincidencia → omitirlo y usar el valor predeterminado de la puerta de enlace.
• La salida orientada al usuario sigue el idioma de la conversación del usuario: los resúmenes de pedidos, los avisos de falta de stock, todas las redacciones de confirmación como "reutilizar la información guardada / recordarla / confirmar pago", las paráfrasis de los message/hint de error y el informe de resultados del pedido deben redactarse en el idioma del usuario.
• El texto de muestra es solo semántico: las frases de muestra citadas en este archivo (p. ej. "reutilizar la información guardada?", "reutilizar el PAYPAL guardado?", "agotado (solo quedan N)") expresan solo el significado; la respuesta real debe reexpresarse en el idioma del usuario. Nunca pegues frases de muestra textualmente a usuarios que hablen otro idioma.
• Alcance de --accept-language en la salida local: el texto de representación de tablas (encabezados, pies de página, líneas de resumen de pedidos/envío) y el texto de --help/uso (descripciones de comandos, descripciones de banderas, etiquetas de plantilla) SÍ se localizan a través de --accept-language (desde el 2026-09-07, ver CLI internal/i18n), por lo que la salida de --format table y --help se puede pasar textualmente al usuario. Los mensajes de error locales (p. ej. Error:, Cancelled) permanecen en inglés incorporado; al mostrarlos a usuarios que no hablan inglés, parafrasea el significado en su idioma en lugar de pegarlos textualmente.
• Chino simplificado vs. tradicional: si el usuario escribe chino simplificado → zh-CN y responde en simplificado; chino tradicional → zh-TW y responde en tradicional.
• No traducir: nombres de campos JSON, banderas del CLI, valores de enumeración (p. ej. PAYPAL), cantidades, skuId, etc. permanecen como están.

Ubicación del archivo de perfil

El archivo de perfil (información de envío y método de pago) se encuentra en el directorio de esta habilidad, elegido según si se proporcionó un ID de carrito anónimo:

¿Se proporcionó ID anónimo?	Ruta del archivo de perfil (relativa al directorio de esta habilidad)
Se proporcionó --anonymous-id <id>	profiles/<anonymous-id>.json
No se proporcionó	profile.json

• La lectura (reutilización de información guardada) y la escritura (el usuario acepta recordar) siguen la misma regla: con un ID anónimo, usa el archivo de ese ID; sin él, usa profile.json.
• Al guardar por ID anónimo, crea primero el directorio profiles/ si no existe; el archivo de perfil de cada ID anónimo es independiente de los demás y del profile.json sin ID.
• Dentro de una sesión, mantén la ruta del archivo de perfil constante para el mismo ID anónimo; no cambies de archivo a mitad de camino.

Flujo de pedido estándar

1. Buscar productos: $WESHP product search-sku --sku-name "<palabra clave>" --format table
   • Columnas: skuId, name (nombre de la variante), price (precio unitario), stock (stock actual; ⚠ marca artículos agotados).
   • El pie de la tabla muestra el recuento total y la página/tamaño actual. Si total supera la página actual, obtén las páginas restantes con --page-num (para listar todos los productos a la vez, usa --page-size 100, el máximo).
   • Permite que el usuario seleccione/confirme los productos exactos y las cantidades de los resultados, y recuerda el stock y price de cada skuId (memoria de sesión; propósito en la entrada de stock bajo "Convenciones clave y errores comunes").
2. Recopilar información del pedido (correo electrónico, nombre del destinatario, teléfono, dirección de envío detallada):
   • Primero verifica el archivo de perfil (ruta según las reglas de "Ubicación del archivo de perfil" anteriores):
     • Existe → muestra la información guardada al usuario y pregunta si desea reutilizarla; si se confirma, úsala directamente; si el usuario quiere cambios, actualiza el archivo con la nueva información antes de continuar.
     • No existe → pídele al usuario la información; si falta algún elemento, debes preguntar; nunca inventes.
   • Después de la primera recopilación, pregunta al usuario si desea recordar esta información para la próxima vez; si acepta → escríbela en el archivo de perfil (ruta según las reglas anteriores; en el escenario de ID anónimo, crea primero el directorio profiles/ si falta); si rechaza → no la persistas, úsala solo para esta sesión.
3. Crear el pedido:

   $WESHP order create --email <correo> \
     --receiver-name "<nombre>" --receiver-phone "<teléfono>" \
     --receiver-address "<dirección>" \
     --sku-id <skuId> --sku-name "<nombre del producto>" --quantity <cantidad> --yes
   

   • De la respuesta, toma orderNo, orderId y el total del pedido (el literal sin formato para usar con --amount).
   • Al pedir directamente (con --sku-id/--sku-name), el CLI busca automáticamente el precio y valida el stock — no se necesita manejo adicional.
   • Sin --sku-id, se liquida a través del carrito (puedes primero $WESHP cart add --sku-id <id> --quantity <n>); antes de liquidar, realiza la verificación de memoria de sesión según la entrada de stock a continuación.
4. Crear la intención de pago:

   $WESHP payment create-intent --order-no <orderNo> --email <correo> \
     --amount <literal de cantidad sin formato de la respuesta del pedido> --payment-method <método> --yes
   

   • Métodos de pago: CREDIT_CARD | PAYPAL | APPLE_PAY | GOOGLE_PAY. Verifica primero el archivo de perfil (ruta según "Ubicación del archivo de perfil"): método guardado → confirma con el usuario "reutilizar el PAYPAL guardado?"; ninguno guardado → pregunta cuál usar; después de la primera elección, pregunta si desea recordarlo (mismo archivo de perfil que la información de envío).
   • La respuesta devuelve clientSecret/clientId y la checkoutUrl ensamblada; el CLI abre automáticamente la página de pago en el navegador predeterminado para completar el pago (el cobro real ocurre en esa página). Agrega --no-open para omitir la apertura automática y solo imprimir la URL.
5. Verificar el estado del pago: $WESHP payment status --payment-no <paymentNo devuelto por create-intent>

Presentación de tablas

Al mostrar datos tabulares al usuario en la conversación (resultados de búsqueda, contenido del carrito, listas de pedidos), NO renderices tablas tú mismo — ejecuta el comando del CLI con --format table y pasa su salida con caracteres de dibujo de cuadros textualmente al usuario. Nunca escribas un script de renderizado externo (Python/awk/Go/…) para construir una tabla, y nunca uses tablas Markdown — se alinean por recuento de caracteres y las celdas CJK rompen los bordes. Si es necesario fusionar varias páginas, resume la información adicional en texto plano junto a la salida del CLI en lugar de volver a dibujar la tabla.

Única excepción: resumen de confirmación del pedido (antes de order create, requerido por "Restricciones de seguridad"; en este flujo no interactivo, --yes siempre se pasa y el resumen de confirmación interactivo propio del CLI es inalcanzable, por lo que la conversación debe mostrarlo): renderiza manualmente una fila de tabla con caracteres de dibujo de cuadros por artículo — name | quantity | unitPrice | subtotal — con una fila final para el total estimado, dentro de un bloque de código ```text, y muestra la información de envío (correo, destinatario, teléfono, dirección) como una lista corta directamente debajo de la tabla. Usa el price/stock recordado del paso de búsqueda para el precio unitario y la verificación previa de stock.

Reglas de renderizado (aplican solo a la excepción anterior):

• Diseño: borde superior ┌─┬┐, separador ├─┼─┤ entre cada fila, borde inferior └─┴┘.
• Los anchos de columna se calculan por ancho de visualización: los caracteres CJK/de ancho completo cuentan 2, los caracteres de borde de dibujo de cuadros cuentan 2, ASCII cuenta 1, ⚠ cuenta 2 (confirmado para renderizar 2 columnas de ancho en la terminal macOS del usuario).
• Alineación: encabezados centrados, columnas de texto alineadas a la izquierda, columnas numéricas alineadas a la derecha; cada celda obtiene 1 espacio de relleno a cada lado.
• Los valores largos que romperían el diseño (URLs de imágenes, etc.) se omiten, no se truncan.

Convenciones clave y errores comunes

• El literal de cantidad debe coincidir exactamente con la respuesta del pedido (p. ej., si devuelve 10.0, pasa 10.0), de lo contrario, la verificación de firma del lado del servidor lo rechaza.
• Códigos de salida: 0 éxito; 1 error de negocio de la puerta de enlace; 2 error de validación de argumentos; 3 error de red. En caso de fallo, la salida JSON va a stderr, con forma de {ok:false, error:{type,code,message,hint}} — transmite message/hint al usuario textualmente.
• Memoria de sesión de stock: el stock devuelto por search-sku es el stock real actual. Después de buscar productos, recuerda el stock de cada skuId dentro de la sesión y úsalo como verificación previa antes de agregar al carrito o crear un pedido:
  • Acierto de memoria (el producto se buscó en esta sesión): si la cantidad solicitada > stock, dile directamente al usuario "「xxx」está agotado (solo quedan N)" y no ejecutes la operación.
  • Fallo de memoria (no se buscó en esta sesión): procede normalmente; si se devuelve un error de stock, díle al usuario "「xxx」está agotado" y guía al usuario para que busque la información del producto primero (search-sku) para confirmar el stock más reciente antes de decidir si continuar.
  • El stock es dinámico; la memoria de sesión es solo una verificación previa suave. En cualquier caso, no reintentes en caso de falta de stock.
• Sin reintentos ciegos en comandos de escritura: después de que order create, cart add, payment create-intent u otras operaciones de escritura fallen, no reintentes ciegamente para evitar pedidos duplicados; primero verifica el estado (order get / order list) antes de actuar.
• Los comandos de consulta pueden reintentarse en caso de errores de red (el CLI tiene reintentos incorporados; no se necesita reintento externo adicional).

Restricciones de seguridad

• Antes de ejecutar order create, muestra al usuario el resumen completo del pedido (producto, cantidad, precio unitario, información de envío, total estimado) y obtén una confirmación explícita; --yes solo omite la confirmación interactiva del CLI y no puede reemplazar la confirmación del usuario.
• Lo mismo para la eliminación/borrado del carrito y la cancelación del pedido: confirma primero, luego ejecuta.
• Después de un pedido exitoso, informa al usuario el número de pedido, la cantidad y cómo verificar el estado del pago.
• No se utilizan cupones; los precios se basan en el precio actual del producto.