api/TELEGRAM_MODULES.md

# backend/api — Moduli Telegram (M2 Split)

> **Refactor M2 — 2 Luglio 2026**
> Il monolite `telegram_webhook.py` (2844 righe, 5 hotfix consecutivi) è stato
> spezzato in 6 moduli a responsabilità singola. Hotfix futuri toccano **un solo file**.

---

## Grafo delle dipendenze

```
telegram_tg_client.py          (stdlib + httpx only)
        │
        ├──► telegram_keyboards.py     (solo costanti/dict — zero import interni)
        │           │
        │           ├──► telegram_cmd_monitoring.py
        │           │           └──► (esposto via telegram_webhook.py)
        │           │
        │           ├──► telegram_cmd_ai.py
        │           │           └──► (esposto via telegram_webhook.py)
        │           │
        │           └──► telegram_callbacks.py
        │                       ├── importa _cmd_do, _cmd_autofix ... da telegram_cmd_ai
        │                       └── importa _cmd_help, _cmd_status ... da telegram_cmd_monitoring
        │
        └──► telegram_webhook.py       (router FastAPI puro — importa da tutti)
                    └──► montato in backend/main.py come _tg_webhook_router
```

---

## Moduli

### `telegram_tg_client.py` — 276 righe
**Ruolo:** Telegram Bot API puro. Layer 0 senza dipendenze interne.

| Simbolo | Descrizione |
|---------|-------------|
| `_get_bot_token()` | Legge `TELEGRAM_BOT_TOKEN` dall'env |
| `_log_tg_exc(task)` | Log eccezioni fire-and-forget (Gap-2.6) |
| `_fmt_elapsed(sec)` | Formatta durata in human-readable |
| `_tg_reply(chat_id, text)` | Invia messaggio con parse_mode=HTML |
| `_tg_send(chat_id, text)` | Come reply, ritorna `message_id` |
| `_tg_edit(chat_id, msg_id, text)` | Modifica messaggio esistente |
| `_tg_photo(chat_id, url, caption)` | Invia foto via URL |
| `_tg_typing(chat_id)` | Invia `sendChatAction typing` |
| `_tg_react(chat_id, msg_id, emoji)` | Imposta reaction emoji |
| `_tg_answer_callback(callback_id)` | Risponde a `callback_query` (≤3s) |

**Import:** `asyncio, html, logging, os, time, httpx`

---

### `telegram_keyboards.py` — 109 righe
**Ruolo:** Costanti UI e keyboards. Zero logica, zero import interni.

| Simbolo | Tipo | Descrizione |
|---------|------|-------------|
| `_QUICK_PICK_KB` | `dict` | Inline keyboard selezione task rapida |
| `_MAIN_KB` | `dict` | Reply keyboard principale |
| `_BENCH_ACTION_KB` | `dict` | Keyboard post-benchmark |
| `_TASK_MENU_KB` | `dict` | Sub-menu task |
| `_STATUS_MENU_KB` | `dict` | Sub-menu stato sistema |
| `_PERF_MENU_KB` | `dict` | Sub-menu performance |
| `_HEALTH_MENU_KB` | `dict` | Sub-menu health |
| `_DEV_MENU_KB` | `dict` | Sub-menu developer |
| `_LAST_GOAL` | `dict[int,str]` | Memoria per bottone 🔁 Rifai |
| `_BENCH_CACHE` | `dict[int,dict]` | Ultimo run benchmark per chat |
| `_after_task_kb(chat_id)` | func | Keyboard dinamica post-task |

**Import:** solo `from __future__ import annotations`

---

### `telegram_cmd_monitoring.py` — 456 righe
**Ruolo:** Comandi di monitoraggio, stato e diagnostica.

| Comando / Funzione | Trigger Telegram |
|--------------------|-----------------|
| `_cmd_help(chat_id)` | `/start` `/help` `tgw_help` |
| `_cmd_logs(chat_id)` | `/logs` `tgw_logs` |
| `_cmd_status(chat_id)` | `/stato` `tgw_status` |
| `_cmd_commit_summary(chat_id)` | `/commit` `tgw_commits` |
| `_cmd_check(chat_id)` | `/salute` `tgw_health` |
| `_cmd_tasks(chat_id)` | `/attività` `tgw_tasks` |
| `_cmd_git(chat_id, args)` | `/git` `tgw_git` |
| `_cmd_coord(chat_id)` | `/coord` `tgw_coord` |
| `_cmd_scan_now(chat_id)` | `/scan` `tgw_scan` |
| `_cmd_telemetry(chat_id)` | `/telemetria` `tgw_telemetry` |

**Import:** stdlib + `telegram_tg_client` + `telegram_keyboards`

---

### `telegram_cmd_ai.py` — 1152 righe
**Ruolo:** Comandi AI, LLM e operativi. Modulo più pesante — contiene lo streaming loop.

| Comando / Funzione | Trigger Telegram |
|--------------------|-----------------|
| `_cmd_do(chat_id, goal)` | `/avvia` — lancia task AI con streaming |
| `_cmd_autofix(chat_id)` | `/fix` `tgw_autofix` |
| `_cmd_nota(chat_id, text)` | `/nota` `tgw_nota` |
| `_cmd_cerca(chat_id, query)` | `/cerca` `tgw_cerca` |
| `_cmd_meteo(chat_id, city)` | `/meteo` `tgw_meteo` |
| `_cmd_riepilogo(chat_id)` | `/riepilogo` `tgw_briefing` |
| `_cmd_score(chat_id)` | `/score` `tgw_score` |
| `_cmd_bench(chat_id)` | `/bench` `tgw_bench` |
| `_cmd_improve(chat_id, target)` | `/migliora` `tgw_improve` |

**Import:** stdlib + `telegram_tg_client` + `telegram_keyboards`

---

### `telegram_callbacks.py` — 353 righe
**Ruolo:** Smista `callback_query` e `inline_query` in arrivo da Telegram.

| Funzione | Descrizione |
|----------|-------------|
| `_handle_inline(iq, token)` | Risponde alle inline query (`@ARJagent_ap_bot testo`) |
| `_handle_callback(cb, token)` | Dispatch per tutti i `callback_data` `tgw_*` / `agent` / `qp_*` |

**Import:** `telegram_tg_client` + `telegram_keyboards` + `telegram_cmd_ai` + `telegram_cmd_monitoring`

> ⚠️ **Questo modulo crea dipendenze circolari potenziali** — non importare
> `telegram_callbacks` da `telegram_cmd_ai` o `telegram_cmd_monitoring`.

---

### `telegram_webhook.py` — 605 righe  *(era 2844)*
**Ruolo:** Router FastAPI puro. Solo endpoint HTTP, zero logica di business.

| Endpoint | Metodo | Descrizione |
|----------|--------|-------------|
| `/api/telegram/webhook` | POST | Ricezione update getUpdates (polling daemon) |
| `/api/telegram/process` | POST | Endpoint alternativo per CF Pages proxy |
| `/api/telegram/config/invalidate` | POST | Invalida cache config bot |

**Import:** FastAPI + tutti i 5 moduli sopra
**Montato in:** `backend/main.py` → `app.include_router(_tg_webhook_router)`

---

## Regole per gli hotfix

| Vuoi cambiare... | Tocca solo... |
|------------------|---------------|
| Aspetto di un bottone / label | `telegram_keyboards.py` |
| Risposta a un comando /help, /stato… | `telegram_cmd_monitoring.py` |
| Logica task AI / streaming / bench | `telegram_cmd_ai.py` |
| Routing dei bottoni inline (tgw_*) | `telegram_callbacks.py` |
| Helpers HTTP verso api.telegram.org | `telegram_tg_client.py` |
| Routing endpoint FastAPI | `telegram_webhook.py` |

---

## Daemon Node.js (scripts/lib/daemon-callbacks.mjs)

Il daemon usa **getUpdates polling** (non webhook registrato).
Riceve gli update, li smista ai command handler Python via HTTP interno.
Il flusso `callback_data tgw_*` viene elaborato da `telegram_callbacks.py::_handle_callback`.

```
Telegram ──► getUpdates daemon ──► POST /api/telegram/process
                                          │
                                    telegram_webhook.py (router)
                                          │
                              ┌───────────┴───────────┐
                         message?                callback_query?
                              │                        │
                    telegram_cmd_*.py        telegram_callbacks.py
                                                  ::_handle_callback
```