HonNoMachi je Android aplikacija namijenjena ljubiteljima knjiga. Omogućuje registriranim korisnicima da postanu dio zajednice u kojoj mogu prodavati knjige koje im više ne trebaju i otkrivati nove naslove za svoju kolekciju.
HonNoMachi (本の街 - "Grad knjiga") je mobilna platforma koja spaja kupce i prodavače rabljenih knjiga. Aplikacija pruža intuitivno korisničko iskustvo s fokusom na sigurnost transakcija i jednostavnost korištenja.
Ključne značajke:
- Sigurna autentifikacija korisnika (Email/Lozinka, Google OAuth)
- Pretraživanje i filtriranje knjiga po nazivu, žanru i autoru
- Košarica s integriranim plaćanjem
- Simulacija plaćanja putem Stripe integracije
- Upravljanje korisničkim profilom
- Administratorski panel za moderaciju
| Kategorija | Tehnologija |
|---|---|
| Jezik | Kotlin |
| UI Framework | Jetpack Compose + Material Design 3 |
| Arhitektura | MVVM (Model-View-ViewModel) |
| Backend | Firebase (Authentication, Firestore, Storage, Cloud Functions) |
| Cloud Functions | TypeScript / Node.js 22 |
| Plaćanje | Stripe Android SDK (simulacija) |
| Async Operations | Kotlin Coroutines + Flow |
| Dependency Injection | Hilt |
| Version Control | Git / GitHub (Git Flow workflow) |
| CI/CD | GitHub Actions |
| Project Management | Jira + Confluence |
Prije nego započnete s instalacijom, provjerite imate li sljedeće:
- Android Studio Ladybug (2024.2.1) ili novije
- JDK 17 ili novije
- Android SDK s minimalno API 26 (Android 8.0 Oreo)
- Git instaliran na računalu
- Firebase projekt (ili pristup postojećem projektu tima)
- Google Play Services na uređaju/emulatoru
git clone https://github.com/25-26-izvanredni-tim/HonNoMachi.git
cd HonNoMachiVažno: Datoteka
google-services.jsonnije uključena u repozitorij zbog sigurnosnih razloga.
Opcija A: Zatražite datoteku od člana tima putem sigurnog kanala.
Opcija B: Preuzmite iz Firebase konzole:
- Prijavite se na Firebase Console
- Odaberite projekt HonNoMachi
- Idite na Project Settings → Your apps → Android app
- Preuzmite
google-services.json - Premjestite datoteku u
app/direktorij projekta
- U
local.propertiesdodajte:STRIPE_PUBLISHABLE_KEY=pk_test_... - U CI okruženju postavite varijablu:
STRIPE_PUBLISHABLE_KEY=pk_test_... - Nikada ne stavljajte Stripe secret key (
sk_...) u Android aplikaciju - Backend secret-e za Cloud Functions postavite preko Firebase CLI:
npx firebase-tools functions:secrets:set STRIPE_SECRET_KEY --project <firebase-project-id>npx firebase-tools functions:secrets:set STRIPE_WEBHOOK_SECRET --project <firebase-project-id>npx firebase-tools functions:secrets:set STRIPE_WALLET_WEBHOOK_SECRET --project <firebase-project-id> - Deploy backend funkcija (PowerShell: navodnici oko
--only):npx firebase-tools deploy --only "functions:createCheckoutPaymentIntent,functions:addToCartAndReserve,functions:removeFromCartAndRelease,functions:cancelCheckout,functions:releaseExpiredCheckoutSessions,functions:releaseExpiredCartReservations,functions:createWalletTopupIntent,functions:stripeWebhook,functions:stripeWalletWebhook" --project <firebase-project-id> - U Stripe Dashboardu dodajte checkout webhook endpoint:
https://us-central1-<firebase-project-id>.cloudfunctions.net/stripeWebhooki uključite evente:payment_intent.succeeded,payment_intent.payment_failed,payment_intent.canceled - U Stripe Dashboardu dodajte wallet webhook endpoint:
https://us-central1-<firebase-project-id>.cloudfunctions.net/stripeWalletWebhooki uključite evente:payment_intent.succeeded,payment_intent.payment_failed,payment_intent.canceled,charge.refunded
- Otvorite projekt u Android Studiju
- Kliknite Sync Now za sinkronizaciju Gradle datoteka
- Povežite Android uređaj ili pokrenite emulator
- Kliknite Run 'app' ili koristite
Shift + F10
Ako pokrećete Gradle iz terminala:
# Windows PowerShell
.\gradlew.bat :app:assembleDebug# Bash / Git Bash
./gradlew :app:assembleDebugZa detaljnije upute o postavljanju projekta, pogledajte: Development Setup - Confluence
- Registracija putem Email/Lozinka s validacijom podataka
- Email verifikacija (Firebase Authentication verifikacijski tok)
- Prijava/Odjava — sigurna autentifikacija postojećih korisnika
- Validacija forme (real-time provjera email formata i politike lozinke)
- Ponovno slanje verifikacijskog emaila
- Pohrana korisničkih podataka u Firestore bazu
- Google OAuth prijava/registracija (Firebase Auth + Credential Manager)
- Pregled svih dostupnih knjiga (HomePage s LazyColumn)
- Pretraga po naslovu s dinamičkim filtriranjem
- Detaljni pregled pojedine knjige (galerija slika, svi podaci)
- Ažuriranje podataka (ime, prezime, kontakt, adresa)
- Promjena lozinke (validacija jačine + poništavanje sesija)
- Promjena e-maila uz sigurnosne korake (ponovna verifikacija)
- Lokalizacija EN/HR (string resursi, enumi: BookGenre, BookCondition, Currency)
- Lint korak dodan u CI pipeline prije builda
- Model podataka za ponude (naslov, autor, žanr, godina, izdavač, opis, stanje, cijena, slike)
- UI za kreiranje i uređivanje ponuda s upravljanjem stanjima (loading/saving/error)
- ViewModel i business logika za upravljanje ponudama
- Unit testovi za validaciju i business logiku
- CartItemModel i CartRepository s Firestore integracijom (real-time snapshotListener)
- Dodavanje u košaricu s prevencijom dupliciranja
- Pregled košarice, brisanje artikala i prikaz ukupne cijene (CartPage)
- Indikator košarice (BadgedBox) s real-time ažuriranjem badge-a
- CartViewModel s Hilt DI i upravljanjem stanjima (Loading/Success/Error)
- Setup i integracija Firebase Crashlytics (plugin, konzola, Version Catalog)
- CrashlyticsManager za centralizirano hvatanje non-fatal grešaka
- Automatsko praćenje trenutnog ekrana i prijavljenog korisnika (userId)
- Pristanak korisnika na analitiku i Crashlytics (GDPR)
- Firebase Alerts i Slack notifikacije za crash izvještaje
- Reorganizacija paketa (ui/, data/, di/)
- Hilt setup (@HiltAndroidApp, @AndroidEntryPoint, AppModule)
- Refaktoriranje Firebase logike u repozitorije (AuthRepository, BookRepository)
- ViewModeli s @HiltViewModel i UiState data klasama po ekranu
- Izdvojen image_uploader modul za prijenos slika (Firebase Storage)
- ImageUploader sučelje s FirebaseImageUploader implementacijom
- Result sealed klasa za upravljanje pogreškama (success/error)
- ImageUploaderModule s Hilt DI
- Konfiguracija Firebase Storage pravila i ažuriranje dozvola u AndroidManifest.xml
- Refaktoriran
AddPage.kt– validacija u ViewModel, custom state holder, form polja kao zasebne composable komponente - Refaktoriran
AuthRepository.kt– Firestore operacije u zasebnu klasu,getUserDocument()helper, konstante za kolekcije - Refaktoriran
ProfileScreen.kt– boje u temu, ekstrahiranaProfileEditFormcomposable, stringovi u resources - Refaktoriran
AuthViewModel.kt– callbackovi zamijenjeni sa StateFlow, pojednostavljen init blok, uklonjeni magic stringovi - Kreirane reusable auth komponente (
EmailInputField,PasswordInputField) - Refaktoriran
LoginScreen.kt,SignupScreen.ktiChangePasswordScreen.kt– integrirane zajedničke auth komponente, uklonjen duplicirani kod
- Unit testovi za
AuthViewModel(19),AddBookViewModel(25),HomeViewModel(6) - Unit testovi za
AuthRepository(12),BookRepository(5),ProfileRepository(8),CartRepository(5) - Unit testovi za
FirestoreUserDataSourceImpl(4),Result<T>(3),ImageSourceInitializer(+2) - Pokrivenost koda (JaCoCo) povećana s 3.6% na 29.39% (89 novih testova u 10 test klasa)
- Administratorska navigacija, zaštita ruta i Firestore sigurnosna pravila
-
AdminRepository– dohvat, pretraga i filtriranje korisnika po statusu - Sučelje – lista korisnika, pretraga i filteri, detaljan prikaz, account status sekcija
- Unit testovi:
AdminRepositoryTest(11),AdminViewModelTest(3),AdminUserListViewModelTest(8),UserDetailViewModelTest(4) - Instrumentirani testovi:
AdminScreenTest(4)
- Pozadinska logika suspenzije i reaktivacije korisnika
- Firestore sigurnosna pravila za suspenziju
- Sučelje – dijalog, akcije i efekti suspenzije na korisnički račun
-
OrderRepository– ažuriranje statusa knjige uSOLDi brisanje iz košarica svih korisnika - Validacija nedostupnih knjiga pri dodavanju u košaricu
- Konverzija valuta (USD u EUR),
HomePageprikazuje samo dostupne knjige - Unit i Instrumented testovi za upravljanje košaricom
- Integracija Stripe Android SDK-a za simulaciju plaćanja (HNM-101/102)
- Stripe Checkout flow — kreiranje PaymentIntent-a, Success/Cancel ekrani
- Cloud Functions backend (TypeScript) —
createCheckoutPaymentIntent,stripeWebhook,stripeWalletWebhook - Rezervacija knjiga u košarici s automatskim istekom (TTL 15 min, max 60 min)
- Scheduled Cloud Functions za čišćenje isteklih rezervacija i checkout sesija
- Konverzija valuta (EUR ↔ USD) na backend i frontend razini
- Implementacija wallet sustava unutar aplikacije (PaymentSheet)
- Cloud Function
createWalletTopupIntentza nadopunu novčanika - Stripe Wallet webhook za praćenje transakcija (uspjeh, neuspjeh, refund)
- Email servis za obavijesti o kupnji putem Nodemailer-a (HNM-103)
- Email obavijesti kupcu i prodavaču nakon uspješne transakcije
- Korisničke postavke za uključivanje/isključivanje obavijesti
- ShelfPage s tabovima "Purchased" i "Sold" za pregled povijesti transakcija (HNM-108)
- Filtriranje i prikaz knjiga po statusu kupnje/prodaje
- My Listings ekran za upravljanje vlastitim ponudama (HNM-109)
- Filtriranje ponuda po statusu (All/Active/Inactive)
- Toggle vidljivosti ponude (AVAILABLE ↔ INACTIVE) i brisanje ponuda
- Integracija My Listings kao treći tab na ShelfPage
- Email obavijest korisniku pri suspenziji i reaktivaciji računa (HNM-300)
- Cloud Function trigger na promjenu statusa korisnika u Firestore-u
- Vizualna poboljšanja AuthScreen, ProfileScreen i BookDetailScreen (HNM-300)
- Automatsko potpisivanje Release APK-a keystoreom putem GitHub Secrets
- Distribucija potpisanog APK-a putem Firebase App Distribution za interni QA
- Automatsko verzioniranje buildova na temelju Git tagova
- ProGuard obfuskacija u release build konfiguraciji
- Nadogradnja Node.js runtime-a s v20 na v22 za Cloud Functions
- Rješavanje SonarQube arhitekturalnih i sigurnosnih nalaza
- Smanjenje kognitivne kompleksnosti UI metoda
- Reorganizacija build skripti — grupiranje dependencija, verzije u Version Catalog
- Zamjena deprecated
hiltViewModelimporta u svim UI komponentama - Zamjena ponavljajućih string literala s imenovanim konstantama
- Implementacija guard pravila za suspendirane korisnike (HNM-112)
- Implementacija monetizacije putem oglasa (HNM-113)
Projekt koristi Git Flow workflow sa sljedećom strukturom grana:
- Kreirajte novu granu iz
develop - Implementirajte promjene
- Kreirajte Pull Request prema
develop - Zatražite code review od barem jednog člana tima
- Nakon odobrenja, merge u
develop
Projekt koristi DevOps prakse za automatizaciju procesa razvoja, testiranja i isporuke.
- Jira za upravljanje projektom i praćenje zadataka
- Firebase Rules — upravljanje pravilima autentifikacije, Firestore baze i Storage-a ručno putem Firebase konzole (bez Firebase CLI / Infrastructure as Code pristupa)
- Git kao sustav za kontrolu verzija s Git Flow workflow strategijom
- GitHub kao udaljeni repozitorij i platforma za suradnju
- Struktura grana:
master(produkcija),develop(razvoj),feature/*,bugfix/*,release/* - Obvezni Pull Requesti s code reviewom prije merga u
develop
- Gradle (Kotlin DSL) kao sustav za izgradnju projekta
- Automatska izgradnja Debug APK-a unutar CI pipeline-a na svakom push-u i PR-u
- Automatska izgradnja Release APK-a pri push-u na
mastergranu - Konfiguracija:
compileSdk = 36,minSdk = 26,targetSdk = 36,JDK 17
CI pipeline pokreće se automatski na svakom push i pull request prema master i develop granama putem GitHub Actions. Pipeline uključuje:
| Korak | Opis | Ovisi o |
|---|---|---|
| Lint provjera | KTlint i Android Lint analiza koda | - |
| Unit testovi | Pokretanje unit testova s generiranjem JaCoCo izvještaja o pokrivenosti koda | - |
| SonarCloud analiza | Statička analiza koda, code smells, bugovi, sigurnosni propusti i prikaz pokrivenosti koda | Unit testovi |
| Build Debug APK | Kompilacija debug verzije aplikacije | Lint provjera, Unit testovi |
| Build Release APK | Kompilacija release verzije (samo pri push-u na master) |
Lint provjera, Unit testovi |
- Concurrency control — upravljanje istovremenim pokretanjima pipeline-a za istu granu
- JUnit za unit testove
- MockK za mockiranje ovisnosti u testovima
- Fake Repository — lažne implementacije repozitorija za izolirano testiranje bez vanjskih ovisnosti
- Jetpack Compose Testing (
ui-test-junit4) za testiranje UI komponenti - Espresso za instrumentacijske (androidTest) testove
- Coroutines Test (
kotlinx-coroutines-test) za testiranje asinkronog koda - Navigation Testing za testiranje navigacijskih tokova
- Automatsko pokretanje testova u CI pipeline-u na svakom push-u i PR-u
Planirane aktivnosti za kontinuiranu isporuku:
- Automatsko potpisivanje release APK-a (keystore putem GitHub Secrets)
- Distribucija putem Firebase App Distribution za interni QA
- Verzioniranje buildova na temelju Git tagova
- KTlint — statička analiza i provjera stila Kotlin koda prema službenim konvencijama
- Android Lint — detekcija potencijalnih bugova, sigurnosnih propusta i performansnih problema
- JaCoCo — generiranje izvještaja o pokrivenosti koda testovima (XML + HTML)
- SonarCloud — kontinuirana inspekcija kvalitete koda (statička analiza, code smells, bugovi, sigurnosni propusti) s integracijom JaCoCo izvještaja za prikaz pokrivenosti koda
- Upload lint i JaCoCo izvještaja kao CI artefakata za pregled nakon svakog builda
- GitHub Secrets za sigurno pohranjivanje osjetljivih podataka (
GOOGLE_SERVICES_JSON,SONAR_TOKEN) - Gradle Kotlin DSL (
build.gradle.kts) za deklarativnu konfiguraciju projekta i ovisnosti - Version Catalog (
libs.versions.toml) za centralizirano upravljanje verzijama biblioteka -
.gitignoreza isključivanje osjetljivih i generiranih datoteka iz repozitorija
- GitHub-Slack integracija — automatske obavijesti u Slack kanalu o push eventima, pull requestovima, code reviewovima i statusu CI pipeline-a
Implementirani alati:
- Firebase Analytics — praćenje korisničkih događaja i ponašanja unutar aplikacije
- Firebase Crashlytics — automatsko prikupljanje i analiza crash izvještaja
Kompletan Project Wiki dostupan je na Confluence:
| Dokument | Opis |
|---|---|
| Project Overview | Pregled projekta i ciljevi |
| System Architecture | Dijagram arhitekture sustava |
| Development Setup | Upute za postavljanje projekta |
| Product Backlog | Lista svih User Storyja |
| Korisnička dokumentacija | Upute za korištenje aplikacije |
| UX Design | Wireframovi i dizajn smjernice |
Projekt razvija tim studenata Fakulteta organizacije i informatike (FOI), Varaždin.
| Član | Uloga | |
|---|---|---|
| Ivan Giljević | igiljevic@student.foi.hr | Developer |
| Denis Kuzminski | dkuzminsk22@student.foi.hr | Developer |
| Zlatko Pračić | zpracic@student.foi.hr | Developer |
| Mislav Žnidarec | mznidarec@student.foi.hr | Developer |
Kolegij: Analiza i razvoj programa
Akademska godina: 2025/2026
Institucija: Fakultet organizacije i informatike, Varaždin
Status projekta: Dovršeni svi sprintovi Zadnje ažuriranje: 02.04.2026.