From f1cc929f1853629ee2e3bf6beb7e384e59fedf49 Mon Sep 17 00:00:00 2001 From: Norbert Maciaszek Date: Sat, 27 Dec 2025 00:22:13 +0100 Subject: [PATCH] update spec --- spec.md | 464 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 464 insertions(+) create mode 100644 spec.md diff --git a/spec.md b/spec.md new file mode 100644 index 0000000..a01b13d --- /dev/null +++ b/spec.md @@ -0,0 +1,464 @@ +# Gift Planning App – MVP Specification + +**Project Name:** Gift Planner +**Created:** December 26, 2025 +**Status:** Pre-development / Discovery Phase + +--- + +## 1. Project Vision & Goals + +### Business Goal +Aplikacja wspomaga planowanie i śledzenie prezentów na dowolne okazje (święta, urodziny, rocznice), automatyzując zarządzanie budżetem, listami osób i śledzeniem cen. + +### Success Metrics (do doprecyzowania) +- Liczba zarejestrowanych userów +- % userów, którzy ukończy workflow od okazji do budżetu +- Engagement z AI recommendations +- Średni czas planowania okazji + +### Ograniczenia na start +- Budżet: TBD +- Deadline MVP: TBD +- Zespół: TBD +- Geograficznie: Polska (Ceneo integration) + +--- + +## 2. Core Domain – MVP Scope + +### User & Authentication +- [ ] Rejestracja / logowanie (email + hasło) +- [ ] Profil usera (opcjonalnie: foto, preferencje powiadomień) +- [ ] **Bez social logins na MVP** +- [ ] Brak współdzielenia list (single-user na MVP) + +### Globalna Lista Osób (User Resource) +Przypisana do usera, reużywalna między okazjami. + +**Pola:** +- `id`, `userId` +- `name` (imię/pseudonim) +- `relation` (np. matka, przyjaciel, partner – dla kontekstu AI) +- `age` (opcjonalnie, dla AI recommendations) +- `interests` (notatki/tagi: sport, gaming, moda itp.) +- `notes` (profilowanie AI: styl życia, ulubione kolory, unikanie konkretnych rzeczy) +- `createdAt`, `updatedAt` + +**Pola (Rozszerzone UI):** +- `birthDate` (Data urodzin) +- `nameDay` (Data imienin - format MM-DD) +- `clothingSizes` (JSON: { top: "M", bottom: "38", shoe: "39" }) +- `avoidances` (Alergie, rzeczy nielubiane - kluczowe dla AI) +- `links` (Wishlista, profil social media) + +**Uwaga:** Specyficzne daty (jak urodziny osoby) są traktowane jako standardowe obiekty `Occasion`, co pozwala na przypisanie wielu prezentów do jednego wydarzenia osobistego. + +**Operacje:** +- CRUD na osobach +- Lista osób dla danego usera +- Search/filter po nazwie + +--- + +### Okazja (Occasion) +Kontener dla prezentów i budżetu w konkretnym kontekście czasowym. + +**Pola:** +- `id`, `userId` +- `title` (np. "Święta 2025", "Urodziny Anny") +- `description` (opcjonalnie) +- `date` (przybliżona data okazji) +- `totalBudget` (opcjonalnie, całkowity budżet na okazję) +- `status` (draft, planning, shopping, done) +- `createdAt`, `updatedAt` + +**Operacje:** +- CRUD na okazjach +- Lista okazji dla danego usera +- Filtry: aktywne, przeszłe, po dacie + +--- + +### Powiązanie Osoba ↔ Okazja +Tablica łączy osoby z okazjami (wiele-do-wielu). + +**Pola:** +- `id`, `occasionId`, `personId` +- `budgetPerPerson` (opcjonalnie, Budget przydzielony dla tej osoby na tę okazję) +- `notes` (opcjonalnie, specyficzne notatki dla tej osoby w ramach tej okazji) +- `createdAt` + +**Operacje:** +- Dodaj osoby do okazji (można masowo) +- Usuń osobę z okazji +- Edytuj budżet per osoba + +--- + +### Produkt (Product Master) +Baza rzeczywistych przedmiotów, które mogą być prezentami. + +**Pola:** +- `id` +- `title` (nazwa modelu/produktu) +- `description` (pełny opis techniczny) +- `ean` / `sku` +- `imageUrl` +- `tags` (kategorie: kuchnia, gaming, itp.) +- `ceneoUrl` (link do porównywarki) +- `globalMinPrice`, `globalMaxPrice` (z historii śledzenia) + +--- + +### Prezent - Instancja (Gift / Planning Instance) +Konkretny plan podarowania produktu danej osobie na wybraną okazję. + +**Pola:** +- `id`, `productId` (FK), `occasionId` (FK), `personId` (FK) +- `status` (idea, selected, bought, wrapped, given) +- `purchasePrice` (cena, za którą faktycznie kupiliśmy) +- `purchaseStore` (sklep, w którym dokonano zakupu) +- `orderNumber` (opcjonalnie) +- `personalNotes` (notatki specyficzne dla tego obdarowanego) +- `createdAt`, `updatedAt` + +**Operacje:** +- CRUD na instancjach prezentów +- Śledzenie statusu zakupu per osoba +- Powiązanie z globalną kartą produktu + +--- + +### Centrum Aktualizacji (Updates Center) +Spersonalizowany feed powiadomień. + +**Typy aktualizacji:** +- **Okazja cenowa**: Spadek ceny rynkowej produktu z karty produktu. +- **Zbliżająca się okazja**: Countdown do wydarzeń (globalnych i mini-okazji). +- **Inspiracja AI**: Nowe propozycje na podstawie profilu osoby. +- **Raport budżetowy**: Podsumowanie wydatków w danym miesiącu. + +--- + +### Budżet & Postęp (Occasion Analytics) +Obliczone **automatycznie** na podstawie prezentów i okazji. + +**Per Okazja:** +- Całkowity budżet (suma `totalBudget` lub suma `budgetPerPerson` dla wszystkich osób) +- Wydane dotychczas (suma `price` prezentów ze statusem ≥ "selected") +- Pozostały budżet +- % wykorzystania budżetu +- Liczba osób +- Liczba prezentów (total, ready/wrapped, pending) + +**UI Representation:** +- Progress bar: wydane / budżet +- Liczniki: "3 z 5 osób gotowych", "12 z 15 prezentów" +- Alert, jeśli przekraczamy budżet + +--- + +## 3. Secondary Features – Phase 2 (Post-MVP) + +### Price Tracking via Ceneo + +**Architecture:** +- User dodaje `url` do prezentu (dowolny link, np. ceneo.pl/...) +- Backend: cron job (raz dziennie lub częściej) + manualne "refresh" przez UI +- Pobieranie aktualnej ceny z API Ceneo / scrapingiem (Apify) +- Zapis snapshotu ceny do tabeli `PriceSnapshot(giftId, price, timestamp, source)` + +**Pola Gift (extended):** +- `currentPrice` (najniższa cena z ostatniego snapshotu) +- `priceHistory` (relacja do `PriceSnapshot`) +- `priceAlert` (boolean: czy śledzić zmiany cen?) +- `priceAlertThreshold` (opcjonalnie: powiadom, gdy spadnie poniżej X) + +**UI Features:** +- Mini-sparkline / mini-wykres ostatnich 30 dni cen +- Badge: "Najtaniej w 2 tygodniach" lub "Drożej o X%" od średniej +- Alert: "Cena spadła poniżej progu – dobry moment!" + +**Powiadomienia (Phase 2):** +- Email/push alert, gdy cena spadnie poniżej threshold +- Reminder: "Zbliżają się święta – ceny mogą wzrosnąć" +- Scheduled reminder: "Sprawdzaj ceny tego prezentu co 3 dni" + +--- + +### AI Gift Recommendations (Phase 2) + +**Use Case:** +User przychodzi na okazję, widzi osobę w liście, kliknie "Suggest Gifts" → AI generuje 5–10 propozycji z uzasadnieniami. + +**Input Context (AI):** +- Profil osoby: wiek, zainteresowania, relacja +- Okazja: typ, budżet per osoba, pozostały budżet na całą okazję +- Historia: jakie prezenty już kupił/planuje dla tej osoby w historii (unikaj duplikatów) +- Unikalność: weź pod uwagę, jakie prezenty planuje dla innych osób (różnorodność) + +**Output:** +- Lista propozycji: [{ title, category, priceRange, reason, matchScore }] +- Reason: "Lubisz gaming, a wiek sugeruje..." itp. +- Link do szukania: łatwe przejście do Ceneo/Google Shopping + +**Implementacja:** +- LLM (OpenAI API / local Ollama / inne) +- Prompt engineering: struktura context + constraints (budżet, unikalne przedmioty) +- User ręcznie decyduje, co dodać (zero auto-dodawania, pełna kontrola) + +--- + +## 4. Architektura Techniczna (High Level) + +### Tech Stack (Proposed) +- **Frontend:** React 19 + Next.js (App Router) + - Server Components dla list/agregacji + - Client Components dla interaktywnych formularzy + - TanStack Query do synchronizacji danych + +- **Backend:** Node.js / Next.js API Routes lub oddzielny backend (Express/NestJS) + - REST API lub GraphQL (tbd) + - Autentykacja: JWT / session-based + +- **Database:** PostgreSQL (+ Prisma ORM) + - Wersjonowanie: migrations + +- **External Services:** + - Ceneo API / Apify scraper (Phase 2) + - OpenAI API lub self-hosted LLM (Phase 2) + - Email service (e.g., SendGrid, Resend) dla alertów (Phase 2) + +- **Deployment:** TBD (Vercel, self-hosted, AWS, etc.) + +--- + +### Database Schema (Sketch) + +``` +User +├── id (PK) +├── email (UNIQUE) +├── password_hash +├── created_at +└── updated_at + +Person +├── id (PK) +├── user_id (FK) +├── name +├── relation +├── age +├── interests (TEXT / JSON) +├── notes +├── created_at +├── updated_at + +Occasion +├── id (PK) +├── user_id (FK) +├── title +├── description +├── date +├── total_budget +├── status (draft | planning | shopping | done) +├── created_at +├── updated_at + +OccasionPerson (M2M) +├── id (PK) +├── occasion_id (FK) +├── person_id (FK) +├── budget_per_person +├── notes +├── created_at + +Product +├── id (PK) +├── title +├── description +├── imageUrl +├── tags (JSON) +├── ean +├── ceneo_url +├── created_at + +Gift (Planning Instance) +├── id (PK) +├── product_id (FK) +├── occasion_id (FK) +├── person_id (FK) +├── status (idea | selected | bought | wrapped | given) +├── purchase_price (cena zakupu) +├── purchase_store +├── personal_notes +├── created_at + +IndividualOccasion (Zrezygnowano - używamy tabeli Occasion) +``` +``` + +--- + +### API Endpoints (MVP, Sketch) + +#### Auth +- `POST /api/auth/register` → register user +- `POST /api/auth/login` → login user +- `POST /api/auth/logout` → logout + +#### Persons +- `GET /api/persons` → list all persons for logged user +- `POST /api/persons` → create person +- `PUT /api/persons/:id` → update person +- `DELETE /api/persons/:id` → delete person + +#### Occasions +- `GET /api/occasions` → list occasions for logged user +- `POST /api/occasions` → create occasion +- `PUT /api/occasions/:id` → update occasion +- `DELETE /api/occasions/:id` → delete occasion +- `GET /api/occasions/:id` → get occasion with full context + +#### OccasionPerson (Managing persons in occasion) +- `POST /api/occasions/:id/persons` → add person(s) to occasion +- `DELETE /api/occasions/:id/persons/:personId` → remove person +- `PUT /api/occasions/:id/persons/:personId` → update budget_per_person + +#### Gifts +- `GET /api/occasions/:id/gifts` → list gifts for occasion +- `POST /api/occasions/:id/gifts` → create gift for person +- `PUT /api/gifts/:id` → update gift (title, status, price, url, etc.) +- `DELETE /api/gifts/:id` → delete gift + +#### Occasion Analytics (computed read-only) +- `GET /api/occasions/:id/analytics` → budget, postęp, countdowny + +--- + +## 5. UI/UX Flow (MVP) + +### Key Views + +#### 1. Dashboard (Home) +- Recent Gifts: szybki podgląd ostatnio dodanych planów +- Active Occasions cards +- Quick AI Suggestions banner + +#### 6. Kalendarz Okazji, Inspiracje i Poradniki (Templates & Blog) +* **Global Holidays**: Biblioteka ogólnych świąt (Dzień Matki, Boże Narodzenie) z opcją „Użyj jako szablon”. +* **Inspiracje (Global Products)**: Baza produktów sugerowanych przez AI, posortowana kategoriami (Elektronika, Wellness itp.). +* **Blog i Poradniki**: Serce treści SEO aplikacji. Artykuły łączące poradnictwo (np. "Jak wybrać prezent") z bezpośrednimi linkami do produktów i okazji. + - **Shoppable Content**: Możliwość dodawania produktów bezpośrednio z treści artykułu do planów użytkownika. + - **Nienachalne Reklamy**: Sekcje promujące konkretne marki lub produkty w kontekście merytorycznych wpisów. + - **Analiza Wektorowa AI**: Sugerowanie artykułów i produktów na podstawie zainteresowań wyłapanych z profili osób. +* **One-Click Add**: Możliwość szybkiego przypisania produktu z bazy inspiracji do konkretnej osoby i okazji w aplikacji. +* **Wyszukiwarka AI**: Interaktywne pole tekstowe pozwalające na dopytanie AI o konkretne pomysły spoza bazy. + +#### 3. Centrum Aktualizacji (Updates) +- Feed powiadomień: price drops, countdowns, AI ideas, budget alerts + +#### 3. Osoba Detail (Relationship Hub) +- Aktywne okazje osobiste i globalne (np. "Urodziny", "Święta") +- AI Profiler: zarządzanie preferencjami dla LLM +- Historia zakupowa ("Ostatnio kupione") + +#### 4. Karta Produktu (Product Master) +- Globalna historia ceny (wykres 30 dni) +- Porównywarka Ceneo (oferty sklepów) +- Lista planów, w których występuje ten produkt (re-use) + +#### 5. Gift Planning (Instance View) +- Logistyka: status, notatki zakupowe, numer zamówienia +- Analiza ceny zakupu vs cena rynkowa + +#### 6. Settings +- Profil usera i wylogowanie + +#### 7. Globalny Budżet (Budget Hub) +- Wykres wydatków miesięcznych +- Podział na kategorie (Elektronika, Zabawki, Dom) +- Lista ostatnich transakcji +- Statystyki "Wydane w tym roku" + +#### 8. Occasion Details (Tabs) +Widok okazji podzielony na zakładki: +1. **Lista Osób**: Karty osób z przypisanymi prezentami i budżetem per osoba. +2. **Wszystkie Prezenty**: Zbiorcza lista prezentów (Flat list) do łatwego zarządzania statusami (Kupione/Zapakowane). +3. **Analiza AI**: Sugestie i porady dotyczące optymalizacji budżetu i doboru prezentów. + +--- + +## 6. MVP Definition & Phasing + +### MVP = Everything in Section 2 (Core Domain) +- ✅ User auth +- ✅ Persons management (global reusable list) +- ✅ Occasions CRUD +- ✅ Connect persons to occasions +- ✅ Gifts CRUD + status tracking +- ✅ Budget & postęp calculations +- ✅ Aggregate gift list per occasion + +**Timeline:** ~4–8 weeks (team-dependent) + +### Phase 2 (Post-MVP, ~4 weeks after) +- Price tracking via Ceneo + PriceSnapshot table +- Price alerts & notifications (email/push) +- AI gift recommendations (LLM integration) + +### Phase 3+ (Nice-to-have, Later) +- Collaborative lists (share occasion with family) +- Analytics: roczne porównania, trendy wydatków +- Export to PDF/calendar +- Mobile app (native or responsive PWA) +- Social: wishlist sharing, gift registry + +--- + +## 7. Key Decisions & Assumptions (To Validate) + +- [ ] Single-user MVP (no collaboration) – OK? +- [ ] Auth method: email/password or OAuth? (assuming email/pwd for MVP) +- [ ] Database: PostgreSQL assumption – confirm? +- [ ] Ceneo integration: API lub web scraping? (Apify fallback) +- [ ] AI model: OpenAI API czy local/self-hosted? (cost/privacy trade-off) +- [ ] Monetization: subscription, freemium, ads? (affects feature gating) +- [ ] Mobile-first design czy desktop-first? (assuming mobile-responsive on MVP) + +--- + +## 8. Next Steps + +1. **Validate domain model** – robi sens struktura User → Occasion → Person → Gift? +2. **Detailed API spec** – co dokładnie zwraca endpoint? +3. **UI wireframes** – sketche ekranów +4. **Phase 1 backlog** – rozbić MVP na user stories + tasking +5. **Tech setup** – inicjalizacja repo, struktura projektu, Prisma schema +6. **First feature cycle** – login/register → Person CRUD → Occasion CRUD + +--- + +## 9. Assumptions & Open Questions + +### Business +- Czy aplikacja ma być darmowa czy z opcjami premium? +- Target audience: Polska czy szerzej? +- Launch timeline? + +### Technical +- Czy self-hosted czy cloud (Vercel, Railway)? +- Rate limits dla Ceneo API czy backup plan? +- Jak long-term archivizować stare okazje? + +### Product +- Czy dark mode na MVP? +- Czy offline support (PWA)? +- Czy mobile app native czy Web + PWA? + +--- + +**Document Version:** 1.0 +**Last Updated:** December 26, 2025 +**Status:** Awaiting validation & feedback