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

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 :

 `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 :

 `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