weshp-order

weshp-cli Pedido Único

Esta habilidade guia o weshp-cli (a CLI de e-commerce cross-border Weshp) para concluir pesquisa de produtos, gerenciamento de carrinho, criação de pedidos e pagamento para o usuário.

Passo 1: Localizar o binário

O binário é fornecido com esta habilidade, em seu diretório bin/. Primeiro, detecte o ambiente de execução:

uname -sm   # ex.: "Darwin arm64"

Resultado de uname -sm	Binário a usar (no diretório bin/ da habilidade; caminho absoluto $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

• O diretório desta habilidade é o diretório que contém o arquivo SKILL.md atual; o diretório bin é bin/ dentro dele.
• Se a execução falhar com Permission denied, execute chmod +x <binário> primeiro.
• Ao longo deste documento, $WESHP refere-se ao caminho absoluto desse binário.

Passagem de parâmetros de sessão

Se o usuário fornecer algum dos itens a seguir na conversa, anexe a flag correspondente a cada comando $WESHP nesta sessão (mantenha-a consistente durante toda a sessão, não a remova no meio):

Fornecido pelo usuário	Flag a anexar
Ambiente (ex.: 测试环境/ambiente de teste)	--env test (use --env prod apenas se o usuário disser explicitamente 生产环境/produção)
ID do carrinho anônimo	--anonymous-id <id>
Idioma (ex.: zh-CN, en-US)	--accept-language <idioma> (regras de mapeamento em "Adaptação de idioma" abaixo)
appId	--app-id <appId>

Para qualquer item não fornecido, não adicione a flag (use a configuração padrão) — a única exceção é --accept-language: quando o usuário não o forneceu explicitamente, anexe-o automaticamente de acordo com as regras em "Adaptação de idioma"; também não pergunte proativamente ao usuário sobre esses parâmetros.

Ambiente

A CLI seleciona o ambiente via --env e conecta-se ao ambiente de produção por padrão:

Ambiente	Gateway	Página de checkout (intenção de pagamento)
prod (padrão)	https://weshv.com/store	https://checkout.airwallex.com/#/standalone/checkout
test	https://test.weshv.com/store	https://checkout-demo.airwallex.com/#/standalone/checkout

• Produção é onde ocorrem cobranças reais. Antes de executar qualquer comando de escrita (order create, payment create-intent, …) no ambiente padrão (prod), certifique-se de que o usuário está ciente de que o pedido e o pagamento são reais; a confirmação das "Restrições de segurança" deve declarar em qual ambiente o comando será executado.
• Substituições diretas de endereço de gateway (--gateway / WESHP_GATEWAY) não são mais suportadas — alterne ambientes apenas via --env.

Adaptação de idioma

Esta habilidade atende usuários em vários idiomas. No início da sessão, determine a localidade a partir do idioma da conversa atual do usuário e mantenha-a consistente durante toda a sessão, sem alternar no meio:

Idioma da conversa do usuário	Localidade (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 Europeu)	pt-PT
Italiano	it-IT
Indeterminável / sem correspondência	omita --accept-language, use o padrão do gateway

Regras de determinação e uso:

• Restrição forte (prioridade máxima): todo o texto visível ao usuário deve estar no idioma da última mensagem do usuário — não apenas o corpo da conversa, mas também as descrições de comando mostradas ao usuário ao invocar comandos (a descrição Bash), resumos de pedidos, perguntas de confirmação e tudo o mais que o usuário possa ver. Esta regra tem prioridade sobre o restante deste arquivo e qualquer instrução global de "responda sempre em um idioma fixo"; mesmo que a documentação desta habilidade ou a saída do comando esteja em outro idioma, expresse-a no idioma do usuário.
• Prioridade de três níveis do --accept-language: ① fornecido explicitamente pelo usuário → use o valor explícito; ② não fornecido → procure na tabela acima pelo idioma da conversa do usuário e anexe-o a cada comando $WESHP; ③ indeterminável ou sem correspondência → omita-o e use o padrão do gateway.
• Saída voltada ao usuário segue o idioma da conversa do usuário: resumos de pedidos, avisos de falta de estoque, todas as palavras de confirmação como "reutilizar as informações salvas / lembrar / confirmar pagamento", paráfrases de message/hint de erro e o relatório de resultado do pedido devem ser escritos no idioma do usuário.
• Exemplos de texto são apenas semânticos: frases de exemplo citadas neste arquivo (ex.: "reutilizar as informações salvas?", "reutilizar o PAYPAL salvo?", "fora de estoque (restam apenas N)") expressam apenas o significado; a resposta real deve ser reexpressa no idioma do usuário. Nunca cole frases de exemplo literalmente para usuários que falam outro idioma.
• Escopo do --accept-language na saída local: texto de renderização de tabela (cabeçalhos, rodapés, linhas de resumo/envio) e texto --help/de uso (descrições de comando, descrições de flags, rótulos de modelo) SÃO localizados via --accept-language (desde 2026-09-07, veja CLI internal/i18n), então a saída de --format table e --help pode ser passada diretamente ao usuário. Mensagens de erro locais (ex.: Error:, Cancelled) permanecem em inglês incorporado — ao mostrá-las a usuários não-ingleses, parafraseie o significado no idioma deles em vez de colá-las literalmente.
• Chinês Simplificado vs. Tradicional: se o usuário escrever em Chinês Simplificado → zh-CN e responda em Simplificado; Chinês Tradicional → zh-TW e responda em Tradicional.
• Não traduza: nomes de campos JSON, flags da CLI, valores de enum (ex.: PAYPAL), valores, skuId, etc. permanecem como estão.

Localização do arquivo de perfil

O arquivo de perfil (informações de envio e método de pagamento) reside no diretório desta habilidade, escolhido com base no fornecimento de um ID de carrinho anônimo:

ID anônimo fornecido?	Caminho do arquivo de perfil (relativo ao diretório da habilidade)
--anonymous-id <id> fornecido	profiles/<anonymous-id>.json
Não fornecido	profile.json

• Leitura (reutilizar informações salvas) e escrita (usuário concorda em lembrar) seguem a mesma regra: com um ID anônimo, use o arquivo desse ID; sem, use profile.json.
• Ao salvar por ID anônimo, crie o diretório profiles/ primeiro se ele não existir; o arquivo de perfil de cada ID anônimo é independente dos outros e do profile.json sem ID.
• Dentro de uma sessão, mantenha o caminho do arquivo de perfil consistente para o mesmo ID anônimo; não alterne arquivos no meio.

Fluxo de pedido padrão

1. Pesquisar produtos: $WESHP product search-sku --sku-name "<palavra-chave>" --format table
   • Colunas: skuId, name (nome da variante), price (preço unitário), stock (estoque atual; ⚠ marca fora de estoque).
   • O rodapé da tabela mostra a contagem total e a página/tamanho atual. Se total exceder a página atual, busque as páginas restantes com --page-num (para listar todos os produtos de uma vez, use --page-size 100, o máximo).
   • Deixe o usuário escolher/confirmar os produtos e quantidades exatos dos resultados, e lembre-se do stock e price de cada skuId (memória de sessão; finalidade na entrada de estoque em "Principais convenções e armadilhas").
2. Coletar informações do pedido (e-mail, nome do destinatário, telefone, endereço de entrega detalhado):
   • Primeiro, verifique o arquivo de perfil (caminho conforme as regras de "Localização do arquivo de perfil" acima):
     • Existe → mostre as informações salvas ao usuário e pergunte se deseja reutilizá-las; se confirmado, use-as diretamente; se o usuário quiser alterações, atualize o arquivo com as novas informações antes de continuar.
     • Não existe → peça ao usuário; se algum item estiver faltando, você deve perguntar; nunca invente.
   • Após a primeira coleta, pergunte ao usuário se deseja lembrar estas informações para a próxima vez; concordar → escreva no arquivo de perfil (caminho conforme as regras acima; no cenário de ID anônimo, crie o diretório profiles/ primeiro se estiver faltando); recusar → não persista, use apenas para esta sessão.
3. Criar o pedido:

   $WESHP order create --email <email> \
     --receiver-name "<nome>" --receiver-phone "<telefone>" \
     --receiver-address "<endereço>" \
     --sku-id <skuId> --sku-name "<nome do produto>" --quantity <quantidade> --yes
   

   • Da resposta, extraia orderNo, orderId e o total do pedido (o literal bruto a ser usado para --amount).
   • Ao pedir diretamente (com --sku-id/--sku-name), a CLI automaticamente consulta o preço e valida o estoque — nenhuma manipulação extra necessária.
   • Sem --sku-id, ele liquida via carrinho (você pode primeiro $WESHP cart add --sku-id <id> --quantity <n>); antes de liquidar, faça a verificação de memória de sessão conforme a entrada de estoque abaixo.
4. Criar a intenção de pagamento:

   $WESHP payment create-intent --order-no <orderNo> --email <email> \
     --amount <literal bruto de valor da resposta do pedido> --payment-method <método> --yes
   

   • Métodos de pagamento: CREDIT_CARD | PAYPAL | APPLE_PAY | GOOGLE_PAY. Verifique o arquivo de perfil primeiro (caminho conforme "Localização do arquivo de perfil"): método salvo → confirme com o usuário "reutilizar o PAYPAL salvo?"; nenhum salvo → pergunte qual usar; após a primeira escolha, pergunte se deseja lembrá-lo (mesmo arquivo de perfil das informações de envio).
   • A resposta retorna clientSecret/clientId e o checkoutUrl montado; a CLI abre automaticamente a página de checkout no navegador padrão para concluir o pagamento (a cobrança real ocorre nessa página). Adicione --no-open para pular a abertura automática e apenas imprimir a URL.
5. Verificar status do pagamento: $WESHP payment status --payment-no <paymentNo retornado por create-intent>

Apresentação de tabelas

Ao mostrar dados tabulares para o usuário na conversa (resultados de pesquisa, conteúdo do carrinho, listas de pedidos), NÃO renderize tabelas você mesmo — execute o comando CLI com --format table e passe a saída com caracteres de caixa diretamente para o usuário. Nunca escreva um script de renderização externo (Python/awk/Go/…) para construir uma tabela e nunca use tabelas Markdown — elas alinham por contagem de caracteres e células CJK quebram as bordas. Se várias páginas precisarem ser mescladas, resuma as informações extras em texto simples ao lado da saída CLI em vez de redesenhar a tabela.

Única exceção — resumo de confirmação do pedido (antes de order create, exigido por "Restrições de segurança"; neste fluxo não interativo --yes é sempre passado e o resumo de confirmação interativo próprio da CLI é inacessível, então a conversa deve mostrá-lo): renderize manualmente uma linha de tabela com caracteres de caixa por item — nome | quantidade | preçoUnitário | subtotal — com uma linha final para o total estimado, dentro de um bloco de código ```text, e mostre as informações de envio (e-mail, destinatário, telefone, endereço) como uma lista curta diretamente abaixo da tabela. Use o price/stock lembrados da etapa de pesquisa para o preço unitário e a pré-verificação de estoque.

Regras de renderização (aplicam-se apenas à exceção acima):

• Layout: borda superior ┌─┬┐, separador ├─┼─┤ entre cada linha, borda inferior └─┴┘.
• Larguras das colunas são calculadas por largura de exibição: caracteres CJK/largura total contam como 2, caracteres de borda de caixa contam como 2, ASCII conta como 1, ⚠ conta como 2 (confirmado para renderizar 2 colunas de largura no terminal macOS do usuário).
• Alinhamento: cabeçalhos centralizados, colunas de texto alinhadas à esquerda, colunas numéricas alinhadas à direita; cada célula recebe 1 espaço de preenchimento de cada lado.
• Valores longos que explodiriam o layout (URLs de imagem, etc.) são omitidos, não truncados.

Principais convenções e armadilhas

• O literal de valor deve corresponder exatamente à resposta do pedido (ex.: se retornar 10.0, passe 10.0), caso contrário, a verificação de assinatura do lado do servidor o rejeita.
• Códigos de saída: 0 sucesso; 1 erro de negócio do gateway; 2 falha de validação de argumento; 3 erro de rede. Em caso de falha, a saída JSON vai para stderr, no formato {ok:false, error:{type,code,message,hint}} — repasse message/hint ao usuário literalmente.
• Memória de sessão de estoque: o stock retornado por search-sku é o estoque atual real. Após pesquisar produtos, lembre-se do estoque de cada skuId dentro da sessão e use-o como uma pré-verificação antes de adicionar ao carrinho / criar pedido:
  • Acerto na memória (o produto foi pesquisado nesta sessão): se a quantidade solicitada > estoque, diga diretamente ao usuário "「xxx」está fora de estoque (restam apenas N)" e não execute a operação.
  • Erro na memória (não pesquisado nesta sessão): prossiga normalmente; se um erro de estoque retornar, diga ao usuário "「xxx」está fora de estoque" e oriente o usuário a pesquisar informações do produto primeiro (search-sku) para confirmar o estoque mais recente antes de decidir se continua.
  • O estoque é dinâmico; a memória de sessão é apenas uma pré-verificação suave. Em ambos os casos, não tente novamente em caso de falta de estoque.
• Sem novas tentativas cegas em comandos de escrita: após order create, cart add, payment create-intent ou outras operações de escrita falharem, não tente novamente cegamente para evitar pedidos duplicados; verifique o status primeiro (order get / order list) antes de agir.
• Comandos de consulta podem ser repetidos em caso de erros de rede (a CLI tem novas tentativas internas; nenhuma nova tentativa externa adicional é necessária).

Restrições de segurança

• Antes de executar order create, mostre ao usuário o resumo completo do pedido (produto, quantidade, preço unitário, informações de envio, total estimado) e obtenha confirmação explícita; --yes apenas pula a confirmação interativa da CLI e não pode substituir a confirmação do usuário.
• O mesmo para exclusão/limpeza de carrinho e cancelamento de pedido: confirme primeiro, depois execute.
• Após um pedido bem-sucedido, informe o número do pedido, o valor e como verificar o status do pagamento ao usuário.
• Nenhum cupom é usado; os preços são baseados no preço atual do produto.