# 👑 King POS - Point of Sale & Manajemen Keuangan

Aplikasi Kasir (Point of Sale), Manajemen Inventori Stok, dan Laporan Keuangan berbasis web yang modern, responsif, dan siap pakai. Dibangun menggunakan arsitektur terpisah antara Frontend SPA (React + Vite + TailwindCSS) dan Backend REST API (Node.js + Express + MySQL).

---

## 📌 Daftar Isi
- [Teknologi yang Digunakan](#-teknologi-yang-digunakan)
- [Struktur Folder](#-struktur-folder)
- [Prasyarat Sistem](#-prasyarat-sistem)
- [Panduan Setup di Localhost](#-panduan-setup-di-localhost)
  - [1. Setup Database MySQL](#1-setup-database-mysql)
  - [2. Setup Backend (Server)](#2-setup-backend-server)
  - [3. Setup Frontend (Client)](#3-setup-frontend-client)
- [Akun Login Default](#-akun-login-default)
- [Fitur Utama](#-fitur-utama)
- [Daftar Endpoint API Utama](#-daftar-endpoint-api-utama)
- [Troubleshooting & Solusi](#-troubleshooting--solusi)

---

## 🛠️ Teknologi yang Digunakan

### Frontend
- **Framework:** React 18 + Vite
- **Styling:** TailwindCSS
- **State Management:** Zustand
- **Icons:** Lucide React
- **Notifications:** React Hot Toast
- **Lainnya:** React Router v6, Axios, Recharts, JsBarcode, HTML5 QR Code Scanner, ESC/POS Encoder, jsPDF, XLSX

### Backend
- **Runtime:** Node.js (v18+ atau v20+)
- **Framework:** Express.js
- **Database:** MySQL / MariaDB (Driver: `mysql2/promise`)
- **Autentikasi:** JSON Web Token (JWT) & bcryptjs
- **File Upload:** Multer

---

## 📁 Struktur Folder

```text
kingpos/
├── db_kingpos.sql              # File dump database MySQL lengkap
├── database/                   # Skrip schema & seed SQL alternatif
│   ├── schema.sql
│   ├── seed.sql
│   └── migrations/
├── server/                     # Backend REST API (Express.js)
│   ├── server.js               # File server utama
│   ├── package.json
│   ├── .env.example
│   ├── .env                    # Konfigurasi environment backend
│   └── uploads/                # Direktori penyimpanan file gambar produk
├── frontend/                   # Frontend SPA (React + Vite)
│   ├── src/
│   │   ├── api/                # Axios client & request interceptors
│   │   ├── utils/
│   │   │   ├── apiBase.js      # URL Base API terpusat
│   │   │   └── endpoints.js    # Definisi route endpoint API
│   │   ├── pages/              # Halaman-halaman aplikasi
│   │   ├── components/         # Komponen UI reusable (Modal, Table, Barcode, dll)
│   │   └── store/              # Zustand auth & store state
│   ├── package.json
│   ├── .env.example
│   └── .env                    # Konfigurasi environment frontend
└── README.md
```

---

## 💻 Prasyarat Sistem

Sebelum memulai, pastikan perangkat Anda telah terinstal:
1. **Node.js** (Versi 18.x LTS atau 20.x LTS) & **npm** / **yarn**.
   - Cek instalasi: `node -v` dan `npm -v` (atau `yarn -v`)
2. **MySQL Server** atau **MariaDB** (dapat menggunakan **XAMPP**, **Laragon**, **MAMP**, atau instalasi standalone).
3. **Git** (opsional, untuk version control).
4. Web browser modern (Google Chrome, Edge, Safari, Mozilla Firefox).

---

## 🚀 Panduan Setup di Localhost

Ikuti 3 langkah mudah berikut untuk menjalankan King POS di localhost:

### 1. Setup Database MySQL

1. **Jalankan service MySQL** di komputer Anda (misalnya melalui panel XAMPP atau Laragon).
2. **Buat database baru** bernama `db_kingpos`.
   - **Melalui phpMyAdmin:**
     1. Buka browser dan akses `http://localhost/phpmyadmin`.
     2. Klik menu **Databases / Basis Data**.
     3. Masukkan nama database: `db_kingpos`, pilih Collation `utf8mb4_unicode_ci`, lalu klik **Create**.
     4. Pilih database `db_kingpos` yang baru dibuat.
     5. Masuk ke tab **Import / Impor**.
     6. Klik **Choose File / Pilih Berkas**, pilih file **`db_kingpos.sql`** yang ada di folder root proyek ini.
     7. Gulir ke bawah lalu klik **Import / Kirim**.
   - **Atau melalui Terminal / Command Prompt:**
     ```bash
     # Buat database
     mysql -u root -p -e "CREATE DATABASE db_kingpos CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

     # Import file database dump
     mysql -u root -p db_kingpos < db_kingpos.sql
     ```

---

### 2. Setup Backend (Server)

1. Buka terminal baru dan arahkan ke direktori `server`:
   ```bash
   cd server
   ```

2. Install seluruh dependensi backend:
   ```bash
   npm install
   # atau jika menggunakan yarn:
   yarn install
   ```

3. Buat dan sesuaikan file `.env`:
   ```bash
   cp .env.example .env
   ```

4. Buka file `.env` di folder `server/` dan sesuaikan dengan kredensial MySQL lokal Anda:
   ```env
   PORT=8080
   NODE_ENV=development

   DB_HOST=127.0.0.1
   DB_PORT=3306
   DB_USER=root
   DB_PASSWORD=
   DB_NAME=db_kingpos

   JWT_SECRET=super-secret-key-kingpos-jwt-2026
   JWT_EXPIRES_IN=7d

   UPLOAD_DIR=./uploads
   ```
   > **Catatan:**
   > - Jika MySQL Anda menggunakan password (misal pada Laragon atau Mac Homebrew), isi `DB_PASSWORD` sesuai password Anda.
   > - Default XAMPP pada Windows biasanya `DB_USER=root` dan `DB_PASSWORD=` (kosong).

5. Jalankan backend server:
   ```bash
   # Mode pengembangan dengan auto-reload:
   npm run dev

   # Atau mode standar:
   npm start
   ```

6. Jika berhasil, server akan berjalan di:
   ```text
   http://localhost:8080
   ```

---

### 3. Setup Frontend (Client)

1. Buka terminal baru (biarkan terminal server tetap berjalan) dan arahkan ke direktori `frontend`:
   ```bash
   cd frontend
   ```

2. Install seluruh dependensi frontend:
   ```bash
   npm install
   # atau jika menggunakan yarn:
   yarn install
   ```

3. Buat file `.env` di direktori `frontend`:
   ```bash
   cp .env.example .env
   ```

4. Pastikan file `frontend/.env` mengarah ke backend localhost Anda:
   ```env
   VITE_API_BASE_URL=http://localhost:8080
   ```

5. Jalankan frontend development server:
   ```bash
   npm run dev
   # atau jika menggunakan yarn:
   yarn dev
   ```

6. Buka browser dan akses aplikasi di:
   ```text
   http://localhost:5173
   ```

---

## 🔐 Akun Login Default

Setelah database berhasil di-import dari `db_kingpos.sql`, Anda dapat menggunakan akun bawaan berikut untuk login:

| Role / Jabatan | Email | Password | Hak Akses Utama |
| :--- | :--- | :--- | :--- |
| **Admin Utama** | `admin@pos.local` | `password` | Seluruh fitur (Dashboard, POS, Produk, Stok, Pelanggan, Supplier, Keuangan, Laporan, Pengaturan, Kelola User) |
| **Kasir** | `kasir@pos.local` | `password` | Dashboard operasional, Transaksi Kasir (POS), Riwayat Transaksi, Daftar Pelanggan |
| **Owner** | `owner@pos.local` | `password` | Dashboard analitik, Laporan Laba/Rugi, Arus Kas (Cash Flow), Monitoring Transaksi & Produk |

> 💡 **Tips:** Anda dapat menambahkan pengguna baru atau mengubah password melalui menu **Pengguna & Hak Akses** saat login sebagai Admin.

---

## ✨ Fitur Utama

- 🛒 **Point of Sale (Kasir Cepat):**
  - Pencarian produk realtime dan integrasi Barcode / QR Code Scanner.
  - Multi satuan (Pcs, Box, Lusin, dll) dan penetapan harga bertingkat (Tiered Pricing / Grosir).
  - Pilihan diskon, pajak, dan biaya tambahan (biaya admin/ongkir).
  - Metode pembayaran tunai, transfer bank, QRIS, dan pencatatan piutang pelanggan.
  - Cetak struk belanja otomatis (Format Thermal Printer ESC/POS 58mm/80mm & PDF).
- 📦 **Manajemen Produk & Stok:**
  - Manajemen katalog produk beserta foto produk, kategori, SKU, dan barcode.
  - Penyesuaian stok (Stock Adjustment: penambahan, pengurangan, opname).
  - Peringatan stok menipis (Low Stock Alert).
  - Cetak label barcode produk massal.
  - Fitur Import / Export data produk via file Excel (.xlsx).
- 💰 **Keuangan & Arus Kas (Cash Flow):**
  - Pencatatan pengeluaran operasional (Operational Expenses) berdasarkan kategori.
  - Manajemen akun rekening kas / bank / e-wallet.
  - Manajemen hutang ke supplier dan piutang pelanggan beserta riwayat cicilan pelunasan.
- 📊 **Laporan & Analisis:**
  - Ringkasan omset penjualan harian, mingguan, dan bulanan.
  - Laporan laba kotor, produk terlaris, dan performa kasir.
  - Ekspor laporan penjualan ke format Excel dan PDF.
- 👥 **Multi User & Role-Based Access Control (RBAC):**
  - Pembagian hak akses terperinci sesuai role pengguna (Admin, Kasir, Owner).

---

## 📡 Daftar Endpoint API Utama

Semua pemanggilan API dari frontend dikelola terpusat di `frontend/src/utils/endpoints.js` dan terhubung ke backend di `server/server.js`:

| Modul | Method | Endpoint | Keterangan |
| :--- | :--- | :--- | :--- |
| **Auth** | `POST` | `/api/auth/login` | Login user & generate JWT Token |
| **Auth** | `GET` | `/api/auth/me` | Mengambil profil user & permissions yang sedang login |
| **Produk** | `GET` | `/api/products` | Menampilkan katalog produk (pagination, search, filter) |
| **Produk** | `POST` | `/api/products` | Menambah produk baru (dengan upload gambar) |
| **Produk** | `PUT` | `/api/products/:id` | Mengubah detail produk |
| **Produk** | `DELETE`| `/api/products/:id` | Menghapus produk |
| **Transaksi** | `GET` | `/api/transactions` | Riwayat transaksi penjualan |
| **Transaksi** | `POST` | `/api/transactions` | Membuat transaksi penjualan baru dari POS |
| **Transaksi** | `POST` | `/api/transactions/:id/refund` | Refund / pembatalan transaksi |
| **Pelanggan** | `GET` | `/api/customers` | Daftar pelanggan toko |
| **Akun Kas** | `GET` | `/api/cash-accounts` | Daftar akun kas/bank |
| **Pengaturan** | `GET` | `/api/settings` | Pengaturan profil toko, struk, dan sistem |

---

## ❓ Troubleshooting & Solusi

### 1. Frontend masih memanggil API remote/demo, bukan localhost
**Penyebab:** File `.env` pada folder `frontend` belum dibuat atau belum dimuat ulang oleh Vite.  
**Solusi:**
1. Pastikan file `frontend/.env` sudah ada dan berisi:
   ```env
   VITE_API_BASE_URL=http://localhost:8080
   ```
2. Hentikan Vite di terminal (`Ctrl + C`), lalu jalankan kembali `npm run dev` atau `yarn dev`.

### 2. Error Backend: `ECONNREFUSED 127.0.0.1:3306`
**Penyebab:** Service MySQL belum berjalan.  
**Solusi:**
1. Buka control panel XAMPP atau Laragon.
2. Pastikan service **MySQL** sudah dalam status **Running / Started**.

### 3. Error Backend: `ER_ACCESS_DENIED_ERROR`
**Penyebab:** Username atau password database di `server/.env` tidak cocok.  
**Solusi:**
1. Buka `server/.env`.
2. Sesuaikan `DB_USER` dan `DB_PASSWORD` dengan konfigurasi MySQL komputer Anda.

### 4. Port 8080 atau 5173 sudah digunakan aplikasi lain
**Solusi:**
- Untuk Backend: Ubah nilai `PORT` di `server/.env` (misalnya menjadi `PORT=5000`), lalu sesuaikan `VITE_API_BASE_URL` di `frontend/.env` menjadi `http://localhost:5000`.
- Untuk Frontend: Port Vite dapat diatur melalui flag `--port` atau diatur otomatis oleh Vite ke port bebas berikutnya.

---

## 📝 Lisensi & Kontribusi

Proyek ini dikembangkan untuk kebutuhan operasional retail dan point of sale. Silakan sesuaikan kode dan konfigurasi sesuai dengan alur bisnis Anda.