ulfrxdev
7944ad2dbf
All checks were successful
Build and Deploy / build-and-push (push) Successful in 27s
195 lines
10 KiB
Markdown
195 lines
10 KiB
Markdown
# 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)
|
||
RecipeDetail.js ← detal przepisu (oryginał, nieużywany — 3-zakładkowy)
|
||
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`)
|
||
|
||
> **Uwaga:** Istnieje starsza wersja (`RecipeDetail.js`) z 3 zakładkami (Składniki, Kroki, Wartości) i read-only alternatywami. Aktualnie nieużywana — import w `app.js` wskazuje na `RecipeDetailV2.js`.
|
||
|
||
**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) |
|