Registrare gli esiti: stati, prove e record.py

Ogni tentativo su una directory si chiude con un comando. scripts/record.py scrive una sola riga attuale per piattaforma in submissions.json, nella cartella del prodotto, e rifiuta le righe che il toolkit considera non dimostrate o non sicure. Quel rifiuto è il punto centrale: il tracker è ciò che impedisce a “abbiamo inviato a 40 directory” di significare “abbiamo compilato 40 moduli e sperato”. Questa guida tratta gli stati, le prove che ciascuno richiede, i flag del comando e cosa può e non può finire in una nota. È un riassunto di RUNBOOK.md e dei controlli dello script stesso, non li sostituisce.

Il comando

L’esempio del runbook, eseguito dalla directory del toolkit con una cartella di progetto privata già creata:

Su Windows, nei comandi seguenti usa py -3 al posto di python3 (oppure python, se è quello il tuo comando per Python 3.10+). Tieni il workspace in una cartella locale privata, fuori da OneDrive o da altre cartelle sincronizzate. Negli esempi di shell su più righe, in PowerShell scrivi il comando su una sola riga ed elimina i caratteri \ finali.

python3 scripts/record.py --project ../private-product pitchwall draft \
  --note "Product import corrected; final form not sent" \
  --next-action "Check saved profile and review final form"

Due argomenti posizionali (id della piattaforma, stato) e due opzioni obbligatorie (--note, --next-action). I flag facoltativi sono --public-url, --confirmed-public, --launch-date e --replace. L’id della piattaforma deve essere uno slug in minuscolo, lo stato deve essere uno degli undici elencati sotto, e il tracker si interrompe con una spiegazione ogni volta che una regola non è rispettata. Il modulo di registrazione della dashboard locale chiama la stessa funzione con le stesse regole.

Gli undici stati e le prove minime

La tabella del runbook, in breve:

Stato	Cosa devi aver osservato
draft	Lavoro preparato; invio finale non confermato.
prepared_needs_human	Un’azione precisa del titolare o una verifica (CAPTCHA, 2FA) blocca il lavoro preparato.
submitted_pending_review	La piattaforma ha ricevuto esplicitamente l’invio; resta la moderazione.
queued	La piattaforma conferma una posizione in coda o uno stato di lista d’attesa.
scheduled	La piattaforma conferma una data di lancio uguale o successiva alla data minima; l’eventuale approvazione in sospeso va nella nota.
live	Scheda pubblica verificata, senza etichetta di attesa; richiesti URL pubblico e --confirmed-public.
already_listed	Verificata una scheda pubblica già esistente; stessi requisiti di live.
blocked	Idoneità, capacità dell’account o un dato obbligatorio mancante impediscono di procedere.
deferred_paid	Il percorso utilizzabile richiede un pagamento; non è stato acquistato nulla.
not_a_fit	Il prodotto non soddisfa i criteri di pubblico o di inserimento.
unavailable	Il percorso o la piattaforma al momento non è utilizzabile; annota il problema.

Le distinzioni che contano di più sono quella tra bozza e invio e quella tra in attesa e live. Una schermata di ringraziamento non rende live una scheda. Una pagina raggiungibile può essere ancora in attesa di approvazione. Una casella “distribuisci anche al nostro partner” spuntata non significa che una seconda piattaforma abbia ricevuto qualcosa. Il risultato di ogni piattaforma resta indipendente, così i totali non vengono mai gonfiati.

Le regole applicate dallo script

• Gli stati pubblici richiedono una prova. live e already_listed richiedono --public-url con un URL HTTPS controllato (niente query string, niente frammento, niente percorsi di account, dashboard o login) e --confirmed-public, la tua dichiarazione di aver guardato la pagina.
• scheduled richiede una data. --launch-date YYYY-MM-DD è obbligatorio e non può essere precedente a earliest_launch_date in product.json; la guida alla data minima di lancio spiega perché.
• Le note restano pulite. Note e prossime azioni non possono contenere link, indirizzi email, coppie in stile password= o prefissi di token noti. Il file del tracker è pensato per essere condivisibile; le prove con URL dell’account vanno in uno spazio privato.
• Una riga per piattaforma. Se la piattaforma ha già una riga, il comando fallisce a meno che tu non passi --replace, dopo aver esaminato sia la riga esistente sia la piattaforma. La sostituzione è intenzionale, mai un effetto collaterale.
• Niente link simbolici, scritture atomiche, un file di lock. Dettagli noiosi, ma sono il motivo per cui due agenti che scrivono contemporaneamente non corrompono il tracker.

Riprendere senza duplicati

All’inizio della sessione successiva, leggi il tracker prima di toccare qualsiasi modulo. Dai la precedenza ai passaggi di consegne a una persona e ai lanci programmati da verificare, poi agli invii in attesa la cui finestra di revisione dichiarata è trascorsa. Se una piattaforma non indica tempi di revisione, concorda una data di follow-up con il titolare invece di inventarne una. E non inviare mai di nuovo per scalare una coda: ricontrolla il record esistente. Il tracker memorizza lo stato attuale, non la cronologia; se ti serve una traccia di audit, archivia a parte riepiloghi delle run privi di dati sensibili.

Per esempi concreti degli stati su piattaforme reali, leggi l’articolo sugli stati degli invii e la guida precedente su come tracciare gli invii senza contarli due volte; il vocabolario in sé è definito alla voce stato della scheda.