spécifications App — **SelectO**



---

# 1. Vision synthétique

**SelectO** — PWA « instagrammable » qui permet aux clients d’un établissement (café, boutique, resto) de scanner un QR unique et de commander / payer en ligne ou via WhatsApp, tout en gardant une option “concierge” humaine. Objectifs clés : conversion rapide (no-install), expérience visuelle premium, flexibilité de fulfilment (dine-in / pickup / livraison), et administration temps réel pour les commerçants.

---

# 2. Parcours utilisateur (user journey) — étapes et critères d’acceptation

1. **Scan QR → ouverture PWA**

   * QR encode : `venue_id`, `table_id` (optionnel), `session_token` (éphémère).
   * PWA s’ouvre, charge menu optimisé (progressive rendering).
   * Critère : <200ms Time-to-interactive sur 3G simulée pour la page d’accueil (optimisable via CDN et lazy-loading).

2. **Page menu — navigation visuelle**

   * Grille d’images haute résolution, Stories/Highights, filtres allergènes, toggle langue (EN/FR/AR).
   * Critère : possibilité d’ajouter un item au panier en ≤2 clics depuis la fiche produit.

3. **Personnalisation & panier**

   * Modifiers (lait, taille, extras), règles de disponibilité (horaire), prix TTC calculé en temps réel (incl. taxes locales).
   * Critère : validation du calcul prix sur 100 commandes test (consistance).

4. **Choix de fulfilment**

   * Dine-in (table service avec `table_id`), Pick-up (numéro de commande), Livraison (adresse + zone).
   * Critère : validation de zone de livraison et estimation actuelle de délai.

5. **Paiement / WhatsApp**

   * Option A : Paiement instantané (Stripe / Apple Pay / PayPal) → confirmation immédiate + ticket KDS.
   * Option B : Envoyer vers WhatsApp Business (message structuré) → conversation bot/humain → confirmation manuelle.
   * Critère : webhook de paiement confirmant la réservation et poussant l’ordre au KDS.

6. **KDS / Back-of-house**

   * Entrée auto dans KDS (avec priorité: paiement confirmé > WhatsApp confirmé).
   * Critère : KDS affiche l’ordre en temps réel (<1s).

7. **Notifications**

   * Client : push/in-app (PWA) + WhatsApp (selon canal). Commerçant : dashboard & sonorisation KDS.
   * Critère : envoi d’un récapitulatif de commande (PDF/HTML) et d’un numéro de commande.

---

# 3. Architecture technique détaillée (propositions & rationale)

## Stack recommandé (production-ready)

* **Frontend (PWA)**: Next.js (TypeScript) + React, Tailwind CSS, image optimization (next/image)
  *Raison*: SSR/ISR pour SEO & fast first paint, facile PWA integration.
* **UI design**: Figma (component library), animations Framer Motion, responsive & RTL support (Arabe).
* **Backend**: Node.js + NestJS (TypeScript) ou Express + Prisma/TypeORM
  *Raison*: architecture modulaire, DI, très testable.
* **Data**:

  * **Primary transactional DB**: PostgreSQL (orders, payments, users, venues) — ACID for orders.
  * **NoSQL**: MongoDB or ElasticSearch for flexible menu docs, search & faceted filters, and fast ingestion of media metadata.
  * **Cache / Queue**: Redis (session cache, rate limiting, pub/sub) + RabbitMQ or AWS SQS (background jobs).
* **Assets**: S3 / Cloudinary for images (automatic resizing / CDN).
* **Realtime/KDS**: WebSocket (Socket.io) or server-sent events (SSE) for order streaming to KDS.
* **Payments**: Stripe (Apple Pay via Stripe), PayPal integration; webhooks for payment confirmation.
* **Communication (WhatsApp)**: WhatsApp Business API via Meta or Twilio Conversations (support templates + interactive messages).
* **Hosting / CDN**: Vercel (frontend) + AWS (ECS / Lambda / RDS / S3) or equivalent.
* **Observability**: Prometheus + Grafana, Sentry for errors, ELK stack for logs.

---

# 4. Sécurité & conformité

* **OWASP Top10** protections (CSRF, XSS, input validation, rate limiting).
* **PCI**: utiliser Stripe elements / hosted checkout to éviter scopes PCI élevés.
* **GDPR**: user consent on data, droit d’effacement, stockage dans région appropriée (EU/MAROC si exigé).
* **Auth**: OAuth2 for staff/admin; session short-lived for PWA (token tied to QR session).
* **Backups**: point-in-time recovery pour PostgreSQL + snapshot S3.

---

# 5. QR codes & sessions — mécanisme proposé

* **QR dynamique**: each QR contains `venue_id` + `table_id` + ephemeral signed token (HMAC) valid 15-60 min.
* **Flow**: scan → request `/session/init` with token → server validates signature & issues short-lived JWT session for the browser.
* **Benefits**: prevents forged QR & ties orders to a table/place.

---

# 6. Data model (essentiel) — aperçu simplifié

**Tables (Postgres)**

* `venues` (id, name, address, tz, currency, tax_rules)
* `menus` (id, venue_id, version, published_at)
* `products` (id, menu_id, sku, name, base_price, available_from, available_to)
* `modifiers` (id, product_id, type, price_delta)
* `orders` (id, venue_id, session_id, status, total_amount, payment_id, fulfilment_type, created_at)
* `order_items` (order_id, product_id, qty, modifiers_json, line_total)
* `users` (opt-in, contact channels)
* `kds_events` (order_id, status, timestamps)

**Collections (Mongo)**

* `media` (images, variants, focal points)
* `menu_catalog` (flexible product schemas, marketing highlights)

---

# 7. API contract (exemples essentiels)

* `POST /api/session/init` { token } → 200 { session_jwt, venue }
* `GET /api/venue/{id}/menu?lang=fr` → 200 { menu }
* `POST /api/cart/preview` { session, items } → 200 { totals, tax_breakdown }
* `POST /api/orders` { session, items, fulfilment, payment_method } → 201 { order_id, payment_url (if external) }
* `POST /webhooks/stripe` → 200 (verify & mark paid)
* `POST /webhooks/whatsapp` → 200 (confirm via message templates)
* `WS /kds/stream?token=` → stream orders to kitchen

---

# 8. WhatsApp integration — UX & payload

* **When user chooses WhatsApp**: send structured JSON to WhatsApp Business API (template or interactive message) including:

  * venue name, order items + modifiers, total TTC, order id, estimated prep time, CTA buttons: *Confirmer & Payer* / *Modifier*.
* **Fallback**: if bot route fails, send message to human queue (support dashboard shows pending chat with customer + order details).
* **Note**: for WhatsApp templates, pre-approval may be necessary (Meta). Préparer templates multilingues.

---

# 9. KDS / Back-of-House details

* **KDS view**: tri par statut, préparation et temps écoulé. Filtre par type (dine-in, pickup, delivery).
* **Printer integration**: cloud print to local thermal printers via small POS agent (desktop / Pi) or direct printing via cloud printers (e.g., Google Cloud Print alternatives).
* **Prioritization**: payé > WhatsApp confirmé > en attente. Option “rush” flagset par staff.

---

# 10. Admin dashboard (fonctionnalités avancées)

* Multi-venue, multi-user roles (owner, manager, kitchen, cashier).
* **Menu manager**: drag-drop, versioning & schedule (ex: brunch menu 9h–12h).
* **Orders**: filtre, réassignation, print, remboursement.
* **Analytics**: ventes par item, taux conversion QR → commande, panier moyen, peak hours heatmap.
* **Marketing**: gestion des Highlights/Stories, promos, segmentations pour envoi WhatsApp/SMS (consentement requis).
* **Audit logs** and access controls.

---

# 11. Monitoring, métriques & SLAs (ce à quoi prêter attention)

* **Client-side**: FCP, TTI, Largest Contentful Paint, Time to Interactive.
* **Backend**: p95 order creation latency, payment webhook processing time.
* **Reliability**: uptime 99.9% pour le service frontend; KDS sous 1s real-time delivery.
* **Business KPIs**: taux de conversion (scan→commande), panier moyen, % commandes via WhatsApp vs paiements directs.

---

# 12. Tests & QA

* Unit tests + integration tests (Jest/Playwright).
* E2E scenarii (simuler scan QR, ajout items, paiement, webhook).
* Load testing (k6) pour peak (600 req/min premier pilot).
* Security scans (Snyk), pen-test avant go-live.

---

# 13. Déploiement & maintenance (phases, livrables)

* **Phase MVP (Pilote)**: PWA minimal (scan → menu → panier → paiement Stripe) + KDS basique + admin menu editor + WhatsApp fallback minimal.
* **Phase Commerce**: multi-langues, modifiers, stock management, print integration.
* **Phase Growth**: loyalty, recommendations AI, AB testing, marketing automations.

> Livrables par phase : spécifications API, wireframes, MVP build, tests, déploiement infra, playbook ops.

---

# 14. Exemples de cas d’usage & critères d’acceptation (QA-ready)

* **CA1**: Client scanne QR d’une table, commande un café avec lait d’amande, paie par Apple Pay → KDS reçoit commande payée et ticket imprimé.
* **CA2**: Client choisit WhatsApp — message envoyé, agent valide et confirme → order status passe à `confirmed` et KDS reçoit l’ordre.
* **CA3**: Item marqué out-of-stock depuis admin → n’apparaît plus dans menu mobile ; panier existant recalculé et client notifié.

---

# 15. Observations / recommandations stratégiques

* **Polyglot DB** (Postgres + Mongo) donne robustesse pour transactions + flexibilité pour menu/marketing.
* **Prioriser l’expérience mobile PWA (fast & offline)** : cache menu + service worker pour reconnections intermittentes.
* **WhatsApp = fort différenciateur** au Maroc/France ; prévoir early work sur templates et approbation Meta.
* **Monétisation & Upsell** : suggestions visuelles “Best pairing”, promos limitées dans le temps (Stories highlights).

---
_____________________________________________________________

PUIS — on étend la spec en intégrant clairement :

1️⃣ **Paiement immédiat pour le “Take-Away / Click & Collect”**
2️⃣ **Paiement différé pour la consommation sur place (payer à la fin)**

Je complète ci-dessous — de façon intégrée, cohérente avec ce qu’on a déjà défini.

---

# AJOUT — Gestion avancée des modes de paiement selon le contexte

## 1. Règles générales (logique produit)

### A. Take-Away / Click & Collect

➡️ **Paiement obligatoire AVANT validation de la commande**

* La commande n’est transmise au KDS **qu’après confirmation de paiement**.
* Options : Stripe, Apple Pay, PayPal, ou WhatsApp → lien de paiement sécurisé.
* Annulation automatique si paiement non effectué dans X minutes.

**Statuts possibles :**

* `cart` → `awaiting_payment` → `paid` → `sent_to_kitchen` → `ready` → `picked_up`

---

### B. Dine-In / Table Service (payer à la fin)

➡️ **Ouverture d’une session-table avec consommation continue**

* Le client peut commander plusieurs fois pendant la même session.
* Aucune obligation de payer immédiatement.
* La facture se cumule automatiquement.
* Le paiement se fait **au moment du départ**, en ligne ou au comptoir.

**Statuts possibles :**

* `session_open` → commandes successives (`in_progress`)
  → `ready/served`
  → **au moment du départ** : `checkout_pending` → `paid` / `pay_at_counter`

Possibilité d’ajouter :

* Paiement partagé (split bill)
* Pourboires (tips)
* Impression / envoi ticket récapitulatif

---

## 2. Impact sur le parcours utilisateur

### Étape “Mode de consommation”

Lors du choix :

👉 **DINE-IN (Sur place)**

* Message clair :

  > « Vous pourrez payer à la fin. Votre addition sera cumulée. »
* Affichage permanent d’un **suivi d’addition** (total actuel).

👉 **TAKE-AWAY**

* Message clair :

  > « Paiement sécurisé requis pour confirmer votre commande. »
* Redirection immédiate vers l’écran de paiement.

---

## 3. UI / UX — éléments visibles

### Sur place

* Badge “Session ouverte – Table XX”
* Timeline :

  * Commandé → En préparation → Servi
* Bouton visible : **“Demander l’addition”**
* Option : payer en ligne ou notifier qu’on paiera au comptoir.

### Take-away

* Ecran paiement → confirmation → suivi préparation
* QR/Code de retrait optionnel

---

## 4. Admin — règles configurables

Depuis le dashboard, le commerçant choisit :

| Paramètre                                 | Options         |
| ----------------------------------------- | --------------- |
| Obliger le paiement pour Take-Away        | Oui / Non       |
| Autoriser paiement à la fin pour Dine-In  | Oui / Non       |
| Paiement mixte (part en ligne + comptoir) | Activable       |
| Temps d’expiration panier non payé        | X minutes       |
| Politique d’annulation                    | personnalisable |

---

## 5. Flux techniques

### Webhooks paiement (Take-Away)

* Créer commande → statut `awaiting_payment`
* Réception webhook Stripe
* Validation → push au KDS

### Sessions Table (Dine-In)

* `session_id` lié au QR (table)
* Chaque commande s’ajoute à la session
* Clôture session → déclenche facture → paiement

---

## 6. KDS — règles de priorisation

* **Paid Take-Away** → priorité haute (time-sensitive)
* **Dine-In** → flux normal, regroupement par table/session
* Indicateur distinct :

  * 🟢 Payé
  * 🟡 À payer à la fin

---

## 7. Cas limites importants

✔️ Client Dine-In commande, puis décide de partir — payer immédiatement
✔️ Client Take-Away abandonne → panier expire
✔️ Session Table oubliée → clôture automatique après X heures
✔️ Problème de réseau → facture récupérée via session QR

---

## 8. Exemple concret

### Sur place

* Table 14 commande 3 fois
* Total cumulé : 185 MAD
* Fin du repas → bouton “Payer maintenant”
* Paiement + ticket

### Take-Away

* Latte + croissant
* Paiement immédiat via Apple Pay
* Ticket + notification « Prêt dans 6–8 minutes »

---

## 9. Résumé décision produit

| Mode                      | Quand on paie | Validation commande        |
| ------------------------- | ------------- | -------------------------- |
| Dine-In (payer plus tard) | À la fin      | Après confirmation serveur |
| Take-Away                 | Avant         | Après paiement validé      |

---







# ZZZ. Prochaines actions pour moi ____________

1. Je produis les **user stories** + backlog priorisé pour l’itération MVP.
2. Je génère un **wireframe** (desktop & mobile) de l’interface “Instagram-style” (menu + produit + panier).
3. Ou bien je crée le **schéma d’API OpenAPI (YAML)** prêt à être importé dans Postman/Swagger.

Lequel préférez-vous en premier ? (je peux démarrer directement sur le wireframe ou les user stories).

### Pour la prochaine étape

Souhaitez-vous que je :

1️⃣ intègre ces règles directement dans le **backlog / user stories**,
2️⃣ mette à jour les **API & statuts exacts**,
3️⃣ ou prépare un **schéma visuel (diagramme de flux)** ?

Et petite clarification rapide (numérotée) pour être sûr qu’on aligne tout :

1. Souhaitez-vous autoriser le **paiement partiel** pour les tables (ex : quelqu’un part plus tôt) ?
2. Le paiement au comptoir doit-il être **enregistré quand même** dans SelectO (pour analytics) ?

Dites-moi — et je complète.