# Bot "insert" — mettere un prodotto sotto controllo prezzo

Da un link a un prodotto tracciato: il bot ricava il codice, chiede il prezzo target e lo
consegna al sistema di tracking. Da lì in poi se ne occupano gli script di controllo, che
avvisano quando il prezzo scende sotto la soglia.

**Non pubblica niente su nessun canale.** I post li fa `createandsend`; questo bot riempie
solo la lista delle cose da guardare.

## I file

| file | cosa fa |
|---|---|
| `insert.php` | il webhook: comandi, conversazione, chiamate alle API di inserimento |
| `setup_menu.php` | registra il menu dei comandi. **Da lanciare a mano una volta** |
| `create_webhook.php` | registra il webhook su Telegram |
| `user_states.json` | la conversazione in corso di ogni utente |

## I comandi

| comando | cosa fa |
|---|---|
| `/new` | due bottoni: **Amazon** o **AliExpress** |
| `/newasin` | va dritto al flusso Amazon |
| `/newae` | va dritto al flusso AliExpress |
| `/annulla` | butta via la conversazione in corso |
| `/aiuto` | la schermata di spiegazione |

**Il modo più veloce non è un comando**: si incolla (o si inoltra) il link del prodotto e
basta. Il bot capisce dal link se è Amazon o AliExpress e parte con il flusso giusto —
`handleManualInsertFromMessage()`. Funziona anche con i messaggi **inoltrati da un canale**
e con quelli che hanno il link nella **didascalia di una foto**, che è il caso tipico di un
post di offerte girato al bot.

## I due flussi

### Amazon

```
link ──▶ ASIN ──▶ "prezzo massimo?" ──▶ inserito
```

L'ASIN si ricava dal link (`extractAsinFromUrl()` copre `/dp/`, `/gp/product/`, i formati
vecchi e il parametro `ASIN=`); i link accorciati vengono risolti seguendo i redirect. Se
dal link non esce niente, il bot lo chiede scritto a mano.

Poi serve un solo numero: il **prezzo massimo**. L'inserimento chiama
`amzInserisciAsin($asin, ['max_price' => …, 'max_price_usato' => …])`, in
`bot_section/amazon/inserimento.php`.

> Fino al 13/08/2026 era una chiamata HTTP a `from_all/insert_form.php`. Quella cartella
> stava fuori dal progetto ed è stata eliminata: adesso è una funzione dentro la sezione
> Amazon, e la chiama anche il bottone "metti in tracciamento" di `createandsend`.

**Il target dell'usato non si chiede: si calcola.** È `max_price / 1.20`, cioè il 20% sotto
quello del nuovo. È una scelta, non una legge: un usato che costa quanto il nuovo non è
un'offerta, e chiedere due numeri per ogni prodotto avrebbe raddoppiato il lavoro senza
raddoppiare l'informazione.

### AliExpress

```
link ──▶ prodotto + varianti ──▶ una domanda per variante ──▶ inserito
```

Passa da due endpoint di `ae_track`:

| endpoint | quando |
|---|---|
| `ae_track/ae_api_load.php?k=…&url=…` | carica prodotto e varianti (sku_id, nome, prezzo attuale, foto) |
| `ae_track/ae_api_insert.php` | riceve `pid` e la mappa `sku_id => target` |

Le varianti si scorrono **una per una**, con foto e prezzo di adesso sotto gli occhi:
si scrive il target, oppure si preme **SALTA**. Vengono tracciate solo quelle a cui è
stato dato un prezzo — `targets` resta vuoto se si salta tutto, e in quel caso non si
inserisce niente invece di inserire un prodotto senza soglie.

Due dettagli che sembrano minori:

- I **link brevi** (`a.aliexpress.com/_xxx`) non contengono il `product_id`: vengono
  risolti seguendo i redirect prima di chiamare l'API.
- Il bottone SALTA porta dentro **l'indice della variante** (`{"f":"aeskip","i":3}`). Se si
  preme il SALTA di un messaggio vecchio, il bot se ne accorge e lo ignora, invece di
  saltare la variante sbagliata.

## Chi può usarlo

`$authorized_users` in testa a `insert.php`: quattro id Telegram, con i nomi accanto in
`$authorized_users_names` — servono a scrivere **chi** ha inserito cosa nel log
`amazon_alert_log`, che altrimenti direbbe solo un numero.

Chi non è in lista riceve un "accesso negato" che si autocancella dopo cinque secondi.

## La chat si pulisce da sola

Questo bot **cancella i propri messaggi e quelli dell'utente** man mano che il flusso
avanza (`bot_messages` nello stato tiene l'elenco di cosa togliere). È l'opposto di
`createandsend`, e per un buon motivo: lì i messaggi sono il lavoro — l'anteprima di un
post da rivedere — mentre qui sono solo domande di servizio, e quello che resta è la
riga di conferma dell'inserimento.

## Cose da sapere

- **`user_states.json` sta accanto allo script** (`__DIR__`). Prima il percorso era
  relativo alla cartella di lavoro del processo, che con Apache non è garantita: se fosse
  cambiata, gli stati sarebbero finiti da un'altra parte e ogni risposta sarebbe stata
  letta come se fosse la prima, **senza un errore da nessuna parte**. Il file deve essere
  scrivibile dall'utente del web (`www-data`).
- **`setup_menu.php` va lanciato a mano** dopo il primo deploy e ogni volta che si
  cambiano i comandi.
- **Il prezzo si scrive come numero e basta** (`25.99` o `50`). Il bot rifiuta il resto e
  ripropone la domanda; il messaggio di errore si autocancella.
- **Gli inserimenti finiscono in `amazon_alert_log`** con azione, ASIN, autore e data.