Sincronizzazione della documentazione Markdown con il CMS

Questo documento è un runbook operativo per i flussi di lavoro IA/operatore attendibili che sincronizzano i file di documentazione Markdown modificati nella cartella docs/ del repository con pagine di documentazione di WebBlocks CMS collegate alla loro sorgente. Sono indicazioni di prodotto puramente documentali. Non aggiunge alcun motore di sincronizzazione a runtime, endpoint, migrazione, comando Artisan, script, job, coda, tabella di database, processo di rilascio o connessione a un qualsiasi target live.

I file Markdown sotto docs/ restano la fonte di verità per la documentazione tecnica di WebBlocks CMS. Le pagine di documentazione del CMS sono derivati generati, in bozza o pubblicati, di quei file Markdown. Il flusso di lavoro esiste affinché le modifiche alla documentazione fatte durante il normale sviluppo del prodotto possano riflettersi in un sito di documentazione del CMS senza trattare la pagina del CMS come la copia autorevole.

Si tratta di un flusso di lavoro IA/operatore, non di una sincronizzazione automatica a runtime. Il CMS non deve sorvegliare il repository, scaricare file Markdown o modificare contenuti da solo. Un operatore o uno strumento IA attendibile pianifica, valida e, facoltativamente, applica aggiornamenti sicuri in bozza tramite la Internal Content API.

Il modello deve funzionare per qualsiasi installazione del CMS o sito di documentazione di destinazione. La documentazione e i report devono restare generici e non devono includere il nome reale di un sito di destinazione, un dominio reale, un token API reale, un percorso assoluto locale, un log grezzo o un valore di ambiente.

Gli operatori futuri devono poter usare prompt concisi come:

Da questi comandi brevi, l'IA/l'operatore deve dedurre il flusso di lavoro standard:

• usare i file Markdown sotto docs/ come insieme di sorgenti candidate
• preferire i file modificati anziché una scansione completa dell'albero docs
• leggere il front matter cms_sync e i metadati di origine
• scoprire l'API del CMS di destinazione da GET /webadmin/api
• usare solo contratti di contenuto e handle di blocco scoperti
• abbinare le pagine del CMS collegate alla sorgente per identità di origine prima che per percorso
• produrre un piano e un report di validazione per ogni file
• applicare solo quando il comando autorizza esplicitamente un apply sicuro in bozza o l'utente approva il piano esatto
• non pubblicare mai a meno che l'utente non lo richieda esplicitamente e il token disponga di content.publish

Update da solo significa pianificare, validare e applicare modifiche sicure in bozza solo quando l'istruzione dell'utente autorizza chiaramente l'apply. Non implica pubblicazione, modifiche alla navigazione, sovrascrittura di pagine live, importazione di media o automazione del browser.

Usate questo ordine per decidere quali file Markdown sono candidati:

1. Se l'utente fornisce un elenco esplicito di file, usate quell'elenco.
2. Altrimenti, usate i file Markdown modificati nel repository sotto docs/.
3. Includete i file .md aggiunti, modificati e rinominati.
4. Escludete i file di changelog di rilascio archiviati sotto docs/releases/ se non esplicitamente richiesti.
5. Escludete i documenti interni di IA, worklog, audit o pianificazione privata quando sono al di fuori della documentazione pubblica o contrassegnati come interni.
6. Escludete i file privi di metadati cms_sync a meno che il flusso di lavoro non sia esplicitamente in modalità di pianificazione o adozione.
7. Eseguite una riscansione completa di docs/ solo quando l'utente la richiede esplicitamente.

Il rilevamento dei file modificati è soltanto un passaggio di selezione delle sorgenti. Non deve modificare lo stato di Git, mettere file in stage, creare artefatti di rilascio o dedurre un'installazione del CMS di destinazione dai remote del repository.

I file Markdown aderiscono tramite front matter:

cms_site, qui sopra, è un handle di sito di destinazione di esempio, non un dominio o un nome di installazione reali. cms_source_id è l'identità di origine stabile. Se un file viene spostato, l'identità di origine può restare invariata, così la pagina di destinazione può ancora essere abbinata in modo sicuro.

Regole dei metadati:

• cms_source_id è l'identità di origine stabile.
• cms_path è il percorso canonico di Page Translation, ad esempio /docs/internal-content-api; non anteponete /p alle nuove pagine di documentazione.
• cms_layout vale docs per impostazione predefinita quando è assente.
• cms_locale vale en per impostazione predefinita quando è assente.
• cms_title vale per impostazione predefinita il primo H1 o un titolo derivato dal nome del file quando è assente.
• l'hash di origine è un hash SHA-256 del contenuto Markdown sorgente usato per rilevare le modifiche.
• l'assenza dei metadati cms_sync significa che il file viene saltato dalla normale modalità di aggiornamento e può essere segnalato per la pianificazione dell'adozione.

L'adozione iniziale può essere svolta come passaggio di seeding dei metadati puramente documentale, prima di qualsiasi discovery del CMS live o tentativo di apply. Quel passaggio dovrebbe aggiungere front matter generico e sicuro ai file Markdown di documentazione pubblica selezionati, così che i piani successivi possano identificare id di origine, percorsi, lingue (locale), layout e titoli senza tirare a indovinare. Una passata di adozione completa di docs/ dovrebbe comunque escludere i changelog di rilascio archiviati sotto docs/releases/, a meno che un operatore attendibile non approvi esplicitamente quelle pagine di archivio.

Una pagina del CMS collegata alla sorgente dovrebbe conservare i metadati di origine nelle impostazioni della pagina. Le impostazioni della pagina bastano per il flusso di lavoro documentato; una tabella di mappatura delle sorgenti separata può essere presa in considerazione più avanti solo se lo richiedono reportistica, mappatura tra lingue, audit od operazioni su larga scala.

Struttura consigliata delle impostazioni della pagina:

Il percorso di origine è descrittivo. L'identità stabile è source_id e il rilevatore delle modifiche è source_sha256. La Internal Content API accetta questo oggetto solo tramite l'impostazione di pagina consentita source_sync, lo conserva dopo l'apply e restituisce gli stessi campi sicuri nelle risposte di elenco e dettaglio delle pagine per l'abbinamento. Non memorizzate token, valori di ambiente, percorsi assoluti locali, percorsi del server o altri segreti.

L'ordine di abbinamento deve essere deterministico:

1. Cercate una pagina del CMS con source_sync.source_id corrispondente o con metadati cms_source_id equivalenti.
2. Se la trovate, confrontate source_sha256.
3. Se non esiste corrispondenza per id di origine, cercate una pagina al percorso canonico cms_path.
4. Se il percorso esiste senza metadati di origine corrispondenti, segnalate un caso di adozione o di revisione del conflitto.
5. Se il percorso appartiene a un altro source_id, segnalate un conflitto e fermatevi per quel file.
6. Se al percorso non esiste alcuna pagina, pianificate create_draft_page con page.path impostato al percorso canonico cms_path.

Non usate il confronto dei contenuti come meccanismo primario di abbinamento. Abbinate prima per identità di origine stabile e solo dopo per percorso, per l'adozione o la revisione dei conflitti.

Per la documentazione Markdown modificata, usate queste impostazioni predefinite:

• Se l'hash di origine è invariato nei metadati del CMS, saltate il file.
• Se non esiste alcuna pagina del CMS corrispondente, pianificate create_draft_page.
• Se esiste una pagina in bozza corrispondente, pianificate replace_existing_draft_page per gli slot gestiti di proprietà della pagina.
• Se esiste solo una pagina pubblicata corrispondente, non sostituitela direttamente a meno che il flusso di lavoro non preveda un percorso documentato sicuro di bozza o staging e l'utente non approvi esplicitamente quel percorso.
• Lo slot gestito predefinito è main.
• Preservate header, footer, slot disattivati e assegnazioni di Shared Slot.
• Non sostituite uno slot servito da uno Shared Slot.
• Pianificate la navigazione separatamente e non applicate modifiche alla navigazione per impostazione predefinita.
• La pubblicazione non fa mai parte di content apply per impostazione predefinita.

Il flusso di lavoro dovrebbe rigenerare gli slot gestiti di proprietà della pagina a partire dalla sorgente Markdown, invece di cercare di preservare modifiche manuali del CMS all'interno di quegli slot. Le pagine di documentazione collegate alla sorgente sono derivati riproducibili; il Markdown resta autorevole.

Costruite contenuti strutturati usando solo handle scoperti nell'installazione di destinazione. Non indovinate mai gli handle dei blocchi né grafie simili.

Regole pratiche di mappatura:

• H1 corrisponde al titolo della pagina e/o a un blocco content_header quando quell'handle è disponibile.
• H2 e H3 corrispondono a blocchi header, con ancore dove supportate.
• I paragrafi corrispondono a rich-text.
• Il testo breve e non formattato può usare plain_text solo quando è più appropriato del rich text.
• Gli elenchi corrispondono a un blocco elenco quando il contratto dei contenuti corrente ne prevede uno; altrimenti mantenerli in rich-text.
• Le tabelle corrispondono a un blocco table ove possibile.
• I blocchi di codice delimitati corrispondono a un blocco code.
• Le citazioni corrispondono a blocchi quote oppure di tipo alert/callout a seconda del significato e dei contratti scoperti.
• I normali link Markdown restano link rich-text.
• I link di tipo CTA possono diventare button_link solo quando sono intenzionalmente orientati all'azione.
• L'HTML grezzo va evitato; html è un ripiego soggetto a revisione, solo quando i blocchi strutturati non possono rappresentare il contenuto.
• Immagini e media non devono essere scaricati o importati. Segnalate un avviso, a meno che il flusso di lavoro di destinazione non supporti esplicitamente i riferimenti a media già esistenti.

Preferite una struttura di documentazione leggibile a un unico grande blocco rich-text. Una normale pagina di documentazione usa di solito content_header o il contenuto del titolo derivato dall'H1, seguito da intestazioni, rich text, elenchi, tabelle e blocchi di codice all'interno dello slot gestito main.

Il flusso di lavoro è API-first:

1. Iniziate da GET /webadmin/api.
2. Usate i link restituiti per OpenAPI, la guida IA, il contratto dei contenuti, i tipi di blocco, le pagine, la navigazione e gli Shared Slot.
3. Verificate che il token abbia le capability necessarie per la modalità richiesta.
4. Leggete le pagine esistenti e i metadati di origine tramite l'API.
5. Costruite i piani di pagina usando solo handle scoperti.
6. Eseguite POST /webadmin/api/content/validate prima dell'apply.
7. Applicate solo dopo un'approvazione esplicita o quando l'istruzione dell'utente autorizza esplicitamente un apply sicuro in bozza.
8. Non pubblicate mai a meno che l'utente non lo richieda esplicitamente e il token disponga di content.publish.
9. Non usate mai l'automazione del browser quando l'API è disponibile.

Gli errori dell'API sono feedback per il flusso di lavoro. Trattate le risposte JSON 401, 403 e 422 come segnali di arresto o di revisione, seguite i link di discovery/documentazione e riportate uno stato riassunto e sicuro senza stampare segreti.

Quando i documenti modificati candidati sono più di uno:

• trattate ogni documento sorgente come un aggiornamento di pagina pianificato indipendente
• validate tutti i piani di pagina candidati prima di applicare qualsiasi batch, a meno che l'operatore non scelga esplicitamente l'apply file per file
• lasciate che il conflitto di un file blocchi solo quel file, senza nascondere i piani riusciti degli altri
• segnalate separatamente i file saltati, pianificati, validati, applicati, falliti e in conflitto
• non apportate modifiche alla navigazione solo perché sono cambiati più documenti
• mantenete la pianificazione della navigazione come un piano esplicito separato

L'apply in batch deve essere conservativo. Se l'utente ha richiesto un apply sicuro in bozza, applicate solo gli elementi validati sicuri per la bozza e lasciate non applicati i conflitti o i casi da rivedere.

Fermatevi prima dell'apply quando:

• il token API manca, non è valido o è stato revocato
• il discovery dell'API fallisce
• OpenAPI, il contratto dei contenuti o i tipi di blocco non sono leggibili
• gli handle di blocco necessari non sono disponibili
• cms_path è in conflitto con un altro cms_source_id
• la pagina di destinazione è pubblicata e non è disponibile un percorso sicuro di sostituzione in bozza
• il piano sostituirebbe uno slot servito da uno Shared Slot
• la validazione fallisce
• l'utente non ha approvato l'apply e l'istruzione era una simulazione o di sola pianificazione

Fermatevi anche prima della pubblicazione, a meno che l'utente non la richieda esplicitamente, il piano sia già stato validato/applicato in sicurezza e il token disponga di content.publish.

Per i batch, raggruppate gli stessi campi nelle sezioni skipped, planned, validated, applied, failed, conflict e needs review.

Solo pianificazione:

Solo validazione:

Validare e applicare aggiornamenti sicuri in bozza:

Pianificazione con riscansione completa:

Solo pianificazione della navigazione:

Le pagine di documentazione collegate alla sorgente dovrebbero essere contrassegnate nel CMS come gestite dalla sorgente. Una futura schermata di modifica potrà avvisare gli editor: "Questa pagina è sincronizzata da una sorgente Markdown. Modificate invece il file sorgente."

Le modifiche manuali nel CMS alle pagine di documentazione collegate alla sorgente non vengono preservate dalla successiva rigenerazione degli slot gestiti a partire dalla sorgente. Le assegnazioni di header/footer e di Shared Slot vengono invece preservate, perché non sono contenuto Markdown gestito di proprietà della pagina.

La documentazione e i report dell'operatore non devono includere token, segreti, percorsi assoluti locali, log grezzi, valori di ambiente, nomi reali di siti di destinazione o domini reali.