@extends('docs.layout')

@section('title', 'Barang Keluar (Usage)')

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

@section('page_header')
  <span class="doc-page-badge fase-1"><i class="bi bi-box-arrow-up-right me-1"></i> Modul Mutasi</span>
  <h1 class="doc-page-title">Barang Keluar & Validasi Stok Fisik</h1>
  <p class="doc-page-description">Dokumentasi pencatatan pemakaian material lapangan (Usage), form mutasi multi-baris, serta mekanisme proteksi validasi stok fisik untuk mencegah saldo gudang minus.</p>
@endsection

@section('content')
  <section id="fungsi-usage">
    <h2>1. Fungsi & Struktur Transaksi Barang Keluar</h2>
    <p>Modul Barang Keluar digunakan untuk mencatat material yang diambil dari gudang proyek untuk digunakan pada pekerjaan fisik di lapangan. Struktur data terbagi atas:</p>
    <ul>
      <li><strong>Header Transaksi (<code>usages</code>):</strong> Menyimpan <code>nomor_pengeluaran</code> (Nomor Surat Jalan/Pengeluaran), <code>tanggal_keluar</code>, <code>penanggung_jawab</code> (mandor/kepala tukang yang mengambil), dan <code>keterangan</code>.</li>
      <li><strong>Rincian Barang (<code>usage_details</code>):</strong> Menyimpan baris material yang dikeluarkan, meliputi <code>item_id</code> (material), <code>unit_id</code> (satuan), dan <code>kuantitas</code>.</li>
    </ul>
  </section>

  <section id="algoritma-validasi-stok">
    <h2>2. Algoritma Validasi Stok Fisik Ketat (Stock Validation)</h2>
    <p>Untuk menjaga akurasi pembukuan logistik dan mencegah pengambilan fiktif, <code>UsageController@store</code> dan <code>UsageController@update</code> menjalankan <strong>Validasi Ketersediaan Saldo Fisik</strong>:</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 Stok di Backend</span>
        <p>Sebelum transaksi pemakaian disimpan:</p>
        <ol>
          <li><strong>Menghitung Total Barang Masuk:</strong> Sistem menjumlahkan seluruh pembelian item bersangkutan pada proyek ini <code>$totalIn = PurchaseDetail::whereHas('purchase', fn($q) => $q->where('project_id', $project->id))->where('item_id', $itemId)->sum('kuantitas')</code>.</li>
          <li><strong>Menghitung Total Barang Keluar:</strong> Menjumlahkan pemakaian sebelumnya <code>$totalOut = UsageDetail::whereHas('usage', fn($q) => $q->where('project_id', $project->id))->where('item_id', $itemId)->sum('kuantitas')</code>.</li>
          <li><strong>Menghitung Saldo Stok Tersedia:</strong> <code>$availableStock = $totalIn - $totalOut</code>.</li>
          <li><strong>Evaluasi Skenario Tambah Baru:</strong>
            <pre class="bg-dark text-white p-2 rounded small my-2">IF (Kuantitas_Keluar_Baru > Available_Stock) {
    DB::rollBack();
    // Gagalkan transaksi dan munculkan pesan error:
    // "Stok [Nama Material] tidak mencukupi! Tersedia: X, Diminta: Y"
}</pre>
          </li>
          <li><strong>Evaluasi Skenario Edit Transaksi:</strong>
            <pre class="bg-dark text-white p-2 rounded small my-2">Stok_Efektif = Available_Stock + Kuantitas_Lama_Pada_Transaksi_Ini
IF (Kuantitas_Keluar_Baru > Stok_Efektif) {
    DB::rollBack();
    // Gagalkan update dan tampilkan batas stok efektif
}</pre>
          </li>
        </ol>
      </div>
    </div>
  </section>

  <section id="fitur-form-usage">
    <h2>3. Fitur Form Multi-Baris & Informasi Stok Real-Time</h2>
    <ul>
      <li><strong>Label Info Stok pada Dropdown:</strong> Saat staf membuka form pengeluaran barang (<code>usages/create.blade.php</code>), opsi dropdown material secara cerdas menampilkan sisa stok yang tersedia (misal: <em>"Semen Gresik 50kg (Sisa: 45 Zak)"</em>) sehingga staf langsung mengetahui ketersediaan barang sebelum memilih.</li>
      <li><strong>Multi-Row Input:</strong> Memungkinkan pencatatan pengeluaran banyak jenis material sekaligus dalam satu surat jalan lapangan.</li>
      <li><strong>Lampiran Berita Acara:</strong> Di halaman Detail Pengeluaran (<code>usages/show.blade.php</code>), staf dapat melampirkan foto serah terima barang di lapangan atau pindaian tanda tangan mandor.</li>
    </ul>
  </section>

  <section id="pemetaan-file-usage">
    <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/UsageController.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/Usage.php</code><br><code>app/Models/UsageDetail.php</code></td>
            <td>Relasi Eloquent ke Project, Item, Unit, dan ProjectFile.</td>
          </tr>
          <tr>
            <td>Views</td>
            <td><code>resources/views/admin/usages/</code></td>
            <td>Daftar transaksi (index), form input (create), form edit (edit), dan detail pengeluaran + lampiran (show).</td>
          </tr>
          <tr>
            <td>Routes</td>
            <td><code>routes/web.php</code></td>
            <td>Nested routes: <code>admin/projects/{project}/usages/...</code></td>
          </tr>
        </tbody>
      </table>
    </div>
  </section>
@endsection