Initial import

2026-04-22 22:31:52 +07:00
commit ef756b97a1
71 changed files with 4518 additions and 0 deletions
--- a/docs/CODE_DOCUMENTATION.md
+++ b/docs/CODE_DOCUMENTATION.md
@ -0,0 +1,414 @@
+# Code Documentation
+
+Dokumen ini menjelaskan struktur code Android `Emoney Info` agar developer lain bisa lebih cepat memahami project, mencari area yang relevan, dan melakukan perubahan dengan aman.
+
+## 1. Ringkasan Project
+
+Project ini adalah versi Android dari aplikasi iOS `Emoney Info`.
+
+Fungsi utama aplikasi:
+- membaca kartu uang elektronik via NFC
+- menampilkan saldo dan riwayat transaksi
+- menampilkan halaman bantuan dan informasi aplikasi
+- mengekspor history transaksi ke PDF
+- menampilkan iklan AdMob banner dan interstitial
+
+Stack utama:
+- Kotlin
+- Jetpack Compose
+- Android NFC (`IsoDep`, `NfcF`, `MifareClassic`)
+- Google Mobile Ads SDK
+
+Package utama:
+- `com.korancrew.emoneyinfo`
+
+## 2. Struktur Folder
+
+Struktur code utama ada di:
+
+```text
+app/src/main/java/com/korancrew/emoneyinfo
+├── ads
+├── data
+├── nfc
+├── pdf
+├── ui
+├── util
+└── MainActivity.kt
+```
+
+Penjelasan singkat:
+
+- `ads`
+  Menyimpan konfigurasi AdMob.
+
+- `data`
+  Menyimpan model UI utama dan data FAQ.
+
+- `nfc`
+  Berisi seluruh logic pembacaan kartu, helper APDU/FeliCa, kriptografi Brizzi, dan router NFC.
+
+- `pdf`
+  Logic export history transaksi menjadi PDF.
+
+- `ui`
+  Semua screen Compose, komponen UI, tema, dan root app navigation.
+
+- `util`
+  Helper umum. Saat ini dipakai untuk logging debug-only.
+
+## 3. Entry Point Aplikasi
+
+File utama:
+- [MainActivity.kt](/Users/wirabasalamah/work/gitlab/EmoneyInfo-andro/app/src/main/java/com/korancrew/emoneyinfo/MainActivity.kt)
+
+Tanggung jawab `MainActivity`:
+- mengaktifkan theme utama
+- inisialisasi AdMob
+- membuat `UnifiedNfcReader`
+- me-render root Compose lewat `EmoneyInfoApp`
+- meneruskan event NFC dari `onNewIntent`
+- mengaktifkan dan menonaktifkan foreground dispatch NFC pada `onResume` / `onPause`
+
+Secara sederhana, `MainActivity` adalah jembatan antara lifecycle Android dengan UI dan NFC reader.
+
+## 4. Root UI dan Navigasi
+
+File utama:
+- [EmoneyInfoApp.kt](/Users/wirabasalamah/work/gitlab/EmoneyInfo-andro/app/src/main/java/com/korancrew/emoneyinfo/ui/EmoneyInfoApp.kt)
+
+`EmoneyInfoApp` adalah root Compose application. File ini menangani:
+- bottom navigation
+- `NavHost` dan route screen
+- membaca `uiState` dari `UnifiedNfcReader`
+- membaca dan menyimpan preference `show card number`
+
+Route utama:
+- `home`
+- `settings`
+- `history`
+- `faq`
+- `about`
+- `terms`
+- `privacy`
+
+Bottom navigation hanya menampilkan:
+- `E-Money`
+- `Settings`
+
+## 5. Screen Utama
+
+Screen Compose ada di folder:
+- `/ui/screens`
+
+Yang paling penting:
+
+- [HomeScreen.kt](/Users/wirabasalamah/work/gitlab/EmoneyInfo-andro/app/src/main/java/com/korancrew/emoneyinfo/ui/screens/HomeScreen.kt)
+  Menampilkan hasil scan terakhir, saldo, nomor kartu, dan transaksi terakhir.
+
+- [HistoryScreen.kt](/Users/wirabasalamah/work/gitlab/EmoneyInfo-andro/app/src/main/java/com/korancrew/emoneyinfo/ui/screens/HistoryScreen.kt)
+  Menampilkan list riwayat transaksi, banner ads, dan tombol export PDF fixed di bawah.
+
+- [SettingsScreen.kt](/Users/wirabasalamah/work/gitlab/EmoneyInfo-andro/app/src/main/java/com/korancrew/emoneyinfo/ui/screens/SettingsScreen.kt)
+  Menampilkan 4 menu utama: bahasa, tampilkan nomor kartu, pusat bantuan, dan tentang aplikasi.
+
+- [FaqScreen.kt](/Users/wirabasalamah/work/gitlab/EmoneyInfo-andro/app/src/main/java/com/korancrew/emoneyinfo/ui/screens/FaqScreen.kt)
+  Menampilkan FAQ dan pencarian pertanyaan.
+
+- [AboutScreen.kt](/Users/wirabasalamah/work/gitlab/EmoneyInfo-andro/app/src/main/java/com/korancrew/emoneyinfo/ui/screens/AboutScreen.kt)
+  Menampilkan info aplikasi dan navigasi ke terms/privacy.
+
+## 6. Model Data UI
+
+File utama:
+- [Models.kt](/Users/wirabasalamah/work/gitlab/EmoneyInfo-andro/app/src/main/java/com/korancrew/emoneyinfo/data/Models.kt)
+
+Model inti:
+
+### `CardType`
+Enum untuk jenis kartu:
+- `MANDIRI`
+- `FLAZZ`
+- `BRIZZI`
+- `TAPCASH`
+- `JACKCARD`
+- `MEGACASH`
+- `KMT`
+
+### `TransactionItem`
+Mewakili 1 item riwayat transaksi.
+
+Field penting:
+- `title`
+- `date`
+- `amount`
+- `isCredit`
+- `locationName`
+
+Method penting:
+- `formattedAmount()`
+- `formattedDate()`
+- `subtitle()`
+
+Catatan:
+- currency selalu diformat sebagai `IDR` / `Rp`
+- warna amount di UI ditentukan dari `isCredit`
+
+### `EmoneyUiState`
+State utama yang dipakai UI.
+
+Field penting:
+- `cardType`
+- `balance`
+- `cardNumber`
+- `transactions`
+- `scanMessage`
+- `isNfcSupported`
+
+Semua screen utama membaca state ini, terutama `HomeScreen` dan `HistoryScreen`.
+
+## 7. Arsitektur NFC
+
+Folder utama:
+- `/nfc`
+
+File yang paling penting:
+- [UnifiedNfcReader.kt](/Users/wirabasalamah/work/gitlab/EmoneyInfo-andro/app/src/main/java/com/korancrew/emoneyinfo/nfc/UnifiedNfcReader.kt)
+- [CardReaders.kt](/Users/wirabasalamah/work/gitlab/EmoneyInfo-andro/app/src/main/java/com/korancrew/emoneyinfo/nfc/CardReaders.kt)
+- [NfcUtils.kt](/Users/wirabasalamah/work/gitlab/EmoneyInfo-andro/app/src/main/java/com/korancrew/emoneyinfo/nfc/NfcUtils.kt)
+- [BrizziCrypto.kt](/Users/wirabasalamah/work/gitlab/EmoneyInfo-andro/app/src/main/java/com/korancrew/emoneyinfo/nfc/BrizziCrypto.kt)
+- [AndroidStrings.kt](/Users/wirabasalamah/work/gitlab/EmoneyInfo-andro/app/src/main/java/com/korancrew/emoneyinfo/nfc/AndroidStrings.kt)
+
+### 7.1 `UnifiedNfcReader`
+
+`UnifiedNfcReader` adalah orchestrator NFC aplikasi.
+
+Tanggung jawab:
+- mengecek apakah device support NFC
+- menyimpan `uiState` dalam `StateFlow`
+- menerima `Tag` dari `onNewIntent`
+- memilih reader yang sesuai berdasarkan teknologi kartu
+- mengubah hasil pembacaan menjadi `EmoneyUiState`
+- mengatur pesan UI seperti `tap card hint` dan `tap again hint`
+
+Reader yang didaftarkan saat ini:
+- `IsoDepCardRouter()`
+- `MifareClassicCardReader()`
+- `FelicaCardReader()`
+
+### 7.2 `CardReaders.kt`
+
+File ini berisi implementasi pembacaan kartu per keluarga teknologi dan per jenis kartu.
+
+Struktur utamanya:
+- `CardReader`
+- `IsoDepCardRouter`
+- `FelicaCardReader`
+- `MifareClassicCardReader`
+- object reader spesifik, seperti `BrizziReader`, `MandiriReader`, `FlazzReader`, `TapCashReader`, dan lainnya
+
+Alur umum:
+1. router menentukan teknologi kartu
+2. router memanggil reader spesifik
+3. reader mengirim command APDU atau FeliCa
+4. response di-parse menjadi saldo, nomor kartu, dan history
+5. hasil akhir dikembalikan sebagai `EmoneyUiState`
+
+### 7.3 `NfcUtils.kt`
+
+File ini berisi helper low-level:
+- `ApduResponse`
+- `transceiveApdu`
+- `transceiveSelect`
+- helper FeliCa read
+- helper hex, endian, format card number, parsing tanggal
+
+Ini adalah file utility inti untuk operasi byte-level dan APDU.
+
+### 7.4 `BrizziCrypto.kt`
+
+Khusus untuk flow Brizzi yang membutuhkan proses auth/crypto.
+
+File ini sebaiknya disentuh dengan hati-hati karena error kecil pada:
+- mode cipher
+- IV
+- padding
+- urutan challenge
+
+bisa membuat kartu gagal dibaca.
+
+## 8. Dukungan Kartu
+
+Kartu yang saat ini sudah menjadi target utama:
+- Brizzi
+- Flazz BCA
+- Mandiri e-Money
+- BNI TapCash
+- KMT
+- JackCard
+- MegaCash
+
+Catatan penting:
+- tidak semua kartu memakai flow yang sama
+- beberapa kartu memakai `IsoDep`
+- KMT memakai `NfcF`
+- ada fallback `MifareClassic` untuk kasus tertentu
+
+Untuk perubahan parser, validasi terbaik tetap lewat test pada kartu fisik nyata.
+
+## 9. Alur Scan NFC
+
+Secara sederhana:
+
+1. `MainActivity.onResume()` mengaktifkan foreground dispatch
+2. user menempelkan kartu
+3. Android mengirim `Intent` NFC ke activity yang sedang aktif
+4. `MainActivity.onNewIntent()` meneruskan intent ke `UnifiedNfcReader`
+5. `UnifiedNfcReader` memilih reader yang cocok
+6. reader membaca data kartu
+7. hasil scan dimasukkan ke `uiState`
+8. UI Compose otomatis recompose dan menampilkan saldo/history terbaru
+
+Setelah scan berhasil, `scanMessage` akan berubah lalu kembali ke hint scan ulang setelah 5 detik.
+
+## 10. Localization
+
+String resource:
+- [values/strings.xml](/Users/wirabasalamah/work/gitlab/EmoneyInfo-andro/app/src/main/res/values/strings.xml)
+- [values-id/strings.xml](/Users/wirabasalamah/work/gitlab/EmoneyInfo-andro/app/src/main/res/values-id/strings.xml)
+
+App mendukung:
+- Inggris
+- Indonesia
+
+Catatan:
+- bahasa UI mengikuti locale device
+- currency tetap `IDR`
+- beberapa pesan scan dari layer NFC juga dilokalisasi melalui `AndroidStrings`
+
+## 11. AdMob
+
+File utama:
+- [AdMobConfig.kt](/Users/wirabasalamah/work/gitlab/EmoneyInfo-andro/app/src/main/java/com/korancrew/emoneyinfo/ads/AdMobConfig.kt)
+- [AdMobBanner.kt](/Users/wirabasalamah/work/gitlab/EmoneyInfo-andro/app/src/main/java/com/korancrew/emoneyinfo/ui/components/AdMobBanner.kt)
+
+Penempatan saat ini:
+- banner di `Home`
+- banner di `History`
+- banner di `Settings`
+- interstitial sebelum export PDF
+
+Catatan implementasi:
+- `test device IDs` hanya diaktifkan pada `BuildConfig.DEBUG`
+- logging ads dibatasi ke debug build melalui `AppLog`
+
+## 12. Export PDF
+
+File utama:
+- [HistoryPdfExporter.kt](/Users/wirabasalamah/work/gitlab/EmoneyInfo-andro/app/src/main/java/com/korancrew/emoneyinfo/pdf/HistoryPdfExporter.kt)
+
+Fungsi utama:
+- menghasilkan PDF dari `EmoneyUiState`
+- menyertakan tipe kartu, saldo, nomor kartu, dan tabel transaksi
+- membuka chooser agar file bisa dibuka atau dibagikan
+
+Flow dari UI:
+1. user menekan `Export PDF`
+2. jika interstitial tersedia, iklan ditampilkan dulu
+3. setelah iklan selesai atau gagal tampil, PDF dibuat
+4. file dibuka lewat chooser
+
+## 13. Preference Lokal
+
+Saat ini preference utama yang dipakai:
+- `masked`
+
+Disimpan di:
+- `SharedPreferences("emoney_info_prefs")`
+
+Dipakai untuk:
+- menentukan apakah nomor kartu ditampilkan penuh atau dimasking
+
+Catatan:
+- key `masked` saat ini bernilai `true` ketika nomor kartu ditampilkan penuh
+- nama key ini tidak ideal secara semantik
+- kalau nanti ingin dirapikan, sebaiknya diganti menjadi key yang lebih jelas, misalnya `show_card_number`
+
+## 14. Logging dan Build Production
+
+File utama:
+- [AppLog.kt](/Users/wirabasalamah/work/gitlab/EmoneyInfo-andro/app/src/main/java/com/korancrew/emoneyinfo/util/AppLog.kt)
+- [app/build.gradle.kts](/Users/wirabasalamah/work/gitlab/EmoneyInfo-andro/app/build.gradle.kts)
+
+Prinsip saat ini:
+- log sensitif hanya aktif di debug build
+- release build memakai:
+  - `minifyEnabled = true`
+  - `shrinkResources = true`
+
+Ini penting karena flow NFC dan ads punya banyak data internal yang tidak perlu muncul di production log.
+
+## 15. File Yang Paling Sering Diedit
+
+Kalau ingin ubah tampilan:
+- `/ui/screens`
+- `/ui/theme`
+- `/res/values`
+
+Kalau ingin ubah parser kartu:
+- `/nfc/CardReaders.kt`
+- `/nfc/NfcUtils.kt`
+- `/nfc/BrizziCrypto.kt`
+
+Kalau ingin ubah model dan formatting:
+- `/data/Models.kt`
+
+Kalau ingin ubah ads:
+- `/ads/AdMobConfig.kt`
+- `/ui/components/AdMobBanner.kt`
+
+Kalau ingin ubah PDF:
+- `/pdf/HistoryPdfExporter.kt`
+
+## 16. Risiko dan Catatan Maintenance
+
+Beberapa area sensitif:
+
+- parser NFC
+  Perubahan kecil bisa memutus pembacaan kartu tertentu.
+
+- flow Brizzi
+  Paling sensitif karena ada auth dan kriptografi.
+
+- formatting UI berdasarkan `locationName`
+  KMT memakai lokasi valid, tapi kartu lain tidak selalu punya mapping lokasi yang berguna.
+
+- preference `masked`
+  Namanya membingungkan dan bisa memicu bug kalau dibaca tanpa konteks.
+
+- ads production
+  Pastikan testing device ID tidak dipakai untuk release path, dan lakukan uji di device nyata.
+
+## 17. Saran Pengembangan Selanjutnya
+
+Beberapa perbaikan yang layak dipertimbangkan:
+
+- pecah `CardReaders.kt` menjadi beberapa file per kartu agar lebih mudah dirawat
+- ganti `SharedPreferences` sederhana ke wrapper preference yang lebih eksplisit
+- buat test parser terpisah untuk data response yang sudah diketahui
+- tambahkan dokumentasi mapping kartu dan APDU per provider
+- rapikan naming key `masked`
+
+## 18. Ringkasan Cepat
+
+Kalau hanya ingin memahami project dengan cepat, mulai dari file ini:
+
+1. [MainActivity.kt](/Users/wirabasalamah/work/gitlab/EmoneyInfo-andro/app/src/main/java/com/korancrew/emoneyinfo/MainActivity.kt)
+2. [EmoneyInfoApp.kt](/Users/wirabasalamah/work/gitlab/EmoneyInfo-andro/app/src/main/java/com/korancrew/emoneyinfo/ui/EmoneyInfoApp.kt)
+3. [Models.kt](/Users/wirabasalamah/work/gitlab/EmoneyInfo-andro/app/src/main/java/com/korancrew/emoneyinfo/data/Models.kt)
+4. [UnifiedNfcReader.kt](/Users/wirabasalamah/work/gitlab/EmoneyInfo-andro/app/src/main/java/com/korancrew/emoneyinfo/nfc/UnifiedNfcReader.kt)
+5. [CardReaders.kt](/Users/wirabasalamah/work/gitlab/EmoneyInfo-andro/app/src/main/java/com/korancrew/emoneyinfo/nfc/CardReaders.kt)
+6. [HistoryScreen.kt](/Users/wirabasalamah/work/gitlab/EmoneyInfo-andro/app/src/main/java/com/korancrew/emoneyinfo/ui/screens/HistoryScreen.kt)
+7. [HistoryPdfExporter.kt](/Users/wirabasalamah/work/gitlab/EmoneyInfo-andro/app/src/main/java/com/korancrew/emoneyinfo/pdf/HistoryPdfExporter.kt)
+
+Dengan urutan itu, sebagian besar arsitektur project sudah akan terlihat.