# Dokumentasi Area Member — Catatan Warung

Panduan ini menjelaskan cara menggunakan aplikasi **Catatan Warung** dari sisi **member** (pemilik warung). Area member dipakai untuk mencatat penjualan, pengeluaran, stok, laporan, dan mengelola profil warung.

**URL produksi:** https://catatanwarung.solusi-it.com

---

## Daftar Isi

1. [Ringkasan](#ringkasan)
2. [Memulai](#memulai)
3. [Navigasi Aplikasi](#navigasi-aplikasi)
4. [Dashboard](#dashboard)
5. [Transaksi](#transaksi)
6. [Stok Barang](#stok-barang)
7. [Laporan](#laporan)
8. [Profil & Data Warung](#profil--data-warung)
9. [Paket Langganan](#paket-langganan)
10. [Batasan per Paket](#batasan-per-paket)
11. [Pertanyaan Umum](#pertanyaan-umum)
12. [Referensi URL](#referensi-url)

---

## Ringkasan

Catatan Warung adalah aplikasi web untuk pemilik warung dan toko kelontong. Member dapat:

- Mencatat **penjualan** (manual atau dari stok barang)
- Mencatat **pengeluaran / catatan harian**
- Mengelola **inventori stok** (jika paket & mode warung mendukung)
- Melihat **laporan keuangan** dan mengekspor PDF (paket Premium+)
- Mengelola **hutang & piutang** (paket Standar+)
- Mengatur **profil warung** dan tampil di direktori publik (paket Premium+)

Aplikasi berjalan di browser (HP atau laptop). Tidak perlu instal aplikasi.

---

## Memulai

### Registrasi akun baru

1. Buka halaman depan (`/`) → klik **Mulai Gratis** atau buka langsung `/daftar`
2. Isi **nama**, **email**, dan **password** (minimal 6 karakter)
3. Atau klik **Daftar dengan Google** jika login Google sudah dikonfigurasi di server
4. Setelah berhasil, Anda otomatis masuk dan diarahkan ke **Dashboard**
5. Paket **Free** langsung aktif untuk akun baru

### Login

| Cara | URL | Keterangan |
|------|-----|------------|
| Email & password | `/login` | Akun yang didaftarkan manual |
| Google | Tombol di `/login` atau `/daftar` | Untuk akun yang terdaftar / di-link via Google |

**Catatan:**
- Akun yang hanya terdaftar via Google **tidak bisa** login dengan password — gunakan tombol Google
- Jika email sudah terdaftar dengan password, login Google akan **menghubungkan** akun yang sama

### Logout

- Klik **Keluar** di sidebar (desktop) atau tombol keluar di header mobile
- Atau akses `/logout`

### Akun demo (lingkungan development)

| | Nilai |
|--|-------|
| URL | `/login` |
| Email | `member@catatanwarung.com` |
| Password | `member123` |

Akun demo dibuat otomatis saat menjalankan `npm run db:init`.

---

## Navigasi Aplikasi

### Menu utama (desktop — sidebar)

| Menu | URL | Keterangan |
|------|-----|------------|
| Dashboard | `/dashboard` | Ringkasan bisnis harian |
| Transaksi | `/transaksi` | Penjualan, catatan, hutang/piutang |
| Stok Barang | `/stok` | Hanya tampil jika mode inventori aktif |
| Laporan | `/laporan` | Laporan keuangan |
| Langganan | `/langganan` | Info & pilihan paket |
| Panduan | `/bantuan` | Dokumentasi cara pakai aplikasi |
| Profil | `/profil` | Data akun & warung |

### Menu bawah (mobile)

Di layar kecil, navigasi utama ada di **bottom bar**: Beranda, Transaksi, Stok (jika aktif), Laporan, Paket, Panduan.

Profil diakses dari dashboard atau ketik `/profil` langsung.

### Halaman yang memerlukan login

Semua URL di bawah `/dashboard`, `/transaksi`, `/stok`, `/laporan`, `/langganan`, dan `/profil` memerlukan sesi member aktif. Jika belum login, Anda diarahkan ke `/login`.

---

## Dashboard

**URL:** `/dashboard`

Dashboard menampilkan ringkasan warung Anda:

- **Pendapatan hari ini** dan perbandingan dengan kemarin
- **Pendapatan bulan ini**
- **Grafik penjualan mingguan**
- **Transaksi terbaru**
- **Kategori penjualan teratas**
- **Aksi cepat**: Tambah Penjualan, Catatan Harian, Hutang Piutang, Semua Transaksi

Gunakan dashboard sebagai titik awal setiap hari untuk memantau performa warung.

---

## Transaksi

**URL:** `/transaksi`

Menu transaksi terbagi menjadi tiga bagian:

### 1. Penjualan

**Daftar:** `/transaksi/penjualan`  
**Tambah:** `/transaksi/penjualan/tambah`

#### Mode Tanpa Stok (semua paket)

Cocok jika Anda hanya ingin mencatat nominal penjualan tanpa mengurangi inventori:

1. Buka **Tambah Penjualan**
2. Pilih kategori (Makanan, Minuman, dll.)
3. Isi **deskripsi** (contoh: "Nasi goreng × 12")
4. Isi **jumlah (Rp)**
5. Pilih **tanggal** (default: hari ini)
6. Simpan

#### Mode Dari Stok (paket Standar+ & mode warung "Dengan Stok")

Jika fitur stok aktif, Anda bisa memilih tab **Dari Stok**:

1. Cari barang di inventori
2. Pilih barang → qty otomatis mengisi harga jual (bisa disesuaikan)
3. Stok barang **berkurang otomatis** setelah penjualan disimpan
4. Qty tidak boleh melebihi stok tersedia

> Menu stok dan opsi "Dari Stok" hanya muncul jika **paket** memiliki privilege inventori **dan** mode warung di profil diset **Dengan Stok**.

### 2. Catatan Harian

**Daftar:** `/transaksi/catatan`  
**Tambah:** `/transaksi/catatan/tambah`

Digunakan untuk mencatat **pengeluaran operasional** atau **pendapatan lain** di luar penjualan produk utama.

Contoh pengeluaran: beli gas, listrik, gaji karyawan, sewa.  
Contoh pendapatan lain: jasa titip, pendapatan sampingan.

### 3. Hutang & Piutang

**URL:** `/transaksi/hutang-piutang`  
**Tambah:** `/transaksi/hutang-piutang/tambah`

Fitur ini hanya tersedia jika paket Anda memiliki privilege **Hutang & Piutang** (Standar ke atas). Jika belum, Anda diarahkan ke halaman langganan.

| Jenis | Kegunaan |
|-------|----------|
| **Hutang** | Utang warung ke supplier / pihak lain |
| **Piutang** | Bon pelanggan yang belum lunas |

Setiap catatan bisa dilunasi sebagian atau seluruhnya. Status **aktif** ditampilkan di ringkasan menu transaksi.

---

## Stok Barang

Fitur stok hanya tersedia jika:

1. Paket langganan memiliki privilege **Inventori Stok**, **dan**
2. Di **Profil → Data Warung**, mode inventori diset **Dengan Stok**

Jika salah satu tidak terpenuhi, menu Stok disembunyikan dan akses `/stok` diarahkan ke halaman langganan.

### Daftar barang

**URL:** `/stok`

Fitur utama:

- Lihat semua barang dengan stok, harga beli/jual, nilai inventori
- Filter: **Semua**, **Menipis**, **Habis**, **Aktif**
- Filter per **kategori**
- **Mutasi stok** langsung dari daftar (stok masuk / keluar manual)
- Edit barang → `/stok/[id]/edit`

### Tambah barang

**URL:** `/stok/tambah`

Isi nama, kategori, satuan, stok awal, harga beli/jual, dan batas stok minimum (untuk peringatan "menipis").

Batas jumlah barang mengikuti paket (`max_barang`). Jika batas tercapai, penambahan barang ditolak — upgrade paket diperlukan.

### Stok Opname

**URL:** `/stok/opname`  
**Buat opname:** `/stok/opname/tambah`

Hanya tersedia paket **Premium** atau **Enterprise** (privilege `stok_opname`).

Alur opname:

1. Buat sesi opname baru
2. Untuk setiap barang, isi **stok fisik** (hasil hitung di warung)
3. Sistem menghitung **selisih** dengan stok di sistem
4. Setelah disimpan, stok sistem disesuaikan otomatis

---

## Laporan

**URL:** `/laporan`

Laporan menampilkan ringkasan keuangan warung dengan filter periode:

| Periode | Cakupan |
|---------|---------|
| Hari Ini | Transaksi hari berjalan |
| Minggu Ini | 7 hari terakhir |
| Bulan Ini | Bulan kalender berjalan |
| Semua | Seluruh riwayat |

### Isi laporan

- Total **penjualan**, **pengeluaran**, dan **laba/rugi**
- Grafik harian penjualan vs pengeluaran
- Rincian per kategori
- Daftar transaksi dalam periode

### Export PDF

Tombol **Export PDF** tersedia jika paket memiliki privilege **Export Laporan PDF** (Premium+). PDF dihasilkan di browser menggunakan data laporan yang sedang ditampilkan.

---

## Profil & Data Warung

**URL:** `/profil`

Halaman profil memiliki tiga tab:

### Tab Profil

- Ubah **nama** dan **email** akun member
- Lihat tanggal bergabung dan paket aktif

### Tab Data Warung

Kelola informasi warung yang ditampilkan ke publik (jika diaktifkan):

| Field | Keterangan |
|-------|------------|
| Nama warung | Nama tampilan |
| Deskripsi | Tentang warung |
| Kategori | Jajanan, sembako, dll. |
| Alamat lengkap | Dengan autocomplete kodepos |
| Telepon / WhatsApp | Kontak pelanggan |
| Koordinat GPS | Untuk peta |
| Jam & hari buka | Operasional |
| Foto URL | Link gambar warung |
| Mode inventori | **Tanpa Stok** atau **Dengan Stok** |
| Warung aktif | Nonaktifkan profil warung |
| Tampil publik | Muncul di direktori (perlu privilege) |

**Mode inventori:**

| Mode | Perilaku |
|------|----------|
| Tanpa Stok | Hanya penjualan manual; menu Stok disembunyikan |
| Dengan Stok | Inventori aktif; penjualan bisa dari stok; menu Stok tampil |

Opsi **Dengan Stok** hanya bisa dipilih jika paket memiliki privilege inventori.

**Warung publik:** Toggle **Tampil publik** hanya berfungsi jika paket memiliki privilege `warung_publik`. Tanpa privilege, opsi ditampilkan dengan pesan upgrade.

### Tab Password

- Ubah password akun (hanya akun email/password)
- Akun Google-only tidak memakai tab ini

---

## Paket Langganan

**URL:** `/langganan`

Halaman ini menampilkan:

- Paket aktif Anda saat ini
- Jumlah transaksi bulan ini (terhadap batas paket)
- Daftar semua paket dengan harga bulanan/tahunan
- Daftar fitur (privilege) tiap paket

### Paket yang tersedia

| Paket | Ringkasan |
|-------|-----------|
| **Free** | Mulai mencatat penjualan; batas 100 transaksi/bulan |
| **Standar** | Inventori stok, hutang/piutang; max 50 barang, 500 transaksi/bulan |
| **Premium** | + Stok opname, export PDF, warung publik; max 200 barang; transaksi tak terbatas |
| **Enterprise** | Semua fitur; barang & transaksi tak terbatas |

Harga default (bisa diubah admin):

| Paket | Bulanan | Tahunan |
|-------|---------|---------|
| Free | Rp 0 | Rp 0 |
| Standar | Rp 49.000 | Rp 490.000 |
| Premium | Rp 99.000 | Rp 990.000 |
| Enterprise | Rp 299.000 | Rp 2.990.000 |

### Cara upgrade

Saat ini upgrade dilakukan **melalui admin** setelah konfirmasi pembayaran/transfer. Tombol **Pilih [Paket]** di halaman langganan menampilkan informasi kontak — pembayaran online belum tersedia.

Admin back office mengassign paket di **Kelola Member**.

---

## Batasan per Paket

Privilege yang mempengaruhi pengalaman member:

| Privilege | Dampak jika tidak aktif |
|-----------|-------------------------|
| `inventori_stok` | Tidak bisa mode "Dengan Stok", menu Stok disembunyikan |
| `stok_opname` | Akses `/stok/opname` diarahkan ke langganan |
| `hutang_piutang` | Menu Hutang & Piutang disembunyikan |
| `laporan_pdf` | Tombol Export PDF di laporan tidak tampil |
| `warung_publik` | Tidak bisa mengaktifkan warung di direktori publik |
| `max_barang` | Batas jumlah produk di stok (0 = tak terbatas) |
| `max_transaksi_bulan` | Batas total transaksi per bulan (0 = tak terbatas) |

Batas dicek otomatis saat menambah barang atau transaksi.

---

## Pertanyaan Umum

### Apakah bisa dipakai di HP?

Ya. Tampilan mobile dirancang untuk dipakai di warung: header ringkas, tombol besar, menu bawah tetap.

### Apakah data antar member tercampur?

Tidak. Setiap member hanya melihat data warung milik sendiri. Data diisolasi per `member_id`.

### Kenapa menu Stok tidak muncul?

Periksa dua hal:

1. Paket Anda harus memiliki **Inventori Stok** (Standar+)
2. Di **Profil → Data Warung**, mode harus **Dengan Stok**

### Kenapa tidak bisa tambah barang lagi?

Anda mungkin mencapai batas `max_barang` paket. Cek halaman **Langganan** atau upgrade paket.

### Kenapa transaksi ditolak?

Bisa karena batas `max_transaksi_bulan` pada paket Free (100/bulan). Upgrade ke paket lebih tinggi untuk limit lebih besar atau tak terbatas.

### Bagaimana jika lupa password?

Saat ini reset password dilakukan manual oleh admin. Fitur lupa password belum tersedia di aplikasi.

### Apa bedanya Back Office dan Member?

| | Member | Back Office |
|--|--------|-------------|
| URL login | `/login` | `/backoffice/login` |
| Pengguna | Pemilik warung | Admin platform |
| Fungsi | Catat & kelola warung sendiri | Kelola semua member, paket, landing page |

---

## Referensi URL

### Publik (tanpa login)

| URL | Halaman |
|-----|---------|
| `/` | Landing page |
| `/daftar` | Registrasi member |
| `/login` | Login member |
| `/auth/google` | Redirect OAuth Google |

### Member (perlu login)

| URL | Halaman |
|-----|---------|
| `/dashboard` | Dashboard |
| `/transaksi` | Menu transaksi |
| `/transaksi/penjualan` | Daftar penjualan |
| `/transaksi/penjualan/tambah` | Tambah penjualan |
| `/transaksi/catatan` | Daftar catatan harian |
| `/transaksi/catatan/tambah` | Tambah catatan |
| `/transaksi/hutang-piutang` | Hutang & piutang |
| `/transaksi/hutang-piutang/tambah` | Tambah hutang/piutang |
| `/stok` | Daftar barang |
| `/stok/tambah` | Tambah barang |
| `/stok/opname` | Daftar opname |
| `/stok/opname/tambah` | Buat opname |
| `/laporan` | Laporan keuangan |
| `/langganan` | Paket langganan |
| `/bantuan` | Panduan / dokumentasi member |
| `/profil` | Profil & warung |
| `/logout` | Keluar |

---

## Alur Kerja Disarankan (Pemula)

```
Daftar / Login
      ↓
Isi Profil & Data Warung  (/profil)
      ↓
Catat penjualan harian    (/transaksi/penjualan/tambah)
      ↓
Catat pengeluaran         (/transaksi/catatan/tambah)
      ↓
Pantau dashboard          (/dashboard)
      ↓
Lihat laporan mingguan    (/laporan)
```

Jika paket Standar+ dan ingin kelola inventori:

```
Aktifkan mode "Dengan Stok" di profil
      ↓
Tambah barang di Stok     (/stok/tambah)
      ↓
Jual dari stok            (/transaksi/penjualan/tambah → Dari Stok)
      ↓
Opname berkala (Premium+) (/stok/opname)
```

---

*Dokumen ini mengacu pada versi aplikasi di repository `catatan-warung`. Jika ada perbedaan di lingkungan produksi, hubungi administrator platform.*