feat(billing): Stripe + abbonamento Pro con trial 30gg (ADR 0004)

Chiude la decisione "payment provider" aperta in CLAUDE.md.

**Modello**: free 30gg post-signup (no carta richiesta) → Pro mensile €9,90 / annuale €89. Allinea il paywall al confine fra fase INTENSIVE e TRANSITION (PRD §5.1), quando l'utente ha già visto i primi risultati. Dopo la scadenza l'app non si "spegne": storico restano consultabili (sola lettura), ma generazione piani / nuove pesate / digiuni / foto / export richiedono abbonamento attivo.

**Schema**: nuova tabella `subscriptions` (1:1 con users) con stati TRIALING/ACTIVE/PAST_DUE/CANCEL_AT_PERIOD_END/CANCELED/EXPIRED + `billing_webhook_events` per idempotenza dei retry Stripe.

**Backend** (`apps/api/src/modules/billing/`):
- `GET /me/billing/status` — snapshot + derived (kind, isPro, trialDaysRemaining)
- `POST /me/billing/checkout` — crea Stripe Checkout Session (subscription mode + Stripe Tax + tax_id_collection)
- `POST /me/billing/portal` — Customer Portal Session
- `POST /webhooks/stripe` — raw body, firma HMAC, idempotenza per `event.id`, dispatch su `customer.subscription.*`, `checkout.session.completed`, `invoice.payment_failed`
- Plugin `requirePro()` (402 payment_required) applicato a 9 rotte: meal-plans CRUD, weight-entries POST, check-ins POST, fast-events POST/PATCH, fasting/pause POST, export.pdf (plan+tracking)

**Shared** (`@ketopath/shared/billing/pro-status`):
- `isProActive(snap)` — verifica live (gestisce anche TRIALING con `trialEndsAt` passato in caso di cron in ritardo)
- `deriveProStatus(snap)` — kind + isPro + trialDaysRemaining + accessEndsAt per l'UI
- `computeTrialEndsAt(signupAt, days=30)`
- 11 unit test

**Frontend** (`apps/web/src/app/[locale]/billing/`):
- Pagina `/billing` editoriale (capitolo VIII) con StatusBlock per ogni kind, BillingActionsBar client (transitions, redirect a Stripe), 3 benefits
- `<TrialBanner>` in SignedInDashboard (3 stati: trial in corso oro / scaduto pomodoro / past_due pomodoro)
- Nav item "Abbonamento" (chapter VI) nel grid asimmetrico
- i18n IT completo (`Billing` namespace)

**Soft-degradation**: env Stripe (`STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, `STRIPE_PRICE_ID_*`, `BILLING_RETURN_URL`) sono tutte opzionali. Senza configurazione i route billing rispondono 503 e il banner trial mostra "pagamenti non ancora attivati" — utenti in trial continuano a usare l'app.

99/99 test verdi, lint pulito su tutto il monorepo.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

packages/db/prisma/migrations/20260507091227_add_subscriptions/migration.sql

@@ -0,0 +1,53 @@
+-- CreateEnum
+CREATE TYPE "SubscriptionStatus" AS ENUM ('TRIALING', 'ACTIVE', 'PAST_DUE', 'CANCEL_AT_PERIOD_END', 'CANCELED', 'EXPIRED');
+
+-- CreateEnum
+CREATE TYPE "BillingInterval" AS ENUM ('MONTH', 'YEAR');
+
+-- CreateTable
+CREATE TABLE "subscriptions" (
+    "id" TEXT NOT NULL,
+    "user_id" TEXT NOT NULL,
+    "status" "SubscriptionStatus" NOT NULL,
+    "trial_ends_at" TIMESTAMP(3) NOT NULL,
+    "stripe_customer_id" TEXT,
+    "stripe_subscription_id" TEXT,
+    "stripe_price_id" TEXT,
+    "current_period_end" TIMESTAMP(3),
+    "interval" "BillingInterval",
+    "cancel_at_period_end" BOOLEAN NOT NULL DEFAULT false,
+    "ended_at" TIMESTAMP(3),
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "subscriptions_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "billing_webhook_events" (
+    "id" TEXT NOT NULL,
+    "type" TEXT NOT NULL,
+    "received_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "processed_at" TIMESTAMP(3),
+    "payload" JSONB NOT NULL,
+
+    CONSTRAINT "billing_webhook_events_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "subscriptions_user_id_key" ON "subscriptions"("user_id");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "subscriptions_stripe_customer_id_key" ON "subscriptions"("stripe_customer_id");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "subscriptions_stripe_subscription_id_key" ON "subscriptions"("stripe_subscription_id");
+
+-- CreateIndex
+CREATE INDEX "subscriptions_status_idx" ON "subscriptions"("status");
+
+-- CreateIndex
+CREATE INDEX "billing_webhook_events_type_idx" ON "billing_webhook_events"("type");
+
+-- AddForeignKey
+ALTER TABLE "subscriptions" ADD CONSTRAINT "subscriptions_user_id_fkey" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE CASCADE ON UPDATE CASCADE;

packages/db/prisma/schema.prisma

@@ -76,6 +76,23 @@ enum MealPlanStatus {
   ARCHIVED
 }
 
+// PRD §16.3 / ADR 0004 — stato dell'abbonamento. Mappato 1:1 sullo stato
+// Stripe ma mantenuto in DB come source-of-truth applicativo (l'API non
+// chiama Stripe a ogni request — usa il valore qui).
+enum SubscriptionStatus {
+  TRIALING            // free 30gg post-signup, no carta richiesta
+  ACTIVE              // pagante, in regola
+  PAST_DUE            // pagamento fallito, in retry da Stripe (grace period)
+  CANCEL_AT_PERIOD_END // canceled ma valido fino a fine periodo corrente
+  CANCELED            // canceled ed expired
+  EXPIRED             // trial scaduto senza upgrade
+}
+
+enum BillingInterval {
+  MONTH
+  YEAR
+}
+
 model User {
   id                   String    @id @default(cuid())
   email                String    @unique
@@ -97,6 +114,7 @@ model User {
 
   profile       Profile?
   preferences   Preferences?
+  subscription  Subscription?
   sessions      Session[]
   accounts      Account[]
   weightEntries WeightEntry[]
@@ -109,6 +127,49 @@ model User {
   @@map("users")
 }
 
+// ADR 0004 — abbonamento dell'utente. 1:1 con User. Lo stato è la verità
+// applicativa: il webhook Stripe lo aggiorna, ma le route che gating-ano
+// le feature leggono solo da qui (niente roundtrip Stripe).
+model Subscription {
+  id                   String             @id @default(cuid())
+  userId               String             @unique @map("user_id")
+  status               SubscriptionStatus
+  // Trial nativo (30gg post-signup, no carta). Sempre valorizzato.
+  trialEndsAt          DateTime           @map("trial_ends_at")
+  // Stripe: presente solo dopo il primo upgrade (checkout completato).
+  stripeCustomerId     String?            @unique @map("stripe_customer_id")
+  stripeSubscriptionId String?            @unique @map("stripe_subscription_id")
+  stripePriceId        String?            @map("stripe_price_id")
+  // Periodo corrente (Pro). Riflette `current_period_end` di Stripe.
+  currentPeriodEnd     DateTime?          @map("current_period_end")
+  interval             BillingInterval?
+  // Se `cancelAtPeriodEnd = true`, la sub è ancora ACTIVE ma non si rinnoverà.
+  cancelAtPeriodEnd    Boolean            @default(false) @map("cancel_at_period_end")
+  // Quando lo status è effettivamente expired/canceled, archiviamo la data.
+  endedAt              DateTime?          @map("ended_at")
+  createdAt            DateTime           @default(now()) @map("created_at")
+  updatedAt            DateTime           @updatedAt @map("updated_at")
+
+  user User @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@index([status])
+  @@map("subscriptions")
+}
+
+// ADR 0004 — registro idempotenza dei webhook Stripe. Stripe ritenta gli
+// eventi falliti, ricezione multipla è normale: scartiamo i duplicati su
+// `event.id` invece di applicare due volte lo stesso aggiornamento.
+model BillingWebhookEvent {
+  id          String   @id // event.id di Stripe (evt_...)
+  type        String
+  receivedAt  DateTime @default(now()) @map("received_at")
+  processedAt DateTime? @map("processed_at")
+  payload     Json
+
+  @@index([type])
+  @@map("billing_webhook_events")
+}
+
 // PRD §6 — sistema achievement: badge sbloccati man mano che l'utente
 // raggiunge milestone (prima pesata, primo digiuno, primo piano, ecc.).
 // `key` identifica univocamente l'achievement (vedi packages/shared).