@extends('docs.layout')

@section('title', 'Arsitektur & Database')

@section('breadcrumb')
  <li class="breadcrumb-item active">Arsitektur & Database</li>
@endsection

@section('page_header')
  <span class="doc-page-badge fase-1"><i class="bi bi-diagram-3 me-1"></i> Arsitektur Sistem</span>
  <h1 class="doc-page-title">Arsitektur & Skema Database</h1>
  <p class="doc-page-description">Penjelasan struktur direktori kode sumber, pola arsitektur MVC framework Laravel 10, daftar file Controller & Model, serta relasi skema database (ERD) 15 tabel.</p>
@endsection

@section('content')
  <section id="pola-arsitektur">
    <h2>1. Pola Arsitektur MVC</h2>
    <p>Sistem Informasi SSE dibangun di atas framework <strong>Laravel 10 (PHP 8.1+)</strong> dengan mengadopsi standar arsitektur <em>Model-View-Controller (MVC)</em>. Pemisahan tugas diimplementasikan secara jelas:</p>
    <ul>
      <li><strong>Model (<code>app/Models/</code>):</strong> Merepresentasikan entitas data bisnis dan mengelola relasi Eloquent ORM (misal: <code>hasMany</code>, <code>belongsTo</code>, <code>morphMany</code>).</li>
      <li><strong>View (<code>resources/views/admin/</code>):</strong> Template antarmuka pengguna berbasis Blade yang terintegrasi dengan Bootstrap 5, DataTables, dan Select2.</li>
      <li><strong>Controller (<code>app/Http/Controllers/Admin/</code>):</strong> Mengatur alur logika bisnis, validasi request data, transaksi database (<code>DB::transaction</code>), dan kalkulasi saldo anggaran/stok.</li>
      <li><strong>Routing (<code>routes/web.php</code>):</strong> Mendefinisikan endpoint web yang dilindungi oleh middleware otentikasi (<code>auth</code>) dan kontrol hak akses peran (<code>role:admin,...</code>).</li>
    </ul>
  </section>

  <section id="struktur-folder-lengkap">
    <h2>2. Pemetaan Struktur Direktori</h2>
    <p>Berikut adalah rincian folder utama proyek dan perannya dalam aplikasi:</p>
    
    <div class="table-responsive">
      <table class="table table-bordered table-striped">
        <thead class="table-dark">
          <tr>
            <th>Path Direktori / File</th>
            <th>Fungsi & Cakupan</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td><code>app/Http/Controllers/Admin/</code></td>
            <td>Tempat berkumpulnya 11 Controller utama yang menangani seluruh operasi CRUD dan logika validasi per modul admin.</td>
          </tr>
          <tr>
            <td><code>app/Http/Controllers/AuthController.php</code></td>
            <td>Menangani alur autentikasi login berbasis username, lockout rate limiter, dan logout.</td>
          </tr>
          <tr>
            <td><code>app/Http/Middleware/RoleMiddleware.php</code></td>
            <td>Guard middleware yang mencegat request dan memastikan pengguna memiliki role yang sesuai sebelum mengakses modul tertentu (mencegah error 403 Forbidden).</td>
          </tr>
          <tr>
            <td><code>app/Models/</code></td>
            <td>Menyimpan 11 class Eloquent Model yang mendefinisikan casting tipe data, fillable attributes, dan relasi database antar tabel.</td>
          </tr>
          <tr>
            <td><code>database/migrations/</code></td>
            <td>Kumpulan 23 file migrasi skema database yang mendefinisikan struktur tabel, kolom, index, dan foreign key constraints.</td>
          </tr>
          <tr>
            <td><code>database/seeders/</code></td>
            <td>Berisi seeder awal master data (<code>DatabaseSeeder.php</code> dan <code>UnitSeeder.php</code> untuk inisialisasi 16+ satuan standar).</td>
          </tr>
          <tr>
            <td><code>resources/views/admin/</code></td>
            <td>Berisi 47 file Blade view yang dikelompokkan ke dalam sub-folder tiap modul (<code>projects</code>, <code>rab</code>, <code>purchases</code>, <code>usages</code>, <code>stocks</code>, <code>paid-wages</code>, <code>items</code>, <code>vendors</code>, <code>units</code>, <code>users</code>).</td>
          </tr>
          <tr>
            <td><code>resources/views/admin/partials/</code></td>
            <td>Komponen reusable seperti header navbar (<code>header.blade.php</code>), flash toast notifications (<code>toast_messages.blade.php</code>), dan section lampiran polymorphic (<code>project_files_section.blade.php</code>).</td>
          </tr>
          <tr>
            <td><code>resources/views/layouts/app.blade.php</code></td>
            <td>Master layout panel admin berbasis tema Sneat (warna utama hijau <code>#16a34a</code>) yang memuat sidebar menu, navbar, script modal z-index handler, dan assets bundle.</td>
          </tr>
          <tr>
            <td><code>resources/views/docs/</code></td>
            <td>Pusat dokumentasi internal sistem yang terintegrasi langsung dengan framework Blade dan diproteksi akses login admin.</td>
          </tr>
        </tbody>
      </table>
    </div>
  </section>

  <section id="daftar-controller">
    <h2>3. Daftar Controller & Peran Logika</h2>
    <p>Rincian peran dari 11 Controller admin yang menggerakkan sistem:</p>
    
    <div class="table-responsive">
      <table class="table table-bordered table-hover">
        <thead class="table-light">
          <tr>
            <th>Nama Controller</th>
            <th>Tanggung Jawab Logika Utama</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td><code>DashboardController.php</code></td>
            <td>Mengalkulasi metrik agregat di beranda (Total Proyek, Total Realisasi Belanja, Total Upah, Total Budget RAP) serta merender progress bar per proyek aktif.</td>
          </tr>
          <tr>
            <td><code>ProjectController.php</code></td>
            <td>Manajemen CRUD Proyek dan penyediaan halaman Detail Proyek dengan navigasi Tab horizontal ERP.</td>
          </tr>
          <tr>
            <td><code>RabController.php</code></td>
            <td>Modul RAB: Kalkulasi anggaran terpadu (Upah & Material), auto-suggest AJAX per kategori, parsing impor Excel RAP multi-level, download template Excel, dan cetak print view.</td>
          </tr>
          <tr>
            <td><code>PurchaseController.php</code></td>
            <td>Barang Masuk: Dynamic multi-row input, <strong>validasi batas sisa anggaran RAB Material</strong>, auto-create master on-the-fly, dan edit transaksi dengan rekalkulasi budget efektif.</td>
          </tr>
          <tr>
            <td><code>UsageController.php</code></td>
            <td>Barang Keluar: Dynamic multi-row input, <strong>validasi stok fisik ketersediaan barang</strong>, dan edit transaksi dengan rekalkulasi stok efektif.</td>
          </tr>
          <tr>
            <td><code>StockController.php</code></td>
            <td>Monitoring Stok: Agregasi saldo berjalan per material, tabel buku besar (ledger) kronologis per transaksi masuk/keluar, dan cetak laporan stok resmi.</td>
          </tr>
          <tr>
            <td><code>PaidWageController.php</code></td>
            <td>Upah Terbayar: Pencatatan realisasi upah tukang, pemetaan ke uraian pekerjaan RAB Upah, persentase realisasi anggaran upah, dan cetak laporan upah.</td>
          </tr>
          <tr>
            <td><code>ProjectFileController.php</code></td>
            <td>Manajemen File: Upload file lampiran polymorphic, hapus file & record, download stream, dan in-page modal preview (PDF & Gambar).</td>
          </tr>
          <tr>
            <td><code>ItemController.php</code></td>
            <td>CRUD Master Material, auto-generated kode barang, relasi kategori dan satuan master.</td>
          </tr>
          <tr>
            <td><code>VendorController.php</code></td>
            <td>CRUD Master Vendor/Pemasok material beserta kontak dan alamat.</td>
          </tr>
          <tr>
            <td><code>UnitController.php</code></td>
            <td>CRUD Master Satuan (m3, m2, kg, zak, btg, dll) yang tersinkronisasi ke seluruh dropdown sistem.</td>
          </tr>
          <tr>
            <td><code>RabCategoryController.php</code></td>
            <td>CRUD Kategori Pekerjaan RAB (Persiapan, Tanah, Pondasi, Struktur Beton, dll).</td>
          </tr>
          <tr>
            <td><code>UserController.php</code></td>
            <td>Manajemen Pengguna (Admin only): Create/edit user, ganti password, ganti role, upload foto profil, dan pemantauan waktu login terakhir.</td>
          </tr>
        </tbody>
      </table>
    </div>
  </section>

  <section id="skema-database-erd">
    <h2>4. Skema Database & Relasi Eloquent (ERD)</h2>
    <p>Database sistem terdiri dari 15 tabel utama yang saling berelasi erat:</p>

    <div class="table-responsive">
      <table class="table table-bordered table-striped">
        <thead class="table-dark">
          <tr>
            <th>Nama Tabel</th>
            <th>Model Terkait</th>
            <th>Foreign Keys & Relasi Eloquent</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td><code>projects</code></td>
            <td><code>Project</code></td>
            <td>
              <code>hasMany(Rab)</code>, <code>hasMany(Purchase)</code>, <code>hasMany(Usage)</code>, <code>hasMany(PaidWage)</code>, <code>hasMany(ProjectFile)</code>
            </td>
          </tr>
          <tr>
            <td><code>rabs</code></td>
            <td><code>Rab</code></td>
            <td>
              <code>project_id</code> &rarr; <code>projects.id</code> (Cascade Delete).<br>
              <code>hasMany(RabDetail)</code>
            </td>
          </tr>
          <tr>
            <td><code>rab_details</code></td>
            <td><code>RabDetail</code></td>
            <td>
              <code>rab_id</code> &rarr; <code>rabs.id</code> (Cascade Delete).<br>
              <code>rab_category_id</code> &rarr; <code>rab_categories.id</code> (Nullable).<br>
              <code>morphMany(ProjectFile, 'fileable')</code>
            </td>
          </tr>
          <tr>
            <td><code>purchases</code></td>
            <td><code>Purchase</code></td>
            <td>
              <code>project_id</code> &rarr; <code>projects.id</code>, <code>vendor_id</code> &rarr; <code>vendors.id</code>.<br>
              <code>hasMany(PurchaseDetail)</code>, <code>morphMany(ProjectFile, 'fileable')</code>
            </td>
          </tr>
          <tr>
            <td><code>purchase_details</code></td>
            <td><code>PurchaseDetail</code></td>
            <td>
              <code>purchase_id</code> &rarr; <code>purchases.id</code> (Cascade Delete).<br>
              <code>item_id</code> &rarr; <code>items.id</code>, <code>unit_id</code> &rarr; <code>units.id</code> (Nullable).
            </td>
          </tr>
          <tr>
            <td><code>usages</code></td>
            <td><code>Usage</code></td>
            <td>
              <code>project_id</code> &rarr; <code>projects.id</code>.<br>
              <code>hasMany(UsageDetail)</code>, <code>morphMany(ProjectFile, 'fileable')</code>
            </td>
          </tr>
          <tr>
            <td><code>usage_details</code></td>
            <td><code>UsageDetail</code></td>
            <td>
              <code>usage_id</code> &rarr; <code>usages.id</code> (Cascade Delete).<br>
              <code>item_id</code> &rarr; <code>items.id</code>, <code>unit_id</code> &rarr; <code>units.id</code> (Nullable).
            </td>
          </tr>
          <tr>
            <td><code>paid_wages</code></td>
            <td><code>PaidWage</code></td>
            <td>
              <code>project_id</code> &rarr; <code>projects.id</code>.<br>
              <code>rab_detail_id</code> &rarr; <code>rab_details.id</code> (Nullable).
            </td>
          </tr>
          <tr>
            <td><code>items</code></td>
            <td><code>Item</code></td>
            <td>
              <code>item_category_id</code> &rarr; <code>item_categories.id</code>.<br>
              <code>unit_id</code> &rarr; <code>units.id</code> (Nullable).
            </td>
          </tr>
          <tr>
            <td><code>project_files</code></td>
            <td><code>ProjectFile</code></td>
            <td>
              <code>project_id</code> &rarr; <code>projects.id</code>.<br>
              Polymorphic: <code>fileable_id</code> & <code>fileable_type</code> (merujuk ke Project, Purchase, Usage, atau RabDetail).
            </td>
          </tr>
          <tr>
            <td><code>vendors</code></td>
            <td><code>Vendor</code></td>
            <td><code>hasMany(Purchase)</code></td>
          </tr>
          <tr>
            <td><code>units</code></td>
            <td><code>Unit</code></td>
            <td><code>hasMany(Item)</code>, <code>hasMany(PurchaseDetail)</code>, <code>hasMany(UsageDetail)</code></td>
          </tr>
          <tr>
            <td><code>item_categories</code></td>
            <td><code>ItemCategory</code></td>
            <td><code>hasMany(Item)</code></td>
          </tr>
          <tr>
            <td><code>rab_categories</code></td>
            <td><code>RabCategory</code></td>
            <td><code>hasMany(RabDetail)</code></td>
          </tr>
          <tr>
            <td><code>users</code></td>
            <td><code>User</code></td>
            <td>Menyimpan credential login, role (enum/string), photo_path, dan last_login_at.</td>
          </tr>
        </tbody>
      </table>
    </div>
  </section>

  <section id="konvensi-frontend">
    <h2>5. Standar Komponen & Konvensi Frontend</h2>
    <ul>
      <li><strong>CSS Tema & Palet Warna:</strong> Menggunakan palet hijau SSE (<code>#16a34a</code>) sebagai warna utama brand.</li>
      <li><strong>DataTables Integration:</strong> Seluruh tabel data dilengkapi dengan penomoran berurutan otomatis (<code>$loop->iteration</code>), pencarian client-side, dan pagination.</li>
      <li><strong>Select2 Tags:</strong> Dropdown pemilihan data master dikonfigurasi dengan <code>tags: true</code> untuk memungkinkan penginputan instan on-the-fly.</li>
      <li><strong>Print Optimization:</strong> Semua halaman laporan (RAB, Stok, Upah) dilengkapi dengan aturan CSS <code>@media print</code> yang secara otomatis menyembunyikan sidebar, navbar, tombol aksi, dan pagination saat dicetak ke printer atau disimpan sebagai PDF.</li>
    </ul>
  </section>
@endsection