Table des matières

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

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

Bibliothèques et frameworks

Infrastructure

3. Framework NOOP - Architecture personnalisée

Caractéristiques principales

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

Service Admin ()

Service QR ()

Service Stats ()

Service URL ()

Conventions de nommage

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

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

- Base de redirection

Authentification MySQL

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

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é

Notifications d'erreurs

8. Sécurité

Authentification

Protection des données

Accès aux fichiers

9. Déploiement et maintenance

Structure de déploiement

Chaque service est déployé sur son sous-domaine :

Maintenance

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

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

  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

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

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

  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é

Performance

Maintenance

12. API et intégrations

Service URL

Service Stats

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é

Performance

Maintenance

Code

14. Ressources

Fichiers de configuration clés

Patterns de développement

Points critiques

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