Panduan Operasional & Deployment

1. Persiapan Lingkungan (Environment Setup)

Zhuzhe POS membutuhkan lingkungan server yang optimal untuk menangani request API yang cepat dan proses data yang besar.

1.1 Kebutuhan Server (Backend)

  • PHP: Versi 8.2 atau lebih tinggi (Direkomendasikan 8.3).

  • Web Server: Nginx atau Apache.

  • Database: MySQL 8.0+ atau MariaDB 10.4+.

  • Ekstensi PHP Wajib: intl, bcmath, gd (untuk kompresi gambar), pdo_mysql.

1.2 Kebutuhan Pengembangan (Frontend)

  • Node.js: Versi 18 atau 20 (LTS).

  • NPM / Yarn: Untuk manajemen paket library React.

2. Instalasi Tahap Pengembangan (Local Development)

Ikuti langkah berikut untuk menjalankan aplikasi di komputer lokal:

  1. Clone Project: Unduh kode sumber dari repositori.

  2. Backend Setup:

    • Jalankan composer install.

    • Duplikat file .env.example menjadi .env.

    • Atur koneksi database di file .env.

    • Jalankan php artisan key:generate.

    • Jalankan php artisan install:api (untuk Laravel 11/12).

  3. Database Inisialisasi:

    • Jalankan php artisan migrate:fresh --seed untuk membuat tabel dan mengisi data awal (Super Admin, Toko Contoh, Produk Contoh).

  4. Frontend Setup:

    • Jalankan npm install.

    • Jalankan npm run dev untuk menyalakan server Vite.

  5. Akses: Buka browser di alamat http://localhost:8000.

3. Strategi Deployment ke Hosting/VPS

Proses pemindahan aplikasi ke server produksi membutuhkan ketelitian agar fitur seperti Vite dan Struk Belanja tidak error.

3.1 Kompilasi Aset (Production Build)

Sebelum mengunggah ke hosting, Anda WAJIB melakukan kompilasi file React menjadi file statis:

codeBash

  • Hasil: Folder public/build akan tercipta. Folder ini berisi aset yang sudah dikompres dan file manifest.json.

  • Penting: Folder public/build ini wajib diunggah ke server hosting.

3.2 Pengaturan File .env Produksi

Pastikan variabel berikut diatur dengan benar di server:

  • APP_ENV=production

  • APP_DEBUG=false

  • APP_URL=https://nama-domain-anda.com

  • SANCTUM_STATEFUL_DOMAINS=nama-domain-anda.com

3.3 Folder Permissions

Laravel membutuhkan izin akses tulis pada beberapa folder agar tidak terjadi Internal Server Error:

  • chmod -R 775 storage

  • chmod -R 775 bootstrap/cache

4. Konfigurasi Khusus Printer di Lokasi (On-Site)

Agar fitur cetak struk profesional (tanpa dialog browser) berfungsi:

4.1 Printer USB (Windows Sharing)

  1. Pasang driver printer POS58B.

  2. Lakukan Sharing Printer dengan nama yang sederhana (misal: POS58).

  3. Di menu Settings aplikasi, pilih metode Kabel dan isi alamat dengan nama sharing tersebut.

4.2 Printer Bluetooth (Android/Browser)

  1. Pastikan koneksi menggunakan HTTPS (WebBluetooth API tidak jalan di HTTP biasa).

  2. Lakukan Pairing bluetooth antara perangkat kasir dan printer.

  3. Di terminal POS, klik tombol "Hubungkan Bluetooth" satu kali di awal shift.

5. Pemeliharaan Rutin (Maintenance)

Untuk menjaga performa sistem Enterprise tetap stabil:

  1. Backup Database: Lakukan ekspor database secara rutin (harian/mingguan) untuk mengantisipasi kegagalan server.

  2. Optimasi Database: Jalankan OPTIMIZE TABLE secara berkala pada tabel yang sering berubah datanya seperti stock_movements dan transactions.

  3. Clear Cache: Jika Anda melakukan perubahan pada Setting atau Metadata, jalankan:

    • php artisan config:cache

    • php artisan route:cache

    • php artisan view:clear

6. Penutup (Summary)

Zhuzhe POS Enterprise bukan hanya sebuah aplikasi kasir, melainkan sistem manajemen sumber daya perusahaan yang lengkap. Dengan pondasi Full Multi-Tenant, isolasi data berbasis Store ID, dan sistem Audit Trail stok yang ketat, aplikasi ini siap digunakan untuk mendukung pertumbuhan bisnis Anda dari tingkat UMKM hingga jaringan ritel nasional.

PreviousPengaturan Sistem, Branding & Konfigurasi Hardware

Last updated