PDC de paiement partagé : invite de l’IA de l’orchestrateur App Builder

Utilisez cette page pour copier l’invite complète qui génère le projet split-pay-orchestrator : le pay-orchestrator consommateur d’événement d’E/S, pay-accept et pay-deny actions web, le demo-dashboard et le client REST Commerce.

Utiliser cette invite

Copiez tout du DÉBUT INVITE au Fin de l’invite dans Cursor (avec Claude) ou directement dans Claude. Exécutez l’invite à partir du répertoire split-payment-orchestrator/ (racine du projet App Builder).

Avant d’exécuter

L’invite

DÉBUT DE L’INVITE

Vous générez une application Adobe App Builder complète pour orchestrer les paiements partagés dans Adobe Commerce. Cette application reçoit les événements d’E/S de Commerce, traite les décisions de paiement fractionné et appelle de nouveau Commerce via REST.

Projet: split-payment-orchestrator
Runtime: Node.js 18
Dépendances clés : @adobe/aio-sdk ^6.0.0, got ^11.8.6, oauth-1.0a ^2.2.6

Générez tous les fichiers répertoriés ci-dessous. L’application doit fonctionner avec Adobe I/O Runtime (aio app deploy).

Structure de fichier à générer

split-payment-orchestrator/
├── package.json
├── app.config.yaml
├── .env.example
└── actions/
    ├── payment-orchestrator/
    │   ├── index.js         ← I/O Event entry point
    │   ├── commerce-client.js
    │   ├── threshold.js
    │   ├── cash-payment.js
    │   ├── order-update.js
    │   └── store-credit.js  ← Deprecated stub; kept for reference
    ├── payment-accept/
    │   └── index.js
    ├── payment-decline/
    │   └── index.js
    └── demo-dashboard/
        └── index.js

package.json

{
  "name": "split-payment-orchestrator",
  "version": "1.0.0",
  "private": true,
  "description": "Adobe App Builder action — split payment PoC orchestrator",
  "engines": { "node": ">=18" },
  "scripts": {
    "deploy": "NODE_OPTIONS=--disable-warning=DEP0040 aio app deploy",
    "aio": "NODE_OPTIONS=--disable-warning=DEP0040 aio"
  },
  "dependencies": {
    "@adobe/aio-sdk": "^6.0.0",
    "@adobe/exc-app": "^1.5.9",
    "got": "^11.8.6",
    "oauth-1.0a": "^2.2.6"
  }
}

app.config.yaml

Définissez quatre actions dans le package split_payment_orchestrator :

payment-orchestrator

payment-accept

payment-decline

demo-dashboard

Enregistrement des événements (sous events.registrations) :

Split payment — sales order place before:
  description: Invokes payment-orchestrator when an order is about to be placed
  events_of_interest:
    - provider_metadata: dx_commerce_events
      event_codes:
        - com.adobe.commerce.observer.sales_order_place_before
  runtime_action: split_payment_orchestrator/payment-orchestrator

actions/payment-orchestrator/commerce-client.js

Client REST OAuth 1.0a partagé pour Adobe Commerce. Implémente :

createCommerceClient(params, logger) — renvoie { request, baseUrl }

actions/payment-orchestrator/threshold.js

evaluateThreshold({ orderTotal, storeCreditAmount, cashAmount, params, logger }) — renvoie { pass: boolean, reason: string }

Logique :

actions/payment-orchestrator/cash-payment.js

recordCashPending({ commerce, orderId, cashAmount, logger }) — renvoie { ok: boolean, error? }

actions/payment-orchestrator/order-update.js

updateOrderAfterOrchestration({ commerce, orderId, success, detail, logger }) — renvoie { ok: boolean, error? }

actions/payment-orchestrator/store-credit.js

applyStoreCredit({ commerce, cartId, amount, logger }) : mise en œuvre obsolète sans opération

Incluez ce fichier avec un avis de @deprecated JSDoc expliquant :

L’orchestrateur n’applique plus de crédit de magasin via REST. Le crédit de magasin est appliqué lors du passage en caisse dans le module Commerce PHP (PlaceOrderPlugin) à l’aide de BalanceManagementInterface::apply(), qui nécessite un panier actif. Lorsque App Builder reçoit l’événement d’E/S, le panier est inactif. Ce fichier est conservé à titre de référence ou pour les flux personnalisés où le crédit de magasin est appliqué après la commande.

Conservez une implémentation fonctionnelle (la même forme que les autres modules) afin que les développeurs puissent étudier le modèle, mais marquez-le clairement comme n’étant pas utilisé dans le flux actuel.

actions/payment-orchestrator/index.js

Point d’entrée des événements I/O. Implémente async function main(params).

Extraction de la payload :

Les événements d’Adobe Commerce I/O peuvent diffuser la payload sous plusieurs formes. Extrayez l’objet de valeur d’ordre en vérifiant ces chemins dans l’ordre :

Extraction du champ à partir de la valeur :

Flux:

Important : toujours renvoyer statusCode: 200 — I/O Runtime réessaiera les réponses non-200, ce qui entraînerait un traitement des commandes en double. Des erreurs sont signalées dans le corps.

PUBLIC_ERRORconstante : "Payment could not be processed. Please try again or contact support." — utilisée pour tous les messages d’erreur orientés vers l’extérieur.

actions/payment-accept/index.js

Action web HTTP. Appels POST /V1/split-payment/orders/:orderId/cash-received.

Résolution de l’ID de commande : cochez params.orderId, puis params.payload.orderId et params.__ow_body (JSON analysé). Renvoie 400 en cas d’absence.

Flux:

actions/payment-decline/index.js

Action web HTTP. Même modèle que payment-accept, mais appelle POST /V1/split-payment/orders/:orderId/cash-decline.

Renvoyer la { ok: true, orderId, message: 'declined' } en cas de succès.

actions/demo-dashboard/index.js

Tableau de bord autonome de l’opérateur de démonstration. Fournit un tableau de bord HTML pour répertorier les commandes en espèces en attente et déclencher des actions d’acceptation/refus. Il s’agit d’une action web unique qui sert à la fois l’interface utilisateur d’HTML et une API JSON.

Sécurité:

Routage (basé sur la méthode HTTP + chemin/corps) :

L’action reçoit toutes les demandes. Déterminez l’intention à partir de :

Récupération des commandes en attente :

Tableau de bord HTML :
Le tableau de bord est une chaîne HTML renvoyée avec Content-Type: text/html. Il devrait :

Erreur lors de l’affichage dans l’interface utilisateur :
Lorsqu’un appel REST Commerce échoue, incluez le statut HTTP et une brève description du corps de l’erreur Commerce (sanitize — supprimer les balises HTML, tronquer à 500 caractères). N’exposez pas les informations d’identification.

Assistants de réponse :

function jsonResponse(statusCode, obj, extraHeaders = {}) { ... }
function htmlResponse(html) { ... }

.env.example

# Commerce REST base URL — no trailing slash
COMMERCE_BASE_URL=

# OAuth 1.0a integration credentials (Admin → System → Integrations)
COMMERCE_CONSUMER_KEY=
COMMERCE_CONSUMER_SECRET=
COMMERCE_ACCESS_TOKEN=
COMMERCE_ACCESS_TOKEN_SECRET=

# PoC threshold — must match split_payment/general/threshold in Commerce (default: 100)
PAYMENT_THRESHOLD=100

LOG_LEVEL=info

# Demo dashboard optional shared secret
DEMO_UI_SECRET=
DEMO_UI_BASE_URL=

Déployer la commande

Après avoir généré tous les fichiers, à partir du répertoire split-payment-orchestrator/ :

npm install
cp .env.example .env
# Edit .env with your credentials
aio app deploy

Après le déploiement, notez les URL d’action imprimées par aio app deploy. L’URL demo-dashboard vous permet d’accéder au tableau de bord de l’opérateur.

Fin de l’invite

Toutes les ressources de cette série

Ressources de référence