Chore/open source repositioning

.github/workflows/ci.yml

@@ -10,11 +10,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v4
         with:
           node-version: 20
-          cache: npm
-      - run: npm ci
-      - run: npm run db:generate
-      - run: npm run lint
-      - run: npm run test
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run db:generate
+      - run: pnpm run lint
+      - run: pnpm run test

.gitignore

@@ -41,3 +41,6 @@ yarn-error.log*
 next-env.d.ts
 
 /src/generated/prisma
+
+# scratch / internal notes, strategy drafts, AI research dumps — not for the public repo
+/private

CLAUDE.md

@@ -0,0 +1,50 @@
+# FiscLink — contesto per Claude
+
+Open source, self-hosted, mercato italiano. Non riposizionarlo come SaaS commerciale internazionale: il pubblico target sono developer/freelance/piccoli SaaS italiani che usano Stripe.
+
+## Cos'è davvero
+
+Bridge fiscale Stripe → dati italiani. Riceve webhook Stripe, capisce se mancano Codice Fiscale/Partita IVA/SDI/PEC/indirizzo, manda un Magic Link al cliente per completarli, valida i dati, li prepara per export o per Fatture in Cloud. Non emette fatture allo SdI con un canale proprietario, non sostituisce commercialista o provider fiscale.
+
+## Direzione del progetto (importante)
+
+Il repo ha subito un riposizionamento (`chore/open-source-repositioning`) da SaaS ambizioso multi-provider a tool open source piccolo e onesto, focalizzato solo su Stripe. Il codice ha già client per Shopify e WooCommerce (`src/lib/shopify`, `src/lib/woocommerce`) e logiche VIES/OSS/note di credito — **non cancellarli**, ma non riattivarli o pubblicizzarli senza che l'utente lo chieda esplicitamente. La UI li mostra già come "Prossimamente"/disabilitati: è voluto.
+
+Prima di proporre nuove feature grandi, la priorità è: far funzionare bene Stripe → validazione → Magic Link → export. Evita overclaim nei testi pubblici (landing, meta SEO, JSON-LD): niente "fatturazione automatica a norma SDI garantita", niente pricing finti, niente paragoni aggressivi con i competitor. Il tono giusto è quello di `src/app/page.tsx` (disclaimer onesti), non quello dei vecchi doc commerciali.
+
+## Documenti interni vs pubblici
+
+- `docs/` → pubblico, deve restare accurato e coerente con la direzione open source (SETUP, DEPLOY, TEST_GUIDE, AI_CONTEXT, DEVELOPMENT_ROADMAP, PRODUCT_POSITIONING, PUBLISHING).
+- `private/` → **gitignored**, mai committato. Ci stanno appunti di lavoro, analisi AI, strategie commerciali/pricing, scratch file (es. vecchi `TODO.md`, `STATUS_REPORT.md`, `docs/research/*`, `docs/commercial_strategy/*`). Se trovi un file con linguaggio da pitch commerciale, prezzi, o dump di chat AI, va in `private/`, non in `docs/`.
+
+## Package manager
+
+**pnpm**, non npm. Lockfile: `pnpm-lock.yaml`. `package-lock.json` non deve tornare.
+
+pnpm isola i node_modules per package: occhio a phantom dependency (moduli che npm trovava per hoisting accidentale ma non sono dichiarati). Se qualcosa rotto dopo `pnpm install` con errore "Cannot find module X", probabilmente va aggiunto esplicitamente in `package.json`.
+
+`package.json` ha `pnpm.overrides` per `ioredis` (pinnato a `5.10.1` per matchare quello richiesto da `bullmq` ed evitare doppie versioni con conflitti di tipo TS) e `pnpm.onlyBuiltDependencies` per approvare gli script postinstall nativi (prisma engines, sharp, esbuild, msgpackr-extract, unrs-resolver). Se aggiungi una dipendenza con binari nativi e pnpm si blocca su "Ignored build scripts", aggiungila lì invece di girare `pnpm approve-builds` a mano.
+
+`stripe` è pinnato esatto a `20.3.1` (non `^20.3.1`): versioni più nuove cambiano il literal type di `apiVersion` in `src/lib/stripe/client.ts` e rompono il build. Se aggiorni Stripe, aggiorna anche quella stringa.
+
+## Comandi utili
+
+```bash
+pnpm install
+pnpm run db:generate   # prisma generate
+pnpm dev                # Next.js
+pnpm worker             # worker BullMQ (richiede Redis)
+pnpm test
+pnpm lint
+pnpm build
+```
+
+`docker compose up -d` per Postgres + Redis locali.
+
+## Stato lint/build
+
+Build e test passano. Lint ha errori pre-esistenti (apostrofi non escaped in `privacy/terms/page.tsx`, due `any` in `dashboard/page.tsx`, alcuni `react-hooks/set-state-in-effect` in `dashboard/settings/page.tsx`) non ancora risolti — non bloccano build/test ma falliscono `pnpm lint` e quindi la CI sul job lint. Da sistemare prima di una release pubblica seria.
+
+## Lingua
+
+L'utente scrive in italiano e vuole risposte in italiano (vedi istruzioni globali). Il prodotto stesso è in italiano (UI, meta SEO, disclaimer). Mantieni questo focus: non anglicizzare la narrazione del prodotto, usa l'inglese solo dove serve per discoverability internazionale (es. topic GitHub).

README.md

@@ -1,11 +1,23 @@
 # FiscLink
 
-Open source Stripe fiscal bridge for Italy.
+[![CI](https://github.com/eliazv/fisclink/actions/workflows/ci.yml/badge.svg)](https://github.com/eliazv/fisclink/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.md)
+[![Next.js](https://img.shields.io/badge/Next.js-16-black)](https://nextjs.org)
 
-FiscLink aiuta chi usa Stripe in Italia a raccogliere, validare e normalizzare i dati fiscali necessari per la fatturazione elettronica italiana.
+**Raccogli e valida i dati fiscali italiani (Codice Fiscale, Partita IVA, SDI, PEC) mancanti dai pagamenti Stripe.**
+
+Open source, self-hosted, pensato per developer, freelance e piccoli SaaS italiani che incassano con Stripe ma si trovano senza i dati necessari per la fatturazione elettronica.
 
 > Stato del progetto: early preview / developer tool. Non è un gestionale fiscale completo e non sostituisce commercialista, consulente fiscale o provider accreditato SdI.
 
+## Perché esiste
+
+In Italia la fatturazione elettronica è obbligatoria per la quasi totalità delle partite IVA. Stripe però non raccoglie in modo affidabile Codice Fiscale, Partita IVA, indirizzo o codice destinatario SDI/PEC al momento del pagamento.
+
+Il risultato è che chi vende con Stripe in Italia finisce a rincorrere i clienti via email per i dati fiscali mancanti, oppure rischia fatture incomplete o in ritardo verso il commercialista.
+
+FiscLink automatizza solo questa parte: webhook Stripe → controllo dati → Magic Link al cliente se manca qualcosa → dati validati e pronti per l'export o per il gestionale fiscale che già usi.
+
 ## Cosa fa
 
 - Riceve eventi Stripe da webhook.
@@ -67,6 +79,7 @@ Export / integrazione opzionale con Fatture in Cloud
 ### Prerequisiti
 
 - Node.js 20+
+- pnpm 10+ (`npm i -g pnpm` se non lo hai)
 - PostgreSQL
 - Redis
 - Account Stripe in test mode
@@ -78,16 +91,16 @@ Export / integrazione opzionale con Fatture in Cloud
 ```bash
 git clone <repo-url>
 cd fisclink
-npm install
+pnpm install
 cp .env.example .env
-npx prisma migrate dev --name init
-npm run dev
+pnpm exec prisma migrate dev --name init
+pnpm dev
 ```
 
 In un secondo terminale:
 
 ```bash
-npm run worker
+pnpm worker
 ```
 
 Per testare i webhook Stripe in locale:
@@ -99,12 +112,12 @@ stripe listen --forward-to "localhost:3000/api/webhooks/stripe?merchant=YOUR_MER
 ## Script utili
 
 ```bash
-npm run dev          # Avvia Next.js
-npm run worker       # Avvia i worker BullMQ
-npm run build        # Build produzione
-npm run lint         # ESLint
-npm run test         # Test Vitest
-npm run db:studio    # Prisma Studio
+pnpm dev             # Avvia Next.js
+pnpm worker          # Avvia i worker BullMQ
+pnpm build           # Build produzione
+pnpm lint            # ESLint
+pnpm test            # Test Vitest
+pnpm db:studio       # Prisma Studio
 ```
 
 ## Roadmap pragmatica
@@ -117,8 +130,8 @@ npm run db:studio    # Prisma Studio
 - [x] Validazione fiscale italiana formale
 - [x] Dashboard stato documenti
 - [ ] Supporto completo a `invoice.paid` per abbonamenti Stripe Billing
-- [ ] Export CSV/JSON per commercialista
-- [ ] `.env.example` e documentazione self-hosting
+- [x] Export CSV/JSON per commercialista
+- [x] `.env.example` e documentazione self-hosting
 
 ### v0.2 — Export e integrazioni
 
@@ -134,6 +147,19 @@ npm run db:studio    # Prisma Studio
 - [ ] Provider fiscali aggiuntivi
 - [ ] Supporto OSS/estero documentato
 
+## Integrazioni future (presenti nel codice, disattivate per ora)
+
+Il codice include già client per Shopify e WooCommerce (`src/lib/shopify`, `src/lib/woocommerce`), ma non sono esposti nella UI e sono disabilitati di default. La fase attuale del progetto è volutamente concentrata solo su Stripe: prima va reso solido quel flusso, poi si riattivano gli altri provider.
+
+## Documentazione
+
+- [`docs/SETUP.md`](docs/SETUP.md) — setup completo, servizi esterni, deploy
+- [`docs/DEPLOY.md`](docs/DEPLOY.md) — deploy su Railway/Render/Fly/VPS
+- [`docs/TEST_GUIDE.md`](docs/TEST_GUIDE.md) — guida ai test manuali end-to-end
+- [`docs/AI_CONTEXT.md`](docs/AI_CONTEXT.md) — contesto tecnico per chi (o cosa) lavora sul codice
+- [`docs/DEVELOPMENT_ROADMAP.md`](docs/DEVELOPMENT_ROADMAP.md) — direzione di sviluppo
+- [`docs/PRODUCT_POSITIONING.md`](docs/PRODUCT_POSITIONING.md) — cosa promettere e cosa no
+
 ## Disclaimer fiscale
 
 Questo software è fornito come strumento tecnico. La responsabilità sulla correttezza, emissione, trasmissione e conservazione delle fatture resta dell'utilizzatore e dei suoi consulenti/provider fiscali.

docs/AI_CONTEXT.md

@@ -169,9 +169,9 @@ connettore-fiscale/
 ```bash
 docker compose up -d          # PostgreSQL + Redis
 cp .env.example .env          # Configura variabili
-npx prisma migrate dev        # Crea tabelle
-npm run dev                   # Next.js su :3000
-npx tsx src/lib/workers/start.ts  # Worker (terminale separato)
+pnpm exec prisma migrate dev  # Crea tabelle
+pnpm run dev                  # Next.js su :3000
+pnpm exec tsx src/lib/workers/start.ts  # Worker (terminale separato)
 ```
 
 ## Servizi esterni necessari

docs/DEPLOY.md

@@ -13,7 +13,7 @@
 # 1. Clona e installa
 git clone <repo-url>
 cd connettore-fiscale
-npm install
+pnpm install
 
 # 2. Configura environment
 cp .env.example .env
@@ -23,10 +23,10 @@ cp .env.example .env
 bash scripts/dev-start.sh
 
 # 4. In terminale 1: app Next.js
-npm run dev
+pnpm run dev
 
 # 5. In terminale 2: workers BullMQ
-npm run worker
+pnpm run worker
 
 # 6. (Opzionale) In terminale 3: webhook Stripe
 stripe listen --forward-to localhost:3000/api/webhooks/stripe?merchant=TUO_MERCHANT_ID
@@ -38,14 +38,14 @@ App disponibile su http://localhost:3000
 
 | Comando | Descrizione |
 |---|---|
-| `npm run dev` | Avvia Next.js in dev mode |
-| `npm run worker` | Avvia i 5 workers BullMQ |
-| `npm run build` | Build produzione |
-| `npm run start` | Avvia app in produzione |
-| `npm run db:migrate` | Esegui migrazioni (produzione) |
-| `npm run db:migrate:dev` | Crea nuove migrazioni (dev) |
-| `npm run db:generate` | Rigenera Prisma Client |
-| `npm run db:studio` | Apri Prisma Studio (GUI database) |
+| `pnpm run dev` | Avvia Next.js in dev mode |
+| `pnpm run worker` | Avvia i 5 workers BullMQ |
+| `pnpm run build` | Build produzione |
+| `pnpm run start` | Avvia app in produzione |
+| `pnpm run db:migrate` | Esegui migrazioni (produzione) |
+| `pnpm run db:migrate:dev` | Crea nuove migrazioni (dev) |
+| `pnpm run db:generate` | Rigenera Prisma Client |
+| `pnpm run db:studio` | Apri Prisma Studio (GUI database) |
 
 ---
 
@@ -70,8 +70,8 @@ Railway supporta processi long-running, perfetto per i workers BullMQ.
 
 1. Clicca sul servizio della tua app
 2. Vai su "Settings":
-   - Build Command: `npm run build`
-   - Start Command: `npm run start`
+   - Build Command: `pnpm run build`
+   - Start Command: `pnpm run start`
 3. Vai su "Variables" e aggiungi:
 
 ```
@@ -91,7 +91,7 @@ Nota: `DATABASE_URL` e `REDIS_URL` vengono iniettate automaticamente se hai coll
 
 1. Nel progetto, clicca "New" → "GitHub Repo" → stesso repo
 2. Settings:
-   - Start Command: `npm run worker`
+   - Start Command: `pnpm run worker`
 3. Collega lo stesso PostgreSQL e Redis (clicca sul DB → "Connect" → seleziona il servizio worker)
 4. Copia le stesse variabili d'ambiente del servizio app
 
@@ -100,11 +100,11 @@ Nota: `DATABASE_URL` e `REDIS_URL` vengono iniettate automaticamente se hai coll
 Railway esegue il build automaticamente. Per le migrazioni:
 
 1. Vai sul servizio app → "Settings"
-2. Cambia Build Command a: `npx prisma migrate deploy && npm run build`
+2. Cambia Build Command a: `pnpm exec prisma migrate deploy && pnpm run build`
 
 Oppure usa la Railway CLI:
 ```bash
-railway run npx prisma migrate deploy
+railway run pnpm exec prisma migrate deploy
 ```
 
 ### Passo 6: Dominio custom
@@ -140,12 +140,12 @@ railway run npx prisma migrate deploy
 
 ```
 1. render.com → New Web Service → connetti GitHub
-2. Build: npm run build
-3. Start: npm start
+2. Build: pnpm run build
+3. Start: pnpm start
 4. New → PostgreSQL (free 256MB)
 5. New → Redis (free)
 6. New → Background Worker (per i workers BullMQ)
-   Start: npm run worker
+   Start: pnpm run worker
 7. Configura le stesse variabili d'ambiente
 ```
 
@@ -188,7 +188,7 @@ Se hai un VPS (Hetzner €4/mese):
 ### Obbligatori
 - [ ] Dominio registrato e DNS configurato
 - [ ] SSL attivo (automatico su Railway/Render/Fly)
-- [ ] Database migrato (`npx prisma migrate deploy`)
+- [ ] Database migrato (`pnpm exec prisma migrate deploy`)
 - [ ] Variabili d'ambiente produzione configurate
 - [ ] Stripe live keys configurate
 - [ ] Webhook Stripe endpoint produzione attivo

docs/technical_status/SETUP.md → docs/SETUP.md

@@ -5,7 +5,7 @@
 | Strumento                   | Versione          | Scopo                     |
 | --------------------------- | ----------------- | ------------------------- |
 | **Node.js**                 | ≥ 20 LTS          | Runtime                   |
-| **pnpm** (o npm/yarn)       | ≥ 9               | Package manager           |
+| **pnpm**                    | ≥ 10              | Package manager           |
 | **Docker + Docker Compose** | Qualsiasi recente | PostgreSQL + Redis locali |
 | **Stripe CLI**              | Ultima            | Forward webhook in locale |
 
@@ -80,8 +80,8 @@ EMAIL_FROM="FiscLink <noreply@tuodominio.it>"
 ### 2.4 Inizializza il database
 
 ```bash
-npx prisma migrate dev --name init
-npx prisma generate
+pnpm exec prisma migrate dev --name init
+pnpm exec prisma generate
 ```
 
 ### 2.5 Avvia l'app
@@ -105,7 +105,7 @@ La CLI stamperà il webhook signing secret (`whsec_...`), salvalo in `.env` come
 ### 2.7 Avvia i worker (in un terminale separato)
 
 ```bash
-npx tsx src/lib/workers/start.ts
+pnpm exec tsx src/lib/workers/start.ts
 ```
 
 I worker elaborano le code BullMQ: creazione fatture, invio SDI, magic link, rimborsi.
@@ -182,7 +182,7 @@ Database: PostgreSQL (Prisma ORM)
 I worker BullMQ **non** girano su Vercel (serverless ≠ long-running).
 Opzioni:
 
-- **Railway**: Crea un servizio con start command `npx tsx src/lib/workers/start.ts`
+- **Railway**: Crea un servizio con start command `pnpm exec tsx src/lib/workers/start.ts`
 - **Fly.io**: Dockerfile con CMD per i worker
 - **VPS**: PM2 con `pm2 start src/lib/workers/start.ts --interpreter=tsx`
 
@@ -236,7 +236,7 @@ Opzioni:
 ### Database
 
 - [ ] Backup automatici configurati (Supabase li include)
-- [ ] Migration eseguita: `npx prisma migrate deploy`
+- [ ] Migration eseguita: `pnpm exec prisma migrate deploy`
 - [ ] Indici verificati (Prisma li crea da schema)
 
 ### Monitoraggio
@@ -259,14 +259,14 @@ Opzioni:
 ```bash
 # Sviluppo
 pnpm dev                                    # App Next.js
-npx tsx src/lib/workers/start.ts            # Worker BullMQ
+pnpm exec tsx src/lib/workers/start.ts            # Worker BullMQ
 stripe listen --forward-to localhost:3000/api/webhooks/stripe?merchant=ID
 
 # Database
-npx prisma studio                           # GUI database
-npx prisma migrate dev --name <nome>        # Nuova migration
-npx prisma migrate deploy                   # Applica in produzione
-npx prisma generate                         # Rigenera client
+pnpm exec prisma studio                     # GUI database
+pnpm exec prisma migrate dev --name <nome>  # Nuova migration
+pnpm exec prisma migrate deploy             # Applica in produzione
+pnpm exec prisma generate                   # Rigenera client
 
 # Test
 pnpm test                                   # Tutti i test