# Terapisku - Technical & Business Documentation

> Dokumentasi ini digenerate secara otomatis (reverse engineered) berdasarkan implementasi aktual di dalam source code.

## 1. System Overview
Terapisku adalah aplikasi platform pemesanan layanan terapi/kesehatan profesional. Aplikasi ini menghubungkan antara konsumen (pemesan layanan) dan terapis/mitra (penyedia layanan). Aplikasi mendukung pemesanan layanan, manajemen profil, tracking order, manajemen alamat, manajemen dompet/keuangan, dan back-office (admin/superadmin).

## 2. Technology Stack
Berdasarkan analisis file `composer.json`, `package.json`, dan `.env`:
* **Framework Backend:** Laravel ^13.8 (PHP ^8.3)
* **Framework Frontend:** Laravel Blade, Vite, Tailwind CSS ^4.0.0
* **Database Utama:** PostgreSQL (`pgsql`)
* **Cache & Session & Queue:** Redis
* **Authentication Package:** Laravel Default (Auth) & Laravel Socialite (^5.29) untuk Google Login.
* **Email System:** SMTP (menggunakan akun Gmail)
* **ID Obfuscation:** Hashids (`hashids/hashids` ^5.0) digunakan untuk mengenkripsi ID di URL (contoh: `$service->secure_id`).

<!-- INSERT_NEXT -->

## 3. Database Architecture & Models
Aplikasi Terapisku memiliki beberapa entitas utama di dalam database:

### Tabel dan Model Utama:
* **Users** (`User.php`): Menyimpan data baik untuk Konsumen maupun Mitra Terapis.
  - Terdapat field spesifik mitra (KYC) seperti `nik`, `ktp_image`, `selfie_image`, `bank_account_number`, `bank_account_name`.
  - Terdapat kolom `wallet_balance` untuk menyimpan saldo.
  - Memiliki trait `SoftDeletes` dan `Hashidable` untuk menyembunyikan ID.
* **UserAddresses** (`UserAddress.php`): Menyimpan multi-alamat pengguna lengkap dengan lat/long (`latitude`, `longitude`) dan status alamat utama (`is_default`).
* **Services** (`Service.php`) & **ServiceCategories** (`ServiceCategory.php`): Menyimpan data layanan, memiliki relasi many-to-one ke Kategori. Service menyimpan field JSON `durations` (menyimpan array relasi waktu durasi dan harga).
* **Orders** (`Order.php`): Relasi transaksi antara `user_id` (Konsumen), `mitra_id` (Terapis), dan `service_id`. 
  - Menyimpan snapshot dari `total_price` dan `duration`.
* **WalletTransactions** (`WalletTransaction.php`): Menyimpan histori mutasi dompet `in` (masuk) dan `out` (keluar).
* **Withdrawals** (`Withdrawal.php`): Pencatatan request tarik dana Mitra Terapis ke rekening Bank.
* **AppNotifications** (`AppNotification.php`): Menyimpan notifikasi dalam aplikasi pengguna.
* **HeroSettings, HowItWorks, Promotions, Ratings**: Konten pendukung untuk halaman depan (Landing Page).

## 4. Flow Pemesanan (Order Flow) & Business Rules
Proses pemesanan layanan terapi melewati 4 tahapan di controller (berdasarkan `LandingController`):
1. **Pilih Layanan & Durasi (`orderStep2` / `orderStep3`)**: 
   - Konsumen memilih layanan.
   - Durasi diekstrak dari atribut JSON `durations` milik model `Service`. Fallback ke durasi pertama bila tidak valid.
2. **Lokasi & Detail Penjadwalan (`orderStep4`)**: Menangani konfirmasi harga sebelum checkout.
3. **Status Pesanan**: Order memiliki tracking status. 
4. **Validasi Tarik Dana (Withdrawal)**: 
   - Minimal penarikan dana adalah Rp50.000.
   - Saldo dompet (wallet_balance) harus lebih besar dari nominal tarik dana.
   - Melakukan Database Transaction untuk: (1) Mengurangi saldo user, (2) Mencatat mutasi keluar (`WalletTransaction`), dan (3) Membuat pengajuan `Withdrawal` dengan status `pending`.



## 5. Web Routes & Sub-Domain Architecture
Aplikasi Terapisku secara arsitektur menggunakan **Subdomain Routing** pada file `routes/web.php`. Routing dibagi ke dalam tiga domain utama:

1. **Admin Panel (`manage.terapisku.com`)**:
   - URL login sengaja disamarkan (disguised security route) menjadi `/gcp-managed-airflow-migrations`.
   - Menggunakan middleware `auth` dan kustom middleware `admin`.
   - Modul yang dicakup: Dashboard, Live Pesanan, Manajemen Mitra & Konsumen (Suspend/Unsuspend), Tarik Dana, Keuangan, Monitoring (API, Error), Konfigurasi sistem.
   - Superadmin (middleware `superadmin`): Akses penuh termasuk reset password admin lain, manajemen User, Hero settings, Services, Service Categories, Promotions.

2. **Mitra / Terapis Panel (`mitra.terapisku.com`)**:
   - Diperuntukkan bagi Terapis.
   - Fitur Auth: Login dengan OTP WhatsApp (`/login/otp`), Magic Link (`/go/{token}`).
   - Pendaftaran Mitra: Terdiri dari tahap Verifikasi Nomor HP (OTP) dan Submit Dokumen KYC (KTP, Selfie, Rekening Bank).
   - Menu Mitra: Order Bidding (`order-bid-mitra`), Riwayat Order, Wallet, Tarik Dana, Notifikasi, dan Profil.

3. **Consumer / Homepage (`terapisku.com`)**:
   - Diperuntukkan bagi Pelanggan.
   - Fitur Auth: Login/Daftar dengan OTP WhatsApp & integrasi Google Login (OAuth 2 - Socialite).
   - Fitur Konsumen: Pemilihan Layanan (`/services`), Pemesanan (Checkout 4 tahap), Manajemen Alamat multi-lokasi (Google Maps proxy terintegrasi), Manajemen Profil, dan histori pesanan.

## 6. Authentication & Roles
* **Authentication:** Menggunakan Laravel Session Base (guard `web`) standar yang divariasikan dengan OTP Verification flow (tidak hanya mengandalkan password). 
* **Role System:** Tidak menggunakan package eksternal (seperti Spatie). Mengandalkan kolom string `role` di tabel `users`.
  * `superadmin`: Developer / Root Admin.
  * `admin`: Operator sistem.
  * `mitra`: Penyedia Jasa/Terapis.
  * `konsumen`: Pengguna standar.
* **OTP & Magic Link:** Menggunakan session flow dengan OTP dinamis untuk proses login Mitra dan Konsumen.



## 7. Controllers & API Integration
1. **AdminPanelController**: Menghandle seluruh flow manajerial seperti melihat statistik pesanan, melihat Whatsapp log, mengelola mitra (approve KYC) dan konsumen (suspend), mengatur penarikan dana, serta mengatur fee dan konfigurasi utama aplikasi.
2. **LandingController**: Entry point untuk Consumer. Mengelola rendering layanan yang ditawarkan, menampilkan ulasan (rating), serta flow pendaftaran dan pesanan mitra dan konsumen.
3. **MapProxyController**: Mengamankan API Key dan menyediakan proxy pencarian lokasi (Autocomplete) dengan melempar request ke OSM (OpenStreetMap Nominatim API) yang dilimit khusus `countrycodes: id` (Indonesia). Proxy ini dicatat hit_count-nya dalam tabel `api_request_logs`.

## 8. Integrasi Layanan Eksternal (Third-Party)
1. **WhatsApp API (Fonnte):** 
   - Digunakan untuk mengirim kode OTP dan notifikasi.
   - Fungsi helper `send_whatsapp()` di `app/Support/helpers.php` mengatur logika konversi prefix nomor telepon (mengubah awalan 0 menjadi 62).
   - Log sukses/gagal disimpan di tabel `whatsapp_logs`.
2. **Google Maps / OpenStreetMap:**
   - Digunakan untuk mapping lokasi pencarian alamat (Autcomplete Proxy) via OSM Nominatim (`MapProxyController`).
3. **Google Social Login (OAuth 2.0):**
   - Diimplementasikan melalui package Laravel Socialite di `GoogleAuthController`.
4. **Email SMTP (Google):**
   - Menggunakan akun Gmail (`autofollowonline@gmail.com`) untuk notifikasi berbasis email.

## 9. Security, Edge Cases & Error Handling
1. **ID Obfuscation:** 
   - Terapisku tidak pernah memunculkan Primary Key (`id`) ke publik, khususnya pada tabel `Service`. Trait `Hashidable` (menggunakan Hashids) digunakan untuk mengenkripsi ID, misalnya `$service->secure_id`. Hal ini mencegah celah IDOR (Insecure Direct Object Reference).
2. **Disguised Security Route:**
   - Halaman login Administrator disembunyikan di rute `/gcp-managed-airflow-migrations`. Rute standar (`/login` atau `/admin/login`) tidak ada/dialihkan, meningkatkan keamanan dari brute force scanner.
3. **Validasi Penarikan Dana (Race Condition Prevention):**
   - Pada metode `processTarikDanaMitra`, seluruh proses pemotongan saldo dan pembuatan histori dijalankan di dalam `DB::transaction()` untuk memastikan integritas data.
4. **Penanganan Alamat Default (Edge Case):**
   - Saat sebuah alamat `default` dihapus, sistem (`ProfileController`) secara otomatis mencari alamat lain yang tersisa dari pengguna tersebut dan menjadikannya sebagai alamat default baru, sehingga konsumen tidak pernah memiliki state "tanpa alamat default" jika mereka memiliki minimal satu alamat.

## 10. Glossary / Kosakata Sistem
- **Konsumen:** Pengguna platform yang memesan layanan terapi.
- **Mitra:** Terapis profesional yang menyediakan layanan, perlu lolos KYC.
- **Operator / Admin:** Staff back-office yang bertugas mengelola operasional harian.
- **Superadmin:** Developer atau Root Access yang memegang seluruh kendali konfigurasi.
- **KYC (Know Your Customer):** Proses verifikasi Mitra dengan upload KTP, Foto Selfie, dan data bank.
- **GMV (Gross Merchandise Value):** Total nilai transaksi kotor yang terjadi dalam sehari.
- **Withdrawal:** Penarikan saldo dompet dari aplikasi ke rekening bank lokal Mitra.