Update Praktik Budidaya
This commit is contained in:
+712
@@ -0,0 +1,712 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user