@extends('docs.layout')

@section('title', 'Manajemen Lampiran File')

@section('breadcrumb')
  <li class="breadcrumb-item active">Manajemen Lampiran</li>
@endsection

@section('page_header')
  <span class="doc-page-badge fase-1"><i class="bi bi-paperclip me-1"></i> Modul Media</span>
  <h1 class="doc-page-title">Manajemen Lampiran Dokumen Multi-Level</h1>
  <p class="doc-page-description">Dokumentasi arsitektur penyimpanan berkas lampiran berbasis relasi Polymorphic, 3 tingkat hierarki lampiran, fitur in-page modal preview, dan penanganan multi-modal z-index.</p>
@endsection

@section('content')
  <section id="arsitektur-polymorphic">
    <h2>1. Arsitektur Lampiran Polymorphic</h2>
    <p>Untuk menghindari pembuatan tabel file yang terpisah-pisah untuk setiap modul, sistem SSE menggunakan satu tabel terpusat <code>project_files</code> dengan memanfaatkan relasi <strong>Eloquent Polymorphic (<code>nullableMorphs</code>)</strong>:</p>
    
    <div class="table-responsive">
      <table class="table table-bordered table-striped">
        <thead class="table-dark">
          <tr>
            <th>Kolom Database</th>
            <th>Tipe Data</th>
            <th>Fungsi & Peran</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td><code>project_id</code></td>
            <td><code>BIGINT (FK)</code></td>
            <td>Mengaitkan file ke proyek yang bersangkutan (untuk isolasi folder penyimpanan).</td>
          </tr>
          <tr>
            <td><code>fileable_id</code></td>
            <td><code>BIGINT (Nullable)</code></td>
            <td>ID dari entitas pemilik berkas (misal: ID transaksi Purchase, ID baris RabDetail).</td>
          </tr>
          <tr>
            <td><code>fileable_type</code></td>
            <td><code>VARCHAR (Nullable)</code></td>
            <td>Nama class Model pemilik berkas (<code>App\Models\Purchase</code>, <code>App\Models\Usage</code>, <code>App\Models\RabDetail</code>, atau <code>NULL</code> untuk level modul).</td>
          </tr>
          <tr>
            <td><code>nama_file</code> / <code>nama_asli</code></td>
            <td><code>VARCHAR</code></td>
            <td>Nama file terenkripsi unik di disk dan nama asli saat diunggah pengguna.</td>
          </tr>
          <tr>
            <td><code>path_file</code></td>
            <td><code>VARCHAR</code></td>
            <td>Lokasi penyimpanan pada direktori <code>storage/app/public/project-files/{project_id}/</code>.</td>
          </tr>
          <tr>
            <td><code>ukuran_file</code> / <code>mime_type</code></td>
            <td><code>BIGINT / VARCHAR</code></td>
            <td>Metadata ukuran berkas dalam bytes dan tipe MIME (cth: <code>application/pdf</code>, <code>image/jpeg</code>).</td>
          </tr>
        </tbody>
      </table>
    </div>
  </section>

  <section id="tiga-level-lampiran">
    <h2>2. Tiga Tingkat Hierarki Lampiran (3-Level Attachments)</h2>
    <p>Fitur lampiran melayani 3 kebutuhan operasional yang berbeda:</p>
    
    <div class="row g-3 my-2">
      <div class="col-md-4">
        <div class="card h-100 border-0 shadow-sm p-3 bg-light">
          <h6 class="fw-bold text-success"><i class="bi bi-folder2-open me-2"></i> Level 1: Modul / Proyek</h6>
          <p class="small text-muted mb-0">Disediakan via partial <code>project_files_section.blade.php</code> di halaman RAB, Rekap Stok, dan Upah Terbayar. Digunakan untuk dokumen umum (Surat Perjanjian Kontrak, SPK, RAP Master, Berita Acara Rekap).</p>
        </div>
      </div>
      <div class="col-md-4">
        <div class="card h-100 border-0 shadow-sm p-3 bg-light">
          <h6 class="fw-bold text-success"><i class="bi bi-card-checklist me-2"></i> Level 2: Baris Rincian RAB</h6>
          <p class="small text-muted mb-0">Tombol paperclip dan badge indikator <code>📎 N</code> per baris tabel RAB. Digunakan untuk melampirkan gambar kerja teknik, detail potongan konstruksi, atau analisis harga satuan spesifik rincian tersebut.</p>
        </div>
      </div>
      <div class="col-md-4">
        <div class="card h-100 border-0 shadow-sm p-3 bg-light">
          <h6 class="fw-bold text-success"><i class="bi bi-receipt me-2"></i> Level 3: Per Transaksi Faktur</h6>
          <p class="small text-muted mb-0">Tersedia di halaman Detail Pembelian (<code>purchases/show</code>) dan Detail Pemakaian (<code>usages/show</code>). Digunakan untuk melampirkan foto nota belanja toko, invoice vendor, kwitansi, atau surat jalan bermaterai.</p>
        </div>
      </div>
    </div>
  </section>

  <section id="in-page-preview-multimodal">
    <h2>3. Modal Preview In-Page & Multi-Modal Stacking Handler</h2>
    <ul>
      <li><strong>In-Page Modal Preview (<code>#modalGlobalFilePreview</code>):</strong> Pengguna tidak perlu membuka tab baru untuk membaca dokumen. Mengklik tombol pratinjau (👁️) akan langsung membuka pop-up modal:
        <ul>
          <li><strong>File Gambar (JPG/PNG):</strong> Ditampilkan responsif di tengah modal.</li>
          <li><strong>File Dokumen PDF:</strong> Ditampilkan interaktif menggunakan viewer <code>&lt;iframe&gt;</code> bawaan browser.</li>
        </ul>
      </li>
      <li><strong>Penanganan Multi-Modal z-index (Multi-Modal Handler):</strong> Pada saat modal preview dibuka dari dalam modal upload baris RAB (nested modals), JavaScript di <code>resources/views/layouts/app.blade.php</code> secara otomatis menghitung jumlah modal aktif dan menaikkan <code>z-index</code> modal baru (<code>1090 + count * 20</code>) agar tidak tertutup backdrop abu-abu.</li>
      <li><strong>Download Langsung:</strong> Method <code>download()</code> di <code>ProjectFileController.php</code> mengalirkan file langsung via stream download dengan nama asli file.</li>
    </ul>
  </section>

  <section id="pemetaan-file-attachments">
    <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/ProjectFileController.php</code></td>
            <td>Method <code>store</code>, <code>destroy</code>, <code>download</code>, <code>preview</code>.</td>
          </tr>
          <tr>
            <td>Model</td>
            <td><code>app/Models/ProjectFile.php</code></td>
            <td>Relasi <code>morphTo('fileable')</code>, accessor helper (<code>ukuranReadable</code>, <code>isImage</code>, <code>iconClass</code>).</td>
          </tr>
          <tr>
            <td>Partial View</td>
            <td><code>resources/views/admin/partials/project_files_section.blade.php</code></td>
            <td>Komponen reusable daftar berkas & form upload level modul/transaksi.</td>
          </tr>
          <tr>
            <td>Modal Layout</td>
            <td><code>resources/views/layouts/app.blade.php</code></td>
            <td>Modal global preview (<code>#modalGlobalFilePreview</code>) dan script multi-modal stacking handler.</td>
          </tr>
        </tbody>
      </table>
    </div>
  </section>
@endsection