Table des matières

Documentation Technique - Projet HolyBus

Documentation Technique - Projet HolyBus

1. Vue d'ensemble du projet

Objectifs et problématiques adressées

Le projet HolyBus est une plateforme de gestion multi-services déployée sur une architecture de sous-domaines. Chaque dossier représente un service indépendant accessible via un sous-domaine spécifique, permettant une organisation modulaire et une maintenance simplifiée.

Contexte métier et utilisateurs cibles

Clients : Interface utilisateur principale pour les services de transport
Administration : Back-office pour la gestion des services
Services mobiles : Applications dédiées aux différents partenaires de transport (Touriscar, Artis, Evolity, CCVA, Procars, Hegobus)
Statistiques : Système de collecte et analyse de données
URL : Service de gestion et redirection d'URLs

Architecture technique globale

holybus/
├── main/           # Site principal (domaine racine)
├── www/            # Service web principal
├── client/         # Interface client
├── admin/          # Back-office administrateur
├── mobile/         # Services mobiles par partenaire
│   ├── touriscar/
│   ├── artis/
│   ├── evolity/
│   ├── ccva/
│   ├── procars/
│   └── hegobus/
├── stats/          # Service de statistiques
└── url/            # Service de gestion d'URLs

2. Stack technologique

Technologies principales

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

Bibliothèques et frameworks

NOOP Framework : Framework PHP custom (version 2.0.1) avec architecture MVC
jQuery 2.1.3 : Bibliothèque JavaScript principale
jQuery UI 1.11.2 : Interface utilisateur avancée
D3.js 3.5.3 : Visualisation de données
C3.js 0.4.22 : Graphiques basés sur D3
Modernizr : Détection des fonctionnalités navigateur
TinyColorPicker : Sélecteur de couleurs

Infrastructure

Hébergement : Infomaniak (154clm.myd.infomaniak.com)
Base de données : MySQL (154clm_admin, 154clm_url)
Utilisateur MySQL : 154clm_holybus
Environnement de développement : Local (serveurweb, 192.168.2.200)

3. Framework NOOP - Architecture personnalisée

Caractéristiques principales

Version : NOOP 2.0.1 (MIT License, Dimitri Avenel)
Architecture : MVC avec routing automatique
Configuration : Système de configuration centralisé
Gestion des erreurs : Handler d'exceptions personnalisé
Cache : Système de cache intégré pour les vues
Base de données : Abstraction PDO multi-base

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::start();

4. Structure du code

Organisation des services

Service Client ()

Point d'entrée : index.php
Configuration : Session management, configuration base de données
Bibliothèques : lib/ (jQuery, CSS, ressources visuelles)
Sécurité : secure/ (contrôleurs, vues, fonctions)

Service Admin ()

Point d'entrée : index.php
Configuration : secure/global.ini
Gestion : Interface d'administration complète

Services Mobiles ()

Chaque partenaire possède sa propre instance :

Structure identique : index.php, secure/, lib/, img/, perso/
Partenaires : touriscar, artis, evolity, ccva, procars, hegobus
Documentation : mobile/doc/ avec assets CSS/JS

Conventions de nommage

Fichiers de configuration : .ini, .htaccess, .php-ini
Contrôleurs : secure/control/
Vues : secure/view/
Ressources : lib/, img/
Personnalisation : perso/

5. Configuration et environnements

Configuration base de données (Production)

[pdo]
db = "mysql,host=154clm.myd.infomaniak.com;dbname=154clm_admin,154clm_holybus,89hG?#56m-wRF"
db2 = "mysql,host=154clm.myd.infomaniak.com;dbname=154clm_url,154clm_holybus,89hG?#56m-wRF"

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'))));

Configuration par environnement

Production : Debug OFF, base Infomaniak
Développement : Debug ON, base locale

5. 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

Fonction : Gestion administrative principale
Usage : Services client, admin, mobile
Tables principales :
- admin_clients : Gestion des clients transport
- admin_campagnes : Campagnes de communication
- admin_codes : Codes QR et contenus associés
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 code -> URL longue
Processus : Redirection automatique via miniurl

Authentification MySQL

Utilisateur : 154clm_holybus
Mot de passe : 89hG?#56m-wRF
Accès : Permissions sur les deux bases de données

Flux de données inter-bases

Synchronisation automatique (mobile/cron.php)

// Processus de synchronisation des codes QR
$pdo = new PDO('154clm_admin');   // Source : clients et campagnes
$pdo2 = new PDO('154clm_url');    // Destination : URLs courtes
 
// Mapping automatique : QR Code -> URL mobile
foreach ($clients as $client) {
    // Lecture fichier QRCodes.txt du client
    // Mise à jour table url pour redirection
    // Mise à jour admin_codes avec contenu JSON
}

Configuration par service

Client/Admin : db (admin), accès données clients/campagnes
URL : db (url), dbadmin (admin) pour les références
Mobile : db (admin) pour authentification et données

Patterns d'utilisation

Service Client

// Accès base admin pour données clients
'pdo' => array('db' => '154clm_admin')

Service URL

// Double accès pour redirection et logging
'pdo' => array(
    'db' => '154clm_url',      // URLs courtes
    'dbadmin' => '154clm_admin' // Référentiel clients
)

Services Mobile

// Accès admin pour authentification partenaires
'pdo' => array('db' => '154clm_admin')

Intégrations spécifiques

Génération d'URLs mobiles

QR Code [12345] → Fichier QRCodes.txt → Base admin_codes → Base url
→ Redirection : url.holybus.fr/12345 → m.holybus.fr/client/arret/LOC

Authentification centralisée

Base admin : Référentiel utilisateurs
Sessions : Partagées entre services
Permissions : Gestion par service selon le dossier client

6. Gestion des erreurs et logging

System d'exception personnalisé

Classes : NoopException, NoopConfigException, NoopControllerException, NoopViewException
Handler : exception_callback() avec notification par email
Logging : Classe Logger pour traçabilité
Monitoring : Headers X-Benchmark pour performances

Email de notification d'erreurs

mail(
    'webmaster@domain.com',
    'Error '.$code.': '.$message,
    $stackTrace,
    'Content-type: text/html; charset=utf-8'
);

7. Sécurité

Authentification

Admin : Login/password dans global.ini
Sessions : Gestion centralisée avec timeout
API : Authentification basic pour service URL

Protection des données

Stripslashes : Nettoyage automatique des données
PDO : Requêtes préparées
Headers : Configuration sécurisée (.htaccess)

Accès aux fichiers

Dossiers secure/ : Protégés par .htaccess
Configuration : Fichiers .ini protégés
Environnement : Détection automatique dev/prod

8. Déploiement et maintenance

Structure de déploiement

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

www.holybus.fr → main/
client.holybus.fr → client/
admin.holybus.fr → admin/
touriscar.holybus.fr → mobile/touriscar/
Etc.

Maintenance

Logs : Système de logging centralisé
Monitoring : Headers de performance automatiques
Cache : Invalidation manuelle via ?no-cache

9. Commande batchCampagne.php - Génération de campagnes QR

Vue d'ensemble

Le script admin/secure/control/batchCampagne.php est l'outil principal pour générer massivement des campagnes de codes QR pour les clients transport. Il automatise la création de codes QR, miniURLs, et fichiers de production.

Fonctionnalités principales

1. Génération automatique de codes

// Configuration par campagne
$id_campagne = 271;
$societe = 'evolity';
$lot = '11cm';
$destination_url = 'https://evolity.holybus.fr/';

2. Processus de génération

Récupération de la campagne : Lecture des paramètres depuis admin_campagnes
Vérification des codes existants : Calcul du nombre de codes manquants
Création des miniURLs : Insertion dans la base 154clm_url
Génération des codes QR : Création des enregistrements admin_codes
Production des fichiers : CSV, QR Codes PNG, mapping InDesign

3. Sorties générées

Fichiers CSV

holybus-campagne-271_11cm.csv        # Liste des codes générés
holybus-campagne-271_11cm-indesign.csv  # Chemins pour InDesign

QR Codes PNG

out/qrcodes-271_11cm/
├── code-12345.png
├── code-12346.png
└── ...

Structure des données

{
    "url": "https://evolity.holybus.fr/",
    "miniurl": "https://url.holybus.fr/12345"
}

Script d'import (import.php)

Utilisation avec CSV

# Upload d'un mapping ID miniURL <-> ID SIRI
curl -k -F "csv=@./holybus-campagne-269-idSiri.csv" \
     https://admin.holytag.org/import

Note : Pas d'authentification requise pour l'endpoint import

Processus d'import

Lecture du CSV : [id_code, siri_code]
Génération d'URLs : https://m.holybus.fr/societe/arret/SIRI_CODE
Mise à jour des bases : admin_codes + url
Génération QR : Codes PNG individuels
Export InDesign : Chemins macOS pour intégration PAO

Workflow complet - Ajout d'un client et campagne SIRI

cf. https://app.asana.com/1/1530398085277/project/1205755380967232/task/1209326056812982?focus=true

Phase 1 : Préparation administrative

Ajouter le client dans l'interface admin
Créer une campagne avec un nombre maximal de codes
Configuration des scripts :
- Modifier admin/secure/control/batchCampagne.php
- Modifier admin/secure/control/import.php
- Paramètres requis :
  - Nom du client (pour URL cible - nom du projet)
  - ID de la campagne

Phase 2 : Génération initiale des codes

# Accès navigateur pour générer codes + QR Codes + liste associations
https://admin.holytag.org/batchCampagne

Sorties générées :

Codes en base de données
QR Codes PNG individuels
Liste des associations code = miniURL

Phase 3 : Mapping des codes SIRI

Créer un fichier CSV : "ID miniURL" + "ID SIRI"
Format : holybus-campagne-[ID]-idSiri.csv

Import définitif :

curl -k -F "csv=@./holybus-campagne-269-idSiri.csv" \
  https://admin.holytag.org/import

Phase 4 : Résultat final

Base de données : Mapping complet codes QR ↔ arrêts SIRI
Redirection : url.holybus.fr/12345 → m.holybus.fr/client/arret/SIRI_CODE
Assets : QR Codes PNG + CSV InDesign pour impression

Intégration système QR

Service de génération QR

class QR {
    const URL = 'http://qr.lca.fr/';
    const AUTH = 'webmaster:ChrAle09lca';
 
    static public function generate($data) {
        // Appel API externe pour génération PNG
        // Paramètres : size=4, ecc=L, margin=2
    }
}

Chaîne de redirection

QR Code physique → url.holybus.fr/12345 → m.holybus.fr/client/arret/LOC

Points d'attention

Sécurité

Credentials hard-codés dans les scripts
Accès API QR externe non sécurisé
Upload CSV sans validation stricte

Maintenance

Chemins InDesign hard-codés pour macOS
Dépendance API externe qr.lca.fr
Pas de système de rollback

Performance

usleep(300) pour éviter la surcharge API
Génération séquentielle (non parallélisée)
Stockage fichiers local uniquement

10. API et intégrations

Service URL

Endpoint : https://url.holybus.fr/
Authentification : Basic Auth (webmaster:password)
Fonction : Gestion et redirection d'URLs courtes

Configuration API

'api' => array(
    'url' => 'https://url.holybus.fr/',
    'url-auth' => 'webmaster:ChrAle09lca'
)

10. Ressources et contacts

Fichiers de configuration clés

admin/secure/global.ini : Configuration principale
client/index.php : Configuration client
*/noop.php : Framework core

Patterns de développement

MVC : Contrôleurs dans secure/control/, vues dans secure/view/
Configuration : Centralisée avec héritage
Cache : MD5 hash des paramètres + timestamp
Routing : Automatique basé sur l'arborescence

Points d'attention

Credentials : Présents en dur dans les fichiers de configuration
Framework : NOOP est un framework custom, documentation interne nécessaire
Multi-tenant : Architecture distribuée sur sous-domaines
Legacy : Code datant de 2010-2014, nécessite migration progressive

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

Tips & parachutes

Si jamais les URLs cibles sont identiques et pointent sur l'accueil du site client, c'est qu'il y a eu un manquement dans l'utilisation du batchCampagne. Il convient donc de regénérer les URLs en prenant le code de l'arrêt indiqué au début du libellé de admin_codes. Ce travail peut se faire en masse (cf. chat Holybus - mise à jour en masse des URLs cibles) via le SQL suivant (à adapter bien-sûr) :

UPDATE 154clm_admin.admin_codes AS ac
JOIN 154clm_url.url AS u
  ON u.code = ac.id_code
/* calcule CODEARRET = premiers caractères du libellé avant "-" */
JOIN (
  SELECT id_code,
         TRIM(SUBSTRING_INDEX(libelle, '-', 1)) AS code_arret
  FROM 154clm_admin.admin_codes
) AS x
  ON x.id_code = ac.id_code
SET
  /* nouvelle URL normalisée */
  u.url = CONCAT('https://evolity.holybus.fr/arret/', x.code_arret),
 
  /* mise à jour du JSON si valide : contenu.url := nouvelle URL */
  ac.contenu = CASE
                 WHEN JSON_VALID(ac.contenu)
                   THEN JSON_SET(ac.contenu, '$.url',
                                 CONCAT('https://evolity.holybus.fr/arret/', x.code_arret))
                 ELSE ac.contenu
               END
WHERE u.url LIKE '%evolity%'
  AND ac.libelle NOT LIKE 'Campagne Pack%'
  AND x.code_arret <> '';