# POS, voucher QR, dan printer thermal

## Alur POS kantin

```mermaid
flowchart LR
    A[Kasir memilih produk] --> B[Santri menempel kartu]
    B --> C[Verifikasi sidik jari]
    C --> D{Saldo dan limit cukup?}
    D -- Tidak --> E[Transaksi ditolak]
    D -- Ya --> F[Debit saldo santri]
    F --> G[Kredit ledger kantin]
    G --> H[Simpan penjualan dan snapshot item]
    H --> I[Kirim detail belanja ke wali]
```

`kantin_sales` menyimpan transaksi utama, sedangkan `kantin_sale_items`
menyimpan snapshot nama, SKU, harga, jumlah, dan subtotal. Harga lama tidak
berubah ketika master produk diperbarui.

## Alur voucher untuk kantin eksternal

```mermaid
stateDiagram-v2
    [*] --> Diterbitkan: kartu + sidik jari valid\nsaldo santri didebit
    Diterbitkan --> Dicairkan: QR valid\noperator mencatat penerima
    Diterbitkan --> Dibatalkan: koreksi resmi
    Dicairkan --> [*]
    Dibatalkan --> [*]
```

- Hanya `unit_usahas.is_affiliated = true` yang dapat menerbitkan dan
  mencairkan voucher.
- QR berisi UUID acak dan HMAC berbasis `APP_KEY`. Perubahan UUID atau token
  membuat voucher tidak valid.
- Pencairan memakai `SELECT ... FOR UPDATE`; dua permintaan bersamaan tidak
  dapat mencairkan voucher yang sama.
- Voucher yang masih `diterbitkan` ditampilkan sebagai kewajiban belum cair.
  Saat dicairkan, nilainya masuk kas keluar pada leger pondok.
- Penerbitan voucher tidak menambah `saldo_unit` kantin karena belum merupakan
  omzet kantin penerbit.

## Printer thermal

Printer dikonfigurasi per perangkat di **Admin → Perangkat**:

1. pasang driver printer thermal pada komputer kiosk;
2. jadikan printer sebagai printer default pada OS/browser;
3. pilih lebar kertas 58 atau 80 mm;
4. aktifkan cetak otomatis;
5. izinkan silent printing melalui kebijakan kiosk browser jika lingkungan
   operasional memang membutuhkannya.

Browser standar tetap dapat menampilkan dialog cetak. Pemilihan printer tanpa
dialog memerlukan pengaturan kiosk/silent-print pada komputer fisik; aplikasi
web sengaja tidak meminta akses USB mentah agar kompatibel dan lebih aman.

## Voucher hilang

```mermaid
flowchart LR
    A[Santri melapor ke kantin penerbit] --> B[Verifikasi voucher, kartu, dan sidik jari]
    B --> C[QR lama langsung diblokir]
    C --> D[Masa sengketa 7 hari]
    D --> E{Penyelesaian}
    E --> F[QR pengganti tanpa debit kedua]
    E --> G[Refund resmi ke saldo santri]
```

Voucher berlaku 30 hari sejak pertama diterbitkan. Pengganti memakai sisa masa
berlaku voucher awal. Selama masa tunggu, scan QR menampilkan status diblokir
dan pencairan ditolak. Jadwal praktis penukaran kantin eksternal adalah setiap
7–14 hari agar voucher dapat dikumpulkan terlebih dahulu.

## Tabel utama

| Tabel | Fungsi |
|---|---|
| `kantin_products` | Master produk per unit usaha |
| `kantin_sales` | Header transaksi POS dan relasi ledger |
| `kantin_sale_items` | Snapshot detail belanja |
| `kantin_vouchers` | Lifecycle voucher dan data pencairan |
| `transaksis` | Debit saldo santri, termasuk `voucher_kantin` |
| `unit_usaha_transaksis` | Kredit omzet kantin untuk transaksi POS |