🌾 AGRO 360 — Instrukcja: user flow SaaS

0. Mapa całości, konwencje, glosariusz Meta

Sekcja zerowa dodana po audycie v1.1. Przeczytaj zanim wjedziesz w detale. Zawiera: jeden diagram pokazujący cały user flow end-to-end, podsumowanie audytu spójności (gdzie są luki do zaadresowania), konwencje czytania dokumentu i słownik terminów branżowych.

0.1 Mapa całego user flow — end-to-end

Pełna podróż klienta od pierwszego kontaktu (reklama) do retencji po latach. Każdy etap odsyła do dedykowanej sekcji. To jest kanoniczna sekwencja — wszystkie pozostałe diagramy w dokumencie są jej fragmentami.

flowchart TD
    subgraph ACQ["🎯 AKWIZYCJA — sekcja 2"]
      A1[Reklama / SEO /
polecenie] --> A2[Landing
agro360.pl]
      A2 --> A3{CTA
'Wypróbuj'?}
    end

    subgraph SIGN["✍️ REJESTRACJA — sekcja 3"]
      A3 -->|Tak| B1[Formularz
email + hasło]
      B1 --> B2[Weryfikacja
email]
      B2 --> B3[Auto-login
+ start trialu 30d]
    end

    subgraph ONB["🚀 ONBOARDING — sekcja 4"]
      B3 --> C1{Pierwsza wizyta?}
      C1 -->|Nowy user, brak
zaproszenia| C2[Wizard 5 kroków:
farma → pole → uprawa
→ zabieg → zaproszenie]
      C1 -->|Zaproszony user| C3[Mini-onboarding:
tutorial roli,
tour gospodarstwa]
      C2 --> C4[💡 AHA MOMENT
koszt/ha widoczny]
      C3 --> D1
      C4 --> D1
    end

    subgraph CORE["📦 CODZIENNE UŻYCIE — sekcja 5, 6, 11"]
      D1[Dashboard +
switcher gospodarstw] --> D2[Loop:
zabiegi · magazyn ·
faktury · koszty · raporty]
      D2 --> D3{Współpraca?}
      D3 -->|Tak| D4[Zaprasza
pracownika /
agronoma]
      D3 -->|Nie| D2
      D4 --> D2
    end

    subgraph CONV["💳 KONWERSJA — sekcja 8"]
      D2 -.->|dzień 23 trialu| E1[Banner '7 dni']
      E1 --> E2[Wpięcie karty]
      E2 -->|dzień 30| E3{Auto-charge
OK?}
      E3 -->|Tak| F1[Klient płacący
Pro 49 zł/mies]
      E3 -->|Nie| E4[Dunning:
1d/3d/5d/7d retry]
      E4 -->|Sukces| F1
      E4 -->|Fail 7d| E5[Read-only
mode]
      E5 -->|Wpięcie nowej karty| F1
      E5 -.->|60d| E6[Konto
zawieszone]
    end

    subgraph RET["🔁 RETENCJA & EKSPANSJA — sekcja 6, 8"]
      F1 --> G1[Codzienne użycie]
      G1 --> G2{Sygnał
at-risk?}
      G2 -->|Nie| G1
      G2 -->|Tak| G3[Health score
alert → success]
      G3 --> G1
      G1 --> G4[Upsell:
roczny plan /
Enterprise]
    end

    subgraph EXIT["🚪 OFFBOARDING — sekcja 9, 11"]
      G1 -.->|user chce wyjść| H1[Anulowanie:
krótka ankieta,
działa do końca okresu]
      H1 --> H2[Dane zachowane
12 mies]
      H2 -.->|Reactivate| F1
      H2 -.->|Eksport + usuń| H3[RODO export
+ hard delete]
    end

    A3 -->|Nie| Z1[Newsletter /
retargeting]
    Z1 -.-> A2

    style A1 fill:#e8f0e0,stroke:#4a7c2c
    style C4 fill:#fff3d6,stroke:#c08a2a
    style F1 fill:#4a7c2c,stroke:#2d5016,color:#fff
    style E5 fill:#fff3d6,stroke:#c08a2a
    style E6 fill:#ffe9e9,stroke:#e88a8a
    style H3 fill:#ffe9e9,stroke:#e88a8a
    

Definicja „aha moment"

Aha moment = pierwszy zabieg wpisany w wizardzie onboardingowym, po którym system pokazuje wyliczony koszt zł/ha i potwierdza odjęcie z magazynu.

Mierzona metryka: time_to_aha = czas od kliknięcia „Załóż konto" do pierwszego workHistory.created z wyliczonym kosztem. Target: < 15 min. Jeśli > 30 min — alert do success, prawdopodobny churn w trialu.

0.2 Audyt spójności — co wymaga decyzji

Wynik przeglądu całego dokumentu pod kątem: spójność user flow, logiczne luki, sprzeczności między sekcjami, braki w obsłudze edge case'ów. Każdy punkt ma 📝 Audit notatkę inline w odpowiedniej sekcji. Wszystkie to decyzje do podjęcia przed implementacją.

0.3 Konwencje dokumentu — jak czytać

0.4 Glosariusz terminów

Skróty branżowe (rolnictwo) i techniczne (SaaS) używane w dokumencie:

0.5 Wymagania niefunkcjonalne (NFR)

Brakowało tego w v1.0 — dodaję zbiorczo dla wszystkich modułów:

1. Persona i kontekst biznesowy Gotowe

Zanim zaprojektujemy jakikolwiek ekran SaaS, musimy mieć jasność: dla kogo to robimy, jaki problem rozwiązujemy i jak na tym zarabiamy. Ta sekcja jest fundamentem — wszystkie kolejne decyzje (cennik, onboarding, role, ficzery) będą się do niej odwoływać.

Status: to są tezy wstępne, nie kontrakt. Wymagają walidacji — najlepiej przez rozmowę z 5-10 realnymi rolnikami z grupy docelowej zanim zaczniemy budować.

1.1 Persona główna — „Rolnik-gospodarz"

1.2 Persona drugorzędna — „Agronom-doradca"

1.3 Persona trzecia (edge) — „Duży gracz"

1.4 Problem do rozwiązania

Dziś typowy rolnik z grupy docelowej radzi sobie z dokumentacją gospodarstwa w sposób fragmentaryczny:

1.5 Value proposition

AGRO 360 to cyfrowy notatnik gospodarstwa, który prowadzi się sam. Wpisujesz raz pracę polową — system odlicza z magazynu, liczy koszt na hektar, dokleja do rejestru ŚOR i przygotowuje raport pod kontrolę. Bez Excela, bez papieru, bez „muszę to jeszcze ogarnąć wieczorem".

Trzy obietnice, które różnicują nas od konkurencji (eDWIN, SatAgro, FarmFacts):

1. Prostota „chłopskiego rozumu" — nie ERP rolniczy, tylko jeden ekran = jedna decyzja. Onboarding w 5 minut.
2. Polskie realia od pierwszego dnia — numery zezwoleń ARiMR, formulacje (WG/SC/EC/SL), zł/ha, dostawcy lokalni. Nie tłumaczenie z niemieckiego.
3. Działa na telefonie w polu — szybki interfejs zoptymalizowany pod jedną rękę i słońce w oczy. Pełne offline-first dochodzi w fazie 2 (Q4 2026) — patrz s.12. Na MVP: online, ale błyskawiczne.

1.6 Model przychodów — teza wstępna

Trzy modele do rozważenia, z plusami i minusami:

Decyzja v2.0: Tier-based z Free trial 30 dni → Pro 49 zł/mies za gospodarstwo (flat) → Agronom Pro 99 zł/mies (osobny plan dla doradców z N klientami) → Enterprise indywidualnie (gospodarstwa > 300 ha lub multi-farm). Trial = pełen Pro z jednym ogranicznikiem: brak generowania pakietu kontrolerskiego PDF (killer feature = upgrade trigger).

1.6.1 Liczby biznesowe — hipotezy do walidacji

Założenia finansowe na podstawie benchmarków SaaS B2B + specyfika rolnictwa (sezonowość, długie cykle decyzyjne):

Co to oznacza: żeby AGRO 360 było opłacalne dla solo foundera (Adam) potrzebujemy 150 płatnych klientów w ~12 mies. Przy CAC 392 zł budżet marketingowy max ~60 000 zł na akwizycję pierwszych 150. To prawdopodobne przez polecenia + content SEO + 1-2 kampanie Facebook z targetowaniem rolniczym.

1.6.2 Status persony Marta (agronom) — decyzja

Marta to klient płacący, NIE darmowy kanał. Osobny plan Agronom Pro (99 zł/mies) z dostępem do N gospodarstw klientów (z ich zgodą per gospodarstwo). Marta nie konsumuje slotów w planach klientów-rolników. Klienci-rolnicy płacą za swoje Pro osobno. To dwa równoległe kanały przychodu.

Mechanika:

• Rolnik (Tomek) ma swój Pro 49 zł/mies. To jego dane.
• Tomek wysyła zaproszenie do Marty (s.6) jako Agronom-gość.
• Marta ma własne konto Agronom Pro 99 zł/mies — bez tego nie może zaakceptować zaproszenia.
• Marta widzi gospodarstwo Tomka w swojej liście klientów (s.6.8 nowa sub-sekcja).
• Marta NIE liczy się do limitu 3 userów Tomka.
• Bonus akwizycyjny: Marta poleciła Tomka → Tomek pierwszy miesiąc 50% taniej, Marta dostaje 30 zł na poczet swojej subskrypcji.

1.7 Ścieżka klienta — od poznania do retencji

flowchart LR
    A[Reklama FB / polecenie
sąsiada / Google] --> B[Landing page
agro360.pl]
    B --> C{Decyzja:
wypróbować?}
    C -->|Tak| D[Rejestracja
email + hasło]
    C -->|Nie| Z[Newsletter /
retargeting]
    D --> E[Onboarding wizard
dodaj 1. pole]
    E --> F[Pierwsza praca polowa
wpisana w 5 min]
    F --> G{Aha moment?
koszt/ha widoczny}
    G -->|Tak| H[Codzienne użycie
tydzień 1-4]
    G -->|Nie| Y[Churn w trialu]
    H --> I[Koniec trialu 30 dni]
    I --> J{Konwersja na
płatny plan?}
    J -->|Tak| K[Klient płacący
49 zł/mies]
    J -->|Nie| Y
    K --> L[Retencja
codzienne użycie]
    L --> M[Upsell:
zaproś agronoma /
dodaj pracownika]

    style A fill:#e8f0e0,stroke:#4a7c2c
    style K fill:#4a7c2c,stroke:#2d5016,color:#fff
    style Y fill:#fff3d6,stroke:#c08a2a
    style G fill:#fff3d6,stroke:#c08a2a
    

1.8 Otwarte pytania do walidacji

• Czy 49 zł/mies to akceptowalna cena dla rolnika 60-150 ha? (Może 99 zł? Może 29 zł?)
• Czy Free tier zachęca, czy kanibalizuje płatność? Może lepiej tylko trial 30 dni bez Free?
• Czy rejestr ŚOR pod kontrolę ARiMR to wystarczająca pojedyncza obietnica, żeby zapłacili? (Hipoteza: tak — to konkretny ból z konkretną karą.)
• Czy persona „Agronom-doradca" to nasz klient, czy kanał dystrybucji? (Może oferować im darmowe konto za każdego sprowadzonego klienta?)
• Czy konkurencja (eDWIN, SatAgro) ma realnych aktywnych użytkowników z naszej grupy, czy tylko nazwiska na liście?

2. Akwizycja: landing page Gotowe

Landing page to jedna strona statyczna (osobny deployment, np. agro360.pl) — nie część aplikacji. Cel: w 10 sekund odpowiedzieć „dla kogo to jest" i przekonwertować na rejestrację. Optymalizowane pod mobile (rolnik na traktorze ze smartfonem).

2.1 Struktura strony — sekcje po kolei

2.2 User flow akwizycji

flowchart TD
    Start([Źródło ruchu]) --> Src{Skąd?}
    Src -->|Reklama FB/Google| LP[Landing
agro360.pl]
    Src -->|Polecenie sąsiada| LP
    Src -->|Branżowy portal| LP
    LP --> Read{Czyta hero?}
    Read -->|Bounce 70%| End1([Wyjście])
    Read -->|Scroll dalej| Features[Sekcje
funkcje/jak działa]
    Features --> Price[Cennik]
    Price --> Decide{Decyzja}
    Decide -->|CTA Wypróbuj| Reg[Rejestracja
sekcja 3]
    Decide -->|Demo| Demo[Wideo 2min]
    Decide -->|FAQ| FAQ[Czyta FAQ]
    Demo --> Reg
    FAQ --> Decide
    Decide -->|Wyjście| Retarget[Pixel FB
retargeting]

    style LP fill:#e8f0e0,stroke:#4a7c2c
    style Reg fill:#4a7c2c,stroke:#2d5016,color:#fff
    style End1 fill:#fff3d6,stroke:#c08a2a
    

2.3 Wymagania techniczne landingu

• Statyczna strona (Astro / Next.js static / nawet plain HTML) — szybkość ładowania < 2s na 4G
• SEO podstawowe: meta tags, schema.org Organization, sitemap
• Analytics: GA4 / Plausible (RODO-friendly) + Hotjar / Microsoft Clarity dla sesji
• Pixel FB + Google Ads conversion tracking (CTA klik + rejestracja)
• Cookie banner zgodny z RODO (Cookiebot / własny)
• Hosting osobny od aplikacji (CDN: Cloudflare Pages / Vercel)

3. Rejestracja i wybór planu Gotowe

Cel rejestracji: najmniejszy możliwy próg wejścia. Im więcej pól w formularzu, tym większy drop-off. Decyzja o planie odkładamy na koniec trialu — user najpierw musi zobaczyć wartość.

3.1 Model rejestracji — decyzja: „trial-first, no card"

Trzy modele rozważane, wybieramy C:

3.2 Ekran rejestracji

3.3 Flow rejestracji

flowchart TD
    Start([CTA na landingu]) --> Form[Formularz
email + hasło + imię]
    Form --> Submit{Submit}
    Submit -->|Email zajęty| Err1[Komunikat:
masz już konto?
link do loginu]
    Submit -->|Walidacja OK| Send[Wyślij email
weryfikacyjny]
    Send --> Wait[Ekran:
sprawdź skrzynkę]
    Wait --> Click{User klika link?}
    Click -->|Tak, w 24h| Verify[Konto
aktywne]
    Click -->|Nie w 24h| Remind[Email przypominający
po 24h]
    Remind --> Click
    Click -->|Nigdy w 7 dni| Cleanup[Konto usuwane
email się zwalnia]
    Verify --> Login[Auto-login
+ start trialu 30 dni]
    Login --> Onboard[Onboarding wizard
sekcja 4]

    style Form fill:#e8f0e0,stroke:#4a7c2c
    style Onboard fill:#4a7c2c,stroke:#2d5016,color:#fff
    style Err1 fill:#ffe9e9,stroke:#e88a8a
    

3.4 Ekran weryfikacji email

3.5 Plany cenowe — finalna forma (v2.0)

Logika ogranicznika trialu (audit #4 RESOLVED): Trial daje pełnię użycia (smak prawdziwego produktu), ale brak pakietu kontrolerskiego PDF. To jedyny ograniczenie i jednocześnie killer feature — w momencie gdy Tomkowi „za 3 dni kontrola ARiMR", upgrade jest naturalny i emocjonalnie uzasadniony.

3.6 Flow wpięcia karty — 3 momenty (decyzja v2.0, audit #5 RESOLVED)

Trial bez karty (3.1) wymaga jasnego flow KIEDY karta się pojawia. Decyzja: trzy okazje:

flowchart TD
    Trial1[Trial dzień 1-22] --> Day23{Dzień 23}
    Day23 --> Banner1[🟡 Banner non-blocking:
'Zostało 7 dni - wpij metodę
płatności żeby przejść płynnie.
Nic nie pobierzemy do dnia 30.']
    Banner1 --> Choice1{User klika?}
    Choice1 -->|Tak, wpina| Stored1[💳 Karta zapisana,
banner znika,
dzień 30 auto-charge]
    Choice1 -->|Ignoruje| Day28[Dzień 28]
    Day28 --> Banner2[🟠 Banner mocniejszy:
'2 dni do końca trialu.
Bez karty stracisz możliwość
wpisywania.']
    Banner2 --> Day30{Dzień 30}
    Day30 -->|Karta wpięta| Charge[Auto-charge 49 zł]
    Day30 -->|Karta nie wpięta| ReadOnly[🔴 Read-only mode
+ ekran konwersji 3.6.1]
    ReadOnly --> Settings[Opcja 3: link
'Ustawienia → Subskrypcja'
dostępny zawsze]
    Settings --> Choice1
    Stored1 --> Day30

    style Stored1 fill:#e8f0e0,stroke:#4a7c2c
    style ReadOnly fill:#fff3d6,stroke:#c08a2a
    style Charge fill:#4a7c2c,stroke:#2d5016,color:#fff
    

Trzy okazje, trzy poziomy presji:

1. Dzień 23 (proaktywne) — łagodny banner, „uniknij przerwy". Nie blokuje pracy.
2. Dzień 28-30 (eskalacja) — banner kontrastowy, email + push.
3. Zawsze (samoobsługa) — link Ustawienia → Subskrypcja → Wpij kartę. Dla userów którzy chcą od pierwszego dnia.

Karta pobierana przez Stripe Customer Portal (hosted) — minimum integracji, max bezpieczeństwa. Wspierane metody: BLIK, karta, Apple/Google Pay (przez Stripe + Przelewy24).

3.6.1 Konwersja na płatny — ekran po trialu (dzień 30 bez karty)

Na dzień 30 bez wpiętej karty: read-only mode (user widzi dane, ale nie może dodawać) + ekran „Przedłuż żeby pisać".

3.7 Login (dla wracających)

4. Onboarding: pierwsze gospodarstwo Gotowe

To najważniejszy ekran całego SaaS. Tu się decyduje czy user zostanie. Cel: w <10 min user widzi pierwszą wartość („aha moment") — koszt na hektar swojego pola po wpisaniu jednego zabiegu.

4.1 Filozofia onboardingu

• Skip-able zawsze — każdy krok ma „pomiń, dodam później". User w stresie nie utknie.
• Progres widoczny — pasek „2 z 5", motywuje dokończenie.
• Wartość przed wysiłkiem — najpierw pokazujemy benefit, potem prosimy o dane.
• Seed data realistyczny — gotowe szablony (4 uprawy, 6 ŚOR z bazy sorDatabase, 4 dostawców nawozów). User nie patrzy na pustkę.

4.2 Flow wizarda — 5 kroków

flowchart LR
    Login([Po loginie]) --> S1[Krok 1
Nazwa gospodarstwa
+ lokalizacja]
    S1 --> S2[Krok 2
Dodaj 1. pole]
    S2 --> S3[Krok 3
Przypisz uprawę]
    S3 --> S4[Krok 4
Wpisz 1. zabieg
opcjonalne]
    S4 --> S5[Krok 5
Zaproś osobę
opcjonalne]
    S5 --> Done[Dashboard
z banerem 'aha']

    S1 -.skip.-> S2
    S2 -.skip.-> S3
    S3 -.skip.-> Done
    S4 -.skip.-> S5

    style Done fill:#4a7c2c,stroke:#2d5016,color:#fff
    style S2 fill:#e8f0e0,stroke:#4a7c2c
    style S4 fill:#fff3d6,stroke:#c08a2a
    

4.3 Krok 1 — Nazwa gospodarstwa + lokalizacja

4.4 Krok 2 — Dodaj pierwsze pole

4.5 Krok 3 — Przypisz uprawę

4.6 Krok 4 — Pierwszy zabieg (opcjonalny)

4.7 Krok 5 — Zaproś osobę (opcjonalny)

4.8 Lądowanie — pierwszy dashboard

4.9 Onboarding checklisty (post-wizard)

Po wizardzie checklisty się utrzymują w widgetcie na dashboardzie (collapsable), znikają gdy user wykona zadanie. Zniknięcie wszystkich = end-of-onboarding event w analytics.

4.10 Wariant B onboardingu — zaproszony user (decyzja v2.0, audit #6 RESOLVED)

Sekcje 4.2-4.9 opisują onboarding foundera (zakłada własną farmę). Drugi scenariusz: user dostał zaproszenie (s.6.3) — np. Tomek zaprosił Marka jako pracownika lub Marta zaprosiła swojego klienta. Nie pokazujemy wizarda farmy (nie ma własnej), zamiast tego dedykowany mini-onboarding 3 ekrany.

flowchart LR
    Email([Klik w zaproszeniu]) --> Reg[Skrócona rejestracja:
imię + hasło
email pre-filled]
    Reg --> S1[Krok 1
Powitanie spersonalizowane:
'Tomek zaprosił Cię do
Gospodarstwa Kowalskich
jako Pracownika']
    S1 --> S2[Krok 2
Mini-tour roli:
'Jako Pracownik możesz:
✅ Wpisywać zabiegi
✅ Sprawdzać magazyn
❌ Nie zobaczysz Faktur']
    S2 --> S3[Krok 3
Quick win:
'Spróbuj wpisać
zabieg testowy.
Tomek zobaczy notyfikację.']
    S3 --> Dash[Dashboard
workerDashboard]

    style S2 fill:#e8f0e0,stroke:#4a7c2c
    style Dash fill:#4a7c2c,stroke:#2d5016,color:#fff
    

Po Wariancie B: user trafia do swojego workerDashboard (lub odpowiedniego dla roli — agronomDashboard / accountantDashboard). Onboarding checklisty z 4.9 też się pojawiają, ale w skróconej wersji (np. tylko „Zaktualizuj swój profil" + „Wpisz pierwszy realny zabieg").

Edge case: user zaakceptował zaproszenie do gospodarstwa Tomka, ale chce też założyć własne. Z dashboardu → switcher gospodarstw (s.6.4) → [+ Załóż własne gospodarstwo] → przechodzi do Wariantu A (wizard foundera 4.2-4.9).

4.11 Post-onboarding journey — sekwencja 30 dni trialu (decyzja v2.0, audit #7 RESOLVED)

Wizard kończy „aha momentem". Dalej zaczyna się zaprojektowana sekwencja retencji — 7 zaplanowanych touchpoints w 30 dni trialu, każdy z konkretnym celem: edukacja → użycie → konwersja.

Metryki sukcesu sekwencji:

• D+7 retention = % userów którzy dodali ≥ 1 zabieg po wizardzie (target > 60%)
• D+14 active users = % aktywnych przynajmniej raz w 2. tygodniu (target > 50%)
• Conversion D+30 → paid (target > 25%)
• D+33 win-back rate (target ~5% — bonus na top conversion)

Wszystkie touchpoints konfigurowalne w admin panelu (s.10) jako szablony email/push z możliwością A/B testów.

5. Core usage — katalog modułów MVP (greenfield) Gotowe v2.0

Po decyzji Adama: budujemy od nowa. Prototyp Przemka (agro360-mvp2.html, ~9700 linii vanilla JS) jest biblioteką wiedzy domenowej — dowodzi że logika biznesowa rolnicza (mieszaniny ŚOR, koszty zł/ha, magazyn auto-odliczanie, kalkulatory MTZ) jest przemyślana i działa. SaaS buduje się od zera w nowoczesnym stacku (s.12), z prototypu kopiujemy logikę i decyzje branżowe, nie kod.

5.1 Katalog modułów MVP — referencja domenowa → backlog do zbudowania

5.2 Typowe ścieżki użytkownika w SaaS

flowchart TD
    Login([Login]) --> Dash[ownerDashboard]
    Dash --> P1{Co chcę zrobić?}

    P1 -->|Wpisać zabieg| FW[fieldWorkPanel]
    FW --> Type[Wybór typu:
uprawa/siew/nawóz/
ochrona/żniwa]
    Type --> Form[renderWorkForm]
    Form --> Save[saveFieldWork]
    Save --> Wh[Odejmij z magazynu
+ koszty]
    Wh --> Dash

    P1 -->|Sprawdzić magazyn| Mag[warehousePanel]
    Mag --> Sub[Sub-screen:
zboże/ŚOR/nasiona]
    Sub --> Dash

    P1 -->|Dodać fakturę| Inv[invoicesPanel]
    Inv --> InvSave[saveInvoice]
    InvSave --> CostUpd[Update costsRegister]
    CostUpd --> Dash

    P1 -->|Wygenerować raport ARiMR| Rep[reportsPanel]
    Rep --> PDF[Server PDF]
    PDF --> Download[Pobierz]

    P1 -->|Sprawdzić koszty| Costs[costsPanel]
    Costs --> Filter[Filtr: uprawa/pole/data]
    Filter --> Dash

    style Dash fill:#4a7c2c,stroke:#2d5016,color:#fff
    style Save fill:#e8f0e0,stroke:#4a7c2c
    style PDF fill:#fff3d6,stroke:#c08a2a
    

5.3 Najczęstszy flow — wpisanie zabiegu ochrony roślin

To 60% wartości produktu. Krok po kroku jak działa w apce dziś — i co zmieni SaaS:

5.4 Co kopiujemy 1:1 z prototypu (logika domenowa, nie kod)

Przemek już to przemyślał i działa — w nowym buildzie zachowujemy identyczne reguły biznesowe, ale piszemy w React + TypeScript:

• Kalkulacja kosztów — zł/ha, suma na zabieg, podsumowanie per uprawa/pole/sezon
• Kolejność aplikacji ŚOR wg formulacji — WG → SC → EC → SL (kluczowa decyzja agronomiczna z prototypu, l. 8724)
• Auto-odejmowanie z magazynu przy zabiegu z atomowym UPDATE WHERE qty >= X (s.11.3)
• Reguły alertów magazynowych — domyślny próg 20% poniżej alertThreshold
• Wzory kalkulatorów — MTZ (masa tysiąca ziaren), gęstość siewu, kalkulator inwestycji w nawozy (l. 7477, 7591, 7660)
• Walidacje branżowe — format numerów zezwoleń ŚOR R-XXXX/RRRR, jednostki (ha/kg/t/l), zakres dawek
• Bazowy katalog ŚOR — 12 preparatów z l. 7338 jako seed do rozszerzenia do 100+
• Layout formularza zabiegu — kolejność pól (data → pola → uprawa → mieszanina → notatki) — Przemek to przetestował z perspektywy rolnika

5.5 Co przeprojektujemy (UX/UI od nowa)

Prototyp ma znaną logikę, ale wygląd i interakcje wymagają unowocześnienia:

• Nawigacja — z fixed overlay paneli (display:none toggle) → routing (React Router) z deep linkami URL
• Dashboard owner — z hardcoded widgetów pogody i MATIF → konfigurowalne karty + realne integracje (faza 2)
• Mobile-first — prototyp jest desktop-first; SaaS na odwrót (persona Tomek na smartfonie w polu)
• Empty states — w prototypie brak; w SaaS przyjazne ilustracje + CTA dla każdego pustego ekranu
• Loading / error states — wszystkie operacje async, skeleton loaders zamiast spinnerów
• Forms — z plain HTML inputs → React Hook Form + Zod walidacja + inline error messages
• Dwa dashboardy (owner/worker) — zachowujemy ideę, ale dochodzi 3 (agronom — sekcja 6.8) i 4 (księgowa — minimalny)
• „Szybki zabieg" jako big action button na dashboardzie — 3 pola (data/pole/typ) i reszta dzieje się sama (pomysł z prototypu poszerzony)

5.6 Co całkiem nowe (nie istnieje w prototypie)

Wszystko związane z SaaS jako modelem biznesowym:

• Auth & sesje — login, rejestracja, reset hasła, magic link, OAuth Google (s.3)
• Multi-tenancy — `currentFarmId` context, RLS PostgreSQL, izolacja danych (s.7)
• Membership model — user ↔ farm ↔ role, zaproszenia (s.6)
• Switcher gospodarstw w top barze (s.6.4)
• Dashboard agronoma — lista klientów, kolejka rekomendacji (s.6.8)
• Onboarding wizard A i B (s.4 i s.4.10)
• Post-onboarding journey — sekwencja emailowa 30 dni (s.4.11)
• Subscription & billing — Stripe checkout, dunning, faktury VAT (s.8)
• Trial banner w headerze, ekran konwersji (s.3.6)
• Backend API — REST/RPC nad Supabase, z autoryzacją JWT, RLS
• Realtime sync — gdy dwóch userów w tym samym gospodarstwie online (Supabase Realtime)
• Audit log — kto co kiedy zmienił, dla compliance i debug (s.6.7)
• Admin panel — wewnętrzne narzędzie (s.10)
• Email transakcyjny — Resend z templates (welcome, weryfikacja, dunning, retencja)
• Storage plików — skany faktur w Supabase Storage
• Server-side PDF — Puppeteer w funkcji serverless dla pakietu kontrolerskiego (faza 2 podstawowo, w MVP klient-side html2pdf)

5.7 Bugi w prototypie do nie-powtórzenia w SaaS

Trzeba świadomie nie kopiować:

• In-memory state bez persystencji — w prototypie fieldWorkHistory, invoicesRegister, costsRegister żyją tylko w pamięci JS (l. 7864, 4963, 3480) i znikają po reload. W SaaS: zawsze backend persist + optimistic UI.
• Niespójność seed data — grainWarehouse ma fieldId 1-3, ale farmFields pusty. W SaaS: walidacja referential integrity przez foreign keys + seeds spójne.
• Kolizja nazw — paymentsPanel = wydatki rolnika (NIE billing SaaS). W SaaS używamy farmExpenses dla rolnika, subscription dla billingu SaaS.
• Brak error handlingu — wszystkie operacje były synchroniczne (localStorage). W SaaS: każde wywołanie API z try/catch + retry + user-facing error.
• Hardcoded mocki bez disclaimer — pogoda 12°C, MATIF, ceny nawozów wyglądały jak prawdziwe, choć były wymyślone. W SaaS: jeśli mock, oznaczamy „Dane demonstracyjne" lub używamy real API od MVP.

6. Współpraca i role Gotowe

Apka dziś ma proste rozróżnienie owner / worker (zmienna currentRole, l. 3464). To za mało dla SaaS. Persona „Marta-agronom" obsługuje wiele gospodarstw — potrzebujemy modelu user należy do wielu gospodarstw przez różne role.

6.1 Cztery role w gospodarstwie

6.2 Model danych — User ↔ Membership ↔ Farm

erDiagram
    User ||--o{ Membership : "ma"
    Farm ||--o{ Membership : "ma"
    Membership }o--|| Role : "jest"

    User {
        uuid id PK
        string email UK
        string name
        string phone
        timestamp createdAt
    }
    Farm {
        uuid id PK
        string name
        string region
        timestamp createdAt
        string subscriptionStatus
    }
    Membership {
        uuid id PK
        uuid userId FK
        uuid farmId FK
        enum role
        timestamp joinedAt
        timestamp invitedAt
        string status
    }
    Role {
        enum value
    }
    

Kluczowe: User i Farm to relacja many-to-many przez Membership. Jeden user może być właścicielem jednego gospodarstwa i agronomem w 5 innych. Jedno gospodarstwo ma wielu users.

6.3 Flow zaproszenia użytkownika

flowchart TD
    Owner([Właściciel]) --> Settings[Ustawienia →
Użytkownicy]
    Settings --> Add[+ Zaproś osobę]
    Add --> Form[Email + rola]
    Form --> Send[Wyślij
zaproszenie]
    Send --> Email[Email z linkiem
i 7-dniowym tokenem]
    Email --> Click{Klika link}
    Click -->|Ma już konto| LinkAccount[Doklej Membership
do istniejącego konta]
    Click -->|Nie ma konta| Register[Skrócona rejestracja
od razu z Membership]
    Click -->|Nie klika 7 dni| Expire[Token wygasa
email przypominający]
    LinkAccount --> Notify[Notyfikacja:
nowe gospodarstwo]
    Register --> Notify
    Notify --> InApp[User loguje się
widzi switcher gospodarstw]

    style Owner fill:#e8f0e0,stroke:#4a7c2c
    style InApp fill:#4a7c2c,stroke:#2d5016,color:#fff
    

6.4 Switcher gospodarstw — kluczowy UI element

6.5 Ekran zarządzania użytkownikami

6.5.1 Limity userów w planach — finalna logika (decyzja v2.0, audit #9 RESOLVED)

Plan Pro ma limit „3 userów" — ale 4 role oraz pomysł 5. (księgowa). Decyzja: licznik dzielony na 3 kategorie:

Przykład realny dla Tomka (Pro 49 zł/mies): Tomek (właściciel) + Anna (współwłaścicielka) + Marek (pracownik) = 3 operatorzy = limit OK. Plus Marta (agronom) gratis, plus pani Kowalska (księgowa) gratis. Razem 5 osób w gospodarstwie za 49 zł.

6.5.2 Flow przy przekroczeniu limitu (decyzja v2.0, audit #10 RESOLVED)

Co się dzieje gdy właściciel chce zaprosić 4. operatora (limit 3 wykorzystany)? Soft block w UI + jasne opcje:

flowchart TD
    Click[+ Zaproś osobę] --> Form[Email + rola: Pracownik]
    Form --> Submit{Submit}
    Submit --> Check{Limit operatorów
w planie OK?}
    Check -->|Tak| Send[Wyślij zaproszenie]
    Check -->|Nie — 3/3| Block[⚠️ Modal:
'Wykorzystałeś limit 3
operatorów planu Pro']
    Block --> Opts{User wybiera}
    Opts -->|Upgrade do Enterprise| Up[Stripe checkout
upgrade]
    Opts -->|Usuń istniejącego| Remove[Lista 3 obecnych
z opcją usunięcia]
    Opts -->|Anuluj| Cancel[Zamknij modal]
    Remove --> RemoveUser[Backend usuwa
membership]
    RemoveUser --> Send
    Up --> Active[Subscription upgraded]
    Active --> Send

    style Block fill:#fff3d6,stroke:#c08a2a
    style Send fill:#e8f0e0,stroke:#4a7c2c
    

Backend: POST /api/farms/:id/invitations z body {email, role} sprawdza limit per role-category. Zwraca 402 Payment Required + payload {current, limit, upgrade_url} jeśli przekroczono. Frontend renderuje modal z 3 opcjami.

Analogicznie dla limitu „1 gospodarstwo" przy próbie utworzenia 2-giego w planie Pro — modal „Drugie gospodarstwo wymaga Enterprise. [Skontaktuj się z nami] [Anuluj]".

6.6 Matrix uprawnień — co która rola widzi w UI

6.7 Audit log — kto co kiedy zmienił

Dla wszystkich zmian zapisujemy: {userId, action, resource, before, after, timestamp}. Dostępne w panelu „Ustawienia → Historia zmian" (właściciel + współwłaściciel). Kluczowe gdy ktoś zarzuca „kto skasował tę fakturę".

6.8 Dashboard agronoma — multi-farm widok (decyzja v2.0, audit #11 RESOLVED)

Persona Marta obsługuje 10-30 gospodarstw klientów. Sam switcher gospodarstw (s.6.4) to za mało — Marta potrzebuje jednego widoku z którego widzi co dzieje się u wszystkich klientów. To dedykowany dashboard po loginie dla usera z planem „Agronom Pro".

6.8.1 Kolejka rekomendacji (Inbox)

Centralna funkcja agronoma — wszystko co wymaga jego reakcji w jednym miejscu:

6.8.2 Cross-farm raporty (Agronom Pro feature)

• Timeline aktywności — wszystkie zabiegi 12 klientów w jednym widoku, filtrowanie po uprawie / dacie / typie
• Porównanie — „klienci uprawiający rzepak: średnia dawka N, max, min, mediana" — szybko widać outliery
• Wykorzystanie ŚOR — które preparaty najczęściej u klientów (przydaje się przy negocjacji rabatu z dostawcą hurtowym)
• Masowy eksport pakietów kontrolerskich — jednym kliknięciem PDF dla wszystkich 12 klientów (każdy klient dostaje swój zindywidualizowany)
• Anonimizowane benchmarki — „Twoi klienci mają średnie koszty pszenicy 2 340 zł/ha vs. branża 2 580 zł/ha" — dowód wartości Marty

Privacy: Marta widzi dane konkretnego klienta TYLKO za zgodą (s.6.7). Klient może w każdej chwili odebrać dostęp. Cross-farm raporty są zawsze pseudonimizowane gdy wyświetlane (np. „Klient #3" zamiast nazwy), z opcją odsłonięcia tylko przez Martę (audit log).

7. Multi-tenancy: model danych Gotowe

Fundament SaaS. Dziś apka ma jedno gospodarstwo per device w localStorage. Docelowo: N gospodarstw w jednej bazie, z twardą izolacją między nimi. Tej sekcji nie da się odpuścić — wszystkie pozostałe są od niej zależne.

7.1 Strategia izolacji — wybieramy „shared DB, tenant_id column"

Wybieramy shared DB + tenant_id z Row Level Security w PostgreSQL — standard branżowy dla SaaS naszej skali.

7.2 Schemat bazy — kluczowe tabele

erDiagram
    User ||--o{ Membership : ma
    Farm ||--o{ Membership : ma
    Farm ||--o{ Field : ma
    Farm ||--o{ WorkHistory : ma
    Farm ||--o{ ChemWarehouse : ma
    Farm ||--o{ SeedWarehouse : ma
    Farm ||--o{ GrainWarehouse : ma
    Farm ||--o{ Invoice : ma
    Farm ||--o{ Cost : ma
    Farm ||--o{ Subscription : ma
    Field ||--o{ WorkHistory : "dotyczy"
    User ||--o{ WorkHistory : "wpisał"
    WorkHistory }o--|| MixtureItem : "ma"
    Subscription ||--o{ Invoice_SaaS : "generuje"

    Farm {
        uuid id PK
        string name
        string region
        timestamp createdAt
        uuid ownerId FK
    }
    Field {
        uuid id PK
        uuid farmId FK
        string name
        decimal areaHa
        string crop
        json gpsPolygon
        json parcelNumbers
    }
    WorkHistory {
        uuid id PK
        uuid farmId FK
        uuid fieldId FK
        uuid createdByUserId FK
        enum type
        date workDate
        decimal cost
        json metadata
    }
    ChemWarehouse {
        uuid id PK
        uuid farmId FK
        string name
        enum category
        string registrationNo
        decimal qty
        decimal price
    }
    Subscription {
        uuid id PK
        uuid farmId FK
        enum plan
        timestamp trialEndsAt
        timestamp currentPeriodEnd
        string stripeId
    }
    

7.3 Row Level Security (RLS) — przykład polityki

Każde zapytanie SQL automatycznie filtruje po farm_id aktywnego użytkownika. Backend nigdy nie polega tylko na WHERE w aplikacji — RLS jest siatką bezpieczeństwa.

-- Policy na tabeli fields: user widzi tylko pola gospodarstw w których ma membership
CREATE POLICY field_isolation ON fields
  FOR ALL
  USING (
    farm_id IN (
      SELECT farm_id FROM memberships
      WHERE user_id = current_setting('app.current_user_id')::uuid
    )
  );

ALTER TABLE fields ENABLE ROW LEVEL SECURITY;

Backend ustawia SET app.current_user_id = '...' na początku każdego requestu (z JWT). Reszta dzieje się sama.

7.4 Mapping localStorage → tabele bazy

7.5 Co jest globalne (cross-tenant) — read-only katalogi

Część danych nie należy do żadnego konkretnego gospodarstwa, tylko do całego SaaS:

• sor_catalog — baza preparatów ŚOR (dziś sorDatabase, 12 wpisów hardcoded → docelowo 100+ aktualizowane co kwartał z rejestru gov.pl)
• fertilizer_catalog — typy nawozów (saletra, mocznik, polifoska, ...) z domyślnymi parametrami NPK
• crop_catalog — lista upraw (pszenica, rzepak, ...)
• regions_catalog — województwa, gminy
• suppliers — dostawcy nawozów (dziś 4 hardcoded → docelowo crowdsource z miastami i cenami)

Każdy z tych katalogów może mieć overrides per farm: gospodarstwo może dodać własny ŚOR (regionalny, nieobjęty katalogiem) lub własnego dostawcę nawozów.

7.6 Wybór backendu — decyzja techniczna

Rekomendacja wstępna: Supabase na MVP. PostgreSQL pod spodem (znamy go, RLS gotowy), auth wbudowany, realtime, storage na pliki (skany faktur). Możliwość self-host później bez przepisywania. Hosting w EU (Frankfurt) zgodny z RODO.

7.6.1 Subskrypcja per Farm + Trial per User account (decyzja v2.0, audit #12 RESOLVED)

Po analizie 3 opcji w pierwotnym audicie — wybieramy opcję A z poprawką:

• Subscription jest własnością Farm (zgodne z ERD, Subscription.farm_id)
• Trial 30 dni przysługuje USER account przy pierwszej rejestracji i jest powiązany z pierwszą Farm którą zakłada (lub do której zostaje zaproszony jako założyciel)
• Drugie gospodarstwo założone przez tego samego usera = własna subskrypcja, BEZ nowego trialu (anty-abuse: jeden trial per email)
• Owner gospodarstwa jest Stripe Customer dla tego gospodarstwa — to on płaci, jego karta, jego faktura. Współwłaściciele nie dostają billingu.
• Transfer własności (s.9.8) — przy przekazaniu własności gospodarstwa, transfer obejmuje też Stripe Customer (nowy właściciel wpina nową kartę w 7 dni, inaczej stary właściciel nadal płaci do końca okresu)
• Agronom Pro — osobna subskrypcja na koncie agronoma (Marta), niezwiązana z żadną Farm klienta. Agronom płaci sam za swoje konto.

Konsekwencje dla UI:

• User-założyciel z 2 gospodarstwami widzi ekran „Subskrypcje" jako listę (2 pozycje, każda z własnym statusem, planem, fakturami)
• Próba założenia 2-giego gospodarstwa w Pro → modal „Drugie gospodarstwo wymaga osobnej subskrypcji Pro 49 zł/mies lub planu Enterprise. Kontynuować?"
• Faktura wystawiana na dane gospodarstwa (NIP gospodarstwa jeśli ustawiony, inaczej dane usera-właściciela)

7.6.2 Multi-farm billing — szczegóły (decyzja v2.0, audit #13 RESOLVED)

7.7 Migracja danych existing user → SaaS

Co z userami którzy używają lokalnej apki dziś i ich danymi w localStorage?

1. Apka lokalna nadal działa offline (nie blokujemy)
2. Dodajemy w niej przycisk „Przejdź na SaaS — przenieś dane"
3. Wykorzystujemy istniejące exportAppData() (l. 6449) — generuje JSON z całością
4. Rejestracja na SaaS → krok 2.5 w wizardzie: „Masz dane z apki lokalnej? Wgraj plik backup"
5. Import dzieli na tabele (fields, warehouse, history, ...), przypisuje farm_id nowo utworzonego gospodarstwa

8. Billing i subskrypcja Gotowe

Cel: jak najmniej tarcia przy pierwszej płatności i jak najmniej wsparcia. Dla persony Tomek (42, smartfon) — musi działać z BLIKa, w 3 klikach, na telefonie.

8.1 Wybór dostawcy płatności

Rekomendacja: Stripe + Przelewy24 jako payment method w Stripe. Stripe ma natywne wsparcie P24 i BLIK (przez P24) od 2024. Dostajemy najlepszy z dwóch światów: solidną logikę subskrypcji + PL metody płatności. Drugi wybór: Tpay solo, jeśli okaże się że Stripe-P24 ma jakieś niespodzianki w PL.

8.2 Plany — finalna struktura (z sekcji 3, tu z perspektywy backendu)

8.3 Flow konwersji trial → płatny

flowchart TD
    Trial[Trial dzień 1-23] -->|7 dni przed końcem| Email1[Email + banner:
'Zostało 7 dni']
    Email1 --> Trial24[Trial dzień 24-29]
    Trial24 -->|2 dni przed końcem| Email2[Email + banner:
'Zostało 2 dni - wybierz plan']
    Email2 --> Day30{Dzień 30:
karta wpięta?}
    Day30 -->|Tak, auto-charge| Charge[Stripe pobiera 49 zł]
    Day30 -->|Nie| ReadOnly[Read-only mode:
można czytać, nie pisać]
    Charge -->|OK| Active[Subscription active]
    Charge -->|Fail| RetryFlow[Retry: 1d, 3d, 5d, 7d
email + banner]
    RetryFlow -->|Sukces| Active
    RetryFlow -->|7 dni fail| ReadOnly
    ReadOnly --> Choice{User decyduje}
    Choice -->|Wybiera plan| Checkout[Checkout Stripe]
    Choice -->|Eksport + wyjście| Export[exportAppData JSON]
    Checkout --> Active
    Choice -->|Nic przez 60 dni| Suspend[Konto zawieszone
dane zachowane 12 mies]

    style Active fill:#4a7c2c,stroke:#2d5016,color:#fff
    style ReadOnly fill:#fff3d6,stroke:#c08a2a
    style Suspend fill:#ffe9e9,stroke:#e88a8a
    

8.4 Ekran „Subskrypcja" w aplikacji

8.5 Anulowanie subskrypcji

Anulowanie zawsze proste (nie ukrywać, nie utrudniać — RODO + dobre obyczaje). Flow:

flowchart LR
    Click[Klik 'Anuluj'] --> Reason[Krótki form:
dlaczego? opcjonalne]
    Reason --> Confirm{Potwierdź}
    Confirm -->|Tak| Cancel[Subskrypcja kończy się
na koniec okresu rozliczeniowego]
    Cancel --> Until[Do końca okresu:
pełna funkcjonalność]
    Until --> Expire[Po końcu okresu:
read-only mode]
    Expire --> Retain[Dane zachowane 12 mies
możliwy reactivate]

    style Cancel fill:#fff3d6,stroke:#c08a2a
    style Retain fill:#e8f0e0,stroke:#4a7c2c
    

8.6 Faktury VAT

Stripe generuje faktury VAT automatycznie, ale dla polskich firm trzeba dodać:

• NIP w danych konta (opcjonalne dla osób fizycznych, wymagane dla firm odliczających VAT)
• VAT 23% wyświetlany osobno na fakturze
• Numeracja zgodna z PL (np. FV/2026/05/0001) — Stripe Invoice Numbering: prefix per region
• Dane sprzedawcy: nasza firma (kto wystawia AGRO 360)
• Faktura PDF mailem po każdej płatności + dostępna w portalu

8.7 Webhooki Stripe — obsługiwane eventy

8.8 Co istnieje w apce a koliduje z billingiem SaaS

8.9 Enforcement limitów planu

Backend egzekwuje limity per request. Frontend pokazuje przyjazne komunikaty.

9. Ustawienia konta Gotowe

Kluczowe rozróżnienie: ustawienia konta (usera) vs ustawienia gospodarstwa (farmy). Dziś w apce wszystko jest pomieszane w settingsPanel + agro360_settings. W SaaS rozdzielamy — bo jeden user może być w wielu gospodarstwach, a jego profil jest jeden.

9.1 Struktura ustawień — dwa drzewa

9.2 Moje konto — profil użytkownika

9.3 Bezpieczeństwo

9.4 Powiadomienia

Każda kategoria z togglem on/off per kanał. SMS tylko gdy zweryfikowany numer + odpowiedni plan (Enterprise lub plan z dodatkiem SMS — alternatywnie limit np. 10 SMS/mies w Pro).

9.5 Moje dane (RODO Article 15 + 20)

RODO daje userowi prawo: (a) wiedzieć jakie dane mamy, (b) otrzymać je w formacie maszynowym, (c) żądać usunięcia.

9.6 Usunięcie konta — flow „double opt-out" (decyzja v2.0, audit #14 RESOLVED)

Z poprawką: żaden user nie może zostać uwięziony w SaaS. Jeśli jest jedynym właścicielem, dajemy mu wybór per gospodarstwo (przekaż / opuść / usuń).

flowchart TD
    Click[Klik 'Usuń konto'] --> Warn[Ekran:
co się stanie?
lista skutków + Twoje gospodarstwa]
    Warn --> HasMember{Mam jakieś
memberships?}
    HasMember -->|Nie| Confirm
    HasMember -->|Tak| Resolve[Ekran 'Najpierw załatwmy gospodarstwa':
lista wszystkich memberships
z opcją per gospodarstwo]
    Resolve --> Per{Per gospodarstwo}
    Per -->|Jestem jedynym właścicielem| Choice1[Wybierz:
• Przekaż współwłaścicielowi
• Usuń gospodarstwo wraz z kontem
• Zaproś nowego właściciela i odczekaj]
    Per -->|Jestem współwłaścicielem| Choice2[Wybierz:
• Tylko opuść
• Wymuś usunięcie gospodarstwa
  jeśli jestem ostatnim aktywnym]
    Per -->|Jestem pracownikiem/agronomem/księgową| Choice3[Auto: opuszczam membership]
    Choice1 --> AllDone
    Choice2 --> AllDone
    Choice3 --> AllDone
    AllDone{Wszystkie
załatwione?}
    AllDone -->|Nie| Resolve
    AllDone -->|Tak| Confirm[Wpisz email + 'USUWAM'
żeby potwierdzić]
    Confirm --> Email[Email z linkiem
'Potwierdź usunięcie']
    Email --> Click2[Klik w emailu w 24h]
    Click2 --> Soft[Soft-delete:
konto deactivated]
    Soft --> Grace[30 dni grace period
możliwy reactivate]
    Grace --> Hard[Po 30 dniach:
hard delete + anonimizacja]
    Hard --> AuditLog[Wpis w gov audit:
'user X deleted on Y']

    style Soft fill:#fff3d6,stroke:#c08a2a
    style Hard fill:#ffe9e9,stroke:#e88a8a
    style Resolve fill:#e8f1fb,stroke:#7aa8e0
    

Opcja „Usuń też gospodarstwo" wywołuje flow z s.9.9 (usunięcie gospodarstwa) — z osobnym double opt-out + emailem do wszystkich userów gospodarstwa o usunięciu przez właściciela. Cały proces zaprojektowany żeby user mógł zawsze wyjść — zgodnie z RODO Art. 17.

Co się dzieje przy hard delete: user usunięty, jego memberships usunięte, ale dane gospodarstwa (zabiegi, faktury które wpisał) zostają — z atrybucją „usunięty użytkownik" (audit log). To zgodne z RODO (legitimate interest właściciela gospodarstwa do dokumentacji).

9.7 Ustawienia gospodarstwa

9.8 Backup i eksport gospodarstwa

9.9 Usunięcie gospodarstwa

Tylko właściciel. Identyczny flow jak usunięcie konta (double opt-out, 30 dni grace, hard delete + anonimizacja). Dodatkowo: wszyscy users dostają email „gospodarstwo zostało usunięte przez właściciela".

10. Admin panel (super-admin) Gotowe

Wewnętrzne narzędzie dla zespołu AGRO 360. Nigdy nie publiczne, dostępne pod osobnym subdomenem (admin.agro360.pl) z IP whitelistą + obowiązkowym 2FA. Cel: prowadzić biznes (metryki) + pomagać klientom (support).

10.1 Role w panelu admin

10.2 Struktura panelu — ekrany

10.3 Dashboard — kluczowe metryki

10.3.1 Metryki kanału Agronom (decyzja v2.0, audit #16 RESOLVED)

Osobny widget na dashboardzie admina — Marta i inni doradcy są drugim filarem przychodów:

Hipoteza do udowodnienia metrykami: klienci sprowadzeni przez agronoma mają niższy churn (potwierdzone wstępnie: 2.1% vs 3.8%). Jeśli się utrzyma, to mocny argument za inwestycją w kanał (więcej kuponów, większy retainer dla agronoma).

10.4 „Impersonate" — kluczowa funkcja supportu

Klient dzwoni z problemem, support musi zobaczyć dokładnie to co widzi user. Implementacja:

flowchart TD
    Support[Admin Support] --> Search[Szukaj usera / farmy]
    Search --> Find[Wybór klienta]
    Find --> Request[Klik 'Impersonate']
    Request --> Consent{Wymagana zgoda?}
    Consent -->|Tak - zawsze poza CRITICAL| EmailUser[Email do usera:
'Support chce mi pomóc - zgadzasz się?']
    EmailUser --> UserConsent{User zgadza się?}
    UserConsent -->|Tak, klik w emailu| Token[Token tymczasowy
ważny 30 min]
    UserConsent -->|Nie / brak akcji 24h| Deny[Brak dostępu]
    Token --> SessionLog[Session jako user
z banerem czerwonym
'IMPERSONATING - widzi user']
    SessionLog --> AuditAll[Każda akcja w audit log
z atrybucją 'support@: admin X']

    style Token fill:#fff3d6,stroke:#c08a2a
    style SessionLog fill:#ffe9e9,stroke:#e88a8a
    

Anti-patterns do uniknięcia:

• Impersonate bez zgody usera (poza CRITICAL — np. kradzież konta)
• Brak czerwonego bannera „impersonating" w UI
• Brak audit log każdej akcji w trybie impersonate
• Możliwość zmiany hasła klienta w trybie impersonate (zablokować)

10.5 Operacje wsparcia

10.6 Health i monitoring

• Sentry — błędy JS/backend, alerty na Slack
• Uptime monitoring — UptimeRobot / Better Stack, każda 1 min, alert SMS dla on-call
• Status page — publiczna strona status.agro360.pl z incydentami (transparentność dla klientów)
• DB metrics — Supabase dashboard, alerty na connection pool, slow queries
• Email deliverability — Resend/Postmark dashboard, alerty na bounce rate > 2%
• Webhook reliability — Stripe webhooks signature verification + retry, alert gdy > 10 failed

10.8 Środowiska testowe (decyzja v2.0, audit #15 RESOLVED)

Trzy poziomy izolacji od produkcji — żeby zespół mógł rozwijać bez psucia danych klientów:

10.8.1 Test accounts na produkcji

Czasem zespół musi przetestować coś na realnej produkcji (np. webhook Stripe Live, nowy flow OAuth). Mechanizm:

• Konta oznaczone flagą is_internal=true w bazie
• Nie liczone do metryk (MRR, churn, conversion) w admin panelu (s.10.3)
• Subskrypcje jako Stripe „Internal" z 100% coupon (0 zł)
• Lista dostępna tylko super-adminom, max 5 kont per team member
• Auto-cleanup po 90 dniach nieaktywności (żeby nie zaśmiecać prod)

10.8.2 Smoke testy po deployu

Po każdym deployu na prod, GitHub Actions uruchamia Playwright E2E na test accounts:

1. Login działa (email + hasło, OAuth Google)
2. Dashboard ładuje się < 2s
3. Wpisanie zabiegu zapisuje się i odlicza z magazynu
4. Generacja PDF pakietu kontrolerskiego nie wywala 500
5. Stripe webhook (test event) trafia w endpoint i przetwarza

Jeśli któryś fail → automatyczny rollback do poprzedniej wersji + Slack alert.

10.7 Feature flags

Mechanizm rollout per cohort (alpha, beta, % users, plan). Implementacja: tabela feature_flags(name, value_json, audience_filter) + endpoint GET /api/me/flags. Przykłady flagów:

• new_dashboard_ui — testujemy nowy dashboard na 10% userów
• arimr_integration — tylko Enterprise
• weather_api_v2 — przejście z mock na real, gradual rollout
• maintenance_mode — ekran „przerwa techniczna" dla wszystkich

11. Edge cases i error handling Gotowe

Każdy edge case nieobsłużony to wycieczka klienta do konkurencji. Ta sekcja katalogizuje wszystkie scenariusze „co jeśli" zidentyfikowane w sekcjach 1-10 plus te specyficzne dla naszej branży (offline w polu, kontrola ARiMR „za 30 minut", BLIK się skończył w żniwa).

11.1 Auth & dostęp

11.2 Offline i sieć

Offline-first to wartość rdzeniowa — Tomek w polu nie ma zasięgu, ale chce wpisać zabieg. Strategia:

11.3 Kolizje danych (concurrent edits)

Persona Tomek wpisuje zabieg offline, pracownik Marek równolegle online wpisuje inny zabieg na tym samym polu. Co dalej?

11.4 Billing edge cases

11.5 Dane i magazyn

11.6 Integracje z zewnętrznymi serwisami

11.7 Branżowe edge cases (specyficzne dla rolnictwa)

11.8 Globalna obsługa błędów — wzorce UI

• Toast notyfikacje — success (zielony), warning (żółty), error (czerwony), info (niebieski). Max 4-5s, klikalne żeby zostawić, X żeby zamknąć.
• Inline errors w formularzach — pod polem, czerwone, konkretne („Email musi zawierać @" zamiast „Błędne dane")
• Empty states — gdy brak pól / zabiegów / faktur — przyjazna ilustracja + CTA „Dodaj pierwsze pole"
• Loading skeleton — zamiast spinnerów (lepszy UX)
• Retry buttons — przy każdym network error przycisk [Spróbuj ponownie]
• Crash page — gdy całość się wywali: „Coś poszło nie tak. [Wróć do dashboardu] [Zgłoś błąd]" + automatyczny send do Sentry

12. Roadmap implementacji Gotowe

Sekcja sumuje wszystkie wcześniejsze ustalenia w konkretny plan działania. Założenia: jedna osoba (Adam) + Claude jako pair, iteracyjnie, fragmentarycznie. Cel: pierwszy płacący klient w 4-6 miesięcy od decyzji „budujemy".

12.1 Stack technologiczny — finalne decyzje v2.0 (greenfield, audyt #17 + #18 RESOLVED)

Łączny stack to ~12-15 zewnętrznych zależności. Większość ma free tier wystarczający na pierwsze 6 miesięcy. Szacunkowy koszt miesięczny po pierwszych 50 klientach: ~120-180 zł (Supabase Pro $25, Stripe transakcje, Resend pro $20, Sentry hobby, reszta free).

12.2 Faza 0 — Przygotowanie (2 tygodnie)

• 🔧 Naprawić bugi w obecnej apce, blokujące migrację:
  • fieldWorkHistory → zapisać do localStorage
  • invoicesRegister, costsRegister → j.w.
  • Spójność seed data (grainWarehouse ma fieldId 1-3, ale farmFields pusty)
  • Konflikt nazw: paymentsPanel → farmExpensesPanel
• 📋 Rejestracja firmy (Sp. z o.o. lub JDG), NIP, konto bankowe, księgowa
• 📄 Regulamin SaaS + Polityka prywatności (RODO) — prawnik
• 🎨 Branding (logo, paleta, typografia) — może zostać obecna zielona
• 🌐 Domeny: agro360.pl, app.agro360.pl, admin.agro360.pl, status.agro360.pl
• 📧 Email: kontakt@, noreply@, support@ — DNS SPF/DKIM/DMARC

12.3 Faza 1 — MVP SaaS greenfield build (14-16 tygodni)

Cel: Pierwsze 10 płatnych gospodarstw + 2 aktywnych agronomów. Wszystko inne odpuszczamy. Estymata wyższa niż w v1.0 (była 8-10 tyg) — bo greenfield build = wszystko od zera, nie refaktor.

gantt
    title Faza 1 — MVP SaaS greenfield (~14-16 tygodni)
    dateFormat YYYY-MM-DD
    section Setup
    Monorepo + design system (Tailwind+shadcn) :s1, 2026-06-01, 5d
    Supabase setup + schema + RLS              :s2, 2026-06-01, 7d
    Vercel hosting + CI/CD                     :s3, after s1, 3d
    section Auth & Multi-tenancy
    Auth UI (rejestracja, login, reset)        :a1, after s2, 7d
    Membership model + role gating             :a2, after a1, 5d
    Switcher gospodarstw + invitations         :a3, after a2, 7d
    section Core Modules
    Pola — CRUD + lista + szczegóły            :c1, after s3, 7d
    Magazyn — 3 typy + alerty + auto-odejmowanie :c2, after c1, 10d
    Prace polowe — formularz uniwersalny       :c3, after c2, 14d
    Mieszaniny ŚOR + kolejność WG/SC/EC/SL     :c4, after c3, 7d
    Faktury + koszty + dashboard               :c5, after c4, 10d
    Raporty PDF (klient-side, pakiet kontroler) :c6, after c5, 7d
    section Onboarding & Retention
    Onboarding wizard A + B                    :o1, after a3, 7d
    Post-onboarding journey (emaile)           :o2, after o1, 5d
    Empty states + skeleton loaders            :o3, after c1, 5d
    section Billing
    Stripe integration + plany + checkout      :b1, after c5, 7d
    Subscription panel + dunning + faktury VAT :b2, after b1, 7d
    section Landing & Launch
    Landing page (Next.js static)              :l1, 2026-06-01, 14d
    Beta testers (5-10) feedback loop          :l2, after b2, 14d
    Smoke testy + monitoring + go-live         :l3, after l2, 7d
    

12.4 Faza 1 — checklist szczegółowy (greenfield)

Łącznie: 27 zadań × średnio 5-7 dni roboczych = ~140-180 person-days = 14-16 tygodni dla solo foundera (Adam) lub 8-10 tygodni dla pary (Adam + 1 dev).

12.5 Faza 1 — co świadomie NIE robimy

• ❌ Admin panel (sekcja 10) — dopiero w fazie 2
• ❌ Offline-first / PWA — zaczynamy online-only, architekturę przygotowujemy
• ❌ 2FA — w fazie 2 (Supabase Auth obsługuje, ale UI flow w 2)
• ❌ Mapy GPS realne — najpierw ręczne wpisywanie powierzchni
• ❌ Pogoda real-time — mock z apki zostaje na start
• ❌ MATIF real-time — mock
• ❌ Server-side PDF — print-to-PDF wystarcza na MVP
• ❌ OCR faktur — ręczne wpisywanie
• ❌ Enterprise plan
• ❌ API publiczne dla katalogów ŚOR
• ❌ Aplikacja mobilna natywna — PWA wystarcza

12.6 Faza 2 — Wzrost i polerka (10-14 tygodni)

Cel: 100+ płatnych gospodarstw, NPS > 40, zero blokerów do skalowania.

• 🛠️ Admin panel + metryki + impersonate (s.10)
• 📱 PWA + offline-first (Service Worker + IndexedDB) (s.11)
• 🗺️ Mapy GPS realne (OpenStreetMap + Leaflet)
• 🌦️ Integracja pogoda (OpenWeather) + alerty pogodowe
• 📊 Server-side PDF (Puppeteer / serverless) — lepsze raporty ARiMR
• 🔐 2FA — pełny flow w UI
• 👩‍🌾 Rola Agronom + dashboard agronoma „moi klienci"
• 💡 Kalkulator ROI w landingu (s.2 — pomysł)
• 🎯 Kupony / kody promocyjne (Stripe)
• 📈 Blog SEO (s.2 — pomysł)
• 🔔 Health score per gospodarstwo (s.10 — pomysł)
• 📋 „Pakiet kontrolerski" jednoklikowy (s.9 — pomysł)

12.7 Faza 3 — Enterprise i integracje (długoterminowo)

• 🏢 Plan Enterprise + multi-farm dla agronomów
• 🤝 Integracja ARiMR (eksport e-Wniosek, import działek)
• 📷 OCR faktur (Google Vision / własny)
• 🤖 AI-asystent („zaproponuj termin oprysku", „przewiduj plon")
• 📡 API publiczne (dla księgowości, ERP-ów rolniczych)
• 📱 Aplikacja natywna iOS / Android (jeśli PWA nie wystarcza)
• 🛰️ Integracje GPS z ciągnikiem (ISOBUS, AgrirouterApi) — sprzęt premium
• 🌍 Wersja EN dla EU export

12.8 Metryki sukcesu per faza

12.9 Ryzyka i mitigacja

12.10 Kolejność akcji następnego tygodnia (very next)

1. Walidacja: 5 rozmów z prawdziwymi rolnikami z grupy docelowej. Pytania: czy płaciliby 49 zł/mies? Co byłoby killer feature? Co dzisiaj robią z ŚOR?
2. W parallel: fix bugów (fieldWorkHistory persystencja, seed data spójność, nazwa paymentsPanel)
3. Po rozmowach: aktualizacja sekcji 1 (persona) i 1.6 (model cenowy) na podstawie feedbacku
4. Decyzja go/no-go fazy 0 → 1
5. Jeśli go: rejestracja firmy + Supabase setup (równolegle)

13. Notatki dla Przemka — co weryfikujesz jako rolnik v2.0

Przemek — Ty jesteś autorem prototypu agro360-mvp2.html i to dzięki Tobie wiemy że logika agronomiczna działa. Cała reszta dokumentu to nasza propozycja przekształcenia tego w pełnoprawny SaaS. Ta sekcja jest specjalnie dla Ciebie — zostawiamy listę konkretnych pytań na które tylko rolnik może odpowiedzieć rzetelnie. Twoje „nie tak" zaoszczędzi nam tygodnie pracy.

13.1 Persona główna — czy Tomek jest realny?

Opisaliśmy Tomka (s.1.1): 42 lata, 60-150 ha, własny ciągnik + opryskiwacz, kombajn często wynajmowany, 0-2 stałych pracowników, smartfon Android, Excel na poziomie podstawowym, korzysta z Top Agrar / Agrofakt.

• Czy Tomek to realna persona, której znasz w swojej okolicy?
• Wiek 42 — w sam raz, za stary, za młody? (chodzi o gotowość do płacenia za apkę cyfrową)
• 60-150 ha to dobry przedział? Może 30-80? Może 100-300?
• Czy „Tomek" używa jakiejkolwiek apki rolniczej dziś? eDWIN? SatAgro? FarmFacts? Excel? Zeszyt?
• Co jeszcze robi w gospodarstwie z czego dziś nie korzysta z apki, ale chętnie zacząłby?

13.2 Persona Marta (agronom) — czy ma sens?

Założyliśmy że doradcy agronomiczni (firmy chemiczne, niezależni doradcy) obsługują 10-30 rolników i chętnie zapłacą 99 zł/mies za apkę z dostępem do danych klientów.

• Czy znasz takich doradców w okolicy?
• Czy oni już mają jakieś narzędzie, czy „każdy klient w innym Excelu / w głowie"?
• Czy 99 zł/mies to dla nich akceptowalna kwota? (Lider rynku — IsoBus / SatAgro Premium — kosztuje 200-400 zł)
• Czy oni byliby skłonni sprowadzać klientów do AGRO 360 (kanał afiliacji)?

13.3 Cena Pro 49 zł/mies — sweet spot?

Zakładamy 49 zł/mies za gospodarstwo (490 zł/rok). Dla Tomka 60-150 ha to ok 0.5-0.8 zł/ha/mies — czyli koszt 4-5 litrów Roundupa rocznie.

• Czy 49 zł to dla Tomka akceptowalna kwota, biorąc pod uwagę że dziś nie płaci nic (papier + Excel)?
• Może lepiej 99 zł/mies (postrzegana wyższa wartość)? Lub 29 zł (bezbolesny mikro-impuls)?
• Wolałby rocznie (490 zł raz) czy miesięcznie (49 zł × 12 = 588 zł)?
• Co Cię najmocniej skłania (lub nie) do zapłaty za narzędzie cyfrowe? (To zwykle największa bariera dla persony Tomek.)

13.4 Value proposition — czy to TO?

Powtarzamy 3 obietnice (s.1.5):

1. Rejestr ŚOR pod kontrolę ARiMR w jednym kliku (PDF do druku)
2. Koszty zł/ha per uprawa automatycznie
3. Magazyn który sam się odlicza

• Która z trzech jest najmocniejsza dla Tomka? Która najsłabsza?
• Czego brakuje w tej trójcy? Co by Cię najmocniej skusiło do zapłaty natychmiast?
• Czy obietnica „pakiet kontrolerski ARiMR jednym klikiem" (s.9 — killer feature) to dla Ciebie realny problem? Czy faktycznie boli kontrola?

13.5 Mieszaniny ŚOR — kolejność WG/SC/EC/SL

W prototypie zaimplementowałeś sortowanie mieszanin wg formulacji (WG → SC → EC → SL). To jest jedna z naszych „kopiujemy 1:1" decyzji (s.5.4).

• Czy ta kolejność jest standardem w realnym opryskiwaniu? Skąd ją wziąłeś?
• Czy są wyjątki które apka powinna obsłużyć? (np. niektóre adiuwanty wlewane na końcu)
• Czy „woda / połowa / WG / SC / EC / SL / woda / reszta" to kompletny algorytm?
• Co ze sprawdzaniem kompatybilności preparatów? Mamy pomysł alertu „Artea + Roundup nie zalecane" — czy to jest realny case z życia?

13.6 Lista preparatów ŚOR (sor_catalog)

Prototyp ma 12 preparatów hardcoded. Plan: rozszerzyć do 100+ w MVP i aktualizować co kwartał z gov.pl.

• Czy 100 preparatów wystarczy? Ile realnie używa Tomek (5-10? 30?)?
• Skąd najlepiej brać aktualną listę? Rejestr MRiRW? Etykiety z gov.pl? Producenci?
• Czy regionalne preparaty (lokalne firmy chemiczne) są ważne, czy wystarczą te globalne?
• Jak często wpadają nowe preparaty? Jak często coś jest wycofywane?

13.7 Sezonowość — czego nie wziąłem pod uwagę?

Rolnictwo to silnie sezonowy biznes. W dokumencie wspominamy „tryb żniw" (s.11), zmiana sezonu 1 września (s.11.7), klęski żywiołowe.

• Co się dzieje zimą (grudzień-luty)? Rolnik nie używa apki — czy to ryzyko churnu? Czy zostaje bo „magazyn i faktury"?
• Kiedy są peak'i pracy? Wiosna (siew) / lato (ochrona) / jesień (żniwa)? Czy apka powinna mieć „tryb wzmożonej aktywności" automatycznie?
• Roczny czy sezonowy abonament — co ma więcej sensu? (49 zł/mies × 12 vs. „pakiet sezonowy 350 zł na 8 mies + 4 mies gratis")

13.8 Operatorzy w gospodarstwie — kto naprawdę wpisuje dane?

Założyliśmy 4 role (s.6.1): Właściciel, Współwłaściciel, Pracownik, Agronom. Plus pomysł na Księgową.

• Czy realnie ktoś poza właścicielem wpisuje dane do takiego systemu? Czy żona / syn / pracownik to dotknie?
• Czy „pracownik na żniwa" (sezonowy) potrzebuje konta, czy on tylko wpisuje za niego właściciel?
• Limit 3 operatorów w Pro — wystarczy? Trzeba więcej?
• Księgowa — czy realnie potrzebuje DOSTĘPU do apki, czy wystarczy eksport Excel raz na miesiąc?

13.9 Pakiet kontrolerski — co MUSI zawierać?

Killer feature MVP: PDF pod kontrolę ARiMR/PIORiN.

• Co kontroler realnie sprawdza w czasie kontroli? Czego od Tomka wymaga?
• Czy musi być format zgodny z e-Wniosek (XML) czy wystarcza PDF do wydruku?
• Mapy pól — w kontroli ważne czy nie? (Geoportal vs nasza mapa)
• Czy kontroler chce widzieć paragony zakupu (faktury) przy każdym zabiegu, czy tylko sumarycznie?
• Jak długo trzeba przechowywać rejestr (RODO mówi 5 lat, rolnictwo może więcej)?

13.10 Słownik — czy używamy poprawnej terminologii?

Glosariusz (s.0.4) zawiera 25+ terminów. Sprawdź czy używamy tych samych słów co rolnik:

• „Pole" czy „działka" czy „kawałek"? (formalne vs potoczne)
• „Zabieg" czy „oprysk" czy „nawożenie"? (zabieg to nasze nadrzędne, czy lepiej rozdzielać)
• „Uprawa" czy „kultura" czy „roślina"?
• „Magazyn" czy „skład" czy „przechowalnia"?
• „Plon" jako wynik zbioru — OK, czy potocznie „zbiór"?
• „Mieszanina" ŚOR — czy raczej „mieszanka", „roztwór roboczy"?
• Czy są regionalne różnice w nazewnictwie? (Wielkopolska vs Mazowsze vs Podlasie)

13.11 Czego nie ma a powinno być?

Ten dokument jest naszą hipotezą. Bardzo prawdopodobne że czegoś nie pomyśleliśmy.

• Jakie zadanie codzienne rolnika nie zostało tu pokryte? (np. zarządzanie maszynami / paliwem / pracownikami sezonowymi / sprzedażą plonów / transportem)
• Co Cię w prototypie najbardziej brakowało, a co masz tylko w głowie / zeszycie?
• Jaki raport / wykres / podsumowanie chciałbyś dostawać automatycznie (np. „tygodniowy raport mailem")?
• Co Cię w innych aplikacjach rolniczych najbardziej wkurzało?

13.12 Beta testers — kogo poznasz?

W Fazie 1 (s.12.4) potrzebujemy 5-10 beta testerów z grupy docelowej. To kluczowy zasób.

• Czy znasz 5-10 rolników których moglibyśmy zaprosić do bety? (60-200 ha, smartfon, otwarci na nowości)
• Czy znasz 2-3 agronomów do bety planu Agronom Pro?
• Czy byłbyś gotów ich osobiście zarekomendować? (Zaufanie do Ciebie >> zaufanie do nieznanej apki)
• Czy ktoś z Twoich znajomych kontrolerów ARiMR mógłby zwalidować nasz pakiet kontrolerski PDF?

13.13 Co dalej?

Po Twoich odpowiedziach planujemy:

1. Aktualizacja dokumentu do v2.1 z Twoimi poprawkami (persona / cena / value prop / terminologia)
2. Adam zarejestruje firmę i Supabase
3. Zaczynamy budować Fazę 1 zgodnie z s.12.4 — 27 zadań w 14-16 tygodni
4. Po 8 tygodniach masz pierwszy zalogowalny SaaS do potestowania
5. Po 14-16 tygodniach launch z bety z 5-10 rolnikami

Dzięki za prototyp, Przemek. Bez Twojej wizji to byłoby teoretyzowanie. Z Twoją wizją — mamy specyfikację działającą na żywym organizmie, z prawdziwą logiką rolniczą i polskimi realiami. Twoja walidacja tej sekcji to ostatni krok przed kodem.