Dokumentasi Aplikasi Tambang Go

v1.0.0 Bahasa: Indonesia | Dibuat: Juli 2026

🏪

1. Gambaran Umum Aplikasi

Tambang Go adalah platform e-commerce berbasis mobile (Android/iOS) yang dirancang khusus untuk jual-beli produk tali tambang. Aplikasi ini memungkinkan tiga jenis pengguna — Pembeli, Penjual, dan Administrator — untuk berinteraksi dalam ekosistem perdagangan yang terintegrasi secara penuh.

Role Pengguna

30+

Layar Aplikasi

50+

Endpoint API

15+

Tabel Database

👤 Pembeli (Buyer)

Pengguna yang dapat menjelajahi katalog, menambahkan produk ke keranjang, melakukan pemesanan, dan mengelola riwayat transaksi. Mode tamu tersedia untuk menjelajahi tanpa login.

🏬 Penjual (Seller)

Pengguna yang dapat mengelola produk, menerima pesanan, memantau pendapatan, dan melakukan penarikan dana ke rekening bank.

🛡️ Administrator

Mengelola seluruh platform melalui panel web browser (bukan aplikasi mobile). Bertugas mengkonfirmasi pembayaran, memproses penarikan dana, mengelola pengguna, kategori, dan pengaturan sistem.

📌 Catatan Penting: Meskipun nama proyeknya adalah "Tambang Go", backend yang digunakan adalah Laravel (PHP), bukan bahasa pemrograman Go. Nama "Go" kemungkinan merupakan nama merek/brand aplikasi.

⚙️

2. Teknologi yang Digunakan

Apa itu Stack Teknologi?

Stack teknologi (tech stack) adalah kumpulan teknologi/bahasa/framework yang digunakan untuk membangun aplikasi. Tambang Go menggunakan stack Flutter + Laravel + MySQL:

Flutter — framework Google untuk membangun UI aplikasi mobile (Android/iOS) dengan satu codebase Dart
Laravel — framework PHP untuk membangun backend REST API dan panel admin web
MySQL — sistem database relasional untuk menyimpan data permanen

Pemilihan stack ini umum untuk aplikasi mobile + backend karena Flutter efisien untuk UI cross-platform, Laravel cepat untuk API, dan MySQL stabil untuk data transaksional e-commerce.

📱 Frontend (Mobile App)

Teknologi	Versi	Kegunaan
Flutter	3.x	Framework UI multi-platform
Dart SDK	≥ 3.2.6	Bahasa pemrograman
Provider	^6.1.1	State Management
HTTP	^1.1.0	Komunikasi dengan API
flutter_secure_storage	^9.0.0	Penyimpanan token aman
google_sign_in	^6.2.2	Login dengan Google
image_picker	^1.0.7	Upload foto produk/profil
cached_network_image	^3.4.1	Cache gambar dari internet
intl	^0.20.2	Format tanggal & mata uang (id_ID)

🖥️ Backend (REST API)

Teknologi	Versi	Kegunaan
Laravel	10.x	Framework PHP REST API
PHP	≥ 8.1	Bahasa pemrograman backend
MySQL	8.x	Database relasional
Laravel Sanctum	^3.2	Autentikasi Bearer Token
Guzzle HTTP	^7.2	Validasi token Google OAuth
Laravel Blade	built-in	Template HTML panel admin web
Vite	latest	Build asset frontend panel admin

🗂️ Platform Target

Platform	Status	Catatan
Android	✅ Utama	Target utama pengembangan, ada `google-services.json`
iOS	✅ Tersedia	Konfigurasi tersedia, memerlukan Xcode
Web	⚠️ Tersedia	Folder web tersedia, belum dioptimalkan
Windows / Linux / macOS	⚠️ Tersedia	Folder desktop tersedia, belum dioptimalkan
Panel Admin Web	✅ Browser	Diakses melalui browser di `/admin/login`

🏗️

3. Arsitektur Sistem

Sistem Tambang Go menggunakan arsitektur Client-Server dengan pemisahan yang jelas antara frontend (Flutter) dan backend (Laravel). Komunikasi data dilakukan melalui REST API berbasis JSON dengan autentikasi Bearer Token.

Apa itu Arsitektur Client-Server?

Arsitektur adalah cara komponen-komponen sistem diorganisir dan saling berkomunikasi. Pada arsitektur Client-Server, aplikasi dibagi menjadi dua pihak:

Client (Klien) — aplikasi yang dijalankan pengguna di perangkatnya (aplikasi Flutter di HP). Client bertugas menampilkan UI dan menerima input pengguna.
Server (Peladen) — program yang berjalan di komputer/server (Laravel). Server memproses logika bisnis, mengakses database, dan mengembalikan data ke client.

Pemisahan ini memungkinkan satu backend melayani banyak client (Android, iOS, web admin) sekaligus. Data disimpan terpusat di server sehingga konsisten untuk semua pengguna.

Analogi: Client seperti pelanggan di restoran (memesan via menu/app), server seperti dapur (memproses pesanan), dan database seperti gudang bahan (menyimpan data produk, pesanan, user).

📱 Mobile App

Flutter (Dart)
Android / iOS

⇄

⚡ REST API

Laravel 10
PHP 8.1+

⇄

🗄️ Database

MySQL 8
tambang_go

Panel Admin Web diakses melalui browser secara terpisah dari aplikasi mobile. Panel web menggunakan session cookie Laravel (bukan Bearer Token).

Pola Arsitektur Flutter

📁 Entry point aplikasi: frontend/lib/main.dart — mendaftarkan 5 Provider via MultiProvider dan menampilkan SplashScreen.

// Alur data dalam aplikasi Flutter:
Screen (Widget UI)
  → memanggil → Provider (State Management / ChangeNotifier)
    → memanggil → Service (Business Logic Layer)
      → memanggil → ApiService (HTTP Client Layer)
        → request ke → Laravel API (REST Backend)
          → response → JSON diparse ke → Model (Data Transfer Object)
            → dikembalikan ke → Provider → Screen diperbarui (notifyListeners)

Struktur Folder Proyek

tambang_go/
├── frontend/                    # Aplikasi Flutter
│   ├── lib/
│   │   ├── config/              # api_config.dart, app_assets.dart
│   │   ├── models/              # DTO: User, Product, Order, Cart, dll.
│   │   ├── providers/           # AuthProvider, ProductProvider, OrderProvider, dll.
│   │   ├── screens/             # Layar UI (auth/, buyer/, seller/, admin/, profile/)
│   │   ├── services/            # HTTP API clients
│   │   ├── utils/               # auth_guard, shipping calculator, dll.
│   │   └── widgets/             # Komponen reusable
│   └── pubspec.yaml
│
├── backend-laravel/             # Backend Laravel
│   ├── app/
│   │   ├── Http/Controllers/Api/   # Controller API untuk Flutter
│   │   ├── Http/Controllers/Web/Admin/ # Controller panel admin web
│   │   ├── Http/Middleware/        # Guard role: buyer, seller, admin
│   │   ├── Models/                 # Eloquent ORM models
│   │   └── Support/               # Business logic services
│   ├── database/
│   │   ├── migrations/            # 25 file migrasi database
│   │   └── seeders/               # Data awal (admin, kategori, produk)
│   ├── routes/
│   │   ├── api.php                # Semua route REST API
│   │   └── web.php                # Route panel admin web
│   └── resources/views/admin/    # Template Blade panel admin
│
└── docs/                        # Dokumentasi tambahan

👤

4. Fitur Pembeli (Buyer)

Pembeli adalah pengguna utama aplikasi mobile. Terdapat dua mode akses: Mode Tamu (tanpa login) dan Mode Login dengan akun terautentikasi.

🌐 Mode Tamu (Guest)

Menjelajahi katalog produk tali tambang
Melihat detail produk (gambar, spesifikasi, harga)
Mencari produk berdasarkan kata kunci
Memfilter produk berdasarkan kategori
Melihat banner promosi di halaman utama
Prompt login otomatis saat mencoba beli/keranjang

🔐 Mode Terautentikasi

Semua fitur mode tamu
Menambahkan produk ke keranjang belanja
Melakukan proses checkout pesanan
Melihat riwayat dan detail pesanan
Mengelola profil dan foto
Mengakses dompet dan penarikan dana

Fitur Detail Pembeli

🛍️ Katalog Produk

Tampilan daftar produk dengan gambar, nama, harga, dan toko
Banner/slider promosi di bagian atas halaman
Pencarian real-time berdasarkan nama produk
Filter berdasarkan kategori (Tali Nilon, Tali Baja, dll.)
Pagination (infinite scroll atau pagination manual)
Detail produk: multi-gambar, diameter, material, berat, satuan (meter/roll/kg/pcs)

Kode: frontend/lib/screens/buyer/buyer_home_screen.dart (BuyerProductListPage) → product_detail_screen.dart | Provider: frontend/lib/providers/product_provider.dart | API: backend-laravel/app/Http/Controllers/Api/ProductController.php

🛒 Keranjang Belanja

Menambahkan produk dari toko yang berbeda ke satu keranjang
Mengubah jumlah item (increment/decrement)
Menghapus item dari keranjang
Preview ongkos kirim per toko (sebelum checkout)
Indikator jumlah item di ikon keranjang

Kode: frontend/lib/screens/buyer/cart_screen.dart | Provider: frontend/lib/providers/cart_provider.dart | Service: frontend/lib/services/cart_service.dart | API: backend-laravel/app/Http/Controllers/Api/CartController.php

💳 Checkout & Pembayaran

Metode Pengiriman: Kurir (bayar ongkir) atau Ambil di Toko (pickup gratis)
Metode Pembayaran: Transfer Bank atau COD (Bayar di Tempat)
Tampilkan rekening platform untuk transfer manual
Ringkasan harga: subtotal + pajak + komisi + ongkir = total
Pengecekan mode maintenance sebelum checkout

Kode: frontend/lib/screens/buyer/checkout_screen.dart, order_success_screen.dart | Widget: frontend/lib/widgets/order_price_breakdown.dart, platform_transfer_instructions.dart | API: backend-laravel/app/Http/Controllers/Api/OrderController.php method store()

📦 Manajemen Pesanan

Riwayat pesanan dengan filter status
Detail pesanan lengkap (item, harga, status, info pengiriman)
Upload bukti pembayaran transfer (foto)
Konfirmasi penerimaan barang + upload bukti penerimaan
Pembatalan pesanan (hanya status tertentu)
Statistik ringkasan pembelian (total pesanan, pengeluaran, dll.)

Kode: frontend/lib/screens/buyer/order_history_screen.dart, order_detail_screen.dart, buyer_dashboard_screen.dart | Provider: frontend/lib/providers/order_provider.dart | API: backend-laravel/app/Http/Controllers/Api/OrderController.php

💰 Dompet Pembeli

Saldo dompet dari refund pesanan yang dibatalkan
Riwayat transaksi dompet (kredit/debit)
Menambahkan rekening bank untuk pencairan
Pengajuan penarikan saldo ke rekening bank

📁 Lokasi kode fitur dompet pembeli:

UI frontend/lib/screens/buyer/buyer_wallet_screen.dart
UI frontend/lib/screens/buyer/buyer_payment_account_screen.dart
Widget frontend/lib/widgets/buyer_wallet_chip.dart
Service frontend/lib/services/buyer_withdrawal_service.dart
API backend-laravel/app/Http/Controllers/Api/BuyerWithdrawalController.php
Logic backend-laravel/app/Support/BuyerWalletService.php
Model backend-laravel/app/Models/WalletTransaction.php

📁 Ringkasan lokasi kode seluruh fitur pembeli: Lihat bagian 24. Implementasi Kode per Fitur untuk penjelasan alur kode lengkap dari UI → Provider → Service → API.

🏬

5. Fitur Penjual (Seller)

Penjual adalah pengguna yang memiliki toko di platform Tambang Go. Pembeli dapat mengupgrade akunnya menjadi penjual langsung dari halaman profil.

📊 Dashboard Penjual

Ringkasan total produk aktif dan stok tersisa
Total nilai inventori (stok × harga)
Ringkasan pendapatan (setelah komisi platform)
Shortcut cepat ke manajemen produk, pesanan, dan penarikan

📦 Manajemen Produk

Daftar semua produk milik toko dengan status dan stok
Tambah produk baru dengan multi-foto, deskripsi, dan spesifikasi
Edit produk (nama, harga, deskripsi, gambar, spesifikasi)
Update stok secara terpisah (tanpa harus edit seluruh produk)
Nonaktifkan/aktifkan tampilan produk
Hapus produk
Statistik produk: jumlah aktif, stok rendah, nilai total

🚚 Manajemen Pesanan

Daftar pesanan masuk dengan filter status dan tanggal
Detail setiap pesanan (item, pembeli, metode pengiriman)
Update status pesanan: Konfirmasi → Proses → Kirim
Informasi alamat pengiriman pembeli

💰 Keuangan Penjual

Rekening bank untuk pencairan dana (CRUD)
Saldo pendapatan bersih yang dapat dicairkan
Riwayat pengajuan penarikan dana
Pengajuan penarikan baru ke rekening yang terdaftar
Laporan keuangan per periode

💡 Upgrade ke Penjual: Pengguna dengan role Pembeli dapat mengupgrade menjadi Penjual melalui halaman Profil → tombol "Jadi Penjual". Kode: frontend/lib/screens/profile/profile_screen.dart memanggil frontend/lib/providers/auth_provider.dart → method updateRole() → endpoint PUT /api/profile/role di backend-laravel/app/Http/Controllers/Api/ProfileController.php.

📁 Ringkasan lokasi kode fitur penjual:

Shell frontend/lib/screens/seller/seller_home_screen.dart
Dashboard frontend/lib/screens/seller/seller_dashboard_screen.dart
Produk frontend/lib/screens/seller/add_product_screen.dart, edit_product_screen.dart
Pesanan frontend/lib/screens/seller/seller_order_screen.dart
Keuangan frontend/lib/screens/seller/withdrawal_request_screen.dart, payment_account_screen.dart
API Produk backend-laravel/app/Http/Controllers/Api/ProductController.php
API Penarikan backend-laravel/app/Http/Controllers/Api/SellerWithdrawalController.php
Pendapatan backend-laravel/app/Support/SellerEarningsCalculator.php

🛡️

6. Fitur Administrator

⚠️ Admin Tidak Bisa Login di Mobile! Akun administrator hanya dapat diakses melalui panel web browser di alamat /admin/login. Jika admin mencoba login di aplikasi mobile, sistem akan menolak dan menampilkan layar "Admin Access Denied".

👥 Manajemen Pengguna

Melihat dan mencari semua pengguna terdaftar
Detail profil setiap pengguna (role, status, kontak)
Membuat akun pengguna baru
Mengubah data dan role pengguna
Menonaktifkan/menghapus akun pengguna

🏷️ Manajemen Kategori

Membuat kategori produk baru (misal: Tali Nilon, Tali Baja, Tali Rami)
Edit dan hapus kategori
Upload gambar kategori
Aktifkan/nonaktifkan kategori

📋 Manajemen Pesanan

Melihat semua pesanan dari seluruh penjual
Filter pesanan berdasarkan status dan tanggal
Konfirmasi pembayaran transfer (setelah memeriksa bukti bayar pembeli)
Mengubah status pesanan secara manual

💸 Manajemen Penarikan Dana

Daftar pengajuan penarikan dari penjual (Seller Withdrawals)
Daftar pengajuan penarikan dari pembeli (Buyer Withdrawals)
Approve atau tolak pengajuan penarikan dengan catatan
Riwayat lengkap semua transaksi penarikan

⚙️ Pengaturan Platform

Persentase komisi platform dari setiap transaksi
Persentase pajak (opsional)
Biaya ongkos kirim kurir (per toko)
Nama dan alamat toko untuk pickup
Rekening bank platform (untuk pembayaran transfer)
Jumlah minimum penarikan dana
Aktifkan/nonaktifkan mode maintenance

🖼️ Banner Promosi

Upload banner gambar untuk slider di halaman katalog pembeli
Mengelola (hapus) banner yang ada

📈 Laporan Pendapatan

Laporan pendapatan platform (total komisi yang diterima)
Laporan pendapatan penjual (per penjual)

📁 Lokasi kode fitur admin (panel web browser):

Routes backend-laravel/routes/web.php — prefix /admin/*
Login backend-laravel/app/Http/Controllers/Web/Admin/AuthController.php
Dashboard backend-laravel/app/Http/Controllers/Web/Admin/DashboardController.php
User backend-laravel/app/Http/Controllers/Web/Admin/UserController.php
Pesanan backend-laravel/app/Http/Controllers/Web/Admin/OrderController.php
Penarikan backend-laravel/app/Http/Controllers/Web/Admin/WithdrawalController.php, BuyerWithdrawalController.php
Pengaturan backend-laravel/app/Http/Controllers/Web/Admin/SettingsController.php
Middleware backend-laravel/app/Http/Middleware/IsWebAdmin.php
Blokir Mobile frontend/lib/screens/auth/admin_access_denied_screen.dart

📱

7. Layar Aplikasi Flutter

Aplikasi menggunakan MaterialPageRoute untuk navigasi antar layar (push/pop). Setiap role memiliki halaman utama dengan Bottom Navigation Bar berisi 4 tab. Semua path file relatif terhadap frontend/lib/screens/.

📁 Lokasi kode navigasi & routing:

frontend/lib/main.dart — SplashScreen memuat auth + banner, lalu navigasi ke HomeScreen
frontend/lib/screens/home_screen.dart — router berdasarkan role (Consumer<AuthProvider>)
frontend/lib/screens/buyer/buyer_home_screen.dart — bottom nav pembeli (4 tab)
frontend/lib/screens/seller/seller_home_screen.dart — bottom nav penjual (4 tab)
frontend/lib/utils/auth_guard.dart — proteksi aksi yang memerlukan login

🔑 Layar Autentikasi

File	Nama Layar	Deskripsi
`main.dart → SplashScreen`	Layar Splash	Ditampilkan saat aplikasi pertama kali dibuka. Memuat status autentikasi dan prefetch data banner, lalu redirect ke layar yang sesuai.
`home_screen.dart`	Home Router	Layar pengarah yang menentukan destinasi berdasarkan role pengguna: buyer → BuyerHomeScreen, seller → SellerHomeScreen, admin → AdminAccessDeniedScreen, tamu → BuyerHomeScreen.
`auth/login_screen.dart`	Login	Form login dengan email/password dan tombol Login dengan Google. Validasi input sebelum mengirim request.
`auth/register_screen.dart`	Registrasi	Form pendaftaran akun baru. Pengguna dapat memilih role awal: Pembeli atau Penjual.
`auth/admin_access_denied_screen.dart`	Admin Ditolak	Layar informasi bahwa admin tidak dapat login di aplikasi mobile. Menampilkan instruksi untuk menggunakan panel web.

👤 Layar Pembeli (Buyer)

File	Nama Layar	Tab	Deskripsi
`buyer/buyer_home_screen.dart`	Home Pembeli	Bottom Nav	Container utama dengan 4 tab: Katalog, Pesanan, Dashboard, Profil.
`buyer/product_detail_screen.dart`	Detail Produk	—	Tampilan lengkap satu produk: galeri foto carousel, nama, harga, stok, spesifikasi (diameter, material, berat, satuan), deskripsi, dan tombol Tambah ke Keranjang.
`buyer/cart_screen.dart`	Keranjang Belanja	—	Daftar semua item di keranjang, dikelompokkan per toko. Edit jumlah, hapus item, preview ongkir, dan tombol Checkout.
`buyer/checkout_screen.dart`	Checkout	—	Pilih metode pengiriman (kurir/pickup) dan metode pembayaran (transfer/COD). Tampilkan rincian harga dan rekening tujuan transfer.
`buyer/order_success_screen.dart`	Pesanan Berhasil	—	Konfirmasi pesanan sukses dengan nomor pesanan dan instruksi pembayaran (untuk transfer).
`buyer/order_history_screen.dart`	Riwayat Pesanan	Tab 2	Daftar semua pesanan dengan filter status. Bisa tap untuk melihat detail.
`buyer/order_detail_screen.dart`	Detail Pesanan	—	Informasi lengkap pesanan: item, harga, status, metode bayar/kirim, dan aksi (upload bukti bayar, konfirmasi terima, batalkan).
`buyer/buyer_dashboard_screen.dart`	Dashboard Statistik	Tab 3	Statistik ringkasan belanja: total pesanan, total pengeluaran, jumlah per status pesanan.
`buyer/buyer_wallet_screen.dart`	Dompet Pembeli	—	Saldo dompet dari refund, riwayat transaksi dompet, dan aksi penarikan saldo.
`buyer/buyer_payment_account_screen.dart`	Rekening Bank Pembeli	—	Daftar rekening bank yang terdaftar untuk pencairan saldo dompet. CRUD rekening.

🏬 Layar Penjual (Seller)

File	Nama Layar	Tab	Deskripsi
`seller/seller_home_screen.dart`	Home Penjual	Bottom Nav	Container utama penjual dengan 4 tab: Dashboard, Produk, Pesanan, Profil.
`seller/seller_dashboard_screen.dart`	Dashboard Penjual	Tab 1	Ringkasan KPI toko: total produk, stok, nilai inventori, pendapatan. Tombol shortcut ke fitur utama.
`seller/add_product_screen.dart`	Tambah Produk	—	Form lengkap untuk menambahkan produk baru: nama, kategori, harga, stok, deskripsi, spesifikasi (diameter/material/berat/satuan), upload multi-foto.
`seller/edit_product_screen.dart`	Edit Produk	—	Form edit produk yang sudah ada. Data terisi otomatis dari API.
`seller/seller_order_screen.dart`	Pesanan Masuk	Tab 3	Daftar pesanan yang mengandung produk milik toko ini. Filter berdasarkan status dan rentang tanggal.
`seller/payment_account_screen.dart`	Rekening Penjual	—	Manajemen rekening bank penjual untuk pencairan pendapatan.
`seller/withdrawal_request_screen.dart`	Penarikan Dana	—	Form pengajuan penarikan pendapatan ke rekening yang terdaftar. Tampilkan saldo yang tersedia.
`financial_report_screen.dart`	Laporan Keuangan	—	Laporan pendapatan penjual per periode waktu.

👤 Layar Profil (Semua Role)

File	Nama Layar	Deskripsi
`profile/profile_screen.dart`	Profil Utama	Tampilkan foto, nama, email, role. Menu: Edit Profil, Ganti Password, Jadi Penjual (khusus buyer), Dompet (khusus buyer), Logout.
`profile/edit_profile_screen.dart`	Edit Profil	Form untuk mengubah nama, nomor telepon, alamat, dan foto profil.
`profile/change_password_screen.dart`	Ganti Password	Form ganti password dengan verifikasi password lama.

🧩 Widget Reusable

File	Nama Widget	Fungsi
`widgets/guest_auth_prompt.dart`	Guest Auth Prompt	Overlay/dialog yang muncul saat tamu mencoba aksi yang memerlukan login (checkout, lihat pesanan, dll.)
`widgets/google_sign_in_button.dart`	Tombol Google Sign-In	Tombol login dengan Google yang sudah diformat sesuai panduan Google.
`widgets/buyer_wallet_chip.dart`	Chip Dompet	Komponen kecil yang menampilkan saldo dompet pembeli. Bisa di-tap untuk membuka layar dompet.
`widgets/product_banner_slider.dart`	Slider Banner	Carousel/slider otomatis yang menampilkan banner promosi dari API.
`widgets/order_price_breakdown.dart`	Rincian Harga	Komponen yang menampilkan breakdown harga pesanan: subtotal, pajak, komisi, ongkir, total.
`widgets/platform_transfer_instructions.dart`	Instruksi Transfer	Tampilkan rekening bank platform dan instruksi cara bayar via transfer.

🗺️

8. Navigasi & Routing

Apa itu Navigasi dan Routing?

Navigasi adalah cara pengguna berpindah antar layar (screen) dalam aplikasi — seperti membuka halaman detail produk dari katalog, atau kembali ke halaman sebelumnya.

Routing adalah aturan/logika yang menentukan layar mana yang ditampilkan berdasarkan kondisi tertentu. Di Tambang Go, routing utama berdasarkan role pengguna: tamu/buyer → BuyerHomeScreen, seller → SellerHomeScreen, admin → ditolak.

Flutter menggunakan Navigator dengan pola stack (tumpukan): layar baru di-push ke atas layar lama, tombol back pop layar teratas. Tidak ada URL seperti browser — navigasi berbasis stack widget.

Contoh: Dari katalog → tap produk → Navigator.push(ProductDetailScreen) → tap keranjang → Navigator.push(CartScreen). Tombol back pop satu per satu kembali.

Aplikasi menggunakan sistem navigasi Flutter bawaan (Navigator) dengan MaterialPageRoute. Tidak menggunakan package routing pihak ketiga seperti GoRouter atau AutoRoute. Implementasi routing role ada di frontend/lib/screens/home_screen.dart.

Alur Navigasi Utama

App Start

→

SplashScreen

→

HomeScreen (Router)

HomeScreen menentukan destinasi berdasarkan status login dan role:

Tidak Login

→

BuyerHomeScreen (Mode Tamu)

Role: buyer

→

BuyerHomeScreen

Role: seller

→

SellerHomeScreen

Role: admin

→

AdminAccessDeniedScreen

Auth Guard

File utils/auth_guard.dart digunakan untuk melindungi aksi yang memerlukan login. Jika pengguna belum login, GuestAuthPrompt ditampilkan sebagai overlay yang mengarahkan ke layar Login.

// Contoh penggunaan auth guard di screen
void onCheckoutPressed() {
  if (!authProvider.isLoggedIn) {
    // Tampilkan dialog prompt login
    showDialog(context: context, builder: (_) => GuestAuthPrompt());
    return;
  }
  // Lanjut ke checkout
  Navigator.push(context, MaterialPageRoute(
    builder: (_) => CheckoutScreen()
  ));
}

🔐

9. Sistem Autentikasi

Apa itu Autentikasi dan Otorisasi?

Autentikasi (Authentication) adalah proses memverifikasi identitas pengguna — menjawab pertanyaan "Siapa Anda?". Contoh: login dengan email/password atau Google Sign-In. Jika kredensial benar, sistem mengenali siapa pengguna tersebut.

Otorisasi (Authorization) adalah proses menentukan apa yang boleh dilakukan pengguna setelah teridentifikasi — menjawab pertanyaan "Apa yang Anda boleh akses?". Contoh: pembeli boleh checkout, penjual boleh kelola produk, admin boleh konfirmasi pembayaran.

Di Tambang Go, autentikasi mobile menggunakan Bearer Token (token Sanctum dari Laravel). Setiap request ke API membawa token ini sebagai "kartu identitas digital". Middleware backend (buyer, seller, admin) mengecek role sebelum mengizinkan akses endpoint tertentu.

Contoh di aplikasi: Saat pembeli login, AuthProvider menyimpan token. Saat menambah item ke keranjang, token dikirim ke server. Server memverifikasi token valid dan role = buyer sebelum memproses request.

Mekanisme Autentikasi API

Backend menggunakan Laravel Sanctum untuk menghasilkan Bearer Token. Token ini disimpan di sisi klien menggunakan flutter_secure_storage (penyimpanan aman berbasis Keystore/Keychain).

📁 Lokasi kode autentikasi:

UI Login frontend/lib/screens/auth/login_screen.dart
UI Register frontend/lib/screens/auth/register_screen.dart
State frontend/lib/providers/auth_provider.dart — method: login(), register(), loginWithGoogle(), logout()
Service frontend/lib/services/auth_service.dart
Google OAuth frontend/lib/services/google_auth_service.dart
HTTP + Token frontend/lib/services/api_service.dart — saveToken(), getToken()
Controller backend-laravel/app/Http/Controllers/Api/AuthController.php
Routes backend-laravel/routes/api.php — baris 35–37, 57–58
Model backend-laravel/app/Models/User.php

// Header yang disertakan di setiap request ter-autentikasi:
Authorization: Bearer {token}
Content-Type: application/json

// Kunci penyimpanan di klien:
auth_token  // Token Sanctum
user_data   // Data user (JSON)

Metode Login yang Tersedia

Metode	Endpoint	Request Body	Keterangan
Email/Password	POST `/api/login`	`{"email": "...", "password": "..."}`	Hanya untuk role buyer dan seller. Admin ditolak.
Registrasi	POST `/api/register`	`{"name", "email", "password", "role"}`	Role bisa `buyer` atau `seller`.
Google OAuth	POST `/api/auth/google`	`{"access_token": "google_token"}`	Menggunakan package `google_sign_in`. Token Google divalidasi oleh backend via Guzzle.

Response Autentikasi

{
  "user": {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com",
    "role": "buyer",
    "profile_photo": "/storage/photos/1.jpg"
  },
  "token": "1|abc123xyz...",
  "token_type": "Bearer"
}

Middleware Proteksi Route

Middleware	Pengecekan	Berlaku Pada
`auth:sanctum`	Token valid di tabel `personal_access_tokens`	Semua route proteksi
`buyer`	`user.role === 'buyer'`	Route `/buyer/*`
`seller`	`user.role === 'seller'`	Route `/seller/*`
`admin`	`user.role === 'admin'`	Route `/admin/*` (API)
`admin.web`	Session admin aktif	Route `/admin/*` (Web Panel)

🌐

10. API Endpoint Publik

Apa itu REST API?

API (Application Programming Interface) adalah antarmuka yang memungkinkan dua program saling berkomunikasi. REST (Representational State Transfer) adalah gaya arsitektur API yang populer, menggunakan protokol HTTP dengan operasi standar:

GET — mengambil/membaca data (contoh: daftar produk)
POST — membuat data baru (contoh: registrasi, checkout)
PUT — memperbarui data (contoh: edit profil)
DELETE — menghapus data (contoh: hapus item keranjang)

Data dipertukarkan dalam format JSON (teks terstruktur yang mudah dibaca mesin). Endpoint adalah URL spesifik, misalnya GET /api/products untuk mengambil daftar produk.

Analogi: REST API seperti menu restoran dengan nomor pesanan. Client memesan "GET /products" (lihat daftar makanan), server mengembalikan daftar dalam format JSON. Client tidak perlu tahu bagaimana dapur (backend) menyiapkan data — cukup tahu cara memesan.

Endpoint berikut dapat diakses tanpa autentikasi. Cocok untuk fitur browse produk mode tamu.

Base URL: http://10.0.2.2:8001/api (Android Emulator) — didefinisikan di frontend/lib/config/api_config.dart baris 6. Route backend: backend-laravel/routes/api.php.

Method	Endpoint	Fungsi	Query Parameter
POST	`/register`	Daftar akun baru	—
POST	`/login`	Login email & password	—
POST	`/auth/google`	Login dengan Google	—
GET	`/products`	Daftar produk (katalog)	`search`, `category_id`, `page`
GET	`/products/{id}`	Detail satu produk	—
GET	`/categories`	Daftar semua kategori	—
GET	`/categories/{id}`	Detail satu kategori	—
GET	`/settings/storefront`	Data banner slider & info toko	—

Contoh Response: GET /products

{
  "data": [
    {
      "id": 1,
      "name": "Tali Nilon 10mm",
      "price": 15000,
      "stock": 500,
      "unit": "meter",
      "diameter": "10mm",
      "material": "Nilon",
      "image": "/storage/products/1.jpg",
      "seller": { "id": 2, "name": "Toko Tambang Jaya" },
      "category": { "id": 1, "name": "Tali Nilon" }
    }
  ],
  "meta": { "current_page": 1, "total": 45, "per_page": 15 }
}

👤

11. API Endpoint Pembeli

🔒 Endpoint Umum (Semua Role Terautentikasi)

Method	Endpoint	Fungsi
POST	`/logout`	Hapus token & logout
GET	`/me`	Data user yang sedang login
GET	`/profile`	Tampilkan profil lengkap
PUT	`/profile`	Update data profil (nama, telepon, alamat)
PUT	`/profile/role`	Upgrade role dari buyer ke seller
PUT	`/profile/password`	Ganti password
POST	`/profile/photo`	Upload foto profil (multipart/form-data)
GET	`/settings/checkout`	Pengaturan checkout: pajak, ongkir, mode maintenance

🛒 Keranjang Belanja (`/cart`)

Method	Endpoint	Fungsi	Request Body
GET	`/cart`	Ambil isi keranjang + info lokasi pickup + preview ongkir	—
POST	`/cart`	Tambah item ke keranjang	`{"product_id": 1, "quantity": 2}`
PUT	`/cart/{id}`	Update jumlah item	`{"quantity": 3}`
DELETE	`/cart/{id}`	Hapus satu item	—
DELETE	`/cart`	Kosongkan seluruh keranjang	—
GET	`/cart/count`	Jumlah total item di keranjang	—

📦 Pesanan (`/orders`)

Method	Endpoint	Fungsi	Request/Query
GET	`/orders`	Daftar pesanan pembeli	Query: `status`
GET	`/orders/statistics`	Statistik ringkasan pesanan	—
POST	`/orders`	Buat pesanan baru (checkout dari keranjang)	`{"shipping_method", "payment_method", "address", ...}`
GET	`/orders/{id}`	Detail pesanan beserta item	—
POST	`/orders/{id}/cancel`	Batalkan pesanan	—
POST	`/orders/{id}/payment-proof`	Upload bukti pembayaran transfer	multipart: `proof` (file gambar)
POST	`/orders/{id}/confirm-receipt`	Konfirmasi barang diterima + upload bukti penerimaan	multipart: `proof` (file gambar)

💰 Dompet & Penarikan Pembeli (`/buyer/*`)

Method	Endpoint	Fungsi
GET	`/buyer/wallet/balance`	Saldo dompet + riwayat transaksi
GET	`/buyer/payment-accounts`	Daftar rekening bank buyer
POST	`/buyer/payment-accounts`	Tambah rekening bank baru
PUT	`/buyer/payment-accounts/{id}`	Update data rekening
DELETE	`/buyer/payment-accounts/{id}`	Hapus rekening
GET	`/buyer/withdrawals`	Riwayat pengajuan penarikan
POST	`/buyer/withdrawals`	Ajukan penarikan saldo dompet

🏬

12. API Endpoint Penjual

Semua endpoint berikut memerlukan autentikasi Sanctum + middleware seller (role harus seller). Prefix: /seller/

📦 Manajemen Produk (`/seller/products`)

Method	Endpoint	Fungsi	Keterangan
GET	`/seller/products`	Daftar produk milik toko ini	Filter/pagination tersedia
GET	`/seller/products/statistics`	Statistik produk (total, stok rendah, nilai)	—
POST	`/seller/products/upload-image`	Upload gambar produk	`multipart/form-data`, field: `image`
POST	`/seller/products`	Buat produk baru	JSON dengan semua field produk
PUT	`/seller/products/{id}`	Update produk	Hanya pemilik produk
DELETE	`/seller/products/{id}`	Hapus produk	Hanya pemilik produk
PUT	`/seller/products/{id}/stock`	Update stok saja	Body: `{"stock": 100}`

📋 Pesanan Masuk (`/seller/orders`)

Method	Endpoint	Fungsi	Request
GET	`/seller/orders`	Daftar pesanan yang berisi produk toko ini	Query: `status`, `date_from`, `date_to`
PUT	`/seller/orders/{id}/status`	Update status pesanan	Body: `{"status": "confirmed"\|"processing"\|"shipped"}`

🏦 Rekening & Penarikan Penjual

Method	Endpoint	Fungsi
GET	`/seller/payment-accounts`	Daftar rekening bank penjual
POST	`/seller/payment-accounts`	Tambah rekening baru
PUT	`/seller/payment-accounts/{id}`	Update data rekening
DELETE	`/seller/payment-accounts/{id}`	Hapus rekening
GET	`/seller/withdrawals/balance`	Saldo pendapatan bersih yang bisa dicairkan
GET	`/seller/withdrawals`	Riwayat pengajuan penarikan
POST	`/seller/withdrawals`	Ajukan penarikan pendapatan

🛡️

13. API Endpoint Admin

Semua endpoint berikut memerlukan autentikasi Sanctum + middleware admin. Prefix: /admin/. Endpoint ini digunakan oleh panel web admin (browser).

Method	Endpoint	Fungsi
GET	`/admin/settings`	Ambil pengaturan platform saat ini
PUT	`/admin/settings`	Update pengaturan platform
GET	`/admin/product-banners`	Daftar banner promosi
POST	`/admin/product-banners`	Upload banner baru (multipart)
DELETE	`/admin/product-banners/{id}`	Hapus banner
GET	`/admin/users`	Daftar semua pengguna
POST	`/admin/users`	Buat pengguna baru
GET	`/admin/users/{id}`	Detail pengguna
PUT	`/admin/users/{id}`	Update data pengguna
DELETE	`/admin/users/{id}`	Hapus pengguna
GET	`/admin/orders`	Semua pesanan di platform
PUT	`/admin/orders/{id}/status`	Update status pesanan
PUT	`/admin/orders/{id}/payment`	Update status pembayaran (konfirmasi transfer)
GET	`/admin/withdrawals`	Semua pengajuan penarikan penjual
PUT	`/admin/withdrawals/{id}`	Approve/tolak penarikan penjual
GET	`/admin/buyer-withdrawals`	Semua pengajuan penarikan pembeli
PUT	`/admin/buyer-withdrawals/{id}`	Approve/tolak penarikan pembeli

🗄️

14. Skema Database

Apa itu Database dan Skema?

Database adalah tempat penyimpanan data aplikasi secara permanen. Tanpa database, data hilang setiap kali aplikasi ditutup. Tambang Go menggunakan MySQL, database relasional yang menyimpan data dalam bentuk tabel (seperti spreadsheet Excel).

Skema database adalah struktur/definisi tabel: nama kolom, tipe data, dan relasi antar tabel. Contoh: tabel products punya kolom name, price, stock; tabel orders terhubung ke users (pembeli) via buyer_id.

Migrasi — file PHP yang mendefinisikan/mengubah struktur tabel secara terkontrol
Seeder — script untuk mengisi data awal (admin, kategori sample, produk demo)
Foreign Key (FK) — relasi antar tabel (misal: product.seller_id → users.id)

Contoh di Tambang Go: Saat checkout, backend menulis ke tabel orders dan order_items, lalu mengurangi stock di tabel products — semua dalam satu transaksi database agar data konsisten.

Database menggunakan MySQL dengan nama database tambang_go. Struktur tabel didefinisikan di backend-laravel/database/migrations/ (25 file migrasi). Data awal diisi oleh backend-laravel/database/seeders/.

Tabel `users`

Kolom	Tipe	Nullable	Keterangan
id	bigint UNSIGNED	No	Primary Key, Auto Increment
name	varchar(255)	No	Nama lengkap
email	varchar(255)	No	Unique, digunakan untuk login
google_id	varchar(255)	Yes	ID akun Google (OAuth), Unique
email_verified_at	timestamp	Yes	Waktu verifikasi email
password	varchar(255)	Yes	Hash bcrypt (null untuk akun Google-only)
phone	varchar(255)	Yes	Nomor telepon
address	text	Yes	Alamat (juga digunakan sebagai alamat toko penjual)
profile_photo	varchar(255)	Yes	Path foto profil di storage
role	enum('admin','seller','buyer')	No	Role pengguna
status	enum('active','inactive')	No	Default: active
remember_token	varchar(100)	Yes	Token "ingat saya"
created_at / updated_at	timestamp	Yes	Timestamps otomatis

Tabel `categories`

Kolom	Tipe	Keterangan
id	bigint PK	Primary Key
name	varchar(255)	Nama kategori (contoh: Tali Nilon, Tali Baja)
slug	varchar(255) UNIQUE	URL-friendly identifier
description	text nullable	Deskripsi kategori
image	varchar(255) nullable	Path gambar kategori
is_active	boolean	Status aktif/nonaktif kategori

Tabel `products`

Kolom	Tipe	Keterangan
id	bigint PK	—
seller_id	bigint FK → users	Penjual pemilik produk
category_id	bigint FK → categories	Kategori produk
name	varchar(255)	Nama produk
slug	varchar(255) UNIQUE	URL-friendly identifier
description	text nullable	Deskripsi lengkap produk
price	decimal(12,2)	Harga satuan
stock	integer	Stok tersedia
image	varchar(255) nullable	Gambar utama
images	JSON nullable	Array path gambar tambahan (multi-foto)
unit	enum('meter','roll','kg','pcs')	Satuan produk
weight	decimal nullable	Berat produk (kg)
diameter	varchar(50) nullable	Diameter tali (contoh: "10mm")
material	varchar(100) nullable	Material tali (contoh: "Nilon", "Baja")
is_active	boolean	Status tampil di katalog

Tabel `orders`

Kolom	Tipe	Keterangan
id	bigint PK	—
order_number	varchar UNIQUE	Format: `ORD-YYYYMMDD-XXXXXX`
buyer_id	bigint FK → users	Pembeli yang memesan
subtotal	decimal(15,2)	Total harga barang (sebelum pajak/komisi/ongkir)
tax_amount	decimal(15,2)	Nominal pajak
commission_amount	decimal(15,2)	Nominal komisi platform
commission_percent	decimal(5,2)	Persentase komisi saat transaksi
total_amount	decimal(15,2)	subtotal + pajak + komisi
shipping_cost	decimal(15,2)	Ongkos kirim
shipping_method	enum('pickup','courier')	Metode pengiriman
status	enum	pending/confirmed/processing/shipped/delivered/cancelled
payment_status	enum	unpaid/pending_payment/pending_confirmation/paid/refunded
payment_method	enum('transfer','cod')	Metode pembayaran
shipping_name	varchar nullable	Nama penerima
shipping_phone	varchar nullable	Telepon penerima
shipping_address	text nullable	Alamat pengiriman
payment_proof_image	varchar nullable	Path bukti pembayaran transfer
receipt_proof_image	varchar nullable	Path bukti penerimaan barang
paid_at	timestamp nullable	Waktu pembayaran dikonfirmasi
shipped_at	timestamp nullable	Waktu pesanan dikirim
delivered_at	timestamp nullable	Waktu pesanan diterima

Tabel `order_items`

Kolom	Tipe	Keterangan
id	bigint PK	—
order_id	bigint FK → orders	Pesanan terkait
product_id	bigint FK → products	Produk yang dipesan
seller_id	bigint FK → users	Penjual produk (disimpan untuk history)
product_name	varchar	Snapshot nama produk saat pembelian
product_price	decimal	Snapshot harga saat pembelian
quantity	integer	Jumlah unit yang dipesan
subtotal	decimal	product_price × quantity

Tabel `platform_settings`

Kolom	Tipe	Keterangan
commission_percent	decimal(5,2)	Persentase komisi (contoh: 5.00)
tax_percent	decimal(5,2)	Persentase pajak (0 jika tidak ada)
shipping_courier_cost	decimal(15,2)	Biaya kurir per toko
min_withdrawal_amount	decimal(15,2)	Minimum saldo untuk penarikan
pickup_store_name	varchar	Nama toko/lokasi pickup
pickup_store_address	text	Alamat lengkap pickup
payment_bank_name	varchar	Nama bank platform (untuk transfer buyer)
payment_account_number	varchar	Nomor rekening platform
payment_account_holder_name	varchar	Nama pemilik rekening platform
maintenance_mode	boolean	Aktifkan mode maintenance (blokir checkout)
maintenance_message	text nullable	Pesan yang ditampilkan saat maintenance

Tabel-tabel Lainnya

Nama Tabel	Fungsi	Kolom Utama
`carts`	Item keranjang belanja	user_id, product_id, quantity — UNIQUE(user_id, product_id)
`seller_payment_accounts`	Rekening bank penjual untuk pencairan	user_id, bank_name, account_number, account_holder_name, is_default
`withdrawal_requests`	Pengajuan penarikan penjual	seller_id, amount, bank info, status (pending/approved/rejected/completed), admin_note, processed_by
`buyer_payment_accounts`	Rekening bank pembeli untuk pencairan dompet	user_id, bank_name, account_number, account_holder_name, is_default
`buyer_withdrawal_requests`	Pengajuan penarikan pembeli	buyer_id, amount, bank info, status, admin_note
`wallet_transactions`	Riwayat transaksi dompet pembeli	user_id, type (credit/debit), amount, source_type, source_id, description
`product_banners`	Banner promosi untuk slider katalog	image (path file)
`personal_access_tokens`	Token Sanctum (dikelola Laravel otomatis)	tokenable_type, tokenable_id, token (hashed)

📐

15. Model Data Flutter

Apa itu Model Data (DTO)?

Model adalah kelas/kelas data yang merepresentasikan entitas bisnis dalam kode. Di Flutter, model berfungsi sebagai DTO (Data Transfer Object) — objek perantara yang mengubah data JSON dari API menjadi struktur Dart yang mudah digunakan di UI.

Tanpa model, developer harus mengakses data mentah seperti json['name'] di setiap tempat. Dengan model, cukup product.name — lebih aman, terbaca, dan terhindar dari typo.

fromJson() — method untuk memparse JSON → objek Dart
toJson() — method untuk mengubah objek Dart → JSON (saat kirim ke API)
Model Flutter (frontend/lib/models/) ↔ Model Laravel/Eloquent (backend-laravel/app/Models/) merepresentasikan entitas yang sama

Contoh: Response API GET /products/1 berupa JSON. Class Product.fromJson() di product.dart mengubahnya menjadi objek Product dengan properti name, price, stock yang bisa langsung ditampilkan di ProductDetailScreen.

Model Flutter berfungsi sebagai Data Transfer Object (DTO) — yaitu kelas yang memetakan data JSON dari API ke objek Dart. Semua model berada di folder frontend/lib/models/. Model backend (Eloquent) ada di backend-laravel/app/Models/.

File Model	Kelas	Field Utama
`models/user.dart`	`User`	id, name, email, role, phone, address, profilePhoto, status, googleId
`models/product.dart`	`Product`	id, sellerId, categoryId, name, slug, description, price, stock, image, images (List), unit, weight, diameter, material, isActive, seller, category
`models/category.dart`	`Category`	id, name, slug, description, image, isActive
`models/cart_item.dart`	`CartItem`, `Cart`	id, productId, quantity, product (nested); Cart juga berisi pickupLocations, shippingPreview
`models/order.dart`	`Order`, `OrderItem`	id, orderNumber, buyerId, subtotal, taxAmount, commissionAmount, totalAmount, shippingCost, shippingMethod, status, paymentStatus, paymentMethod, items (List<OrderItem>)
`models/payment_account.dart`	`PaymentAccount`	id, userId, bankName, accountNumber, accountHolderName, isDefault
`models/withdrawal_request.dart`	`WithdrawalRequest`	id, sellerId, amount, bankName, accountNumber, accountHolderName, status, adminNote, processedBy, createdAt
`models/buyer_withdrawal_request.dart`	`BuyerWithdrawalRequest`	id, buyerId, amount, bankInfo, status, adminNote, createdAt
`models/product_banner.dart`	`ProductBanner`	id, image (path)
`models/api_response.dart`	`ApiResponse<T>`	Generik wrapper: success (bool), message (String), data (T nullable), errors (Map nullable)

Contoh Model: Product

class Product {
  final int id;
  final int sellerId;
  final String name;
  final double price;
  final int stock;
  final String unit;    // 'meter' | 'roll' | 'kg' | 'pcs'
  final String? diameter;
  final String? material;
  final List<String> images;

  Product.fromJson(Map<String, dynamic> json) : 
    id = json['id'],
    name = json['name'],
    price = double.parse(json['price'].toString()),
    // ... dan seterusnya
    images = List<String>.from(json['images'] ?? []);
}

🔄

16. Alur Bisnis Utama

Apa itu Alur Bisnis (Business Flow)?

Alur bisnis adalah rangkaian langkah/logika yang harus dilalui untuk menyelesaikan proses bisnis dari awal sampai akhir. Di e-commerce, alur bisnis mendefinisikan siapa melakukan apa, kapan, dan dalam kondisi apa.

Memahami alur bisnis penting karena kode aplikasi seharusnya merefleksikan proses bisnis nyata. Setiap langkah alur biasanya diimplementasikan oleh kombinasi layar UI, API endpoint, dan perubahan status di database.

Contoh alur checkout di Tambang Go: Pembeli pilih barang → checkout → upload bukti bayar → admin konfirmasi → penjual kirim → pembeli konfirmasi terima. Setiap panah adalah aksi yang memicu perubahan kode di frontend dan backend.

Alur Pembelian Lengkap (Transfer Bank)

📁 File kode terkait alur checkout transfer: frontend/lib/screens/buyer/checkout_screen.dart → frontend/lib/providers/order_provider.dart → backend-laravel/app/Http/Controllers/Api/OrderController.php (store, uploadPaymentProof, confirmReceipt, cancel)

Tambah ke Keranjang

→

Checkout
(pilih metode)

→

POST /orders
stok berkurang

→

Status: pending
keranjang bersih

Upload Bukti Bayar
payment-proof

→

pending_confirmation
menunggu admin

→

Admin Konfirmasi
status: paid

→

Seller Proses
confirmed → shipped

Buyer Konfirmasi
confirm-receipt

→

Status: delivered
Selesai ✓

Alur Pembelian COD (Bayar di Tempat)

Checkout COD

→

Status: pending
payment: unpaid

→

Seller Kirim Barang
status: shipped

→

Bayar + Terima Barang
status: delivered

Alur Pembatalan & Refund

Buyer Batalkan
POST /cancel

→

Cek: Ada Bukti Bayar?

YA: Refund ke Dompet
payment: refunded

TIDAK: Batalkan Langsung
status: cancelled

Alur Penarikan Dana Penjual

Seller Ajukan
POST /withdrawals

→

Status: pending
menunggu admin

→

Admin Review

→

approved/completed

atau

rejected

📋

17. Status Pesanan & Pembayaran

Apa itu Status Pesanan dan Status Pembayaran?

Dalam sistem e-commerce, setiap pesanan memiliki dua dimensi status yang melacak progres berbeda:

Status Pesanan (Order Status) — melacak progres pengiriman barang: pending → confirmed → processing → shipped → delivered (atau cancelled).
Status Pembayaran (Payment Status) — melacak progres pembayaran uang: unpaid → pending_payment → pending_confirmation → paid → refunded.

Kedua status berjalan paralel. Misalnya pesanan bisa sudah confirmed (penjual siap kirim) sementara pembayaran masih pending_confirmation (menunggu admin cek bukti transfer).

Analogi: Status pesanan seperti pelacakan paket JNE (sudah dikirim/belum). Status pembayaran seperti status tagihan (sudah lunas/belum). Keduanya perlu dipantau terpisah.

Status Pesanan (Order Status)

pending

→

confirmed

→

processing

→

shipped

→

delivered

cancelled

Status	Ditetapkan Oleh	Kondisi
pending	Sistem otomatis	Saat checkout berhasil. Menunggu konfirmasi seller.
confirmed	Seller	Seller telah mengkonfirmasi pesanan dan siap diproses.
processing	Seller	Pesanan sedang dikemas/disiapkan.
shipped	Seller	Barang sudah diserahkan ke kurir/siap diambil.
delivered	Buyer	Buyer mengkonfirmasi barang sudah diterima (via `confirm-receipt`).
cancelled	Buyer/Admin	Pesanan dibatalkan. Stok dikembalikan.

Status Pembayaran (Payment Status)

Status	Keterangan	Metode
`unpaid`	Belum dibayar	COD — menunggu pembayaran saat barang tiba
`pending_payment`	Menunggu pembayaran	Transfer — buyer belum upload bukti bayar
`pending_confirmation`	Menunggu konfirmasi admin	Transfer — bukti bayar sudah diupload, admin belum konfirmasi
`paid`	Sudah dibayar	Transfer (dikonfirmasi admin) atau COD (barang diterima)
`refunded`	Dana dikembalikan ke dompet	Transfer yang sudah dikonfirmasi lalu pesanan dibatalkan

💰

18. Perhitungan Harga Pesanan

Apa itu Struktur Harga E-Commerce?

Harga yang dibayar pembeli tidak hanya harga barang. Platform e-commerce seperti Tambang Go memecah total transaksi menjadi beberapa komponen agar transparan:

Subtotal — total harga semua barang (harga × jumlah)
Pajak — persentase dari subtotal (jika diaktifkan admin)
Komisi Platform — biaya layanan platform (% dari subtotal), sumber pendapatan admin
Ongkos Kirim — biaya pengiriman kurir per toko (gratis jika pickup/ambil di toko)
Grand Total — jumlah akhir yang harus dibayar pembeli

Perhitungan ini dilakukan di backend saat checkout (OrderController.php → store()) agar tidak bisa dimanipulasi dari sisi client.

Setiap pesanan memiliki struktur harga yang transparan dengan beberapa komponen yang dikonfigurasi oleh admin.

📁 Lokasi kode perhitungan harga:

UI frontend/lib/widgets/order_price_breakdown.dart — tampilan breakdown di checkout & detail pesanan
Checkout backend-laravel/app/Http/Controllers/Api/OrderController.php — method store()
Ongkir backend-laravel/app/Support/CourierShippingCalculator.php
Settings backend-laravel/app/Models/PlatformSetting.php — commission_percent, tax_percent, shipping_courier_cost

Rumus Perhitungan

// 1. Subtotal = Total harga barang
subtotal = Σ (harga_produk × jumlah) untuk semua item

// 2. Pajak (jika tax_percent > 0)
tax_amount = subtotal × (tax_percent / 100)

// 3. Komisi Platform (diambil dari subtotal)
commission_amount = subtotal × (commission_percent / 100)

// 4. Total Merchandise
total_amount = subtotal + tax_amount + commission_amount

// 5. Ongkos Kirim (hanya untuk metode 'courier')
shipping_cost = courier_cost_per_toko × jumlah_toko_unik_di_keranjang
// Untuk 'pickup': shipping_cost = 0

// 6. Grand Total yang Harus Dibayar Buyer
grand_total = total_amount + shipping_cost

Contoh Perhitungan Nyata

Komponen	Perhitungan	Nilai
Tali Nilon 10mm × 50 meter	Rp 15.000 × 50	Rp 750.000
Tali Baja 8mm × 1 roll	Rp 350.000 × 1	Rp 350.000
Subtotal	—	Rp 1.100.000
Pajak (2%)	Rp 1.100.000 × 2%	Rp 22.000
Komisi Platform (5%)	Rp 1.100.000 × 5%	Rp 55.000
Total Merchandise	—	Rp 1.177.000
Ongkir Kurir (2 toko × Rp 20.000)	—	Rp 40.000
GRAND TOTAL	—	Rp 1.217.000

📌 Catatan Komisi: Komisi platform bukan diambil dari penjual setelah transaksi, melainkan sudah termasuk dalam harga yang dibayar pembeli. Penjual menerima pendapatan bersih setelah dikurangi komisi.

💳

19. Sistem Dompet & Penarikan Dana

Apa itu Dompet Digital dan Penarikan Dana?

Dompet digital (wallet) di aplikasi e-commerce adalah saldo virtual pengguna yang tersimpan di platform. Saldo ini bisa diisi dari refund (pengembalian dana) dan dicairkan ke rekening bank.

Penarikan dana (withdrawal) adalah proses pemindahan saldo dari platform ke rekening bank pengguna. Di Tambang Go ada dua jenis:

Dompet Pembeli — saldo dari refund pesanan transfer yang dibatalkan, bisa ditarik ke rekening bank buyer
Pendapatan Penjual — akumulasi penjualan produk (setelah komisi), bisa ditarik ke rekening bank seller

Penarikan memerlukan persetujuan admin karena transfer dilakukan secara manual ke rekening bank. Status: pending → approved/rejected → completed.

Contoh: Pembeli bayar transfer Rp 500.000, lalu batalkan pesanan. Sistem otomatis mengkredit Rp 500.000 ke dompet via BuyerWalletService.php. Pembeli ajukan penarikan → admin transfer manual → status completed.

💰 Dompet Pembeli (Buyer Wallet)

Dompet pembeli diisi secara otomatis ketika pesanan transfer yang sudah dikonfirmasi pembayarannya kemudian dibatalkan. Kode refund: backend-laravel/app/Support/BuyerWalletService.php.

Saldo awal = 0
Kredit: dari refund pesanan yang dibatalkan
Debit: saat penarikan ke rekening bank
Minimum penarikan: sesuai pengaturan admin

🏦 Pendapatan Penjual

Penjual mendapatkan pendapatan setiap kali pesanan berstatus delivered. Perhitungan: backend-laravel/app/Support/SellerEarningsCalculator.php.

pendapatan_bersih = subtotal_item - komisi_platform

Saldo terakumulasi dari setiap pesanan selesai
Ajukan penarikan dengan memilih rekening terdaftar
Admin memproses transfer manual

Alur Penarikan Dana

Tahap	Aktor	Aksi	Status
1	Seller/Buyer	Pilih jumlah dan rekening → POST withdrawal	pending
2	Admin	Review di panel web	—
3a	Admin	Approve → transfer manual ke rekening	approved → completed
3b	Admin	Tolak dengan catatan alasan	rejected

⚡

20. State Management

Apa itu State Management?

State (keadaan) adalah data yang dapat berubah seiring waktu dan memengaruhi tampilan UI aplikasi. Contoh state di Tambang Go:

Apakah pengguna sudah login atau belum?
Berapa jumlah item di keranjang belanja?
Daftar produk yang sedang ditampilkan di katalog
Status loading saat menunggu response API
Detail pesanan yang sedang dilihat

State Management adalah cara mengelola, menyimpan, dan membagikan data (state) ini agar seluruh bagian aplikasi bisa mengaksesnya dengan konsisten. Tanpa state management yang baik, data harus "dikirim" manual antar widget (prop drilling) dan UI tidak otomatis diperbarui saat data berubah.

Masalah tanpa state management:

Data duplikat di banyak widget — sulit disinkronkan
UI tidak refresh otomatis setelah data berubah
Logika bisnis tercampur dengan kode tampilan (UI)
Sulit melacak dari mana data berasal

Solusi di Tambang Go — Provider: Package Provider (v6.1.1) menggunakan pola ChangeNotifier. Provider menyimpan state di satu tempat terpusat. Saat state berubah, Provider memanggil notifyListeners() sehingga semua widget yang "mendengarkan" otomatis di-rebuild (diperbarui tampilannya).

Analogi: State Management seperti papan skor di pertandingan basket. Semua pemain (widget) melihat skor yang sama dari papan (Provider). Ketika skor berubah, papan diperbarui dan semua pemain langsung tahu — tidak perlu satu per satu memberitahu.

Contoh konkret di Tambang Go: Pembeli menambah produk ke keranjang → CartProvider.addToCart() dipanggil → API berhasil → Provider update jumlah item → notifyListeners() → ikon keranjang di header otomatis menampilkan angka baru tanpa perlu refresh manual halaman.

Implementasi Provider di Tambang Go

Aplikasi Flutter menggunakan package Provider (versi 6.1.1) sebagai solusi state management. Provider dipasang di level root aplikasi menggunakan MultiProvider di frontend/lib/main.dart baris 25–32.

// Di main.dart — MultiProvider di root app
MultiProvider(
  providers: [
    ChangeNotifierProvider(create: (_) => AuthProvider()),
    ChangeNotifierProvider(create: (_) => ProductProvider()),
    ChangeNotifierProvider(create: (_) => CartProvider()),
    ChangeNotifierProvider(create: (_) => OrderProvider()),
    ChangeNotifierProvider(create: (_) => StorefrontProvider()),
  ],
  child: MaterialApp(...),
)

Provider	File	State yang Dikelola
AuthProvider	`providers/auth_provider.dart`	User terautentikasi, token, status login/logout, operasi Google Sign-In, update profil & password, upgrade role
ProductProvider	`providers/product_provider.dart`	Daftar produk publik, produk seller, kategori, loading state, pagination, filter/search
CartProvider	`providers/cart_provider.dart`	Isi keranjang, jumlah item, operasi add/update/remove, preview ongkir
OrderProvider	`providers/order_provider.dart`	Daftar pesanan buyer/seller, detail pesanan, checkout, update status, statistik, upload bukti
StorefrontProvider	`providers/storefront_provider.dart`	Data banner katalog (ProductBanner[]), prefetch gambar banner saat splash

Pola Penggunaan Provider di Screen

// Membaca state (tanpa subscribe ulang saat berubah)
final authProvider = Provider.of<AuthProvider>(context, listen: false);

// Membaca state (widget direbuild saat state berubah)
final cartProvider = context.watch<CartProvider>();

// Shortcut Consumer widget
Consumer<ProductProvider>(
  builder: (context, productProvider, child) {
    if (productProvider.isLoading) return CircularProgressIndicator();
    return ProductGrid(products: productProvider.products);
  }
)

📌 Tidak ada database lokal: Semua data diambil dari API setiap kali dibutuhkan. Hanya token autentikasi dan data user yang disimpan secara persisten menggunakan flutter_secure_storage.

📦

21. Dependensi Lengkap

Apa itu Dependensi (Dependencies)?

Dependensi adalah library/paket pihak ketiga yang digunakan proyek agar developer tidak perlu menulis ulang fungsi umum dari nol. Alih-alih membuat HTTP client sendiri, proyek ini memakai package http. Alih-alih membuat sistem state sendiri, memakai provider.

Dependensi dideklarasikan di:

Flutter: frontend/pubspec.yaml — diinstall via flutter pub get
Laravel: backend-laravel/composer.json — diinstall via composer install

Setiap dependensi memiliki versi spesifik (misal provider: ^6.1.1) untuk memastikan kompatibilitas dan reproduksibilitas proyek di komputer lain.

Flutter Dependencies (pubspec.yaml)

Package	Versi	Fungsi Detail
http	^1.1.0	HTTP client untuk request GET, POST, PUT, DELETE ke Laravel API. Menangani header, body JSON, dan multipart upload.
provider	^6.1.1	State management dengan pola ChangeNotifier. Memungkinkan widget merespons perubahan data secara reaktif.
flutter_secure_storage	^9.0.0	Menyimpan token Sanctum dan data user secara aman menggunakan Android Keystore / iOS Keychain. Tidak bisa diakses oleh app lain.
shared_preferences	^2.2.2	Penyimpanan key-value sederhana untuk preferensi aplikasi. Digunakan sebagai fallback atau untuk data non-sensitif.
intl	^0.20.2	Internationalization dan formatting. Digunakan untuk format mata uang Rupiah (Rp 15.000) dan format tanggal bahasa Indonesia.
image_picker	^1.0.7	Memilih foto dari galeri atau mengambil foto baru dari kamera. Digunakan untuk upload foto produk, profil, dan bukti pembayaran.
cached_network_image	^3.4.1	Menampilkan gambar dari URL dengan cache lokal. Meningkatkan performa karena gambar tidak perlu didownload ulang setiap render.
google_sign_in	^6.2.2	Integrasi Google OAuth. Mendapatkan access_token dari Google untuk dikirim ke backend (`POST /auth/google`).
flutter_localizations	SDK	Dukungan multi-bahasa Flutter. Memungkinkan penggunaan locale id_ID untuk format tanggal dan angka dalam bahasa Indonesia.
cupertino_icons	^1.0.2	Icon set gaya iOS (Cupertino). Pelengkap Material Icons untuk tampilan yang lebih native di iOS.

Laravel Dependencies (composer.json)

Package	Versi	Fungsi
laravel/framework	^10.0	Framework PHP utama: routing, middleware, Eloquent ORM, Blade templating
laravel/sanctum	^3.2	Autentikasi API berbasis Bearer Token untuk SPA dan mobile app
guzzlehttp/guzzle	^7.2	HTTP client PHP untuk verifikasi access token Google ke Google API
laravel/tinker	^2.8	REPL (Read-Eval-Print Loop) untuk berinteraksi dengan aplikasi via command line
fakerphp/faker	^1.9.1	Generate data palsu untuk seeder database
laravel/pint	^1.0	Code style fixer untuk PHP (berbasis PHP-CS-Fixer)
phpunit/phpunit	^10.1	Testing framework untuk unit dan feature test

⚙️

22. File Konfigurasi

Apa itu File Konfigurasi?

Konfigurasi adalah pengaturan aplikasi yang bisa diubah tanpa harus mengubah kode logika bisnis. File konfigurasi memisahkan "setting" dari "kode program" sehingga aplikasi bisa dijalankan di lingkungan berbeda (development, production) dengan pengaturan berbeda.

Contoh pengaturan konfigurasi di Tambang Go:

URL server API (emulator vs perangkat fisik)
Kredensial database (host, username, password)
Port server Laravel (8001)
Pengaturan CORS (izin akses cross-origin)

Contoh: Saat development di emulator Android, api_config.dart menggunakan http://10.0.2.2:8001/api. Saat deploy ke perangkat fisik, URL diganti ke IP komputer. Kode aplikasi tidak berubah — hanya konfigurasi.

Frontend: api_config.dart

File konfigurasi paling penting di sisi Flutter. Berisi base URL API dan semua endpoint URL sebagai konstanta statis.

// frontend/lib/config/api_config.dart
class ApiConfig {
  // ⚠️ Ganti URL ini sesuai environment pengembangan:
  // Android Emulator : http://10.0.2.2:8001/api
  // iOS Simulator    : http://localhost:8001/api
  // Perangkat Fisik  : http://YOUR_COMPUTER_IP:8001/api
  static const String baseUrl = 'http://10.0.2.2:8001/api';

  // Storage keys (flutter_secure_storage)
  static const String tokenKey = 'auth_token';
  static const String userKey  = 'user_data';
}

Backend: File .env

Variable	Nilai Default	Keterangan
APP_NAME	"Tali Tambang Go"	Nama aplikasi
APP_URL	http://localhost:8001	URL backend (port 8001)
DB_CONNECTION	mysql	Driver database
DB_HOST	127.0.0.1	Host database
DB_PORT	3306	Port MySQL
DB_DATABASE	tambang_go	Nama database
DB_USERNAME	root	Username MySQL
DB_PASSWORD	(kosong)	Password MySQL

CORS (config/cors.php)

Backend Laravel dikonfigurasi untuk menerima request dari semua origin (*) pada path api/*. Ini memungkinkan Flutter di berbagai device mengakses API.

Data Awal (Seeders)

Data	Email/Info	Password
Akun Admin	admin@example.com	password
Akun Seller Contoh	seller@example.com	password
Akun Buyer Contoh	buyer@example.com	password
Kategori	Tali Nilon, Tali Baja, Tali Rami, dll.
Produk Sample	Beberapa produk tali tambang dengan variasi spesifikasi

🚀

23. Cara Menjalankan Aplikasi

Prasyarat

Software	Versi Minimum	Keterangan
Flutter SDK	3.x	Termasuk Dart SDK ≥ 3.2.6
Android Studio / VS Code	Latest	IDE dengan plugin Flutter
PHP	8.1+	Untuk menjalankan backend Laravel
Composer	2.x	Package manager PHP
MySQL	8.x	Database server
Android Emulator / Device	API 21+	Untuk testing aplikasi mobile

Langkah 1: Setup Backend Laravel

# 1. Masuk ke folder backend
cd tambang_go/backend-laravel

# 2. Install dependensi PHP
composer install

# 3. Salin file environment
cp .env.example .env

# 4. Edit .env — sesuaikan konfigurasi database
# DB_DATABASE=tambang_go, DB_USERNAME=root, DB_PASSWORD=

# 5. Generate application key
php artisan key:generate

# 6. Buat database 'tambang_go' di MySQL, lalu jalankan migrasi
php artisan migrate

# 7. Isi data awal (admin, kategori, produk sample)
php artisan db:seed

# 8. Buat symlink storage (untuk akses file yang diupload)
php artisan storage:link

# 9. Jalankan server di port 8001
php artisan serve --port=8001

Backend sekarang berjalan di http://localhost:8001. Panel admin web dapat diakses di http://localhost:8001/admin/login menggunakan kredensial: admin@example.com / password

Langkah 2: Setup Flutter Frontend

# 1. Masuk ke folder frontend
cd tambang_go/frontend

# 2. Install dependensi Flutter
flutter pub get

# 3. (Opsional) Verifikasi konfigurasi
flutter doctor

# 4. Jalankan aplikasi (pastikan emulator/device sudah aktif)
flutter run

# Atau untuk build APK release:
flutter build apk --release

⚠️ Konfigurasi URL API: Jika menggunakan perangkat fisik, buka file frontend/lib/config/api_config.dart dan ganti baseUrl dengan IP komputer Anda (bukan 10.0.2.2 yang hanya berlaku untuk Android Emulator).

Langkah 3: Akses Panel Admin Web

# Panel admin dapat diakses melalui browser
URL  : http://localhost:8001/admin/login
Email: admin@example.com
Pass : password

Troubleshooting Umum

Masalah	Solusi
Gambar tidak tampil di app	Pastikan `php artisan storage:link` sudah dijalankan
Koneksi API gagal di emulator	Gunakan `10.0.2.2` sebagai host, bukan `localhost`
Error CORS di web	Periksa `config/cors.php` — pastikan `allowed_origins` sudah `*`
Login Google gagal	Pastikan `google-services.json` ada di `android/app/` dan SHA-1 sudah terdaftar
Database migration error	Pastikan database `tambang_go` sudah dibuat di MySQL sebelum migrate

💻

24. Implementasi Kode per Fitur

Bagian ini menjelaskan kode sumber aktual yang digunakan untuk setiap fitur aplikasi. Setiap fitur mengikuti pola yang sama: Screen (UI) → Provider (state) → Service (API client) → Laravel Controller → Model/Database. Semua path file relatif terhadap folder root proyek tambang_go/.

📌 Pola umum: Flutter tidak menyimpan data bisnis secara lokal (kecuali token auth). Setiap aksi pengguna memicu request HTTP ke backend Laravel, response JSON diparse ke Model Dart, lalu Provider memanggil notifyListeners() agar UI diperbarui.

24.1 🔐 Autentikasi (Login, Register, Google Sign-In)

login_screen.dart → AuthProvider.login() → AuthService.login() → ApiService.post() → AuthController.php → User::createToken()

Layer	File	Fungsi Utama
UI	frontend/lib/screens/auth/login_screen.dart	Form email/password, tombol Google Sign-In, validasi input
UI	frontend/lib/screens/auth/register_screen.dart	Form registrasi dengan pilihan role buyer/seller
Widget	frontend/lib/widgets/google_sign_in_button.dart	Tombol login Google yang terintegrasi dengan GoogleAuthService
State	frontend/lib/providers/auth_provider.dart	`login()`, `register()`, `loginWithGoogle()`, `logout()`, `loadUser()`
Service	frontend/lib/services/auth_service.dart	Wrapper HTTP untuk endpoint auth; menyimpan token via ApiService
Service	frontend/lib/services/google_auth_service.dart	Mendapatkan `access_token` dari Google SDK
Model	frontend/lib/models/user.dart	DTO user dengan getter `isBuyer`, `isSeller`, `isAdmin`
Controller	backend-laravel/app/Http/Controllers/Api/AuthController.php	`register()`, `login()`, `googleAuth()`, `logout()`, `me()`
Middleware	backend-laravel/app/Http/Middleware/IsAdmin.php	Menolak akses non-admin ke route `/admin/*`
Routes	backend-laravel/routes/api.php	POST `/register`, `/login`, `/auth/google`

Cuplikan kode — Routing berdasarkan role setelah login (frontend/lib/screens/home_screen.dart):

class HomeScreen extends StatelessWidget {
  // Consumer<AuthProvider> membaca user yang sedang login
  if (user == null) return BuyerHomeScreen();      // mode tamu
  if (user.isAdmin) return AdminAccessDeniedScreen();
  if (user.isBuyer) return BuyerHomeScreen();
  if (user.isSeller) return SellerHomeScreen();
}

Cuplikan kode — Backend membuat token Sanctum (backend-laravel/app/Http/Controllers/Api/AuthController.php, method register):

$user = User::create([...]);
$token = $user->createToken('auth_token')->plainTextToken;
return response()->json(['data' => ['user' => $user, 'token' => $token]]);

24.2 🛍️ Katalog Produk, Kategori & Banner

buyer_home_screen.dart → ProductProvider.loadProducts() → ProductService.getProducts() → ProductController.php → Product::query()

Layer	File	Fungsi Utama
UI	frontend/lib/screens/buyer/buyer_home_screen.dart	`BuyerProductListPage`: search, filter kategori, infinite scroll, ikon keranjang
UI	frontend/lib/screens/buyer/product_detail_screen.dart	Detail produk, galeri foto, tombol tambah ke keranjang
Widget	frontend/lib/widgets/product_banner_slider.dart	Carousel banner promosi dari API storefront
State	frontend/lib/providers/product_provider.dart	`loadProducts()`, `loadCategories()`, `getProduct()`
State	frontend/lib/providers/storefront_provider.dart	`loadBanners()`, `prefetchBannerImages()`
Service	frontend/lib/services/product_service.dart	GET `/products`, `/categories`
Service	frontend/lib/services/settings_service.dart	GET `/settings/storefront` untuk banner
Model	frontend/lib/models/product.dart, category.dart, product_banner.dart	DTO produk, kategori, banner
Config	frontend/lib/config/api_config.dart	`fullImageUrl()` — menyesuaikan URL gambar untuk emulator/device
Controller	backend-laravel/app/Http/Controllers/Api/ProductController.php	`index()` (publik), `show()` (detail)
Controller	backend-laravel/app/Http/Controllers/Api/StorefrontSettingsController.php	`show()` — banner slider
Model	backend-laravel/app/Models/Product.php, Category.php, ProductBanner.php	Eloquent ORM dengan relasi seller & category

Cuplikan kode — Prefetch banner saat splash (frontend/lib/main.dart, SplashScreen):

// Saat app start, muat auth + banner bersamaan
await authProvider.loadUser();
await storefrontProvider.loadBanners();
await storefrontProvider.prefetchBannerImages();

24.3 🛒 Keranjang Belanja

cart_screen.dart → CartProvider.addToCart() → CartService.addToCart() → CartController.php → Cart::updateOrCreate()

Layer	File	Fungsi Utama
UI	frontend/lib/screens/buyer/cart_screen.dart	Daftar item, ubah quantity, hapus, tombol checkout
State	frontend/lib/providers/cart_provider.dart	`loadCart()`, `addToCart()`, `updateQuantity()`, `removeFromCart()`
Service	frontend/lib/services/cart_service.dart	CRUD keranjang via REST API
Model	frontend/lib/models/cart_item.dart	`CartItem` + `Cart` (total, shipping preview, pickup locations)
Util	frontend/lib/utils/shipping_preview.dart	Helper tampilan preview ongkir per toko
Controller	backend-laravel/app/Http/Controllers/Api/CartController.php	`index()` (termasuk shipping preview), `store()`, `update()`, `destroy()`
Support	backend-laravel/app/Support/CourierShippingCalculator.php	Hitung ongkir: biaya × jumlah toko unik
Support	backend-laravel/app/Support/SellerPickupResolver.php	Resolve alamat pickup dari profil penjual
Model	backend-laravel/app/Models/Cart.php	Relasi user + product, unique constraint per user+product

Cuplikan kode — CartProvider memanggil service (frontend/lib/providers/cart_provider.dart):

Future<bool> addToCart(int productId, {int quantity = 1}) async {
  final response = await _cartService.addToCart(productId, quantity: quantity);
  if (response.success) { await loadCart(); return true; }
}

24.4 💳 Checkout & Pembayaran

checkout_screen.dart → OrderProvider.createOrder() → OrderService.createOrder() → OrderController.store() → DB transaction

Layer	File	Fungsi Utama
UI	frontend/lib/screens/buyer/checkout_screen.dart	Form alamat, pilih shipping (courier/pickup) & payment (transfer/COD)
UI	frontend/lib/screens/buyer/order_success_screen.dart	Konfirmasi sukses + instruksi transfer
Widget	frontend/lib/widgets/order_price_breakdown.dart	Breakdown: subtotal, pajak, komisi, ongkir, total
Widget	frontend/lib/widgets/platform_transfer_instructions.dart	Tampilkan rekening bank platform
State	frontend/lib/providers/order_provider.dart	`createOrder()`
Util	frontend/lib/utils/pickup_location.dart	Helper lokasi pickup dari data keranjang
Controller	backend-laravel/app/Http/Controllers/Api/OrderController.php	`store()` — buat order, kurangi stok, kosongkan keranjang
Controller	backend-laravel/app/Http/Controllers/Api/CheckoutSettingsController.php	`show()` — pengaturan pajak, ongkir, maintenance
Concern	backend-laravel/app/Http/Controllers/Concerns/EnrichesOrdersWithPlatformPayment.php	Lampirkan rekening platform ke response order transfer
Model	backend-laravel/app/Models/PlatformSetting.php	Singleton: commission_percent, tax_percent, shipping_courier_cost

Cuplikan kode — Perhitungan harga di backend (backend-laravel/app/Http/Controllers/Api/OrderController.php, method store):

$subtotal = sum(harga × quantity);
$taxAmount = $subtotal × ($settings->tax_percent / 100);
$commissionAmount = $subtotal × ($settings->commission_percent / 100);
$shippingCost = CourierShippingCalculator::totalForCart($cartItems, $settings);
// Generate nomor: ORD-YYYYMMDD-XXXXXX

24.5 📦 Manajemen Pesanan (Buyer & Seller)

order_detail_screen.dart → OrderProvider → OrderService → OrderController.php → Order + OrderItem models

Fitur	File Flutter	File Backend	Endpoint
Riwayat pesanan buyer	order_history_screen.dart	OrderController.php → `index()`	GET `/orders`
Detail pesanan	order_detail_screen.dart	OrderController.php → `show()`	GET `/orders/{id}`
Upload bukti bayar	order_detail_screen.dart	OrderController.php → `uploadPaymentProof()`	POST `/orders/{id}/payment-proof`
Konfirmasi terima barang	order_detail_screen.dart	OrderController.php → `confirmReceipt()`	POST `/orders/{id}/confirm-receipt`
Batalkan pesanan	order_detail_screen.dart	OrderController.php → `cancel()`	POST `/orders/{id}/cancel`
Pesanan masuk seller	seller_order_screen.dart	OrderController.php → `sellerOrders()`	GET `/seller/orders`
Update status seller	seller_order_screen.dart	OrderController.php → `updateStatus()`	PUT `/seller/orders/{id}/status`
Statistik buyer	buyer_dashboard_screen.dart	OrderController.php → `statistics()`	GET `/orders/statistics`
Util status seller	frontend/lib/utils/seller_order_status.dart	—	Label & warna status pesanan

Cuplikan kode — Refund ke dompet saat cancel (backend-laravel/app/Support/BuyerWalletService.php):

public static function creditOrderRefundIfEligible(Order $order): bool {
  if (!self::isEligibleForWalletRefund($order)) return false;
  WalletTransaction::create([
    'user_id' => $order->buyer_id,
    'type' => WalletTransaction::TYPE_CREDIT,
    'amount' => $order->grand_total,
    'description' => 'Pengembalian dana pesanan #' . $order->order_number,
  ]);
}

24.6 🏬 Fitur Penjual (Produk, Pesanan, Keuangan)

Manajemen Produk

add_product_screen.dart → ProductProvider.createProduct() → ProductService → ProductController.store()

Layer	File	Method / Fungsi
UI Tambah	frontend/lib/screens/seller/add_product_screen.dart	Form produk + upload multi-foto via image_picker
UI Edit	frontend/lib/screens/seller/edit_product_screen.dart	Edit produk & update stok
UI Daftar	frontend/lib/screens/seller/seller_home_screen.dart	`SellerProductManagementPage` — tab produk
State	frontend/lib/providers/product_provider.dart	`createProduct()`, `updateProduct()`, `updateStock()`, `uploadProductImage()`
Controller	backend-laravel/app/Http/Controllers/Api/ProductController.php	`myProducts()`, `store()`, `update()`, `updateStock()`, `uploadImage()`

Keuangan & Penarikan Dana

Layer	File	Fungsi
Dashboard	frontend/lib/screens/seller/seller_dashboard_screen.dart	Ringkasan KPI + shortcut ke fitur keuangan
Penarikan	frontend/lib/screens/seller/withdrawal_request_screen.dart	Form ajukan penarikan pendapatan
Rekening	frontend/lib/screens/seller/payment_account_screen.dart	CRUD rekening bank penjual
Laporan	frontend/lib/screens/financial_report_screen.dart	Laporan pendapatan per periode
Service	frontend/lib/services/withdrawal_service.dart, payment_account_service.dart	API penarikan & rekening
Controller	backend-laravel/app/Http/Controllers/Api/SellerWithdrawalController.php	`balance()`, `store()`
Logic	backend-laravel/app/Support/SellerEarningsCalculator.php	Hitung pendapatan bersih setelah komisi

24.7 💰 Dompet Pembeli & Penarikan

buyer_wallet_screen.dart → BuyerWithdrawalService → BuyerWithdrawalController.php → WalletTransaction

Layer	File	Fungsi
UI Dompet	frontend/lib/screens/buyer/buyer_wallet_screen.dart	Saldo, riwayat transaksi, ajukan penarikan
UI Rekening	frontend/lib/screens/buyer/buyer_payment_account_screen.dart	CRUD rekening bank buyer
Widget	frontend/lib/widgets/buyer_wallet_chip.dart	Chip saldo di header katalog
Service	frontend/lib/services/buyer_withdrawal_service.dart	`getBalance()`, `createRequest()`
Model	frontend/lib/models/buyer_withdrawal_request.dart	`BuyerWalletBalance`, `BuyerWithdrawalRequest`
Controller	backend-laravel/app/Http/Controllers/Api/BuyerWithdrawalController.php	`balance()`, `store()`
Logic	backend-laravel/app/Support/BuyerWalletService.php	Kredit refund otomatis ke dompet
Model	backend-laravel/app/Models/WalletTransaction.php	Ledger kredit/debit dompet buyer

24.8 🌐 Layer HTTP & Konfigurasi API

Semua komunikasi Flutter ↔ Laravel melewati ApiService (singleton). Token Sanctum disimpan di secure storage dan otomatis dilampirkan ke setiap request ter-autentikasi.

File	Peran
frontend/lib/config/api_config.dart	Base URL + semua endpoint URL sebagai konstanta statis
frontend/lib/services/api_service.dart	Singleton HTTP client: `get()`, `post()`, `put()`, `delete()`, `uploadImage()`
frontend/lib/models/api_response.dart	Wrapper generik `ApiResponse<T>` untuk success/error
backend-laravel/routes/api.php	Definisi semua route REST API + middleware group
backend-laravel/config/sanctum.php	Konfigurasi token authentication
backend-laravel/config/cors.php	CORS policy untuk akses dari mobile app

Cuplikan kode — ApiService menambahkan Bearer Token (frontend/lib/services/api_service.dart):

Future<Map<String, String>> _getHeaders({bool includeAuth = false}) async {
  final headers = {'Accept': 'application/json', 'Content-Type': 'application/json'};
  if (includeAuth) {
    final token = await getToken();  // dari flutter_secure_storage
    if (token != null) headers['Authorization'] = 'Bearer $token';
  }
  return headers;
}

Daftar Lengkap Provider, Service & Model Flutter

Provider	File
AuthProvider	providers/auth_provider.dart
ProductProvider	providers/product_provider.dart
CartProvider	providers/cart_provider.dart
OrderProvider	providers/order_provider.dart
StorefrontProvider	providers/storefront_provider.dart

Service	File
ApiService	services/api_service.dart
AuthService	services/auth_service.dart
ProductService	services/product_service.dart
CartService	services/cart_service.dart
OrderService	services/order_service.dart
SettingsService	services/settings_service.dart
WithdrawalService	services/withdrawal_service.dart
BuyerWithdrawalService	services/buyer_withdrawal_service.dart

📋 Ringkasan Dokumentasi

Aplikasi Tambang Go adalah platform e-commerce multi-role yang komprehensif untuk produk tali tambang. Dibangun dengan arsitektur modern menggunakan Flutter untuk antarmuka mobile dan Laravel sebagai backend REST API. Sistem mendukung tiga jenis pengguna dengan workflow bisnis yang lengkap mulai dari browsing produk, pemesanan, pembayaran, pengiriman, hingga manajemen keuangan penjual dan pembeli.

Flutter

Frontend Mobile

Laravel

Backend REST API

MySQL

Database

⚓ Tambang Go

Dokumentasi Aplikasi Tambang Go

1. Gambaran Umum Aplikasi

👤 Pembeli (Buyer)

🏬 Penjual (Seller)

🛡️ Administrator

2. Teknologi yang Digunakan

Apa itu Stack Teknologi?

📱 Frontend (Mobile App)

🖥️ Backend (REST API)

🗂️ Platform Target

3. Arsitektur Sistem

Apa itu Arsitektur Client-Server?

📱 Mobile App

⚡ REST API

🗄️ Database

Pola Arsitektur Flutter

Struktur Folder Proyek

4. Fitur Pembeli (Buyer)

🌐 Mode Tamu (Guest)

🔐 Mode Terautentikasi

Fitur Detail Pembeli

🛍️ Katalog Produk

🛒 Keranjang Belanja

💳 Checkout & Pembayaran

📦 Manajemen Pesanan

💰 Dompet Pembeli

5. Fitur Penjual (Seller)

📊 Dashboard Penjual

📦 Manajemen Produk

🚚 Manajemen Pesanan

💰 Keuangan Penjual

6. Fitur Administrator

👥 Manajemen Pengguna

🏷️ Manajemen Kategori

📋 Manajemen Pesanan

💸 Manajemen Penarikan Dana

⚙️ Pengaturan Platform

🖼️ Banner Promosi

📈 Laporan Pendapatan

7. Layar Aplikasi Flutter

🔑 Layar Autentikasi

👤 Layar Pembeli (Buyer)

🏬 Layar Penjual (Seller)

👤 Layar Profil (Semua Role)

🧩 Widget Reusable

8. Navigasi & Routing

Apa itu Navigasi dan Routing?

Alur Navigasi Utama

Auth Guard

9. Sistem Autentikasi

Apa itu Autentikasi dan Otorisasi?

Mekanisme Autentikasi API

Metode Login yang Tersedia

Response Autentikasi

Middleware Proteksi Route

10. API Endpoint Publik

Apa itu REST API?

Contoh Response: GET /products

11. API Endpoint Pembeli

🔒 Endpoint Umum (Semua Role Terautentikasi)

🛒 Keranjang Belanja (/cart)

📦 Pesanan (/orders)

💰 Dompet & Penarikan Pembeli (/buyer/*)

12. API Endpoint Penjual

📦 Manajemen Produk (/seller/products)

📋 Pesanan Masuk (/seller/orders)

🏦 Rekening & Penarikan Penjual

13. API Endpoint Admin

14. Skema Database

Apa itu Database dan Skema?

Tabel users

Tabel categories

Tabel products

Tabel orders

Tabel order_items

Tabel platform_settings

Tabel-tabel Lainnya

15. Model Data Flutter

Apa itu Model Data (DTO)?

🛒 Keranjang Belanja (`/cart`)

📦 Pesanan (`/orders`)

💰 Dompet & Penarikan Pembeli (`/buyer/*`)

📦 Manajemen Produk (`/seller/products`)

📋 Pesanan Masuk (`/seller/orders`)

Tabel `users`

Tabel `categories`

Tabel `products`

Tabel `orders`

Tabel `order_items`

Tabel `platform_settings`