Vai al contenuto

Processo editoriale

Questa sezione descrive il ciclo editoriale autorevole di Architecture Coffee, dagli input accettati in D1 fino all'evidenza provider. Ogni passaggio ha un'azione, un attore, una validazione e una prova distinti.

La documentazione non concede autorità

La presenza di un pulsante, di una route o di una capability provider non autorizza l'operazione. L'API proietta le azioni consentite, applica il permesso richiesto e resta l'autorità sulle transizioni.

Sequenza end-to-end

sequenceDiagram
    participant E as Editor o reviewer
    participant API as API Worker
    participant D1
    participant AI as Provider AI
    participant MJ as Mailjet
    E->>API: seleziona Topic accepted
    API->>D1: crea job queued
    Note over API,D1: Queue esegue il comando bounded
    API->>D1: legge contesto accepted
    API->>AI: richiede candidate JSON
    AI-->>API: JSON candidato
    API->>API: schema e quality gate
    API->>D1: salva draft pending_review
    E->>API: rivede e approva
    API->>D1: editorialStatus approved
    E->>API: pubblica esplicitamente
    API->>D1: status published
    E->>API: prepara Campaign Draft separato
    API->>MJ: crea draft o carica contenuto
    MJ-->>API: evidenza sanitizzata
    Note over API,MJ: scheduling e delivery restano distinti

La sequenza mostra il percorso possibile, non una pipeline automatica. Nessuna freccia autorizza quella successiva.

Autorità e sistemi di record

flowchart TB
    editor["Editor e reviewer umani"]
    app["API e policy applicativa"]
    d1["D1<br/>stato editoriale e audit"]
    ai["Provider AI<br/>output candidato"]
    mailjet["Mailjet<br/>contatti, consenso e delivery"]
    repo["Repository e Brain<br/>contratti e governance"]
    editor -->|"azioni esplicite"| app
    repo -->|"schema, Skill e regole"| app
    app <--> d1
    app -->|"prompt e contesto accettato"| ai
    ai -->|"candidate JSON"| app
    app -->|"operazioni provider separate"| mailjet
    mailjet -->|"evidenza sanitizzata"| app
Sistema Possiede Non possiede
D1 Topic, Knowledge Asset, glossario, Issue, revisioni, job, Campaign Draft e audit runtime ADR, codice, segreti o destinatari
Repository e Brain architettura, schema, Skill, policy e documentazione stabile catalogo editoriale runtime
API Worker autorizzazione, validazione e orchestrazione giudizio editoriale o consenso destinatari
Provider AI esecuzione del modello e risposta candidata Issue canonico, approvazione o pubblicazione
Mailjet contatti, liste, consenso, unsubscribe, bounce, suppression e stato destinatario Issue Content canonico o stato editoriale
Umani autorizzati selezione, revisione, approvazione e decisioni operative bypass di schema, quality gate o permessi server-owned

Contratto delle fasi

Fase Transizione o output Evidenza minima Non accade
Curazione Topic e Knowledge Asset proposed → accepted revisione D1 e readback nessuna generazione
Generazione job queued → running → completed o failed job D1 e Issue associato nessuna approvazione
Validazione candidate JSON → contenuto valido schema e diagnostica deterministica nessun HTML canonico
Revisione pending_review → approved o rejected reviewer autenticato e timestamp nessuna pubblicazione
Pubblicazione draft → published publishedAt e proiezione pubblica nessun Mailjet o deployment
Campaign Draft prepare e content_upload aggregate e attempt sanitizzati nessuno scheduling o send
Scheduling richiesta provider separata stato scheduled e ricevuta provider nessuna prova di delivery
Delivery esecuzione provider evidenza live autorizzata nessuna copia dei destinatari in D1
Feedback POST su Issue pubblicato record feedback e insight derivato nessuna modifica dell'Issue pubblicato

Percorso di lettura

  1. Topic e Knowledge Asset.
  2. Generazione Issue e job.
  3. Quality gate deterministici.
  4. Review, approvazione e pubblicazione.
  5. Campaign Draft.
  6. Scheduling ed evidenza di delivery.
  7. Feedback e confine dell'Issue pubblicato.
  8. Fallimenti e recupero.
  9. Governance del glossario.

I runbook applicano la struttura operativa comune: preparare e rivedere un Issue, recuperare un job, approvare e pubblicare, preparare un Campaign Draft, diagnosticare un provider e verificare l'evidenza di delivery.

Riferimenti canonici