# Widoki i scenariusze — Aplikacja Kuchenna

> **Cel dokumentu:** Opis wszystkich widoków aplikacji z obecnym stanem, scenariusze użytkownika i znane problemy. 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 | Elastyczne, 1–7 dni do przodu |
| Posiłki | 3 główne (śniadanie, obiad, kolacja) + dodatkowe przy treningu |
| Powtarzalność | Duża (zwłaszcza śniadania) — kopiowanie dnia kluczowe |
| Styl gotowania | Hybrydowy: trochę meal-prep, trochę na bieżąco |
| Zakupy | Mieszane: duże zakupy + uzupełnienia w tygodniu |
| Cel dietetyczny | Utrzymanie wagi, śledzenie per posiłek |
| Pomijanie posiłków | Jawne "pomijam" (jedzenie na mieście) |
| Przepisy | Na razie katalog wbudowany (9 przepisów), bez edytora |

### Kluczowe pain-pointy (zgłoszone)

1. Brak możliwości pominięcia slotu w planerze
2. Brak "Dodaj do planera" z widoku przepisu
3. Ilości na liście zakupów nie do edycji
4. Brak kalorii per slot w widoku dnia
5. Za dużo kliknięć w kluczowych flow

---

## 2. Przegląd widoków

### 2.1 Przepisy (`RecipeList`)

**Lokalizacja:** `js/views/RecipeList.js`

Siatka 2-kolumnowa kart przepisów generowana dynamicznie z `RECIPES`. Każda karta zawiera miniaturę (placeholder), tytuł, czas przygotowania, kalorie. Kliknięcie otwiera detal.

**Elementy:**
- Wyszukiwarka (real-time, po tytule i tagach)
- Przycisk filtrów (overlay)
- Siatka kart

**Stan:** Kompletny.

---

### 2.2 Filtry (`Filter`)

**Lokalizacja:** `js/views/Filter.js`

Overlay z chipami pór posiłku, tagami dietetycznymi i suwakiem czasu. Dynamicznie generowane z `MEAL_SLOTS` i tagów z `RECIPES`.

**Elementy:**
- Chipy: pory posiłku (z `MEAL_SLOTS`)
- Chipy: tagi dietetyczne (zbierane z `RECIPES`)
- Suwak: maksymalny czas przygotowania
- Przycisk "Wyczyść" + "Pokaż X wyników"

**Stan:** Kompletny.

---

### 2.3 Szczegóły przepisu (`RecipeDetail`)

**Lokalizacja:** `js/views/RecipeDetail.js`

Full-screen overlay z detalami przepisu. Trzy zakładki: Składniki, Kroki, Wartości.

**Elementy:**
- Hero (placeholder) + strzałka powrotu + **"Do planera"** (nowe)
- Tytuł, tagi, czas, kcal
- Selektor porcji (±) z przeliczaniem
- Zakładka Składniki: lista z checkboxami + badge stanu spiżarni + "Dodaj do listy zakupów"
- Zakładka Kroki: numerowane kroki
- Zakładka Wartości: kcal/białko/tłuszcze/węglowodany × porcje
- **Bottom sheet "Dodaj do planera"**: wybór dnia (7 dni) + slotu → zapis do planStore

**Stan:** Kompletny.

---

### 2.4 Planer posiłków (`MealPlanner`)

**Lokalizacja:** `js/views/MealPlanner.js`

Kalendarz (tydzień/miesiąc) + plan dnia z slotami posiłków.

**Elementy kalendarza:**
- Widok tygodnia ↔ miesiąca (swipe góra/dół)
- Nawigacja: ←/→ + "Dziś"
- Kropki pod dniem = zaplanowane posiłki

**Elementy planu dnia:**
- Nagłówek dnia + **"Kopiuj dzień"** (nowe)
- Karta podsumowania kalorycznego (kcal + makro, rozwijalne szczegóły)
- "Składniki na ten dzień" (badge z liczbą braków)
- Sloty posiłków (5 slotów z `MEAL_SLOTS`):
  - **Kcal per slot** w nagłówku (nowe)
  - Karty przepisów z porcjami, kcal, czasem, przyciskiem usuwania
  - Kliknięcie nazwy przepisu → RecipeDetail
  - "Dodaj przepis" / "Dodaj kolejny"
  - **"Pomijam"** przy pustym slocie (nowe) → slot przygaszony z "Cofnij"

**Bottom sheety:**
1. **Picker przepisów**: wyszukiwarka + "Ostatnio używane" + lista filtrowana do `allowedSlots`
2. **Składniki i spiżarnia**: porównanie potrzeb vs zapasy + prognoza tygodnia + "Dodaj braki"
3. **Kopiuj plan dnia**: lista 13 dni (3 wstecz, 10 do przodu) → kopiuje cały dzień

**Stan:** Kompletny.

---

### 2.5 Spiżarnia (`Pantry`)

**Lokalizacja:** `js/views/Pantry.js`

Przeglądanie i edycja stanów magazynowych składników.

**Elementy:**
- Wyszukiwarka
- Chipy filtrów kategorii
- Toggle "Tylko na stanie"
- Siatka chipów składników (kolorowana wg stanu)
- Bottom sheet edycji: ±, input, wartości odżywcze, "Dodaj na listę zakupów"

**Stan:** Kompletny.

---

### 2.6 Zakupy (`Shopping`)

**Lokalizacja:** `js/views/Shopping.js`

Zarządzanie listami zakupów.

**Elementy:**
- Selektor aktywnej listy
- Przycisk "Nowa lista"
- **Pasek akcji listy kuchennej** (widoczny gdy są zaznaczone pozycje):
  - "Kupione → spiżarnia" (z **potwierdzeniem** — nowe)
  - "Wyczyść kupione"
- Lista kuchenna: pogrupowana po kategorii, checkbox, **edycja ilości** (klik → prompt, nowe)
- Lista freeform: tekst + notatka, checkbox

**Stan:** Kompletny.

---

## 3. Przepływy między widokami

```
Przepisy ──[klik kartę]──→ Szczegóły przepisu
                              ├──[Dodaj do listy zakupów]──→ Zakupy (lista kuchenna)
                              └──[Do planera]──→ Planer (wybór dnia + slotu)

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

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

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

---

## 4. Scenariusze użytkownika

### Scenariusz 1: Przeglądanie przepisów

**Cel:** Użytkownik otwiera apkę, chce zobaczyć co jest dostępne.

1. Otwiera aplikację → widzi zakładkę **Przepisy** z siatką 9 kart
2. Przewija listę, czyta opisy i kalorie na kartach
3. Klika kartę "Makaron z pomidorami i bazylią"
4. Widzi detal: składniki, kroki, wartości odżywcze
5. Zmienia liczbę porcji z 1 na 3 → składniki i kcal się przeliczają
6. Przełącza zakładkę na "Kroki" → widzi kroki
7. Przełącza na "Wartości" → widzi makroskładniki ×3
8. Wraca strzałką ← do listy

**Znane problemy:**
- Brak zdjęć (szare placeholdery) — OK dla prototypu
- Po powrocie z detalu filtr/szukajka powinny się utrzymać (utrzymują się)

---

### Scenariusz 2: Szukanie przepisu na kolację

**Cel:** Użytkownik szuka czegoś konkretnego.

1. Wpisuje "łosoś" → lista filtruje się do 1 karty
2. Kasuje tekst → wracają wszystkie
3. Klika ikonę filtrów
4. Zaznacza "Kolacja" → lista się zawęża
5. Dodatkowo zaznacza tag "Wysokobiałkowe"
6. Ustawia suwak na max 25 min
7. Klika "Pokaż X wyników" → wraca do przefiltrowanej listy
8. Wybiera przepis i otwiera detal

**Znane problemy:**
- Brak wizualnego wskaźnika aktywnych filtrów na ikonce (badge/kropka)
- Po zamknięciu filtrów ← (zamiast "Pokaż") — zachowanie może być nieintuicyjne

---

### Scenariusz 3: Planowanie posiłków na tydzień

**Cel:** Użytkownik układa menu na kilka dni.

1. Przechodzi na zakładkę **Planer**
2. Widzi dzisiejszy dzień z demo-danymi
3. Klika na przepis w slocie → otwiera się detal
4. Wraca ← do planera
5. Klika następny dzień w kalendarzu
6. Widzi puste sloty, klika "Dodaj przepis" przy Śniadaniu
7. Picker: wpisuje fragment nazwy, widzi "Ostatnio używane"
8. Wybiera przepis → pojawia się w slocie z **kcal w nagłówku**
9. Przy obiedzie klika **"Pomijam"** (je na mieście) → slot przygaszony
10. Klika "Składniki na ten dzień" → widzi braki vs spiżarnia
11. Klika "Dodaj braki na dziś do listy" → toast
12. Następnego dnia: **"Kopiuj dzień"** → wybiera dzień docelowy → gotowe

**Znane problemy:**
- Po dodaniu braków brak informacji "już dodano" — ryzyko duplikacji
- "Kopiuj dzień" kopiuje też status "Pominięto"

---

### Scenariusz 4: Zarządzanie spiżarnią

**Cel:** Użytkownik sprawdza co ma w domu.

1. Przechodzi na zakładkę **Spiżarnia**
2. Widzi chipy składników pogrupowane po kategorii
3. Włącza "Tylko na stanie" → widzi co ma
4. Klika "Płatki owsiane" → bottom sheet
5. Ustawia 500g
6. Zamyka → chip zmienił się na zielony z "500 g"
7. Chce dodać mleko na listę → klika "Dodaj na listę" w sheecie

**Znane problemy:**
- Po zamknięciu bottom sheet scroll wraca na górę (re-render)
- Brak możliwości ręcznego wpisania ilości szybko (ale jest input type=number)

---

### Scenariusz 5: Zakupy w sklepie

**Cel:** Użytkownik jest w sklepie, odznacza kupione.

1. Otwiera zakładkę **Zakupy**
2. Widzi listę kuchenną pogrupowaną po kategorii
3. Bierze mleko z półki → klika checkbox → przekreślenie
4. Widzi `sourceNote`: "Braki z planu dnia"
5. Ilość się nie zgadza — klika na **ilość** → prompt → poprawia
6. Kupuje dalsze pozycje

**Znane problemy:**
- Kupione mieszają się z niekupionymi w grupie (brak separacji)
- Brak podsumowania: "Do kupienia: 5, kupione: 3"
- Na telefonie w sklepie — elementy mogłyby być większe

---

### Scenariusz 6: Po zakupach — przeniesienie do spiżarni

**Cel:** Użytkownik wrócił ze sklepu, aktualizuje spiżarnię.

1. Otwiera **Zakupy** → widzi zaznaczone pozycje
2. Pojawia się pasek: **"Kupione → spiżarnia"** i **"Wyczyść kupione"**
3. Klika "Kupione → spiżarnia" → **potwierdzenie z podglądem** pozycji
4. Potwierdza → toast "Przeniesiono X pozycji"
5. Kupione znikają z listy
6. Przechodzi do **Spiżarni** → stany zaktualizowane
7. Wraca do **Planera** → braki zmniejszone

**Znane problemy:**
- Brak undo (cofnięcia przeniesienia)

---

### Scenariusz 7: Gotowanie z przepisu

**Cel:** Użytkownik gotuje, sprawdza przepis krok po kroku.

1. Otwiera **Planer** → dzisiejszy dzień
2. Klika przepis w slocie Kolacja
3. Otwiera się detal → przełącza na "Kroki"
4. Czyta krok po kroku
5. Sprawdza ilość składnika → przełącza na "Składniki"
6. Wraca na "Kroki"

**Znane problemy:**
- Brak trybu "krok po kroku" (full-screen, jeden krok, swipe next)
- Ekran wygasa po chwili (brak wake lock)
- Nie ma checkboxa przy krokach

---

### Scenariusz 8: "Co mogę ugotować?"

**Cel:** Użytkownik ma coś w spiżarni, chce wiedzieć co da się z tego zrobić.

1. Otwiera **Spiżarnię** → widzi co ma
2. Chciałby kliknąć "Co mogę ugotować?" → **takiej funkcji jeszcze nie ma**
3. Musi ręcznie sprawdzać przepisy

**Propozycja:** Filtr "Mam składniki" w widoku Przepisy.

---

## 5. Tabela znanych problemów i luk

| # | Problem | Scenariusz | Status |
|---|---------|-----------|--------|
| 1 | Brak wskaźnika aktywnych filtrów na ikonce | 2 | TODO |
| 2 | Podwójne dodanie braków do listy zakupów | 3 | TODO |
| 3 | Kupione mieszają się z niekupionymi (brak separacji) | 5 | TODO |
| 4 | Brak podsumowania na liście zakupów (ile kupione/do kupienia) | 5 | TODO |
| 5 | Brak undo przy "Kupione → spiżarnia" | 6 | TODO |
| 6 | Brak trybu "krok po kroku" przy gotowaniu | 7 | PROPOZYCJA |
| 7 | Brak wake lock (ekran wygasa) | 7 | PROPOZYCJA |
| 8 | Brak filtra "Mam składniki" | 8 | PROPOZYCJA |
| 9 | Scroll spiżarni resetuje się po edycji | 4 | TODO |
| 10 | Zamknięcie filtrów ← vs "Pokaż" — niespójne zachowanie? | 2 | DO WERYFIKACJI |

---

## 6. Zrealizowane w ostatniej iteracji

| # | Funkcja | Widok |
|---|---------|-------|
| P1 | "Dodaj do planera" z widoku przepisu (wybór dnia + slotu) | RecipeDetail |
| P2 | Kopiowanie planu dnia na inny dzień | MealPlanner |
| P3 | "Pomijam" w slocie planera | MealPlanner + planStore |
| P4 | Kalorie per slot w nagłówku slotu | MealPlanner |
| P5 | Edycja ilości na liście zakupów (klik → prompt) | Shopping |
| P6 | Potwierdzenie "Kupione → spiżarnia" z podglądem | Shopping |
| P7 | Lepszy picker przepisów (wyszukiwarka + ostatnio używane) | MealPlanner |

---

## 7. Stos technologiczny

| Warstwa | Technologia |
|---------|-------------|
| Frontend | Plain HTML + ES modules, imperatywna manipulacja DOM |
| Style | Tailwind CSS (CDN), Font Awesome 6 (CDN) |
| Dane | Statyczny katalog `js/data/catalog.js`, localStorage |
| PWA | manifest.webmanifest + sw.js |
| Deploy | Docker + nginx:alpine, Gitea CI/CD |
| Język UI | Polski |