README.md

---
title: Tokiva Backend Node
emoji: 📦
colorFrom: green
colorTo: indigo
sdk: docker
app_port: 7860
---

# Tokiva POS Backend (Node.js & TypeScript Edition)

Backend ini dibangun menggunakan **Node.js**, **Express**, **TypeScript**, ORM **Prisma**, dan database **MySQL**. Aplikasi ini dirancang untuk mendukung operasional sistem POS (Point of Sales) ritel modern, lengkap dengan fitur manajemen stok berbasis FEFO (First Expired First Out), kasir shift, audit logging, dan integrasi penyimpanan cloud (Supabase Storage).

---

## 🛠️ Persyaratan System (Prerequisites)

- Node.js (v18 atau lebih tinggi)
- npm atau yarn
- Database MySQL

---

## 🚀 Cara Menjalankan secara Lokal

### 1. Install Dependensi
Masuk ke direktori `backend-node` dan jalankan instalasi:
```bash
cd backend-node
npm install
```

### 2. Setup Environment Variable
Buat file `.env` di dalam folder root `backend-node` dan isi sesuai dengan kebutuhan Anda:
```env
PORT=5000
DATABASE_URL="mysql://username:password@127.0.0.1:3306/tokiva"

# JWT Configuration
JWT_SECRET_KEY="rahasia_super_kuat_anda"
JWT_EXPIRES_IN="24h"

# Supabase Storage Configuration (Opsional, untuk upload gambar produk/member)
SUPABASE_URL="https://your-supabase-url.supabase.co"
SUPABASE_ANON_KEY="your-anon-key"
SUPABASE_SERVICE_KEY="your-service-role-key"
```

### 3. Sinkronisasi Skema Database & Generate Prisma Client
Jalankan perintah berikut untuk mensinkronkan skema database lokal Anda dengan Prisma Client:
```bash
npx prisma generate
```

### 4. Jalankan Server Development
Jalankan server dalam mode development (menggunakan `ts-node-dev` untuk auto-reload):
```bash
npm run dev
```
Server akan berjalan di: **`http://localhost:5000`**

---

## 📂 Struktur Direktori Proyek

```text
backend-node/
├── prisma/                  # Skema database Prisma
│   └── schema.prisma
├── src/
│   ├── controllers/         # Menangani HTTP request dan format response
│   ├── middlewares/         # Middleware Express (Auth, Zod Validation, Error handler)
│   ├── routes/              # Defini endpoint API Express
│   ├── schemas/             # Validator skema request input menggunakan Zod
│   ├── services/            # Logika bisnis inti aplikasi
│   ├── utils/               # Helper (Supabase, JWT, response formatter, audit logger)
│   ├── app.ts               # Setup Express application
│   └── server.ts            # Entrypoint API server
├── .env                     # File konfigurasi environment
├── package.json             # File dependensi proyek
└── tsconfig.json            # Konfigurasi TypeScript compiler
```

---

## 📘 Referensi Endpoint API

Seluruh endpoint API memiliki prefix `/api`. 
Endpoint yang membutuhkan header **Authorization** harus melampirkan token JWT: `Bearer <token_jwt>`.

### 1. Autentikasi (`/api/auth`)
| Method | Endpoint | Auth | Deskripsi |
|---|---|---|---|
| `POST` | `/auth/login` | Publik | Login pengguna menggunakan username dan password |
| `POST` | `/auth/refresh` | Publik | Melakukan refresh JWT token |

### 2. Manajemen Pengguna / Karyawan (`/api/users`)
| Method | Endpoint | Auth | Deskripsi |
|---|---|---|---|
| `GET` | `/users` | Admin | Memuat daftar semua pengguna |
| `POST` | `/users` | Admin | Membuat akun pengguna baru |
| `PUT` | `/users/:id` | Admin | Mengedit informasi akun pengguna |
| `DELETE` | `/users/:id` | Admin | Menghapus akun pengguna (Soft-Delete) |

### 3. Kategori Produk (`/api/kategori`)
| Method | Endpoint | Auth | Deskripsi |
|---|---|---|---|
| `GET` | `/kategori` | Token | Memuat seluruh kategori produk |
| `POST` | `/kategori` | Token | Menambah kategori baru |
| `PUT` | `/kategori/:id` | Token | Mengubah kategori |
| `DELETE` | `/kategori/:id` | Token | Menghapus kategori |

### 4. Supplier / Pemasok (`/api/supplier`)
| Method | Endpoint | Auth | Deskripsi |
|---|---|---|---|
| `GET` | `/supplier` | Token | Memuat seluruh supplier aktif |
| `POST` | `/supplier` | Token | Menambah supplier baru |
| `PUT` | `/supplier/:id` | Token | Mengubah data supplier |
| `DELETE` | `/supplier/:id` | Token | Menghapus supplier |

### 5. Member / Pelanggan Loyalitas (`/api/member`)
| Method | Endpoint | Auth | Deskripsi |
|---|---|---|---|
| `GET` | `/member` | Token | Memuat daftar member |
| `POST` | `/member` | Token | Mendaftarkan member baru |
| `PUT` | `/member/:id` | Token | Memperbarui profil member |
| `DELETE` | `/member/:id` | Token | Menghapus member |

### 6. Produk (`/api/produk`)
| Method | Endpoint | Auth | Deskripsi |
|---|---|---|---|
| `GET` | `/produk` | Token | Memuat daftar produk (mendukung pencarian & filter) |
| `GET` | `/produk/:id` | Token | Memuat detail lengkap satu produk |
| `GET` | `/produk/scan/:barcode_or_kode` | Token | Mencari produk berdasarkan barcode/kode untuk scan cepat |
| `POST` | `/produk` | Token | Menambah produk baru |
| `PUT` | `/produk/:id` | Token | Memperbarui produk |
| `DELETE` | `/produk/:id` | Token | Menghapus produk (Soft-Delete) |

### 7. Manajemen Stok & Batch FEFO (`/api/stok`)
| Method | Endpoint | Auth | Deskripsi |
|---|---|---|---|
| `POST` | `/stok/masuk` | Token | Mencatat barang masuk/restock ke batch tertentu |
| `POST` | `/stok/opname` | Token | Membuat draf stok opname (penyesuaian fisik) |
| `POST` | `/stok/opname/:opname_id/approve` | Token | Menyetujui opname dan menyesuaikan stok utama produk |
| `GET` | `/stok/mutasi` | Token | Memuat kartu stok / riwayat mutasi stok produk |
| `GET` | `/stok/batches` | Token | Memuat batch stok produk yang masih aktif (qty sisa > 0) |

### 8. Transaksi Penjualan (`/api/transaksi`)
| Method | Endpoint | Auth | Deskripsi |
|---|---|---|---|
| `POST` | `/transaksi` | Token | Mencatat transaksi kasir baru (FEFO auto-deduction) |
| `GET` | `/transaksi` | Token | Memuat riwayat transaksi penjualan |
| `POST` | `/transaksi/retur` | Token | Melakukan retur barang dari suatu transaksi (refund/exchange) |

### 9. Bon & Piutang Member (`/api/bon`)
| Method | Endpoint | Auth | Deskripsi |
|---|---|---|---|
| `GET` | `/bon` | Token | Memuat semua daftar bon piutang member |
| `POST` | `/bon/:bon_id/cicil` | Token | Mencatat pembayaran cicilan bon member |

### 10. Laporan Finansial & Operasional (`/api`)
| Method | Endpoint | Auth | Deskripsi |
|---|---|---|---|
| `GET` | `/laporan/ringkasan` | Admin | Memuat ringkasan keuangan (pendapatan, laba kotor, dll) |
| `GET` | `/laporan/penjualan` | Admin | Laporan detail penjualan berdasarkan rentang tanggal |
| `GET` | `/laporan/stok` | Admin | Laporan analisis stok produk saat ini |

### 11. Manajemen Shift Kasir (`/api`)
| Method | Endpoint | Auth | Deskripsi |
|---|---|---|---|
| `POST` | `/shift/buka` | Token | Membuka shift kasir baru dan mencatat modal awal |
| `POST` | `/shift/tutup` | Token | Menutup shift kasir, mencatat total fisik uang, & mendeteksi selisih |
| `GET` | `/shift/aktif` | Token | Mendapatkan informasi shift yang sedang berjalan |

### 12. Upload File Media (`/api/upload`)
| Method | Endpoint | Auth | Deskripsi |
|---|---|---|---|
| `POST` | `/upload/produk` | Token | Upload gambar produk ke Supabase Storage (Base64/Form-Data) |
| `POST` | `/upload/member` | Token | Upload foto member ke Supabase Storage |

---

## 🧪 Jalankan Tes Integrasi CRUD

Untuk memverifikasi fungsionalitas CRUD secara end-to-end terhadap database MySQL lokal Anda:
1. Pastikan server backend sedang berjalan (`npm run dev`).
2. Jalankan perintah script uji coba:
   ```bash
   node scratch/test-crud.js
   ```