commercecraft-agent-skill

Moteur de Site E-Commerce Front-End Automatique de Haut Niveau (Auto E-Commerce Frontend Engine)

Concept clé : Esthétique visuelle extrême, architecture d'ingénierie solide, expérience 100% front-end en boucle fermée, zéro dépendance externe.

Cette compétence intègre les meilleures pratiques du commerce électronique DTC (Direct-to-Consumer) et de l'ingénierie front-end moderne, en se concentrant sur la fourniture d'une expérience e-commerce front-end moderne de qualité commerciale, sans placeholders, avec une vraie machine à états pour le shopping et le paiement.

Règles de langue d'exécution :

• Nom de marque, titres de produits, paramètres de spécifications, textes d'interface utilisateur → Anglais uniquement, donnant une qualité de marque internationale.
• Journal de développement, rapports d'avancement, explications techniques et interactions utilisateur → Chinois traditionnel (Taiwanais).
• Variables, fonctions, définitions d'interface dans le code → camelCase / PascalCase en anglais, interdiction absolue de noms en pinyin chinois.

---

🤖 Cinq Rôles Virtuels et Matrice de Compétences (Architecture d'Équipe d'Agents)

Lors de l'exécution du processus de construction du site, l'agent IA passe à 5 rôles professionnels, progressant séquentiellement et se vérifiant mutuellement :

Rôle	Responsabilités Principales	Compétences Clés (Tags)
1. Orchestrateur de Projet	Positionnement de la marque, sélection de la catégorie, planification de l'exécution et coordination inter-étapes	prd, brainstorming, executing-plans, writing-plans
2. Directeur Créatif Principal	Définition de l'ambiance de la marque, contrastes de couleurs, système typographique, mise en page de haute qualité	ui-ux-pro-max, brand-guidelines, canvas-design, frontend-design
3. Architecte Full-Stack Principal	Interfaces TypeScript strictes, machine à états Zustand, composants RWD et implémentation du routage	web-artifacts-builder, frontend-design, react-best-practices, tailwindcss
4. Stratège de Contenu	Descriptions de produits professionnelles, textes narratifs, mots-clés SEO, conception d'avis clients	content-research-writer, internal-comms, brand-guidelines, doc-coauthoring
5. QA & Conformité	Audit zéro placeholder, débogage console, validation de build, vérification des 7 critères de qualité	verification-before-completion, webapp-testing, systematic-debugging, audit

---

🚀 Processus d'Exécution du Cycle de Vie Complet (Phases du Cycle de Vie)

Utilisateur lance : "Génère-moi un site e-commerce de type [catégorie/style]"

┌─ Phase 0 : Chargement des Règles de Tolérance Zéro et des Principes Psychologiques (P0)
│  ├─ 📖 Lire references/anti-patterns.md (18 règles de tolérance zéro)
│  └─ 📖 Lire references/ux-psychology-ecommerce.md (Principes de psychologie CRO)
│
├─ Phase 1 : Génération de la Graine Créative et du Système de Design (Creative & System Generation)
│  ├─ 🎲 Déterminer le thème de la marque (ex : Minimal Desk Aesthetics, Luxe Aromatherapy, Tech Gear)
│  ├─ 🎨 Exécution Directeur Créatif : Décider de la palette de couleurs (Règle 60-30-10) et de la typographie (Display / Body)
│  ├─ ✍️ Exécution Stratège de Contenu : Générer le slogan principal de la marque et 8 à 12 données de spécifications de produits très réalistes
│  └─ 📝 Écrire le résumé du PRD du projet et les décisions de conception dans docs/DESIGN_DECISIONS.md
│
├─ Phase 2 : Construction de l'Ingénierie Front-End Pure (Vite + React + TS + Tailwind)
│  ├─ 🏗️ Initialiser le squelette du projet (Vite React-TS)
│  ├─ 📦 Installer les dépendances principales : zustand, react-router-dom, lucide-react, clsx, tailwind-merge, framer-motion, canvas-confetti
│  ├─ 📐 Importer templates/ecommerce-types.ts pour garantir des contraintes de typage strictes
│  └─ 🛒 Implémenter la couche d'état (src/store/useCartStore.ts) avec persistance LocalStorage
│
├─ Phase 3 : Implémentation du Routage Complet du Site E-Commerce (11 Pages, 100% Complètes)
│  ├─ 🏠 Couche A (Boucle d'Achat Principale) : Accueil, Boutique, DétailProduit, PanierTiroir, Paiement, CommandeRéussie
│  ├─ 👤 Couche B (Centre de Confiance Utilisateur) : Profil, HistoriqueCommandes
│  └─ 📜 Couche C (Pages de Conformité et de Confiance) : FAQ, PolitiqueLivraison, RetoursRemboursements, ÀPropos
│
├─ Phase 4 : Renforcement de la Psychologie CRO et Élévation Visuelle
│  ├─ ⏳ Injecter des étiquettes de rareté (Scarcité : "Only 3 units left!")
│  ├─ 🚚 Implémenter une barre de progression du seuil de livraison gratuite ("Ajoutez X€ de plus pour bénéficier de la Livraison Gratuite")
│  ├─ ⭐ Intégrer de vraies évaluations par étoiles et des dynamiques d'achat (Preuve Sociale)
│  ├─ 🏷️ Injecter des données structurées Schema.org (Product, Offer) en JSON-LD
│  └─ 🖼️ Configurer des images commerciales haute définition provenant d'Unsplash (interdiction des placeholders flous)
│
└─ Phase 5 : Validation Qualité et Livraison en un Clic (Quality & Delivery Gate)
   ├─ 🔨 Exécuter npm run build (garantir 0 erreur TypeScript, 0 avertissement de build)
   ├─ 🔍 Exécuter les 7 vérifications de seuil de qualité (Zero Mock, Zero Broken Links)
   └─ 🚀 Fournir l'aperçu front-end et les instructions de déploiement en un clic sur Vercel

---

📋 Spécifications du Routage Complet des 11 Pages (Exigences de Page)

Chaque site généré doit avoir les 11 routes de page complètes suivantes, aucune page vide ou 404 n'est autorisée :

1. Page d'Accueil (/) :

   • Bannière visuelle Hero (grande image à fort impact, CTA fort "Shop The Collection").
   • Badges de confiance d'autorité (Livraison Gratuite, Garantie 30 Jours, Cryptage 256-Bit SSL, Artisanat Éthique).
   • Cascade de produits vedettes recommandés (Grille de Produits en Vedette).
   • Accès rapide par catégorie (Acheter par Catégories).
   • Section Histoire de la Marque (Ethos de la Marque).
   • Témoignages clients authentiques (Preuve Sociale).
   • Section d'abonnement à la newsletter (avec incitation à la réduction).

2. Catalogue de Produits (/shop) :

   • Filtre multidimensionnel : Filtre par catégorie, Curseur de fourchette de prix, Filtre par tag.
   • Fonction de tri en temps réel : Popularité, Prix croissant, Prix décroissant, Nouveautés.
   • Champ de recherche par mot-clé instantané (Recherche Client Instantanée).
   • État de défense en cas de recherche vide (État vide avec bouton de réinitialisation des filtres).

3. Page de Détail du Produit (/product/:id) :

   • Galerie d'images avec prévisualisation sous plusieurs angles (Galerie d'Images).
   • Sélecteur de spécifications : Taille, Couleur, Variante.
   • Indication d'urgence de stock (par exemple, alerte ambrée quand le stock est < 5).
   • Régulateur d'augmentation/diminution de quantité.
   • Double bouton : "Ajouter au Panier" (glissement du tiroir panier) et "Acheter Maintenant" (accès direct au paiement).
   • Onglets : Spécifications détaillées, Informations de livraison et de retour, Avis clients authentiques.
   • Recommandations de produits associés (Produits Recommandés).
   • Injection de Schema.org JSON-LD.

4. Tiroir du Panier Latéral (CartDrawer) :

   • Glisse en douceur (Framer Motion / Transition) lorsque l'icône du panier dans l'en-tête est cliquée ou qu'un produit est ajouté.
   • Barre de progression en temps réel du seuil de montant pour la livraison gratuite (par exemple, livraison gratuite pour 100€ d'achat).
   • Liste des articles : vignette, nom, spécifications sélectionnées, modification de la quantité, suppression instantanée.
   • Champ de code promo (code réduction) intégré (ex : WELCOME10 pour une réduction immédiate de 10%).
   • Récapitulatif des prix : Sous-total, Réduction, Frais de livraison estimés, Montant total.
   • Bouton d'accès direct au paiement (Procéder au Paiement).

5. Centre de Paiement (/checkout) :

   • Interface de paiement en 3 étapes :
     1. Informations de contact et de livraison : Nom, Email, Adresse, Téléphone.
     2. Choix du mode de livraison : Standard (0~5€), Express (15€).
     3. Simulation du mode de paiement : Saisie de carte de crédit simulée (avec mise en forme automatique, icône de sécurité), options de paiement rapide Apple Pay / PayPal.
   • Carte récapitulative de commande en temps réel à droite/en bas (Carte Colante du Résumé de Commande).
   • Prévention des doubles clics, validation en temps réel des champs du formulaire.

6. Page de Commande Réussie (/order-success) :

   • Animation de coche de succès verte et effet de confettis festifs (canvas-confetti).
   • Numéro de commande unique généré aléatoirement (ex : #ORD-2026-89412).
   • Liste complète du résumé de commande, informations du destinataire et date de livraison estimée.
   • Bouton de retour "Continuer les Achats".

7. Suivi et Historique des Commandes (/orders) :

   • Saisie du numéro de commande ou de l'email pour simuler une barre de progression de commande (Confirmée → En Préparation → Expédiée → Livrée).

8. Profil et Favoris (/profile) :

   • Consultation rapide des informations de base de l'utilisateur simulé, de sa liste de souhaits (Wishlist).

9. Foire Aux Questions (/faq) :

   • Composant accordéon (Accordion) avec les questions fréquentes sur la commande, la livraison, les retours, l'entretien des matériaux, etc.

10. Politique de Livraison (/shipping) :

    • Tableau des frais de livraison nationaux et internationaux, délais de livraison par pays, explication des droits de douane.

11. Politique de Retour et Histoire de la Marque (/returns & /about) :

    • Énoncé clair des conditions de garantie de retour sous 30 jours, processus de retour en 3 étapes et histoire de la création de la marque.

---

🧠 Guide d'Implémentation Obligatoire de la Psychologie du E-Commerce et du Taux de Conversion (CRO)

Chaque site généré doit intégrer les mécanismes psychologiques suivants (voir la définition détaillée dans references/ux-psychology-ecommerce.md) :

1. Loi de Hick :
   • Le formulaire de paiement est par défaut simplifié, réduisant les champs non obligatoires inutiles.
   • Le menu principal de navigation ne dépasse pas 5 éléments de premier niveau.
2. Effet d'Ancrage :
   • Les produits en promotion affichent le prix d'origine barré (ex : ~~120,00€~~ 89,00€) et une étiquette d'économies "Économisez 31€".
3. Rareté et Urgence :
   • Sur la page de détail, afficher dynamiquement "Il ne reste que 2 articles à ce prix".
   • Sur la page de paiement, indiquer "Réservé dans votre panier pendant 10:00 minutes" (minuteur optionnel).
4. Preuve Sociale :
   • Sur la page d'accueil et les pages de détail, marquer les acheteurs authentifiés avec un badge "Acheteur Vérifié".
   • Note moyenne des produits sur les cartes du catalogue (ex : "★ 4.9 (128 avis)").
5. Aversion à la Perte :
   • Alerte dynamique de la barre de progression de livraison gratuite dans le panier : "Plus que 12€ pour bénéficier de la livraison gratuite sur tout le site !".

---

🛠️ Spécifications de l'Architecture de Gestion d'État (Zustand + LocalStorage)

Utiliser un store Zustand découplé et anti-rebond pour garantir la persistance du panier après un rafraîchissement de la page :

// src/store/useCartStore.ts Modèle de spécification
import { create } from 'zustand';
import { persist } from 'zustand/middleware';
import { CartItem, Product } from '../types';

interface CartState {
  items: CartItem[];
  isOpen: boolean;
  promoCode: string | null;
  discountRate: number;
  openCart: () => void;
  closeCart: () => void;
  addItem: (product: Product, quantity?: number, selectedVariant?: string) => void;
  removeItem: (itemId: string) => void;
  updateQuantity: (itemId: string, quantity: number) => void;
  applyPromoCode: (code: string) => { success: boolean; message: string };
  clearCart: () => void;
  getSubtotal: () => number;
  getTotal: () => number;
}

---

🛡️ Barrière de Qualité de Livraison (7 Seuils de Validation)

Avant de soumettre le résultat à l'utilisateur, le rôle QA doit vérifier et valider chaque élément :

1. Zéro Image Cassée : Toutes les URL d'images doivent se charger correctement et être adaptées à la taille, avec les attributs loading="lazy" et alt.
2. Zéro Lien Mort : Tous les liens de navigation, les liens de bas de page et les boutons doivent être cliquables et rediriger vers les 11 routes de page correspondantes.
3. Zéro Placeholder : Interdiction absolue d'utiliser Lorem Ipsum, Produit 1, 0,00€ et autres textes de remplissage. Tous les textes doivent correspondre au positionnement de la marque.
4. Boucle Complète du Panier : Ajouter au panier → Tiroir coulissant → Modification de la quantité avec mise à jour du prix → Application d'un code promo de réduction → Validation du paiement → Redirection vers la page Commande Réussie avec obtention d'un numéro de commande.
5. Garantie RWD : Pas de débordement horizontal sur mobile (375px), tablette (768px) et desktop (1280px+).
6. Structure SEO : La page de détail du produit doit afficher correctement le application/ld+json (Schema.org Product).
7. Validation du Build de Production : Exécuter npm run build sans aucune erreur, produire le répertoire dist/.