Vai al contenuto

Generazione Issue e job

La generazione è asincrona. La richiesta HTTP crea un job durevole e affida alla Queue un comando limitato; D1, non la coda, è l'autorità sullo stato.

Obiettivo e transizione autorevole

stateDiagram-v2
    [*] --> queued: richiesta accettata
    queued --> running: consumer acquisisce il job
    running --> completed: draft valido associato
    running --> failed: errore terminale
    queued --> failed: enqueue o contesto fallito
    completed --> completed: redelivery idempotente
    failed --> failed: nessuna riapertura

Gli stati sono queued, running, completed e failed. Un nuovo tentativo operatore crea un nuovo job; non riscrive un job terminale.

Input e fonti accettate

La richiesta contiene un solo topicId valido. Il consumer ricostruisce il contesto da D1 usando:

  • Topic accepted;
  • Knowledge Asset accepted collegati;
  • Skill di generazione accepted possedute dal Brain;
  • schema Issue Content posseduto dal repository.

Il browser non invia prompt, Knowledge Asset, Issue number o metadati canonici.

Attore e autorizzazione

Un'identità con issue:generate crea il job. La Queue esegue il comando server-owned. La chiave del provider resta un secret del Worker; il provider non riceve una sessione Access o permessi editoriali.

Validazione e quality gate

Per ogni candidato, entro il limite configurato:

  1. la risposta deve essere JSON;
  2. deve rispettare lo schema Issue Content;
  3. i metadati autorevoli vengono normalizzati da Topic, Knowledge Asset e sequenza Issue;
  4. i quality gate deterministici devono passare;
  5. soltanto allora il draft viene inserito.

Il default corrente è tre candidate attempt interni. Gli errori di contenuto esauriscono il limite; gli errori provider usano anche la redelivery bounded della Queue.

Responsabilità dell'AI

Il provider produce solo candidate Issue Content JSON. Non produce HTML canonico, non sceglie gli ID runtime, non persiste, non approva, non pubblica, non prepara campagne e non invia email.

Persistenza e audit in D1

D1 conserva:

  • job e tempi createdAt, startedAt, completedAt;
  • esito sicuro e, su successo, issueId e issueSlug;
  • diagnostica bounded su fallimento;
  • Issue draft con editorialStatus: pending_review.

Prompt grezzi, chiavi, risposta provider completa e segreti non diventano audit.

Evidenza di successo

Un job è riuscito solo se:

  • è completed;
  • contiene l'Issue runtime associato;
  • l'Issue esiste con lo stesso slug e Topic;
  • il contenuto è valido e pending_review.

Un 202 Accepted, un messaggio Queue o un polling interrotto non provano il successo.

Fallimento e recupero

Codici come TOPIC_NOT_ACCEPTED, TOPIC_NOT_COVERED, AI_GENERATION_ATTEMPTS_EXHAUSTED o AI_GENERATION_FAILED indicano il punto di rientro. Correggere prima l'autorità D1 o la configurazione; poi creare un nuovo job esplicito. La redelivery di un job completato non rigenera.

Usare il runbook di recupero.

Effetti collaterali esclusi

La generazione non:

  • approva o pubblica;
  • modifica un Issue pubblicato;
  • prepara Campaign Draft;
  • schedula o invia;
  • chiama Mailjet;
  • distribuisce il Frontend.

Riferimenti canonici