# BayarQR Digital Commerce Plugin — Spec V1

Dokumen ini menjadi acuan implementasi plugin WordPress untuk penjual produk digital (ebook, template, file premium) dengan pembayaran BayarQR dan kontrol akses setelah bayar.

## 1. Positioning Produk

- Plugin ini ditujukan untuk user WordPress + Elementor yang menjual produk digital.
- Pembayaran diproses oleh BayarQR.
- Akses produk dan membership mini dikelola di plugin WordPress.
- Tidak menggunakan BayarQR Mail Relay. Pengiriman email hanya melalui SMTP custom milik user.

## 2. Tujuan Utama

- Memudahkan user membuat alur jualan digital tanpa coding.
- Mendukung checkout lewat BayarQR.
- Menyediakan halaman akses produk yang aman.
- Menyediakan dua model akses:
  - one-time access (sekali jalan),
  - membership access (akses ulang di member area).

## 3. Prinsip UX (Founder Direction)

- Alur setup harus ringkas, maksimal 3 langkah:
  1) buat produk digital,
  2) hubungkan checkout BayarQR,
  3) atur akses setelah bayar.
- Elementor-first:
  - user bebas desain landing, checkout page, access page.
  - plugin sediakan shortcode/widget agar tinggal tempel.
- Pemula tidak dipaksa memahami webhook/token di awal.

## 4. Arsitektur Alur

### 4.1 Komponen

- BayarQR:
  - membuat/menyediakan payment link atau checkout session,
  - memvalidasi status pembayaran.
- Plugin WordPress:
  - menyimpan produk digital,
  - menyimpan policy akses,
  - memproses webhook terverifikasi,
  - menerbitkan entitlement akses,
  - menyajikan halaman akses aman.

### 4.2 Alur Pembayaran

1. Visitor membuka landing page.
2. Klik checkout via shortcode/widget plugin.
3. Plugin mengarahkan ke checkout BayarQR (default hosted) atau render mode embedded (advanced).
4. Setelah sukses:
   - redirect ke access page WordPress,
   - jika SMTP aktif: kirim magic link akses via email.
5. Entitlement akses hanya dianggap valid setelah webhook BayarQR terverifikasi.

## 5. Paket Fitur

### 5.1 Starter

- Produk digital sederhana.
- Integrasi checkout BayarQR.
- Redirect ke access page.
- One-time access policy.
- Tanpa SMTP custom UI (atau disembunyikan).

### 5.2 Pro+

- Semua fitur Starter.
- SMTP custom settings.
- Magic link email + resend.
- Membership access (akses ulang).
- Member area dengan slot promosi produk lain.

## 6. Feature Set V1

### 6.1 Koneksi BayarQR

- Field:
  - Base URL BayarQR,
  - API Key,
  - Environment (SANDBOX/LIVE).
- Tombol:
  - Test Connection.
- Validasi:
  - tampilkan status koneksi valid/gagal.

### 6.2 Manajemen Produk Digital

- Data produk:
  - nama produk,
  - slug produk,
  - harga,
  - deskripsi singkat,
  - file resource (lampiran),
  - status (draft/published).
- Mapping checkout:
  - payment link ID/slug (atau auto-create saat publish jika diset).

### 6.3 Checkout Integration

- Mode checkout:
  - Hosted (default),
  - Embedded QR (advanced).
- Shortcode minimum:
  - `[bayarqr_digital_checkout product="slug-produk"]`
- Output:
  - judul produk,
  - harga,
  - CTA bayar.

### 6.4 Product Access Policy

Per produk, wajib memilih satu mode:

1) `ONE_TIME`
- Akses sekali jalan.
- Download link signed + expiry.
- Opsional batas unduh (default 1 kali).

2) `MEMBERSHIP`
- Akses berulang via member area.
- Entitlement berdasarkan email/user.
- Masa berlaku entitlement:
  - lifetime,
  - atau N hari.

### 6.5 Access Page & Download Security

- Halaman akses bisa dibuat user dengan Elementor.
- Plugin menyediakan shortcode gate:
  - `[bayarqr_digital_access product="slug-produk"]`
- File tidak disajikan sebagai URL publik langsung.
- Download harus melalui endpoint plugin yang memverifikasi entitlement.
- Signed token untuk link unduh harus memiliki:
  - expiry timestamp,
  - signature,
  - product binding,
  - user/email binding.

### 6.6 Mini Membership

- Model identitas:
  - email-first.
- Signup flow:
  - tidak wajib registrasi penuh sebelum bayar,
  - setelah bayar sukses bisa dibuat akun mini atau magic session.
- Member area:
  - daftar produk yang dimiliki,
  - tombol unduh/akses ulang,
  - blok upsell/cross-sell.

### 6.7 SMTP Custom (Pro+)

- Setting:
  - SMTP Host,
  - Port,
  - Secure (TLS/SSL),
  - Username,
  - Password,
  - From Name,
  - From Email.
- Tombol:
  - Send Test Email.
- Jika SMTP belum aktif:
  - email magic link dimatikan,
  - fallback hanya redirect access page.

## 7. Fallback dan Error UX

- Jika pembayaran sukses tapi webhook belum masuk:
  - tampilkan status "Memverifikasi pembayaran, mohon tunggu".
- Jika SMTP tidak aktif:
  - tampilkan info admin: "SMTP belum dikonfigurasi. Fitur email akses nonaktif."
- Jika token akses expired:
  - tampilkan CTA request link baru (Pro+).
- Jika entitlement tidak valid:
  - tampilkan CTA kembali ke halaman produk/checkout.

## 8. Data Model Minimum (Plugin Side)

- `bq_products`
  - id, slug, name, price, policy_mode, status, created_at, updated_at
- `bq_orders`
  - id, product_id, email, bayarqr_ref, payment_status, paid_at, created_at
- `bq_entitlements`
  - id, product_id, email/user_id, mode, expires_at, download_limit, download_count, status
- `bq_access_tokens`
  - id, entitlement_id, token_hash, expires_at, used_at, max_use
- `bq_email_logs`
  - id, template, recipient, status, sent_at, error_summary

## 9. Keamanan Wajib

- Verifikasi webhook signature BayarQR.
- Idempotency handler webhook (hindari grant dobel).
- Semua token akses disimpan hash (bukan plaintext).
- Sanitasi output HTML untuk admin UI plugin.
- Capability checks untuk semua endpoint admin plugin.
- Audit log internal untuk grant/revoke entitlement.

## 10. Non-Goals V1

- Tidak membangun LMS penuh.
- Tidak membangun affiliate system di V1.
- Tidak membangun mail relay BayarQR.
- Tidak menggantikan WooCommerce path untuk produk fisik.

## 11. Kriteria Selesai V1 (Acceptance)

- User dapat publish 1 produk digital dan menerima pembayaran BayarQR.
- Setelah paid, user pembeli dapat membuka access page aman.
- Mode one-time dapat membatasi unduhan sesuai policy.
- Mode membership dapat menampilkan akses ulang di member area.
- SMTP custom (Pro+) berhasil kirim magic link/test mail.
- Semua flow utama punya pesan error/fallback yang jelas.