# 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) |