🏛️ Dokumentasi Arsitektur Tata Naskah, Private Vault, & Mesin Pencocokan Pengadaan 3-Arah

Dokumen ini adalah cetak biru teknis dan spesifikasi sistem bagi tim pengembang, arsitek sistem, dan subagent forensic-auditor serta db-security-architect di ERP BUMDes Bolulango, Desa Bandungan, Kecamatan Bulango Utara, Kabupaten Bone Bolango.

---

1. Landasan Arsitektur & Latar Belakang Masalah#

Dalam operasional ERP BUMDes Bolulango, pengelolaan persuratan dinas, dokumen pengadaan barang/pakan ternak, dan bukti transaksi kas/bank menghadapi 4 tantangan integritas:

1. Risiko Akses Terbuka Dokumen Rahasia: Surat keputusan internal, Berita Acara Musdes, dan berkas lelang memerlukan pengamanan ketat agar tidak dapat diakses secara publik melalui URL telanjang (naked public URLs).
2. Risiko Pemalsuan / Penimpaan Berkas Historis: Pengunggahan berkas bukti foto fisik atau scan nota tidak boleh menimpa berkas yang telah tersimpan sebelumnya (immutable archive).
3. Risiko Pembayaran Fiktif / Selisih Tagihan Supplier: Pengadaan bahan pakan ternak (konsentrat, dedak padi, jagung giling) dan sarana kandang secara tempo memerlukan verifikasi otomatis tiga penjuru (Purchase Order vs Goods Receipt Note fisik vs Faktur Supplier) sebelum kas dicairkan.
4. Risiko Penghapusan Sepihak Dokumen Beredar: Naskah dinas resmi yang telah berstatus submitted atau published tidak boleh dihapus secara permanen dari database (anti-hard-delete), melainkan harus melalui alur pembatalan resmi (soft-revoke).

Untuk menjawab tantangan tersebut, sistem menerapkan pengerasan terpadu melalui Migrasi Database 297, modul procurement-3way-match.ts, dan Workspace Rule .agents/rules/standar_tata_naskah_dan_bukti_transaksi.md.

---

2. Spesifikasi Database & Skema Migrasi 297#

Migrasi SQL 297_document_vault_security_hardening_and_procurement_3way_matching.sql mengimplementasikan 4 pilar pengerasan database:

A. Pengerasan Storage Bucket Private Vault

sql
-- Pengerasan bucket official-docs-vault menjadi strictly private
UPDATE storage.buckets 
SET public = false 
WHERE id = 'official-docs-vault';

-- Kebijakan akses baca hanya untuk pengguna terautentikasi (authenticated)
CREATE POLICY "Authenticated users can read official docs vault"
ON storage.objects FOR SELECT
TO authenticated
USING (bucket_id = 'official-docs-vault');

-- Perlindungan anti-mutasi bagi peran pengawasan
CREATE POLICY "Oversight roles cannot upload to official docs vault"
ON storage.objects FOR INSERT
TO authenticated
WITH CHECK (
 bucket_id = 'official-docs-vault' 
 AND NOT public.is_oversight_role()
);

B. Ekspansi Constraint Approval Action

Constraint document_approval_logs_action_check pada tabel document_approval_logs diperluas dari 6 aksi lama menjadi 9 aksi resmi:

• SUBMIT: Pengajuan draf naskah untuk telaah.
• PARAF: Pembubuhan paraf koordinasi oleh pejabat penelaah.
• APPROVE: Persetujuan materi naskah oleh pimpinan.
• REJECT: Penolakan pengajuan naskah dengan catatan revisi.
• PUBLISH: Penetapan dan penerbitan naskah resmi ber-QR publik.
• RESET_TO_DRAFT: Pengembalian naskah ke draf kasar untuk penyuntingan ulang.
• REVISE: Pencatatan revisi redaksional naskah.
• REVOKE: Pembatalan naskah resmi yang telah beredar (soft-revoke).
• ARCHIVE: Pengarsipan naskah pasca-masa retensi aktif.

C. Kolom Rekonsiliasi Pengadaan 3-Arah

• Tabel purchase_transactions:

• grn_number (VARCHAR 64): Nomor unik Goods Receipt Note atomik.
• invoiced_amount (NUMERIC 15,2): Nilai nominal tagihan resmi dari supplier.
• three_way_match_status (VARCHAR 32, default: 'PENDING'): Status hasil evaluasi 3 penjuru.
• three_way_match_metadata (JSONB): Rincian komparasi kuantitas dan harga per item.

• Tabel purchase_items:

• received_quantity (NUMERIC 12,2): Kuantitas fisik riil yang diterima di gudang/kandang.
• invoiced_cost_price (NUMERIC 15,2): Harga satuan final yang tertera pada faktur supplier.

---

3. Arsitektur Pure Engine Pencocokan Pengadaan 3-Arah (procurement-3way-match.ts)#

Modul lib/utils/procurement-3way-match.ts dirancang sebagai fungsi murni (pure deterministic function) bebas efek samping (side-effects) yang dapat diuji secara independen.

Memuat diagram alur...

Logika Ambang Batas Varians:

1. Toleransi Kuantitas: 0% (Kuantitas fisik diterima wajib persis sama dengan PO, kelebihan kirim tanpa PO ditolak).
2. Toleransi Harga Minor: Varians harga satuan < 5% ditandai VARIANCE_PRICE.
3. Pemblokiran Kritis: Varians harga satuan >= 5% atau invoiced_amount > total_amount ditandai DISCREPANCY_BLOCKED.

---

4. Lapisan Pengamanan Server Actions & Storage#

A. Payment Blocking Guard

• lib/actions/purchase.ts (recordSupplierPayment):

typescript
if (purchase.three_way_match_status && purchase.three_way_match_status !== 'MATCHED') {
 return {
 success: false,
 message: 'Pelunasan diblokir: Status 3-Way Match faktur ' + purchase.invoice_number + ' adalah ' + purchase.three_way_match_status + '. Wajib MATCHED atau memiliki persetujuan khusus Direktur.',
 error: 'Pelunasan diblokir: Status 3-Way Match adalah ' + purchase.three_way_match_status + '.'
 }
}

• lib/actions/livestock-payables.ts (settleLivestockSupplierBill): Memeriksa kesesuaian 3-way match sebelum memicu RPC atomik rpc_process_supplier_payment.

B. Anti-Overwrite Storage

• lib/actions/storage.ts & lib/actions/evidence-storage.ts: Parameter pengunggahan berkas dikunci pada upsert: false. Upaya mengunggah berkas dengan nama/path yang sama akan ditolak oleh storage engine.

C. Time-Limited Signed URL Vault

• lib/actions/document-vault.ts (getSignedVaultDocumentUrl):

typescript
export async function getSignedVaultDocumentUrl(
 fileUrlOrPath: string,
 expiresInSeconds: number = 3600
): Promise<{ success: boolean; url?: string; error?: string }> { ... }

Mengonversi path berkas privat menjadi URL bertanda tangan berbatas waktu (maksimal 3600 detik / 1 jam), mencegah kebocoran dokumen dinas dan scan surat masuk.

D. Anti-Hard-Delete & Soft-Revoke

• lib/actions/official-docs.ts (deleteOfficialDocument & revokeOfficialDocument): Dokumen resmi berstatus submitted atau published tidak pernah dihapus via DELETE SQL, melainkan diperbarui statusnya menjadi status = 'revoked' disertai pencatatan aktor pembatalan, alasan pencabutan, dan stempel waktu WITA pada tabel document_approval_logs dengan aksi REVOKE.

---

5. Arsitektur 5 Modalitas Output & Ekspor Dokumen Resmi (On-Demand Rendering)#

Selain penyimpanan database dan Storage Bucket, lapisan output on-demand (Lapis 3) pada ERP BUMDes Bolulango tidak hanya mencakup Microsoft Word (.docx), melainkan 5 modalitas output resmi yang terkalibrasi penuh:

---

6. Ringkasan Pengujian & Kepatuhan Kualitas#

---

Dokumen internal arsitektur teknis ERP BUMDes Bolulango. Dilarang dipublikasikan ke domain publik tanpa izin Super Admin.