# 📘 Panduan Lengkap — Sistem Distribusi Telur

Panduan ini menjelaskan cara **memasang, menjalankan, dan memakai** aplikasi dari
nol. Ditulis untuk orang awam — ikuti langkah demi langkah.

---

## 1. Apa Ini?

Aplikasi web untuk mengelola distribusi telur **multi-cabang**. Ada 4 peran:

| Peran | Tugas |
|---|---|
| **Super Admin (Pusat)** | Beli telur dari petani, atur stok gudang pusat, sebar ke cabang, atur harga, pantau semua cabang, kelola akun & produk. |
| **Owner / Approver** | Lihat laporan & pantau (read-only), kirim pesan ke cabang. |
| **Admin Cabang** | Buat order, kelola stok cabang, kelola pelanggan, kirim barang ke kurir. |
| **Kurir** | Terima tugas antar, upload foto bukti, tandai selesai. |

---

## 2. Yang Harus Disiapkan (Prasyarat)

1. **Komputer** Windows / Mac / Linux.
2. **Node.js versi 18.18 atau lebih baru.** Cek dengan buka terminal / CMD:
   ```bash
   node -v
   ```
   Kalau belum ada, unduh dari <https://nodejs.org> (pilih versi **LTS**).
3. **Git** (untuk mengambil kode). Unduh dari <https://git-scm.com>.

---

## 3. Cara Memasang (Install)

Buka terminal (CMD / PowerShell / Terminal), lalu jalankan baris per baris:

```bash
# 1. Ambil kode dari GitHub
git clone https://github.com/FalahALL/distribusi-telur
cd distribusi-telur

# 2. Pasang semua kebutuhan aplikasi (butuh internet, sekali saja)
npm install

# 3. Siapkan file konfigurasi
cp .env.example .env
# (di Windows CMD gunakan:  copy .env.example .env )

# 4. Buat database + isi data contoh
npm run setup

# 5. Jalankan aplikasi
npm run dev
```

Setelah langkah ke-5, buka browser ke **<http://localhost:3000>**
(kalau port 3000 dipakai aplikasi lain, otomatis pindah ke 3001 — lihat pesan di
terminal).

> **Sudah pernah clone & mau update kode terbaru?**
> ```bash
> git pull            # ambil perubahan terbaru
> npm install         # kalau ada dependency baru
> npm run db:migrate  # terapkan perubahan struktur database (data lama aman)
> npm run dev
> ```

---

## 4. Akun Demo (untuk mencoba)

Password semua akun: **`password123`**

| Login (email ATAU no. HP) | Peran |
|---|---|
| `superadmin@telur.local` | Super Admin |
| `owner@telur.local` | Owner / Approver |
| `admin1@telur.local` … `admin5@telur.local` | Admin Cabang (5 cabang) |
| `kurir1@telur.local` … `kurir5@telur.local` | Kurir 1 tiap cabang |
| `kurir1b@telur.local` … `kurir5b@telur.local` | Kurir 2 tiap cabang |

> **Login bisa pakai no. HP** yang diset Super Admin, bukan cuma email.
> Contoh: admin1 punya no. HP `081200000001`.

---

## 5. Alur Kerja Sehari-hari

### A. Super Admin (Pusat) — buka **Dashboard**
1. **Beli Telur** → input pembelian dari petani (nama petani, jenis telur,
   jumlah peti, harga beli). Stok masuk ke gudang pusat.
2. **Sebar ke Cabang** → bagikan stok pusat ke cabang (mis. Cabang 1 = 200 peti,
   Cabang 2 = 100 peti).
3. **Atur Harga & Produk** → set harga jual per peti (berlaku semua cabang),
   bisa juga **jadwalkan harga besok** yang otomatis aktif. Tambah/edit/
   nonaktifkan produk di sini juga.
4. Pantau: omset + jumlah terjual (hari/minggu/bulan), stok gudang pusat
   (kemarin vs sekarang), **grafik tren** (bisa pilih 7 hari / bulanan /
   triwulan / caturwulan / 1 tahun), dan notifikasi stok kritis.
5. **💬 Pesan ke Cabang** (paling bawah) → chat langsung dengan admin cabang.

### B. Admin Cabang — buka **Panel Cabang**
1. Tab **Dashboard**: lihat stok cabang langsung + buat order baru
   (pilih pelanggan → **ketuk produk** untuk menambah → simpan). Stok otomatis
   direservasi.
2. **Kirim ke Kurir**: pilih kurir cabang (Kurir 1 / Kurir 2). Alamat & no. HP
   tujuan **otomatis ikut data pelanggan** (tidak perlu ketik ulang). Sebelum
   kirim, tampil tabel **tugas kurir** (sudah/sedang mengantar ke siapa).
3. Tab **Stok**: kelola stok (barang masuk, penyesuaian, retur).
4. Tab **Pelanggan**: tambah/edit/hapus pelanggan (hapus butuh konfirmasi).
5. Tab **💬 Pesan ke Pusat**: balas pesan dari Pusat.

### C. Kurir — buka halaman **Kurir**
1. Antrian tugas muncul → **Berangkat** → **Upload Foto & Selesai**.
2. Status jadi *terkirim*, stok keluar tercatat otomatis.

---

## 6. Fitur Penting Lain

- **🔔 Lonceng notifikasi** (kanan atas): tanda ada pesan masuk yang belum
  dibaca. Klik → langsung ke area pesan.
- **Login tersimpan**: setelah login, perangkat "diingat" — lain kali cukup klik
  "Lanjutkan sebagai …" tanpa ketik ulang. Reset otomatis sesuai pengaturan.
- **Hapus otomatis pesan lama**: Super Admin bisa set pesan dihapus otomatis
  (harian/mingguan/bulanan/tahunan) agar database tetap ringan.
- **Verifikasi dua langkah** untuk aksi berbahaya (hapus akun, hapus pelanggan).

---

## 7. Perintah npm yang Sering Dipakai

| Perintah | Fungsi |
|---|---|
| `npm run dev` | Jalankan aplikasi (mode pengembangan) |
| `npm run setup` | Pasang database baru + isi data contoh (sekali di awal) |
| `npm run db:seed` | Isi ulang data contoh |
| `npm run db:migrate` | Terapkan perubahan struktur database |
| `npm run db:reset` | **Hapus semua data** & isi ulang dari awal (hati-hati!) |
| `npm run db:studio` | Buka tampilan database (GUI) di browser |
| `npm run build` | Siapkan versi produksi |
| `npm run start` | Jalankan versi produksi (setelah `build`) |
| `npm run typecheck` | Cek error TypeScript |

---

## 8. Masalah Umum & Solusi

| Masalah | Solusi |
|---|---|
| `node: command not found` | Node.js belum terpasang → pasang dari nodejs.org |
| Port 3000 dipakai | Aplikasi otomatis pindah ke 3001, atau matikan aplikasi lain di port 3000 |
| Halaman lama muncul terus (padahal sudah update) | Aplikasi ini PWA — refresh keras (Ctrl+Shift+R) atau hapus cache browser |
| `EPERM ... query_engine ...dll` saat migrasi (Windows) | Hentikan dulu `npm run dev`, jalankan migrasi, baru nyalakan lagi |
| Lupa password akun | Login sebagai Super Admin → Akun → Edit → isi Password baru |

Lihat juga:
- **[02-PANDUAN-HOSTING.md](02-PANDUAN-HOSTING.md)** — cara online-kan ke hosting.
- **[03-PANDUAN-DATABASE.md](03-PANDUAN-DATABASE.md)** — pindah SQLite → PostgreSQL & backup.