# Gestionale bg_perspective: istruzioni per il Claude di Valentina

Questo file è per te, Claude di Valentina. Valentina (Instagram @madness_vale) e Paolo (@bg_perspective) tengono i
contatti con editori, autori e illustratori di giochi da tavolo in un gestionale comune, su
**https://bg-perspective.it/gestionale**. Tu ci lavori a nome di Valentina, **da solo, senza bisogno di chiedere a
Paolo**: puoi leggere, aggiungere, correggere e cancellare quello che le regole qui sotto permettono.

Se Valentina ti chiede di sistemare qualcosa (un handle Instagram sbagliato, una mail, un editore doppio, uno stato,
un messaggio da registrare) lo fai tu, con le API descritte qui. Non serve passare dalla pagina web e non serve
chiedere il permesso a nessuno.

Salva questo file nelle istruzioni permanenti del progetto di Valentina (per esempio come `GESTIONALE.md` accanto al
suo `CLAUDE.md`, con una riga nel `CLAUDE.md` che dice di leggerlo), così lo ritrovi a ogni sessione.


## 1. Prima di tutto: la chiave

Ogni richiesta vuole la chiave di Valentina. **La chiave non sta in questo file e non va mai scritta in chat, nei
comandi o nei file**: sta in una variabile d'ambiente di Windows che si chiama `GESTIONALE_CHIAVE`.

Controlla che ci sia, senza mostrarla:

```bash
test -n "$GESTIONALE_CHIAVE" && echo presente || echo MANCA
```

```powershell
if ($env:GESTIONALE_CHIAVE) { "presente" } else { "MANCA" }
```

Se manca, guida Valentina a parole (la chiave gliel'ha mandata Paolo su WhatsApp, e la incolla lei, non tu):

1. Menu Start, scrivere **variabili di ambiente**, aprire "Modifica le variabili di ambiente relative al proprio account".
2. In alto, "Variabili dell'utente", cliccare **Nuova…**.
3. Nome: `GESTIONALE_CHIAVE`. Valore: la chiave copiata da WhatsApp. OK, e di nuovo OK.
4. Chiudere e riaprire Claude Code: le variabili nuove si leggono solo all'avvio.

Poi verifica che la chiave funzioni:

```bash
curl -s -H "Authorization: Bearer $GESTIONALE_CHIAVE" https://bg-perspective.it/api/gestionale/io
```

Deve rispondere `{"utente":{"id":"valentina","nome":"Valentina"}}`. Se risponde 401, la chiave è sbagliata o
scaduta: Valentina la chiede di nuovo a Paolo.


## 2. La guida sempre aggiornata

Le API crescono nel tempo. L'elenco completo e aggiornato degli indirizzi si legge **senza chiave**:

```bash
curl -s https://bg-perspective.it/api/gestionale
```

Se qualcosa in questo file non torna con la guida, vale la guida. Leggila all'inizio di ogni lavoro sul gestionale.


## 3. Come scrivere i comandi senza impazzire (Windows)

Claude Code su Windows di solito usa **Git Bash**: lì gli esempi con `curl` di questo file funzionano così come sono.
Si preparano tre variabili all'inizio e poi si usano in ogni comando:

```bash
H="Authorization: Bearer $GESTIONALE_CHIAVE"
J="Content-Type: application/json"
B=https://bg-perspective.it/api/gestionale
```

**Attenzione al JSON con gli apostrofi** (nomi come "Let's Dig", "Don't Panic"): dentro `-d '...'` un apostrofo
rompe il comando. In quel caso scrivi il JSON in un file temporaneo e passalo con `--data @file`:

```bash
cat > /tmp/corpo.json <<'FINE'
{"scheda": "Editore francese di Don't Panic Games, l'edizione italiana la fa Mana Project"}
FINE
curl -s -X PATCH -H "$H" -H "$J" "$B/editori/12" --data @/tmp/corpo.json
```

Se invece stai usando **PowerShell**, non usare `curl` con il JSON tra apici (PowerShell lo rovina): usa
`Invoke-RestMethod`, che è fatto apposta:

```powershell
$H = @{ Authorization = "Bearer $env:GESTIONALE_CHIAVE" }
$B = "https://bg-perspective.it/api/gestionale"
Invoke-RestMethod -Method Patch -Uri "$B/editori/12" -Headers $H -ContentType "application/json; charset=utf-8" `
  -Body (@{ instagram = "@handle_giusto" } | ConvertTo-Json)
```

Le risposte sono sempre JSON. Gli errori arrivano come `{"errore": "spiegazione"}` con un codice: 400 dati non
validi, 401 chiave mancante o sbagliata, 403 stai provando a toccare una cosa di Paolo, 404 non trovato, 409 esiste
già. Leggi il messaggio di errore: dice esattamente cosa non va.


## 4. Cosa c'è dentro

Gli **editori** hanno `nome, instagram, hashtag, email, canale` (come si contattano davvero: mail, modulo sul sito,
DM), `sito, italiano` (1 o 0), `fonte, verificato_il` (data del controllo) e `scheda`, con i fatti stabili: chi sono,
cosa pubblicano, handle da non confondere.

Ogni editore ha uno **stato di Valentina** e uno di Paolo, separati: `attesa` (scritto, si aspetta), `si` (mandano
giochi), `no` (hanno detto di no o rimandano a un altro editore), `""` (nessun contatto). Accanto c'è
`ricontatto_il`, la data in cui farsi risentire.

La **cronologia** raccoglie ogni messaggio mandato o ricevuto e ogni nota, con `data, tipo` (`inviato`, `ricevuto`,
`nota`), `canale` e `testo`. Ogni voce ha il nome di chi l'ha scritta.

Le **persone** sono autori e illustratori, con `instagram` e i giochi a cui hanno lavorato. I **giochi** stanno per id
di BoardGameGeek, collegati agli editori (`italiano`, `originale`, `altro`) e alle persone (`autore`, `illustratore`).
Il **follow** è lo scambio settimanale degli account che hanno ricambiato il follow (vedi il punto 7).


## 5. Le regole

1. **I dati di editori, persone e giochi sono di tutti e due**: puoi correggerli liberamente. Resta scritto che l'ha
   fatto Valentina (`aggiornato_da`), quindi non serve chiedere a Paolo.
2. **Lo stato lo cambi solo per Valentina**: l'API sa chi sei dalla chiave, quello di Paolo non si può toccare.
3. **I messaggi in cronologia** li aggiungi a nome di Valentina, e puoi modificare o cancellare **solo i suoi**.
   Quelli di Paolo si leggono e basta.
4. **Prima di scrivere a un editore**, leggi la sua scheda e la cronologia di Paolo: così non gli si scrive in due la
   stessa cosa.
5. **Ogni messaggio che Valentina manda o riceve** si registra in cronologia, e si aggiorna il suo stato con la data
   di ricontatto.
6. **Prima di creare** un editore o una persona, cerca se c'è già, anche scritto in un altro modo. Se l'hai creato
   doppio per sbaglio, vedi la ricetta E.
7. Date sempre `AAAA-MM-GG`. Handle Instagram con la `@` davanti nei campi `instagram` (negli editori e nelle persone),
   senza `@` nel follow.
8. Gli id di BoardGameGeek e gli handle Instagram **non si scrivono a memoria**: si copiano dalla pagina vera (il
   gioco su boardgamegeek.com, il profilo su instagram.com) e si controlla che il profilo sia proprio quello.


## 6. Le ricette

Ogni ricetta parte dalle tre variabili `H`, `J`, `B` del punto 3. Negli indirizzi, al posto dell'id di un editore si
può usare il **nome esatto** con gli spazi scritti `%20` (`Cranio%20Creations`), ma l'id numerico è più sicuro.

### A. Correggere un dato di un editore (per esempio l'handle Instagram sbagliato)

È la cosa che serve più spesso. Tre passi: trovarlo, correggerlo, controllare.

```bash
# 1. Trovarlo: la ricerca guarda nome, instagram, email e sito. Nella risposta c'è il suo "id".
curl -s -H "$H" "$B/editori?cerca=cranio"

# 2. Correggere solo i campi che servono (qui l'instagram dell'editore con id 12)
curl -s -X PATCH -H "$H" -H "$J" "$B/editori/12" -d '{"instagram":"@craniocreations_official"}'

# 3. La risposta è la scheda aggiornata: controlla che il campo sia giusto
```

Si possono correggere insieme più campi: `-d '{"instagram":"@...","email":"stampa@...","sito":"https://..."}'`. Per
svuotare un campo si manda `null`: `-d '{"hashtag":null}'`. Anche il nome si può correggere.

### B. Correggere una persona (autore o illustratore)

```bash
curl -s -H "$H" "$B/persone?cerca=silva"                                     # trova l'id
curl -s -X PATCH -H "$H" -H "$J" "$B/persone/12" -d '{"instagram":"@lorenzo_silva_hg"}'
```

### C. Registrare un messaggio e aggiornare lo stato

```bash
# Messaggio mandato o ricevuto (data: se manca è oggi)
curl -s -X POST -H "$H" -H "$J" "$B/editori/12/contatti" \
  -d '{"tipo":"inviato","canale":"mail","data":"2026-10-02","testo":"Chiesta una copia di Railroad Tiles in inglese."}'

# Stato di Valentina e data di ricontatto (null per toglierla)
curl -s -X PUT -H "$H" -H "$J" "$B/editori/12/stato" -d '{"stato":"attesa","ricontatto_il":"2026-10-15"}'
```

Per un autore o un illustratore: `POST $B/persone/<id>/contatti` con lo stesso corpo.

### D. Correggere o cancellare un messaggio di Valentina

L'id del messaggio è nella cronologia della scheda (`GET $B/editori/12`, campo `contatti`).

```bash
curl -s -X PATCH -H "$H" -H "$J" "$B/contatti/42" -d '{"testo":"Testo corretto","data":"2026-10-01"}'
curl -s -X DELETE -H "$H" "$B/contatti/42"
```

### E. Un editore inserito due volte, o con il nome sbagliato

Non si cancella un editore: si corregge quello giusto e si avvisa Paolo del doppione.

1. Correggi i dati sull'editore giusto (ricetta A), compreso il nome se serve.
2. Se sul doppione c'erano messaggi di Valentina, rifalli sull'editore giusto (ricetta C) e cancellali dal doppione
   (ricetta D).
3. Sul doppione scrivi una nota, così Paolo lo toglie:
   `-d '{"tipo":"nota","testo":"DOPPIONE di <nome giusto> (id <n>): da togliere"}'` su `POST $B/editori/<id doppione>/contatti`.

### F. Nuovo editore, nuova persona

Prima cerca (ricetta A, passo 1). Se non c'è:

```bash
curl -s -X POST -H "$H" -H "$J" "$B/editori" \
  -d '{"nome":"Nome Editore","instagram":"@handle","email":"info@esempio.it","sito":"https://esempio.it","italiano":1,"canale":"mail","fonte":"sito ufficiale","verificato_il":"2026-10-02"}'

curl -s -X POST -H "$H" -H "$J" "$B/persone" \
  -d '{"nome":"Nome Cognome","instagram":"@handle","autore":1,"illustratore":0,"fonte":"profilo Instagram","verificato_il":"2026-10-02"}'
```

La risposta ti dà l'`id` nuovo. Se rispondono 409, esiste già: cercalo e correggi quello.

### G. Giochi e legami

```bash
curl -s -H "$H" "$B/giochi?cerca=railroad"
curl -s -X POST -H "$H" -H "$J" "$B/giochi" -d '{"bgg_id":418062,"titolo":"Railroad Tiles","anno":2025,"nostro":"desiderato"}'
curl -s -X POST -H "$H" -H "$J" "$B/giochi/418062/collega" -d '{"editore":12,"ruolo":"italiano"}'
curl -s -X POST -H "$H" -H "$J" "$B/giochi/418062/collega" -d '{"persona":12,"ruolo":"autore"}'
curl -s -X DELETE -H "$H" "$B/giochi/418062/collega?editore=12&ruolo=italiano"
```

`nostro` può essere `collezione`, `ricevuto` o `desiderato`.

### H. Chi ricontattare

```bash
curl -s -H "$H" "$B/ricontatti?entro=2026-10-15"                 # quelli di Valentina
curl -s -H "$H" "$B/editori?stato=attesa"                        # tutti gli editori dove Valentina è "in attesa"
curl -s -H "$H" "$B/editori?stato=si&utente=paolo"               # quelli che mandano giochi a Paolo
```


## 7. Lo scambio dei follow, ogni lunedì

Paolo e Valentina scrivono ogni giorno un DM a chi seguono e non li segue. Chi poi ricambia il follow è un account
**attivo, che risponde**: ogni lunedì se li passano, e ognuno segue quelli dell'altro.

Il tuo lavoro del lunedì:

```bash
# 1. Caricare chi ha ricambiato il follow di Valentina dopo un suo DM, nella settimana.
#    handle senza @; lingua in italiano; descrizione: di cosa parla l'account, poche parole, in italiano.
curl -s -X POST -H "$H" -H "$J" "$B/follow" \
  -d '{"account":[{"handle":"nome_account","ricambiato_il":"2026-10-05","lingua":"inglese","descrizione":"giochi da tavolo in famiglia"}]}'

# 2. Dire a Valentina quali account di Paolo seguire
curl -s -H "$H" "$B/follow?di=paolo&da_seguire=1"

# 3. Quando Valentina ne ha seguito uno su Instagram, segnarlo (l'id è nell'elenco del passo 2)
curl -s -X PATCH -H "$H" -H "$J" "$B/follow/37" -d '{"seguito":true}'
```

Ricaricare lo stesso account non lo duplica: aggiorna lingua e descrizione. Un account si toglie dal proprio elenco
con `DELETE $B/follow/<id>`. Valentina vede tutto anche nella pagina **Follow** del gestionale, dove può premere
"Seguito" a mano.


## 8. A mano

Tutto si può fare anche dalla pagina **https://bg-perspective.it/gestionale** (utente `valentina`, password data da
Paolo; il login non scade). Nella scheda di un editore, sotto i dati, c'è il link **"Modifica i dati"**. Ma se
Valentina chiede a te, fallo tu con le API: è più veloce e resta tutto registrato.