# The 20-Minute Hero — MVP Scope

> Dokument definiuje minimalny zakres produktu (MVP) wystarczający do walidacji core hipotezy.
> **Core hipoteza:** Użytkownik wychodzi na zewnątrz → wykonuje GPS quest → AI weryfikuje dowód → dostaje XP + HERO tokeny.

---

## Co waliduje MVP

| Pytanie | Jak walidujemy |
|---|---|
| Czy GPS questy motywują do wychodzenia z domu? | DAU/MAU, czas do pierwszego questu |
| Czy AI weryfikacja jest wystarczająco dobra? | % fałszywych pozytywów/negatywów (ręczny audit 100 proofów) |
| Czy loop XP → poziom → kolejny quest działa? | Retention D1/D7 (cel: D1 ≥40%, D7 ≥15%) |
| Czy AI onboarding (Aldric) buduje zaangażowanie? | % ukończonych onboardingów, NPS |

---

## Zakres funkcji MVP

### W MVP

| Moduł | Szczegóły |
|---|---|
| Firebase Auth | Google + Apple Sign-In, Firebase ID token (Bearer) |
| AI Onboarding | Aldric, uproszczony do 3-4 tur, wybór klasy, backstory |
| Profil + Postać | Poziom, XP bar, HERO balance, klasa, cechy wizualne (statyczny art per class) |
| GPS Quest Discovery | PostGIS ST_DWithin, quest_templates seedowane (30 questów), mapa z pinami |
| Przyjęcie questu | Jeden aktywny quest naraz, czas na wykonanie |
| Proof upload | Zdjęcie only (expo-camera + presigned URL → Cloudflare R2) |
| AI weryfikacja | Gemini 3 Flash, few-shot calibration (§35), JSON schema output |
| XP + HERO award | BullMQ job, idempotency_key, natychmiastowe off-chain (token_ledger) |
| Push: wynik | FCM/APNs — Quest zatwierdzone! +150 XP, +2 HERO |
| Leaderboard | Top 20 postaci po XP (tygodniowy) |
| Deploy | Docker Compose, VPS, HTTPS |

### Poza MVP (post-PMF)

| Moduł | Dlaczego czeka |
|---|---|
| Community voting | AI jako jedyny arbiter wystarcza do walidacji |
| Guilds / Seasons / Weekly Challenges | Retencja — ważna, ale dopiero gdy jest co utrzymać |
| IAP / Hero Pass / Token Shop | Monetyzacja po walidacji product-market fit |
| Sponsored Quests (B2B) | Wymaga relacji sprzedażowych |
| AI generowanie questów | Ręcznie seedowane questy wystarczą na alpha |
| Social (follow, tips, reakcje) | Sieć społecznościowa — wymaga masy krytycznej |
| UFS Fraud Scoring | Podstawowy rate limit wystarczy |
| GDPR deletion pipeline | Soft delete wystarczy prawnie na etapie MVP |
| Avatar AI generation | Statyczny art per class, Tier 1 tylko |
| GPS anti-spoofing (zaawansowany) | Podstawowy speed-check wystarczy |
| Video / multi-photo proof | Foto na start, reszta w sprint 2 |

---

## Tabele bazy danych — MVP subset

Z Migration 001 używamy tylko:

- users — Firebase auth, profil, reviewer_accuracy
- user_devices — FCM tokeny (push)
- characters — klasa, poziom, XP, atrybuty, 5x attr_*
- onboarding_sessions — konwersacja z Aldricem
- quest_templates — 30 seedowanych questów z GPS coords
- quests — instancje questów per user
- quest_attempts — próby (łączy quest z proof)
- proofs — metadata, status, AI score, s3_key
- xp_ledger — każdy XP event z idempotency_key
- token_ledger — każdy HERO event z idempotency_key
- token_balances — cache salda

Pomijamy w MVP: guilds, guild_members, seasons, season_pass_purchases, weekly_challenges, iap_purchases, hero_pass_subscriptions, sponsors, tips, social_follows, votes, vote_queue, character_milestones.

---

## Ekrany mobilne MVP

- /auth — Login (Google / Apple)
- /onboarding — AI chat z Aldricem (3-4 tury)
- /onboarding/class — Wybór klasy postaci
- /onboarding/done — Podsumowanie + przejście do mapy
- /(tabs)/map — Mapa z questami w pobliżu
- /(tabs)/quests — Lista aktywnych + historia questów
- /(tabs)/profile — Postać: klasa, poziom, XP bar, HERO balance, streak
- /(tabs)/leaderboard — Top 20 w tym tygodniu
- /quest/:id — Szczegóły questu + przycisk Akceptuj
- /quest/:id/camera — Kamera → capture → upload
- /quest/:id/proof — Status weryfikacji (pending → wynik)

---

## Quest templates — seed (30 questów)

Seedujemy 10 questów per kategoria dla 3 miast startowych:

| Kategoria | Przykłady |
|---|---|
| outdoor_photo | Sfotografuj najstarszy budynek w promieniu 500m · Znajdź i zrób zdjęcie ławce w parku |
| social | Porozmawiaj z nieznajomym i zrób wspólne selfie (za zgodą) · Zapytaj kogoś o polecenie miejsca |
| observation | Opisz 3 różne materiały na fasadach budynków w tej ulicy · Znajdź coś czerwonego, okrągłego i metalowego |

Każdy quest_template ma: title, description, proof_type, difficulty, xp_reward, token_reward, location (POINT), radius_m, category, time_limit_minutes.

---

## Harmonogram budowy

| Faza | Zakres | Dni |
|---|---|---|
| 1 — Setup | Turborepo + pnpm, Hono skeleton, Drizzle + PostgreSQL/PostGIS, Docker Compose, env config (Zod) | 1 |
| 2 — Auth + Character | Firebase middleware, auth endpoint, onboarding API, Aldric prompt, character creation | 2 |
| 3 — Quest System | Migration subset, 30 seeded quest_templates, nearby endpoint (PostGIS), quest accept | 2 |
| 4 — Proof + AI | Presigned URL (R2), proof submit, BullMQ verifyProof worker, Gemini few-shot, XP award (idempotent) | 2 |
| 5 — Push + Leaderboard | FCM push (quest result), weekly leaderboard, character profile endpoint | 1 |
| 6 — Mobile | Expo setup, Auth, Onboarding chat, Map, Quest detail, Camera + upload, Proof status, Profile, Leaderboard | 4 |
| 7 — Deploy + QA | VPS deploy, HTTPS, real device testing (GPS + camera), bugfixes, seed data | 2 |
| Total | | ~14 dni roboczych |

Wąskie gardła: testowanie GPS + kamery na prawdziwym urządzeniu, kalibracja Gemini, TestFlight review ~24h.

Nie wliczone: konfiguracja kont (Firebase, Gemini API, Cloudflare R2, Apple Developer, Google Play), review każdej fazy.

---

## Definicja gotowe dla MVP

- [ ] Rejestracja przez Google/Apple działa na prawdziwym telefonie
- [ ] AI onboarding (Aldric) tworzy postać w max 4 turach
- [ ] Mapa pokazuje questy w promieniu 1km od użytkownika
- [ ] Użytkownik może zrobić zdjęcie jako proof i je wysłać
- [ ] Gemini weryfikuje zdjęcie w max 30s
- [ ] Po zatwierdzeniu: XP i HERO dodane do profilu (idempotent)
- [ ] Push notification przychodzi z wynikiem
- [ ] Leaderboard pokazuje top graczy
- [ ] Działa bez crashy przez 30 minut użytkowania