pcrt-legal-return/PLAN.md

# Pizeta Recesso — App Shopify per la funzione di recesso
### Piano di sviluppo multi-agente

> **Obiettivo:** App Shopify riutilizzabile che rende qualsiasi negozio conforme alla funzione
> elettronica di recesso ("pulsante di recesso") obbligatoria — **Art. 54-bis Codice del Consumo**
> (D.Lgs 209/2025), recepimento Dir. (UE) 2023/2673. In vigore per contratti conclusi **dal 19
> giugno 2026**. I merchant sono esposti *da adesso*.
>
> **Base legale verificata:** vedi `ANALISI-REQUISITI-LEGALI.md` (fonti primarie/secondarie).
> Le voci ⚠ restano da confermare su EUR-Lex prima del go-live.

---

## 0. Decisioni bloccate

| Tema | Decisione | Nota |
|---|---|---|
| Distribuzione | **Custom distribution ora (2-3 store live) → Public molto più avanti** | Custom = no review, ok per pochi store. Account separati → 1 registrazione custom per store. Codice riusato per il futuro public |
| Backend | **Template Shopify Remix (Node) + Polaris** | Strada ufficiale Shopify |
| Hosting | **Fly.io** | Riuso setup esistente |
| Database | **Postgres + Prisma** | Fly Postgres (default) o Supabase (ho le creds) — decido in Fase 0 |
| Email (ricevuta durevole) | **Stub in MVP**, provider (Resend/Postmark) da decidere prima del go-live | Ricevuta con timestamp |
| Store di test | **SOLO `pcrt-reso-test`** (usa e getta) | ⚠ MAI pizeta-pharma-2 o store da trasferire: `shopify app dev`/install app DISABILITA il transfer in modo irreversibile |
| Consegna storefront | **Theme App Extension + App Proxy** | installazione senza toccare il tema, guest-capable |

**La cartella tema (`pizeta-pharma/`) NON è l'app** — è un tema Liquid, solo target di test.
L'app è questo repo separato.

---

## 0-bis. ⚠️ VINCOLO CRITICO — trasferimento store (IRREVERSIBILE)

**Il landmine è STRETTO: solo le DRAFT app / `shopify app dev` disabilitano il transfer.**
Lanciare `shopify app dev` (draft app) contro un development store — o abilitare developer preview —
**disabilita il trasferimento in modo permanente e irreversibile** (CLI issue #3946). Uno store
transfer-disabled non si trasferisce più: andrebbe ricostruito da zero.

**Cosa NON disabilita il transfer** (verificato):
- **Custom distribution via install link** (la nostra app recesso finita): si installa come una
  normale app, **non** applica "Transfer Disabled". Installabile anche su store del cliente (via link
  store-specifico, scadenza 7 giorni; ownership non richiesta).
- **Legacy/admin custom app** (es. "Import Negozio"): non disabilita il transfer.

**Regole operative:**
1. Sviluppo/test (**`shopify app dev` = draft**) **solo su `pcrt-reso-test`** (usa e getta). ← unica vera protezione.
2. **Mai** `shopify app dev` / draft contro **pizeta-pharma-2** o store destinati al cliente.
3. **App finita (custom link):** installabile su pizeta + altri store, **prima o dopo** il transfer,
   senza rompere niente. Per zero-rischi assoluti, installa **dopo** il transfer (banale, via link).
4. ⚠ Nuance da confermare empiricamente: install custom su un client-transfer store ancora "in your
   org" (pre-transfer) — fonti in conflitto. Se vuoi installare pre-transfer, testa prima.

---

## 0-ter. Strategia distribuzione & isolamento ambienti

**Principio:** *una build public-grade, distribuita Custom ora.* Non due sviluppi.

Vincolo di piattaforma (verificato): una app **Public — anche unlisted — richiede review Shopify** per
installarsi su store **live**. Solo **Custom** installa su live senza review. Quindi:
- **ORA:** distribuzione **Custom** (unico canale per il live senza review) su 2-3 store clienti.
- **DOMANI:** **nuova registrazione Public** + review, stesso codice. La distribuzione non è convertibile,
  ma non si converte: si aggiunge una seconda registrazione.

**Codice public-grade dal giorno 1** (così il public futuro = re-registrazione, non rebuild):
1. Template Shopify CLI/Remix standard — OAuth multi-tenant, session token (no scorciatoia single-store).
2. Dati **multi-tenant per-shop** dal giorno 1, anche con soli 2-3 negozi.
3. **Webhook GDPR obbligatori** subito.
4. **Billing API dietro flag** (`isPublic`): off in custom, on in public. Unico ramo di codice divergente.
5. Performance/sicurezza a livello review **man mano**, non retrofit.

**Isolamento ambienti (anti-rottura) — creato separato dal giorno 1 in A0:**
```
pcrt-reso-test  →  staging (Fly)  →  recesso-custom (Fly, CLIENTI LIVE)
   sviluppo         collaudo          stabile — deploy solo testati — DB proprio

recesso-public (Fly, DOMANI)  →  registrazione Public + DB proprio
   stesso codice, deployment SEPARATO → non tocca mai recesso-custom
```
Registrazioni Partner distinte + Fly app distinti + DB distinti → il deploy della public **non può**
impattare gli store live sulla custom (isolamento strutturale, non per disciplina).

**Regole anti-rottura sulla custom-live:** test su `pcrt-reso-test` prima; migrazioni DB solo
**additive/backward-compatible**; theme extension **versionate** (rollback); **API version pinnata**.

---

## 1. Architettura

```
STOREFRONT (acquirente)
  ├─ Theme App Extension (app embed)  → pulsante "recedere dal contratto qui"
  └─ App Proxy  /apps/recesso         → flusso recesso guest-capable sul dominio dello shop
        1. lookup: Order ID + email        (guest — buona prassi per "facilmente accessibile")
        2. form: nome, dichiarazione, email (precompilato se loggato)
        3. STEP 2 conferma: "conferma recesso"  (funzione dedicata, anti-accidentale)
        4. successo + ricevuta durevole inviata

BACKEND (Fly.io)
  ├─ App Remix (admin embedded, Polaris)
  ├─ Postgres (Prisma): richieste, regole, impostazioni, audit
  ├─ Motore compliance: calcolo finestra, esclusioni Art. 59, tipo-prodotto, scadenza
  ├─ Ricevuta durevole: email con testo dichiarazione + timestamp di TRASMISSIONE
  ├─ Webhook: fulfillment (avvio finestra) + 3 GDPR obbligatori
  └─ Billing (aggiunto in fase App Store)
```

**Perché Theme App Extension + App Proxy:** il pulsante acquirente + form guest devono vivere sul
dominio del negozio e sopravvivere agli aggiornamenti del tema senza che il merchant tocchi il
Liquid. App Proxy consente a un URL storefront (`/apps/recesso`) di raggiungere il backend
restando sul dominio dello shop — necessario per l'accesso guest e per "facile come acquistare".

---

## 2. Matrice requisiti (il contratto su cui ogni agente costruisce)

Corretta e integrata dopo `ANALISI-REQUISITI-LEGALI.md`.

| # | Requisito legale | Funzionalità | Criteri di accettazione |
|---|---|---|---|
| R1 | Funzione visibile, facilmente accessibile, **continuativamente disponibile** per tutta la finestra | Pulsante extension + pagina proxy sempre attiva, legata al singolo ordine | Label **"recedere dal contratto qui"**; funzione attiva tutta la finestra di quell'ordine |
| R2 | Accesso facile (guest = buona prassi, non obbligo) | Lookup Order ID + email | Guest completa il recesso con solo n° ordine + email; nessun login forzato |
| R3 | Raccolta nome, id contratto, mezzo elettronico, dichiarazione | Form recesso | I 4 dati raccolti + persistiti |
| R4 | Conferma a 2 step, funzione dedicata | Funzione **"conferma recesso"** | Invio impossibile senza 2ª azione esplicita; **no dark pattern** |
| R5 | Ricevuta su supporto durevole **senza ritardo**, con dichiarazione + **timestamp di trasmissione** | Email transazionale | Email < 1 min; contiene testo dichiarazione + data/ora di trasmissione |
| R6 | Onere probatorio del professionista | Persistenza DB + **audit log immutabile** | Record immutabile richiesta + timestamp + invio ricevuta |
| R7 | Funzione **non più onerosa della conclusione** (anti dark pattern) | UX ≤ passaggi del checkout | ≤ passaggi/attriti del checkout; no pop-up dissuasivi, pre-flag, retention nudge |
| R8 | Termine 14gg, decorrenza per tipo | Motore compliance | Scadenza corretta per beni (consegna/ultimo lotto) / servizi (conclusione) / digitale |
| R9 | Esclusioni Art. 59 (su misura, deperibili, sigillati igiene) | Regole esclusione (prodotto/collezione/tag) | Item escluso segnalato con motivo; no recesso "cieco" |
| R10 | Non conformità → 14gg → 12 mesi+14gg (Art. 53) | Warning misconfig + calcolo corretto | Admin avvisa su misconfig; scadenza riflette proroga quando applicabile |
| R11 | Pulsante **AGGIUNTIVO**, non sostitutivo | Coesistenza modulo tipo Allegato I-B + email | App non disabilita/nasconde gli altri canali |
| R12 | Obblighi info **Art. 49** (ubicazione funzione) | Testo info recesso + link ubicazione | Info diritto di recesso + posizione funzione mostrate |
| R13 | Rimborso: spese consegna incluse; reso a carico consumatore se informato; diminuzione valore | Logica rimborso + informativa | Schermata informa su chi paga reso; calcolo include spedizione standard |
| R14 | Lingua del contratto/offerta | i18n (IT/EN/DE/FR/ES…) | Flusso acquirente + ricevuta localizzati |
| R15 | Solo **B2C** | Filtro ordini | Ordini B2B esclusi dal flusso obbligatorio |
| R16 | Webhook GDPR obbligatori Shopify | `customers/data_request`,`customers/redact`,`shop/redact` | Tutti e 3 implementati + HMAC verificato |
| R17 | Sanzione pulsante non conforme = pratica scorretta Art. 27 (AGCM, fino €10M/4%) | (rischio, non feature) | Documentato; guida merchant alla conformità |

---

## 3. Modello dati (bozza Prisma)

- **Shop** — dominio, accessToken(cifrato), piano, installedAt
- **Settings** — labelPulsante, brandColors, indirizzoReso, giorniFinestraDefault, overrideMercati, testoInfoRecesso, email (emailSubject/emailIntro/emailNote), + toggle per-shop: notifyEnabled/notifyEmail, tagEnabled, enforceWindow, enforceExclusions, **stateAwareEmail, autoCancelUnfulfilled, returnAtCustomerExpense, returnInstructions**
- **ExclusionRule** — scope(prodotto|collezione|tag|tutto), targetId, motivo(sumisura|deperibile|igiene), attiva
- **WithdrawalRequest** — shopId, orderId, orderName, nomeCliente, email, testoDichiarazione, **trasmessoAt (ts)**, locale, canale(guest|account), tipoProdotto, stato, ricevutaInviataAt, scadenzaCalcolata
- **AuditLog** — shopId, evento, hashPayload, ts (append-only, immutabile)
- **WebhookEvent** — topic, ricevutoAt, processato (idempotenza)

---

## 4. Piano multi-agente (agenti SPECIALIZZATI, esecuzione SEQUENZIALE)

Preferenza utente: agenti **super-specializzati**, eseguiti **uno alla volta** (parallelo solo dove
strettamente utile), **minimo consumo di token**. Ogni agente = un brief focalizzato con
input / deliverable / criteri di uscita espliciti. **Nessun avvio automatico** — parto al tuo ok.

### Fase 0 — Fondamenta *(gate: tutto il resto dipende da qui)*
- **A0 architect** — init app Remix, schema Prisma, config Fly, igiene segreti, collegamento ai 2 dev store, CI. **Uscita:** app installata su entrambi i dev store, `/health` verde su Fly, DB migrato.

### Fase 1 — Specifica compliance *(gate: il contratto di accettazione)*
- **A1 compliance-mapper** — trasforma `ANALISI-REQUISITI-LEGALI.md` + §2 in criteri di accettazione testabili + copy deck (etichette IT esatte, template ricevuta, testo info recesso), risolve i punti ⚠. **Uscita:** file criteri approvato contro cui ogni agente testa.

### Fase 2 — MVP core (minimo legalmente conforme) *(sequenziale)*
- **A2 storefront-extension** — Theme App Extension + App Proxy lookup guest (R1,R2,R7,R11).
- **A3 backend-flow** — endpoint recesso, conferma 2 step, persistenza + timestamp (R3,R4,R6).
- **A4 receipt** — email durevole con dichiarazione + timestamp trasmissione (provider stub) (R5).
- **Uscita:** guest su dev store immacolato completa il recesso → record + ricevuta. **Questo è già conforme.**

### Fase 3 — Admin merchant *(sequenziale; A5→A6)*
- **A5 admin-UI + motore di stile estensibile** — Polaris: dashboard richieste, impostazioni, testo info (R12). **Theming a 3 livelli** (requisito utente: "super estendibile, personalizzabile da template"):
  1. **Token da Settings** (no-code) — colore brand, font, raggio, logo, larghezza → override delle CSS variables del form (base già pronta: il form del design è tutto a token `:root`).
  2. **Eredita tema** — opzione App Proxy in **Liquid** → il form è reso dentro il tema del negozio (look nativo, "template del merchant").
  3. **CSS custom** — escape hatch per personalizzazione totale.
  Merchant sceglie il livello; default = card a token controllata. Può diventare un agente dedicato (theming) se troppo grande per A5.
- **A6 compliance-engine** — esclusioni Art. 59 + calcolo finestra/scadenza per tipo prodotto + warning misconfig + logica rimborso (R8,R9,R10,R13,R15). **Uscita:** merchant configura esclusioni/finestre; item escluso si comporta secondo R9.
- **A6-bis operatività per stato ordine** *(confermata call Pizeta 2026-06-16 + `AUDIT-STATI-ORDINE.md`)* — comportamenti aggiuntivi, **tutti toggle per-shop** (app generica: ognuno decide). Dati già raccolti dal lookup: `displayFulfillmentStatus`, `deliveredAt`, `cancelledAt`, `financialStatus`.
  1. **Ricevuta differenziata per stato** (`stateAwareEmail`, default ON): la ricevuta durevole (sempre inviata) include un blocco operativo diverso —
     - *non evaso* → "ordine annullato, procederemo al rimborso";
     - *spedito/consegnato* → istruzioni di reso (indirizzo, spese a carico cliente, prodotto integro, rimborso dopo il rientro).
  2. **Auto-annullamento ordini non evasi** (`autoCancelUnfulfilled`, default OFF — irreversibile, opt-in): al recesso su ordine non evaso → `orderCancel` (refund+restock). Bonus: Shopify emette `orders/cancelled` → si ferma il bot di remarketing del merchant.
  3. **Istruzioni di reso configurabili**: `returnAddress` (già in schema), `returnAtCustomerExpense` (default ON — Art. 57: informa + rende il cliente responsabile delle spese), `returnInstructions` (testo opzionale).
  **Resta MANUALE per scelta Pizeta** (nessuna automazione richiesta): resi parziali + rimborso proporzionale (pannello Shopify), emissione rimborso (Shopify manda la sua mail), verifica data consegna se il corriere non passa l'evento a Shopify.
  **Uscita:** merchant attiva/disattiva ciascun comportamento; il flusso si adatta allo stato dell'ordine.
- **A6-ter recesso parziale** *(OPZIONALE — non è un obbligo di legge)* — Base legale in `ANALISI-REQUISITI-LEGALI.md` §5: il **considerando 37 Dir. (UE) 2023/2673** dice che il professionista **"can"** offrire il recesso su parte del contratto, non che **deve**. Un pulsante a livello di ordine è conforme; il parziale è **differenziazione di prodotto** (lo fa Revize, non lo fa Rescindly) e copre il caso reale Pizeta (3 confezioni, ne rende 2).
  - Toggle per-shop **`partialWithdrawalEnabled`** (default **OFF** = comportamento attuale, un clic = recesso totale).
  - Passo 2: elenco articoli dell'ordine con quantità; **default tutti selezionati** (nessun attrito per chi vuole il totale).
  - Dichiarazione **generata sugli articoli scelti** (oggi dice "intero ordine": non si può lasciare così se il cliente seleziona un sottoinsieme).
  - `createShopifyReturn`: reso limitato alle **righe/quantità selezionate**.
  - `autoCancelUnfulfilled`: si attiva **solo** se la selezione copre l'intero ordine. Parziale + non evaso → order edit / rimborso parziale, che resta manuale.
  - **Idempotenza da rivedere**: oggi la chiave è `(shop, orderId)` (commit `fa8ee9c`), corretta solo nel mondo total-only. Col parziale deve diventare `(shop, orderId, articoli)`: il cliente può recedere per l'articolo A oggi e per il B domani, entrambi legittimi nella finestra.
  - Dati da aggiungere: `lookupOrder` deve restituire titoli, quantità e ID riga; mappatura `lineItem ↔ fulfillmentLineItem` per il reso; nuova colonna (es. `items Json`) su `WithdrawalRequest`.
  - **Uscita:** merchant può abilitare il parziale; con toggle OFF il comportamento resta identico a oggi.

### Fase 4 — Robustezza *(A7→A8 sequenziali, poi A9 audit)*
- **A7 i18n** — localizzazione IT/EN/DE/FR/ES (R14).
- **A8 compliance-webhooks** — 3 webhook GDPR + verifica HMAC + idempotenza (R16).
- **A9 qa-security-auditor** — avversariale: HMAC, abuso lookup guest (enumeration/rate-limit), gestione PII, edge case (fulfillment parziale, beni digitali, calcolo scadenza). **Uscita:** report audit, zero criticità.

### Fase 5 — App Store pubblica *(quando custom → public)*
- **A10 billing** — Shopify Billing API + piani.
- **A11 app-store-submission** — listing, screenshot, privacy, checklist review. **Uscita:** pacchetto pronto per submission.

### Grafo dipendenze
```
A0 → A1 → A2 → A3 → A4 → A5 → A6 → A7 → A8 → A9 → A10 → A11
(sequenziale per default; A7/A8 parallelizzabili solo se serve accelerare)
```

---

## 4-ter. Piano consolidato — stato attuale + residuo *(agg. 2026-07-07)*

Vista unica: cosa è FATTO e cosa RESTA, con A6-bis (Pizeta) e i gap dell'audit
integrati. Dettaglio stato/commit nella memoria di progetto + git.

### ✅ Fatto (custom-grade, testato su pcrt-reso-test)
- **A0–A1** fondamenta + spec compliance + copy deck.
- **A2** Theme App Extension (app block + app embed) + **modal** storefront (iframe, redesign de-AI, popover info).
- **A3** App Proxy: flusso guest 2-step + persistenza + **timestamp trasmissione** + audit (anti-enumeration).
- **A4** ricevuta durevole (nodemailer/Mailpit dev) + **dati per-shop dinamici** (nome/URL/link ordine da Shopify) + **template editabile vincolato** (oggetto/intro/nota + anteprima live + ripristino).
- **A5 (parziale)** admin Polaris: dashboard **Recessi**, **Impostazioni** (email/notifiche/regole), **Esclusioni** (CRUD). Theming: solo token base.
- **A6 (parziale)** engine finestra + esclusioni Art. 59 (dietro toggle, default OFF).
- **A8 (stub)** webhook GDPR + HMAC.
- **EXTRA (oltre il piano originale):** integrazione **Resi Shopify** (`returnCreate` su ordini evasi), **notifica merchant + tag** (toggle), **fix P1** (finestra sulla CONSEGNA, skip ordini annullati/rimborsati), **avviso ordini chiusi**, **audit stati ordine** (`AUDIT-STATI-ORDINE.md`).

### ⏳ Residuo (prioritizzato)

- **R1 — A6-bis operatività per stato ordine (Pizeta-confirmed)** — 3 toggle per-shop: `stateAwareEmail` (ricevuta differenziata non-evaso/spedito-consegnato), `autoCancelUnfulfilled` (annullo automatico ordini non evasi), `returnAtCustomerExpense`+`returnInstructions`+`returnAddress` (istruzioni reso, Art. 57). Dettaglio: sezione A6-bis.
- **R2 — A6 residuo copy compliance** — G7: promemoria rimborso 14gg + facoltà di trattenuta (Art. 56) nella notifica al merchant. *(G6 spese-reso assorbito da R1.)*
- **R2-bis — A6-ter recesso parziale** *(opzionale, toggle `partialWithdrawalEnabled`, default OFF)* — non è compliance ma prodotto: selezione articoli/quantità, dichiarazione sugli articoli scelti, reso limitato alle righe scelte, auto-annullo solo se selezione = intero ordine, idempotenza su `(ordine, articoli)`. Vedi A6-ter e `ANALISI-REQUISITI-LEGALI.md` §5.
- **R3 — Deploy custom (go-live)** — Fly.io + Postgres prod + URL stabile + tunnel Cloudflare nominato + link install custom sui 2-3 store live. *(Serve per usarlo davvero; occhio deadline transfer pizeta-pharma-2 ~metà luglio 2026.)*
- **R4 — A9 hardening / QA-security** — rate-limit robusto, retry ricevuta fallita, idempotenza webhook, review avversariale (enumeration lookup, HMAC, PII), Protected Customer Data (approvazione Shopify per leggere `order.email` in prod).
- **R5 — A7 i18n** — IT/EN/DE/FR/ES.
- **R6 — A5 residuo theming** — motore 3 livelli completo (token no-code / eredita-tema Liquid / CSS custom).
- **R7 — Pubblica** — A10 billing + A11 submission App Store (registrazione Partner separata → non impatta le custom live).

### Ordine consigliato
`R1 → R2 → R3 (deploy) → R4 (hardening) → R5/R6 → R7`
R1/R2 chiudono valore-cliente + compliance copy; R3 mette live; R4 mette in sicurezza prima del traffico reale; R5/R6 rifiniscono; R7 quando si va public.

---

## 5. Milestone

- **M1 (Fase 0–1):** scaffold + contratto compliance. *Nulla di visibile, ma toglie rischio a tutto.*
- **M2 (Fase 2):** **MVP conforme live su pizeta.** ← primo valore reale, azzera esposizione legale.
- **M3 (Fase 3–4):** production-grade, configurabile, auditato.
- **M4 (Fase 5):** submission App Store.

---

## 6. Rischi / punti di attenzione

- **Sovrapposizione nativo Shopify** — Shopify ha regole reso/cancellazione UE; non ricostruire i resi, avvolgerli. Verificare in A1 cosa è nativo vs gap.
- **Competitor esistenti** (Rescindly, REVER) — differenziare su conformità IT esatta + semplicità + prezzo.
- **Lookup guest = superficie di abuso** — enumeration ordini; serve rate-limit + match email + nessun leak su miss (A9).
- **Prova supporto durevole** — ricevuta riproducibile/loggata, non fire-and-forget (A4/A6).
- **Calcolo scadenza** — consegna vs conclusione, beni digitali, fulfillment parziale; fonte unica di verità nel motore (A6).
- **PII** — dichiarazione + email = dati personali; cifratura at rest + webhook GDPR non negoziabili (A8).
- **Base legale ⚠** — confermare numeri articoli UE e inquadramento Art. 27 su fonte primaria (A1).

---

## 7. Punti aperti (non bloccanti)

1. DB: Fly Postgres vs Supabase Postgres — decido in A0.
2. Provider email — decido prima di M2.
3. Automazione rimborso — fuori scope MVP; confermare che il tracking manuale basta al lancio.