Emoney-Info---Android/docs/CODE_DOCUMENTATION.md

# 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.