# 📚 PANDUAN DEPLOYMENT, KONFIGURASI (HO vs CABANG), DAN OPERASIONAL SISTEM
## Sistem ERP + POS Multi-Branch Offline-First (AIPOS3)

Dokumen ini berisi prosedur resmi untuk instalasi sistem, matriks konfigurasi perbedaan antara Kantor Pusat (Head Office - HO) dan Kantor Cabang (Branch), serta Standard Operating Procedures (SOP) penggunaan operasional harian.

---

## 1. 🛠️ PROSEDUR INSTALASI APLIKASI (SYSTEM DEPLOYMENT)

AIPOS3 dirancang untuk dapat di-deploy dengan dua metode utama: **Metode A (Manual Server Setup)** untuk control penuh atau **Metode B (Dockerized Setup)** untuk kemudahan standardisasi di 1000+ branch.

### PRASYARAT SISTEM MINIMUM

| Komponen | Spesifikasi Minimum | Catatan |
|----------|---------------------|---------|
| **Sistem Operasi** | Ubuntu 22.04 LTS / Windows Server 2022 | OS Linux direkomendasikan untuk produksi |
| **PHP Engine** | Version 8.4+ | Harus menyertakan ekstensi `pdo_mysql`, `redis`, `swoole` |
| **Relational DB** | MySQL 8.0+ / PostgreSQL 15+ | Untuk data transaksional utama |
| **Cache & Queue** | Redis 7.0+ | Satu instance untuk Triple-Redis Pattern |
| **Web Server** | Nginx 1.24+ / Laravel Octane | Octane dengan Swoole untuk high-performance |

---

### METODE A: INSTALASI MANUAL (SERVER PRODUCTION / DEV)

Lakukan langkah-langkah berikut di terminal server Anda:

#### **Langkah 1: Clone Project & Masuk Direktori**
```bash
git clone https://github.com/enterprise/aipos3.git
cd aipos3
```

#### **Langkah 2: Instal Dependensi Backend & Frontend**
```bash
# Instal package composer Laravel 12
composer install --no-dev --optimize-autoloader

# Instal dan bangun asset PWA frontend
npm install
npm run build
```

#### **Langkah 3: Konfigurasi Environment (`.env`)**
Salin template konfigurasi dan sesuaikan variabel koneksinya:
```bash
cp .env.example .env
nano .env
```
*(Lihat bagian 2 untuk detail pengisian variabel HO vs Cabang)*

#### **Langkah 4: Generate Application Key & Jalankan Migrasi**
```bash
# Generate encryption key
php artisan key:generate

# Jalankan migrasi database beserta seeder standar COA dan produk
php artisan migrate --force
php artisan db:seed --class=DatabaseSeeder --force
```

#### **Langkah 5: Jalankan Service Background**
Di server Linux, daftarkan daemon ini di bawah **Supervisor** agar terus berjalan otomatis:
```bash
# 1. Jalankan Engine Utama Laravel Octane (Swoole)
php artisan octane:start --server=swoole --host=0.0.0.0 --port=8000

# 2. Jalankan Queue Manager (Horizon)
php artisan horizon

# 3. Jalankan WebSocket Broker (Reverb)
php artisan reverb:start --host=0.0.0.0 --port=8080
```

---

### METODE B: INSTALASI DENGAN DOCKER COMPOSE (REKOMENDASI DEPLOY CABANG)

Metode ini mengemas seluruh stack dalam container terisolasi sehingga tidak memerlukan instalasi manual PHP/MySQL/Redis di OS host.

#### **Langkah 1: Jalankan Docker Compose Build**
Pastikan Docker dan Docker Compose telah terinstal di mesin server, lalu jalankan:
```bash
docker-compose up -d --build
```
Command ini akan otomatis membangun service:
- `aipos3_app`: Node aplikasi PHP 8.4 + Swoole (port `8000`)
- `aipos3_mysql`: MySQL Database Server (port `3306`)
- `aipos3_redis`: Redis 7 Cache, Streams, & Queue (port `6379`)
- `aipos3_horizon`: Horizon Daemon Queue
- `aipos3_reverb`: Reverb WebSocket Broker (port `8080`)

#### **Langkah 2: Jalankan Migrasi di Dalam Container**
```bash
docker-compose exec app php artisan migrate --force
docker-compose exec app php artisan db:seed --force
```

---

## 2. 🎛️ MATRIKS KONFIGURASI HO (HEAD OFFICE) VS CABANG (BRANCH)

Perilaku aplikasi AIPOS3 dikendalikan oleh file `.env` di masing-masing mesin deployment. Parameter paling kritis adalah **`APP_BRANCH_ID`**.

### 1. VARIABEL `.env` KUNCI UNTUK HO VS CABANG

#### **Konfigurasi Mesin Kantor Pusat (Head Office - HO)**
Di server pusat (cloud), isi file `.env` sebagai berikut:
```ini
# Identitas Node: 0 berarti Kantor Pusat (HO)
APP_BRANCH_ID=0

# Database Utama HO (Menampung konsolidasi semua data)
DB_DATABASE=aipos3_ho_db

# Kunci HMAC Utama untuk verifikasi data masuk dari cabang
SYNC_HMAC_SECRET=ho-super-secret-crypt-key-2026
```

#### **Konfigurasi Mesin Kantor Cabang (Branch - e.g., Cabang Bandung)**
Di komputer server lokal yang ada di Cabang Bandung, isi file `.env` sebagai berikut:
```ini
# Identitas Node: ID Cabang unik (misal: Cabang Bandung = 1)
APP_BRANCH_ID=1

# Database Lokal Cabang (Hanya menyimpan data lokal untuk offline-first)
DB_DATABASE=aipos3_branch_1

# URL Endpoint Kantor Pusat untuk upload data sinkronisasi
SYNC_HO_URL=https://erp-pusat.aipos3.com/api/sync/upload
SYNC_HMAC_SECRET=ho-super-secret-crypt-key-2026
```

---

### 2. MATRIKS PERBANDINGAN FITUR & AKSES DATA

| Aspek Arsitektur | Kantor Pusat (Head Office - HO) | Kantor Cabang (Branch Node) |
|------------------|---------------------------------|-----------------------------|
| **Nilai `APP_BRANCH_ID`** | `0` | `1, 2, 3, dst (Sesuai ID Cabang)` |
| **Database Server** | MySQL Cloud Server (High Availability) | MySQL Local Server (Offline-capable) |
| **Akses Modul POS** | Hanya monitoring transaksi harian global | Operasional penuh kasir harian |
| **Otoritas Master Data** | Penuh (Input Produk, Ubah Harga, Promosi) | Read-only (Menerima push master data dari HO) |
| **Stock Ledger Costing** | Konsolidasi seluruh gudang di semua cabang | Hanya memutasi kartu stok gudang sendiri |
| **Double-Entry Journal** | Otomatis dari sinkronisasi cabang & HO manual | Jurnal otomatis lokal sebelum di-sync ke pusat |
| **Triple-Redis Pattern** | Queue (Sync Stock), Streams, Pub/Sub (Dashboard) | Queue (Push Trx), Streams, Pub/Sub (POS Realtime) |

---

### 3. ROLE & PERMISSION (SPATIE RBAC) MATRIX

Sistem menggunakan hak akses Spatie RBAC untuk memastikan keamanan data multitenant cabang:

```mermaid
graph TD
    Superadmin[Superadmin - HO] -->|Akses Semua| HO_Data[(Semua Database Cabang)]
    HO_Manager[HO Manager] -->|Master Data & Approval| ProductPrice[Central Price & Promo]
    Branch_Manager[Branch Manager] -->|Akses Cabang Sendiri| BranchStock[Stok & Purchase local]
    Cashier[Kasir Cabang] -->|Akses POS Terminal| POS[IndexedDB Offline POS]
```

- **Role `superadmin`**: Akses tak terbatas ke seluruh sistem dan semua cabang.
- **Role `ho_manager`**: Mengelola data produk, harga jual nasional, dan menyetujui Purchase Order bernilai besar (>50 Juta Rupiah). Tidak diizinkan melakukan transaksi POS kasir langsung.
- **Role `branch_manager`**: Memantau operasional cabang sendiri, menyetujui mutasi stok lokal, dan melihat laporan laba rugi cabangnya sendiri. **Dilarang keras melihat laporan keuangan cabang lain.**
- **Role `cashier` (Kasir)**: Hanya diizinkan membuka halaman `/pos` terminal untuk transaksi penjualan. Tidak memiliki akses ke menu admin/back-office.
- **Role `accountant`**: Memiliki hak akses khusus laporan akuntansi, jurnal umum, buku besar, neraca, dan laba rugi.

---

## 3. 📖 PROSEDUR PEMAKAIAN APLIKASI (OPERATIONAL SOP)

Berikut adalah petunjuk operasional langkah-demi-langkah (Standard Operating Procedure - SOP) untuk penggunaan sistem di Kantor Pusat dan Kantor Cabang.

---

### A. ALUR KERJA KANTOR PUSAT (HEAD OFFICE - HO)

#### **1. Pengelolaan Master Data Produk Baru**
1. Masuk ke halaman **Admin Back-Office** `/admin/master-data/products`.
2. Klik tombol **Create Product** (`/admin/master-data/products/create`).
3. Masukkan SKU, Nama Produk, Kategori, Deskripsi, dan Barcode dasar.
4. Pada bagian **Product Pricing**, tentukan:
   - *Purchase Price*: Harga beli pusat ke supplier.
   - *Selling Price*: Harga jual default ke konsumen.
   - *Wholesale Price*: Harga grosir untuk pembelian volume besar.
5. Klik **Save**. Sistem akan secara otomatis menulis event ke `master_data_stream` (Redis Streams DB 1) dan menyebarkan (broadcast) produk baru ini ke seluruh database lokal cabang melalui Horizon queue job `SyncStockToAllBranches`.

#### **2. Mass Price Update (Ubah Harga Massal)**
1. Masuk ke menu **Reporting Hub** `/admin/reports/hub?activeTab=products`.
2. Ekspor daftar produk ke format Excel/CSV.
3. Edit kolom harga jual pada file spreadsheet.
4. Gunakan fitur **Import Price** untuk mengunggah kembali file tersebut.
5. Sistem akan memvalidasi data dan memicu update harga terjadwal. Notifikasi perubahan harga akan terkirim secara real-time ke semua dashboard cabang melalui Redis Pub/Sub.

#### **3. Proses Approval Pembelian (Purchasing Approval)**
Ketika Cabang membuat Purchase Order (PO) ke Supplier dengan nilai besar, approval bertingkat wajib dilakukan di Kantor Pusat:
- **Jumlah < 10 Juta**: Otomatis disetujui oleh Supervisor Cabang setempat.
- **Jumlah 10 - 50 Juta**: Membutuhkan persetujuan digital **Branch Manager** lokal.
- **Jumlah > 50 Juta**: Membutuhkan persetujuan **Director / HO Manager** di Kantor Pusat:
  1. HO Manager menerima notifikasi "Pending Approval" via Dashboard / WhatsApp.
  2. Buka menu `/admin/purchasing/dashboard`.
  3. Periksa item barang dan negosiasi harga.
  4. Klik **Approve** atau **Reject** (dengan catatan alasan).
  5. Setelah disetujui, Horizon job akan mengirim dokumen PO ter-approve dalam format PDF ke WhatsApp/Email Supplier secara otomatis.

---

### B. ALUR KERJA OPERASIONAL CABANG & KASIR (POINT OF SALE)

Terminal kasir dirancang dengan arsitektur **Offline-First**, artinya kasir tetap dapat melayani penjualan 100% secara normal meskipun koneksi internet ke pusat mati total.

```
+-------------------------------------------------------------+
|               SOP TRANSAKSI KASIR (KONEKSI NORMAL)          |
|                                                             |
| Scan Barcode  -->  Pilih Customer  -->  Split/Multi Pay --> |
|                                              |              |
| Auto Jurnal   <--  HO Database    <--  Auto-Sync API        |
+-------------------------------------------------------------+

+-------------------------------------------------------------+
|               SOP TRANSAKSI KASIR (INTERNET MATI)           |
|                                                             |
| Scan Barcode  -->  Pilih Customer  -->  Split/Multi Pay --> |
|                                              |              |
| Cek Koneksi   <--  Antrean PWA    <--  Simpan IndexedDB     |
| (Auto Sync)                                                 |
+-------------------------------------------------------------+
```

#### **1. Persiapan Awal POS Kasir (Awal Shift)**
1. Nyalakan monitor kasir, buka browser dan akses URL `/pos`.
2. Sistem PWA akan mendeteksi browser dan mengunduh asset statis secara offline (`service-worker.js`).
3. Sistem secara otomatis membaca database pusat dan menyuntikkan (seeding) daftar katalog produk aktif beserta barcode dan harga jual terbaru ke **IndexedDB lokal (Dexie.js)** di browser kasir.
4. Indikator di pojok kanan atas akan menampilkan badge **ONLINE** (Hijau) berkedip, menandakan siap melakukan sinkronisasi real-time.

#### **2. SOP Transaksi Penjualan Harian**
1. **Input Barang**:
   - *Cara A (Barcode Scanner)*: Arahkan barcode produk ke laser scanner. Sistem menangkap ketukan input laser secara cepat (<50ms) dan memasukkan produk ke keranjang belanja secara instan (1 klik).
   - *Cara B (Manual/Touchscreen)*: Ketik nama produk pada kolom pencarian (F1) atau ketuk ubin produk berukuran besar (touchscreen-friendly 80x80px) pada layar.
2. **Pilih Pelanggan**:
   - Secara default, pelanggan diatur sebagai **WALK-IN CUSTOMER** (Tanpa data pribadi).
   - Jika member, pilih nama pelanggan pada dropdown untuk melacak akumulasi Poin Loyalitas.
   - Jika ada pelanggan baru, klik tombol **Add Customer (F2)** untuk mendaftarkan nama dan nomor HP secara instan (offline-ready).
3. **Pembayaran Multi-Payment & Split Payment**:
   - Jika pelanggan ingin melakukan pembayaran gabungan (Split Payment), masukkan nominal pembayaran tahap 1 (misal: Cash Rp 50.000), tentukan metode bayar, lalu klik **Add Pay**.
   - Masukkan sisa pembayaran pada tahap 2 (misal: scan statis/dinamis QRIS sebesar Rp 35.000 via EDC), lalu klik **Add Pay**.
   - *Aturan Sistem*: Pembayaran split dibatasi maksimal **2 tahap pembayaran saja** (Down Payment + Pelunasan).
4. **Finalisasi & Cetak Struk**:
   - Tekan tombol **Print Receipt (F8)**.
   - Sistem akan memproses transaksi dalam waktu < 1 detik.
   - Browser kasir akan memunculkan dialog cetak struk berformat monospace ESC/POS yang dioptimalkan untuk thermal printer ukuran 58mm/80mm.
   - Laci kas (cash drawer) akan terbuka secara otomatis (jika terhubung).

#### **3. SOP Penangguhan Transaksi (Suspend / Draft Transaksi)**
Jika pelanggan tiba-tiba ingin mengambil barang tambahan saat sedang mengantre di kasir:
1. Kasir tidak perlu menghapus keranjang. Cukup ketuk tombol **Suspend Cart (F4)**.
2. Keranjang belanja aktif akan otomatis disimpan sebagai draft di IndexedDB lokal, dan layar kasir kembali bersih untuk melayani antrean berikutnya.
3. Setelah pelanggan tersebut kembali, ketuk tombol **Drafts** di layar, cari transaksi berdasarkan waktu penangguhan, lalu klik **Resume**. Keranjang belanja lama akan kembali utuh untuk diselesaikan.

#### **4. SOP Penanganan Saat Internet Mati (Offline Mode)**
1. Ketika koneksi internet terputus, indikator di kanan atas akan otomatis berubah menjadi merah berkedip bertuliskan **OFFLINE**.
2. Kasir tetap melanjutkan penjualan, memindai barcode, menerima pembayaran, dan mencetak struk fisik seperti biasa tanpa ada hambatan sama sekali.
3. Setiap transaksi yang dilakukan dalam kondisi offline akan diberikan **UUID v7 (Timestamp-based)** unik dan ditandai dengan `sync_status = 'pending'`. Data disimpan aman di MySQL lokal cabang dan IndexedDB browser.
4. **Saat Internet Kembali Online**:
   - Service Worker secara otomatis mendeteksi pulihnya jaringan internet.
   - Badge status berubah menjadi **ONLINE** (Hijau) dan menampilkan jumlah antrean data yang belum disinkronkan (misal: `5 Pending Sync`).
   - Browser kasir memicu background sync dengan menembak API Endpoint `/api/sync/offline/sync`.
   - Kantor Pusat menerima batch transaksi offline, melakukan validasi keamanan, memicu penyesuaian stok gudang otomatis, dan membukukan jurnal akuntansi secara real-time.
   - Setelah sukses, status di database browser kasir diperbarui menjadi `synced` untuk mencegah pengiriman ganda.

---

### C. ALUR KERJA AKUNTANSI & INVENTORY CABANG

#### **1. Penerimaan Barang Supplier (Purchase Receive)**
1. Saat truk pengirim barang tiba dari Supplier, staf gudang cabang membuka halaman `/admin/inventory/stocks`.
2. Pilih menu **Purchase Receive** dan masukkan nomor PO rujukan.
3. Periksa kesesuaian fisik barang (jumlah dan kondisi) dengan dokumen PO.
4. Masukkan nomor Batch dan Tanggal Kedaluwarsa (Batch & Expiry Date) khususnya untuk produk kategori makanan/farmasi.
5. Klik **Submit Receive**.
6. Sistem akan otomatis:
   - Menambah kuantitas stok produk pada tabel `stocks` di gudang cabang tersebut.
   - Mencatat mutasi kartu stok masuk (`IN`) pada tabel `stock_movements`.
   - Mengubah status PO menjadi `fulfilled`.
   - Menulis log aktivitas ke tabel `audit_logs` (siapa penerima, kapan, dan berapa selisih kuantitasnya).
   - Menghasilkan jurnal akuntansi otomatis di Kantor Pusat: **Debit Persediaan Barang Dagang**, **Kredit Utang Dagang**.

#### **2. Penutupan Shift Harian & Jurnal Otomatis**
Setiap transaksi penjualan kasir (POS) yang disinkronkan ke pusat akan memicu sistem akuntansi otomatis untuk membukukan entri double-entry standar tanpa perlu input manual oleh staf finance:
- **Jurnal Penjualan Kasir POS**:
  - `Debit` : **Kas dan Setara Kas** (Aset) — Sebesar nominal pembayaran tunai/EDC/QRIS.
  - `Kredit`: **Pendapatan Penjualan POS** (Pendapatan) — Sebesar nominal transaksi bersih.
- Staf Akuntan HO cukup memantau laporan Buku Besar (General Ledger), Neraca Saldo (Trial Balance), Neraca Keuangan (Balance Sheet), serta Laporan Laba Rugi (Profit & Loss) yang diperbarui secara real-time di halaman **Reporting Hub** `/admin/reports/hub?activeTab=accounting`.

---

## 4. 🚑 PANDUAN PENANGANAN MASALAH (SYNC TROUBLESHOOTING)

Jika terjadi kendala ketidaksinkronan data antara Kantor Cabang dan Kantor Pusat (HO), ikuti langkah-langkah diagnostik berikut:

### Gejala 1: Transaksi di POS Cabang Tidak Muncul di Laporan HO Pusat
1. **Periksa Status Koneksi**: Pastikan badge koneksi di POS Cabang berwarna hijau (**ONLINE**).
2. **Periksa Antrean Sync**: Lihat angka pending sync di kanan atas. Jika angkanya tidak berkurang, klik tombol **Sync Now** untuk memicu pengiriman paksa.
3. **Analisis Log Server Cabang**:
   Buka terminal di server cabang dan periksa status Horizon queue:
   ```bash
   php artisan horizon:status
   ```
   Jika Horizon tidak aktif, nyalakan kembali:
   ```bash
   php artisan horizon
   ```
4. **Periksa Kunci HMAC**: Pastikan nilai `SYNC_HMAC_SECRET` pada file `.env` di server Cabang sama persis dengan yang ada di server Kantor Pusat. Jika berbeda, request akan ditolak dengan error `401 Unauthorized` oleh middleware `ValidateApiSignature`.

### Gejala 2: Terjadi Inkonsistensi Data Harga Produk Antar Cabang
1. Sistem menerapkan aturan **Last Write Wins** jika ada dua perubahan dalam waktu yang bersamaan.
2. Jika terjadi konflik data yang tidak bisa diselesaikan secara otomatis, sistem akan menuliskan payload mentah data lokal vs remote ke tabel `sync_conflicts` dan menandai record dengan status `conflict`.
3. Akuntan / IT Administrator Kantor Pusat dapat memeriksa daftar konflik dengan menjalankan query:
   ```sql
   SELECT * FROM sync_conflicts WHERE resolution_status = 'pending';
   ```
4. Selesaikan konflik dengan menekan tombol **Resolve** di dashboard pusat, memilih data mana yang benar (apakah data lokal cabang atau data HO pusat), lalu sistem akan menyebarkan hasil keputusan tersebut ke seluruh cabang secara instan.

---
*Dokumen Standard Operating Procedure (SOP) AIPOS3 ini diterbitkan secara resmi oleh IT Enterprise Architect ERP Team.*  
*Hak Cipta © 2026. Seluruh hak cipta dilindungi.*