# Logiciel de Vente & API Stock

Logiciel desktop de vente (Tkinter) avec gestion de stock en temps réel et
API REST sécurisée (FastAPI) pour applications mobiles tierces.
Conforme au PRD v1.0 du 05/08/2026.

---

## 1. Prérequis

- **Python 3.11+** (Tkinter inclus par défaut sous Windows et macOS ;
  sous Linux : `sudo apt install python3-tk`)
- Windows 10/11, macOS ou Linux

## 2. Installation

```bash
# 1. Décompresser le projet puis se placer dedans
cd logiciel-vente-api

# 2. Installer les dépendances
pip install -r requirements.txt

# 3. Créer la configuration (clé API secrète)
#    Windows : copy .env.example .env
#    Linux/macOS : cp .env.example .env
#    → éditer .env et remplacer la valeur de API_KEY

# 4. Insérer les données de démonstration (produits Thomson)
python seed_data.py
```

## 3. Lancement

```bash
# Mode complet : interface graphique + API (port 8000)
python main.py

# Mode serveur seul (sans interface graphique)
python main.py --api-only
```

Vérification de l'API : <http://localhost:8000/api/v1/health>
Documentation interactive Swagger : <http://localhost:8000/docs>

## 4. Utilisation de l'API (app mobile tierce)

Tous les endpoints métier exigent le header `X-API-Key` avec la clé définie
dans `.env` :

```bash
curl -H "X-API-Key: votre-cle" \
     "http://localhost:8000/api/v1/disponibilite/TH-43-4K?qte=2"
```

| Méthode | Endpoint | Auth | Description |
|---|---|---|---|
| GET | `/api/v1/health` | Non | Vérifier que l'API répond |
| GET | `/api/v1/produits` | Oui | Produits actifs |
| GET | `/api/v1/produits/{reference}` | Oui | Détail d'un produit |
| GET | `/api/v1/produits/search?q=...` | Oui | Recherche nom/référence/catégorie |
| GET | `/api/v1/disponibilite/{reference}?qte=n` | Oui | Disponibilité + prix total |
| GET | `/api/v1/categories` | Oui | Liste des catégories |
| GET | `/api/v1/stats/stock-faible` | Oui | Produits sous seuil d'alerte |

## 5. Accès distant — Tunnel Cloudflare

L'app mobile peut interroger l'API à distance sans ouvrir aucun port :

```bash
# Démo rapide (URL temporaire, sans compte Cloudflare)
scripts/tunnel_cloudflare.sh          # Linux/macOS
scripts\tunnel_cloudflare.bat         # Windows

# Production (tunnel nommé, URL fixe — nécessite un compte Cloudflare)
cloudflared tunnel login
cloudflared tunnel create api-stock
cloudflared tunnel route dns api-stock api.votredomaine.com
scripts/tunnel_cloudflare.sh nomme
```

L'URL publique affichée (ex. `https://xyz.trycloudflare.com`) est à utiliser
par l'app mobile : `https://xyz.trycloudflare.com/api/v1/...`
Le HTTPS/TLS 1.3 est assuré automatiquement par Cloudflare.

## 6. Générer l'exécutable (.exe Windows)

Sur une machine **Windows** (PyInstaller ne fait pas de cross-compilation) :

```bat
build.bat
```

Résultat : `dist\LogicielVente\LogicielVente.exe` — autonome, distribuable
sans installation de Python. Sous Linux/macOS : `./build.sh`.

## 7. Scénario de démonstration investisseurs (3 min)

1. **Stock** — l'écran principal affiche les produits Thomson (TV 43" = 5 unités)
2. **Vente** — scanner/saisir `TH-43-4K`, quantité 2, valider → le stock passe à 3 en direct
3. **Synchro** — depuis un smartphone (via l'URL du tunnel), appeler
   `/api/v1/disponibilite/TH-43-4K` → l'API retourne `quantite_stock: 3`
4. **Rupture** — vendre les 3 dernières unités → l'API retourne
   `disponible: false`, `"Rupture de stock"`

## 8. Structure du projet

```
logiciel-vente-api/
├── main.py                  # Point d'entrée (GUI + API en parallèle)
├── config.py                # Configuration (.env, clé API, port, chemins)
├── database.py              # SQLite : schéma, CRUD, vente transactionnelle, triggers
├── models.py                # Modèles Pydantic (validation API)
├── seed_data.py             # Données de démo (5 produits Thomson)
├── requirements.txt
├── .env.example             # Modèle de configuration
├── build.bat / build.sh     # Packaging PyInstaller
├── gui/
│   ├── fenetre_principale.py  # Menu latéral + bandeau + thread API
│   ├── ecran_stock.py         # Tableau produits, recherche temps réel, code couleur
│   ├── ecran_vente.py         # Workflow de vente + ticket
│   ├── ecran_historique.py    # Historique + annulation (remise en stock)
│   └── ecran_api.py           # Statut API, compteurs, journal des requêtes
├── api/
│   ├── app.py               # Application FastAPI (CORS, logs, stats)
│   ├── routes.py            # Endpoints REST
│   └── auth.py              # Vérification du header X-API-Key
└── scripts/
    ├── tunnel_cloudflare.sh
    └── tunnel_cloudflare.bat
```

## 9. Sécurité

- Authentification par header `X-API-Key` (comparaison à temps constant)
- Requêtes SQL paramétrées uniquement (aucune injection possible)
- Contrainte `CHECK (quantite_stock >= 0)` + garde atomique lors des ventes
- HTTPS via Cloudflare Tunnel (TLS 1.3)
- CORS restreint (configurable dans `.env`)
- La clé API n'est jamais écrite dans les logs
- Archivage logique des produits (aucune donnée supprimée physiquement)

## 10. Dépannage

| Problème | Solution |
|---|---|
| `ModuleNotFoundError: tkinter` (Linux) | `sudo apt install python3-tk` |
| Port 8000 déjà utilisé | Changer `API_PORT` dans `.env` |
| 401 sur l'API | Vérifier que `API_KEY` dans `.env` = header envoyé par l'app |
| Base verrouillée | Fermer les autres instances du logiciel |
| Tunnel : URL introuvable | Regarder la ligne `https://...trycloudflare.com` dans la console cloudflared |
