# 📦 Modul Penyerahan Produk Hadiah — Arsitektur & Perbaikan UX

> **Tanggal:** 23 Juli 2026  
> **Status:** Siap dikerjakan  
> **Prioritas:** Medium-High  

---

## 1. Konteks Bisnis

### Alur Pemberian Hadiah
Perusahaan memberikan hadiah berupa **barang fisik** kepada penerima berdasarkan **KPI non-bisnis**. Sebelum hadiah dapat diserahkan, penerima wajib melunasi **tagihan pajak** yang dipungut perusahaan dan akan disetor ke negara.

### Syarat Utama
- Pajak **wajib lunas** sebelum hadiah bisa diserahkan
- Staff internal yang memproses seluruh alur
- Hadiah keluar dari stok gudang (modul distribusi)

---

## 2. Arsitektur 3 Transaksi

### Desain Saat Ini (Sudah Benar ✅)

Tiga transaksi dibuat secara **bersamaan (paralel dalam penciptaan)**, namun eksekusinya bersifat **serial (berurutan)**:

```
            ┌─────────────────────────┐
            │ (a) Penentuan Penerima  │  ← Titik referensi tunggal
            │     Hadiah              │     (semua transaksi merujuk ke sini)
            │     [Modul Mandiri]     │
            └─────┬──────────┬────────┘
                  │          │
        referensi│          │referensi
                  ▼          ▼
  ┌──────────────────┐  ┌──────────────────────┐
  │ (b) Tagihan      │  │ (c) Penyerahan       │
  │     Pajak        │  │     Hadiah            │
  │                  │  │     (modul distribusi)│
  │ [Modul Piutang]  │  │                      │
  └──────────────────┘  └──────────────────────┘
         │                        ▲
         │                        │
         └── HARUS LUNAS DULU ────┘
```

### Kenapa 3 Transaksi Terpisah?

| Alasan | Penjelasan |
|--------|-----------|
| **Jeda waktu nyata** | Customer perlu waktu berhari-hari untuk bayar pajak — tidak mungkin 1 transaksi tunggal |
| **Modul berbeda** | Piutang dan distribusi adalah modul terpisah di sistem |
| **Referensi bersih** | Semua merujuk ke (a) — tidak circular |

### Kenapa Paralel + Serial?

| Aspek | Paralel | Serial |
|-------|---------|--------|
| **Penciptaan** transaksi (a)(b)(c) | ✅ Dibuat bersamaan | - |
| **Penyelesaian** (c) setelah (b) | - | ✅ Dijaga gate check |

> **Prinsip: Paralel dalam keberadaan, serial dalam eksekusi.**

---

## 3. Proteksi yang Sudah Ada ✅

| Proteksi | Status | Mekanisme |
|----------|--------|-----------|
| Info pajak belum lunas | ✅ Ada | Teks italic di kolom Action |
| Tombol disabled saat pajak belum bayar | ✅ Ada | Button disabled di front-end |
| Validasi server-side (gate check) | ✅ Ada | Query real-time ke modul piutang sebelum proses distribusi |
| Anti double-processing | ✅ Ada | `ComLockerTransaksi` di modul distribusi |

---

## 4. Skenario Pembatalan

### Matriks Pembatalan per Tahap

| Tahap saat batal | (a) Penentuan | (b) Tagihan Pajak | (c) Penyerahan | Kompleksitas |
|---|---|---|---|---|
| Baru (a) dibuat | Cancel | Cancel (belum dikirim) | Cancel (belum jalan) | **Rendah** |
| (b) terbit, belum dibayar | Cancel | Cancel tagihan | Cancel (gate check blokir) | **Rendah** |
| (b) pajak sudah LUNAS | Cancel | ⚠️ **Perlu transaksi pengembalian pajak** | Cancel (belum jalan) | **Sedang** |
| (c) hadiah sudah diserahkan | Cancel | ⚠️ Pengembalian pajak | ⚠️ **Retur barang ke stok** | **Tinggi** |

### Aturan Pembatalan
- Pembatalan selalu dimulai dari **(a)** dan cascade ke (b) dan (c)
- Jika (b) sudah lunas → wajib buat transaksi pengembalian pajak
- Jika (c) sudah selesai → wajib proses retur barang ke gudang via modul penerimaan

---

## 5. Perbaikan UX yang Direkomendasikan

### Kondisi Saat Ini (Screenshot)

![Tampilan saat ini](file:///z:/everest_17jul/docs/penyerahan_hadiah_current.png)

**Masalah utama:** Informasi status pajak ada tapi **kurang terlihat** — teks italic kecil di antara tombol-tombol besar di kolom Action. Staff yang sibuk kemungkinan besar langsung klik tombol tanpa membaca teks tersebut.

---

### 5.1 🟥 Badge Warna Status Pajak (Prioritas: TINGGI, Effort: RENDAH)

**Masalah:** Teks italic "*Uang Pelunasan Pajak Hadiah Belum Diterima/Belum Lunas*" tenggelam secara visual di antara tombol-tombol.

**Solusi:** Ganti dengan badge berwarna yang mencolok.

| Status Pajak | Visual Badge |
|---|---|
| Belum lunas | 🟥 Background merah, teks putih, font bold |
| Lunas | 🟩 Background hijau, teks putih, font bold |

**Contoh CSS:**
```css
/* Badge status pajak */
.badge-pajak-belum {
    background-color: #e74c3c;
    color: #ffffff;
    padding: 2px 8px;
    border-radius: 3px;
    font-weight: bold;
    font-size: 11px;
    display: inline-block;
}

.badge-pajak-lunas {
    background-color: #27ae60;
    color: #ffffff;
    padding: 2px 8px;
    border-radius: 3px;
    font-weight: bold;
    font-size: 11px;
    display: inline-block;
}
```

**Contoh HTML:**
```html
<!-- Belum lunas -->
<span class="badge-pajak-belum">PAJAK BELUM LUNAS</span>

<!-- Sudah lunas -->
<span class="badge-pajak-lunas">PAJAK LUNAS</span>
```

---

### 5.2 🔄 Pindah Info Pajak ke Kolom Status (Prioritas: TINGGI, Effort: RENDAH)

**Masalah:** Info pajak saat ini ada di kolom **Action** — staff terbiasa melihat kolom Action sebagai tempat klik, bukan tempat baca informasi.

**Solusi:** Pindahkan info status pajak ke kolom **Status**, karena memang itu informasi status.

**Sekarang:**
```
Kolom Status:                     Kolom Action:
  Request                          [QR untuk Handphone]
  ✅ Request Produk Hadiah          *Uang Pelunasan Pajak...*  ← di sini
  ⬚ Penyerahan Produk Hadiah       [Edit]
                                    [Reject 1 step]
```

**Rekomendasi:**
```
Kolom Status:                          Kolom Action:
  Request                               [QR untuk Handphone]
  ✅ Request Produk Hadiah               [Edit]
  🟥 PAJAK BELUM LUNAS       ← pindah   [Reject 1 step]
  ⬚ Penyerahan Produk Hadiah            [Reject all step]

Next Step:
  Menunggu Pelunasan Pajak
```

---

### 5.3 📊 Progress Bar 3 Langkah (Prioritas: SEDANG, Effort: SEDANG)

**Masalah:** Progress bar saat ini hanya menunjukkan 2 langkah:
```
⓵ REQUEST PRODUK HADIAH ──── ⓶ PENYERAHAN PRODUK HADIAH
```
Staff tidak melihat ada tahap pajak di antaranya → bingung kenapa step 2 belum bisa diproses.

**Solusi:** Tambahkan langkah tengah:
```
⓵ REQUEST HADIAH ──── ⓶ PELUNASAN PAJAK ──── ⓷ PENYERAHAN HADIAH
      ✅ (hijau)          ⏳ (kuning)              🔒 (abu-abu)
```

**Warna indikator per status:**
| Status | Warna | Keterangan |
|--------|-------|-----------|
| Selesai | Hijau (#27ae60) | Langkah sudah complete |
| Menunggu/In Progress | Kuning (#f39c12) | Langkah aktif, menunggu aksi |
| Terkunci | Abu-abu (#95a5a6) | Belum bisa diproses |

---

### 5.4 💬 Tooltip pada Tombol Disabled (Prioritas: SEDANG, Effort: RENDAH)

**Masalah:** Saat tombol disabled, staff tidak langsung paham **kenapa** tidak bisa diklik.

**Solusi:** Tambahkan atribut `title` pada tombol yang disabled:
```html
<button disabled 
        title="Tidak bisa memproses penyerahan - Pajak belum dilunasi"
        style="cursor: not-allowed; opacity: 0.5;">
    Penyerahan Produk Hadiah
</button>
```

---

### 5.5 📋 Info Tagihan di Kolom Keterangan (Prioritas: RENDAH, Effort: SEDANG)

**Masalah:** Kolom Keterangan saat ini kosong (`-`). Bisa dimanfaatkan untuk info yang berguna.

**Solusi:** Tampilkan ringkasan tagihan pajak:
```
Keterangan:
  Pajak: Rp 500.000
  Status: Belum Lunas
  Jatuh Tempo: 30 Jul 2025
```

**Manfaat:** Staff gudang/penyerahan bisa langsung info ke customer tanpa harus buka modul piutang terpisah.

---

## 6. Ringkasan Prioritas Pengerjaan

| # | Perbaikan | Effort | Dampak UX | Status |
|---|-----------|--------|-----------|--------|
| 1 | Badge warna status pajak | Rendah | ⭐⭐⭐ Tinggi | ⬜ Belum |
| 2 | Pindah info pajak ke kolom Status | Rendah | ⭐⭐⭐ Tinggi | ⬜ Belum |
| 3 | Progress bar 3 langkah | Sedang | ⭐⭐ Sedang | ⬜ Belum |
| 4 | Tooltip pada tombol disabled | Rendah | ⭐⭐ Sedang | ⬜ Belum |
| 5 | Info tagihan di kolom Keterangan | Sedang | ⭐ Bonus | ⬜ Belum |

> **Rekomendasi:** Kerjakan #1 dan #2 terlebih dahulu — effort rendah, dampak paling besar.

---

## 7. Catatan Teknis

### Stack yang Digunakan
- PHP 5.6 + CodeIgniter 3.1.8 (HMVC)
- Modul distribusi yang sudah ada untuk penyerahan barang
- Modul piutang/keuangan untuk tagihan pajak
- `ComLockerTransaksi` untuk anti double-processing

### Referensi Kode
- Controller penyerahan hadiah: `application/modules/[modul_hadiah]/controllers/`
- Layout tabel: `coTransaksiLayout.php` di config modul
- Gate check: validasi status pajak di awal proses `FollowUp`

### Kompatibilitas
- Semua CSS baru harus kompatibel dengan browser yang digunakan staff
- Tidak ada dependency tambahan (vanilla CSS saja)
- PHP 5.6 compatible — tidak menggunakan sintaks modern