PRD — Documentazione Askme Desk

Documento di riferimento per allineare la struttura della documentazione Desk a quella di Sign (modulo più avanzato). Questo file non verrà pubblicato sul sito; serve come guida operativa.

1. Obiettivo

Portare la documentazione di Askme Desk allo stesso livello di completezza e struttura di Askme Sign, adattando i contenuti al dominio specifico del service management e ticketing.

2. Struttura target (modello Sign)

La documentazione di Sign è organizzata in due macro-sezioni:

2.1 Documentazione (manuale utente)

File Sign	Contenuto	Equivalente Desk
`manual/features.md`	Manuale operativo completo dell'applicativo, con screenshot e flussi step-by-step. Sezioni: Accesso, Homepage, Profilo, Pratiche e Documenti, Creazione pratica, Firma veloce, Processo di firma, Archivio, Statistiche, Tipologie di processo, Amministrazione	`manual/features.md` (vuoto)
`manual/roles.md`	Tabella completa di tutti i ruoli applicativi con codice, descrizione e funzionalità abilitate	`manual/roles.md` (da creare)

2.2 API Reference

File Sign	Contenuto	Equivalente Desk
`api/overview.md`	Panoramica API, base URL, casi d'uso principali con request/response completi, codici stato, best practices, flusso tipico	`api/overview.md` (esistente, da verificare)
`api/authentication.md`	Autenticazione Keycloak, esempi cURL/Python/JS, risposta, uso token, JWKs, errori comuni	`api/authentication.md` (esistente, già allineato a Sign)
`api/endpoints.md`	Endpoint CRUD dettagliati con parametri, body, response, gestione errori, rate limiting	`api/endpoints.md` (esistente, da verificare)
`api/examples.md`	Esempi completi in Python e JS/Node.js, troubleshooting, best practices	`api/examples.md` (esistente, da verificare)
`api/webhooks.md`	Configurazione webhook, payload, autenticazione (API Key, Basic, OAuth), esempi implementazione	`api/webhooks.md` (da creare)

3. Gap analysis — Stato attuale Desk

Ultimo aggiornamento: 2026-03-05

File esistenti e stato

File	Stato	Note
`intro.md`	✅ Completo	Allineato allo stile Sign con vantaggi, moduli applicativi e card di navigazione
`manual/features.md`	✅ Completo	Manuale operativo completo (~609 righe). Copre: Accesso, Interfaccia Principale, Welcome Page, Liste di Ricerca, Operatività I e II Livello, Agenda, Problem Management, Knowledge Base, Statistiche, CTI, Widget Chat, Portale Assistenza, Amministrazione
`manual/roles.md`	✅ Completo	Creato con 4 profili predefiniti e ~100+ ruoli organizzati per categoria (comuni, I livello, II livello, monitor, contatti, amministrazione)
`manual/getting-started.md`	✅ Completo	Riscritto con focus Desk: 5 passi (accesso, interfaccia, creazione richiesta, gestione, chiusura) con card di navigazione
`manual/configuration.md`	✅ Eliminato	Configurazione inclusa nella sezione "Amministrazione" di `features.md`, come in Sign
`api/overview.md`	✅ Completo	Riscritto con dati reali da Swagger. Contiene: Base URL `/rest`, risorse principali (9 gruppi), formato risposte DataTable, DomainBean, esempio cURL creazione richiesta
`api/authentication.md`	✅ Completo	Identico a Sign (stessa infra Keycloak)
`api/endpoints.md`	✅ Completo	Riscritto integralmente da Swagger (`swagger.json` v3.47). Copre: Richieste I livello (CRUD, assegnazione, presa in carico, sospensione, chiusura, commenti, operazioni massive), Ticket II livello (CRUD, avanzamento workflow, assegnazione, note interne), Work Order, Allegati (upload/download), Knowledge Base, Statistiche e SLA, Autenticazione, Agenda
`api/examples.md`	✅ Completo	Riscritto con endpoint reali. 4 esempi: DeskClient Python completo (richieste + ticket), Client JS/Node.js, monitoraggio SLA bash, importazione CSV
`api/webhooks.md`	❌ Non esiste	Da creare se Desk supporta webhook

Riepilogo avanzamento

Fase 1 (Manuale utente): ✅ COMPLETATA — Tutti i file scritti e allineati
Fase 2 (API Reference): ✅ COMPLETATA — Tutti i file riscritti con dati reali da Swagger v3.47. Resta solo webhooks.md da creare (in attesa conferma supporto webhook)
Fase 3 (Sidebar e navigazione): ✅ COMPLETATA — sidebars-desk.ts aggiornato

4. Piano di implementazione

Fase 1 — Manuale utente (`manual/`) ✅ COMPLETATA

4.1 `manual/features.md` — Manuale operativo ✅

Completato. Struttura finale implementata:

# Manuale
## Askme Desk (intro con tabella ruoli/livelli)
# ACCESSO (Login, Logout)
# INTERFACCIA PRINCIPALE (Motore di ricerca, Monitor)
# WELCOME PAGE (Monitor I e II livello)
# LISTE DI RICERCA (Filtri, Colonne, Paginazione, Selezione, Azioni)
# OPERATIVITÀ DI I LIVELLO (Creazione richiesta, Liste, Dettaglio, Ciclo di vita)
# OPERATIVITÀ DI II LIVELLO (Creazione ticket, Avanzamento, Liste, Work Order)
# AGENDA
# PROBLEM MANAGEMENT
# KNOWLEDGE BASE
# STATISTICHE E REPORTISTICA (Report predefiniti, Custom, Data Warehouse)
# BARRA TELEFONICA (CTI)
# WIDGET ASKME CHAT
# PORTALE ASSISTENZA
# AMMINISTRAZIONE (Configurazioni, Sezioni/Attributi, Workflow, Terne, KB, Ticket periodici, Data Retention)

📋 NOTA: Mancano ancora gli screenshot dell'interfaccia. Quando disponibili, integrarli nelle sezioni corrispondenti.

4.2 `manual/roles.md` — Documentazione ruoli ✅

Completato. Contiene:

4 profili predefiniti (A3_CLI, A3_OP1L, A3_OP2L, ASK3_ADM) con descrizione dei destinatari
~100+ ruoli organizzati in 6 categorie: Comuni, I Livello (Richieste), I Livello (Monitor), II Livello (Ticket), II Livello (Monitor), Contatti/Chiamate, Amministrazione

4.3 `manual/getting-started.md` — Guida rapida ✅

Completato. Struttura implementata:

Prerequisiti
Passo 1-5 (accesso, interfaccia, creazione richiesta, gestione, chiusura)
Card di navigazione verso Manuale, Ruoli e API

📋 NOTA: Mancano screenshot del processo. Quando disponibili, integrarli.

4.4 `manual/configuration.md` — Decisione ✅

Decisione presa: file eliminato. Configurazione inclusa nella sezione "Amministrazione" di features.md, come in Sign.

Fase 2 — API Reference (`api/`) ⚠️ QUASI COMPLETATA

4.5 `api/overview.md` — Panoramica API ✅

Riscritto con dati reali dallo Swagger v3.47. Struttura attuale:

Base URL /rest con nota su istanza configurabile
Tabella risorse principali (Richieste, Ticket, Work Order, Knowledge Base, Allegati, Utenti, Agenda, Statistiche, Autenticazione)
Codici di Stato HTTP reali
Formato risposte DataTable (data, message, recordsTotal, recordsFiltered)
Formato DomainBean (id, codice, nome, descrizione)
Client HTTP consigliati
Esempio rapido: cURL creazione richiesta con campi reali
Supporto, nota versione API 3.47

4.6 `api/endpoints.md` — Endpoint dettagliati ✅ COMPLETO

Riscritto integralmente dal file Swagger swagger.json (v3.47.271-SNAPSHOT, 792 endpoint totali). Documentati i seguenti gruppi:

Richieste I livello: creazione, creazione CT, elenco, liste specializzate, dettaglio, perfezionamento, modifica, assegnazione (singola/auto/massiva), presa in carico, sospensione, chiusura, riattivazione/riapertura, commenti (fornitore/cliente/CT/note interne), operazioni ausiliarie
Ticket II livello: creazione, elenco, liste specializzate, dettaglio, modifica, assegnazione, avanzamento workflow, note interne (I e II livello), operazioni ausiliarie
Work Order: creazione, avanzamento, lista, dettaglio
Allegati: upload (con flusso upload-id), download, allegati ticket, download via hash
Knowledge Base: lista, dettaglio, CRUD, utilizzo
Statistiche: richieste, ticket, SLA (presa in carico, chiusura, step, tempo residuo)
Autenticazione: userinfo, user-full-info, user-authorities
Agenda: eventi CRUD, tipi ed esiti
Gestione Errori: con nota su risposte esito*

4.7 `api/webhooks.md` — Webhook ❌ DA CREARE

Non ancora creato. Struttura prevista (modello Sign):

Concetti generali
Configurazione
Payload (struttura default + personalizzazione)
Autenticazione (API Key, Basic, OAuth)
Esempi implementazione (Node.js, Python)
Best practices

📋 CONTENUTO NECESSARIO: Confermare se Desk supporta webhook. In caso affermativo, servono: eventi disponibili, struttura payload, metodi di autenticazione supportati.

4.8 `api/examples.md` — Esempi ✅

Riscritto con endpoint reali da Swagger. 4 esempi:

Esempio 1: DeskClient Python completo — crea richiesta, dettaglio, assegnazione, presa in carico, crea ticket II livello, avanzamento workflow, chiusura
Esempio 2: DeskClient JavaScript/Node.js — equivalente dell'esempio Python
Esempio 3: Script Bash monitoraggio SLA — usa gli endpoint /statistics/sla* reali
Esempio 4: Importazione massiva richieste da CSV (Python)
Sezioni Troubleshooting e Best Practices aggiornate con errori reali (terna, esiti, upload allegati)

4.9 `sidebars-desk.ts` ✅

Aggiornato. Struttura attuale:

deskSidebar: [
  {
    type: 'category',
    label: 'Askme Desk',
    collapsed: false,
    collapsible: false,
    items: [
      { type: 'doc', id: 'intro', label: 'Introduzione' },
      {
        type: 'category',
        label: 'Documentazione',
        collapsed: false,
        items: [
          'manual/features',
          'manual/roles',
          'manual/getting-started'  // mantenuto nella sidebar
        ],
      },
      {
        type: 'category',
        label: 'API Reference',
        collapsed: false,
        items: [
          'api/overview',
          'api/authentication',
          'api/endpoints',
          'api/examples'
        ],
      }
    ]
  }
]

Nota: getting-started mantenuto nella sidebar. configuration rimosso. api/webhooks da aggiungere quando creato.

5. Riepilogo contenuti da ricevere

#	Cosa serve	Priorità	Per quale file	Stato
1	Manuale operativo Desk con screenshot (o accesso ambiente demo)	🟡 Media	`manual/features.md`	Testo completato, mancano screenshot
2	Elenco completo ruoli Desk (codice + descrizione + funzionalità)	✅ Ricevuto	`manual/roles.md`	Completato
3	Flusso di primo utilizzo con screenshot	🟡 Media	`manual/getting-started.md`	Testo completato, mancano screenshot
4	Specifica OpenAPI/Swagger Desk	✅ Ricevuto	`api/endpoints.md`, `api/overview.md`	Swagger v3.47.271 utilizzato per riscrivere tutti i file API
5	Conferma supporto webhook + dettagli	🟡 Media	`api/webhooks.md`	In attesa di conferma
6	Validazione esempi API esistenti	✅ Fatto	`api/examples.md`	Esempi riscritti con endpoint reali da Swagger
7	Decisione su `configuration.md` (separato o unito)	✅ Deciso	Struttura sidebar	Eliminato, contenuto in features.md

Azioni tecniche rimanenti (non richiedono contenuti esterni)

#	Azione	Priorità	File
A1	~~Rimuovere contenuti Chat residui da `api/overview.md`~~	✅ Fatto	`api/overview.md`
A2	~~Rimuovere endpoint messaggistica Chat da `api/endpoints.md`~~	✅ Fatto	`api/endpoints.md`
A3	Aggiungere `api/webhooks` alla sidebar quando creato	🟡 Media	`sidebars-desk.ts`
A4	~~Aggiungere endpoint mancanti (Commenti, Allegati, Utenti, Categorie, SLA)~~	✅ Fatto	`api/endpoints.md`

6. Convenzioni di stile (da Sign)

Lingua: italiano
Titoli sezioni principali: # MAIUSCOLO (es. # ACCESSO, # ARCHIVIO PRATICHE)
Sottosezioni: ## Title Case o ### Title Case
Screenshot: immagini inline in base64 o riferimento a file in cartella dedicata
Tabelle: formato Markdown standard per parametri, ruoli, codici errore
Admonitions: usare :::tip, :::warning, :::info di Docusaurus
Esempi codice: blocchi con language tag (bash, python, javascript, json)
Card di navigazione: JSX Docusaurus con className="row" e className="card" per i "Prossimi Passi"
Frontmatter: sidebar_position per ordinamento

1. Obiettivo​

2. Struttura target (modello Sign)​

2.1 Documentazione (manuale utente)​

2.2 API Reference​

3. Gap analysis — Stato attuale Desk​

File esistenti e stato​

Riepilogo avanzamento​

4. Piano di implementazione​

Fase 1 — Manuale utente (manual/) ✅ COMPLETATA​

4.1 manual/features.md — Manuale operativo ✅​

4.2 manual/roles.md — Documentazione ruoli ✅​

4.3 manual/getting-started.md — Guida rapida ✅​

4.4 manual/configuration.md — Decisione ✅​

Fase 2 — API Reference (api/) ⚠️ QUASI COMPLETATA​

4.5 api/overview.md — Panoramica API ✅​

4.6 api/endpoints.md — Endpoint dettagliati ✅ COMPLETO​

4.7 api/webhooks.md — Webhook ❌ DA CREARE​

4.8 api/examples.md — Esempi ✅​

Fase 3 — Sidebar e navigazione ✅ COMPLETATA​

4.9 sidebars-desk.ts ✅​

5. Riepilogo contenuti da ricevere​

Azioni tecniche rimanenti (non richiedono contenuti esterni)​

6. Convenzioni di stile (da Sign)​