orion/docs/proposals/merchant-intake-checklist-fr.md

Fiche d'intégration commerçant — Premier point de vente

Liste pratique de toutes les données à collecter auprès d'un nouveau commerçant avant de mettre en service son premier point de vente sur la plateforme de fidélité. Chaque champ est rattaché à la colonne de base de données correspondante, de sorte que ce qui est collecté lors de la réunion d'intégration se reporte 1:1 dans l'interface d'administration.

À utiliser comme formulaire à partager, ou comme trame de discussion pour le premier appel d'intégration.

Comment utiliser ce document

1. Envoyer au commerçant les sections « Ce que vous devez nous fournir » (1–7) avant la réunion de lancement, pour qu'il prépare les logos, numéros de TVA et informations du personnel.
2. Utiliser les sections décisions métier (3, 5) pour structurer l'appel — ce sont les choix que seul le commerçant peut faire.
3. Après l'appel, remplir l'interface d'administration dans l'ordre ci-dessous ; le modèle impose cette chaîne de dépendances (commerçant → point de vente → programme de fidélité → personnel).

TL;DR — ce sans quoi vous ne pouvez absolument pas lancer

• Raison sociale + numéro de TVA + adresse de l'entreprise
• E-mail du propriétaire (identifiant et destinataire de l'invitation)
• Nom du point de vente + code de point de vente (slug URL)
• Type de programme de fidélité (tampons / points / hybride) et structure de récompense
• URL de la politique de confidentialité (RGPD)
• Logo de la marque (PNG carré, fond transparent)
• Couleur principale de la marque (hex)
• Au moins un code PIN du personnel

Tout le reste peut être complété de manière itérative après le lancement.

---

1. Identité de l'entreprise (entité commerçant)

Un par commerçant — alimente la table merchants.

Champ	Requis ?	Colonne BDD	Notes
Raison sociale	✅	name	Apparaît sur les factures et pieds d'e-mails
Nom commercial (si différent)	optionnel	(utiliser name)	Le nom que voient les clients
Description de l'activité	recommandé	description	Slogan d'une ligne
Numéro de TVA	✅ UE	tax_number	Format LU : LU12345678
Numéro d'immatriculation	✅	tax_number (ou champ séparé si disponible)	LU : RCS Lxxxxxx
Adresse de l'entreprise	✅	business_address	Rue + ville + code postal + pays
E-mail de contact principal	✅	contact_email	Pour factures et alertes plateforme
Téléphone principal	recommandé	contact_phone	Pour rappels du support
URL du site web	optionnel	website	Lié depuis le pied de page du storefront

2. Compte propriétaire / administrateur

La personne qui se connecte en tant que propriétaire du commerçant.

Champ	Requis ?	Notes
Nom complet	✅	Affiché dans les journaux d'audit
E-mail (identifiant)	✅	L'invitation y est envoyée — doit être livrable
Téléphone	recommandé
Langue d'interface préférée (en / fr / de / lb)	✅	Pilote la langue du tableau de bord d'admin

3. Chaque point de vente

À répéter par emplacement. Alimente la table stores. La plateforme supporte le multi-emplacement dès le premier jour — même les commerçants mono-magasin vivent dans cette structure.

Champ	Requis ?	Colonne BDD	Notes
Nom du point de vente	✅	name	Ex. : « Fashion Hub City Concorde »
Code interne du point de vente	✅	store_code	Slug en MAJUSCULES, sans espaces — utilisé dans les URLs (/store/FASHIONHUB). À choisir une fois, difficile à modifier
Sous-domaine	optionnel	subdomain	Ex. : fashionhub.rewardflow.lu pour le storefront
Adresse physique	✅	business_address	Par emplacement, remplace l'adresse du commerçant si différente
E-mail de contact local	optionnel	contact_email	Remplace l'e-mail commerçant si le point de vente a le sien
Téléphone local	optionnel	contact_phone
Taux de TVA par défaut %	optionnel	letzshop_default_tax_rate	Par défaut 17 % (TVA standard LU)
Langue d'interface par défaut	✅	default_language / dashboard_language	Langue d'ouverture du terminal du personnel
Langues client	✅	storefront_languages	Sous-ensemble de {en, fr, de, lb} pour LU
Horaires d'ouverture	optionnel	pas encore dans le schéma	Contexte utile pour le support

4. Personnel (par point de vente, pour chaque caissier)

Alimente users + store_users (flux d'invitation).

Champ	Requis ?	Notes
Nom complet	✅	Affiché sur l'écran PIN de la tablette
E-mail	✅ si accès web nécessaire	Les opérateurs uniquement-PIN-tablette n'ont pas besoin de compte
Code PIN à 4 chiffres	✅	Ils le choisissent ; vous le configurez dans /admin/loyalty/pins ; saisi à chaque transaction sur la tablette
Identifiant / numéro d'employé	optionnel	Affiché à côté du nom dans la piste d'audit
Rôle	✅	Un parmi : merchant_owner, store_admin, store_staff

5. Programme de fidélité — les décisions métier

Un programme par commerçant. Alimente la table loyalty_programs. C'est ici que se déroule l'essentiel de la discussion de lancement — aidez-les à choisir.

5.1 Type de programme

Type	Quand le recommander
Tampons	Modèle « achetez-en 10, le suivant est offert ». Cafés, coiffeurs, restaurants, partout où il existe une unité de vente claire
Points	« Gagnez X points par €, échangez-les contre des récompenses ». Commerce avec paniers variés
Hybride	Les deux à la fois. Rare en v1 — à différer

5.2 Si tampons

Champ	Valeur typique	Notes
stamps_target	10	Tampons pour remplir une carte
stamps_reward_description	« Café offert »	Nom de la récompense côté client
stamps_reward_value_cents	500 (= 5 €)	Valeur interne pour l'analytique

5.3 Si points

Champ	Valeur typique	Notes
points_per_euro	1, 5 ou 10	Taux d'acquisition
welcome_bonus_points	50–100	Attribués à l'inscription, donnent une bonne première impression
minimum_purchase_cents	500 (= 5 €)	Montant minimum de vente pour gagner — élimine les achats de chewing-gums
minimum_redemption_points	100	Points minimum pour échanger quoi que ce soit
points_expiration_days	365	Au-delà, les points non utilisés expirent
points_rewards (liste JSON)	voir ci-dessous	Le menu des récompenses

Chaque entrée de points_rewards doit contenir : name, points_required, description, value. Exemple :

[
  {"name": "Bon de 5 €", "points_required": 100, "description": "À utiliser en caisse", "value": 500},
  {"name": "Bon de 15 €", "points_required": 250, "description": "À utiliser en caisse", "value": 1500},
  {"name": "Produit XYZ offert", "points_required": 400, "description": "Retrait en magasin", "value": null}
]

5.4 Garde-fous anti-fraude

Champ	Défaut	Quand modifier
cooldown_minutes	0	Mettre 30–60 pour les cafés à fort volume, pour limiter les abus du personnel
max_daily_stamps	10	Réduire si volume faible ; plafonne les tampons quotidiens d'une carte
require_staff_pin	true	Recommandé true dès qu'il y a >1 employé ; la tablette gère hors ligne

5.5 Comportement multi-emplacement

Ces paramètres sont sur les réglages commerçant (merchant_loyalty_settings), pas sur le programme :

Paramètre	Défaut	Notes
allow_cross_location_redemption	✅ activé	Gagner en A et échanger en B ? Oui pour les chaînes, non pour des indépendants partageant l'infrastructure
allow_void_transactions	✅ activé	Certains commerçants désactivent pour contrôler la fraude
require_order_reference	désactivé	Utile si intégration avec leur caisse — relie chaque transaction de fidélité à un numéro de ticket

6. Éléments de marque

À collecter sous forme de fichiers, pas de liens — nous les hébergeons.

Élément	Format	Taille	Champ BDD
Logo principal	PNG, fond transparent	600×600 min, carré	logo_url
Bannière hero	JPG / PNG	1200×400	hero_image_url
Couleur principale	Hex	ex. #7C3AED	card_color
Couleur secondaire	Hex	ex. #10B981	card_secondary_color
Nom affiché de la carte	Chaîne courte	ex. « Fashion Hub Rewards »	card_name

Le logo sert aussi de logo Google Wallet, donc 600×600 minimum avec fond transparent est le plancher pratique — Google exige une bonne lisibilité.

7. Conformité & RGPD

Requis pour le go-live, en particulier au Luxembourg.

Champ	Requis ?	Champ BDD	Notes
URL de la politique de confidentialité	✅ UE	privacy_url	Lié depuis le formulaire d'inscription. Leur site ou votre CMS
CGU de fidélité	✅	terms_text ou terms_cms_page_slug	Texte en ligne ou slug de page CMS. À couvrir : fonctionnement des points, expiration, conditions de révocation, contact en cas de litige
Contact DPO (si applicable)	dépend de la taille	pas dans le schéma	Règle LU : >5 000 enregistrements clients → DPO désigné requis
Consentement marketing	implicite	(case à cocher sur le formulaire d'inscription)	Obligatoire si envoi d'e-mails anniversaire / réengagement

8. Tablettes (si vous fournissez le matériel POS)

Question	Pourquoi
Combien de tablettes par point de vente ?	Détermine le nombre d'appairages à configurer
Tablettes Android existantes ? Modèle + OS ?	Nécessite Android 8.0+ (API 26), Play Services. Fire OS ne fonctionnera pas
Sourcer les tablettes pour eux ?	Lenovo Tab M11 ou Samsung Galaxy Tab A9 (100–200 € l'unité) — modèles éprouvés
Montage ? Support comptoir ou mural ?	Influe sur le plan d'alimentation/recharge
Wi-Fi à chaque emplacement	La file d'attente hors ligne gère les coupures brèves, pas une journée entière. Confirmer le Wi-Fi au comptoir

9. Migration de données initiales (optionnel mais utile)

Question	Pourquoi
Liste clients fidélité existante ?	S'ils passent d'un autre système ou de cartes papier, import en masse via CSV (e-mail, nom, solde, date d'inscription)
Nombre approximatif de clients initiaux ?	Dimensionne la discussion de capacité
Volume mensuel actuel de transactions	Idem

10. Réutilisation de matériel marketing (pour le futur module marketing)

Beaucoup de nos premiers commerçants sont franchisés (chaînes de mode, restauration, beauté) et reçoivent en continu du matériel de campagne du franchiseur — bannières, modèles d'e-mails, publications sociales, promotions saisonnières. Le futur module marketing vise à republier ce matériel au niveau du point de vente local : un franchisé ne devrait pas avoir à concevoir lui-même un e-mail anniversaire alors que le siège en produit cinq par an.

À l'intégration, posez les questions sous forme d'autorisation pour avoir le feu vert avant de construire la chaîne d'ingestion. On ne leur demande rien aujourd'hui — on inventorie les sources et on obtient une autorisation écrite.

10.1 Matériel marketing existant — inventaire

Question	Pourquoi
Le commerçant est-il franchisé ? De quelle enseigne ?	Détermine les sources institutionnelles potentielles
Reçoit-il une newsletter régulière du franchiseur ? Nous transférer 3–5 récentes	Permet d'évaluer le type de contenu, la fréquence, le mix linguistique et le formatage
Existe-t-il un extranet / portail franchiseur où sont publiées les campagnes ? URL + identifiants en lecture seule	Source idéale : structurée, datée, multilingue
Comptes sociaux sur lesquels le franchiseur publie (Instagram, Facebook, LinkedIn)	Public, scrapable, mais ratio signal/bruit faible
Groupes WhatsApp / Telegram de diffusion auxquels ils appartiennent	Parfois le seul canal — transfert manuel peut être l'unique voie
Packs PDF / images reçus par e-mail ou lien de téléchargement	Fréquent pour les campagnes saisonnières ; demander les derniers
Fréquence : hebdomadaire / mensuelle / par campagne	Dimensionne le volume d'ingestion
Langues de publication du franchiseur	Détermine si on réutilise tel quel ou si on retraduit

10.2 Autorisation de réutilisation — à obtenir par écrit

Avant tout scraping ou republication, le commerçant doit nous autoriser. À recueillir à l'intégration (case à cocher sur le formulaire ou clause dans le contrat commerçant) :

• ✅ « J'autorise {plateforme} à ingérer le matériel marketing que je transfère, partage ou rends accessible, et à le republier en mon nom via les canaux de fidélité/marketing offerts par la plateforme. »
• ✅ « Je confirme avoir le droit (en tant que franchisé) d'utiliser ce matériel en marketing local, et que les chartes de marque ou conditions de licence du franchiseur autorisent la republication via des plateformes tierces. »
• ✅ Nous transférer les chartes de marque / politique de marketing collaboratif du franchiseur si elle existe. Cela détermine ce qui peut être fait en toute sécurité.

10.3 Voies pratiques de capture (du plus simple au plus complexe)

Pour le futur module marketing, par ordre de facilité de mise en œuvre :

1. Transfert vers une boîte dédiée. Donner au commerçant un alias par point de vente, ex. marketing+FASHIONHUB@rewardflow.lu. Il transfère tout e-mail du franchiseur là-bas. On parse et on catégorise.
2. Téléversement glisser-déposer. Une page où le commerçant colle une URL ou téléverse un PDF/image ; on OCR/parse et on met en file pour validation.
3. Récupération authentifiée sur extranet. Ils nous fournissent des identifiants en lecture seule au portail franchiseur ; on sonde régulièrement. Signal le plus élevé, exigence légale la plus haute — nécessite l'aval explicite du franchiseur.
4. Scraping social public. En dernier recours, uniquement pour le matériel publié ouvertement par le franchiseur. Respecter robots.txt et les CGU des plateformes.

10.4 Canaux de republication sur lesquels brancher

Ce qu'on fait de ce matériel une fois capté :

• Rotation de la bannière storefront (déjà dans le CMS)
• E-mails fidélité bienvenue / réengagement / anniversaire (module loyalty v1 — modèles fixes ; module marketing v2 — pilotés par campagne)
• SMS / WhatsApp (module marketing v2, différé)
• Notifications push via la carte Wallet (Google Wallet prend en charge les mises à jour au niveau de la classe — push à chaque téléphone client)

10.5 Signaux d'alerte à remonter au commerçant

Si l'un de ces points apparaît à l'intégration, signaler pour revue juridique avant de toucher au matériel :

• Présence de marques du franchiseur sans licence explicite du franchisé pour cet usage
• Références à des marques tierces (co-promotions) — ces marques n'ont pas consenti à notre plateforme
• Matériel dans une langue que la clientèle du commerçant ne parle pas — on ne traduit pas automatiquement sans autorisation
• Données personnelles de personnes nommées (témoignages, photos) — la chaîne de consentement RGPD ne s'étend peut-être pas à nous

11. Client de test pour vérification

Avant d'ouvrir aux vrais clients, dérouler les 8 tests utilisateur de bout en bout avec deux comptes de test :

• L'e-mail personnel du propriétaire commerçant
• Un membre de l'équipe ou votre propre e-mail

La liste de tests E2E se trouve dans app/modules/loyalty/docs/user-journeys.md.

---

Ordre de saisie suggéré dans l'interface d'administration

Le modèle a des dépendances de clés étrangères strictes, donc à remplir dans cet ordre :

1. Créer le commerçant (/admin/merchants/new) — nécessite § 1.
2. Inviter le propriétaire — nécessite § 2.
3. Créer le(s) point(s) de vente (/admin/stores/new) — nécessite § 3.
4. Créer le programme de fidélité (/admin/loyalty/programs/new) — nécessite §§ 5, 6, 7.
5. Créer les codes PIN du personnel (/admin/loyalty/pins/new par point de vente) — nécessite § 4.
6. Configurer les paramètres multi-emplacement (/admin/loyalty/settings/{merchant}) — nécessite § 5.5.
7. (Optionnel) importer les clients en masse via CSV — nécessite § 9.
8. Appairer la/les tablette(s) à chaque point de vente (/admin/loyalty/terminals/new, QR ou manuel) — nécessite § 8.

---

Référence

• Modèles de base de données : models/database/{merchants,stores,loyalty}.py
• Plan de lancement production fidélité : app/modules/loyalty/docs/production-launch-plan.md
• Synthèse de prêt-au-lancement : loyalty-go-live-readiness.md
• Tests E2E utilisateur : app/modules/loyalty/docs/user-journeys.md
• Version anglaise : merchant-intake-checklist.md