Architettura di prodotto del Plugin Catalog

Questo documento registra l'architettura di prodotto e la pianificazione dell'MVP per la superficie proposta plugins.webblocksui.com prima dell'inizio dell'implementazione. È solo documentazione. Non aggiunge codice di runtime, rotte, migrazioni, controller, client API, tabelle di database, schermate dell'interfaccia, script di deploy, job in background, tag di rilascio o incrementi di versione.

plugins.webblocksui.com è la superficie pubblica proposta del Plugin Catalog per l'ecosistema WebBlocks. Deve aiutare gli utenti a scoprire i plugin, a comprenderne i metadati, a vedere la compatibilità con i prodotti host, a consultare la cronologia dei rilasci e a seguire indicazioni sicure per l'installazione manuale.

Il primo obiettivo è la scoperta, i metadati, la visibilità della compatibilità e indicazioni sicure per l'installazione manuale tramite ZIP. Non deve nascere come un marketplace commerciale e non deve lasciare intendere che esista un'installazione remota automatica dei plugin in WebBlocks CMS, QuizTem, Herne Panel, WebBlocks Publisher o in qualsiasi altro prodotto host.

Il linguaggio di prodotto deve distinguere tre fasi:

• Plugin Catalog: sfogliare, cercare e scoprire i plugin; leggere metadati, compatibilità, note di rilascio, screenshot, documentazione e link di download.
• Plugin Store: in seguito, integrazione affidabile di installazione/aggiornamento dai metadati del catalogo verso i prodotti host.
• Marketplace: futuro livello commerciale con fornitori, account, licenze, pagamenti, approvazioni, valutazioni e distribuzione di plugin a pagamento.

Il prodotto a breve termine deve chiamarsi Plugin Catalog, non Marketplace. Il linguaggio del Marketplace deve restare riservato alle funzionalità commerciali rinviate.

Vantaggi:

• confine di prodotto netto
• roadmap indipendente
• gestione a lungo termine dell'API e del catalogo più semplice

Svantaggi:

• maggior lavoro di configurazione e gestione operativa
• gestione dei contenuti, amministrazione, deploy e manutenzione separati

Vantaggi:

• riutilizza i concetti di pubblicazione degli aggiornamenti
• può riutilizzare gli schemi di artefatti, checksum, metadati di rilascio e manifest

Svantaggi:

• rischia di rendere WebBlocks Publisher troppo esteso
• gli aspetti del catalogo dei plugin differiscono dalla pubblicazione degli aggiornamenti di prodotto
• la scoperta nel catalogo, le matrici di compatibilità e le pagine pubbliche dei plugin possono allontanare Publisher dal suo ruolo principale

Vantaggi:

• dimostra le capacità di WebBlocks CMS
• le pagine di contenuto sono facili da gestire
• il Plugin Catalog può mettere alla prova il sistema di plugin stesso

Svantaggi:

• richiede un plugin di catalogo
• necessita di una separazione accurata tra la gestione dei contenuti pubblici e l'autorità su artefatti e catalogo
• deve evitare che la modifica dei contenuti nel CMS diventi l'autorità sulla sicurezza degli artefatti eseguibili

Il modello ibrido servirebbe le pagine pubbliche di marketing e di contenuto da WebBlocks CMS, mentre l'API del catalogo e i metadati degli artefatti verrebbero serviti da un servizio di catalogo dedicato o da un backend derivato da Publisher.

Potrebbe essere la direzione più pratica nel lungo periodo, ma resta una direzione, non un impegno di implementazione.

Documentate plugins.webblocksui.com come una superficie di prodotto dell'ecosistema con un confine netto. Iniziate con un MVP incentrato sul catalogo: scoperta, metadati, visibilità della compatibilità, note di rilascio, checksum, documentazione e indicazioni per il download manuale.

L'implementazione può iniziare come applicazione Laravel dedicata oppure come plugin di catalogo basato su WebBlocks CMS, ma il contratto dei dati non deve dipendere da una sola implementazione dell'interfaccia. I concetti di WebBlocks Publisher devono restare riutilizzabili, in particolare i metadati di rilascio e le idee di verifica degli artefatti, senza presumere che il Plugin Catalog debba risiedere dentro Publisher.

I concetti seguenti sono solo a livello di pianificazione. Non implicano tabelle di database, API, modelli, migrazioni o schermate di amministrazione nel repository attuale.

• handle
• etichetta
• riepilogo
• descrizione
• fornitore/autore
• URL del sito web
• URL della documentazione
• URL di supporto
• tipo di licenza
• categorie
• tag
• stato: bozza, in elenco, non in elenco, deprecato, sospeso
• data della prima pubblicazione
• data dell'ultimo rilascio

• nome
• slug
• sito web
• contatto di supporto
• stato verificato
• pagina di profilo pubblica
• futura idoneità commerciale, rinviata

• chiave del prodotto, ad esempio webblocks-cms, quiztem, herne-panel o webblocks-publisher
• etichetta del prodotto
• intervalli di versione supportati
• regole di visibilità nel catalogo

• handle del plugin
• versione
• canale: stable, beta, alpha, dev
• data di rilascio
• note di rilascio
• matrice di compatibilità
• versione di PHP/Laravel richiesta, quando applicabile
• URL dell'artefatto
• checksum
• futuri metadati di firma
• note sulle migrazioni
• note sulle modifiche non retrocompatibili
• note di sicurezza
• note sulle deprecazioni

• percorso di archiviazione o URL
• checksum
• dimensione
• MIME/tipo
• formato del pacchetto
• metadati del manifest
• stato di validazione
• stato della scansione
• stato di pubblicazione

• prodotti host supportati
• versioni richieste del prodotto host
• versioni incompatibili del prodotto host
• vincoli su PHP/Laravel, dove rilevanti
• estensioni richieste
• handle di plugin in conflitto
• dipendenze da altri plugin, se in futuro il supporto verrà approvato

• handle del plugin
• versioni interessate
• gravità
• stato
• versione corretta
• riepilogo pubblico
• azione consigliata all'operatore

Le future pagine pubbliche della superficie proposta plugins.webblocksui.com possono includere:

• Homepage
• Elenco dei plugin
• Pagine di categoria
• Risultati di ricerca
• Pagina di dettaglio del plugin
• Pagina della cronologia dei rilasci
• Pagina del profilo del fornitore
• Pagine di compatibilità con i prodotti host
• Pagine di documentazione / guida all'installazione
• Pagina degli avvisi di sicurezza
• Indicazioni sui plugin deprecati o rimossi
• Future pagine del marketplace, esplicitamente rinviate

Le pagine di dettaglio del plugin dovrebbero includere:

• nome del plugin
• riepilogo
• screenshot
• prodotti host supportati
• ultima versione compatibile
• versioni richieste del prodotto host
• note di rilascio
• permessi richiesti
• migrazioni dichiarate
• rotte, impostazioni, comandi e asset dichiarati
• metodo di installazione
• informazioni su download e checksum
• stato di sicurezza/deprecazione
• link di supporto e documentazione

Le future schermate per l'operatore del catalogo possono includere:

• Plugin
• Fornitori
• Rilasci
• Artefatti
• Compatibilità
• Avvisi di sicurezza
• Categorie/Tag
• Coda di revisione, rinviata
• Commerciale/Licenze, rinviato

Si tratta di concetti di pianificazione per il catalogo e l'amministrazione, non di attività di implementazione dell'amministrazione del CMS.

I futuri endpoint API di sola lettura possono includere:

• GET /api/plugins
• GET /api/plugins/{handle}
• GET /api/plugins/{handle}/releases
• GET /api/plugins/{handle}/latest?host_product=webblocks-cms&version=...
• GET /api/host-products
• GET /api/security-advisories
• GET /api/catalog/index

L'API V1 deve essere di sola lettura per i prodotti host. Le risposte dell'API non devono mai provocare da sole un'installazione remota, l'abilitazione di plugin, l'esecuzione di migrazioni, l'applicazione di aggiornamenti, un'installazione arbitraria con Composer o qualsiasi comportamento eseguibile.

I futuri endpoint per publisher/operatori sono separati e rinviati:

• pubblicare un rilascio di plugin
• caricare un artefatto
• approvare una scheda
• sospendere una scheda
• emettere un avviso

WebBlocks CMS e altri prodotti host possono utilizzare il Plugin Catalog per:

• sfogliare il catalogo dall'amministrazione dell'host
• mostrare la compatibilità del plugin prima del download/installazione
• rimandare al download manuale dello ZIP
• confrontare le versioni dei plugin installati con i rilasci del catalogo
• mostrare avvisi di sicurezza/deprecazione per i plugin installati
• supportare flussi controllati di installazione/aggiornamento solo quando i prodotti host ricontrollano i metadati degli artefatti attendibili, verificano i checksum, convalidano i pacchetti e richiedono azioni esplicite dell'operatore

La consultazione del catalogo non deve richiedere che la gestione dei plugin installati sia online. La gestione dei plugin installati deve funzionare anche senza la disponibilità del catalogo. I prodotti host dovrebbero memorizzare nella cache i metadati del catalogo in modo difensivo e i metadati remoti non devono essere considerati comportamento eseguibile attendibile.

Il futuro flusso per manutentori/operatori può includere:

• preparare l'artefatto del plugin in locale
• convalidare il manifest del plugin
• convalidare la struttura del pacchetto
• calcolare il checksum
• caricare artefatto e metadati
• il catalogo verifica la compatibilità e la sicurezza dell'artefatto
• il rilascio viene elencato solo dopo un'approvazione esplicita dell'operatore o tramite un flusso di pubblicazione interno attendibile

Ciò ricorda le idee di WebBlocks Publisher sui metadati di aggiornamento, ma la pubblicazione nel catalogo dei plugin dovrebbe restare una funzionalità separata, a meno che una decisione successiva non le unifichi.

Un primo MVP concreto dovrebbe includere:

• voci di plugin statiche o gestite dal catalogo
• pagine pubbliche di elenco e di dettaglio dei plugin
• metadati dei rilasci dei plugin
• matrice di compatibilità
• link di download manuale
• checksum visualizzati
• link alla documentazione
• nessuna installazione remota automatica lato CMS
• nessun marketplace a pagamento
• nessuna gestione delle licenze
• nessuna pubblicazione self-service da parte di terzi
• nessuna applicazione automatica degli aggiornamenti

Questa fase di pianificazione non include:

• l'implementazione in questa attività
• il deploy in produzione
• l'installazione remota automatica dei plugin
• l'abilitazione automatica dei plugin
• l'esecuzione automatica delle migrazioni dei plugin
• l'applicazione automatica degli aggiornamenti dei plugin
• l'installazione arbitraria con Composer
• un marketplace a pagamento
• un server di licenze
• un portale self-service per i fornitori
• valutazioni/recensioni
• l'automazione della pubblicazione degli artefatti in produzione
• la verifica sul sito in produzione

• plugins.webblocksui.com deve nascere come applicazione Laravel dedicata o come plugin di catalogo basato sul CMS?
• WebBlocks Publisher deve occuparsi della pubblicazione degli artefatti dei plugin, oppure il Plugin Catalog deve avere un proprio flusso di pubblicazione?
• I plugin di prima parte e quelli di terze parti devono avere flussi di approvazione diversi?
• Come devono essere gestite le firme dei plugin?
• Come si potrà introdurre in seguito la licenza commerciale senza modificare il contratto del catalogo?
• Come devono essere rappresentati i plugin privati o interni?
• Come devono dichiarare i plugin multi-host i provider e la compatibilità per ciascun host?