# SPEC — Engine Superman (pipeline Python)

> Come gira il run offline/online Superman. Requisiti: `01_REQUISITI_SUPERMAN.md`.
> Zero dipendenze oltre la stdlib (NFR-01: zero costi). Python ≥ 3.9.

## Struttura

```
engine/
  superman/
    keys.py       — chiave canonica, ID stabili, fingerprint, confidenze (FUN-03, SRC-01, DAT-04)
    schema.py     — validazione baseline, migrazione V1→V2, normalizzazione (FUN-10, UNI-04, DAT-06)
    pipeline.py   — esegui_run(): dedupe, B2B, promo scadute, diff, KPI → snapshot v2
    digest.py     — ruolo Publisher: digest per ambito + digest unico (DIG-01/03/04)
    collect.py    — Collector HTTP live: cache-busting, fingerprint, state fonti (SRC-02/03/04)
    publisher.py  — scrive data file del sito + copia agent prompt e docs (FUN-09)
  superman_cli.py — CLI: build-site, validate-baseline
  tests/          — 16 test pytest su dataset golden (mappati a ID requisito)
```

## Comandi

```
# Pipeline completa: benchmark V1/V2 del workshop → snapshot v2 + digest + data file del sito
python3 engine/superman_cli.py build-site \
  --src /Users/mario/Hermes_Workspace/Progetti/Workshop_GenAI_2026-11-18/benchmarks \
  --out public --agent-dir agent --docs-dir docs

# Verifica integrità di uno snapshot prima di usarlo come baseline
python3 engine/superman_cli.py validate-baseline benchmarks/FIXED/benchmark_FIXED_2026-11-18.json

# Test (16 test, mapping requisiti nel nome)
python3 -m pytest engine/tests -q
```

## Comportamenti chiave (anti-failure)

| Scenario | Comportamento | Requisito |
|---|---|---|
| Baseline JSON corrotta | `BaselineInvalida` → run parte come primo run dichiarato | FUN-10 |
| Baseline schema V1 | migrata al consumo, `id_legacy` conservato | UNI-04 |
| Voci "v2 lite" senza identità | chiave/id/fonti calcolati on-the-fly | robustezza run |
| Stessa offerta su più fonti | 1 voce, fonti unite; prezzi >2% discordi → `conflitto_fonti` | FUN-04/06 |
| Promo con data_fine < oggi | `attiva: false`, il prezzo effettivo è il listino | FUN-05 |
| Voce B2B | `esclusa: true` + motivo | FUN-08 |
| Voce assente + fonti baseline bloccate | `disattivata_incerta`, non `disattivata` | FUN-07 |
| Doppio run stesso giorno | output identico (test NFR-07) | NFR-07 |

## Fetch live (collect.py)

`fetch_fonte(url, baseline_fingerprint)` ritorna lo record `fonti` pronto per lo snapshot:
cache-busting con parametro univoco, `Cache-Control: no-cache`, UA dichiarato, timeout 20s,
rilevamento bot-wall (403/429/503, "just a moment", captcha), classificazione `ok/stale/cache/bloccata`
e fingerprint SHA-256 del contenuto. **Non estrae offerte**: l'adapter di estrazione per fonte è fase 2 —
nessun prezzo simulato nel frattempo (GOV-04).

## Dati pubblicati

`public/data/`: `index.json` (indice run), `snapshot_{ambito}.json` (v2), `digests.json`,
`digest_unico.txt`. `public/agent/` + `public/docs/`: system prompt e documenti del progetto.
