HJSys

# PRODUCT REQUIREMENT DOCUMENT (PRD) ## 1. PROJECT OVERVIEW - **System Name:** HJSys (Harapan Jaya Management System) - **Target Tech Stack:** Laravel 11.x, FilamentPHP v5, MySQL 8.0 - **Target Infrastructure:** Single VPS Ubuntu 22.04 LTS (Dockerized / Coolify / Native Nginx) - **Objective:** Mengotomatiskan seluruh siklus administrasi distributor—mulai dari procurement (PO Masuk), penjualan (PO Keluar/Invoice), manajemen stok otomatis, pelacakan piutang overdue, hingga kalkulasi presisi untuk keuntungan kotor (*gross profit*) dan komisi sales. --- ## 2. USER ROLES & ACCESS CONTROL | Role ID | Role Name | Tanggung Jawab & Hak Akses | | :--- | :--- | :--- | | `super-admin` | Super Admin / Owner | Akses penuh ke seluruh data, laporan keuangan, komisi sales, margin keuntungan, dan manajemen pengguna. | | `procurement` | Admin Procurement | Mengelola Master Supplier, Master Produk, dan Transaksi PO Masuk (Purchase Order ke Supplier). | | `finance_sales` | Admin Finance & Sales | Mengelola Master Client, PO Keluar, Invoice Penjualan, Pencatatan Pembayaran, dan Pelacakan Overdue. | | `salesman` | Salesman | Access Read-only / Draf input untuk PO Keluar dan melihat estimasi komisi pribadi. | --- ## 3. FASE 1: FITUR WAJIB (MVP - MUST HAVE) ### 3.1. Master Data Management - **Master Supplier:** `code`, `name`, `phone`, `address`, `top_days` (Term of Payment default). - **Master Client:** `code`, `name`, `owner_name`, `phone`, `delivery_address`, `tax_address`, `tax_number`, `credit_limit`, `top_days`. - **Master Salesman:** `code`, `name`, `phone`, `commission_rate` (Persentase default, misal `2.00`%). - **Master Produk:** - `sku`, `name`, `unit` (Dus/Pack/Pcs), `buy_price`, `sell_price`, `stock`. ### 3.2. Procurement / PO Masuk (Purchase Order) - **Status Lifecycle:** `draft` -> `sent` -> `received` -> `cancelled`. - **Field Utama:** `po_number`, `supplier_id`, `order_date`, `tax_type` (`non_ppn`, `include_ppn`, `exclude_ppn`), `tax_amount`, `total_amount`, `notes`. - **Item Transaksi:** `product_id`, `qty`, `buy_price`, `subtotal`. - **Automated Stock Rule:** Saat status PO Masuk berubah menjadi `received`, stok barang di `products.stock` **otomatis bertambah**. ### 3.3. Penjualan & Invoicing (Sales Order & Invoicing) - **Pemisahan Status Transaksi & Pembayaran:** - **Status Invoice:** `draft` -> `invoiced` -> `cancelled`. - **Status Payment:** `unpaid` -> `partially_paid` -> `paid` -> `overdue`. - **Field Utama:** `invoice_number`, `client_id`, `sales_rep_id`, `invoice_date`, `due_date`, `invoice_status`, `payment_status`, `tax_type`, `subtotal_amount`, `tax_amount`, `discount_amount`, `total_amount`, `paid_amount`, `gross_profit_total`. - **Item Transaksi:** `product_id`, `qty`, `buy_price_snapshot`, `sell_price_snapshot`, `discount_item`, `subtotal`, `gross_profit`. - **CRITICAL BUSINESS RULES:** 1. **Price Snapshotting:** Saat item dimasukkan ke invoice, system **WAJIB** menyimpan `buy_price_snapshot` dan `sell_price_snapshot` dari tabel `products`. Perubahan harga master produk di masa depan tidak boleh mengubah data histori invoice lama. 2. **Automated Stock Rule:** - Saat `invoice_status` diubah menjadi `invoiced`, stok barang di `products.stock` **otomatis berkurang**. - Jika invoice berstatus `invoiced` diubah menjadi `cancelled`, stok barang wajib **dikembalikan (rollback)** secara otomatis. ### 3.4. Keuangan, Piutang & Overdue Tracking - **Pencatatan Pembayaran:** Menampung riwayat cicilan/pembayaran per invoice (`sales_invoice_id`, `payment_date`, `amount`, `payment_method` [transfer/cash/giro], `reference_number`). - **Update Status Tagihan:** - Jika `paid_amount` = 0 -> Status `unpaid`. - Jika `paid_amount` < `total_amount` -> Status `partially_paid`. - Jika `paid_amount` >= `total_amount` -> Status `paid`. - **Automated Overdue Check:** Scheduled task (Cron Job) berjalan harian (pukul 00:01). Mengidentifikasi invoice berstatus `invoiced` dengan `payment_status` `unpaid` / `partially_paid` yang mana `now() > due_date`, kemudian memperbarui `payment_status` menjadi `overdue`. ### 3.5. Kalkulasi Keuntungan & Komisi Sales - **Rumus Keuntungan Kotor (Gross Profit):** $$\text{Gross Profit Item} = (\text{sell\_price\_snapshot} - \text{buy\_price\_snapshot}) \times \text{qty} - \text{discount\_item}$$ $$\text{Gross Profit Invoice} = \sum(\text{Gross Profit Item}) - \text{discount\_amount\_invoice}$$ - **Rumus Komisi Sales:** Calculated **HANYA** dari invoice berstatus `invoiced` dengan `payment_status` = `paid` (lunas). $$\text{Nilai Komisi} = \text{Total Nominal Invoice Lunas} \times \left( \frac{\text{sales\_rep.commission\_rate}}{100} \right)$$ ### 3.6. Export & Document Generation - **PDF Generation (`barryvdh/laravel-dompdf`):** - Cetak Surat Jalan menggunakan `delivery_address`. - Cetak Invoice Tagihan menggunakan `tax_address` dan menampilkan `tax_number`. - Cetak Purchase Order. - **Excel Export (`maatwebsite/excel`):** Export Rekap Penjualan, Laporan Overdue, dan Rincian Komisi Sales. --- ## 4. FASE 2: ROADMAP PENGEMBANGAN MASA DEPAN 1. **WhatsApp API Gateway:** Send PDF Invoice & Auto Reminder H-3 / H+1 Overdue. 2. **Multi-Warehouse Support:** Pelacakan stok di beberapa gudang terpisah dan fitur Transfer Stok. 3. **Modul Retur & Credit Note:** Penanganan barang rusak/retur toko yang memotong sisa tagihan piutang. 4. **Enforcement Limit Kredit:** Penguncian otomatis pembuatan invoice baru jika piutang toko melebihi `credit_limit`. 5. **Salesman Mobile Portal (PWA):** Tampilan khusus *smartphone* untuk input order langsung dari lokasi toko. 6. **Pencatatan Giro Mundur:** Pengelolaan pencairan giro dengan tanggal kliring resmi. --- ## 5. DATABASE SCHEMA (DBML) ```dbml Table users { id bigint [pk, increment] name varchar email varchar [unique] password varchar role enum('super-admin', 'procurement', 'finance_sales', 'salesman') created_at timestamp updated_at timestamp } Table suppliers { id bigint [pk, increment] code varchar [unique] name varchar phone varchar address text top_days int [default: 0] created_at timestamp updated_at timestamp } Table clients { id bigint [pk, increment] code varchar [unique] name varchar owner_name varchar phone varchar delivery_address text tax_address text [null] tax_number varchar [null] credit_limit decimal [default: 0] top_days int [default: 30] created_at timestamp updated_at timestamp } Table sales_reps { id bigint [pk, increment] user_id bigint [null, ref: > users.id] code varchar [unique] name varchar phone varchar commission_rate decimal [default: 2.00] created_at timestamp updated_at timestamp } Table products { id bigint [pk, increment] sku varchar [unique] name varchar unit varchar [default: 'Pcs'] buy_price decimal [default: 0] sell_price decimal [default: 0] stock int [default: 0] created_at timestamp updated_at timestamp } Table purchase_orders { id bigint [pk, increment] po_number varchar [unique] supplier_id bigint [ref: > suppliers.id] order_date date status enum('draft', 'sent', 'received', 'cancelled') [default: 'draft'] tax_type enum('non_ppn', 'include_ppn', 'exclude_ppn') [default: 'non_ppn'] tax_amount decimal [default: 0] total_amount decimal [default: 0] notes text [null] created_at timestamp updated_at timestamp } Table purchase_order_items { id bigint [pk, increment] purchase_order_id bigint [ref: > purchase_orders.id] product_id bigint [ref: > products.id] qty int buy_price decimal subtotal decimal } Table sales_invoices { id bigint [pk, increment] invoice_number varchar [unique] client_id bigint [ref: > clients.id] sales_rep_id bigint [ref: > sales_reps.id] invoice_date date due_date date invoice_status enum('draft', 'invoiced', 'cancelled') [default: 'draft'] payment_status enum('unpaid', 'partially_paid', 'paid', 'overdue') [default: 'unpaid'] tax_type enum('non_ppn', 'include_ppn', 'exclude_ppn') [default: 'non_ppn'] subtotal_amount decimal [default: 0] tax_amount decimal [default: 0] discount_amount decimal [default: 0] total_amount decimal [default: 0] paid_amount decimal [default: 0] gross_profit_total decimal [default: 0] notes text [null] created_at timestamp updated_at timestamp } Table sales_invoice_items { id bigint [pk, increment] sales_invoice_id bigint [ref: > sales_invoices.id] product_id bigint [ref: > products.id] qty int buy_price_snapshot decimal sell_price_snapshot decimal discount_item decimal [default: 0] subtotal decimal gross_profit decimal } Table payments { id bigint [pk, increment] sales_invoice_id bigint [ref: > sales_invoices.id] payment_date date amount decimal payment_method enum('transfer', 'cash', 'giro') reference_number varchar [null] notes text [null] created_at timestamp updated_at timestamp }