DOC
Accueil/ Projets/ KOBIKE Tracking Notifier/ Rapport projet : kobike-tracking-notifier - Partie 2

Rapport projet : kobike-tracking-notifier - Partie 2

Ce rapport complète le rapport_0001.md en répondant aux questions concernant l'intégration en temps réel de WeCom / Tencent Docs, la récupération des adresses email manquantes via Shopify et Shifter, la pile technologique de l'application de gestion client, et le processus de collecte des emails en boutique.

1. WeCom & Tencent Docs : Écoute en direct et Trigger n8n

Dans la configuration actuelle, WeCom (l'outil collaboratif de Tencent) héberge le document Tencent Docs (腾讯文档). Si vous disposez d'un compte développeur WeCom et d'un accès au fichier, voici comment mettre en place une écoute en direct (ou quasi-temps réel) pour déclencher n8n dès qu'une ligne est modifiée.

Fonctionnement de l'API WeCom pour Tencent Docs

WeCom expose des API spécifiques pour la gestion des micro-documents (WeDoc). Cependant, WeCom ne fournit pas de webhook natif pour notifier en temps réel de la modification d'une cellule spécifique dans un document.

Deux options s'offrent à nous pour écouter les modifications :

Solution A : Passer par un connecteur de scénario (Tencent Cloud HiFlow)

HiFlow est la plateforme d'automatisation de Tencent (similaire à Zapier ou Make). Elle possède un déclencheur natif pour Tencent Docs : "Lorsqu'une ligne est ajoutée ou modifiée dans une feuille".

  1. Provenance : Service SaaS officiel de Tencent Cloud (HiFlow).
  2. Fonctionnement :
    • Vous configurez un déclencheur HiFlow lié à votre fichier Tencent Docs.
    • En action, vous utilisez le module "Webhook" de HiFlow pour envoyer une requête HTTP POST à n8n.
    • n8n reçoit instantanément les données de la ligne modifiée via son nœud "Webhook".
  3. Avantage : Temps réel immédiat, pas de développement complexe pour l'écoute, gratuit dans la limite des quotas de base.

Solution B : La轮询 (Polling) via l'API WeCom Smart Sheet (Recommandé si hébergé localement)

Si le fichier Tencent Docs est configuré sous forme de Smart Sheet (智能表格) :

  1. Provenance : API officielle WeCom (微文档 / 智能表格 API).
  2. Fonctionnement :
    • n8n effectue une requête planifiée (Cron node) toutes les 5 ou 10 minutes.
    • n8n appelle l'API WeCom https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/get_records pour récupérer la liste des lignes.
    • n8n filtre les lignes modifiées récemment en comparant avec sa base de données locale PostgreSQL.
  3. Avantage : Totalement autonome sur votre serveur, aucune dépendance envers un tiers comme HiFlow, sécurité des données accrue.

L'analyse détaillée et le choix de la solution A ou B font l'objet de l'ADR numéro 1.

2. Extraction des emails via Shopify et Shifter

Puisque le fichier Tencent Docs ne contient pas les adresses email des clients, n8n doit enrichir la donnée avant de pouvoir envoyer la notification. Le fichier contient le Platform order number (ex: KO260107-1), qui sert de clé unique.

Provenance et rôles des plateformes

  1. Shopify (Boutique en ligne) :
    • L'API REST Shopify permet de récupérer une commande via son nom (name ou order_number).
    • Requête : GET /admin/api/2023-10/orders.json?name=KO260107-1
    • Si la commande existe, l'API renvoie le profil du client incluant son email.
  2. Shifter (Logiciel de caisse physique et atelier cycliste) :
    • Shifter est utilisé pour les ventes physiques en magasin et l'atelier.
    • Shifter propose une API pour les partenaires permettant de requêter les clients ou les factures par numéro de vente ou identifiant unique.
    • Si la commande provient du magasin physique, n8n interroge l'API de Shifter pour extraire l'adresse email associée au compte client de la facture.

Algorithme de traitement dans n8n

[Nouveau tracking détecté par n8n dans Tencent Docs]
                      |
                      v
          [L'email est-il présent ?]
             /                 \
        (Oui)                  (Non)
          /                       \
   [Envoi direct]       [Rechercher dans Shopify API]
                               |
                        [Trouvé dans Shopify ?]
                         /                 \
                    (Oui)                  (Non)
                      /                       \
         [Enregistrer email]          [Rechercher dans Shifter API]
                |                              |
         [Envoi email]                 [Trouvé dans Shifter ?]
                                        /                 \
                                   (Oui)                  (Non)
                                     /                       \
                        [Enregistrer email]          [Statut: Email manquant]
                               |                             |
                        [Envoi email]             [Alerte équipe magasin]

L'enrichissement des données fait l'objet de l'ADR numéro 2.

3. Architecture de l'application de gestion client

Pour stocker les emails des clients locaux, éviter de les redemander à chaque fois et permettre leur modification, il est nécessaire de créer une application web légère et robuste.

Stack technologique recommandée

La stack proposée respecte le besoin de légèreté, de robustesse, et s'intègre parfaitement avec PostgreSQL et NocoDB déjà présents sur le VPS (via Coolify).

  1. Base de données : PostgreSQL (Existante)

    • Provenance : Base de données déjà hébergée sur votre VPS Coolify.
    • Rôle : Source unique de vérité pour les clients et les statuts de notification.

  2. Backend : Python avec FastAPI

    • Provenance : Framework Python asynchrone moderne, ultra-rapide (basé sur Starlette et Pydantic).
    • Rôle :
      • Fournir une API REST sécurisée pour le frontend React.
      • Valider les données via Pydantic (vérification du format des adresses email, des numéros de téléphone).
      • Communiquer avec PostgreSQL via SQLModel ou SQLAlchemy.
      • Générer automatiquement la documentation de l'API (Swagger UI) pour faciliter les futurs développements.
    • Pourquoi Python ? Python est idéal pour manipuler les données logistiques et interagir avec les API de Shopify et Shifter si n8n doit déléguer certaines tâches complexes.

  3. Frontend : React avec Vite

    • Provenance : React (bibliothèque d'interface de Meta), Vite (outil de build ultra-rapide créé par Evan You).
    • Rôle :
      • Interface utilisateur moderne, monopage (SPA), réactive.
      • Formulaires de recherche de clients, édition des fiches, historique des notifications envoyées.
      • Design épuré en Vanilla CSS (sans Tailwind sauf demande expresse, pour garder le contrôle total du style sans dépendances superflues).

Communication entre les composants

[Navigateur Client (React App)]
             ^
             | HTTP / JSON (Axios ou Fetch)
             v
[API Backend (FastAPI - Python)]
             ^
             | SQL (SQLAlchemy / SQLModel)
             v
[Base PostgreSQL / NocoDB (VPS Coolify)]

Cette architecture est détaillée dans l'ADR numéro 3.

4. Collecte des emails des clients en boutique (Clients physiques)

Le flux logistique repose sur l'adresse email pour l'envoi automatique du suivi. Les clients achetant en magasin (via le logiciel Shifter) n'ont pas toujours d'email enregistré.

Processus d'amélioration de la collecte

Pour combler cette lacune sans perturber le passage en caisse, nous proposons trois leviers :

  1. Optimisation dans Shifter (Point de Vente) :

    • Configurer les fiches clients dans Shifter pour rendre l'adresse email obligatoire lors de la création d'une nouvelle commande ou d'une fiche atelier.
    • Sensibilisation du personnel : expliquer au client que l'email est indispensable pour recevoir la facture d'achat et le lien de suivi de la préparation/livraison du vélo.

  2. Portail d'auto-enregistrement client (React Application) :

    • Mettre en place une page publique simple sur l'application React : https://client.kobike.fr/suivi-email.
    • Sur cette page, le client peut entrer son numéro de commande de caisse (Shifter) et son adresse email.
    • Un QR Code pointant vers cette page est affiché au comptoir de la boutique avec la mention : "Scannez pour recevoir le suivi de votre commande par email".

  3. Enrichissement a posteriori :

    • Si n8n traite une ligne de Tencent Docs pour une vente physique et constate que l'email est manquant dans PostgreSQL/Shifter, n8n crée une tâche ou envoie une alerte automatique (par WeCom ou email interne) à l'équipe du magasin pour les inviter à recontacter le client ou à mettre à jour la fiche.