sembara/PRD.md

PRD — BerasPro

Produk: Sembara — Kelola Stok Beras dan Kebutuhan Sembako Versi dokumen: 1.1 (amandemen hasil sesi grilling 2026-08-25) Tanggal: 2026-08-25 Status: Aktif

Catatan amandemen v1.1: stack frontend diubah menjadi Filament-only; akses data dikunci ke REST API InsForge (JWT per-user); model data disamakan dengan skema live proyek InsForge yang sudah ter-deploy dan berisi data nyata.

---

1. Ringkasan (Overview)

Sembara adalah aplikasi web untuk pengelolaan stok beras dan pesanan pelanggan pada bisnis distribusi/grosir beras. Aplikasi membantu tim operasional mencatat master produk, memantau stok dan mutasinya, memproses sales order dari awal hingga selesai, mencetak surat jalan (delivery note), menangani komplain pelanggan, dan melihat laporan penjualan.

Target pengguna: pemilik/usaha beras skala kecil–menengah dengan 2 peran internal — admin dan operator.

2. Masalah

Pengelolaan bisnis beras yang masih manual (buku/Excel) menimbulkan:

• Selisih stok tidak terlacak (tidak ada riwayat mutasi stok).
• Pesanan hilang atau dobel-proses karena tidak ada alur status yang jelas.
• Stok tidak otomatis berkurang saat order selesai → oversell.
• Komplain pelanggan tidak tercatat dan tidak ada penanggung jawab.
• Laporan penjualan sulit disusun.

3. Tujuan & Ukuran Sukses

Tujuan	Metrik sukses
Stok akurat	Setiap perubahan stok tercatat di stock_movements; selisih fisik vs sistem = 0 pada rekonsiliasi bulanan
Pesanan tertib	100% order melewati alur status valid (pending → processing → delivering → completed / cancelled)
Tanpa oversell	Stok hanya berkurang sekali per order (idempotent), duplikat proses ditolak/dilewati
Keluhan terselesaikan	Semua komplain berstatus open/resolved dengan jejak kepemilikan
Laporan cepat	Ringkasan penjualan & stok tersedia dari halaman Reports tanpa olah manual

4. Pengguna & Peran

4.1 Admin

• Mengelola user/operator.
• Mengelola master produk dan stok (penyesuaian/restok).
• Menyetujui/memproses/menyelesaikan/membatalkan order; menghapus order (soft-delete deleted_at).
• Melihat semua keluhan dan menutupnya.
• Mengakses laporan, log aktivitas, dan manajemen user.

4.2 Operator

• Membuat dan mengubah pesanan.
• Mengelola data pelanggan.
• Menutup keluhan miliknya sendiri saja (validasi kepemilikan created_by).
• Tidak dapat menghapus order, mengelola user, mengubah master produk/stok, atau mengakses laporan.

4.3 Pelanggan (indirek)

Tidak login. Datanya dikelola operator sebagai customers; komplain atas nama pelanggan dicatat lewat modul Complaints.

5. Fitur & Kebutuhan Fungsional

5.1 Autentikasi & Otorisasi

• F1 — Login/logout berbasis sesi server-side. Autentikasi terjadi di InsForge (POST /api/auth/sessions). Access token (JWT) + refresh token disimpan dalam sesi Laravel terenkripsi (SESSION_DRIVER=file) dan di-refresh otomatis oleh middleware saat mendekati kedaluwarsa. Profil user diambil dari tabel users proyek (role, is_active).
• F2 — Role-based access. Dua peran: admin, operator — kolom enum users.role. Diimplementasi via policy + Gate Laravel (Gate::before untuk admin). Satu panel Filament /admin; menu dan aksi difilter per ability; akses langsung ditolak 403.
• Kriteria terima:
  • User belum login dialihkan ke halaman login.
  • Operator yang mengakses fitur admin mendapat 403.

5.2 Produk

• F3 — Master produk (CRUD, admin). Atribut sesuai skema live: code, name, unit, weight, stock_minimum, cost_price, is_active.
• Harga jual tidak disimpan di master produk; harga transaksi ditetapkan per baris item pada order_items.unit_price.
• Kriteria terima: produk tampil di daftar, dapat dibuat/diedit; produk dipakai di order tetap konsisten (harga order tersimpan pada item).

5.3 Stok

• F4 — Stok per produk. Melihat kuantitas tersedia per produk (stocks.quantity, denormalisasi terkontrol).
• F5 — Penyesuaian/restok stok (admin). Mencatat penambahan (restok) atau koreksi; setiap perubahan menghasilkan baris mutasi dan update saldo dalam satu operasi.
• F6 — Riwayat mutasi stok (stock_movements). Kolom: product_id, type (mis. restock, adjustment, order_out), quantity, reference_type/reference_id, notes, created_by, waktu.
• Kriteria terima: saldo stok selalu = hasil agregat mutasi (rekonsiliasi); riwayat dapat difilter/dilihat per produk.

5.4 Pelanggan

• F7 — CRUD pelanggan. Dapat dilakukan operator dan admin. Kolom live: customer_code (CUST-XXXX), nama, alamat, telepon, catatan.
• Kriteria terima: pelanggan dapat dipilih saat membuat order; penghapusan diblokir jika masih direferensikan order.

5.5 Pesanan (Sales Order)

• F8 — CRUD order + item order. Satu order memiliki ≥1 item (order_items: produk, qty, unit_price, subtotal). Nomor order otomatis ORD-YYYYMMDD-XXXX (sequence harian, immutable).
• F9 — Alur status (orders.order_status): pending → processing → delivering → completed, alternatif cancelled hanya dari pending/processing oleh admin atau operator pembuat (created_by). Transisi forward-only, tidak boleh mundur; completed bersifat immutable.
• F10 — Pengurangan stok otomatis & idempotent. Saat order menjadi completed: fungsi RPC di InsForge menyisipkan mutasi order_out (partial unique index stock_movements(reference_type, reference_id) sebagai gerbang idempotensi — duplikat dilewati) lalu decrement stocks.quantity, secara atomik.
• F11 — Cetak surat jalan (PDF) via barryvdh/laravel-dompdf, pratinjau/stream di /orders/{id}/delivery-note, nomor berformat SJL-YYYY/MM/DD-<order_number>; aksi aktif saat status delivering/completed.
• F12 — Hapus order (soft-delete deleted_at) hanya oleh admin.
• F13 — Riwayat status (order_status_histories). Setiap perubahan status tercatat dengan old_status, new_status, changed_by, waktu, catatan.
• Data pendukung (skema live): order_date, delivery_date, driver_id, payment_method (mis. cash), payment_status (mis. paid/unpaid), survey_status (survei kepuasan pasca-penerimaan barang; diisi setelah order completed), notes, completed_at.
• Validasi dua gerbang oversell: qty divalidasi terhadap saldo saat create/update order dan saat transisi ke completed (stok kurang → transisi ditolak dengan pesan jelas).
• Kriteria terima:
  • Order tidak bisa completed jika transisi tidak valid.
  • Proses ulang "completed" pada order yang sama tidak mengurangi stok dua kali.
  • Driver/pengiriman dapat ditetapkan pada order (integrasi modul Drivers).

5.6 Pengemudi (Drivers)

• F14 — Master driver (admin). Kolom live: driver_code (DRV-XXXX), nama, telepon, is_active, catatan.

5.7 Keluhan (Complaints)

• F15 — Catat komplain pelanggan, terhubung ke order/pelanggan. Nomor CMP-YYYYMMDD-XXXX. Status: open / resolved; kolom pendukung live: category, priority, resolution, resolved_at.
• F16 — Validasi kepemilikan: operator hanya boleh menutup keluhan miliknya (created_by); admin bebas. Penutupan mengisi resolution + resolved_at.
• Kriteria terima: transisi status keluhan tervalidasi; penutupan oleh pihak salah ditolak 403.

5.8 Dashboard & Laporan

• F17 — Dashboard statistik ringkas untuk user login — empat widget: jumlah order per status, tabel stok kritis (quantity <= stock_minimum), komplain open berjalan, daftar pesanan terbaru.
• F18 — Laporan (khusus admin): (1) ringkasan penjualan — filter periode, total & per produk; (2) posisi stok + riwayat mutasi. Ekspor CSV/laba masuk backlog.

5.9 Manajemen User

• F19 — Kelola user (khusus admin): daftar, tambah (via admin API InsForge), ubah role/nonaktifkan (is_active).

6. Model Data

Sumber kebenaran skema = proyek InsForge live (dikelola via migrasi SQL InsForge, bukan migrasi Laravel). PK UUID di semua tabel; *_by mereferensi auth.users(id); waktu disimpan UTC, ditampilkan Asia/Jakarta.

Tabel	Kolom utama (skema live)
users	id, name, email, password (hash mirror), role (admin/operator), is_active
customers	id, customer_code, name, address, phone, notes
products	id, code, name, unit, weight, stock_minimum, cost_price, is_active
stocks	id, product_id, quantity (saldo denormalized), updated_at
stock_movements	id, product_id, type, quantity, reference_type, reference_id, notes, created_by — partial unique index (reference_type, reference_id)
orders	id, order_number, order_date, delivery_date, delivery_note_number, customer_id, driver_id, payment_method, payment_status, order_status, survey_status, notes, completed_at, created_by, deleted_at
order_items	id, order_id, product_id, quantity, unit_price, subtotal
order_status_histories	id, order_id, old_status, new_status, changed_by, notes
complaints	id, complaint_number, customer_id, order_id, complaint_date, category, description, status, priority, resolution, resolved_at, created_by
drivers	id, driver_code, name, phone, is_active, notes
activity_logs	id, user_id, action, entity_type, entity_id, description

Row Level Security (RLS) tetap aktif di sisi InsForge sebagai lapisan pertahanan kedua; seluruh panggilan data plane membawa JWT user (lihat §8).

7. Alur Utama

7.1 Siklus order (happy path)

1. Operator membuat order (pilih pelanggan, tambah item produk+qty+harga; sistem validasi saldo stok).
2. pending → diproses (processing) → siap kirim (delivering, tetapkan driver) → completed (RPC idempotent: mutasi order_out + decrement stok atomik).
3. Operator/admin cetak surat jalan PDF (SJL-…) untuk diserahkan pengemudi.
4. Setelah barang diterima: survey_status (survei kepuasan) dapat dicatat.
5. Bila batal: cancelled (hanya dari pending/processing) tanpa efek stok.

7.2 Penanganan komplain

1. Operator mencatat komplain pelanggan (status open, nomor CMP-…).
2. Pemilik komplain atau admin menindaklanjuti, mengisi resolution, lalu menutup (resolved, resolved_at terisi).

8. Kebutuhan Non-Fungsional

Kategori	Persyaratan
Arsitektur	Laravel 12 + Filament 5 (server-rendered, panel tunggal); InsForge cloud sebagai satu-satunya backend data & auth via REST (/api/database/records/*, RPC); tanpa database lokal
Identitas akses	Data plane memakai JWT user hasil login (RLS InsForge aktif sebagai lapis kedua); API key admin (ik_…) hanya untuk provisioning (manajemen user, seed)
Keamanan	Sesi server-side (SESSION_DRIVER=file, terenkripsi); otorisasi policy/Gate; kredensial hanya di .env (tidak dikomit)
Konsistensi data	Idempotensi stok wajib (unique index gerbang mutasi via RPC); validasi transisi status di server
Performa	List terpaginasi server-side (offset/limit); query REST selalu menyebut kolom (select=…) dan dibatasi limit
Zona waktu	Simpan UTC, tampilkan Asia/Jakarta
Auditability	order_status_histories, stock_movements, activity_logs (ditulis service ActivityLogger: action snake-case EN, deskripsi ID)
Testability	PHPUnit (±23 tes) dengan InsForgeFake untuk HTTP fake; suite Authentication, Authorization, OrderFlow (termasuk idempotensi stok), ComplaintFlow

9. Teknologi

• Backend: PHP ^8.2, Laravel 12, Filament 5, laravel-dompdf (surat jalan PDF).
• Frontend: Filament resources/pages (Blade + Livewire bawaan), Tailwind CSS.
• Backend-as-a-Service: InsForge (Postgres + PostgREST-style REST, auth JWT, RLS) — client wrapper app/Services/InsForge/InsForgeClient.php di atas HTTP client Laravel.
• Testing: PHPUnit + tests/Support/InsForgeFake.php.
• Dibuang dari v1.0: Inertia, Vue, TypeScript, Sanctum, Ziggy (tidak dipakai; UI sepenuhnya Filament).

10. Batasan (Out of Scope)

• Portal/e-commerce pelanggan mandiri (pelanggan tidak login).
• Pembayaran online / invoice faktur pajak (kolom pembayaran hanyalah pencatatan manual status/method).
• Multi-gudang / multi-lokasi stok.
• Notifikasi WhatsApp/email otomatis.
• Aplikasi mobile native untuk driver.

11. Rencana Lanjutan (Backlog)

• Notifikasi status order ke pelanggan.
• Laporan laba (cost_price vs unit_price) dan ekspor Excel/CSV.
• Alert otomatis (notifikasi) minimum-stock di dashboard — saat ini baru widget daftar stok kritis.
• Restore UI untuk order soft-deleted.
• Chart tren penjualan di dashboard.

12. Akun Demo (seed)

Seed historis 20260818032150_seed-initial-data.sql di proyek InsForge:

Role	Email	Catatan
Admin	admin@beraspro.test	Password live berbeda dari dokumen v1.0 (terverifikasi 401)
Operator	operator@beraspro.test	Password live tidak diketahui dokumen ini

Akun integrasi khusus pengembangan (dibuat via admin API, fase 0):

Role	Email	Password
Admin	dev@beraspro.test	acak, dilaporkan sekali, disimpan di .env

Jangan komit password ke repository; simpan hanya di .env lokal.

13. Keputusan Arsitektur (hasil grilling 2026-08-25)

1. Backend tunggal InsForge cloud live; tidak ada DB lokal dan tanpa koneksi Postgres langsung (port tidak diekspos).
2. UI sepenuhnya Filament (panel /admin, label bahasa Indonesia); Inertia/Vue/Sanctum/Ziggy dihapus dari rencana.
3. Skema live adalah sumber kebenaran — aplikasi menyesuaikan konvensi live: nomor ORD-/SJL-/CMP-, kolom order_status/survey_status/pembayaran, soft-delete deleted_at, harga jual per item.
4. Panggilan data membawa JWT user (RLS hidup); refresh token disimpan di sesi server dan di-refresh otomatis; API key admin hanya untuk provisioning.
5. Alur order forward-only; cancelled hanya dari pending/processing oleh admin/pembuat; completed immutable; pengurangan stok lewat RPC idempotent saat completed.
6. Uang integer rupiah tanpa desimal; UUID untuk semua PK; audit via ActivityLogger.
7. Implementasi bertahap 0–6 (fondasi → auth → master → stok → order+PDF → komplain → dashboard/laporan/user), tiap fase diakhiri suite hijau.