Documentation technique

Stack technique

Structure des fichiers

Flux de données

/* Flux principal */

NL API (nationalleague.ch)
    │  GET /api/nl/games|players|teams|ranking-q
    ▼
server.js (proxy Express)
    │  proxifie + cache en mémoire
    ▼
app.js (frontend)
    │  normalise, affiche dans l'UI
    │  opérateur édite / sélectionne
    │  ─── POST /api/export/
 ──▶  server.js
    │                                          │  writeJSON(configuredPath)
    │                                          ▼
    │                                     kDrive (fichier JSON)
    │                                          │
    │                                          ▼
    │                                     XPression (DataLink polling)

/* Persistance locale */

app.js ─── POST /api/store ──▶ server.js ──▶ data/store.json
app.js ─── POST /api/config/settings ──▶ config/settings.json
    

Proxy API National League

Le serveur proxifie les 4 endpoints NL car l'API SIHF ne supporte pas CORS en direct. Les URLs de base :

NL_BASE     = 'https://nationalleague.ch/api'
NL_BASE_WWW = 'https://www.nationalleague.ch/api'
    

État client (state)

L'objet state global dans app.js est la source de vérité du frontend :

const state = {
  date: '2026-03-07',         // date courante (ISO)
  store: {                        // persisté dans data/store.json
    guests:           [],         // invités Studio
    guestSlots:       ['','',''], // 3 slots envoi Studio
    commentators:     [],
    commentatorSlots: ['',''],    // 2 slots envoi Commentateur
    createdPlayers:   [],
    crosspromos:      [],
    playoffSeries:    [],
    program:          { date:'', entries:[] },
    tabsComments:     {},         // { "fichier.png": "note" }
    sponsorsComments: {},
    lastSelectedDate: ''
  },
  standings:      [],  // calculé depuis /api/nl/teams + Q xml
  todaysGames:    [],  // calculé depuis rawGames pour state.date
  images:         [],  // depuis /api/images/list
  sponsors:       [],  // depuis /api/sponsors/list
  rawGames:       [],  // brut API matchs
  rawPlayers:     [],  // brut API joueurs
  teamsMapping:   [],  // depuis /api/config/teams
  settings:       {},  // depuis /api/config/settings
  standingsManual: false,
  scheduleManual:  false
};
    

Initialisation serveur

const app  = require('express')();
app.use(cors());
app.use(express.json({ limit: '30mb' })); // 30mb pour les PNG base64
app.use(express.static('./public'));      // sert index.html + assets

// Chemins internes (toujours relatifs au dossier du projet)
const CONFIG_DIR = path.join(__dirname, 'config');
const DATA_DIR   = path.join(__dirname, 'data');
const STORE_PATH = path.join(DATA_DIR, 'store.json');

// resolvePath : chemin absolu si absolu, sinon relatif au projet
function resolvePath(p) {
  return path.isAbsolute(p) ? p : path.join(__dirname, p);
}
    

Les fichiers de config et les JSON d'export peuvent être soit relatifs (dans le dossier du projet) soit absolus (ex: /Users/…/kDrive/…). resolvePath() gère les deux cas.

Référence API complète

Proxy NL

Configuration

Exports JSON Xpression

Images TABS & Sponsors

Schémas JSON exportés

nl_standings.json

{
  "date": "07.03.2026",
  "teams": [
    { "rank":1, "team":"Zurich", "played":50, "diff":45, "points":98, "q":1 },
    …
  ]
}
    

Le champ q indique la qualification : 1=qualifié playoff, 0=neutre, -1=relégation/playout. La liste contient toujours 14 équipes.

nl_schedule.json

{
  "date": "07.03.2026",
  "games": [       // toujours 7 entrées minimum (vides si moins de matchs)
    { "match":"Bienne – Zurich", "home":"Bienne", "away":"Zurich",
      "score":"3:2", "overtime":"" },
    { "match":"", "home":"", "away":"", "score":"", "overtime":"" }, …
  ]
}
    

nl_lowerthird_studio.json

{
  "type": "studio",
  "items": [
    { "name": "Roland Guex", "role": "Présentateur" },
    { "name": "Jessica Dafflon", "role": "Présentatrice" }
  ]
}
    

nl_crosspromo.json

{
  "label": "Quart de finale",
  "homeTeam": "Lausanne", "awayTeam": "Zoug",
  "homeShort": "LHC",     // "empty" si hasPhoto=0
  "awayShort": "EVZ",     // "empty" si hasPhoto=0
  "line1": "Quart de finale",
  "line2": "Lausanne - Zoug",
  "line3": "Vendredi 7 mars à 19h25 sur MySports UN",
  "hasPhoto": 1,   // 0 ou 1
  "freeTV": 0      // 0 ou 1
}
    

nl_tabs.json / nl_sponsors.json

{
  "updatedAt": "2026-03-07T19:25:00.000Z",
  "filename": "classement_semaine_12.png",
  "comment": "Classement après la semaine 12"  // peut être ""
}
    

Démarrage client

// app.js — point d'entrée (DOMContentLoaded)
async function init() {
  loadStore();           // GET /api/store → state.store
  loadConfig();          // GET /api/config/teams + settings + channels
  setupDateNav();        // boutons ← →, affiche label de date
  await loadGames();      // GET /api/nl/games → state.rawGames → todaysGames
  await loadStandingsAPI();
  await loadPlayersAPI();
  // bind tous les onglets
  bindStandings(); bindSchedule(); bindLowerthirdStudio();
  bindLowerthirdCommentator(); bindLowerthirdPlayer();
  bindCrosspromo(); bindImages(); bindSponsors();
  bindProgram(); bindPlayoff(); bindStudio(); bindSettings();
}
    

Modules JS (app.js)

app.js est un fichier monolithique structuré en sections. Chaque section = un onglet :

Auto-save & store

// Sauvegarde automatique après chaque modification UI
async function saveStore() {
  await postJSON('/api/store', state.store);
  // flashAutosave() affiche le point vert en haut à droite
}

// server.js — écriture atomique
function writeJSON(filePath, data) {
  fs.mkdirSync(path.dirname(filePath), { recursive: true });
  fs.writeFileSync(filePath, JSON.stringify(data, null, 2));
}
    

🔧 Testeur d'API

Ces outils interrogent le serveur en direct. Ils ne fonctionnent que si le serveur tourne (http://localhost:3001).

🔧 Inspecteur store.json

Lit et permet d'inspecter ou modifier le store directement.

🔧 Logs & monitoring

Surveiller les requêtes en temps réel

Dans le Terminal où tourne node server.js, ajoute un middleware de logging. Ouvre server.js et ajoute juste après app.use(cors()) :

// Middleware de logging — à retirer en production
app.use((req, res, next) => {
  console.log(`[${new Date().toISOString()}] ${req.method} ${req.path}`);
  if (req.method === 'POST' && req.body) {
    console.log('  Body keys:', Object.keys(req.body));
  }
  next();
});
    

Inspecter les fichiers JSON en direct

Pour surveiller un fichier JSON en temps réel depuis le Terminal :

# Surveille nl_crosspromo.json et affiche à chaque modification
fswatch ~/kDrive/.../DATA/nl_crosspromo.json | \
  xargs -I{} cat ~/kDrive/.../DATA/nl_crosspromo.json

# Ou plus simple avec watch (brew install watch)
watch -n 1 cat ~/kDrive/.../DATA/nl_tabs.json
    

Vérifier les fichiers de config

# Valider que les JSON ne sont pas corrompus
node -e "require('./config/settings.json'); console.log('settings.json OK')"
node -e "require('./data/store.json'); console.log('store.json OK')"
node -e "require('./config/teams.json'); console.log('teams.json OK')"
    

Tester le serveur depuis le Terminal

# Vérifier que le serveur répond
curl -s http://localhost:3001/ | head -5

# Lire le store
curl -s http://localhost:3001/api/store | python3 -m json.tool | head -30

# Forcer un export classement
curl -s -X POST http://localhost:3001/api/export/standings \
  -H "Content-Type: application/json" \
  -d '{"date":"07.03.2026","teams":[]}' | python3 -m json.tool
    

🔧 Erreurs communes & résolutions

cd "Hockey Builder"
npm install

node -e "JSON.parse(require('fs').readFileSync('./data/store.json','utf-8'))"
# Si erreur → fichier corrompu, supprime-le ou remplace par {}

curl -I https://nationalleague.ch/api/v1/games
curl -I https://www.nationalleague.ch/api/v1/players

// server.js — validation (lignes ~460-490)
const PNG_SIG = Buffer.from([0x89,0x50,0x4E,0x47,...]);
const width  = buffer.readUInt32BE(16); // doit être 1920
const height = buffer.readUInt32BE(20); // doit être 1080
        

sips -z 1080 1920 mon_image.png

# Trouver quel processus utilise le port 3001
lsof -ti:3001

# Tuer le processus
kill $(lsof -ti:3001)

# Ou changer le port dans config/settings.json
{ ..., "port": 3002 }