recipe-mockup/VIEWS_AND_SCENARIOS.md

Widoki i scenariusze — Aplikacja Kuchenna

Cel dokumentu: Opis widoków, przepływów i scenariuszy użytkownika. Odniesienie dla dalszego rozwoju.

Kontekst projektu: To jest prototyp / mockup — celem jest wypracowanie UX, logiki widoków i przepływów użytkownika. Finalna aplikacja będzie pisana w innym języku z backendem. Wartość tego prototypu to przede wszystkim: struktura widoków, scenariusze, model danych i decyzje UX — nie kod sam w sobie.

---

1. Profil użytkownika

Cecha	Opis
Liczba osób	1 (gotuje dla siebie)
Planowanie	Mieszane — część z wyprzedzeniem (np. niedziela na tydzień), część ad hoc na bieżąco
Posiłki	5 slotów (śniadanie, drugie śniadanie, obiad, przekąska, kolacja)
Powtarzalność	Duża (zwłaszcza śniadania), ale chce stopniowo urozmaicać
Styl gotowania	Hybrydowy: głównie na bieżąco, ale chce zacząć gotować na zapas (np. zupy na kilka dni)
Jedzenie poza domem	2–3× w tygodniu (restauracja, kantyna, zamówienie) — stąd jawne "Pomijam"
Zakupy	Duże zakupy raz w tygodniu + drobne uzupełnienia
Cel dietetyczny	Świadomość makro — chce widzieć wartości, ale nie liczy co do grama
Bóle	Brak inspiracji ("co ugotować?"), marnowanie jedzenia, brak czasu w tygodniu, chaotyczne zakupy
Przepisy	Katalog wbudowany (6 przepisów, 34 składniki), bez edytora

---

2. Architektura i stos technologiczny

Warstwa	Technologia
Frontend	Plain HTML + ES modules, imperatywna manipulacja DOM
Style	Tailwind CSS (CDN) + inline <style> w index.html, Font Awesome 6 (CDN)
Dane	Statyczny katalog js/data/catalog.js (INGREDIENTS + RECIPES z opcjonalnymi alternatives per składnik), localStorage
Stan	Moduły-closure (filterState, state w planerze) + localStorage przez serwisy
Komunikacja widoków	Globalne callbacki na window (refreshPlanner, refreshPantry, refreshShopping, openRecipeDetail itp.)
PWA	manifest.webmanifest + sw.js (network-only fetch, spełnia warunek instalowalności)
Deploy	Docker + nginx:alpine, Gitea CI/CD
Język UI	Polski

Struktura plików

index.html                    ← jedyny plik HTML, shell aplikacji
js/
  app.js                      ← entry point, montuje widoki, setupTabs()
  storageKeys.js              ← klucze localStorage
  views/
    RecipeList.js             ← lista przepisów
    Filter.js                 ← overlay filtrów
    RecipeDetailV2.js         ← detal przepisu (aktywna wersja)
    MealPlanner.js            ← planer posiłków + kalendarz
    Pantry.js                 ← spiżarnia
    Shopping.js               ← listy zakupów
  services/
    planStore.js              ← load/save planów posiłków
    pantryShopping.js         ← logika spiżarni i list zakupów
    planIngredients.js        ← analityka: sumy kalorii, braki, prognoza
    dateUtils.js              ← narzędzia dat (poniedziałek jako start tygodnia)
  planner/
    mealSlots.js              ← definicja 5 slotów (id, label, icon)
  data/
    catalog.js                ← INGREDIENTS, RECIPES, helpery
  ui/
    toast.js                  ← showAppToast()

---

3. Przegląd widoków

3.1 Przepisy (RecipeList)

Siatka 2-kolumnowa kart przepisów z wyszukiwarką i filtrami. Kliknięcie karty otwiera detal. Filtry (overlay Filter.js): pory posiłku, tagi dietetyczne, suwak czasu.

3.2 Szczegóły przepisu (RecipeDetailV2)

Slide-in overlay z detalami przepisu. Dwie zakładki: Składniki i Kroki.

Zakładka Składniki:

• Podsumowanie wartości odżywczych na górze (4-kolumnowa siatka: kalorie, białko, węgle, tłuszcze) — przeliczane dynamicznie z uwzględnieniem wybranych zamienników
• Składniki jako karty z wartościami odżywczymi per składnik (makro + kcal po prawej, obok gramów)
• Wymienne składniki — kliknięcie ikony shuffle rozwija listę opcji (oryginał + alternatywy) z radio-przyciskami; wybranie zamiennika: karta zmienia się na wybraną opcję (amber obramowanie), podsumowanie kaloryczne przelicza się na żywo
• Selektor porcji (±, zakres 1–12) przelicza składniki i wartości

Bottom sheet "Zaplanuj":

1. Kalendarz (tydzień/miesiąc, nawigacja ←/→/Dziś)
2. Pora posiłku — chipy filtrowane do allowedSlots przepisu
3. Wymienne składniki — wstępnie ustawione z wyborów na liście składników, z możliwością dalszej zmiany
4. Przycisk "Dodaj" → zapis do planStore (z opcjonalnym obiektem substitutions)

Model danych — wymienne składniki:

• W RECIPES, składnik może mieć pole alternatives: ['id1', 'id2', ...]
• Wybrane zamienniki zapisywane jako substitutions: { originalId: chosenAltId } w planStore
• Przykład: serek wiejski ma 3 wymienne składniki — orzechy (5 opcji), truskawki (banany), borówki (jagody)

3.3 Planer posiłków (MealPlanner)

Kalendarz (tydzień/miesiąc) + plan dnia z 5 slotami posiłków. Karty przepisów z porcjami (±), kcal, usuwaniem. "Pomijam" przy pustym slocie. Podsumowanie kaloryczne dnia. "Składniki na ten dzień" z porównaniem do spiżarni i prognozą tygodniową. Kopiowanie planu dnia. Picker przepisów do dodawania. Demo-dane przy pustym localStorage.

3.4 Spiżarnia (Pantry)

Chipy składników pogrupowane po kategorii z kolorami wg stanu. Wyszukiwarka, filtry kategorii, toggle "Tylko na stanie". Bottom sheet edycji z ± i inputem, wartościami odżywczymi, "Dodaj na listę zakupów".

3.5 Zakupy (Shopping)

Lista kuchenna (pogrupowana po kategorii, checkboxy, edycja ilości) + listy freeform. Pasek akcji dla zaznaczonych: "Kupione → spiżarnia" (z podglądem) i "Wyczyść kupione".

---

4. Przepływy między widokami

Przepisy ──[klik kartę]──→ Szczegóły przepisu
                              ├──[zamiana składnika]──→ podsumowanie przelicza się na żywo
                              └──[Zaplanuj]──→ Bottom sheet (kalendarz + pora + zamienniki z detalu) → Planer

Planer ──[klik przepis w slocie]──→ Szczegóły przepisu
       ──[Składniki na ten dzień]──→ Sheet: porównanie z spiżarnią + prognoza
       ──[Dodaj braki do listy]──→ Zakupy (lista kuchenna)
       ──[Kopiuj dzień]──→ Sheet: wybór dnia docelowego
       ──[Dodaj przepis]──→ Sheet: picker przepisów

Spiżarnia ──[Dodaj na listę zakupów]──→ Zakupy

Zakupy ──[Kupione → spiżarnia]──→ Spiżarnia (stany zaktualizowane)

---

5. Scenariusze użytkownika

Niedzielne planowanie tygodnia

Wieczorem w niedzielę siada z apką i układa plan na najbliższe 4–5 dni. Kopiuje sprawdzone dni, dodaje nowe przepisy tam gdzie chce urozmaicenie. Przy kilku posiłkach z góry wie, że będzie jeść poza domem — oznacza je jako pominięte. Sprawdza podsumowanie składników na zaplanowane dni, generuje braki na listę zakupów. Rano idzie do sklepu z gotową listą.

Co mu to daje: Nie musi codziennie myśleć "co ugotować". Kupuje celowo — mniej marnowania.

Poranek — rutynowe śniadanie z wariacją

Od tygodni je to samo śniadanie. Tym razem otwiera detal przepisu i klika shuffle przy jednym ze składników. Porównuje wartości odżywcze zamienników, wybiera coś innego. Podsumowanie kaloryczne przelicza się od razu — widzi, że różnica jest niewielka. Dodaje do planu z zamiennikiem.

Co mu to daje: Urozmaicenie bez wysiłku. Widzi wpływ zamiany na makro zanim się zdecyduje.

Środa wieczór — "nie chce mi się gotować"

Wraca zmęczony z pracy. Otwiera apkę — miał zaplanowany obiad, ale nie ma energii. Oznacza posiłek jako pominięty (zamówi albo zje na mieście). Albo: przegląda przepisy filtrując po czasie do 15 min, szybko coś wybiera i dodaje na dziś.

Co mu to daje: Brak poczucia winy — pominięcie jest jawne, plan się dostosowuje. Albo szybka alternatywa bez przeglądania całego katalogu.

Gotowanie na zapas

W weekend wybiera przepis na obiad i ustawia 3 porcje. Dodaje ten sam przepis na poniedziałek, wtorek i środę. Gotuje raz — ma obiady na trzy dni odhaczone. Składniki na liście zakupów są policzone na pełną ilość.

Co mu to daje: Oszczędność czasu w tygodniu. Jedno gotowanie zamiast trzech.

W sklepie z listą

Stoi w sklepie, otwiera listę zakupów. Produkty pogrupowane po kategoriach — idzie przez alejki i odznacza kolejne pozycje. Wraca do domu, klika "Kupione → spiżarnia" — stany magazynowe aktualizują się jednym ruchem.

Co mu to daje: Nie zapomina co kupić. Spiżarnia jest aktualna bez ręcznego wpisywania.

Sprawdzenie przed zakupami

Przed wyjściem do sklepu sprawdza spiżarnię — co jeszcze ma. Przechodzi do planera, ogląda najbliższe dni i klika "Dodaj braki do listy". Lista zakupów zawiera tylko to, czego naprawdę potrzebuje.

Co mu to daje: Nie kupuje podwójnie. Nie marnuje jedzenia, które zalega w szafce.

---

6. Znane problemy i propozycje ulepszeń

Do poprawy

#	Problem
1	Brak wskaźnika aktywnych filtrów na ikonce (badge/kropka)
2	Po dodaniu braków do listy zakupów brak ochrony przed duplikacją
3	Kupione pozycje mieszają się z niekupionymi w tej samej grupie
4	Brak podsumowania na liście zakupów ("Do kupienia: X, kupione: Y")
5	Brak undo przy "Kupione → spiżarnia"
6	Scroll spiżarni resetuje się po edycji (re-render)
7	"Kopiuj dzień" kopiuje też status "Pominięto" — może nie zawsze pożądane

Propozycje nowych funkcji

#	Funkcja	Opis
P1	Tryb "krok po kroku" przy gotowaniu	Full-screen, jeden krok, swipe next + checkbox
P2	Wake lock	Zapobiega wygaszeniu ekranu podczas gotowania
P3	Filtr "Mam składniki"	W widoku Przepisy — pokaż co da się ugotować z aktualnej spiżarni
P4	Większe elementy na liście zakupów	Ułatwienie obsługi w sklepie na telefonie
P5	Edytor przepisów	Dodawanie własnych przepisów (poza wbudowanym katalogiem)