Sistem manajemen keuangan internal untuk WHUSNET — mengelola transaksi rembush (reimbursement) & pengajuan pembelian, dengan fitur OCR otomatis menggunakan AI (Gemini via n8n), alur approval multi-level, serta dashboard analitik real-time.

Version: 4.5.0 | Laravel: 12 | PHP: 8.4 | Last Updated: 4 Mei 2026

• 📖 Documentation Index - Central hub untuk semua dokumentasi
• ⚡ Quick Start (5 min) - Setup cepat untuk development
• 🤝 Contributing Guide - Panduan kontribusi
• 🔧 Troubleshooting - Solusi masalah umum
• 📝 Changelog - Version history

• Fitur Utama
• Tech Stack
• Arsitektur Sistem
• Persyaratan
• Instalasi & Setup
• Konfigurasi Environment
• Struktur Project
• Peran Pengguna (Roles)
• Modul Aplikasi
• Alur Transaksi
• API Endpoints
• Event & Notifikasi
• Perintah Berguna
• 📚 Dokumentasi Lengkap

• PHP 8.4 + Laravel 12

• Scramble — Automated API documentation (OpenAPI 3.1)

• MySQL 8.0 — Database utama

• Redis 7.2 — Cache, session, queue, rate limiter, ID generator

• Laravel Horizon — Monitoring & manajemen queue worker

• Laravel Reverb — WebSocket server untuk notifikasi real-time

• Blade Templates — Server-side rendering dengan logic role-based.
• Tailwind CSS v4 — Modern utility-first CSS framework.
• Vite — Asset bundling & HMR.
• Vanilla JS & Axios — AJAX interactions & real-time UI synchronization.

• Docker & Docker Compose — Containerized deployment
• Nginx — Reverse proxy & web server
• n8n — Workflow automation untuk OCR processing

• Google Gemini AI — OCR untuk ekstraksi data nota (via n8n webhook)

graph TD
    A[Frontend/User] -->|Upload| B(Laravel API /v1/nota/upload)
    B -->|Dispatch Job| C{Redis Queue}
    C -->|Trigger| D[n8n Workflow]
    
    subgraph n8n_Logic [Security & AI Extraction]
        D1[Layer 1: Duplicate Detection] --> D2[Layer 2: Date Logic Check]
        D2 --> D3[Layer 3: Gemini AI Extraction]
        D3 --> D4[Layer 4: Payment Verification]
    end
    
    D --> n8n_Logic
    D4 -->|Callback| E[Laravel API /ai/auto-fill]
    E -->|Broadcast| F[Laravel Reverb WS]
    F -->|Real-time UI| A
    E -->|Notify| G[Telegram / Push Notif]

1. Upload: User upload foto nota.
2. Security Check (L1 & L2): Sistem mengecek duplikasi hash file dan validitas tanggal (maks 2 hari).
3. AI Extraction (L3): Gemini mengekstrak Vendor, Item, dan Nominal. User melengkapi kategori & alokasi cabang.
4. Approval: Admin/Atasan menyetujui. Jika nominal ≥ 1 Jt, memerlukan approval Owner.
5. Payment: Admin upload bukti bayar (Transfer/Cash).
6. Verification (L4):
   • Transfer: AI mengecek nominal struk vs transaksi. Jika selisih, status menjadi flagged.
   • Cash: Teknisi konfirmasi terima uang via Telegram Bot.

1. Input: Teknisi input detail pengajuan. Sistem menyimpan snapshot original.
2. Management Review: Owner/Atasan dapat merevisi item/nominal. Sistem menandai is_edited_by_management = true.
3. Transparency: Semua user dapat melihat perbandingan antara "Versi Pengaju" dan "Versi Management" melalui toggle di modal detail.
4. Payment holding: Transaksi beralih ke waiting_payment setelah disetujui. Saat invoice diupload, status akan tetap waiting_payment jika terdapat cabang yang masih berhutang (inter-unit debt).
5. Finalization: Status otomatis menjadi completed hanya setelah invoice terunggah DAN seluruh hutang antar cabang telah dilunaskan. Pengeditan kini dikunci total.

1. Input: Staff internal (Admin/Owner) input belanja gudang.
2. Review Management: Persetujuan oleh Management. Status menjadi pending -> waiting_payment.
3. Payment: Upload bukti bayar (Tanpa OCR).
4. Finalization: Status langsung menjadi completed tanpa perlu konfirmasi Telegram teknisi.

Sistem menerapkan 4-Layer Verification untuk menjamin validitas keuangan:

1. Layer 1 (Duplicate): Pengecekan MD5 hash file nota di Redis/DB untuk mencegah nota ganda.
2. Layer 2 (Date Logic): Nota berumur > 2 hari kalender otomatis berstatus auto-reject (dapat di-override oleh Admin/Owner).
3. Layer 3 (AI Extraction): Gemini Pro mengekstrak data dengan parameter confidence. Status low-confidence memerlukan review manual.
4. Layer 4 (Payment Audit): Verifikasi nominal pada struk transfer. Jika tidak cocok, transaksi di-flag dan memerlukan Force Approve dengan alasan tertulis.

Sistem pencarian transaksi dirancang untuk performa optimal pada berbagai skala data:

1. Threshold: 5.000 records benchmark.
2. Mode Client-Side (< 5k): Seluruh data dimuat ke frontend (lean version) untuk pencarian instan tanpa latency server.
3. Mode Server-Side (≥ 5k): Sistem beralih ke paginasi database standar untuk menjaga penggunaan memori browser tetap rendah.
4. Auto-Adaptive: Setiap pemuatan halaman melakukan pengecekan jumlah data via /transactions/count untuk menentukan mode terbaik secara otomatis.

Bot Telegram digunakan sebagai jembatan komunikasi real-time:

• Teknisi: Menerima notifikasi pembayaran cash dan tombol ✅ Konfirmasi Terima.
• Admin/Owner: Menerima alert 🚨 Selisih Nominal atau ⛔ Auto-Reject.
• Owner: Menerima notifikasi untuk Force Approve pada transaksi yang di-flag.
• Broadcast: Pengiriman pesan ke seluruh staf atau role tertentu.

• Docker ≥ 20.x & Docker Compose ≥ 2.x
• Git

Semua dependency lainnya (PHP, Node, MySQL, Redis, dll.) sudah termasuk dalam Docker containers.

git clone <repository-url>
cd Admin-Payment

cp .env.example .env

Edit file .env sesuai konfigurasi (lihat bagian Konfigurasi Environment).

docker-compose up -d --build

# Masuk ke container app
docker exec -it whusnet-app bash

# Install dependencies
composer install

# Generate application key
php artisan key:generate

# Jalankan migrasi database
php artisan migrate

# Buat symbolic link untuk storage
php artisan storage:link

# (Opsional) Jalankan seeder
php artisan db:seed

Variabel penting yang perlu dikonfigurasi di file .env:

# ── Aplikasi ──────────────────────────────────────────
APP_NAME="WHUSNET Admin Payment"
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost:8000

# ── Database ──────────────────────────────────────────
DB_CONNECTION=mysql
DB_HOST=whusnet-db          # nama container Docker
DB_PORT=3306
DB_DATABASE=admin-payment
DB_USERNAME=admin
DB_PASSWORD=root

# ── Redis ─────────────────────────────────────────────
REDIS_HOST=redis             # nama container Docker
REDIS_PORT=6379
REDIS_PASSWORD=<your-redis-password>

# ── Session, Cache, Queue (gunakan Redis) ─────────────
CACHE_DRIVER=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redis

# ── Broadcasting (Reverb WebSocket) ───────────────────
BROADCAST_CONNECTION=reverb
REVERB_APP_ID=<your-reverb-app-id>
REVERB_APP_KEY=<your-reverb-app-key>
REVERB_APP_SECRET=<your-reverb-app-secret>

# ── n8n OCR Integration ──────────────────────────────
N8N_WEBHOOK_URL=<your-n8n-webhook-url>
N8N_SECRET=<your-n8n-secret>

Admin-Payment/
├── app/
│   ├── Console/              # Artisan commands
│   ├── Events/               # Event classes (broadcasting)
│   │   ├── ActivityLogged.php
│   │   ├── NotificationReceived.php
│   │   ├── OcrStatusUpdated.php
│   │   ├── TransactionCreated.php
│   │   └── TransactionUpdated.php
│   ├── Http/
│   │   ├── Controllers/
│   │   │   ├── Api/
│   │   │   │   └── AiAutoFillController.php   # OCR callback & polling
│   │   │   ├── AuthController.php             # Login / Logout
│   │   │   ├── BranchController.php           # CRUD Cabang
│   │   │   ├── DashboardController.php        # Dashboard & analytics
│   │   │   ├── GudangController.php           # Alur belanja gudang (internal)
│   │   │   ├── NotificationController.php     # Notifikasi
│   │   │   ├── PengajuanController.php        # Alur pengajuan
│   │   │   ├── RembushController.php          # Alur rembush + OCR
│   │   │   ├── TransactionController.php      # CRUD & status transaksi
│   │   │   └── UserController.php             # CRUD User
│   │   └── Middleware/
│   │       └── CheckRole.php                  # Role-based access control
│   ├── Jobs/
│   │   └── OcrProcessingJob.php               # Background OCR processing
│   ├── Models/
│   │   ├── ActivityLog.php                    # Log aktivitas
│   │   ├── Branch.php                         # Cabang
│   │   ├── Transaction.php                    # Transaksi (model utama)
│   │   └── User.php                           # Pengguna
│   ├── Notifications/
│   │   ├── OcrStatusNotification.php          # Notif status OCR
│   │   ├── OwnerApprovalNotification.php      # Notif approval owner
│   │   └── TransactionStatusNotification.php  # Notif status transaksi
│   ├── Providers/
│   └── Services/
│       ├── IdGeneratorService.php             # Generator ID sequential (Redis)
│       └── OCR/
│           └── GeminiRateLimiter.php          # Rate limiter Gemini API
├── database/
│   └── migrations/                            # 15 migration files
├── docker/
│   └── nginx/                                 # Konfigurasi Nginx
├── resources/
│   └── views/
│       ├── auth/                              # Halaman login
│       ├── branches/                          # Manajemen cabang
│       ├── dashboard/                         # Dashboard & analytics
│       ├── layouts/                           # Layout utama
│       ├── notifications/                     # Halaman notifikasi
│       ├── transactions/                      # Halaman transaksi (8 views + gudang-form)
│       └── users/                             # Manajemen pengguna
├── routes/
│   ├── api.php                                # API routes (OCR callback)
│   ├── channels.php                           # Broadcasting channels
│   ├── console.php                            # CLI routes
│   └── web.php                                # Web routes utama
├── docker-compose.yml                         # Konfigurasi Docker (9 services)
├── Dockerfile                                 # PHP 8.4-FPM image
└── composer.json                              # PHP dependencies

Terdapat 4 peran pengguna dengan hak akses hierarkis:

• Admin Limited Edit: Admin dapat mengakses halaman edit Pengajuan dalam status waiting_payment untuk mengelola Pembagian Cabang dan Metode Distribusi. Bidang finansial (Item, Harga, DPP, PPN) tetap terkunci (Read-only).
• Settlement Lockout: Jika transaksi memasuki fase pelunasan (isSettlementPhase), seluruh akses edit akan dikunci total untuk SEMUA role, termasuk Owner.
• Edit Protection: Jika status transaksi adalah completed, tombol edit akan disembunyikan untuk SEMUA role guna menjaga integritas audit.

• Login dengan email + password + pemilihan role
• Validasi role saat login (role pada akun harus cocok dengan role yang dipilih)
• Auto-redirect berdasarkan role setelah login

• Statistik Transaksi: Total transaksi, total pending, total disetujui, total ditolak
• Rincian Biaya per Cabang: Breakdown biaya per cabang dengan filter bulan/tahun (AJAX) dan fitur interaktif Hutang Rembush (menampilkan list transaksi pending/waiting payment per cabang).
• Daftar Transaksi Pending: Tabel transaksi yang menunggu approval (AJAX refresh)

Alur lengkap reimbursement dengan OCR:

1. Upload Nota → Foto nota diupload ke server
2. OCR Processing → Job dikirim ke queue, foto dikirim ke n8n webhook → Gemini AI
3. Loading Page → Frontend polling status OCR setiap 2 detik
4. Form Auto-fill → Data hasil OCR mengisi form otomatis (customer, items, amount, dll.)
5. Review & Submit → User verifikasi dan submit transaksi

Alur pengajuan tanpa OCR:

1. Isi Form → Nama vendor, spesifikasi, jumlah, estimasi harga, alasan pembelian
2. Upload Foto (opsional) → Foto pendukung
3. Submit → Langsung masuk ke daftar pending

• Approve: Mengubah status menjadi approved atau completed
  • Jika nominal < Rp 1.000.000 → langsung completed
  • Jika nominal ≥ Rp 1.000.000 → status approved, menunggu Owner approval
• Reject: Mengubah status menjadi rejected dengan alasan penolakan
• Edit: Mengubah detail transaksi (hanya Admin, Atasan, Owner)
• Delete: Menghapus transaksi beserta file attachment

• CRUD cabang (nama cabang)
• Cabang yang masih memiliki transaksi tidak dapat dihapus
• Mendukung response JSON untuk AJAX interactions

• CRUD user dengan validasi role-based
• Admin & Atasan hanya bisa mengelola Teknisi
• Owner bisa mengelola semua role
• Tidak dapat menghapus akun sendiri

• Manajemen Dinamis: CRUD kategori untuk tipe Rembush dan Pengajuan.
• Toggle Status: Aktifkan/Nonaktifkan kategori tanpa menghapus data historis.
• UI Modern: Desain Glassmorphism dengan statistik ringkasan dan pencarian real-time.
• Sync Otomatis: Kategori yang aktif langsung muncul di form Rembush & Pengajuan.

• Notifikasi in-app menggunakan Laravel Notification system
• Filter berdasarkan tipe (OCR status, transaction status)
• Mark as read (satuan atau semua)
• Hapus notifikasi (satuan atau semua)
• Badge unread count via AJAX polling

• Mencatat semua aktivitas user: create, update, approve, reject, delete
• Menyimpan referensi ke user dan transaksi terkait

Sistem untuk menjaga efisiensi anggaran belanja:

• Auto-Calculated: Menghitung harga Min/Max/Avg berdasarkan riwayat transaksi yang disetujui.
• Outlier Filtering: Menggunakan algoritma IQR (Interquartile Range) untuk membuang data harga yang tidak wajar dari kalkulasi.
• Real-time Detection: Memperingatkan user jika harga yang diinput pada Pengajuan melebihi referensi maksimal.
• Anomaly Hub: Dashboard khusus untuk Owner mereview pelanggaran harga (Critical/Medium/Low).
• Manual Lock: Owner dapat mengunci harga referensi secara manual untuk kestabilan kebijakan.

graph TD
    A[Pending] -->|Reject| B[Rejected]
    A -->|< 1jt Approve| C[Waiting Payment]
    A -->|>= 1jt Approve| D[Approved]
    D -->|Owner Approve| C
    C -->|Upload Invoice| E{Has Branch Debt?}
    E -->|Yes| C
    E -->|No| F[Completed]
    C -->|Settle Final Debt| F

1. Gate Approval:
   • Transaksi < Rp 1.000.000: Admin/Atasan approve → waiting_payment.
   • Transaksi ≥ Rp 1.000.000: Admin/Atasan approve → approved (menunggu Owner) → Owner approve → waiting_payment.
2. Payment & Debt Flow:
   • Invoice Uploaded: Jika ada hutang antar cabang, status tetap waiting_payment.
   • Debt Settled: Transaksi otomatis completed saat hutang terakhir dilunaskan (dan invoice sudah ada).

Proyek ini menggunakan Scramble untuk menghasilkan dokumentasi API secara otomatis. Dokumentasi ini mengikuti standar OpenAPI 3.1 dan dapat diakses melalui antarmuka interaktif.

• Interactive UI: http://localhost:8000/docs/api
• OpenAPI Spec (JSON): http://localhost:8000/docs/api.json

Dalam dokumentasi API, Anda akan menemukan beberapa endpoint yang ditandai sebagai Primary atau Legacy:

• Primary: Endpoint standar terbaru yang direkomendasikan untuk semua integrasi baru. Memiliki penamaan yang benar dan konsisten.
• Legacy: Endpoint lama yang dipertahankan untuk backward compatibility. Endpoint ini mungkin memiliki typo yang sudah diperbaiki di versi primary (misal: /ai/auto-fil) atau struktur URL lama. Keduanya menjalankan logic yang sama di backend.

# ── Docker ──────────────────────────────────────────────
docker-compose up -d                     # Start semua service
docker-compose down                      # Stop semua service
docker-compose logs -f app               # Log container app
docker exec -it whusnet-app bash         # Masuk ke container app

# ── Laravel ─────────────────────────────────────────────
php artisan migrate                      # Jalankan migrasi
php artisan migrate:fresh --seed         # Reset DB + seeder
php artisan cache:clear                  # Bersihkan cache
php artisan config:clear                 # Bersihkan config cache
php artisan queue:work                   # Jalankan queue worker
php artisan horizon                      # Jalankan Horizon
php artisan reverb:start                 # Jalankan WebSocket server

# ── Price Index ─────────────────────────────────────────
php artisan price-index:recalculate --mode=incremental  # Recalc item dengan transaksi baru (daily)
php artisan price-index:recalculate --mode=full         # Recalc semua item non-manual (weekly)

# ── Development ─────────────────────────────────────────
npm run dev                              # Vite dev server
npm run build                            # Build assets untuk production
composer dev                             # Jalankan server + queue + vite sekaligus

# ── PR Validation ───────────────────────────────────────
./scripts/check-pr-ready.sh              # Check apakah code siap untuk PR
./vendor/bin/pint                        # Auto-fix code style
./vendor/bin/pint --test                 # Check code style tanpa fix
php artisan test --coverage --min=80     # Run tests dengan minimum 80% coverage
composer audit                           # Security audit untuk PHP dependencies
npm audit --audit-level=moderate         # Security audit untuk Node dependencies

Sebelum membuat Pull Request, pastikan code Anda lolos semua validation checks:

# Jalankan PR readiness checker
./scripts/check-pr-ready.sh

1. Code Style - Pastikan code mengikuti Laravel Pint standards

   ./vendor/bin/pint --test

2. Tests - Semua tests harus pass dengan coverage ≥ 80%

   php artisan test --coverage --min=80

3. Debug Statements - Hapus semua debug code

   # Check untuk dd(), dump(), var_dump(), console.log()
   git diff origin/main | grep -E "(dd\(|dump\(|var_dump\(|console\.log\()"

4. Security - Tidak ada credentials atau sensitive data

   composer audit
   npm audit --audit-level=moderate

Gunakan Semantic Commit format:

<type>: <description>

atau

<type>(<scope>): <description>

Valid Types:

• feat - Fitur baru
• fix - Bug fix
• docs - Dokumentasi
• refactor - Code refactoring
• perf - Performance improvements
• test - Menambah tests
• chore - Maintenance tasks

Contoh:

✅ feat: add price anomaly detection
✅ fix(auth): resolve login redirect issue
✅ docs: update deployment guide
✅ refactor(services): optimize price index calculation

❌ Added new feature
❌ Fixed bug
❌ Update

Jika PR validation gagal, lihat:

• 📋 Troubleshooting PR Validation - Solusi lengkap untuk semua PR validation errors

users
├── id, name, email, password, role
├── email_verified_at, remember_token
└── created_at, updated_at

transactions
├── id, type (rembush/pengajuan/gudang)
├── invoice_number, upload_id, trace_id
├── customer, category, description
├── amount, payment_method, items (JSON)
├── date, file_path, status
├── submitted_by → users.id
├── reviewed_by → users.id, reviewed_at, rejection_reason
├── ai_status, confidence
├── vendor, specs (JSON), quantity, estimated_price
└── created_at, updated_at

transaction_categories
├── id, name, type (rembush/pengajuan)
├── is_active, color_code
└── created_at, updated_at

branches
├── id, name
└── created_at, updated_at

transaction_branches (pivot)
├── transaction_id → transactions.id
├── branch_id → branches.id
├── allocation_percent, allocation_amount
└── created_at, updated_at

activity_logs
├── id, user_id → users.id
├── action, transaction_id, target_id, description
└── created_at, updated_at

notifications (Laravel default)
├── id, type, notifiable_type, notifiable_id
├── data (JSON), read_at
└── created_at, updated_at

document_sequences
└── Tabel pendukung untuk sequential ID generation

Sistem menggunakan Redis untuk menghasilkan ID sequential yang atomic dan aman dari race condition:

Upload ID dan Invoice Number selalu menggunakan counter yang sama (shared sequence), sehingga selalu sinkron.

Untuk dokumentasi yang lebih detail, silakan lihat:

• 📑 Documentation Index - Central hub untuk semua dokumentasi
• 📊 Analisis Dokumentasi - Gap analysis & roadmap dokumentasi

• 🗺️ Visual Flowcharts - Diagram Mermaid lengkap untuk semua alur sistem
• 🏛️ Architecture Diagram - Perbandingan Polling vs Reverb
• 🗄️ Database Schema - ER Diagram & struktur database lengkap
• ⚙️ Backend Documentation - Arsitektur mendalam dan logika bisnis

• 🧮 Price Index System - Sistem referensi harga, anomali, dan IQR logic
• 🎯 Price Index AVG System - Dual-Mode AVG (Auto vs Manual) - Quick Reference
• 📝 Implementasi AVG Manual - Detail implementasi fitur AVG Manual
• 📋 Pengajuan Specification - Sistem Dual-Version dan proteksi edit
• 💰 Rembush Flow Detail - Alur reimbursement dan integrasi AI
• 🔄 Realtime Migration - Migrasi ke Laravel Reverb
• 📊 Export Excel Optimization - Sistem export 3-lapis untuk dataset 40k+ rows

• 📡 API Documentation v4.5 - Webhook n8n, Telegram, dan Endpoint Flow
• 🚀 API Interactive Docs - Dokumentasi API real-time via Scramble

• 🐳 Docker Production Guide - Setup Docker untuk production
• 🔄 CI/CD Guide - GitHub Actions pipeline
• ⚡ Quick Setup (30 min) - Setup cepat Docker & CI/CD
• ✅ Production Checklist - Pre-deployment checklist
• 🔒 Security Checklist - Security best practices

• 📈 Monitoring Setup - Setup monitoring tools
• 📝 Logging Solution - Logging strategy lengkap
• 🔍 Pulse & Log Viewer - Setup Pulse & Log Viewer

• 🚨 Export Troubleshooting - Diagnosa & fix masalah export Excel
• 🩺 503 Error Analysis - Diagnose 503 Service Unavailable
• 🔧 Operations Troubleshooting - Masalah operasional umum

• 🧪 Testing Realtime - Testing fitur real-time
• 💰 Testing Pembagian Biaya - Testing cost allocation

• 📚 Quick Reference - Command reference cepat
• 📊 Technical Audit - Audit teknis & roadmap

Tertarik untuk berkontribusi? Silakan baca:

• 📝 Contributing Guide (Coming Soon)
• 🎨 Code Style Guide (Coming Soon)
• 🔀 Git Workflow (Coming Soon)

Project ini dikembangkan secara internal untuk WHUSNET.

Untuk pertanyaan atau bantuan:

• 📧 Email: [support@whusnet.com]
• 💬 Slack: [#admin-payment-support]
• 📖 Documentation: DOCUMENTATION_INDEX.md

Last Updated: 4 Mei 2026
Version: 4.5
Maintainer: WHUSNET Development Team