# PIXLAB Plaquette Tracker — Guide d'installation

Système complet de tracking de plaquettes PDF avec dashboard admin, notifications temps réel et scoring d'engagement.

---

## 📦 Contenu du projet

```
plaquette-tracker/
├── config/
│   ├── config.php              ← À configurer avant déploiement
│   └── database.sql            ← Schéma MySQL à importer
├── public/                     ← Web-accessible
│   ├── view.php                ← Viewer client
│   ├── assets/                 ← CSS + JS
│   └── pdfs/                   ← Dépôt des PDFs (protégé)
├── api/
│   ├── track.php               ← Endpoint tracking
│   └── pdf-stream.php          ← Stream sécurisé PDF
├── admin/                      ← Dashboard protégé
│   ├── login.php
│   ├── dashboard.php
│   ├── detail.php
│   ├── generate.php
│   ├── logout.php
│   └── assets/admin.css
├── includes/                   ← Classes PHP (non web-accessible)
│   ├── db.php
│   ├── auth.php
│   ├── tracker.php
│   ├── scoring.php
│   └── notifier.php
├── logs/                       ← Logs d'erreurs
└── .htaccess                   ← URL rewriting + sécurité
```

---

## 🚀 Installation sur pixlab.ma

### Étape 1 : Uploader les fichiers

Uploader tout le dossier `plaquette-tracker/` dans un dossier `/p/` à la racine de `pixlab.ma` :

```
pixlab.ma/
├── index.html
├── (autres fichiers du site)
└── p/                          ← Le dossier tracker
    ├── config/
    ├── public/
    └── ...
```

**URL final** : les liens seront `https://pixlab.ma/p/TOKEN`

### Étape 2 : Créer la base de données MySQL

Via phpMyAdmin ou ligne de commande :

```sql
CREATE DATABASE pixlab_tracker CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'pixlab_user'@'localhost' IDENTIFIED BY 'MOT_DE_PASSE_FORT';
GRANT ALL PRIVILEGES ON pixlab_tracker.* TO 'pixlab_user'@'localhost';
FLUSH PRIVILEGES;
```

Puis importer le schéma :

```bash
mysql -u pixlab_user -p pixlab_tracker < config/database.sql
```

Ou depuis phpMyAdmin : sélectionner la base `pixlab_tracker` > Importer > choisir le fichier `config/database.sql`.

### Étape 3 : Configurer `config/config.php`

Éditer le fichier et remplacer :

```php
define('DB_HOST', 'localhost');
define('DB_NAME', 'pixlab_tracker');
define('DB_USER', 'pixlab_user');
define('DB_PASS', 'ton_mot_de_passe_fort'); // ← Celui créé en étape 2

// Générer avec : php -r "echo bin2hex(random_bytes(32));"
define('APP_SECRET', 'COLLER_UN_STRING_RANDOM_64_CARACTÈRES_ICI');

// Email SMTP
define('SMTP_HOST', 'smtp.pixlab.ma');
define('SMTP_USER', 'hello@pixlab.ma');
define('SMTP_PASS', 'ton_mot_de_passe_smtp');

// Ton email pour recevoir les notifs
define('NOTIFY_ADMIN_EMAIL', 'mehdi.koraich@pixlab.ma');
```

### Étape 4 : Créer le mot de passe admin

Le schéma SQL a créé un compte admin `medi` avec un hash factice. Il faut générer le vrai hash.

Via SSH ou un script PHP temporaire :

```bash
php -r "echo password_hash('TON_MOT_DE_PASSE_CHOISI', PASSWORD_BCRYPT);"
```

Puis mettre à jour en base :

```sql
UPDATE pt_admins SET password_hash = 'HASH_COLLÉ_ICI' WHERE username = 'medi';
```

**⚠️ Change le mot de passe par défaut AVANT de mettre en ligne.**

### Étape 5 : Déposer les PDFs

Copier les fichiers PDF dans `public/pdfs/` :

```
public/pdfs/
├── Plaquette-Photobooth-Pixlab-2026.pdf
└── Plaquette-Totems-bornes-Pixlab-2026-Agence-STD.pdf
```

**Les noms doivent correspondre exactement à ceux en base dans `pt_documents.filename`.**

Pour ajouter d'autres documents plus tard :

```sql
INSERT INTO pt_documents (name, filename, total_pages)
VALUES ('Plaquette Mariage 2026', 'plaquette-mariage-2026.pdf', 20);
```

### Étape 6 : Vérifier les permissions

```bash
chmod 755 plaquette-tracker/
chmod 644 plaquette-tracker/config/config.php
chmod 755 plaquette-tracker/logs/
chmod 644 plaquette-tracker/public/pdfs/*.pdf
```

### Étape 7 : Tester

1. Aller sur `https://pixlab.ma/p/admin/login.php`
2. Login avec `medi` + ton mot de passe
3. Cliquer "+ Nouveau lien"
4. Créer un lien test (Client: Test, Document: une plaquette)
5. Ouvrir le lien généré dans un navigateur privé
6. Vérifier que :
   - Le loader PIXLAB s'affiche
   - Le PDF se charge
   - Tu reçois un email de notification
   - Retour au dashboard : la session apparaît avec durée, device, etc.

---

## 🔒 Sécurité — checklist avant production

- [ ] `DEBUG_MODE = false` dans `config.php`
- [ ] `APP_SECRET` a été remplacé par une vraie chaîne aléatoire
- [ ] Mot de passe admin par défaut changé
- [ ] SSL/HTTPS activé (obligatoire pour les cookies secure)
- [ ] Décommenter la redirection HTTPS dans `.htaccess`
- [ ] Décommenter HSTS dans `.htaccess`
- [ ] `config.php` non accessible (testé via `https://pixlab.ma/p/config/config.php` → 403)
- [ ] Dossier `pdfs/` non accessible (testé via `https://pixlab.ma/p/public/pdfs/xxx.pdf` → 403)

---

## 📧 Configuration notifications

### Email (SMTP)

Le système envoie 4 types de notifications :
- 🎯 **Première ouverture** : dès que le client ouvre le lien
- 👀 **Visite de retour** : à chaque nouvelle session
- 🔥 **Lead chaud** : après 3+ sessions + 5+ min (envoyé une seule fois)
- 📤 **Forward détecté** : si une IP différente ouvre le même lien

Configurer `SMTP_*` dans `config.php`.

### WhatsApp (optionnel)

Non activé par défaut. Pour l'activer :

1. Choisir un provider : Twilio, Meta Cloud API, ou autre
2. Mettre `WHATSAPP_ENABLED` à `true`
3. Implémenter la méthode `sendWhatsApp()` dans `includes/notifier.php`

---

## 📊 Utilisation quotidienne

### Créer un lien pour un prospect

1. Aller sur `https://pixlab.ma/p/admin`
2. Cliquer "+ Nouveau lien"
3. Remplir : plaquette, nom client, société, email, expiration
4. Copier le lien généré
5. L'envoyer par email, WhatsApp, etc.

### Consulter l'engagement

- **Dashboard** : vue globale, filtre par chaud/tiède/froid
- **Détails client** : timeline complète, temps par page, événements, forwards détectés

### Signaux à surveiller

- 🔥 **Lead chaud** → appel dans les 24h
- 📤 **Forward détecté** → ton prospect a transféré à un décideur = signal très fort
- ⏱ **Temps élevé sur une page spécifique** → point d'intérêt précis
- 👆 **Clic sur CTA email** → volonté de contact

---

## 🛠 Maintenance

### Logs d'erreurs
`logs/error.log` — consulter en cas de problème

### Nettoyage rate_limit
La table `pt_rate_limit` se nettoie automatiquement. Optionnel : cron mensuel :
```sql
DELETE FROM pt_rate_limit WHERE window_start < DATE_SUB(NOW(), INTERVAL 1 HOUR);
```

### Archivage des vieux liens
Après 1 an par exemple :
```sql
UPDATE pt_links SET is_active = 0 WHERE created_at < DATE_SUB(NOW(), INTERVAL 1 YEAR);
```

---

## 🧩 Évolutions futures (PIXLAB Hub)

Le préfixe `pt_` (plaquette tracker) permet une intégration propre dans le futur PIXLAB Hub.
À prévoir :
- Table `pt_admins` → fusion avec `hub_users` (SSO)
- Notifications → système de queue unifié
- Dashboard → intégré dans le menu principal du Hub
- Export CSV → déjà possible via requêtes directes sur la base

---

## 📞 Support

Technique : relire ce README + logs dans `logs/error.log`
Questions : mehdi.koraich@pixlab.ma

---

**© 2026 PIXLAB — pixlab.ma**
