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 :

```json
[
  {"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`](../modules/loyalty/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`](../modules/loyalty/production-launch-plan.md)
- Synthèse de prêt-au-lancement : [`loyalty-go-live-readiness.md`](loyalty-go-live-readiness.md)
- Tests E2E utilisateur : [`app/modules/loyalty/docs/user-journeys.md`](../modules/loyalty/user-journeys.md)
- Version anglaise : [`merchant-intake-checklist.md`](merchant-intake-checklist.md)