feat: catalogo+30, varianti, sostituti, reintroduzione Fase 2, free meal Fase 3 (PRD §5.1)

Quattro completamenti del PRD §5.1: catalogo, varianti/sostituti, fase 2,
free meal.

Catalogo ricette 16 → 46
- seed-recipes.ts: +30 ricette italiane keto bilanciate
  (8 colazione · 8 pranzo · 6 spuntino · 8 cena)
- seed-ingredients.ts: 33 → 55 ingredienti
  (verdura/carne/pesce/latticini/condimenti + categorie nuove `legumi` e
  `cereali` per Fase 2)
- seed.ts: ora fa upsert anche degli ingredienti pre-esistenti per
  propagare campi nuovi (es. phase2Week)

Varianti + sostituti
- Recipe.variants Json (array { name, description, kcalDelta? })
- RecipeIngredient.substitutes String[]
- /recipes/[id]: nuova sezione "Varianti suggerite" + riga "Sostituzioni:"
  sotto ogni ingrediente quando presenti

Reintroduzione progressiva Fase 2
- Ingredient.phase2Week (settimana minima di reintroduzione, NULL=sempre)
- User.phase2StartedAt: settato automaticamente quando si passa a TRANSITION
- @ketopath/shared/planner/phase-progression: currentPhase2Week,
  isRecipeAllowedForPhaseWeek, weeksSince
- plan.routes filtra fuori le ricette con ingredienti non ancora reintrodotti
- POST /me/profile/phase per avanzare di fase (idempotente sul timestamp)
- 12 unit test su phase-progression
- Esempi seed: lenticchie phase2Week=3, ceci=4, mela=5, pera=6, quinoa=7

Free Meal pianificato Fase 3
- MealSlot.isFreeMeal Boolean (default false)
- POST /me/meal-plans/slots/:id/free-meal toggle, valido solo in MAINTENANCE
- @ketopath/shared/planner/phase-progression: freeMealKcalAdjustment
  (compensazione clamp -200/+50 kcal per pasto sui rimanenti)
- /plan: bottone ☆ in ogni SlotCard quando phase=MAINTENANCE; lo slot
  marcato come pasto libero rende "Pasto libero pianificato" + ~750 kcal
  stimate; macro tracker ne tiene conto

Indicatori di fase nel piano
- /plan ora include currentPhase + phase2Week dalla API
- Header del piano: "Settimana N di Fase 2" o "Mantenimento — Fase 3"

i18n: namespaces Plan + Recipe arricchiti

Schema migration 20260429XXXXXX_add_meal_plan_extras.

66/66 unit test verdi (12 nuovi). Smoke verificato live: API ritorna
correctly i campi nuovi, UI rende badge fase, bottoni ☆/↻, free-meal slot.

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

apps/api/src/modules/plan/plan.routes.ts

@@ -5,8 +5,10 @@ import {
   calculateBmrKatchMcArdle,
   calculateTdee,
   computeDailyKcalTarget,
+  currentPhase2Week,
   extraKcalForSession,
   hasExcludingCondition,
+  isRecipeAllowedForPhaseWeek,
   isTrainingDay,
   macrosForPhase,
   matchMeals,
@@ -71,7 +73,9 @@ export const planRoutes: FastifyPluginAsync = async (fastify) => {
         phases: true,
         prepMinutes: true,
         ingredients: {
-          select: { ingredient: { select: { exclusionGroups: true } } },
+          select: {
+            ingredient: { select: { exclusionGroups: true, phase2Week: true } },
+          },
         },
       },
     });
@@ -79,7 +83,20 @@ export const planRoutes: FastifyPluginAsync = async (fastify) => {
       return reply.code(409).send({ error: 'recipe_catalog_empty' });
     }
 
-    const candidates: RecipeCandidate[] = recipes.map((r) => {
+    // PRD §5.1 — Reintroduzione progressiva: in fase 2 filtriamo le ricette
+    // che contengono ingredienti non ancora reintrodotti per la settimana
+    // corrente di fase 2.
+    const phaseIntForFilter = phaseToInt(profile.currentPhase);
+    const phase2WeekForFilter = currentPhase2Week(profile.user.phase2StartedAt);
+    const allowedRecipes = recipes.filter((r) =>
+      isRecipeAllowedForPhaseWeek(
+        r.ingredients.map((ri) => ({ phase2Week: ri.ingredient.phase2Week })),
+        phaseIntForFilter,
+        phase2WeekForFilter,
+      ),
+    );
+
+    const candidates: RecipeCandidate[] = allowedRecipes.map((r) => {
       const tags = new Set<string>();
       for (const ri of r.ingredients) {
         for (const g of ri.ingredient.exclusionGroups) tags.add(g);
@@ -266,6 +283,31 @@ export const planRoutes: FastifyPluginAsync = async (fastify) => {
     },
   );
 
+  // PRD §5.1 — toggle "pasto libero". Disponibile solo in Fase 3.
+  fastify.post(
+    '/me/meal-plans/slots/:slotId/free-meal',
+    { preHandler: requireAuth() },
+    async (request, reply) => {
+      const slotId = (request.params as { slotId: string }).slotId;
+      const userId = request.user!.id;
+      const slot = await fastify.prisma.mealSlot.findFirst({
+        where: { id: slotId, plan: { userId } },
+        include: { plan: true },
+      });
+      if (!slot) return reply.code(404).send({ error: 'slot_not_found' });
+      const profile = await fastify.prisma.profile.findUnique({ where: { userId } });
+      if (!profile) return reply.code(409).send({ error: 'profile_required' });
+      if (profile.currentPhase !== 'MAINTENANCE') {
+        return reply.code(409).send({ error: 'free_meal_phase3_only' });
+      }
+      const updated = await fastify.prisma.mealSlot.update({
+        where: { id: slotId },
+        data: { isFreeMeal: !slot.isFreeMeal },
+      });
+      return { slot: { id: updated.id, isFreeMeal: updated.isFreeMeal } };
+    },
+  );
+
   // PRD §5.1 — rigenera UN solo slot: ricalcola le top5 ricette tenendo
   // conto dei pasti del giorno già scelti (coerenza dei macros).
   fastify.post(
@@ -456,7 +498,7 @@ export const planRoutes: FastifyPluginAsync = async (fastify) => {
 
   fastify.get('/me/meal-plans/current', { preHandler: requireAuth() }, async (request, reply) => {
     const userId = request.user!.id;
-    const [plan, prefs] = await Promise.all([
+    const [plan, prefs, profileForPhase, userForPhase2] = await Promise.all([
       fastify.prisma.mealPlan.findFirst({
         where: { userId, status: 'ACTIVE' },
         orderBy: { weekStart: 'desc' },
@@ -494,14 +536,29 @@ export const planRoutes: FastifyPluginAsync = async (fastify) => {
         where: { userId },
         select: { fastingProtocol: true },
       }),
+      fastify.prisma.profile.findUnique({
+        where: { userId },
+        select: { currentPhase: true },
+      }),
+      fastify.prisma.user.findUnique({
+        where: { id: userId },
+        select: { phase2StartedAt: true },
+      }),
     ]);
     if (!plan) return reply.code(404).send({ error: 'plan_not_found' });
+    const currentPhase = profileForPhase?.currentPhase ?? null;
+    const phase2Week =
+      currentPhase === 'TRANSITION'
+        ? currentPhase2Week(userForPhase2?.phase2StartedAt ?? null)
+        : null;
     return {
       plan: {
         id: plan.id,
         weekStart: plan.weekStart.toISOString().slice(0, 10),
         slots: plan.slots,
         fastingProtocol: prefs?.fastingProtocol ?? null,
+        currentPhase,
+        phase2Week,
       },
     };
   });

apps/api/src/modules/profile/profile.routes.ts

@@ -153,6 +153,42 @@ export const profileRoutes: FastifyPluginAsync = async (fastify) => {
     return { profile: serialize(profile) };
   });
 
+  // PRD §5.1 — avanzamento di fase. Quando l'utente passa da INTENSIVE a
+  // TRANSITION (Fase 2), salviamo automaticamente phase2StartedAt sull'utente
+  // così la reintroduzione progressiva degli alimenti funziona dalla settimana
+  // corretta.
+  fastify.post('/me/profile/phase', { preHandler: requireAuth() }, async (request, reply) => {
+    const body = request.body as { phase?: unknown };
+    const phase = body.phase;
+    if (phase !== 'INTENSIVE' && phase !== 'TRANSITION' && phase !== 'MAINTENANCE') {
+      return reply.code(400).send({ error: 'invalid_phase' });
+    }
+    const userId = request.user!.id;
+    const profile = await fastify.prisma.profile.findUnique({ where: { userId } });
+    if (!profile) return reply.code(404).send({ error: 'profile_not_found' });
+
+    const transitioning = profile.currentPhase !== 'TRANSITION' && phase === 'TRANSITION';
+
+    await fastify.prisma.profile.update({
+      where: { userId },
+      data: { currentPhase: phase },
+    });
+    if (transitioning) {
+      // Setta phase2StartedAt solo se non già impostato (idempotente).
+      const user = await fastify.prisma.user.findUnique({
+        where: { id: userId },
+        select: { phase2StartedAt: true },
+      });
+      if (!user?.phase2StartedAt) {
+        await fastify.prisma.user.update({
+          where: { id: userId },
+          data: { phase2StartedAt: new Date() },
+        });
+      }
+    }
+    return { phase };
+  });
+
   // PATCH dedicato per le condizioni mediche: l'onboarding lo usa per salvare
   // solo questo delta senza richiedere tutti i campi obbligatori del PUT.
   fastify.patch('/me/profile/conditions', { preHandler: requireAuth() }, async (request, reply) => {