Guida all'integrazione della documentazione

Panoramica

Il sito di documentazione workspace fornisce un manifest leggibile dalla macchina (hub-links.json) che associa le schermate della dashboard dell’Hub alle pagine di documentazione pertinenti. Questo consente al frontend dell’Hub di visualizzare link di aiuto contestuali direttamente nell’interfaccia utente della dashboard.

Come funziona

Il manifest /hub-links.json è un file JSON statico servito dal sito di documentazione. Ogni voce associa un identificatore di schermata dell’Hub a un elenco di link di documentazione pertinenti con titoli e descrizioni.

Struttura del manifest

Il manifest segue questo schema:

{
  "$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"
        }
      ]
    }
  }
}

ID schermata disponibili

ID schermata	Schermata Hub	Link
organizations	Gestione organizzazioni	Introduzione HUB, primi passi, mappatura risorse
tss-list	Elenco TSS (Germania)	Panoramica Germania, nuovi clienti, avvio rapido
clients	Gestione client	Dettagli tecnici, SIGN DE API
transactions	Visualizzatore transazioni	Gestione errori, codici di errore
exports	Gestione esportazioni	Introduzione DSFinV-K, manuale dashboard
api-keys	Gestione chiavi API	Avvio rapido, passaggio a LIVE
cash-registers	Registratori di cassa (Austria)	Panoramica Austria, avvio rapido, SIGN AT API
signers	Firmatari (Spagna)	Panoramica Spagna, avvio rapido

Integrazione nell’Hub

Utilizzo del componente HubNavCard

Il componente React HubNavCard renderizza i link di documentazione per una schermata specifica. Recupera hub-links.json in fase di esecuzione e visualizza i link corrispondenti con stati hover e descrizioni.

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

// Nella barra laterale dell'Hub o nel pannello di aiuto:
<HubNavCard hubScreen="tss-list" />

Esempi live

Ecco la scheda di gestione TSS:

E la scheda delle chiavi API:

Recupero diretto (senza componente)

Se si preferisce recuperare il manifest direttamente nel frontend dell’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;
}

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

Aggiungere nuove mappature di schermate

Per aggiungere link di documentazione per una nuova schermata dell’Hub:

1. Modifica public/hub-links.json nel repository dei docs workspace
2. Aggiungi una nuova voce sotto screens con un ID schermata univoco
3. Includi title, description e un array di links
4. Ogni link necessita di title, url (percorso relativo) e description
5. Invia una PR — il manifest viene distribuito automaticamente con il sito di documentazione

📘Formato URL

Tutti i valori url nel manifest sono percorsi relativi (ad esempio, /hub/introduction/). Quando si integra nell’Hub, anteporre l’URL base dei docs (https://workspace.fiskaly.com).

💡Test in locale

Esegui il server di sviluppo dei docs con npm run dev e accedi a http://localhost:4321/hub-links.json per testare le modifiche al manifest prima di inviare una PR.