Exécution d’essai de l’agent de développement Adobe Commerce App Builder

Une présentation pratique pour créer, déployer et tester des cas d’utilisation d’extensibilité de Commerce avec l’agent de développement Adobe Commerce (CDA). Cette simulation couvre trois cas d’utilisation : un webhook de limite de quantité du panier, un blocage de commande de grande valeur et un archivage piloté par les événements pour les commandes bloquées, du plan directeur aux tests fonctionnels.

Prise en main

Comment signaler des problèmes et des commentaires

Tout au long de l’essai, vous rencontrez des bords rugueux, ce qui est normal lorsque vous travaillez avec une nouvelle fonctionnalité. Saisissez et partagez tout problème avec votre contact de programme Adobe à l’aide du modèle de retour d’informations fourni lors de l’intégration.

Conditions préalables

Comptes et accès

Outils

Un storefront Edge Delivery Services (EDS) est requis pour la validation fonctionnelle. Vous aurez besoin de :

Installez le standard storefront dans un dossier vide, en sélectionnant votre instance ACCS lorsque vous y êtes invité :

aio commerce extensibility app-setup -s aem-boilerplate-commerce -n storefront

Démarrez le storefront :

cd storefront
npm run start

Ouverture de l’agent de développement Commerce

Cas d’utilisation 1 : webhook du nombre maximal d’unités du panier

Ce cas pratique valide les limites de quantité du panier avant l’ajout d’un produit, à l’aide d’un webhook Commerce synchrone.

Étape du plan directeur

Saisissez l’invite suivante et cliquez sur Générer le plan directeur :

Add a validation webhook that runs before a product is added to the cart.

Use the Commerce webhook method observer.sales_quote_item_save_before (type before) — do not use
observer.checkout_cart_product_add_before, observer.sales_quote_add_item, or any other event.

Calculate the total by summing all quote line quantities and the quantity of the current item.
If the same SKU already exists in the quote, exclude its existing quantity to avoid double-counting.

If the total is greater than the maximum allowed, block the add and show:
"You have reached the maximum amount of items."

The maximum allowed must be configurable in Commerce Admin as max_cart_units, with default 10.

Map payload fields using name and source properties:
- name: item.qty, source: data.item.qty
- name: item.sku, source: data.item.sku
- name: quote, source: context_checkout_session.get_quote[items.qty,items.sku]

Set required: true and fallback_error_message: "You have reached the maximum amount of items."
on the webhook config.

When blocking the add, do not use exceptionOperation, because it serializes exceptionClass as class.
Instead, manually return an exception operation response whose body includes type:
{
  "op": "exception",
  "message": "You have reached the maximum amount of items.",
  "type": "\\Magento\\Framework\\GraphQl\\Exception\\GraphQlInputException"
}

Affinez le plan directeur en saisissant les détails dans la boîte de dialogue ou en cliquant sur l’une des pilules au-dessus de la boîte de dialogue (Remettre en question les hypothèses, Trouver les lacunes de conception, etc.). Une fois que vous êtes satisfait, cliquez sur Approuver le plan pour continuer.

Étape de développement

L’agent passe à l’étape de développement et commence à configurer l’espace de travail.

Une fois configuré, l’agent affiche une liste des tâches d’implémentation et commence à créer.

Une fois satisfait du code, cliquez sur l’onglet Intégrations pour continuer.

Configuration des intégrations

Connexion ou création d’un espace de travail App Builder

Pour créer ou connecter un projet App Builder, suivez les instructions à l’écran.

Si vous vous connectez à un espace de travail existant, assurez-vous qu’il dispose des éléments suivants :

Si vous créez un espace de travail, ajoutez manuellement l’API Adobe Commerce as a Cloud Service.

Cliquez sur Suivant pour continuer.

Connexion à Commerce

Sélectionnez votre instance ACCS dans la liste ou saisissez l’URL dans le champ URL de base REST puis cliquez sur Connecter l’instance Commerce. Cliquez sur Suivant pour continuer.

Connexion à GitHub

Connectez l’espace de travail à un référentiel GitHub en saisissant l’URL du référentiel et en utilisant l’application GitHub ou un jeton d’accès personnel. Cliquez sur Suivant pour continuer.

Configurer les variables d’environnement

Renseignez toutes les variables d’environnement requises par le projet.

Déployer

Cliquez sur Développer pour revenir à l’étape de développement, puis demandez à l’agent de se déployer dans le champ d’invite.

Confirmez le déploiement.

Associer l’application dans la gestion des applications

Installation et configuration dans App Management

Tests fonctionnels

Cas d’utilisation 2 : blocage de commande de grande valeur et code de vérification

Revenez à l’étape Plan directeur pour commencer ce cas d’utilisation.

Étape du plan directeur

Saisissez l’invite suivante et cliquez sur Générer le plan directeur :

Add a Commerce event priority subscription to `plugin.sales.api.order_management.place`.

Extract `entity_id` and `grand_total` from the Commerce event payload using event `fields` in `app.commerce.config.ts`.

Important: the runtime action receives a CloudEvents-shaped payload. For Commerce eventing extracted fields,
parse them from `params.data.value`, not directly from `params.data`. The handler must use:
- `params.data.value.entity_id`
- `params.data.value.grand_total`

When `grand_total` is greater than `order_hold_threshold`:
1. Generate a verification code locally.
2. Put the order on hold with state and status `holded`.
When putting the order on hold, save the verification code using `custom_attributes`, not `extension_attributes`.
The Commerce `POST V1/orders` payload should include:
{
  "entity": {
    "entity_id": <entity_id>,
    "state": "holded",
    "status": "holded",
    "custom_attributes": [
      {
        "attribute_code": "<hold_verification_attribute>",
        "value": "<verification_code>"
      }
    ]
  }
}
3. Save the verification code via a `POST V1/orders` Commerce REST API call.

Make these configurable in Commerce Admin:
- `order_hold_threshold`, default `500`
- `hold_verification_attribute`, default `lab_verification_code`

Validate inputs before use:
- `entity_id` must be a positive integer.
- `grand_total` must be a non-negative number.

Affinez le plan directeur si nécessaire, puis cliquez sur Approuver le plan pour continuer.

Développement, déploiement, association et installation

Suivez le même processus que celui utilisé dans le cas d’utilisation 1 pour passer des exigences à une application installée : il n’est pas nécessaire de reconfigurer les intégrations.

Tests fonctionnels

Cas d’utilisation 3 : archivage piloté par les événements pour les commandes retenues

Revenez à l’étape Plan directeur pour commencer ce cas d’utilisation.

Étape du plan directeur

Saisissez l’invite suivante et cliquez sur Générer le plan directeur :

When an order is saved with state holded, archive it to external storage and
record a reference that can be looked up later by order ID.

Add an event priority subscription on observer.sales_order_save_after, filtered to fire only when
state equals holded. From the event payload, extract:
- `entity_id`
- `payment.amount_ordered`
- `custom_attributes` (to read the `lab_verification_code` attribute set in Step 3)

The event handler must:
1. Persist the order details to the `held_orders` App Builder DB collection:
{
  "order_id": <entity_id>,
  "grand_total": <payment.amount_ordered>,
  "verification_code": <lab_verification_code>,
  "archived_at": <ISO timestamp>
}
2. Ensure the record can be looked up later by order ID.

The `held_orders` collection must exist before the handler runs:
- Provision persistent App Builder Database Storage in region `amer`.
- Create the collection during app installation.
- Create a unique index on `order_id` during installation.
- Drop the whole `held_orders` collection when the app is uninstalled.

Register the event handler separately from the existing cart validation webhook and high-value order hold action:
- runtime action: `order-archive/archive-held-order`
- non-web action
- `include-ims-credentials: true` on the archive action and the installation action

Follow the `commerce-app-storage` skill for DB auth, installation steps, and ext.config wiring.
Do not use custom IMS credential normalization or `Core.AuthClient.generateAccessToken`.

Affinez le plan directeur si nécessaire, puis cliquez sur Approuver le plan pour continuer.

Développement, déploiement, association et installation

Suivez le même processus que celui utilisé dans les cas d’utilisation précédents pour passer des exigences à une application installée. Il n’est pas nécessaire de reconfigurer les intégrations.

Tests fonctionnels

Dépannage

Si l’application générée par les analyses entre appareils ne se comporte pas comme prévu ou génère des erreurs, demandez à l’agent de procéder à la résolution des problèmes à partir de l’étape de développement.

Plus le rapport est concret, plus l’agent peut diagnostiquer le problème.

Étapes facultatives

Télécharger le code

Pour continuer à affiner ou à modifier votre IDE préféré, téléchargez le code généré par les analyses entre appareils en cliquant sur l’icône de téléchargement dans la barre d’outils de l’explorateur d’étape de développement. Sélectionnez un dossier de destination et cliquez sur Enregistrer, puis décompressez le package de l’espace de travail.

Pour utiliser les mêmes compétences d’agent que celles utilisées par les analyses entre appareils, installez-les dans le dossier du projet :

npx skills add adobe/aio-commerce-sdk --skill commerce-app-init -y && \
npx skills add adobe/aio-commerce-sdk --skill commerce-app-eventing -y && \
npx skills add adobe/aio-commerce-sdk --skill commerce-app-webhooks -y && \
npx skills add adobe/aio-commerce-sdk --skill commerce-app-business-config -y && \
npx skills add adobe/aio-commerce-sdk --skill commerce-app-storage -y && \
npx skills add adobe/skills --skill appbuilder-project-init -y

Démarrez ensuite l’IDE ou l’interface de ligne de commande et commencez à demander.

Joindre le contexte via un fichier ou un lien

Au lieu de demander directement dans les étapes de plan directeur ou de développement, vous pouvez joindre un contexte à l’aide d’un fichier texte ou d’un lien :

Problèmes connus et solutions

L’étape de plan directeur ne génère pas de tâches

Pour être débloqué et continuer, déplacez l’agent pour générer des tâches.

Les boutons à activer et à extraire de GitHub ne sont pas fonctionnels

Téléchargez plutôt le fichier ZIP du projet à partir de l’étape Développer .

Tutoriels connexes

Guide tutoriel, cas d’utilisation et problèmes connus avec des solutions

Ressources supplémentaires