Guide d'intégration de la documentation

Vue d’ensemble

Le site de documentation workspace fournit un manifeste lisible par machine (hub-links.json) qui associe les écrans du tableau de bord du Hub aux pages de documentation pertinentes. Cela permet au frontend du Hub d’afficher des liens d’aide contextuels directement dans l’interface utilisateur du tableau de bord.

Fonctionnement

Le manifeste /hub-links.json est un fichier JSON statique servi depuis le site de documentation. Chaque entrée associe un identifiant d’écran du Hub à une liste de liens de documentation pertinents avec des titres et des descriptions.

Structure du manifeste

Le manifeste suit ce schéma :

{
  "$schema": "hub-links-schema",
  "version": "1.0.0",
  "screens": {
    "<screen-id>": {
      "title": "Screen Title",
      "description": "What this screen does",
      "links": [
        {
          "title": "Link Title",
          "url": "/path/to/docs-page/",
          "description": "Brief description of the linked page"
        }
      ]
    }
  }
}

IDs d’écran disponibles

ID d’écran	Écran Hub	Liens
organizations	Gestion des organisations	Introduction HUB, premiers pas, mappage des ressources
tss-list	Liste TSS (Allemagne)	Vue d’ensemble Allemagne, nouveaux clients, démarrage rapide
clients	Gestion des clients	Détails techniques, SIGN DE API
transactions	Visualiseur de transactions	Gestion des erreurs, codes d’erreur
exports	Gestion des exportations	Introduction DSFinV-K, manuel du tableau de bord
api-keys	Gestion des API Keys	Démarrage rapide, passer en mode LIVE
cash-registers	Caisses enregistreuses (Autriche)	Vue d’ensemble Autriche, démarrage rapide, SIGN AT API
signers	Signataires (Espagne)	Vue d’ensemble Espagne, démarrage rapide

Intégration dans le Hub

Utilisation du composant HubNavCard

Le composant React HubNavCard affiche les liens de documentation pour un écran donné. Il récupère hub-links.json à l’exécution et affiche les liens correspondants avec des états de survol et des descriptions.

import { HubNavCard } from "@workspace/docs/components";

// Dans votre barre latérale du Hub ou panneau d'aide :
<HubNavCard hubScreen="tss-list" />

Exemples en direct

Voici la carte de gestion TSS :

Et la carte des API Keys :

Récupération directe (sans composant)

Si vous préférez récupérer le manifeste directement dans le frontend du Hub :

const BASE_URL = "https://workspace.fiskaly.com";

async function getHubLinks(screenId: string) {
  const res = await fetch(`${BASE_URL}/hub-links.json`);
  const manifest = await res.json();
  return manifest.screens[screenId] || null;
}

// Utilisation
const links = await getHubLinks("tss-list");
if (links) {
  links.links.forEach((link) => {
    console.log(`${link.title}: ${BASE_URL}${link.url}`);
  });
}

Ajouter de nouveaux mappages d’écran

Pour ajouter des liens de documentation pour un nouvel écran du Hub :

1. Modifiez public/hub-links.json dans le dépôt de docs workspace
2. Ajoutez une nouvelle entrée sous screens avec un ID d’écran unique
3. Incluez title, description et un tableau de links
4. Chaque lien a besoin de title, url (chemin relatif) et description
5. Soumettez une PR — le manifeste est déployé automatiquement avec le site de documentation

📘Format d'URL

Toutes les valeurs url dans le manifeste sont des chemins relatifs (par exemple, /hub/introduction/). Lors de l’intégration dans le Hub, préfixez l’URL de base des docs (https://workspace.fiskaly.com).

💡Test en local

Lancez le serveur de développement des docs avec npm run dev et accédez à http://localhost:4321/hub-links.json pour tester vos modifications du manifeste avant de soumettre une PR.