# Lead Finder

> Strumento interno di Shawe Solutions per trovare, arricchire e convertire potenziali clienti.
> Progettato perché a usarlo siano soprattutto modelli e agenti AI.

## Cos'è

Shawe Solutions vende cinque cose, e Lead Finder serve a trovare chi potrebbe comprarle:

- **Shawe** (`shawe`) — Gestionale prenotazioni per il wellness.
- **Shawe Art** (`shawe_art`) — Gestionale inventario e vendite per chi vende arte.
- **Sito web custom** (`website`) — Progettazione e sviluppo di un sito su misura.
- **Automazioni AI** (`ai_automation`) — Automazione di processi ripetitivi con AI.
- **Soluzioni su misura** (`custom`) — Sviluppo custom fuori dai prodotti standard.

Un *lead* è un'attività commerciale reale. Il lavoro consiste nel capire di cosa ha bisogno,
raccogliere prove, dare un punteggio, produrre qualcosa di concreto e registrare tutto.

## Come si usa

Serve una chiave API, passata come `Authorization: Bearer <chiave>`. La stessa chiave vale
sia per le API REST sia per il server MCP.

- **REST**: `https://ricercatore.shawe.it/api/v1` — schema completo su [https://ricercatore.shawe.it/api/v1/openapi.json](https://ricercatore.shawe.it/api/v1/openapi.json)
- **MCP**: `https://ricercatore.shawe.it/api/mcp` (streamable HTTP) — vedi `docs/mcp.md` nel repository
- **Questa pagina**: chiamando `https://ricercatore.shawe.it/` con una chiave API e `Accept: text/markdown`
  ricevi **un lead diverso ogni volta**, già assegnato a te e lockato per 30 minuti.

## Se hai trovato un'attività nuova

Non controllare prima se esiste: lo fa il sistema. Manda quello che hai e ricevi in risposta
su quale lead è finito e cosa è cambiato.

- una pagina web: `POST /api/v1/ingest/url`, o il tool MCP `ingest_url`
- un PDF (visura, elenco camerale): `POST /api/v1/ingest/file`, o `ingest_file`
- un elenco CSV: `POST /api/v1/ingest/csv`, o `ingest_csv`
- dei campi che hai già in mano: il tool MCP `record_business`

Il confronto è su partita IVA, scheda Google, telefono normalizzato e dominio del sito: se uno
combacia, l'attività viene riconosciuta e aggiornata. Se si somigliano soltanto, il sistema non
fonde: crea la scheda e lascia la coppia da confermare a una persona.

## Il flusso di lavoro

1. Prendi un lead: `POST /api/v1/leads/next`, oppure il tool MCP `claim_next_lead`.
2. Leggi cosa sappiamo già: `GET /api/v1/leads/{id}`.
3. Raccogli quello che manca e registralo: `POST /api/v1/lead-data`.
   **Ogni dato deve avere una fonte e un livello di affidabilità.**
4. Assegna un punteggio con le motivazioni: `POST /api/v1/leads/{id}/score`.
5. Produci qualcosa e registralo: `POST /api/v1/assets`.
6. Aggiorna lo stato: `POST /api/v1/leads/{id}/status`. Portandolo a `in_progress`
   nasce da sola una bozza di proposta, precompilata con quello che sappiamo.
7. Prepara il documento: `GET /api/v1/contracts?leadId=...` per trovarlo,
   `PATCH /api/v1/contracts/{id}` per servizi, prezzi e clausole,
   `POST /api/v1/contracts/{id}/generate` per comporre il testo.

## Documenti commerciali

Proposte, contratti, NDA, DPA, preventivi, verbali di consegna, schede di onboarding,
informative privacy ed email di primo contatto sono lo stesso meccanismo: un template fatto
di sezioni, dei dati, una generazione deterministica.

- `GET /api/v1/templates` — i template con le loro sezioni, le clausole opzionali che puoi
  attivare e l'elenco delle variabili `{{...}}`.
- `GET /api/v1/pricing` — il listino. Gli importi sono in centesimi: 90000 è 900,00 €.
- `POST /api/v1/contracts` — bastano `leadId` e `type`: i dati del cliente vengono dai
  valori risolti del lead, i servizi dai suoi `fitServices`, i prezzi dal listino e i
  termini dai default. Quello che passi tu vince su tutto questo.
- `GET /api/v1/contracts/{id}/data-updates` — cosa il lead ha imparato dopo la creazione del
  documento. `POST` sullo stesso indirizzo lo applica, saltando i campi scritti a mano.
- `POST /api/v1/contracts/{id}/generate` — compone il testo. Deterministico: nessun modello
  viene chiamato, e rigenerare senza cambiamenti non crea una seconda versione.
- `POST /api/v1/contracts/derive` — preventivo, email di primo contatto, onboarding,
  informativa privacy o verbale di consegna, riusando i dati che ci sono già.

I template valgono per tutti i clienti e li modifica solo un amministratore: con
`contracts:write` scegli servizi e clausole su un documento, non riscrivi quello che
mandiamo a tutti.

## Regole

- Non inventare dati. Se non trovi un'informazione, registra che non l'hai trovata.
- Ogni valore ha una fonte: `GET /api/v1/leads/{id}/field-values` dice chi ha detto cosa e
  perché quel valore è quello mostrato. Guardalo prima di correggere un campo a mano.
- Ogni contenuto prodotto per un lead va registrato, anche se costruito altrove.
- Un punteggio senza motivazioni viene rifiutato.
- Un documento generato va **riletto** prima di mandarlo: è composto dai dati, non
  revisionato. Se la risposta elenca `missingVariables`, quei campi nel testo sono spazi
  vuoti da compilare.
- Scrivi in italiano tutto ciò che leggerà una persona.

## Formato delle risposte

Ogni endpoint REST risponde con `{ ok, data, error, hints }`.
`error` porta un `code` stabile e un `hint` che dice cosa fare per rimediare.
`hints` suggerisce il passo successivo: sono consigli, non istruzioni.

## Altro

- [/llms-full.txt](https://ricercatore.shawe.it/llms-full.txt) — la versione completa, con tutti i valori ammessi
- [/api/v1/openapi.json](https://ricercatore.shawe.it/api/v1/openapi.json) — lo schema OpenAPI