---
aliases: ["PowerBricks"]
type: modulo
parent: "MyICR Suite"
---

# CLAUDE.md — PowerBricks
**Versione:** v1
**Ultimo aggiornamento:** 2026-06-26

## Scopo

Visual Query Builder per utenti non tecnici — consente di interrogare la base dati Mediaset (4 domini: Anagrafica, Emesso, Diritti, Box Office) senza conoscere SQL. Blocchi visivi componibili → JSON → SQL → risultati.

Applicazione **read-only** nella forma base.

Documento di specifica completo: `C:\PYTHON\PowerBricks_Specifiche.pdf` (autore: Elon, 26/06/2026)

---

## Architettura tecnologica

| Layer | Tecnologia | Note |
|---|---|---|
| **Contenitore desktop** | **DA DECIDERE** | vedi nota sotto |
| **Frontend** | HTML/CSS/JS + Google Blockly | libreria open-source per blocchi visivi |
| **Backend** | Python + Flask (API REST locale) | riceve JSON albero blocchi → traduce in SQL |
| **Dati** | DuckDB su Parquet | stesso substrato di MyICR Suite |

**Contenitore — decisione aperta (2026-07-13):** opzioni in campo: PyQt6+QtWebEngine, PyWebView, Flask nel browser (come MediaTrack). Decidere con Mauro prima di scrivere codice. La nota precedente ("stesso stack di MediaTrack") era errata — MediaTrack è Flask+HTML puro, nessun PyQt6.

---

## 4 domini logici

| Dominio | Contenuto | Chiave join |
|---|---|---|
| **Anagrafica** | Metadati prodotti TV — titolo, genere, anno, regista | `program_id` (rifer) — perno centrale |
| **Emesso** | Storico trasmissioni — canale, data, orario, fascia | `program_id` |
| **Diritti** | Contratti, scadenze, passaggi, first-run/re-run | `program_id` — logica derivata, non semplice JOIN |
| **Box Office** | Incassi cinematografici, presenze | `program_id` |

---

## Motore di traduzione

- JOIN automatiche gestite dal backend — l'utente non le vede mai
- Perno sempre su **Anagrafica** (LEFT JOIN sistematico per non perdere titoli)
- **Diritti**: dominio speciale — richiede un layer di logica di business separato (passaggi residui, first-run vs re-run, inibizioni, titolarità %). È il pezzo più complesso e il cuore del valore.

Flusso: `Blocchi (mouse) → JSON albero → Flask → SQL → DuckDB → risultati`

---

## Doppio input (stessa piattaforma)

1. **Mouse** (primario): trascinamento mattoncini — utente non tecnico
2. **NL → blocchi** (evoluzione futura): LLM genera l'albero di blocchi, che resta ispezionabile e correggibile. NON bypassa PowerBricks — usa lo stesso traduttore. Zero query sbagliate in silenzio.

---

## Sequenza di sviluppo

1. **Layer semantico** — mappa campi + grafo relazioni + logica business diritti ← pezzo fondante
2. **PowerBricks read-only** — blocchi → JSON → SQL → risultati
3. **Generatore NL → blocchi** — montato sopra lo stesso layer
4. **Fase due** — scheduling query + recapito via email (richiede processo sempre attivo — decisione locale vs servizio da affrontare quando si arriva qui)

---

## NL Query — BI conversazionale (2026-06-08)

**Fase 1 in corso** — validazione qualità su domande reali, zero sviluppo.

### File
- `NL_semantic_layer/NL_QUERY_SCHEMA.md` — dizionario dati completo (v1.1): tutti i parquet L2 + linker.db + ott.db + mediatrack.db, 16 gotcha
- `NL_semantic_layer/NL_QUERY_PATTERNS.md` — pattern interpretativi e convenzioni output
- `.claude/commands/nlquery.md` — skill `/nlquery`

### Convenzioni output stabilite
- Prima colonna sempre `p.program_id AS rifer`
- Scadenze aggregate: `MAX(scad) AS scadenza` (una sola colonna)
- Prime time: `fascia = 'PR'`
- Film italiano: `tipologia='FILM'` + `paesi_produzione1/2/3 = 'I'`
- Ambiguità: chiedere sempre prima di eseguire
- CSV: separatore `;`, UTF-8-sig, intestazioni MAIUSCOLO_UNDERSCORE

### OTT sheet (2026-06-05) — completato
- Architettura due tabelle: OTT (`local_db/ott.db`, 332.177 record) + OTT_EXT (`sync_db/linker.db`, 148.253)
- PK con COLLATE NOCASE su provider (fix duplicati Chili/CHILI)
- Tutti i campi VARCHAR(255) per compatibilità ODBC/Access
- movie_filtrato = 122 (replica VBA): fascia SVOD, provider Netflix/Amazon/Apple, EM filter, cutoff 3 batch

---

## Ambiente

- Tier 2 — venv condiviso `C:\PYTHON\_runtimes\venv\`
- PyQt6 == 6.7.0 PINNED — NON upgradare
- Python 3.11.9