# AISTANDAR — Standar Pengembangan Aplikasi database-pertani-web

Dokumen ini adalah **aturan wajib** bagi AI (dan developer) yang bekerja di repo ini.
Baca seluruhnya sebelum membuat, mengubah, atau merefaktor kode.

## 0. Cara memakai dokumen ini

- Aturan di sini **mengalahkan** kebiasaan umum atau contoh dari luar. Jika ada konflik antara kode lama dan dokumen ini, ikuti dokumen ini **untuk kode baru**, dan ikuti Bagian 13 (Prosedur Refaktor) untuk kode lama.
- Jika sesuatu **tidak diatur** di sini: lihat dulu bagaimana modul yang sudah sesuai standar melakukannya, lalu tiru polanya. Jika tetap tidak jelas, **tanya**, jangan mengarang pola baru.
- **Jangan** menambah package/library baru, mengubah struktur database yang sudah ada, atau mengubah kontrak API tanpa izin eksplisit.
- Bahasa: teks yang tampil ke pengguna (label, pesan, validasi) memakai **Bahasa Indonesia**. Nama domain (petani, lahan, komoditas) tetap Bahasa Indonesia; kata kerja teknis Laravel (`index`, `store`, `show`) tetap bahasa Inggris.

---

## 1. Stack

| Bagian | Teknologi |
|---|---|
| Framework | Laravel 12 |
| Frontend web | Blade (tanpa Livewire/Inertia) |
| UI template | Vuexy (Bootstrap 5), ikon Tabler |
| Grafik | ApexCharts |
| Peta | Leaflet |
| Auth web | Session |
| Auth API | Laravel Sanctum (token) |
| Dokumentasi API | dedoc/scramble |
| Role | `app/Enums/Role.php` (atau lokasi Role yang sudah ada): `super_admin`, `admin`, `fasilitator`, `petani`, `offtaker` |

---

## 2. Struktur folder & penamaan

### 2.1 Pengelompokan per domain

Controller, Model, Request, dan View **dikelompokkan per domain yang sama**:

```
Domain yang ada: Dashboard, Laporan, Produktivitas, Ekosistem, Program, Master,
                 Bumdes, Koperasi, Konfigurasi
```

| Lapisan | Lokasi |
|---|---|
| Controller web | `app/Http/Controllers/Web/{Domain}/{Model}Controller.php` |
| Controller API | `app/Http/Controllers/Api/{Domain}/{Model}Controller.php` |
| Form Request | `app/Http/Requests/{Domain}/Store{Model}Request.php`, `Update{Model}Request.php` |
| Model | `app/Models/{DomainModel}/{Model}.php` (ikuti folder model yang ada: `Pertanian/`, `Wilayah/`, `Program/`, `Master/`, dst.) |
| Enum | `app/Enums/` |
| Service / Query | `app/Services/{Domain}/` |
| View | `resources/views/{domain}/{modul}/` (huruf kecil, kebab-case) |

Controller baru **tidak boleh** ditaruh di root `app/Http/Controllers/`. Controller root yang sudah ada (`ProgramController`, `ProgramKomoditasController`, `ProgramLokasiController`) dipindahkan ke domain `Program/` saat direfaktor.

### 2.2 Konvensi nama

| Objek | Aturan | Contoh |
|---|---|---|
| Model | Singular, PascalCase | `Petani`, `JenisKomoditas` |
| Tabel | snake_case, **selalu ditulis eksplisit** di model | `protected $table = 'petani';` |
| Controller | `{Model}Controller` | `PetaniController` |
| Route name | `{modul}.{aksi}`, kebab-case | `jenis-komoditas.index` |
| URL | kebab-case | `/jenis-komoditas` |
| View | `{domain}/{modul}/{aksi}.blade.php` | `master/provinsi/index.blade.php` |
| Method tambahan | camelCase | `byProvinsi()`, `list()` |

> Karena nama domain berbahasa Indonesia, pluralisasi otomatis Laravel salah (`petanis`). **Wajib** set `$table` di setiap model, dan set parameter route bila perlu (`->parameters(['jenis-komoditas' => 'jenisKomoditas'])`).

---

## 3. Controller

> **Cakupan:** Bagian 3 berlaku untuk **modul CRUD** (pengelolaan data: tambah, ubah, hapus).
> Controller **Dashboard** dan **Laporan/Reporting** tidak terikat aturan 7 method dan mengikuti aturan yang lebih fleksibel di **Bagian 11**.

### 3.1 Tujuh method resmi

Untuk modul CRUD, gunakan **hanya** nama method resource Laravel:

| Method | HTTP | URL | Route name | Fungsi |
|---|---|---|---|---|
| `index` | GET | `/items` | `items.index` | Daftar data |
| `create` | GET | `/items/create` | `items.create` | Form tambah |
| `store` | POST | `/items` | `items.store` | Simpan baru |
| `show` | GET | `/items/{item}` | `items.show` | Detail |
| `edit` | GET | `/items/{item}/edit` | `items.edit` | Form ubah |
| `update` | PUT/PATCH | `/items/{item}` | `items.update` | Simpan perubahan |
| `destroy` | DELETE | `/items/{item}` | `items.destroy` | Hapus (soft delete) |

**Dilarang** memakai nama `add`, `view`, `save`, `delete`, `remove`, `detail`, atau sejenisnya untuk aksi CRUD. (Larangan ini tidak berlaku untuk Dashboard dan Laporan, lihat Bagian 11.)

### 3.2 Prinsip controller tipis

- Validasi **selalu** di Form Request, tidak pernah `$request->validate()` di controller.
- Controller hanya: terima request → panggil model/service → kembalikan respons.
- Logika bisnis yang lebih dari ±15 baris, dipakai di lebih dari satu tempat, atau melibatkan banyak tabel → pindahkan ke `app/Services/{Domain}/`.
- Operasi yang menulis ke lebih dari satu tabel → bungkus dengan `DB::transaction()`.
- Pakai route model binding (`Petani $petani`), bukan `find($id)`.

### 3.3 Tiga pola resmi

Pilih **satu** pola per modul berdasarkan tabel ini:

| Pola | Kapan dipakai | Contoh |
|---|---|---|
| **A. Offcanvas (AJAX)** | Data referensi/sederhana: sedikit field, tanpa halaman detail yang kaya | Provinsi, Kabupaten, Komoditas, Varietas, Adat |
| **B. Resource halaman** | Entitas utama: banyak field, ada relasi, perlu halaman detail | Lahan, Produksi, Workshop, BUMDes, Koperasi |
| **C. Detail multi-tab** | Entitas induk dengan banyak bagian data yang diisi bertahap | Petani, Survey Kelompok Tani |

---

#### Pola A — Offcanvas (AJAX)

- `index` mengembalikan **view**; `store`, `show`, `update`, `destroy` mengembalikan **JSON**.
- Tidak ada halaman `create`/`edit`; form ada di offcanvas di `index.blade.php`.
- `show` dipakai JS untuk mengisi form edit di offcanvas.

```php
// routes/web.php
// Route tambahan WAJIB didaftarkan SEBELUM Route::resource agar tidak tertangkap {provinsi}
Route::get('provinsi/list', [ProvinsiController::class, 'list'])->name('provinsi.list');
Route::resource('provinsi', ProvinsiController::class)->except(['create', 'edit']);
```

```php
namespace App\Http\Controllers\Web\Master;

class ProvinsiController extends Controller
{
    public function index(Request $request)
    {
        $provinsi = Provinsi::query()
            ->when($request->search, fn ($q, $s) => $q->where('nama', 'like', "%{$s}%"))
            ->latest()
            ->paginate(15)
            ->withQueryString();

        return view('master.provinsi.index', compact('provinsi'));
    }

    public function store(StoreProvinsiRequest $request)
    {
        $provinsi = Provinsi::create($request->validated());

        return response()->json([
            'success' => true,
            'message' => 'Provinsi berhasil ditambahkan.',
            'data'    => $provinsi,
        ], 201);
    }

    public function show(Provinsi $provinsi)
    {
        return response()->json(['success' => true, 'data' => $provinsi]);
    }

    public function update(UpdateProvinsiRequest $request, Provinsi $provinsi)
    {
        $provinsi->update($request->validated());

        return response()->json([
            'success' => true,
            'message' => 'Provinsi berhasil diperbarui.',
            'data'    => $provinsi,
        ]);
    }

    public function destroy(Provinsi $provinsi)
    {
        DB::transaction(fn () => $provinsi->delete());

        return response()->json([
            'success' => true,
            'message' => 'Provinsi berhasil dihapus.',
        ]);
    }
}
```

**Dropdown berantai** (provinsi → kabupaten → kecamatan → desa): method `by{Induk}` di controller anak, mengembalikan JSON `[{id, nama}]`.

```php
Route::get('kabupaten/by-provinsi/{provinsi}', [KabupatenController::class, 'byProvinsi'])
    ->name('kabupaten.by-provinsi');
```

---

#### Pola B — Resource halaman

- Semua 7 method; view `index`, `create`, `edit`, `show` + partial `_form`.
- Setelah `store`/`update`/`destroy` → **redirect** dengan flash message.

```php
Route::resource('lahan', LahanController::class);
```

```php
namespace App\Http\Controllers\Web\Produktivitas;

class LahanController extends Controller
{
    public function index(Request $request)
    {
        $lahan = Lahan::query()
            ->with(['petani', 'desa'])
            ->when($request->search, fn ($q, $s) => $q->where('nama', 'like', "%{$s}%"))
            ->latest()
            ->paginate(15)
            ->withQueryString();

        return view('produktivitas.lahan.index', compact('lahan'));
    }

    public function create()
    {
        return view('produktivitas.lahan.create', ['lahan' => new Lahan()]);
    }

    public function store(StoreLahanRequest $request)
    {
        $lahan = Lahan::create($request->validated());

        return redirect()->route('lahan.show', $lahan)
            ->with('success', 'Lahan berhasil ditambahkan.');
    }

    public function show(Lahan $lahan)
    {
        $lahan->load(['petani', 'tanaman']);

        return view('produktivitas.lahan.show', compact('lahan'));
    }

    public function edit(Lahan $lahan)
    {
        return view('produktivitas.lahan.edit', compact('lahan'));
    }

    public function update(UpdateLahanRequest $request, Lahan $lahan)
    {
        $lahan->update($request->validated());

        return redirect()->route('lahan.show', $lahan)
            ->with('success', 'Lahan berhasil diperbarui.');
    }

    public function destroy(Lahan $lahan)
    {
        DB::transaction(fn () => $lahan->delete());

        return redirect()->route('lahan.index')
            ->with('success', 'Lahan berhasil dihapus.');
    }
}
```

---

#### Pola C — Detail multi-tab

- Controller induk (mis. `PetaniController`) memakai Pola B.
- Setiap tab punya **controller sendiri** (`PetaniLahanController`, `PraktikBudidayaController`, …) yang tetap memakai nama method resmi.
- Tab dirangkai sebagai **nested shallow resource** di bawah induk.
- View: `header.blade.php` berisi kartu profil + navigasi tab; setiap tab punya subfolder.
- Tab selain Profil **terkunci** sampai profil induk lengkap. Logika penguncian ditaruh di satu tempat (method di model induk, mis. `$petani->profilLengkap()`), bukan diulang di tiap view.

```
resources/views/produktivitas/petani/
├── index.blade.php
├── create.blade.php
├── edit.blade.php
├── show.blade.php          ← tab Profil
├── header.blade.php        ← kartu profil + navigasi tab
├── _form.blade.php
├── lahan-tanaman/
│   ├── index.blade.php
│   └── ...
├── praktik-budidaya/
└── ...
```

```php
Route::resource('petani', PetaniController::class);
Route::resource('petani.praktik-budidaya', PraktikBudidayaController::class)->shallow();
```

### 3.4 Batas resource

- Jika modul tidak butuh semua aksi, batasi dengan `->only([...])` / `->except([...])`. Jangan biarkan route yang tidak punya method terdaftar.
- Method di luar 7 aksi resmi hanya boleh untuk: dropdown/list (`list`, `by{Induk}`), aksi status yang jelas (`verify`, `approve`), dan export (`export`). Daftarkan sebelum `Route::resource`.

---

## 4. Validasi

- Setiap `store` dan `update` memakai Form Request: `Store{Model}Request`, `Update{Model}Request`.
- Pesan dan atribut dalam Bahasa Indonesia (`messages()` / `attributes()`, atau file `lang/id/validation.php`).
- Form Request yang sama boleh dipakai controller Web dan API.
- Untuk Pola A, Form Request otomatis mengembalikan JSON 422 karena request AJAX mengirim header `Accept: application/json`. **Jangan** menangkap error validasi secara manual.
- **Unique wajib mengabaikan data yang sudah di-soft delete** (lihat 5.3).

```php
public function rules(): array
{
    return [
        'kode' => [
            'required', 'string', 'max:10',
            Rule::unique('provinsi', 'kode')
                ->ignore($this->route('provinsi'))
                ->withoutTrashed(),
        ],
        'nama' => ['required', 'string', 'max:100'],
    ];
}
```

---

## 5. Model, migration, dan soft delete

### 5.1 Model

```php
class Lahan extends Model
{
    use SoftDeletes;

    protected $table = 'lahan';

    protected $fillable = ['petani_id', 'desa_id', 'nama', 'luas'];

    protected function casts(): array
    {
        return [
            'luas'          => 'decimal:2',
            'status_milik'  => StatusKepemilikan::class, // Enum
        ];
    }
}
```

- Pakai `$fillable`, bukan `$guarded = []`.
- Pilihan tetap (jawaban survei, status) disimpan sebagai **PHP Enum** di `app/Enums/` dan di-cast di model. Jangan menulis daftar pilihan langsung di Blade.

### 5.2 Migration

Setiap tabel baru **wajib** memiliki:

```php
$table->id();
// ... kolom
$table->foreignId('created_by')->nullable()->constrained('users');   // ikuti kolom audit yang sudah ada
$table->foreignId('updated_by')->nullable()->constrained('users');
$table->timestamps();
$table->softDeletes();
$table->foreignId('deleted_by')->nullable()->constrained('users');
```

- Jangan mengubah migration yang sudah dijalankan di production; buat migration baru.
- **Jangan** memakai unique index di database untuk kolom pada tabel ber-soft delete (data terhapus akan menghalangi input ulang). Keunikan dijaga di Form Request.

### 5.3 Soft delete (aturan utama)

1. **Semua penghapusan adalah soft delete.** `forceDelete()` dilarang di kode aplikasi.
2. **`deleted_by` wajib terisi** dengan user yang menghapus. Gunakan mekanisme yang sudah ada di project (trait/observer). Jika belum ada, gunakan trait berikut dan pasang di semua model:

```php
namespace App\Models\Concerns;

trait HasDeletedBy
{
    protected static function bootHasDeletedBy(): void
    {
        static::deleting(function ($model) {
            if (! $model->isForceDeleting()) {
                $model->deleted_by = auth()->id();
                $model->saveQuietly();
            }
        });
    }
}
```

3. **Hapus berantai (cascade soft delete).** Jika induk dihapus, **semua data anaknya ikut di-soft delete**, termasuk cucu dan seterusnya. Tulis di model induk:

```php
protected static function booted(): void
{
    static::deleting(function (Petani $petani) {
        if ($petani->isForceDeleting()) {
            return;
        }
        // ->each->delete() memicu event per anak, sehingga deleted_by
        // terisi dan cascade berlanjut ke cucu
        $petani->lahan()->each->delete();
        $petani->praktikBudidaya()->each->delete();
        // ... semua relasi hasMany/hasOne milik petani
    });
}
```

   - **Jangan** memakai `$petani->lahan()->delete()` (query massal), karena tidak memicu event, sehingga `deleted_by` kosong dan cascade terputus.
   - Setiap kali menambah relasi anak baru, **tambahkan juga** ke blok `deleting` induknya.
   - Pemanggilan `delete()` di controller selalu dibungkus `DB::transaction()`.
   - Relasi `belongsTo` ke data master (Provinsi, Komoditas, dll.) **bukan** anak dan tidak ikut terhapus.
4. **Restore** belum disediakan di aplikasi; dilakukan langsung di database oleh admin. Jangan membuat halaman sampah/restore tanpa diminta.

### 5.4 Global scope

- `KomoditasProgramScope` otomatis membatasi data ke komoditas milik program aktif (`SystemProgram`). Jika data "tidak muncul", periksa scope ini dulu.
- Melewati scope hanya dengan `withoutGlobalScope(KomoditasProgramScope::class)` secara eksplisit, dengan komentar alasannya.
- Jangan menambah global scope baru tanpa izin.

---

## 6. Routing

### 6.1 Route CRUD wajib memakai `Route::resource`

Semua modul CRUD (Pola A, B, C) **wajib** didaftarkan dengan `Route::resource`. **Dilarang** menulis route CRUD satu per satu secara manual.

```php
// ❌ SALAH — route CRUD manual
Route::get('provinsi', [ProvinsiController::class, 'index'])->name('provinsi.index');
Route::post('provinsi/store', [ProvinsiController::class, 'store'])->name('provinsi.store');
Route::get('provinsi/view/{id}', [ProvinsiController::class, 'view'])->name('provinsi.view');
Route::post('provinsi/update/{id}', [ProvinsiController::class, 'update'])->name('provinsi.update');
Route::get('provinsi/delete/{id}', [ProvinsiController::class, 'destroy'])->name('provinsi.destroy');

// ✅ BENAR
Route::resource('provinsi', ProvinsiController::class)->except(['create', 'edit']);
```

Aturan turunannya:

| Kebutuhan | Cara |
|---|---|
| Tidak semua aksi dipakai | `->only([...])` atau `->except([...])` |
| Pola A (offcanvas) | `->except(['create', 'edit'])` |
| Pola B (resource halaman) | `Route::resource(...)` penuh |
| Pola C (multi-tab) | Induk `Route::resource`, tab `Route::resource('induk.tab', ...)->shallow()` |
| Beberapa modul sekaligus | `Route::resources([...])` boleh dipakai dalam satu grup domain |
| Nama parameter tidak sesuai model | `->parameters(['jenis-komoditas' => 'jenisKomoditas'])` |
| Method tambahan (`list`, `by{Induk}`, `verify`, `export`) | `Route::get/post/patch` biasa, **ditulis sebelum** `Route::resource` modul yang sama |

- Form hapus/ubah memakai method spoofing Blade (`@method('DELETE')`, `@method('PUT')`), dan AJAX mengirim method HTTP yang sesuai. Jangan memakai `GET` untuk menghapus.
- **Pengecualian:** Dashboard dan Laporan tidak memakai `Route::resource` (lihat Bagian 11). Halaman tunggal seperti Profil akun boleh memakai `Route::singleton('profil', ...)` atau route manual `edit`/`update`.

### 6.2 Aturan routing lainnya

- Semua route web di `routes/web.php`, API di `routes/api.php`.
- Kelompokkan per domain dengan `Route::middleware(...)->group()` dan komentar judul domain.
- Nested resource memakai `->shallow()`. Maksimal **dua tingkat** di URL (`/framework/{framework}/transformasi`). Hierarki lebih dalam (Framework → Transformasi → Aktivitas → Target) dipecah menjadi beberapa nested shallow resource berpasangan.
- **Satu route hanya didaftarkan satu kali.** Sebelum menambah route, cari dulu apakah sudah ada (`php artisan route:list --name=...`).
- Setelah login: `fasilitator` → Dashboard Survei Petani; role lain → Dashboard Karakteristik Petani. Jangan mengubah logika ini tanpa izin.

---

## 7. Blade & Vuexy

### 7.1 Layout

- Semua halaman admin: `@extends('layout.main')` dan mengisi `@section('content')`.
- Halaman auth memakai `auth/layout.blade.php`.
- Jangan membuat layout baru; jangan menyalin `<head>`/sidebar ke halaman.

### 7.2 File view per pola

| File | Pola | Isi |
|---|---|---|
| `index.blade.php` | A, B, C | Tabel, pencarian, pagination (+ offcanvas form untuk Pola A) |
| `create.blade.php` | B, C | Form tambah, `@include('..._form')` |
| `edit.blade.php` | B, C | Form ubah, `@include('..._form')` |
| `show.blade.php` | B, C | Detail |
| `_form.blade.php` | A, B, C | Field form bersama untuk tambah dan ubah |
| `header.blade.php` | C | Kartu profil + navigasi tab |

- File `add.blade.php` dan `view.blade.php` **tidak boleh** dibuat lagi (ganti dengan `create` dan `show`).
- `_form.blade.php` menerima model (kosong saat tambah) dan memakai `old('field', $model->field)`.

### 7.3 Tampilan error validasi

```blade
<input type="text" name="nama"
       class="form-control @error('nama') is-invalid @enderror"
       value="{{ old('nama', $lahan->nama) }}">
@error('nama')
    <div class="invalid-feedback">{{ $message }}</div>
@enderror
```

Untuk Pola A, JS menampilkan error dari respons 422 dengan class yang sama (`is-invalid` + `invalid-feedback`).

### 7.4 Komponen

- Elemen yang muncul di lebih dari dua halaman dijadikan Blade component di `resources/views/components/` (contoh yang ada: `summary-card`, `wilayah-card`, `wilayah-dashboard`).
- Utamakan komponen yang sudah ada sebelum membuat yang baru.

### 7.5 JavaScript & plugin

- JS halaman ditulis di **file terpisah per modul** (ikuti lokasi JS yang sudah dipakai project), dimuat lewat section/stack script di layout. Hindari blok `<script>` panjang di Blade.
- Semua request AJAX mengirim header `X-CSRF-TOKEN` dan `Accept: application/json`.
- URL di JS diambil dari `route()` yang dicetak Blade (mis. atribut `data-url`), **bukan** di-hardcode.
- Pakai plugin yang sudah tersedia di template Vuexy. Jangan menambah library baru tanpa izin. Pembagian peran:

| Kebutuhan | Plugin |
|---|---|
| Konfirmasi hapus | SweetAlert2 (jika terpasang) |
| Notifikasi sukses/gagal | Sesuai yang dipakai modul lain |
| Select dengan pencarian / dropdown berantai | Select2 (jika terpasang) |
| Input tanggal | Flatpickr (jika terpasang) |
| Grafik | ApexCharts |
| Peta | Leaflet |
| Ikon | Tabler Icons (`ti ti-*`) |

---

## 8. Respons & pesan

### 8.1 Web (Pola B/C)

```php
return redirect()->route('lahan.index')->with('success', 'Lahan berhasil dihapus.');
return back()->withInput()->with('error', 'Data gagal disimpan.');
```

Kunci flash: `success`, `error`, `warning`, `info`.

### 8.2 JSON (Pola A dan AJAX web)

```json
{ "success": true, "message": "Provinsi berhasil ditambahkan.", "data": { } }
```

- Error validasi: format 422 bawaan Laravel (`message` + `errors`).
- Error lain: `{ "success": false, "message": "..." }` dengan kode HTTP yang sesuai.

### 8.3 Pola kalimat pesan

`{Nama data} berhasil ditambahkan.` / `diperbarui.` / `dihapus.`

---

## 9. Otorisasi

- Hak akses berdasarkan role pada `Role` yang sudah ada. Ikuti mekanisme pembatasan role yang sudah dipakai (middleware/policy/gate yang ada); jangan membuat sistem permission baru.
- Menu sidebar hanya menampilkan item yang boleh diakses role pengguna, dan route-nya juga dilindungi di sisi server. Menyembunyikan menu saja tidak cukup.

---

## 10. API (`app/Http/Controllers/Api/`)

- API dipakai aplikasi mobile/lapangan. **Kontrak API (URL, nama field, format respons) tidak boleh diubah** tanpa izin eksplisit, termasuk saat refaktor.
- Endpoint baru mengikuti pola dan format respons API yang sudah ada di folder `Api/`.
- Auth memakai Sanctum; login dibatasi rate limit (5/menit). Jangan longgarkan.
- Setiap endpoint baru harus terbaca rapi di dokumentasi Scramble (type-hint Form Request dan tipe return yang jelas).

---

## 11. Pengecualian

### 11.0 Prinsip umum Dashboard & Laporan

Dashboard dan laporan **bersifat baca (read-only)** dan bentuknya beragam, sehingga controller-nya **fleksibel**:

- **Nama method bebas**, asalkan deskriptif dan camelCase (`index`, `chartProduktivitas`, `petaSebaran`, `rekapPerDesa`, `exportExcel`).
- Boleh satu controller dengan banyak method, atau controller satu aksi (`__invoke`) jika halamannya sederhana.
- Route ditulis manual (`Route::get(...)`), **tidak** memakai `Route::resource`.
- Tidak ada `create/store/edit/update/destroy`. Jika sebuah dashboard butuh input data, input itu dibuat sebagai modul CRUD terpisah.

Yang **tetap berlaku** walau fleksibel:

- Lokasi folder per domain (Bagian 2), penamaan route kebab-case dengan prefix (`dashboard.*`, `laporan.*`).
- Validasi filter memakai Form Request jika filternya lebih dari 2–3 parameter.
- Query sederhana boleh di controller. Query agregat yang panjang, berat, atau dipakai di lebih dari satu tempat dipindah ke `app/Services/{Dashboard|Laporan}/`.
- Data yang ditampilkan tetap menghormati soft delete (data terhapus tidak ikut dihitung) dan global scope program.
- Pembatasan akses per role (Bagian 9).

### 11.1 Dashboard

- Controller: `app/Http/Controllers/Web/Dashboard/{Nama}Controller.php`.
- Pola yang disarankan: `index` mengembalikan halaman; data grafik/peta yang dimuat via AJAX memakai method bernama jelas yang mengembalikan JSON.
- Filter umum diterima lewat query string: program, wilayah (provinsi → desa), periode.
- Query berat di-cache (`Cache::remember`) dengan kunci yang memuat nilai filter.
- View: satu file per dashboard di `resources/views/dashboard/`. Grafik ApexCharts, peta Leaflet.
- Data eksternal (AlphaVantage di `InternationalMarketController`) wajib di-cache dan punya penanganan gagal (tampilkan pesan, jangan error 500).

```php
// routes/web.php
Route::prefix('dashboard')->name('dashboard.')->group(function () {
    Route::get('produktivitas', [ProduktivitasController::class, 'index'])->name('produktivitas');
    Route::get('produktivitas/chart-panen', [ProduktivitasController::class, 'chartPanen'])
        ->name('produktivitas.chart-panen');
});
```

### 11.2 Laporan / reporting

- Controller: `app/Http/Controllers/Web/Laporan/{Nama}Controller.php`; view di `resources/views/laporan/{nama}/`.
- Pola yang disarankan per laporan: halaman filter + pratinjau (`index`), lalu method export per format (`exportExcel`, `exportPdf`). Semua menerima **filter yang sama** dengan pratinjau.
- Export kecil yang menempel pada satu modul CRUD atau dashboard boleh berupa method `export` di controller modul tersebut.
- Laporan yang lambat (data besar) boleh diproses di queue, lalu file diunduh setelah siap.
- Gunakan package export yang sudah terpasang di project. Jika belum ada, tanyakan dulu.

```php
Route::prefix('laporan')->name('laporan.')->group(function () {
    Route::get('rekap-panen', [RekapPanenController::class, 'index'])->name('rekap-panen');
    Route::get('rekap-panen/excel', [RekapPanenController::class, 'exportExcel'])->name('rekap-panen.excel');
    Route::get('rekap-panen/pdf', [RekapPanenController::class, 'exportPdf'])->name('rekap-panen.pdf');
});
```

### 11.3 Ekosistem (form builder dinamis)

- Modul `Ekosistem/` (Group, Tabel, Kolom, Formulir, Ringkasan, Value) memiliki struktur dinamis dan **dikecualikan** dari pola CRUD standar.
- Jangan direfaktor ke pola standar kecuali diminta secara eksplisit. Perubahan kecil tetap mengikuti aturan validasi, soft delete, dan kebersihan.

---

## 12. Kebersihan repo

- **Dilarang** menyimpan file salinan/cadangan: `* copy.php`, `*Backup*`, `*01.php`, `*_old*`, dll. Riwayat disimpan di Git.
- Tidak ada kode yang dikomentari dalam jumlah besar ("kode mati"); hapus saja.
- Tidak ada route ganda (lihat Bagian 6).
- Satu commit = satu perubahan logis (satu modul/fitur). Pesan commit Bahasa Indonesia, singkat, diawali jenis: `feat:`, `fix:`, `refactor:`, `chore:`.

Masalah kebersihan yang **sudah diketahui** (selesaikan saat menyentuh area terkait):

- File duplikat/backup: `* copy.php`, `IndikatorPertanianBackupController`, `PanenController01`, `SummaryDashboardController copy.php`, file `composerlock` yang tidak semestinya.
- Route ganda: `users` (resource + manual), `users.verify` (dua kali), `jenis-komoditas.by-komoditas`, `varietas.by-jenis-komoditas`.

---

## 13. Prosedur refaktor modul lama

Modul lama **wajib** disesuaikan dengan standar ini secara bertahap.

### 13.1 Aturan

1. **Satu modul per sesi/commit.** Jangan merefaktor beberapa modul sekaligus.
2. Jangan merefaktor modul yang sedang dikerjakan (ada perubahan belum di-commit) tanpa konfirmasi.
3. API **tidak** ikut diubah (Bagian 10).
4. Perilaku untuk pengguna harus tetap sama; refaktor bukan tempat menambah fitur.

### 13.2 Langkah

1. Simpan daftar route modul: `php artisan route:list --name={modul} > /tmp/before.txt`.
2. Tentukan pola target (A/B/C) sesuai 3.3.
3. Cari **semua** pemakaian nama route, URL, dan view lama di seluruh repo (Blade, JS, controller lain, sidebar), mis. `grep -rn "provinsi.view\|provinsi/add\|master.provinsi.add" app resources routes`.
4. Ubah:
   - method `add` → `create`, `view` → `show`;
   - file `add.blade.php` → `create.blade.php`, `view.blade.php` → `show.blade.php`;
   - route manual → `Route::resource` (+ `only/except`, route tambahan di atasnya);
   - validasi inline → Form Request (dengan `withoutTrashed()` pada unique);
   - pastikan model memakai `SoftDeletes`, `deleted_by` terisi, dan cascade ke anak sudah ditulis;
   - semua referensi yang ditemukan di langkah 3.
5. Bandingkan `route:list` sesudah dengan `/tmp/before.txt`; pastikan tidak ada route yang hilang tanpa sengaja.
6. Uji manual alur lengkap: index → tambah → detail → ubah → hapus (cek `deleted_at`, `deleted_by`, dan data anak).
7. Perbarui tabel status di 13.3.

### 13.3 Status migrasi modul

Status: `Belum` / `Proses` / `Selesai` / `Dikecualikan`

| Domain | Modul | Pola target | Status | Catatan |
|---|---|---|---|---|
| Master | Provinsi | A | Belum | Ada `list` + dropdown berantai |
| Master | Kabupaten/Kota | A | Belum | `by-provinsi` |
| Master | Kecamatan | A | Belum | `by-kabupaten` |
| Master | Desa/Kelurahan | A | Belum | `by-kecamatan` |
| Master | Komoditas | A | Belum | |
| Master | Jenis Komoditas | A | Belum | Route `by-komoditas` dobel |
| Master | Varietas | A | Belum | Route `by-jenis-komoditas` dobel |
| Master | Adat | A | Belum | |
| Master | Keluarga | ? | Belum | Tentukan pola saat refaktor |
| Produktivitas | Petani (+ semua tab) | C | Belum | |
| Produktivitas | Lahan | B | Belum | |
| Produktivitas | Tanaman | B | Belum | |
| Produktivitas | MapTanaman | ? | Belum | |
| Produktivitas | Produksi | B | Belum | |
| Produktivitas | Survey Kelompok Tani (+ tab) | C | Belum | |
| Produktivitas | Sebaran Petani | ? | Belum | Sedang dikerjakan, konfirmasi dulu |
| Program | Program, Program Komoditas, Program Lokasi | B | Belum | Pindah dari root ke `Program/` |
| Program | Framework → Transformasi → Aktivitas → Target | B | Belum | Nested shallow |
| Program | Realisasi | B | Belum | |
| Program | Verifikasi | ? | Belum | Sedang dikerjakan, konfirmasi dulu |
| Program | Workshop (+ Sesi, Peserta) | B | Belum | Sesi/Peserta sedang dikerjakan |
| Program | Kelompok Belajar Tani | B | Belum | |
| Bumdes | Profil, Kelembagaan, Survei | B | Belum | |
| Koperasi | Profil, Kelembagaan, Survei | B | Belum | |
| Konfigurasi | User | B | Belum | Route `users` & `users.verify` dobel |
| Konfigurasi | Profil akun | — | Belum | Hanya `edit`/`update` |
| Ekosistem | Semua | — | Dikecualikan | Lihat 11.3 |
| Dashboard | Semua | — | Dikecualikan | Ikuti 11.1 |

---

## 14. Checklist modul baru

- [ ] Pola ditentukan (A/B/C) sesuai 3.3
- [ ] Migration: `id`, kolom audit, `timestamps`, `softDeletes`, `deleted_by`; tanpa unique index
- [ ] Model: `$table` eksplisit, `$fillable`, `SoftDeletes`, `deleted_by` terisi, casts/Enum
- [ ] Relasi anak ditambahkan ke cascade `deleting` di model induk
- [ ] Form Request `Store`/`Update` dengan pesan Bahasa Indonesia dan unique `withoutTrashed()`
- [ ] Controller di `Web/{Domain}/` dengan nama method resmi saja
- [ ] Route: `Route::resource` (+ `only/except`, `shallow`), tidak dobel, route tambahan di atas resource
- [ ] View di `{domain}/{modul}/`: `index`, `create`, `edit`, `show`, `_form` sesuai pola
- [ ] JS di file terpisah, URL dari `route()`, CSRF terpasang
- [ ] Menu sidebar ditambahkan dan dibatasi per role; route dilindungi di server
- [ ] Respons/flash mengikuti Bagian 8
- [ ] Diuji manual: tambah, ubah, detail, hapus (cek `deleted_at`, `deleted_by`, data anak)
- [ ] Tidak ada file salinan/backup tertinggal