@extends('docs.layout')

@section('title', 'Barang Masuk (Purchasing)')

@section('breadcrumb')
  <li class="breadcrumb-item active">Barang Masuk (Purchasing)</li>
@endsection

@section('page_header')
  <span class="doc-page-badge fase-1"><i class="bi bi-box-arrow-in-right me-1"></i> Modul Pengadaan</span>
  <h1 class="doc-page-title">Barang Masuk & Validasi Anggaran</h1>
  <p class="doc-page-description">Dokumentasi transaksi pengadaan material masuk (Purchasing), form dinamis multi-baris, pembuatan master on-the-fly, serta bedah algoritma validasi batas pagu anggaran RAB Material.</p>
@endsection

@section('content')
  <section id="fungsi-purchasing">
    <h2>1. Fungsi & Struktur Transaksi Purchasing</h2>
    <p>Modul Barang Masuk digunakan oleh <strong>Staf Purchasing</strong> untuk mencatat seluruh nota pembelian material dari vendor/toko ke proyek tertentu. Transaksi terbagi menjadi dua level relasi:</p>
    <ul>
      <li><strong>Header Transaksi (<code>purchases</code>):</strong> Menyimpan <code>nomor_po</code> (Nomor Bukti/Invoice), <code>tanggal_pembelian</code>, <code>vendor_id</code>, <code>total_biaya</code> akumulasi, dan <code>keterangan</code>.</li>
      <li><strong>Rincian Barang (<code>purchase_details</code>):</strong> Menyimpan baris-baris item yang dibeli, mencakup <code>item_id</code> (material), <code>unit_id</code> (satuan), <code>kuantitas</code>, <code>harga_satuan</code>, dan <code>subtotal</code>.</li>
    </ul>
  </section>

  <section id="algoritma-validasi-anggaran">
    <h2>2. Algoritma Validasi Anggaran Ketat (Budget Validation)</h2>
    <p>Fitur keamanan paling krusial pada modul ini adalah <strong>Pencegahan Belanja Overbudget</strong> yang berjalan di dalam <code>PurchaseController@store</code> dan <code>PurchaseController@update</code>:</p>
    
    <div class="callout callout-warning">
      <span class="callout-icon"><i class="bi bi-shield-exclamation"></i></span>
      <div class="callout-body">
        <span class="callout-title">Logika Evaluasi Anggaran di Backend</span>
        <p>Sebelum transaksi disimpan ke database:</p>
        <ol>
          <li><strong>Menghitung Total Pagu RAB Material:</strong> Sistem mengambil nilai <code>$rabBudget = $rab->total_material</code> (atau total agregat <code>SUM(total_harga_material)</code> dari <code>rab_details</code> proyek ini).</li>
          <li><strong>Menghitung Realisasi Belanja:</strong> Menjumlahkan seluruh pembelian sebelumnya <code>$totalPurchased = Purchase::where('project_id', $project->id)->sum('total_biaya')</code>.</li>
          <li><strong>Evaluasi Sisa Anggaran (Skenario Tambah Baru):</strong>
            <pre class="bg-dark text-white p-2 rounded small my-2">Sisa_Anggaran = Total_RAB_Material - Total_Pembelian_Sebelumnya
IF (Total_Belanja_Baru > Sisa_Anggaran) {
    DB::rollBack();
    // Gagalkan transaksi dan kembalikan pesan error interaktif
}</pre>
          </li>
          <li><strong>Evaluasi Sisa Anggaran (Skenario Edit Transaksi):</strong>
            <pre class="bg-dark text-white p-2 rounded small my-2">Sisa_Efektif = Total_RAB_Material - (Total_Pembelian_Sebelumnya - Nilai_Transaksi_Lama_Ini)
IF (Total_Belanja_Baru > Sisa_Efektif) {
    DB::rollBack();
    // Gagalkan update dan tampilkan selisih overbudget
}</pre>
          </li>
        </ol>
      </div>
    </div>
  </section>

  <section id="fitur-form-purchasing">
    <h2>3. Fitur Form Multi-Baris & Tagging Otomatis</h2>
    <ul>
      <li><strong>Multi-Row Input:</strong> Form pembelian (<code>purchases/create.blade.php</code> dan <code>purchases/edit.blade.php</code>) memungkinkan staf memasukkan puluhan jenis material sekaligus dalam satu nomor nota/PO.</li>
      <li><strong>Kalkulasi Subtotal & Grand Total Otomatis:</strong> Saat staf memasukkan kuantitas dan harga satuan, JavaScript secara real-time mengalkulasi subtotal baris dan total nota, serta membandingkannya dengan kartu info sisa anggaran yang tampil di atas form.</li>
      <li><strong>On-The-Fly Master Creation:</strong> Jika toko/vendor, material, atau satuan belum terdaftar di master data, staf dapat langsung mengetikkannya di dropdown Select2. Sistem akan otomatis menyimpannya ke tabel master secara permanen tanpa mengganggu proses input transaksi.</li>
      <li><strong>Lampiran Nota Fisik:</strong> Di halaman Detail Pembelian (<code>purchases/show.blade.php</code>), staf dapat mengunggah foto nota, kwitansi, atau PDF surat jalan sebagai bukti audit (Level 3 Attachment).</li>
    </ul>
  </section>

  <section id="pemetaan-file-purchasing">
    <h2>4. Pemetaan File Kode Terkait</h2>
    <div class="table-responsive">
      <table class="table table-bordered table-striped">
        <thead class="table-dark">
          <tr>
            <th>Layer</th>
            <th>File / Direktori</th>
            <th>Fungsi</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td>Controller</td>
            <td><code>app/Http/Controllers/Admin/PurchaseController.php</code></td>
            <td>Method <code>index</code>, <code>create</code>, <code>store</code>, <code>show</code>, <code>edit</code>, <code>update</code>, <code>destroy</code>.</td>
          </tr>
          <tr>
            <td>Models</td>
            <td><code>app/Models/Purchase.php</code><br><code>app/Models/PurchaseDetail.php</code></td>
            <td>Relasi Eloquent ke Project, Vendor, Item, Unit, dan ProjectFile.</td>
          </tr>
          <tr>
            <td>Views</td>
            <td><code>resources/views/admin/purchases/</code></td>
            <td>Daftar transaksi (index), form input (create), form edit (edit), dan detail nota + lampiran (show).</td>
          </tr>
          <tr>
            <td>Routes</td>
            <td><code>routes/web.php</code></td>
            <td>Nested routes: <code>admin/projects/{project}/purchases/...</code></td>
          </tr>
        </tbody>
      </table>
    </div>
  </section>
@endsection