<markdown>
# Documentation Technique - Projet HolyTag

## 1. Vue d'ensemble du projet

### Objectifs et problématiques adressées
Le projet HolyTag est une plateforme de génération et gestion de QR codes déployée sur une architecture de sous-domaines. Chaque module représente un service spécialisé permettant la création, la gestion et le suivi de campagnes QR codes pour des clients.

### Contexte métier et utilisateurs cibles
- **App** : Interface utilisateur publique pour scanner/saisir des codes d'accès (Holykey)
- **Admin** : Back-office pour la gestion complète des clients, campagnes et codes
- **QR** : Service de génération de QR codes en temps réel
- **Stats** : Système de collecte et analyse de données avec gestion d'abonnements
- **URL** : Service de gestion et redirection d'URLs courtes

### Architecture technique globale

```
holytag/prod/
├── app/            # Interface publique (saisie codes Holykey)
├── admin/          # Back-office administrateur
├── qr/             # Générateur de QR codes
├── stats/          # Service de statistiques et abonnements
├── url/            # Service de gestion d'URLs courtes
├── client/         # Scripts côté client
└── vendor/         # Dépendances externes
```

## 2. Stack technologique

### Technologies principales
- **Backend** : PHP (Framework NOOP custom)
- **Frontend** : JavaScript, jQuery, HTML5, CSS3
- **Base de données** : MySQL
- **Serveur web** : Apache (.htaccess)

### Bibliothèques et frameworks
- **NOOP Framework** : Framework PHP custom avec architecture MVC
- **jQuery** : Bibliothèque JavaScript principale
- **PHPQRCode** : Génération de QR codes
- **PHPMailer** : Gestion des emails
- **C3.js** : Graphiques et visualisations
- **jsTree** : Interface arborescente pour l'admin

### Infrastructure
- **Hébergement** : Infomaniak (1e6g2.myd.infomaniak.com)
- **Base de données** : MySQL (1e6g2_holytag_db, 1e6g2_holytag_url)
- **Utilisateur MySQL** : 1e6g2_holytag
- **Environnement de développement** : Local (serveurweb, 192.168.2.200)

## 3. Framework NOOP - Architecture personnalisée

### Caractéristiques principales
- **Architecture** : MVC avec routing automatique
- **Configuration** : Système de configuration centralisé via fichiers INI
- **Gestion des erreurs** : Handler d'exceptions personnalisé
- **Base de données** : Abstraction PDO multi-base
- **Sessions** : Gestion centralisée avec sécurisation

### Structure de fonctionnement
```php
// Configuration type
noop::config(array(
    'pdo' => array('db' => 'mysql,host=...;dbname=...,user,password'),
    'path' => array(
        'controller' => 'secure/control',
        'view' => 'secure/view'
    )
));

// Démarrage de l'application
noop::init('secure/global.ini');
```

## 4. Structure du code

### Organisation des services

#### Service App (`app/`)
- **Point d'entrée** : `index.php` - Interface publique de saisie de codes Holykey
- **Processus** : `script.php` - Validation et redirection vers URLs courtes
- **Fonction** : Permet aux utilisateurs sans smartphone de décoder des QR codes via un code d'accès

#### Service Admin (`admin/`)
- **Point d'entrée** : `index.php` → redirection vers `treeview`
- **Configuration** : `secure/global.ini`
- **Interface** : Gestion hiérarchique Clients → Campagnes → Codes
- **API REST** : Endpoints pour CRUD complet via jsTree

#### Service QR (`qr/`)
- **Point d'entrée** : `index.php` - Service web de génération QR
- **Librairie** : `qrlib.php` - PHPQRCode pour génération PNG/JPG/SVG
- **API** : Paramètres size, ecc, margin, foreground, background
- **Architecture hybride** : Version locale + service externe `qr.lca.fr`

#### Service Stats (`stats/`)
- **Point d'entrée** : `index.php` - Dashboard et statistiques
- **Fonctionnalités** : Authentification, graphiques C3.js, gestion packs PayPal
- **Contrôleurs** : `secure/control/` - Logique métier complète

#### Service URL (`url/`)
- **Point d'entrée** : `index.php` - Résolution et redirection URLs courtes
- **Base dédiée** : `1e6g2_holytag_url` séparée du référentiel principal

### Conventions de nommage
- **Fichiers de configuration** : `.ini`, `.htaccess`, `.php-ini`
- **Contrôleurs** : `secure/control/`
- **Vues** : `secure/view/`
- **Ressources** : `lib/`, `img/`
- **Temporaires** : `temp/`, `out/`

## 5. Configuration et environnements

### Configuration base de données (Production)
```ini
[pdo]
db = "mysql,host=localhost;dbname=1e6g2_holytag_db,1e6g2_holytag,ycW6-XGiyA8"
```
**Format** : `mysql,host=HOST;dbname=DATABASE,USER,PASSWORD`

### Détection d'environnement
```php
define('DEV', (in_array($_SERVER['HTTP_HOST'], array('serveurweb', '192.168.2.200'))
    || strpos($_SERVER['HTTP_HOST'], '.tarawam') !== false 
    || strpos($_SERVER['HTTP_HOST'], 'holytag.net') !== false));
```

### Configuration par environnement
- **Production** : holytag.fr, base Infomaniak
- **Développement** : holytag.net, base locale
- **URLs** : Configuration dynamique qr/url selon environnement

## 6. Base de données - Spécificité de chaque DB

### Architecture multi-bases
Le système utilise 2 bases de données MySQL distinctes avec des rôles spécifiques :

#### **1e6g2_holytag_db** - Base de gestion principale
- **Fonction** : Gestion administrative et métier
- **Usage** : Services app, admin, stats
- **Tables principales** :
  - `admin_clients` : Gestion des clients
  - `admin_campagnes` : Campagnes de codes QR
  - `admin_codes` : Codes générés avec métadonnées
  - `admin_gabarits` : Templates de QR codes
- **Connexions** : Utilisée par tous les services sauf URL

#### **1e6g2_holytag_url** - Base de redirection
- **Fonction** : Service de raccourcissement d'URLs
- **Usage** : Service URL uniquement  
- **Tables principales** :
  - `url` : Mapping miniurl → URL longue
- **Processus** : Redirection transparente via miniurl

### Authentification MySQL
- **Utilisateur** : `1e6g2_holytag`
- **Mot de passe** : `ycW6-XGiyA8`
- **Accès** : Permissions sur les deux bases de données

### Flux de données inter-bases

#### Processus de génération de codes
1. **Admin** : Création campagne dans `1e6g2_holytag_db`
2. **Génération** : Insertion codes dans `admin_codes`
3. **URLs courtes** : Création miniURLs dans `1e6g2_holytag_url`
4. **App** : Résolution code → miniURL → URL finale

#### Configuration par service
- **App/Admin/Stats** : `db` (1e6g2_holytag_db)
- **URL** : `db` (1e6g2_holytag_url)
- **QR** : Service stateless, pas de base (utilise service externe en production)

### Patterns d'utilisation

#### Service App
```php
// Validation code Holykey
$query = 'SELECT * FROM admin_codes WHERE (type = "miniurl" or type = "pdf") AND cle = ?';
// Redirection vers https://url.holytag.fr/[id_miniurl]
```

#### Service URL  
```php
// Résolution miniURL
'pdo' => array('db' => '1e6g2_holytag_url')
// Redirection finale selon contenu miniURL
```

## 7. Gestion des erreurs et logging

### Système d'exception personnalisé
- **Framework NOOP** : Gestion centralisée des erreurs
- **Logging** : Via error_log PHP standard
- **Debugging** : Activation/désactivation selon environnement

### Notifications d'erreurs
- **Email** : Configuration dans global.ini
- **Headers** : Status codes HTTP appropriés (404, 500)

## 8. Sécurité

### Authentification
- **Admin** : Login/password dans `global.ini`
```ini
[superadmin]
login = "webmaster" 
password = "Kev46ChrDim2"
```
- **Sessions** : Gestion sécurisée avec timeout
- **URL** : Authentification Basic pour certains endpoints

### Protection des données
- **PDO** : Requêtes préparées systématiques
- **Validation** : Contrôle des paramètres d'entrée
- **Accès** : Dossiers secure/ protégés par .htaccess

### Accès aux fichiers
- **Configuration** : Fichiers .ini hors webroot
- **Uploads** : Validation et nettoyage des fichiers
- **Environnement** : Séparation dev/prod automatique

## 9. Déploiement et maintenance

### Structure de déploiement
Chaque service est déployé sur son sous-domaine :
- `holytag.fr` → `app/` (interface publique)
- `admin.holytag.fr` → `admin/`
- `qr.holytag.fr` → `qr/`
- `stats.holytag.fr` → `stats/`
- `url.holytag.fr` → `url/`

### Maintenance
- **Logs** : Via error_log PHP et logs serveur
- **Monitoring** : Pas de système automatisé
- **Cache** : Gestion manuelle via paramètres URL

## 10. API QR Codes - Architecture hybride

### Services de génération multiples
HolyTag utilise une architecture hybride pour la génération de QR codes :

#### Service local (`qr/`)
```
URL : http://qr.holytag.fr/ (développement: qr.holytag.tarawam/)
Fonction : Réplique locale du service externe
Usage : Tests et développement principalement
```

#### Service externe (`qr.lca.fr`)
```
URL : http://qr.lca.fr/
Fonction : Service centralisé de l'agence LCA
Usage : Production (appelé depuis admin/secure/lib/QR.php)
Authentification : webmaster:ChrAle09lca
```

### Logique de basculement
```php
// admin/secure/lib/QR.php ligne 25
$url = (defined('DEV') && DEV === true) ? 
    'http://qr.holytag.tarawam/' :  // Développement
    'http://qr.lca.fr/';           // Production
```

### API de génération commune
```
Paramètres identiques sur les deux services :
- data (string) : données à encoder (obligatoire)
- size (int) : taille matrice (1-10, défaut: 4)
- ecc (char) : correction erreur (L/M/Q/H, défaut: L)
- margin (int) : marge blanche (0-10, défaut: 2)
- output (string) : format sortie (png/jpg/svg, défaut: png)
- foreground/background : couleurs personnalisées
- download : forcer téléchargement
```

### Niveaux de correction d'erreur
- **ECC L** : 6283 caractères (7% correction)
- **ECC M** : 4959 caractères (15% correction)
- **ECC Q** : 3538 caractères (25% correction)  
- **ECC H** : 2719 caractères (30% correction)

### Utilisation
```bash
# Service local (développement)
GET /qr/?data=https://example.com&size=5

# Service externe (production via classe QR)
QR::generate(array(
    'data' => 'https://example.com',
    'size' => 5,
    'output' => 'png'
))
```

### Intégration dans l'admin
```php
// admin/secure/lib/QR.php
class QR {
    const URL = 'http://qr.lca.fr/';
    const AUTH = 'webmaster:ChrAle09lca';
    
    // Appel cURL vers service externe en production
    // ou service local en développement
}
```

## 11. Workflow complet - Gestion d'une campagne

### Phase 1 : Création administrative
1. **Interface Admin** : Création client et campagne
2. **Paramètres** : Nombre de codes, validité, gabarit
3. **Génération** : Création automatique des codes uniques

### Phase 2 : Génération des codes
1. **Codes Holykey** : Génération des clés d'accès uniques
2. **MiniURLs** : Création des URLs courtes associées
3. **QR Codes** : Génération des visuels PNG/SVG
4. **Base** : Insertion dans `admin_codes`

### Phase 3 : Déploiement
1. **Publication** : Codes disponibles via interface App
2. **Redirection** : url.holytag.fr/[code] → destination finale
3. **Statistiques** : Tracking des accès et conversions

### Phase 4 : Suivi
1. **Dashboard Stats** : Métriques de performance
2. **Rapports** : Exports CSV et graphiques
3. **Gestion** : Modification/désactivation des codes

## 11. Script batchCampagne - Génération massive de codes

### Vue d'ensemble
Le script `admin/secure/control/batchCampagne.php` est l'outil principal pour générer massivement des campagnes de codes QR. Il automatise la création de codes, miniURLs et fichiers de production pour impression.

### Configuration du script
```php
// Configuration à modifier dans le fichier
$id_campagne = 886;                              // ID de la campagne cible
$destination_url = 'https://sewan.holytag.fr/magic/';  // URL de destination
```

### Processus de génération automatique

#### 1. Vérification de la campagne
```php
// Récupération des paramètres depuis admin_campagnes
SELECT * FROM admin_campagnes WHERE id_campagne = ?

// Calcul des codes manquants
$nCodes = count($codes_existants);
$manquant = $campagne['nb_codes'] - $nCodes;
```

#### 2. Création des miniURLs
```php
// Insertion dans la base 1e6g2_holytag_url
INSERT INTO url (creation, url) VALUES (NOW(), $destination_url)
$miniUrlId = $pdo2->lastInsertId();
```

#### 3. Génération des codes QR
```php
// Insertion dans admin_codes avec contenu JSON
$contenu = array(
    'url' => $destination_url,
    'miniurl' => 'https://url.holytag.fr/' . $slug
);
INSERT INTO admin_codes (...) VALUES (..., json_encode($contenu), ...)
```

#### 4. Production des fichiers de sortie

##### Fichiers CSV générés
```
out/holytag-campagne-[ID].csv           # Liste des codes avec miniURLs
out/holytag-campagne-[ID]-indesign.csv  # Chemins pour intégration InDesign
```

##### QR Codes PNG individuels
```
out/qrcodes-[ID]/
├── code-[ID_CODE].png
├── code-[ID_CODE].png
└── ...
```

### Utilisation pratique

#### 1. Préparation
```bash
# Modifier les variables dans batchCampagne.php
$id_campagne = 886;
$destination_url = 'https://client.holytag.fr/';
```

#### 2. Exécution
```bash
# Via navigateur (recommandé)
https://admin.holytag.fr/batchCampagne

# Ou via CLI
php admin/secure/control/batchCampagne.php
```

#### 3. Résultats
- **Base de données** : Codes créés avec miniURLs associées
- **CSV** : Listes pour import/export
- **PNG** : QR codes prêts pour impression
- **InDesign** : Chemins formatés pour PAO

### Script d'import complémentaire

#### import.php - Mapping avec données externes
```php
// Configuration similaire
$id_campagne = 951;
$type = 'pdf';  // ou 'miniurl'
```

#### Upload CSV via API
```bash
# Import de mapping personnalisé
curl -k -F "csv=@./holytag-campagne-951-mapping.csv" \
     https://admin.holytag.fr/import
```

### Structure des données générées

#### Format CSV principal
```csv
id_code,miniurl
12345,https://url.holytag.fr/12345
12346,https://url.holytag.fr/12346
```

#### Format InDesign
```csv
@qrcode
\\qrcodes-886\\code-12345.png
\\qrcodes-886\\code-12346.png
```

#### Contenu JSON en base
```json
{
    "url": "https://destination.com/",
    "miniurl": "https://url.holytag.fr/12345"
}
```

### Workflow complet d'utilisation

#### Phase 1 : Préparation administrative
1. **Créer client et campagne** via interface admin
2. **Définir nb_codes** selon besoin impression
3. **Configurer le script** avec ID campagne et URL

#### Phase 2 : Génération initiale
1. **Modifier batchCampagne.php** avec les paramètres
2. **Exécuter le script** via navigateur
3. **Vérifier les sorties** : CSV + QR codes générés

#### Phase 3 : Intégration production
1. **Utiliser les PNG** pour impression physique
2. **Importer les CSV** dans outils PAO (InDesign)
3. **Tester miniURLs** générées

#### Phase 4 : Suivi post-génération
1. **Statistiques** via dashboard stats
2. **Modifications** si nécessaire via admin
3. **Régénération partielle** possible

### Points d'attention

#### Sécurité
- **Pas d'authentification** sur le script (secure() commenté)
- **Variables hard-codées** à modifier manuellement
- **Accès direct** possible via URL

#### Performance
- **Service QR externe** : Appels à qr.lca.fr en production
- **Génération séquentielle** : Pas de parallélisation
- **Fichiers locaux** : Stockage dans /out/ uniquement

#### Maintenance
- **Double base** : Synchronisation admin_codes + url requise
- **Chemins InDesign** : Format Windows avec antislash
- **Pas de rollback** : Suppression manuelle si erreur

## 12. API et intégrations

### Service URL
- **Endpoint** : `https://url.holytag.fr/`
- **Fonction** : Résolution et redirection d'URLs courtes
- **Format** : url.holytag.fr/[miniurl] → destination

### Service Stats
- **Authentification** : Session PHP sécurisée
- **PayPal** : Intégration pour packs payants
- **API** : Endpoints pour données statistiques

### Configuration API
```php
// Services HolyTag
'urls' => array(
    'qr' => 'https://qr.holytag.fr/',
    'url' => 'https://url.holytag.fr/',
    'stats' => 'https://stats.holytag.fr/'
)

// Service externe (classe QR)
'external' => array(
    'qr_lca' => 'http://qr.lca.fr/',
    'auth' => 'webmaster:ChrAle09lca'
)
```

## 13. Points d'attention et améliorations

### Sécurité
- **Credentials** : Mots de passe en clair dans fichiers config
- **HTTPS** : Migration complète vers TLS recommandée
- **Validation** : Renforcement des contrôles d'entrée

### Performance
- **Cache** : Mise en place cache Redis/Memcached
- **CDN** : Distribution des assets statiques
- **Optimisation** : Index base de données et requêtes

### Maintenance
- **Logs** : Système de logging centralisé
- **Monitoring** : Alertes automatiques sur erreurs
- **Sauvegarde** : Automatisation backup bases et fichiers

### Code
- **PHP** : Migration vers version récente
- **Tests** : Couverture automatisée
- **Documentation** : API formelle et guides utilisateur

---

## 14. Ressources

### Fichiers de configuration clés
- `*/secure/global.ini` : Configuration par service
- `app/script.php` : Logique de validation codes
- `qr/index.php` : Service génération QR
- `admin/secure/control/treeview.php` : API admin

### Patterns de développement
- **MVC** : Contrôleurs/vues séparés via NOOP
- **Configuration** : Centralisée avec héritage
- **Routing** : Automatique basé sur arborescence
- **Sessions** : Partagées entre services

### Points critiques
- **Framework NOOP** : Custom, documentation interne requise
- **Multi-base** : Architecture distribuée à maintenir
- **Legacy** : Code nécessitant modernisation progressive
- **Sécurité** : Credentials hard-codés à sécuriser
- **Dépendance externe** : Service qr.lca.fr critique pour la génération QR en production
- **Architecture hybride** : Maintenance de deux services QR (local + externe)

## Tips maintenance

### Code bugué sur interface client (pas de possibilité de modifier le fichier cible)

Il peut arriver qu'un client fasse une erreur de manip et bloque son code (impossible de modifier le contenu cible car colonne contenu vide). 

Dans ce cas, voir en BDD (on a l'ID du code en attribut "data-id" sur le LI de la partie admin).
La colonne "type" : **pdf** (fichier uploadé sur holytag) / **miniurl** (URL cible de id_miniurl)

``1e6g2_holytag_db.admin_code.id_miniurl = 1e6g2_holytag_url.url.code``

Pour ces 2 types, le QR code est la concaténétion de "url.holytag.fr/" suivi de l'ID miniurl. **Il ne doit pas bouger**.

Exemple de code fonctionnel :
```sql
 `admin_code` (`id_code`, `id_campagne`, `creation`, `libelle`, `type`, `contenu`, `id_miniurl`, `ecc`, `size`, `cle`) VALUES
(13206, 1485, '2025-01-14 11:35:39', 'qr lounge', 'pdf', '{"url":"https:\/\/holytag.fr\/pdf\/20250912\/065738_Menu Marceau A4 WKEND minimum.pdf","miniurl":"https:\/\/url.holytag.fr\/13013"}', 13013, '', 0, '');
```
Exemple d'URL correspondant :
```sql
 `url` (`code`, `creation`, `url`) VALUES
(13013, '2025-01-14 11:35:39', 'https://holytag.fr/pdf/20250912/065738_Menu Marceau A4 WKEND minimum.pdf');
```

Si admin_code.contenu est vide, on peut le faire à l'envers à partir de url.url. Si la cible est un fichier sur holytag.fr, on est sur un type "pdf". Si c'est une URL externe, on est sur un "miniurl". Et le url.code = admin_code.id_miniurl. La structure du contenu est en JSON pour ces 2 types.


---
*Documentation générée automatiquement - Projet HolyTag*
</markdown>