# Platform Blueprint — CRM multi-bot

Piattaforma PHP che vende e gestisce **più bot** (catalogo prodotti), con login Telegram, abbonamenti, promo e back office.

Il bot attuale in questa repo diventa il primo prodotto: **`verify-videonote`**.

---

## 1. Layout cartelle (target)

```
htdocs/
  platform/                      ← questo scheletro (in repo: ./platform)
    public/                      ← document root del dominio
      index.php                  ← landing
      assets/
    app/                         ← area cliente (loggata)
    admin/                       ← back office tuo
    hooks/                       ← webhook Stripe / Telegram login callback
    src/
      Auth/ TelegramAuth.php
      Billing/ PromoService.php, SubscriptionService.php
      Catalog/ BotProduct.php, PlanService.php
      Db.php
    storage/
      platform.sqlite            ← o MySQL in produzione
    config.example.php
    schema.sql
  bots/
    verify-videonote/            ← oggi: questa repo (htdocs/bot)
    altro-bot/
  shared/                        ← opzionale: client Telegram, i18n comune
```

**Ora (fase 1):** lo scheletro vive in `./platform` dentro questa repo.  
**Dopo:** sposti `platform/` a `htdocs/platform` e rinomini questo progetto in `htdocs/bots/verify-videonote`.

---

## 2. Mappa URL

| URL | Chi | Cosa |
|-----|-----|------|
| `/` | pubblico | Landing + catalogo bot |
| `/bots/{slug}` | pubblico | Scheda prodotto (prezzi, feature, CTA) |
| `/pricing` | pubblico | Confronto piani |
| `/login` | pubblico | Telegram Login Widget |
| `/auth/telegram` | sistema | Callback login Telegram |
| `/logout` | loggato | Esci |
| `/app` | user | Dashboard: bot acquistati / trial |
| `/app/bots/{slug}` | user | Dettaglio bot + “Aggiungi al gruppo” + stato piano |
| `/app/billing` | user | Fatture, rinnovi, inserisci promo |
| `/app/groups` | user | Gruppi collegati ai suoi bot |
| `/checkout/{plan_id}` | user | Checkout (Stripe) + campo promo |
| `/admin` | super-admin | Overview MRR, bot, abbonamenti |
| `/admin/bots` | super-admin | CRUD prodotti bot |
| `/admin/plans` | super-admin | Prezzi per bot |
| `/admin/promos` | super-admin | Codici sconto a tempo |
| `/admin/customers` | super-admin | Clienti (telegram_id) |
| `/admin/subscriptions` | super-admin | Abbonamenti attivi/scaduti |
| `/admin/groups` | super-admin | Tutti i gruppi installati |
| `/hooks/stripe` | sistema | Webhook pagamenti |
| `/hooks/bot/{slug}` | Telegram | Webhook runtime del bot (proxy o include) |

Deep link Telegram utili:

- `https://t.me/{bot}?start=claim_{token}` — collega account dopo acquisto  
- `https://t.me/{bot}?startgroup=true` — aggiungi al gruppo  

---

## 3. Ruoli

| Ruolo | Come si riconosce |
|-------|-------------------|
| Guest | non loggato |
| Customer | `users` con login Telegram |
| Platform admin | `users.is_platform_admin = 1` (i tuoi `admin_ids`) |
| Bot group admin | admin del gruppo Telegram (gestito nel bot, non nel CRM) |

---

## 4. Flussi principali

### Acquisto
1. Guest apre `/bots/verify` → sceglie Pro  
2. Login Telegram se serve  
3. Opzionale: codice promo `ESTATE20`  
4. Stripe Checkout  
5. Webhook → `subscriptions` active  
6. Redirect `/app/bots/verify` → “Aggiungi al gruppo”

### Runtime bot
1. Gruppo fa `/setgroup`  
2. Bot registra `bot_installations` (platform DB) o sincronizza  
3. Prima di feature Pro: `PlanService::allows(installation, 'link_filter')`  
4. Se Free / scaduto → messaggio upgrade con link `/bots/verify`

### Promo
1. Admin crea in `/admin/promos`  
2. Checkout valida: date, max_uses, product/plan, active  
3. Ordine salva `promo_code_id` + sconto applicato  
4. Incrementa `promo_codes.uses_count`

---

## 5. Collegamento al bot attuale

Nel bot (verify), aggiungere in seguito:

```php
// Pseudocodice
$plan = PlatformClient::planForGroup($groupId);
if (!$plan->allows('link_filter')) {
    // blocca UI o runtime
}
```

Opzioni:
- **A)** Stesso SQLite/MySQL della platform (più semplice in locale)  
- **B)** HTTP API interna `GET /api/entitlements?group_id=` (meglio se bot e platform su path diversi)

Fase 1 consigliata: **stesso DB** (`platform.sqlite` o MySQL), tabella `bot_installations` + `subscriptions`.

---

## 6. Prezzi (seed iniziale suggerito)

Prodotto `verify` (questo bot):

| Plan code | Nome | Prezzo/mese | Feature principali |
|-----------|------|-------------|--------------------|
| `verify_free` | Free | 0 | verifica manuale, 1 gruppo, blacklist 20 |
| `verify_pro` | Pro | 12.00 EUR | auto/ibrida, sicurezza, link, VIP, warn, media, ripetuti |
| `verify_biz` | Business | 39.00 EUR | multi-gruppo illimitato, export, webhook, dashboard |

Altri bot = altri `products` + `plans` nello stesso schema.

---

## 7. Ordine di implementazione

1. Schema SQL + seed prodotti/piani  
2. Config + Db PDO  
3. Landing catalogo (statica/dinamica da `products`)  
4. Telegram Login + sessioni  
5. `/app` lista ownership da `subscriptions`  
6. Admin CRUD plans + promos  
7. Stripe (o pagamento manuale “segna come pagato” per MVP)  
8. Hook entitlement nel bot verify  

---

## 8. Cosa non fare

- Non copiare l’intera cartella bot per ogni cliente  
- Non mettere prezzi hardcoded nel bot  
- Non creare un CRM separato per ogni bot  
- Non salvare token bot in chiaro senza cifratura in produzione