# TieMeasureFlow V1.0.7 → V1.1.0 (rev04-2026) — Master Roadmap

> **Tipo documento:** Master plan / roadmap. Non contiene task eseguibili TDD — rimanda ai sotto-piani per-fase.
> **Spec sorgente:** `Schema sviluppo SW TieFlow_rev04-2026.docx` + `PIANO_IMPLEMENTAZIONE.md` v1.0.
> **Target deployment:** Scenario B — container `tmflow-client` distribuito a ogni tablet/PC industriale, un `tmflow-server` centralizzato su VPS.

**Goal:** Portare TieMeasureFlow da V1.0.7 (funzionalità base: ricette, misure, SPC) a V1.1.0 allineata alla rev04: integrazione GAIA, stazioni per-tablet, ruolo capoturno, editor ricetta a blocchi, workflow operatore stretto (retry/timer/cicalino/avvio produzione), deploy docker per-tablet con registry privato.

## Strategia di Rilascio (revisione 2026-04-17)

Priorità aggiornata dal committente: **consegnare al cliente un sistema funzionante di test il prima possibile**. Il deploy Scenario B (registry + Watchtower + immagini pubblicate) è esplicitamente **rimandato alla fine dello sviluppo**.

Il programma si articola quindi in due milestone:

| Milestone | Contenuto | Obiettivo |
|---|---|---|
| **M1 — Demo cliente** | Fasi 1-5 del piano (modello dati, capoturno, editor blocchi, workflow operatore, GAIA **import-only con dati reali**) + deploy "demo" semplice (single docker-compose su VPS demo, senza registry) | Sistema testabile end-to-end dal cliente con i suoi dati, per raccogliere feedback sul workflow operatore prima di integrare GAIA live e andare in produzione. |
| **M2 — Produzione** | Fase 6 (Deploy B industriale) + Fase 7 (hardening, E2E, rollout pilota) + eventuali aggiustamenti post-feedback M1 | Rollout su tablet/PC reali del cliente. |

Conseguenze operative:
- **Dati reali, non mock:** M1 parte con contenuti veri del cliente (articoli, ricette, stazioni). Niente `MockGaiaClient`: in Fase 5 per M1 sviluppiamo solo il canale di **import one-shot** (endpoint admin che accetta un export GAIA in CSV/JSON, più UI Maker per editing manuale). L'integrazione GAIA live (polling, comandi produzione real-time) slitta a M2. Il cliente ci fornirà una snapshot dati all'inizio di M1.
- L'interfaccia astratta `GaiaClient` viene comunque disegnata in M1 (per non accumulare debito) ma in M1 resta implementata da un `ImportOnlyGaiaClient` che legge da file/DB senza contattare GAIA. I comandi produzione (`start/pause/resume/end`) in M1 scrivono su `production_events` locali — a M2 aggiungiamo l'implementazione che li invia a GAIA.
- Il deploy M1 usa un singolo `docker-compose.yml` su VPS di test con porte esposte a dominio di demo (HTTPS con Let's Encrypt tramite Traefik già presente in V1.0.7). Nessun registry privato, nessun Watchtower, build locale + push con `docker compose up --build`.
- Durante M1 il cliente testa da browser direttamente contro la VPS demo; i "tablet" in quella fase sono semplicemente browser puntati all'URL demo.
- Il feedback M1 può rimodulare le fasi di M2 (es. scoprire che serve un ruolo in più, che il cicalino va cambiato, che il protocollo GAIA va rivisto).

**Architecture:**
- Server FastAPI centralizzato su VPS — unico nodo che parla a GAIA, detiene DB MySQL, genera report, calcola SPC.
- Client Flask impacchettato come `tmflow-client:<version>` pubblicato su registry privato della VPS; ogni tablet/PC industriale pulla la propria copia e si identifica via `STATION_ID` nel `.env`.
- Capoturno come ruolo separato con flusso di override a token a scadenza breve.
- Ricetta estesa a blocchi tipizzati: preparazione documentale + misura vincolata a tolleranze.
- Parametri volatili di ricetta (timer, max_retries) isolati dalla versione immutabile.

**Tech Stack (invariato rispetto a V1.0.7):**
- Server: FastAPI, SQLAlchemy 2.0 async, MySQL 8, Alembic, Pydantic v2, WeasyPrint, Plotly+Kaleido, APScheduler (nuovo, per sync GAIA).
- Client: Flask, Jinja2, Alpine.js, TailwindCSS, Fabric.js, Plotly.js, html5-qrcode, Web Serial, Flask-Babel.
- Nuove integrazioni: adapter GAIA (protocollo TBD col cliente).
- Deploy: Docker registry privato (`registry:2`) sulla VPS + Watchtower sui tablet per auto-update.

---

## 0. Precondizioni e Decisioni Aperte (RISOLVERE PRIMA DI INIZIARE)

Queste scelte sono **prerequisiti**: iniziare senza risolverle produce rework sicuro.

| # | Decisione | Opzioni | Chi decide | Stato |
|---|---|---|---|---|
| D-0.1 | Protocollo integrazione GAIA | REST, DB shared, OPC-UA, file scambio | Cliente + noi | **Aperta** |
| D-0.2 | Credenziali e rete GAIA | VPN, firewall, whitelist IP | IT cliente | **Aperta** |
| D-0.3 | Target hardware "tablet" | Tablet Windows consumer, PC touch industriale Linux, tablet Android | Cliente | **Aperta** (critica per B) |
| D-0.4 | Cicalino/luce avviso | Audio browser HTML5, hardware USB locale, entrambi | Cliente | **Rimandato a M2** (non bloccante M1) |
| D-0.5 | Parametri runtime modificabili vs versione immutabile | A: ogni modifica crea versione; B: separare volatili da strutturali | Noi (raccomandato B) | **Aperta** |
| D-0.6 | Autenticazione capoturno durante override | Login sovrapposto modale, PIN rapido, badge RFID | Cliente | **Aperta** |
| D-0.7 | Timeout auto-logout | Valore default + configurabilità | Cliente | **Risolta:** configurabile via `system_settings` (chiave `auto_logout_minutes`, default 15), con override opzionale per-utente in colonna `users.auto_logout_minutes` (NULL = usa globale). |
| D-0.8 | Naming ruolo capoturno | `Supervisor`, `ShiftLeader`, `Capoturno` | Noi | Proposta: `Supervisor` (già inglese come gli altri) |
| D-0.9 | Tag versione immagine docker | `latest`, SemVer, git sha | Noi | Proposta: SemVer + `latest` |
| D-0.10 | Registry esposto su Internet o solo VPN | Internet+auth, solo VPN | Cliente + noi | Proposta: solo VPN cliente |

**Azione richiesta:** aprire una riunione di allineamento col cliente su D-0.1, D-0.2, D-0.3, D-0.4, D-0.6 prima di Fase 1.

---

## Fasi (ordine consigliato)

Capoturno (Fase 2) è precondizione del workflow operatore (Fase 4). GAIA (Fase 5) può partire in parallelo a Fase 2-3 dopo Fase 1. Fase 6 (deploy industriale B) parte **solo dopo il feedback cliente su M1**.

```
  ┌─────────────────────────── M1 — Demo per cliente ────────────────────────────┐
  │                                                                               │
  │   ┌───────────────────────────────────────────────────┐                       │
  │   │  Fase 1 — Stazioni + identità per-tablet           │  1.5-2 settimane     │
  │   └───────────────┬──────────────────────────────────┘                       │
  │                   │                                                           │
  │       ┌───────────┼─────────────────────┐                                    │
  │       │           │                     │                                    │
  │       ▼           ▼                     ▼                                    │
  │   Fase 2      Fase 3                Fase 5 (import-only)                     │
  │   Capoturno   Editor a blocchi      ImportOnlyGaiaClient + UI import          │
  │       │           │                     │          (paralleli, ~2-3 sett.)   │
  │       └─────┬─────┘                     │                                    │
  │             ▼                           │                                    │
  │         Fase 4 — Workflow operatore    │           2-3 settimane              │
  │         (retry/timer/autologout/avvio) │                                     │
  │             │                           │                                    │
  │             └──────────┬───────────────┘                                    │
  │                        ▼                                                     │
  │               Demo deploy su VPS test                ~2 giorni               │
  │               (docker-compose single-file,                                    │
  │                Traefik+LE, no registry,                                       │
  │                dati reali cliente importati)                                  │
  │                        │                                                     │
  └────────────────────────┼─────────────────────────────────────────────────────┘
                           │
                 ═══  CHECKPOINT: feedback cliente su M1  ═══
                           │
  ┌─────────────────────── M2 — Produzione ─────────────────────────────────────┐
  │                        │                                                     │
  │                        ▼                                                     │
  │               Adjustments post-feedback            variabile                 │
  │               (modifiche workflow, UX, GAIA reale)                            │
  │                        │                                                     │
  │                        ▼                                                     │
  │               Fase 5 reale — GAIA integrazione     1-2 settimane              │
  │               (protocollo definitivo, credenziali,                            │
  │                rete cliente, feature flag)                                    │
  │                        ▼                                                     │
  │               Fase 6 — Deploy B industriale        1 settimana                │
  │               (registry + watchtower + compose                                │
  │                split server/client, STATION_ID,                               │
  │                CI release)                                                    │
  │                        ▼                                                     │
  │               Fase 7 — Hardening & rollout         1-2 settimane              │
  │               (security review, e2e sito pilota,                              │
  │                docs aggiornati, i18n delta)                                   │
  │                                                                              │
  └──────────────────────────────────────────────────────────────────────────────┘
```

**Stima a M1 (sistema demo testabile):** ~6-7 settimane full-time; ~4-5 settimane con 2 fasi in parallelo.
**Stima totale fino a M2:** ~9-11 settimane full-time (include feedback cycle stimato 1-2 settimane).

---

## Fase 1 — Stazioni e Identità per-tablet

**Obiettivo:** modellare il concetto di "stazione di controllo", associare ricette a stazioni, far sì che ogni client carichi solo le ricette della propria stazione identificata da `STATION_ID`.

**Sotto-piano:** `docs/superpowers/plans/2026-04-17-rev04-phase1-stations.md`

**Deliverable:**
- Tabelle `stations`, `station_recipe_assignments` + migration Alembic.
- Endpoint `GET /api/stations`, `POST /api/stations`, `PUT /api/stations/{id}`, `GET /api/stations/{id}/recipes`.
- Schema auth: API key del client associata a una stazione → ogni request porta identità di stazione implicita.
- Variabile d'ambiente `STATION_ID` nel client Flask, letta a startup, usata per filtrare `/api/recipes` in `select_recipe`.
- UI admin per gestire stazioni + assegnazioni.
- Test: un client con STATION_ID=A vede solo le ricette assegnate ad A.

**File impattati principali:**
- Nuovi: `server/models/station.py`, `server/routers/stations.py`, `server/schemas/station.py`, `server/services/station_service.py`, `client/templates/admin/stations.html`, `server/migrations/versions/<hash>_add_stations.py`.
- Modificati: `server/main.py` (registra router), `server/models/__init__.py`, `server/routers/recipes.py` (filtro by station), `client/config.py` (`STATION_ID`), `client/blueprints/measure.py` (passa STATION_ID alle query), `client/blueprints/admin.py` (CRUD stazioni), `client/blueprints/auth.py` (usa API key specifica di stazione).

**Rischi:** rotture retrocompatibilità API se cambiamo signature endpoint esistenti → mitigare con parametro opzionale `station_id` e default None = backward compat.

---

## Fase 2 — Ruolo Capoturno (Supervisor) e Override

**Obiettivo:** introdurre ruolo `Supervisor`, endpoint di override a token breve, UI login-sovrapposto per autorizzazioni puntuali.

**Sotto-piano:** `docs/superpowers/plans/2026-04-17-rev04-phase2-supervisor.md`

**Deliverable:**
- Estensione enum ruoli con `Supervisor` + dependency `require_supervisor`.
- Tabella `supervisor_overrides` (id, requested_by, authorized_by, override_type, target_ref, created_at, consumed_at, reason).
- Endpoint `POST /api/supervisor/override` che valida credenziali supervisor e ritorna `override_token` JWT-like (firmato, TTL 60s).
- Endpoint `POST /api/supervisor/override/verify` usato da altri router prima di eseguire azioni protette.
- Componente Alpine.js `supervisor-modal` riusabile: apertura modale, login, callback con token.
- Audit trail: ogni override consumato logga `consumed_at` + contesto.

**Tipi di override previsti:**
- `FORCE_OUT_OF_TOLERANCE` — operatore vuole confermare misura fuori tolleranza.
- `RESET_RETRY_COUNTER` — sbloccare dopo N tentativi falliti.
- `PAUSE_PRODUCTION` — fermo linea (invierà comando GAIA in Fase 5).
- `END_PRODUCTION` — fine produzione (chiude timer GAIA in Fase 5).
- `EDIT_RUNTIME_PARAMS` — modificare timer/max_retries della ricetta in corsa.

**File impattati principali:**
- Nuovi: `server/models/supervisor_override.py`, `server/routers/supervisor.py`, `server/services/supervisor_service.py`, `server/schemas/supervisor.py`, `client/templates/components/supervisor_modal.html`, `client/static/js/supervisor-modal.js`.
- Modificati: `server/models/user.py` (commento ruoli), `server/middleware/api_key.py` (nuova dep `require_supervisor`), `client/blueprints/measure.py` (consuma token).

---

## Fase 3 — Editor Ricetta a Blocchi (Preparazione + Misura)

**Obiettivo:** estendere il concetto di `RecipeTask` a blocchi tipizzati: `preparation` (documentale: materiali, imballo, temperatura) e `measurement` (con subtask + tolleranze + timer intervallo).

**Sotto-piano:** `docs/superpowers/plans/2026-04-17-rev04-phase3-block-editor.md`

**Deliverable:**
- Migration: aggiunge `block_type ENUM('preparation', 'measurement')` e `measurement_interval_seconds INT NULL`, `max_retries INT NOT NULL DEFAULT 3`, `preparation_content LONGTEXT NULL` a `recipe_tasks`.
- Backfill: tutti i task esistenti → `block_type='measurement'`.
- Editor UI: toggle tipo blocco nel task editor; blocchi preparazione usano rich-text editor (TipTap light o textarea con markdown + preview) e accettano upload PDF/immagine opzionale.
- MeasurementTec UI: blocchi preparazione visualizzati come "scheda documentale" con pulsante "Ho letto, procedi"; blocchi misura invariati.
- Parametri volatili: nuove colonne `measurement_interval_seconds` e `max_retries` sono modificabili senza creare nuova versione (Decisione D-0.5 opzione B).

**File impattati principali:**
- Migration Alembic.
- Modificati: `server/models/task.py`, `server/schemas/task.py`, `server/services/recipe_service.py` (copy-on-write copia anche nuovi campi), `client/templates/maker/task_editor.html`, `client/static/js/annotation-editor.js` (skip per blocchi prep), `client/templates/measure/task_execute.html` (branch per tipo blocco), nuovo `client/templates/measure/preparation_view.html`.

---

## Fase 4 — Workflow Operatore: Retry, Timer, Autologout, Avvio Produzione

> Nota: feedback sonoro (cicalino avvio misura + luce continua) **rimandato a M2**. M1 usa solo notifiche visive.

**Obiettivo:** implementare le regole stringenti della rev04 sul flusso operatore.

**Sotto-piano:** `docs/superpowers/plans/2026-04-17-rev04-phase4-workflow.md`

**Deliverable:**

| Feature | Implementazione |
|---|---|
| N tentativi max poi Supervisor | Contatore in session Flask per `(measurement_session_id, subtask_id)`. Al superamento: modale Supervisor (Fase 2) per reset. |
| Auto-avanzamento solo se pass | Logica JS: se `pass_fail != 'pass'`, bottone "Avanti" disabilitato finché operatore non richiede conferma Supervisor (override FORCE_OUT_OF_TOLERANCE). |
| Log-out bloccato durante attività | Flag `measurement_session.is_active`. Link "Logout" in navbar nascosto/disabilitato se attiva. Endpoint `POST /api/auth/logout` respinge con 409 se sessione attiva senza override. |
| Auto-logout inattività | Alpine store `idle-timer` con event listeners `pointermove/keydown`. Alla scadenza (default 15m, config per-utente o globale) → redirect a `/logout`. |
| ~~Cicalino avvio misura~~ | **Rimandato a M2.** In M1 nessun feedback sonoro: al tick 0 del timer si mostra solo notifica visiva (toast + highlight subtask). |
| ~~Luce/cicalino continuo~~ | **Rimandato a M2.** |
| Timer intervallo tra misure | Countdown JS che legge `measurement_interval_seconds`. Al tick 0: notifica visiva + mostra subtask + sblocca input calibro. |
| "Avvio produzione" post-prima-misura | Bottone UI visibile solo dopo prima misura confermata. Chiamata `POST /api/gaia/production/start` (Fase 5). |
| "Fermo linea" / "Fine produzione" | Due bottoni protetti da Supervisor override. Chiamate GAIA (Fase 5). |

**File impattati principali:**
- Modificati: `client/blueprints/measure.py`, `client/templates/measure/task_execute.html`, `client/static/js/numpad.js` (estende con retry counter), nuovo `client/static/js/idle-timer.js`, nuovo `client/static/js/production-timer.js`, `client/static/js/caliper.js` (hook conferma esplicita).
- Server: aggiunge `measurement_sessions` table (id, user_id, recipe_version_id, station_id, started_at, ended_at, is_active), endpoint start/end.

**Dipendenza:** Fase 2 (Supervisor) e Fase 3 (blocchi con timer) devono essere completate.

---

## Fase 5 — Adapter GAIA

**Obiettivo:** integrare il MES GAIA per sync ricette-stazioni e comandi produzione.

**Sotto-piano:** `docs/superpowers/plans/2026-04-17-rev04-phase5-gaia.md`

**Scope per milestone:**
- **M1 (dati reali, no live GAIA):**
  - Interfaccia astratta `GaiaClient` disegnata per intero (tutti i metodi previsti).
  - Implementazione `ImportOnlyGaiaClient`: `fetch_station_articles` legge da DB popolato via import one-shot; i comandi `start/pause/resume/end` scrivono in una nuova tabella `production_events` locale (sorgente di verità per la demo, poi verrà replicata a GAIA in M2).
  - Endpoint admin `POST /api/admin/gaia-import` che accetta un file (CSV o JSON) esportato dal cliente e popola `station_recipe_assignments` + articoli. Parser tollerante con report errori riga per riga.
  - UI admin `/admin/gaia-import` per uploadare il file, previeware i dati, confermare l'import.
  - Export retro-compatibile: `GET /api/admin/production-events/export` restituisce il JSON/CSV dei `production_events` accumulati (il cliente può caricarlo manualmente in GAIA in M1 se gli serve).
  - Nessuna rete verso GAIA, nessuna credenziale GAIA richiesta per M1.
- **M2:** implementazione concreta `LiveGaiaClient` del protocollo definitivo (REST/DB/altro) in base a D-0.1, credenziali, rete cliente, circuit breaker, monitoring. I `production_events` accumulati da M1 diventano la coda che `LiveGaiaClient` drena verso GAIA al primo avvio.

**Contratto comune (disegnato in M1, usato da entrambe le implementazioni):**

```python
# server/services/gaia_client.py
class GaiaClient(Protocol):
    async def fetch_station_articles(self, station_code: str) -> list[StationArticle]: ...
    async def start_production(self, article_code: str, station_code: str, operator_id: str) -> None: ...
    async def pause_production(self, article_code: str, station_code: str, reason: str) -> None: ...
    async def resume_production(self, article_code: str, station_code: str) -> None: ...
    async def end_production(self, article_code: str, station_code: str, stats: ProductionStats) -> None: ...
```

**Deliverable M1 — `ImportOnlyGaiaClient`:**
- Lettura articoli/ricette dal DB interno popolato via import one-shot.
- Comandi produzione persistiti in tabella `production_events` (no rete esterna).
- Endpoint `POST /api/admin/gaia-import` (upload CSV/JSON export GAIA) + UI `/admin/gaia-import` con preview e conferma.
- Endpoint `GET /api/admin/production-events/export` per esportare gli eventi accumulati (JSON/CSV) da caricare manualmente su GAIA se serve.
- Endpoint `POST /api/gaia/production/{start,pause,resume,end}` usati dal client Flask.
- Config `.env`: `GAIA_MODE=import_only` (default in M1).

**Deliverable M2 — `LiveGaiaClient`:**
- Implementazione concreta del protocollo definitivo (REST/DB/altro) in base a D-0.1.
- Job APScheduler ogni 60s: per ogni stazione attiva, chiama `fetch_station_articles`, aggiorna `station_recipe_assignments`.
- Drain iniziale dei `production_events` accumulati verso GAIA.
- Config `.env`: `GAIA_MODE=live`, `GAIA_BASE_URL`, `GAIA_AUTH_TOKEN`, `GAIA_POLL_INTERVAL_SECONDS`.
- Circuit breaker: se GAIA giù, non bloccare operazioni interne; accoda su `production_events` e degrada a warning in UI.

**File impattati principali:**
- Nuovi in M1: `server/services/gaia_client.py` (Protocol + `ImportOnlyGaiaClient`), `server/services/gaia_import.py`, `server/routers/gaia.py` (production events), `server/routers/admin_gaia.py` (import), `server/schemas/gaia.py`, `server/models/production_event.py`, `client/blueprints/admin.py` (aggiunge route import), `client/templates/admin/gaia_import.html`, `server/tests/test_gaia_import_only.py`.
- Aggiunti in M2: `server/services/gaia_live_client.py`, `server/services/gaia_sync.py` (scheduler), `server/tests/test_gaia_live.py`.
- Modificati: `server/main.py` (lifespan avvia APScheduler solo in modalità live), `server/config.py` (nuove variabili).

---

## Fase M1-Demo — Deploy Demo per Cliente (tra Fase 4 e checkpoint feedback)

**Obiettivo:** dopo Fasi 1-4 e Fase 5 import-only, mettere online una demo accessibile al cliente via HTTPS su dominio di test, **con i dati reali del cliente** (articoli, ricette, stazioni).

**Deliverable:**
- `docker-compose.demo.yml`: estensione del `docker-compose.yml` prod esistente con Traefik + Let's Encrypt puntato a dominio `demo.tielogic.<tld>` (o sottodominio dedicato), MySQL vuoto pronto per l'import, server e client buildati localmente (no registry).
- Seed minimo: solo utenti di esempio per ogni ruolo (MeasurementTec, Maker, Metrologist, Supervisor, Admin) + una stazione "default". Articoli e ricette non vengono seedati: vengono importati dal cliente (o da noi a suo nome) via `/admin/gaia-import` con il file export GAIA reale.
- Pagina `/admin/demo-reset` (protetta da SETUP_PASSWORD) che ripulisce misure + production events lasciando utenti, articoli e ricette (così il cliente ri-testa più volte senza perdere i dati importati).
- Script `scripts/deploy-demo.sh` che fa build, push via SSH alla VPS demo, restart con `docker compose up -d --build`.
- Credenziali demo consegnate al cliente insieme alla guida di test (scenari guidati: "prova come operatore", "prova come capoturno", "prova come maker", ecc.).

**Non incluso (rimandato a M2/Fase 6):** registry privato, Watchtower, compose split server/client, CI release automation, deploy su hardware cliente, `LiveGaiaClient` in tempo reale.

---

## Fase 6 — Deploy Scenario B (Docker per-tablet + Registry + Watchtower) [M2]

**Obiettivo:** package del client come immagine pubblicata su registry privato della VPS; ogni tablet pulla + auto-update via Watchtower. **Parte solo dopo checkpoint feedback M1.**

**Sotto-piano:** `docs/superpowers/plans/2026-04-17-rev04-phase6-deploy-b.md`

**Deliverable:**
- `docker-compose.server.yml` (VPS): `mysql` + `server` + `traefik` + `registry` + `watchtower-server`.
- `docker-compose.client.yml` (per-tablet): `client` + `watchtower-client`, `image: vps.tielogic.local:5000/tielogic/tmflow-client:latest`.
- `.env.client.example` con solo variabili necessarie al client: `STATION_ID`, `STATION_API_KEY`, `API_SERVER_URL`, `CLIENT_SECRET_KEY`, `LANG_DEFAULT`, ecc.
- `Dockerfile.client` ottimizzato: multi-stage, Tailwind build + Babel compile + gunicorn.
- GitHub Actions `.github/workflows/release.yml`: su tag `v*.*.*` builda e pusha `tmflow-server` e `tmflow-client` al registry.
- Script di provisioning `scripts/provision-tablet.sh`: installa docker, crea `.env`, genera STATION_ID, pulla e avvia.
- Documento `docs/DEPLOYMENT_B.md` con procedura manuale operatore IT cliente.

**Scelte tecniche:**
- Registry self-hosted su VPS con auth basic (htpasswd) su `registry:2`, esposto solo via VPN cliente (D-0.10).
- Watchtower `WATCHTOWER_POLL_INTERVAL=300`, `WATCHTOWER_ROLLING_RESTART=true`, label-filtered (`com.centurylinklabs.watchtower.enable=true`) per evitare update indesiderati.
- Tag strategia: ogni release push `tmflow-client:1.1.0` + `tmflow-client:latest`. Tablet seguono `latest`; rollback = retag del latest a versione precedente.

**Caveat D-0.3:** se i tablet target sono Windows consumer, B è fragile (docker desktop + licenze). Documentare come prerequisito mini-PC Linux industriale oppure scivolare a C (che è comunque B+LAN). Questo blocco deve essere chiarito prima.

---

## Fase 7 — Hardening, E2E, Rollout [M2]

**Obiettivo:** fare il sistema robusto per produzione e rilasciarlo su un sito pilota prima del rollout generale.

**Sotto-piano:** `docs/superpowers/plans/2026-04-17-rev04-phase7-hardening.md`

**Deliverable:**
- Security review completa (`oh-my-claudecode:security-reviewer`): nuovi endpoint GAIA, override Supervisor, registry esposto.
- Test E2E manuali + script Playwright/Selenium su: flusso completo operatore + capoturno override + sync GAIA + avvio/fine produzione.
- Rollback plan: procedura di ritorno a V1.0.7 se necessario (backup DB pre-migration, tag immagine precedente).
- Aggiornamento stringhe i18n IT/EN per tutti i nuovi messaggi (capoturno, cicalino, timer, GAIA errori).
- Aggiornamento `CLAUDE.md` + `README.md` + `API.md` + `USER_GUIDE.md`.
- Sito pilota: una singola postazione per una settimana prima del rollout sugli altri.
- Monitoring: log centralizzato + alert su errori GAIA persistenti, override Supervisor eccessivi per stazione, misure fuori tolleranza per ricetta.

---

## Vincoli Trasversali (applicare in ogni fase)

1. **Retrocompatibilità dati:** ogni migration deve avere `downgrade` testato. Mai DROP di colonne con dati senza passo di deprecazione.
2. **Feature flags:** nuove integrazioni (GAIA, Supervisor) dietro flag config (`GAIA_ENABLED`, `SUPERVISOR_ENABLED`) → rollout graduale e rollback veloce.
3. **Test prima:** seguire TDD sui sotto-piani. Ogni endpoint ha almeno un happy path + un negative path + un permission test.
4. **Envelope response:** iniziare ad allineare nuovi endpoint allo standard `{success, data, error}` della spec 2026-04-01, anche se V1.0.7 non lo usa. Minimizza rework futuro.
5. **Audit log:** ogni operazione critica (override, GAIA command, station assign) scrive su `access_logs`.
6. **i18n:** ogni nuova stringa passa da `{{ _('...') }}` o equivalente client-side. Niente testo hardcoded in italiano nei template.
7. **Commit granulari:** un commit per task TDD (test rosso → verde → commit). Usa il git-master agent per il formato commit.

---

## Scelte Architetturali Confermate / Deviate dalla Spec 2026-04-01

| Scelta | Spec 2026-04-01 | V1.1.0 | Motivazione |
|---|---|---|---|
| Struttura cartelle | `src/backend/` + `src/frontend/` | `server/` + `client/` | V1.0.7 ha già cementato questa struttura. Rework > costo beneficio. |
| Package manager | `uv` | `requirements.txt` | Migrazione a uv rimandata a V1.2.0 (task dedicato). |
| Frontend | Gradio o React | Flask server-side | Vincolo cliente: tablet kiosk, i18n server-side, no SPA. Deviazione documentata. |
| Messaging | NATS obbligatorio | Nessuno | Monolite a 2 processi, NATS rimandato a v2.x (quando compariranno moduli camera/ML). |
| API Envelope `{success,data,error}` | Obbligatorio | Adozione incrementale sui nuovi endpoint rev04 | Evita rework totale ma allinea il nuovo codice. |
| Auth header `X-Api-Key` | Obbligatorio | ✓ Già presente (`X-API-Key`) | Allineato (case-insensitive per HTTP). |
| Registry privato + Watchtower | Raccomandato | ✓ Adottato in Fase 6 | Necessario per scenario B. |

---

## Rischi e Mitigazioni

| Rischio | Probabilità | Impatto | Mitigazione |
|---|---|---|---|
| Protocollo GAIA live non decidibile prima di M2 | Media | Medio | M1 non dipende dal protocollo live: usa `ImportOnlyGaiaClient` con dati reali importati. Il protocollo definitivo si chiude durante M1, pronto per Fase 5-live in M2. |
| Export GAIA fornito dal cliente in formato non documentato | Media | Medio | Parser `gaia_import.py` tollerante + anteprima UI + possibilità di caricare più volte; prevedere 1-2 giorni di fitting iniziale del parser sullo specifico formato fornito. |
| Tablet Windows consumer rendono B non praticabile | Media | Alto | Documentare prerequisito hardware, prevedere fallback a C (edge NUC per sito). |
| Cliente cambia idea sul ruolo capoturno | Bassa | Medio | Astrazione override generica: il ruolo può essere rinominato o scomposto senza toccare il flusso. |
| Prestazioni Watchtower con N tablet | Bassa | Basso | `poll_interval=300s`, update scaglionati (`rolling_restart`), banda registry limitata ma accettabile. |
| i18n delta si accumula e va in produzione non tradotto | Media | Medio | Lint in CI che fallisce se ci sono stringhe `_('...')` non in `messages.po`. |
| Migration Alembic rompe DB produzione | Bassa | Critico | Backup pre-deploy obbligatorio, staging con dump produzione, downgrade testato. |

---

## Prossimi passi (focus M1)

1. **Decisioni chiuse:** D-0.4 (cicalino → M2), D-0.7 (autologout configurabile), scelta (b) "dati reali senza live GAIA" in M1.
2. **Decisioni ancora aperte per M1:** D-0.5 (parametri volatili separati dalla versione — raccomandato B) e D-0.6 (UX capoturno: default modale login sovrapposto). Da confermare al volo col cliente o decise da noi di default.
3. **Decisioni rinviabili a M2:** D-0.1 (protocollo GAIA live), D-0.2 (rete/credenziali GAIA), D-0.3 (target hardware tablet), D-0.10 (registry esposto o solo VPN). Da chiudere durante M1, non bloccano la demo.
4. **Richiesta al cliente per sbloccare Fase 5 import-only:** farci avere un **export GAIA d'esempio** (CSV/JSON) degli articoli + ricette per una o due stazioni, così adattiamo il parser.
5. Dettagliare il sotto-piano `phase1-stations` in TDD eseguibile (prima fase sbloccante per tutte le altre di M1).
6. Eseguire le fasi di M1 (1 → 2/3/5-import in parallelo → 4 → Demo deploy) via `superpowers:subagent-driven-development` oppure `superpowers:executing-plans`, con review + verifier tra una fase e l'altra.
7. Consegnare demo al cliente → raccogliere feedback → aprire M2.
8. In M2: chiudere decisioni residue, sviluppare `LiveGaiaClient` + cicalino + Fase 6 (Deploy B) + Fase 7 (hardening/rollout).
