Ceci est une ancienne révision du document !

Table des matières

Documentation Technique - Projet HolyTag

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

// 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 ()

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 ()

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 ()

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 ()

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 ()

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)

[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

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 :

- 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

- 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

Admin : Création campagne dans 1e6g2_holytag_db
Génération : Insertion codes dans admin_codes
URLs courtes : Création miniURLs dans 1e6g2_holytag_url
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

// 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

// 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

[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 ()

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 ()

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

// 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

# 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

// 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

Interface Admin : Création client et campagne
Paramètres : Nombre de codes, validité, gabarit
Génération : Création automatique des codes uniques

Phase 2 : Génération des codes

Codes Holykey : Génération des clés d'accès uniques
MiniURLs : Création des URLs courtes associées
QR Codes : Génération des visuels PNG/SVG
Base : Insertion dans admin_codes

Phase 3 : Déploiement

Publication : Codes disponibles via interface App
Redirection : url.holytag.fr/[code] → destination finale
Statistiques : Tracking des accès et conversions

Phase 4 : Suivi

Dashboard Stats : Métriques de performance
Rapports : Exports CSV et graphiques
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

// 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

// 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

// 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

// 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

# Modifier les variables dans batchCampagne.php
$id_campagne = 886;
$destination_url = 'https://client.holytag.fr/';

2. Exécution

# 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

// Configuration similaire
$id_campagne = 951;
$type = 'pdf';  // ou 'miniurl'

Upload CSV via API

# 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

id_code,miniurl
12345,https://url.holytag.fr/12345
12346,https://url.holytag.fr/12346

Format InDesign

@qrcode
\\qrcodes-886\\code-12345.png
\\qrcodes-886\\code-12346.png

Contenu JSON en base

{
    "url": "https://destination.com/",
    "miniurl": "https://url.holytag.fr/12345"
}

Workflow complet d'utilisation

Phase 1 : Préparation administrative

Créer client et campagne via interface admin
Définir nb_codes selon besoin impression
Configurer le script avec ID campagne et URL

Phase 2 : Génération initiale

Modifier batchCampagne.php avec les paramètres
Exécuter le script via navigateur
Vérifier les sorties : CSV + QR codes générés

Phase 3 : Intégration production

Utiliser les PNG pour impression physique
Importer les CSV dans outils PAO (InDesign)
Tester miniURLs générées

Phase 4 : Suivi post-génération

Statistiques via dashboard stats
Modifications si nécessaire via admin
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

// 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 et contacts

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)

Documentation générée automatiquement - Projet HolyTag