Blueprint: Laporan Bukti Foto Transaksi

Dokumen ini memuat visi, standar teknis, arsitektur sistem, dan peta jalan pengembangan fitur Laporan Bukti Foto Transaksi — halaman cetak khusus yang menampilkan seluruh bukti foto (Nota, Fisik Barang, Bukti Pemakaian) secara terurut per transaksi untuk keperluan audit BUMDes.

---

1. Latar Belakang & Tujuan#

Masalah yang Diselesaikan

Auditor BUMDes memerlukan lampiran bukti fisik berupa foto nota dan barang yang terpisah dari laporan angka keuangan. Sebelumnya, foto hanya bisa dilihat satu-satu melalui modal pratinjau di halaman Jurnal Umum. Tidak ada cara untuk mencetak seluruh bukti foto dalam format laporan formal.

Tujuan Fitur

1. Menyediakan halaman cetak khusus yang menampilkan semua foto bukti transaksi dalam periode tertentu.
2. Mengurutkan foto per transaksi (kronologis) dengan metadata lengkap: tanggal, referensi, keterangan, nominal, dan lokasi GPS.
3. Memenuhi standar audit dengan kop surat resmi, nomor halaman, dan tanda tangan formal.
4. Mempercepat proses audit — auditor tidak perlu membuka satu-satu transaksi untuk melihat bukti foto.

---

2. Posisi dalam Ekosistem ERP BUMDes#

┌─────────────────────────────────────────────────────┐
│ MODUL KEUANGAN │
├──────────────┬──────────────┬────────────────────────┤
│ Input Data │ Validasi │ Laporan │
│ │ │ │
│ • Jurnal │ • Anti-Fraud │ • Laba Rugi │
│ • Kas Kecil │ 3-Foto │ • Neraca │
│ • Pembelian │ • GeoTag GPS │ • BKU │
│ • Aset │ │ • Arus Kas │
│ │ │ • **BUKTI FOTO** ← NEW │
└──────────────┴──────────────┴────────────────────────┘

Fitur ini merupakan lapisan output dari sistem Anti-Fraud 3-Foto yang sudah terintegrasi di modul input (Jurnal, Kas Kecil, Pembelian, Aset). Data foto yang dikumpulkan di sisi input kini dapat dicetak dan diarsipkan secara formal.

---

3. Arsitektur Teknis#

3.1 Aliran Data (Data Flow)

[Supabase DB]
 │
 │ journal_entries.evidence_photos (JSONB)
 │ journal_entries.image_urls (Array)
 │
 ▼
[Server Action: getPhotoEvidenceReport()]
 │
 │ Filter: unit_id, month, year
 │ Transform: extract URLs, compute totals
 │ Filter: only entries with photos
 │
 ▼
[Server Component: page.tsx]
 │
 │ RBAC check, unit list, search params
 │
 ▼
[Client Component: PhotoEvidenceClient.tsx]
 │
 ├── Screen Mode: Grid cards + stats
 └── Print Mode: Formal report layout

3.2 Struktur Database

Data foto disimpan dalam kolom evidence_photos bertipe JSONB pada tabel journal_entries:

json
{
 "receipt": {
 "url": "https://storage.example.com/nota.jpg",
 "lat": 0.5432,
 "lng": 123.0123,
 "address": "Jl. Merdeka No. 1, Ketapang",
 "timestamp": "2026-09-02T10:00:00Z",
 "caption": "Nota ATK Toko Berkah"
 },
 "physical_item": {
 "url": "https://storage.example.com/barang.jpg",
 "lat": 0.5432,
 "lng": 123.0123
 },
 "utilization": {
 "url": "https://storage.example.com/pemakaian.jpg",
 "lat": 0.5432,
 "lng": 123.0123
 }
}

3.3 Komponen Utama

3.4 Keamanan & RBAC

• Fungsi resolveFinanceRBAC() diterapkan di server action.
• Manajer Unit / Kepala Unit: hanya melihat data unit yang ditugaskan.
• Super Admin / Direktur: dapat melihat semua unit dan mode konsolidasi.
• Filter unit di klien otomatis terkunci (disabled) untuk pengguna terbatas.

---

4. Desain Antarmuka (UI/UX)#

4.1 Mode Layar (Screen Mode)

• Panel Filter: Pilihan Unit, Bulan, Tahun, dan tombol Cetak.
• Statistik Ringkas: 4 kartu (Total Transaksi, Total Foto, Lengkap 3 Foto, Tidak Lengkap).
• Enhancement: Kartu "Total Transaksi" dilengkapi dengan Donut Chart indikator persentase kelengkapan foto secara keseluruhan.
• Grid Kartu Transaksi: Menampilkan SEMUA transaksi (termasuk yang tidak memiliki foto) untuk mempermudah audit kelalaian.
• Enhancement Header: Dilengkapi lencana (badge) status dinamis: ✅ Lengkap atau ⚠️ Kurang (x/3).
• Enhancement Aksi: Tombol ✏️ Lengkapi muncul pada transaksi yang fotonya tidak lengkap, menyediakan shortcut langsung ke halaman Edit Jurnal.
• Enhancement Foto: Interaktif dengan animasi hover (zoom halus) dan Lightbox Modal layar penuh ketika foto diklik untuk memperbesar detail (resolusi tinggi).

4.2 Arsitektur Output: Cetak Browser, Ekspor PDF, & Arsip ZIP

Modul ini menyediakan tiga kanal luaran (output pipelines) yang telah distandardisasi untuk kebutuhan audit formal:

1. Cetak Browser Langsung (handlePrint)

• Pre-decoding Image Guard: Menggunakan Promise.allSettled() untuk memaksa pemuatan (force decode) seluruh tag <img> di dalam #photo-report-print-area sebelum memicu window.print(). Ini memitigasi isu foto blank di Safari dan Firefox pada transaksi di luar viewport.
• CSS Print Media: Elemen non-dokumen (filter, kartu statistik, tombol aksi, pagination bar) dieliminasi menggunakan utilitas Tailwind print:hidden. Area laporan utama menggunakan print:block.

2. Ekspor PDF A4 Terpaginasi Resmi (handleExportPDF)

• Logo Polling Guard (waitForLogoImage): Sebelum snapshot kanvas diambil, sistem memvalidasi kelengkapan elemen gambar logo instansi (img[alt="Logo"]) via polling asinkron. Hal ini mengeliminasi risiko kop surat kosong akibat keterlambatan respons site identity.
• Engine html2pdf.js dengan Post-Processing .toPdf():

• Paginasi dinamis menghitung totalPages = pdf.internal.getNumberOfPages().
• Garis pembatas footer hijau BUMDes (#047857) digambar sepanjang batas margin bawah.
• Teks resmi identitas instansi (www.bumdesbolulango.site | bolulangobumdes@gmail.com) disematkan di kiri bawah (font Helvetica, 7pt).
• Penomoran halaman resmi (Halaman i / totalPages) disematkan di kanan bawah (font Helvetica bold, #047857).

• Break Rules: Penerapan idx % 2 === 0 ? 'print:break-before-page' : '' dan break-inside-avoid menjamin maksimal 2 transaksi per lembar A4 tanpa potongan foto di tengah halaman.
• Tanda Tangan Formal: Komponen FormalSignatures otomatis dirender di halaman akhir melalui state toggle isPdfGenerating.

3. Unduh Arsip ZIP Terpadu (handleExportZIP)

• Arsip Multi-Tier: Mengemas seluruh foto transaksi ke dalam direktori independen [NomorUrut]_[NomorReferensi].
• Rekapitulasi CSV Otomatis: Menghasilkan berkas metadata.csv berisi matriks No, Tanggal, Referensi, Keterangan, Pembuat, Nominal, dan Nama Folder.
• Resiliensi Signed URL (Fail-Safe): Fetch gambar dijalankan via Promise.allSettled. Apabila ada URL foto Supabase Storage CDN yang telah kedaluwarsa (expired), proses tidak dibatalkan; melainkan disematkan berkas placeholder .GAGAL_DIUNDUH.txt pada folder terkait, dan pengguna diberitahu via toast.warning() yang merinci jumlah foto yang terdampak.

4.3 Layout Cetak Per Halaman

┌───────────────────────────────────────────┐
│ KOP SURAT BUMDES (FormalHeader) │
│ LAPORAN BUKTI FOTO TRANSAKSI │
│ Periode: September 2026 │
│ Unit: LKTPG (Sub-Holding Ketapang) │
├───────────────────────────────────────────┤
│ #1 02/09/2026 KTPG/20260902/003 │
│ "Pembelian ATK" Rp 750.000 │
│ ● 5-213 Beban Perlengkapan & ATK │
│ ● 1-100 Kas Tunai BUMDes Pusat │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 📄 NOTA │ │ 📦 FISIK │ │ ✅ PAKAI │ │
│ │ [foto] │ │ [foto] │ │ [foto] │ │
│ │ GPS: ... │ │ GPS: ... │ │ GPS: ... │ │
│ └──────────┘ └──────────┘ └──────────┘ │
├───────────────────────────────────────────┤
│ #2 (transaksi berikutnya...) │
├───────────────────────────────────────────┤
│ TANDA TANGAN FORMAL │
│ FormalReportFooter │
└───────────────────────────────────────────┘

---

5. Integrasi dengan Modul Lain#

5.1 Sumber Data Foto

Foto masuk ke kolom evidence_photos dari modul-modul berikut:

5.2 Ketergantungan Komponen

• MultiPhotoGeoTagUploader — komponen input foto di sisi formulir.
• validateJurnalPhotos() — validasi wajib 3 foto di sisi submit.
• getPhotoEvidenceReport() — query data untuk laporan cetak.

---

6. Peta Jalan Pengembangan (Roadmap)#

Fase 1 — Fondasi (✅ Selesai)

• Halaman laporan foto per unit dan periode
• Filter Unit, Bulan, Tahun
• Statistik ringkas (total, lengkap, tidak lengkap)
• Layout cetak formal dengan kop surat dan tanda tangan
• Page break otomatis setiap 2 transaksi
• Menu sidebar di bawah "Laporan Keuangan"

Fase 2 — Peningkatan Cetak & Ekspor (✅ Selesai)

• Ekspor ke PDF langsung (tanpa dialog cetak browser)
• Ekspor ke ZIP (unduh semua foto + CSV metadata)
• Watermark "RAHASIA / CONFIDENTIAL" pada mode cetak (Dibatalkan demi asas transparansi BUMDes)
• Nomor halaman otomatis di footer cetak (Terakomodasi oleh engine print browser/pdf)

Fase 3 — Verifikasi & Audit (✅ Selesai)

• Peta lokasi GPS teragregasi (satu peta menampilkan semua titik foto)
• Deteksi anomali jarak GPS (jika nota dan pemakaian terlalu jauh)
• Kolom checklist verifikasi auditor (centang per foto)
• Integrasi dengan modul Pusat Kontrol untuk flag foto mencurigakan (Anomali Jarak UI)

Fase 4 — Multi-Modul (✅ Selesai)

• Gabungkan foto dari Kas Kecil, Pembelian, dan Aset ke dalam satu laporan terpadu (di-handle via Universal Journal)
• Filter berdasarkan jenis transaksi (jurnal / kas kecil / pembelian) berdasarkan nomor referensi
• Laporan perbandingan bulanan (tren kelengkapan foto) menggunakan recharts

---

7. Catatan Teknis#

Performa

• Query Supabase menggunakan filter entry_date untuk membatasi jumlah data.
• Foto di-render dengan object-cover di layar dan object-contain saat cetak.
• Foto lama (image_urls) tetap ditampilkan di bagian terpisah untuk kompatibilitas.

Status Pasca-Remediasi (07/09/2026 - ✅ Tuntas 100%)

• Multi-Modul Data Flow: ✅ Selesai. Foto dari modul Kas Kecil (petty_cash_vouchers), Pembelian (purchase_transactions), dan Perbendaharaan (treasury_transactions) telah disinkronkan ke journal_entries.evidence_photos via stored procedure (rpc_create_treasury_transaction, rpc_receive_purchase_goods) dan query langsung agregasi voucher kas kecil.
• Ekspor PDF Langsung: ✅ Selesai. Komponen Kop Surat Resmi (FormalReportHeader) dan Lembar Tanda Tangan (FormalSignatures) kini dirender aktif saat ekspor PDF via state isPdfGenerating.
• Filter Sumber Modul: ✅ Selesai. Grid dan cetak menggunakan filteredEntries.
• Ambang Batas Anomali Jarak: ✅ Selesai. Disesuaikan ke batas rasional 25 km (25.000 meter) untuk mencegah alarm palsu.
• Keamanan Otorisasi (RBAC): ✅ Selesai. verifyPhotoEvidence dilindungi guard otorisasi auditor dan revalidasi cache realtime.
• Paging A4: ✅ Selesai. Ditetapkan 2 transaksi per lembar dengan utilitas break-inside-avoid.

---

8. Riwayat Audit & Evaluasi Teknis#

---

Dokumen ini merupakan acuan teknis dan strategis untuk pengembangan fitur Laporan Bukti Foto Transaksi di ERP BUMDes.