Generated file. Source: docs/product_spec.md Edit the source document and run npm run docs:sync to refresh this published copy.

Specyfikacja Produktowa¶

Dokument PM -> Developer¶

Pole	Wartość
Produkt	`Kalkulator Obligacji Skarbowych`
Klasa dokumentu	`authoritative product specification`
Status dokumentu	`active`
Wersja	`1.1`
Ostatni przegląd	`2026-03-24`
Właściciel dokumentu	`Product Manager`
Odbiorca główny	`Developer`
Cel dokumentu	utrzymać wspólne rozumienie produktu, zakresu, statusu wdrożenia i kierunku rozwoju oraz ułatwić przekazywanie pracy między etapami

Spis treści¶

Cel dokumentu i sposób użycia
Kontekst produktu i problem użytkownika
Wizja produktu i cele biznesowe
Stan implementacji i mapa zakresu
Mapa źródeł prawdy
Obowiązujące decyzje projektowe
Grupy użytkowników
Ekrany produktu i ich odpowiedzialność
Diagramy i materiały wizualne
Główne przepływy użytkownika
Parametry wejściowe i ich znaczenie
Zasady prezentacji i interpretacji wyników
Wymagania funkcjonalne
Wymagania dotyczące danych
Granice produktu i odpowiedzialności warstw
Wymagania UX/UI
Wymagania niefunkcjonalne
Roadmapa produktu
Zależności i ryzyka
Kryteria akceptacji
Jak używać tej specyfikacji przy handoffie
Otwarte pytania
Dokumenty powiązane

1. Cel dokumentu i sposób użycia¶

1.1 Po co istnieje ten dokument¶

Dokument ma:

opisać produkt z perspektywy biznesowej i użytkowej
wskazać, co jest już wdrożone, a co dopiero planowane
dać developerowi mapę: gdzie szukać logiki, danych i decyzji projektowych
wspierać przejęcie pracy na dowolnym etapie bez zgadywania aktualnego stanu produktu

1.2 Czego ten dokument nie zastępuje¶

Ten dokument nie zastępuje:

dokumentacji technicznej silnika obligacji
dokumentacji logiki konkretnych strategii
osobnego dokumentu roadmapy produktu
testów
implementacji w kodzie

Te rzeczy są powiązane z niniejszą specyfikacją, ale nie są tu powielane w detalach implementacyjnych.

1.3 Jak czytać ten dokument¶

Przy pracy developerskiej należy czytać dokument w tej kolejności:

Stan implementacji i mapa zakresu
Obowiązujące decyzje projektowe
sekcję odpowiadającą obszarowi, który ma być zmieniany
Dokumenty powiązane

1.4 Znaczenie statusów¶

W dokumencie używane są statusy:

Implemented - zachowanie istnieje w aktualnym produkcie
Implemented / disabled - element jest obecny w produkcie, ale świadomie nie jest aktywny funkcjonalnie
Planned - zachowanie jest zatwierdzonym kierunkiem, ale nie jest jeszcze wdrożone
Out of scope - zachowanie nie należy do bieżącego zakresu

2. Kontekst produktu i problem użytkownika¶

2.1 Problem użytkownika¶

Użytkownik detaliczny zainteresowany obligacjami skarbowymi ma dziś kilka praktycznych trudności:

nie widzi szybko, która obligacja jest najlepsza dla jego konkretnego horyzontu inwestycji
nie rozumie, jak na wynik wpływają podatki, inflacja, koszt przedterminowego wykupu i reinwestycja
nie ma prostego sposobu porównania różnych obligacji rok po roku
materiały źródłowe zwykle opisują parametry emisji, ale nie pokazują pełnego wyniku inwestycji w czytelnej formie

2.2 Dlaczego to ma znaczenie¶

Ten problem ma znaczenie, bo użytkownik:

podejmuje decyzję finansową
może wybrać obligację nieoptymalną dla swojego horyzontu
może błędnie interpretować oprocentowanie jako wynik końcowy
może nie rozumieć, że część kosztów i podatków pojawia się dopiero w końcowym rozliczeniu

2.3 Szansa produktowa¶

Produkt ma dwa poziomy potencjału:

kalkulator porównawczy obligacji
fundament pod przyszły produkt portfelowy oparty o konkretne emisje i historię inwestora

3. Wizja produktu i cele biznesowe¶

3.1 Cel główny¶

Dać użytkownikowi wiarygodne, czytelne i szybkie narzędzie do porównania opłacalności inwestycji w detaliczne obligacje skarbowe.

3.2 Cele szczegółowe¶

zwiększyć zrozumienie różnic między typami obligacji
ułatwić wybór najlepszego instrumentu dla danego horyzontu
pokazać wynik końcowy i przebieg inwestycji w czasie
przygotować produkt i warstwę danych pod przyszły rozwój portfelowy

3.3 Wizja długoterminowa¶

Docelowo produkt ma dojść do stanu, w którym:

dane wejściowe są częściowo aktualizowane automatycznie
użytkownik może pracować na scenariuszach inflacyjnych
możliwe jest modelowanie regularnych inwestycji
istnieje baza danych emisji i fundament pod portfel inwestycyjny
użytkownik może uruchomić kalkulator także przez asystenta, który zadaje pytania, wypełnia formularz i uruchamia tę samą symulację co tryb ręczny

4. Stan implementacji i mapa zakresu¶

4.1 Status modułów produktu¶

Obszar	Status	Uwagi
Wybór obligacji do porównania	`Implemented`	Kafelki i tabela, logika dostępności obligacji rodzinnych; bez limitu kwotowego `800+`
Parametry inwestycji	`Implemented`	Kwota, okres, inflacja, stopa referencyjna, 800+
Typ rachunku	`Implemented / disabled`	Widoczne w UI, bez wpływu na obliczenia
Wykres porównawczy	`Implemented`	Przełączanie metryk i trybu słupkowy/liniowy oraz respektowanie globalnego trybu analizy
Podsumowanie wyników	`Implemented`	Tabela i kafelki, ranking, filtry kolumn oraz respektowanie globalnego trybu analizy
Szczegółowa tabela roczna	`Implemented`	Widok pojedynczej obligacji i widok porównawczy, filtry kolumn, wybór obligacji, dwa układy grupowania danych oraz respektowanie globalnego trybu analizy: przebieg inwestycji / rozliczenie rok po roku; lokalny interfejs przełącznika steruje tym samym wspólnym stanem co wykres
Strona `Jak działa kalkulator`	`Implemented`	Dokumentacja in-app dla użytkownika
Strona `Roadmapa produktowa`	`Implemented`	Komunikacja kierunku rozwoju
Asystent wejścia do kalkulatora	`Planned`	Przyszły dialogowy kanał wejścia do tego samego formularza i silnika
Logika `IKE / IKZE`	`Out of scope`	UI przygotowane, logika odłożona
Automatyczne dane rynkowe	`Planned`	Referencyjna stopa, warunki emisji
Predykcje inflacji i scenariusze	`Planned`	Etapy roadmapy
Portfel obligacji	`Planned`	Kierunek długoterminowy

4.2 Status rodzin logiki obligacji¶

Rodzina / strategia	Status	Uwagi
`OTS`	`Implemented`	Własna strategia kwartalna
`ROR`, `DOR`	`Implemented`	Wspólna rodzina `monthly-income`
`TOS`, `EDO`, `ROS`, `ROD`	`Implemented`	Wspólna rodzina `annual-accumulation`
`COI`	`Implemented`	Rodzina `annual-payout`

4.3 Co jest aktualnym zakresem MVP+¶

Za aktualny produkt uznajemy:

kompletny kalkulator porównawczy dla wszystkich wspieranych obligacji
poprawną interpretację wyników w UI
wsparcie dokumentacyjne w produkcie
stabilną bazę architektoniczną pod dalszy rozwój

4.4 Mapa handoffu dla głównych obszarów¶

Obszar	Gdzie sprawdzić produktowo	Gdzie sprawdzić technicznie	Co zwykle trzeba zaktualizować przy zmianie
Wybór obligacji	ten dokument, sekcja 13	`selection.ts`, store, komponent wyboru obligacji	UI, tooltipy, eligibility rules
Parametry inwestycji	ten dokument, sekcja 11	store, formularz, engine normalization	UI, help text, validacja
Interpretacja wyników	ten dokument, sekcja 12	docs rodzin strategii, komponenty wyników	UI, tooltipy, docs techniczne
Wykres i podsumowanie	ten dokument, sekcje 8, 12, 16	komponenty wyników, store	UI, metryki, filtry
Tabela roczna	ten dokument, sekcje 8, 12, 20	komponent tabeli, event contract	UI, filtry, komunikaty statusów
Logika obligacji	ten dokument, sekcje 6 i 12	`bond_engine_architecture.md` i docs per-bond	docs techniczne, testy, prompt
Dane i roadmapa	ten dokument, sekcje 14, 18	przyszła warstwa danych	roadmapa, acceptance criteria, docs

5. Mapa źródeł prawdy¶

5.1 Źródło prawdy dla wymagań produktowych¶

ten dokument: product_spec.md

5.1a Źródło prawdy dla roadmapy produktu¶

product_roadmap.md

5.2 Źródło prawdy dla architektury silnika¶

bond_engine_architecture.md

5.2a Źródło prawdy dla kontraktu modelu wyników¶

result_model_contract.md

5.2aa Źródło prawdy dla warstwy modeli interpretacyjnych¶

analysis_models_architecture.md

5.2b Źródło prawdy dla kontraktów danych i persistence¶

data_persistence_contracts.md
jawny kontrakt portfela na poziomie snapshotów:
types.ts: src/app/domain/portfolio/types.ts
jawny kontrakt historii predykcji:
types.ts: src/app/domain/prediction-history/types.ts
runtime repozytorium zapisanych symulacji:
repository.ts: src/app/domain/persistence/repository.ts
runtime serwis zapisanych symulacji:
service.ts: src/app/domain/persistence/service.ts
runtime repozytorium i serwis historii predykcji:
repository.ts: src/app/domain/prediction-history/repository.ts
service.ts: src/app/domain/prediction-history/service.ts

5.3 Źródło prawdy dla rodzin strategii¶

monthly-income:
ROR_logic.md
DOR_logic.md
annual-accumulation:
annual_accumulation_logic.md
TOS_logic.md
EDO_logic.md
ROS_logic.md
ROD_logic.md
annual-payout:
annual_payout_logic.md
COI_logic.md
strategia własna:
ODS_logic.md - historyczna nazwa dokumentu dla strategii OTS

5.4 Źródło prawdy dla stanu UI¶

store aplikacji:
useCalculatorStore.ts: src/app/store/useCalculatorStore.ts
persistence.ts: src/app/store/persistence.ts
types.ts: src/app/store/types.ts
zasada odpowiedzialności:
historia sesji kalkulatora należy do store
trwałe zapisane symulacje należą do warstwy persistence repository/service
kompozycja produktu:
App.tsx: src/app/App.tsx

5.5 Zasada aktualizacji¶

Przy każdej zmianie product behavior należy ocenić, czy trzeba zaktualizować:

tę specyfikację
dokument roadmapy produktu
dokumentację techniczną odpowiedniej rodziny
dokumentację konkretnej obligacji
komunikaty i tooltipy w UI

5.6 Źródło prawdy dla aktualnego stanu produktu¶

Jeśli ten dokument, UI i dokumentacja techniczna wydają się niespójne, należy przyjąć taką kolejność weryfikacji:

ten dokument określa wymaganie produktowe
dokument roadmapy określa kolejność i zakres przyszłych etapów
dokumentacja techniczna określa zamierzoną implementację
kod i testy pokazują bieżący stan rzeczywisty

Jeśli punkt 1 lub 2 nie zgadzają się z punktami 3 i 4, należy potraktować to jako debt do wyjaśnienia, a nie jako domyślne zachowanie produktu.

6. Obowiązujące decyzje projektowe¶

To są decyzje obowiązujące teraz. Nie należy ich zmieniać nieświadomie przy kolejnych iteracjach.

6.1 Wynik końcowy interpretujemy przez ostatni rok¶

użytkownik może analizować przebieg inwestycji w latach pośrednich
kalkulator symuluje rzeczywisty przebieg inwestycji, więc finalną ocenę dla horyzontu X lat należy opierać na ostatnim roku tabeli rocznej i wynikach końcowych
powód: podatki i koszty nie zawsze są realizowane od razu

6.2 Obligacje rodzinne są filtrowane przez eligibility, nie przez engine¶

ROS i ROD są zależne od 800+
reguła wyboru należy do warstwy selekcji, nie do warstwy symulacji
na tym etapie kalkulator świadomie nie kontroluje jeszcze limitu kwotowego zakupu wynikającego z wysokości otrzymanych świadczeń

6.3 Typ rachunku jest na razie wyłączony¶

Rachunek maklerski / IKE / IKZE jest widoczny w produkcie
przełączanie jest wyłączone
nie wpływa na wynik kalkulatora

6.4 Wartość brutto i netto mają stałą semantykę¶

Wartość brutto = wartość portfela przed podatkami i kosztami już zrealizowanymi do danego momentu
Wartość netto = wartość portfela po podatkach i kosztach już zrealizowanych
w ostatnim roku Wartość netto oznacza wynik końcowego rozliczenia
lata pośrednie pokazują przede wszystkim przebieg inwestycji i stan portfela w toku, a nie jeszcze osobny ujednolicony tryb odpowiedzi na pytanie: ile dostanę, jeśli zakończę inwestycję dokładnie w tym roku

6.5 Produkt nie jest jeszcze portfelem inwestycyjnym¶

bieżąca wersja jest kalkulatorem porównawczym
roadmapa i warstwa danych mają przygotować grunt pod portfel, ale portfel nie należy do obecnego zakresu

7. Grupy użytkowników¶

7.1 Użytkownik podstawowy¶

Osoba fizyczna, która:

chce porównać detaliczne obligacje skarbowe
zna podstawowe pojęcia finansowe, ale nie chce liczyć wszystkiego ręcznie
potrzebuje prostego, czytelnego porównania

7.2 Użytkownik zaawansowany¶

Osoba, która:

świadomie porównuje różne scenariusze inflacyjne
zwraca uwagę na podatek, reinwestycję i wykup
chce analizować wyniki rok po roku

7.3 Użytkownik przyszły¶

Osoba, która w przyszłości mogłaby:

prowadzić portfel obligacji
śledzić konkretne emisje
aktualizować stan inwestycji w czasie
porównywać historyczny zakup z aktualnym stanem portfela
uruchamiać kalkulator przez dialog z asystentem zamiast ręcznie uzupełniać cały formularz

8. Ekrany produktu i ich odpowiedzialność¶

8.1 Kalkulator¶

Status: Implemented

Odpowiedzialność:

umożliwić pełne porównanie obligacji bez opuszczania aplikacji
zebrać dane wejściowe użytkownika
pokazać wynik końcowy i przebieg inwestycji

Zawiera:

wybór obligacji
parametry inwestycji
wykres porównawczy
podsumowanie wyników
szczegółową tabelę roczną

8.2 Jak działa kalkulator¶

Status: Implemented

Odpowiedzialność:

wyjaśnić użytkownikowi jak korzystać z aplikacji
zmniejszyć ryzyko błędnej interpretacji metryk

8.3 Roadmapa produktowa¶

Status: Implemented

Odpowiedzialność:

pokazać kierunek rozwoju produktu
osadzić aktualny kalkulator w szerszej wizji

8.4 Asystent wejścia do kalkulatora¶

Status: Planned

Odpowiedzialność:

przeprowadzić użytkownika przez pytania o parametry inwestycji
wypełnić formularz za użytkownika na podstawie odpowiedzi
uruchomić tę samą symulację, z której korzysta tryb ręczny
oddać użytkownikowi gotowy stan formularza i wynik z możliwością dalszej ręcznej korekty

9. Diagramy i materiały wizualne¶

Ta sekcja ma skracać czas wejścia w produkt. Diagramy Mermaid pokazują logikę i granice odpowiedzialności, a placeholdery pod screeny definiują, jakie ujęcia UI warto dodać do dokumentacji.

9.1 Diagram przepływu produktu¶

flowchart LR
    A[Uzytkownik ustawia parametry] --> B[Warstwa selekcji]
    B --> C[Wybor dozwolonych obligacji]
    C --> D[Silnik symulacji]
    D --> E[Wyniki roczne]
    D --> F[Wyniki koncowe]
    E --> G[Wykres i tabela roczna]
    F --> H[Podsumowanie i ranking]
    G --> I[Interpretacja w UI]
    H --> I

Cel diagramu:

pokazać drogę od wejścia użytkownika do wyników
rozdzielić selekcję instrumentów od samej symulacji
ułatwić nowej osobie zrozumienie, gdzie kończy się logika produktu, a zaczyna prezentacja

9.2 Diagram granic odpowiedzialności warstw¶

flowchart TB
    subgraph Selection[Warstwa selekcji]
        S1[Eligibility]
        S2[Sanityzacja wyboru]
        S3[Reguly 800+]
    end

    subgraph Engine[Warstwa silnika]
        E1[Strategie obligacji]
        E2[Podatki i wykup]
        E3[Reinwestycja]
        E4[Wyniki roczne i koncowe]
    end

    subgraph UI[Warstwa UI]
        U1[Formularz]
        U2[Wykres]
        U3[Podsumowanie]
        U4[Tabela roczna]
        U5[Dokumentacja in-app]
    end

    Selection --> Engine
    Engine --> UI

Cel diagramu:

utrwalić granicę selection -> engine -> UI
zmniejszyć ryzyko wrzucania reguł eligibility do silnika
pomóc przy handoffie i review zmian

9.3 Diagram interpretacji wynikow¶

flowchart TD
    A[Uzytkownik patrzy na rok N] --> B{Czy to ostatni rok horyzontu?}
    B -- Tak --> C[Traktuj jako wynik koncowego rozliczenia]
    B -- Nie --> D[Traktuj jako stan inwestycji w toku]
    D --> E[Przydatne do zrozumienia przebiegu]
    D --> F[Nie zawsze rowne pytaniu ile dostane po zamknieciu inwestycji]
    C --> G[To jest glowna podstawa decyzji koncowej]

Cel diagramu:

utrwalić najważniejszą zasadę interpretacji produktu
odróżnić lata pośrednie od ostatniego roku
ograniczyć ryzyko błędnego czytania tabel i wykresu

9.4 Diagram logiki `800+`¶

flowchart TD
    A[Czy uzytkownik zaznaczyl 800+?] --> B{Tak czy nie}
    B -- Tak --> C[ROS i ROD sa dostepne w selekcji]
    B -- Nie --> D[ROS i ROD sa niedostepne]
    C --> E[Silnik liczy je jak inne obligacje rodzinne]
    E --> F[Na obecnym etapie brak kontroli limitu kwotowego swiadczen]

Cel diagramu:

jasno pokazać aktualny stan produktu
podkreślić, że obecny etap świadomie nie implementuje limitu kwotowego 800+
rozdzielić dostępność w UI od logiki symulacji

9.5 Diagram roadmapy i zaleznosci etapow¶

flowchart LR
    P0[Etap 0\nDomkniecie logiki MVP] --> P1[Etap 1\nAutomatyzacja danych]
    P1 --> P2[Etap 2\nBaza danych i zapis symulacji]
    P2 --> P3[Etap 3\nModel inflacyjny]
    P3 --> P4[Etap 4\nScenariusze min/max]
    P3 --> P5[Etap 5\nSymulator zmiennosci]
    P2 --> P6[Etap 6\nRegularne inwestowanie i IKE/IKZE]
    P3 --> P6
    P4 --> P6
    P5 --> P6
    P6 --> P7[Etap 7\nAsystent wejscia]

Cel diagramu:

pokazać kolejność rozwoju produktu
wyjaśnić zależności między danymi, predykcją i przyszłym portfelem, z uwzględnieniem tego, że Etap 4 i Etap 5 są opcjonalnymi rozszerzeniami po Etapie 3
ułatwić PM i developerowi planowanie scope