README.md

metadata

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:

cd backend-node
npm install

2. Setup Environment Variable

Buat file .env di dalam folder root backend-node dan isi sesuai dengan kebutuhan Anda:

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:

npx prisma generate

4. Jalankan Server Development

Jalankan server dalam mode development (menggunakan ts-node-dev untuk auto-reload):

npm run dev

Server akan berjalan di: http://localhost:5000

---

📂 Struktur Direktori Proyek

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:

   node scratch/test-crud.js