TuniRFID Retail Suite v2.1

cd D:/virtual_envs/langchain_kernel/langraph_testing/RFID/retail_suite
python -m uvicorn stock_manager.server:app --host 0.0.0.0 --port 8013 --reload

Ouvrir le navigateur ➜ http://localhost:8013

Creer les Magasins / Depots

Les magasins representent vos points de stockage physiques. Chaque mouvement de stock est lie a un magasin.

Magasin 1 : MAG-TUNIS  / "Magasin Tunis Centre"  / Type: STORE
Magasin 2 : DEP-SOUSSE / "Depot Sousse"           / Type: WAREHOUSE
Magasin 3 : HQ-SFAX    / "Siege Sfax"              / Type: HQ

Famille ➜ Sous-famille

Le Rayon est un attribut libre saisi directement sur l'article (ex: DAME, HOME, ENFANT). La hierarchie dans Parametres est : Famille (parent) → Sous-famille (enfant).

FAMILLES :
  CHEMISE  ➜ Chemises       PANTALON ➜ Pantalons
  TSHIRT   ➜ T-Shirts       VESTE    ➜ Vestes
  CEINTURE ➜ Ceintures      ECHARPE  ➜ Echarpes

SOUS-FAMILLES :
  CH-SLIM    ➜ Chemise Slim Fit      (Famille: Chemises)
  CH-CLASSIC ➜ Chemise Classique     (Famille: Chemises)
  PN-JEAN    ➜ Jean                  (Famille: Pantalons)
  PN-CHINO   ➜ Chino                 (Famille: Pantalons)

Gammes de tailles

Une gamme = un ensemble de tailles predefinies. Selectionnee dans l'article, elle alimente automatiquement les variantes.

Gamme ADULTE : 36, 38, 40, 42, 44, 46, 48
Gamme ENFANT : 2A, 4A, 6A, 8A, 10A, 12A, 14A
Gamme UNIQUE : TU (taille unique)
Gamme SHOES  : 39, 40, 41, 42, 43, 44, 45

Unites, Marques, Fournisseurs, Saisons, Genres

Definir Tailles et Couleurs

Tailles : Cliquer "Ajout gamme" ➜ les tailles (36-48) apparaissent comme des chips.

Couleurs : Saisir BLANC + Entree, NOIR + Entree, BLEU CIEL + Entree

Soldes hiver 2026 avec 3 demarques progressives

1. Sidebar ➜ 🏷 Soldes & Promotions ➜ + Nouvelle campagne
2. Nom = SOLDES HIVER 2026, Type = SOLDES
3. Dates : du 2026-01-01 au 2026-01-31
4. Section 3. Demarques : + Ajouter demarque × 3 :
   • D1 : -20% du 01/01 au 10/01
   • D2 : -30% du 11/01 au 20/01
   • D3 : -40% du 21/01 au 31/01
5. Section 4. Cibles ➜ bouton Parcourir & selectionner SKUs ➜ tableau atelier s'ouvre
6. Filtrer par saison HIV-2026 ➜ cocher la ligne d'en-tete ➜ tous les SKUs HIV sont selectionnes
7. (Optionnel) Override par SKU : pour le SKU doudoune cuir, fixer D3 a -50% inline
8. Section 5. Sites ➜ cocher les magasins concernes
9. Enregistrer ➜ la campagne devient active

Le chantier des soldes — un tableau, tout sous la main

L'atelier est l'outil central pour piloter une campagne sur des centaines de SKUs.

Achetez 3, payez 2 — pack famille T-shirts

1. Sidebar ➜ Soldes & Promotions ➜ onglet Regles panier
2. + Nouvelle regle ➜ type = QUANTITE
3. Condition : 3 articles de la famille T-SHIRTS
4. Action : Article le moins cher offert (100% remise sur le SKU le moins cher)
5. Cumul : non-cumulable avec les codes promo
6. Enregistrer

Code promo distribuable

1. Onglet Codes promo ➜ + Nouveau code
2. Code = BIENVENUE15 (saisi par le client en caisse)
3. Reduction : -15% sur le total panier HT
4. Validite : du 2026-05-01 au 2026-06-30, usage max 500
5. Premiere visite client uniquement (case a cocher)
6. Enregistrer ➜ le code apparait dans la liste avec compteur d'usage

Creer un BL

1. Numero : Auto-genere (BL-2026-00001) — lecture seule
2. Fournisseur : Societe Textile du Nord (obligatoire)
3. Depot : Magasin Tunis Centre (obligatoire)
4. Date BL : aujourd'hui
5. Ref fournisseur : FAC-STN-2026-0142
6. Remise globale % : 0
7. Notes : Livraison PE 2026 lot 1

Ajouter une ligne (mode standard)

1. Taper Oxford dans "Ajouter article" ➜ autocomplete
2. Selectionner ➜ dropdown "Variante" apparait
3. Choisir 36 - BLANC
4. Remplir : Qte=10, Prix HT=25.000, Rem%=0, TVA%=19, FODEC%=1
5. Montants calcules en live ➜ Cliquer "Ajouter"

Repeter pour chaque variante... Mais c'est fastidieux pour 21 variantes ! ➜ C'est la qu'intervient la Matrice.

Page Comptes clients B2B

1. Sidebar ➜ Comptes clients B2B ➜ + Nouveau client B2B
2. Raison sociale, matricule fiscal, RC, adresse, contact, telephone, email
3. Conditions commerciales : remise par defaut (%), delai de paiement (jours), plafond encours (DT)
4. Enregistrer ➜ le client apparait avec encours = 0 DT

Page BL Vente

1. Sidebar ➜ BL Vente ➜ + Nouveau BL Vente
2. Client B2B (obligatoire), magasin source, date de livraison
3. Ajouter les articles ➜ matrice de variantes ou ligne par ligne
4. Le prix est pre-rempli automatiquement : prix de vente B2B (gros) de l'article s'il est defini, sinon repli sur le prix de detail. Un badge B2B signale que le tarif gros a ete applique. Remise % editable par ligne ; le prix reste modifiable.
5. Sauvegarder ➜ statut BROUILLON
6. Valider le BL ➜ statut VALIDE, stock decremente (mouvement SORTIE_B2B)

Bouton Creer Facture client

1. Sur le BL Vente VALIDE, cliquer Creer Facture client
2. Confirmer ➜ la facture est creee en BROUILLON avec les lignes du BL et les bons prix
3. Le BL passe a FACTURE
4. Aller dans Factures clients ➜ ouvrir la facture
5. Selectionner ou creer un echeancier (ex: 30 jours fin de mois ➜ date echeance auto-calculee)
6. Valider la facture ➜ statut VALIDEE
7. L'encours du client B2B augmente du montant TTC de la facture

Activer la saisie matricielle

1. Ouvrir un BL (nouveau ou existant en BROUILLON)
2. Section Articles ➜ cliquer "Saisie matricielle"
3. Le formulaire ligne par ligne est masque, la grille apparait

Pour revenir : cliquer "Saisie ligne par ligne"

Selectionner l'article

Taper Oxford ➜ selectionner ➜ toutes les variantes se chargent ➜ la grille se construit :

Creer puis faire valider

1. Choisir depot source et depot destination
2. Ajouter les lignes : Manuel, Scan, Matrice, Import Excel, Depuis BL/Facture, ou Cloner un transfert existant
3. "Soumettre" ➜ le transfert passe EN ATTENTE
4. Un MANAGER+ clique "Valider" ➜ statut VALIDE (contenu verrouille)

↺ Rouvrir une reception (rattraper un ecart)

Un transfert finalise en RECU alors qu'il restait des unites affiche un bouton orange "↺ Rouvrir la reception" (MANAGER+). Un clic le repasse en EN RECEPTION sans toucher au stock deja recu ; vous reprenez la reception des unites restantes via "Recevoir". Le stock destination n'est augmente que du complement — jamais de double comptage.

Ouvrir Veille & Sourcing

1. Sidebar ➜ Veille & Sourcing (section Intelligence IA)
2. L'app dediee /intel.html (Signal Room) s'ouvre dans le meme onglet
3. Onglet Preferences ➜ cocher les secteurs autorises pour ce tenant (limites par allowed_sectors defini en superadmin)

Pipeline Discovery

1. En haut de l'app : Mode Decouverte (par defaut)
2. Choisir le secteur (parmi ceux actives en preferences)
3. Saisir un brief : zone geo, fourchette de prix, contraintes
4. Cliquer Lancer ➜ le pipeline v5 demarre : query_planner_collector ➜ page_extractor ➜ supplier_resolver_extractor ➜ qualifier_scorer ➜ report_composer ➜ finalize
5. L'UI affiche la progression en direct via WebSocket (etapes vert/orange, lignes ajoutees au fil de l'eau)
6. A la fin, un rapport apparait : tendances reperees, fournisseurs scoreds (business TN, confiance donnee, evidence weight), priorite haute/medium/basse

Watchlists par tenant

1. Mode Marques BPS ➜ surveille les marques de la watchlist {slug}.yaml
2. Mode Concurrents ➜ surveille les sites de la watchlist {slug}_competitors.yaml
3. Notifications : un digest 4h regroupe les nouveautes (08/12/16/20h Tunis), envoye par email ou Telegram
4. Heures creuses 22h–07h Tunis : pas d'envoi (anti-spam)

Creer un profil de permission

1. Onglet "Profils & Permissions" dans Parametres
2. Cliquer "+ Nouveau profil"
3. Saisir un nom (ex: Magasinier Vue Seule) et une description
4. Dans la matrice : pour chaque module, cocher les droits a autoriser (les droits non coches seront refuses, meme si le role les permet)
5. Colonne "Effectif" affiche le resultat apres AND avec la baseline du role
6. Cliquer "Enregistrer"

Provisionner une machine

1. Page Postes RFID ➜ + Nouveau poste
2. Nom : Caisse 1 Tunis, magasin associe, type (CAISSE / PORTIQUE / INVENTAIRE)
3. Le systeme genere une API-key HMAC + URL webhook : a copier dans le fichier de config du rfid_dashboard sur la machine
4. Statut initial : JAMAIS VU — passe a EN LIGNE au premier heartbeat recu

Heartbeat et statut

Chaque poste pinge POST /api/heartbeat toutes les 60s avec son etat (lecteur connecte, derniers EPC lus). La liste affiche en temps reel :

• EN LIGNE — heartbeat < 2 min
• SILENCIEUX — heartbeat 2–15 min
• HORS LIGNE — pas de heartbeat depuis > 15 min

Installer Zebra Browser Print

1. Page Config. imprimante ➜ section "Guide d'installation"
2. Cliquer "Telecharger le script d'installation" ➜ un fichier install_zbp.bat est telecharg
3. Executer le .bat en tant qu'administrateur ➜ il telecharg et installe ZBP automatiquement
4. ZBP demarre en arriere-plan et ecoute sur localhost:9100

Verifier le statut ZBP

1. La carte "Statut Zebra Browser Print" en haut de la page affiche en temps reel
2. Si Deconnecte : ZBP n'est pas lance ➜ verifier le service Windows ou relancer le .bat
3. Si Connecte mais aucune imprimante : brancher le cable USB et allumer l'imprimante
4. L'imprimante ZD621R doit apparaitre, de preference avec connexion usb (raw ZPL direct, plus fiable que driver)

1. Les 5 indicateurs en haut de page

Mis a jour selon les filtres actifs (periode 24h par defaut) :

• Ventes — nombre total de tickets (detail : X valides + Y annulees)
• CA TND — chiffre d'affaires des ventes valides uniquement (les annulees sont exclues)
• Panier moyen — CA / nombre de ventes valides
• Annulees % — taux d'annulation sur le total
• En attente d'encaissement (TND) NOUVEAU — montant total des ventes carte/credit/cheque pas encore validees par l'admin. C'est l'argent vendu mais pas encore confirme en caisse : un coup d'oeil sur votre tresorerie a recouvrer.

2. Filtres multicriteres (combinables)

• Puces rapides : Aujourd'hui · 7 derniers jours · 30 jours · Mois en cours · Tout
• Plage de dates Du / Au (remplacee par les puces si vous cliquez l'une d'elles)
• Mode de paiement : Especes / Carte / Cheque / Mixte / Credit
• Statut : Valide (encaisse) / En attente d'encaissement / Annulee / Remboursee
• Caissier (recherche partielle du nom)
• Magasin — visible seulement si le tenant a plusieurs magasins actifs
• Recherche libre : n° de ticket, code client ou raison sociale

2bis. Vues enregistrees (sauvegarder vos filtres) NOUVEAU

Reglez vos filtres puis cliquez "Enregistrer la vue" et nommez-la (ex. « Especes ce mois », « Annulations 30j »). Elle apparait sous forme de pastille ★ en haut de la barre : un clic la reapplique instantanement.

• Cochez "Partager avec l'equipe" pour la rendre visible a tous les ADMIN/MANAGER du magasin.
• Le × sur une pastille supprime la vue (proprietaire ou ADMIN).
• Les vues sont synchronisees cote serveur — vous les retrouvez sur tous vos appareils (a la difference d'un simple favori navigateur).

3. Tableau, tri et pagination

Colonnes : Ticket · Date/Heure · Caissier · Client · Articles · Mode (badge colore) · Magasin · Total TTC · Validation admin · Statut · Actions.

La colonne Statut est placee juste apres Validation admin car elle en decoule (cycle d'encaissement, par ordre de priorite) : ❌ Annulee > ↩ Remboursee > ✅ Valide (espece, ou non-espece coche par l'admin) > ⏳ En attente (non-espece pas encore validee). Plus de contradiction « Valide » + « en attente » sur la meme ligne.

• Tri sur 3 colonnes (Date, Total TTC, N° ticket) — la fleche ▾/▴ indique le sens
• Pagination 25 / 50 / 100 lignes par page, avec indicateur « X–Y / Z »
• Clic sur une ligne ➜ ouvre le detail complet de la vente

4. Validation admin de l'encaissement

La colonne Validation admin tranche entre un encaissement deja confirme et un encaissement en attente selon le mode de paiement :

• Especes ➜ ✅ Auto : l'argent est encaisse a la caisse, la vente est validee d'office. Rien a faire.
• Tout autre mode (carte, credit, cheque, cheque cadeau, mixte) ➜ case a cocher en attente : l'encaissement reel (virement TPE, recouvrement du credit, compensation du cheque) n'est pas garanti au moment de la vente.

Qui peut cocher ? Seuls les profils Admin et Superadmin. Pour les autres roles la case s'affiche mais reste desactivee (lecture seule).

Comment valider : une fois l'argent reellement recu, cochez la case sur la ligne ➜ la vente bascule en « encaissement valide » et le systeme enregistre qui a valide et quand. Decocher annule la validation (champs remis a zero).

Note : les ventes deja presentes dans l'historique avant cette mise a jour restent considerees comme validees (pas de reouverture massive). Une vente annulee ne peut pas etre validee.

5. Fiche detail d'une vente

La fenetre affiche : entete (ticket, date, caissier, magasin, statut), liste des articles (designation, code, qte, prix unitaire TTC, total ligne), bloc client, et le detail des taxes (HT / TVA / FODEC / Droit de consommation / TPE / Timbre / TTC). Si la vente a fait l'objet de retours, un encadre jaune liste l'historique des retours (date, montant, motif).

6. Voir toutes les ventes d'un client

Cliquez sur le nom d'un client dans la colonne Client ➜ la liste se filtre automatiquement sur ce client et une puce « 👤 Client : NOM × » apparait en haut. Les autres filtres (dates, mode...) restent actifs. Cliquez le × pour retirer ce filtre.

7. Exporter (CSV et Excel)

• CSV — fichier texte universel (separateur « ; », encodage compatible Excel FR)
• Excel (.xlsx) — mise en forme riche : entete bleu, ligne d'entete figee, format millimes 0.000 sur HT/TTC, statuts colores (vert valide / orange en attente / rouge annulee / jaune remboursee), ligne de totaux, et un 2e onglet « Filtres appliques » qui trace le contexte de l'export
• Les deux formats incluent desormais les colonnes « Valide par » et « Valide le » — utile pour la passation comptable (qui a confirme l'encaissement, et quand)

L'export respecte les filtres actifs (un export « CARTE, ce mois » ne contient que ces ventes). Plafond de securite : 50 000 lignes par export.

8. Carte de chaleur horaire

Bouton « Afficher heatmap horaire » ➜ grille 7 jours × 24 heures coloree selon l'intensite. Basculez la metrique entre 🛒 Nombre de ventes et 💰 CA TND. Les ventes annulees sont exclues. Usage typique : reperer les pics d'affluence (ex. jeudi 18–19h, samedi 10–12h) pour ajuster les horaires caissiers.

9. Journal d'audit (tracabilite)

Bouton « Audit » ➜ fenetre listant qui a fait quoi et quand sur les actions sensibles : exports CSV/XLSX et annulations en lot. Chaque ligne : utilisateur, role, action, filtres utilises, nombre de lignes, adresse IP, horodatage. Filtrable par action et par date. Utile pour la conformite (qui a exporte les donnees ce mois ?).

Se connecter a la caisse

Sur pos.tunirfid.app : choisir l'enseigne (tenant), selectionner le caissier dans la liste, puis saisir le PIN au pave numerique ➜ VALIDER. La session reste ouverte (le caissier ne voit que ses propres ventes dans l'historique).

Demarrer un ticket

Bouton Nouveau (raccourci F12) ➜ panier vide pret a scanner. Le ticket precedent est automatiquement clos.

Ajouter des articles

Trois facons d'ajouter une ligne au panier :

• Code-barres (douchette) — l'article s'ajoute, la quantite s'incremente si deja present
• EPC RFID (lecteur, offre Premium) — identifie la piece exacte (24 caracteres hex)
• PLU — saisie d'un code court (1 a 6 chiffres) au clavier

Quantites, remises, client

• Quantite : boutons + / − sur chaque ligne ; bouton × pour retirer
• Remise ligne ou remise globale (% sur le total)
• Client fidelite : rechercher le client ➜ ses points et avoirs s'affichent
• Code promo ou bon de reduction : saisir la reference, validee en direct

Choisir le mode de paiement

Bouton REGLER TICKET (raccourci F3) ➜ le total du s'affiche en grand. Modes disponibles :

Confirmez ➜ le ticket 80 mm s'imprime (entete enseigne, articles, totaux, ventilation des modes de paiement, points fidelite gagnes).

Rembourser un article vendu

1. Ouvrir le ticket d'origine (recherche par numero)
2. Retour par quantite : choisir les articles et la quantite a rendre ; ou retour par EPC (Premium) : scanner la piece exacte
3. Choisir un motif (Defectueux, Taille, Couleur, Erreur, Remboursement client)
4. Valider ➜ le stock est restitue (mouvement RETURN), la piece RFID repasse en stock, et les points de fidelite sont ajustes

Comment fonctionne la fidelite

• A chaque vente, le client cumule des points selon le bareme (ex. 10 DT depenses = 1 point)
• Au seuil defini (ex. 100 points), un bon de reduction est genere (ex. 10 DT), avec une date d'expiration
• Le bon s'utilise en caisse en saisissant sa reference au moment du paiement

Le bareme se configure cote StockManager (module M12 Clients / Fidelite).

Identifier ou creer un client des le debut du ticket NOUVEAU

En haut de l'ecran de vente (sous le numero de ticket), une barre Client permet d'associer un client au ticket avant le paiement — pour voir ses points pendant qu'on scanne :

• Identifier un client existant : tapez nom, telephone ou code dans le champ « 👤 Client » ➜ selection dans la liste ➜ ses points s'affichent et ses bons deviennent disponibles au paiement.
• + Nouveau : ouvre le formulaire client complet (identique a celui de StockManager › Parametres) — Particulier (B2C) ou Entreprise (B2B : raison sociale, matricule fiscal, ICE), telephone, email, adresse… Le client est cree dans la meme base que l'admin et associe au ticket.
• Le client choisi est conserve jusqu'au paiement (les points de fidelite sont calcules a l'encaissement) ; un nouveau ticket repart sans client.

Le meme champ client reste disponible dans la fenetre de reglement (pour l'ajouter au dernier moment).

Consulter les ventes

Page Ventes de la caisse : liste des tickets du jour avec filtres (date, mode, caissier). Un MANAGER peut ouvrir le detail et annuler une vente isolee (le stock est reverse).

Rapport journee (cloture)

Page Rapport : indicateurs du jour — CA TTC, nombre de tickets, ticket moyen, ventilation par mode de paiement, top produits, et detail par caissier. Sert a compter la caisse en fin de journee et documenter un eventuel ecart especes.

Anti-double-vente (Premium)

Quand une piece RFID est scannee, son EPC passe en statut RESERVE. Si une autre caisse scanne la meme piece au meme instant, la premiere gagne (200 OK) et la seconde recoit un refus (409) — impossible de vendre deux fois la meme piece physique. Au paiement, l'EPC passe VENDU ; si le ticket est abandonne, il revient automatiquement en STOCK.