persegi/README.md

# Persegi — Sistem Manajemen Organisasi Pemuda Desa

Sistem web production-ready untuk **Organisasi Pemuda Desa Persegi**, berlokasi di Desa Karangdadap, Kecamatan Kalibagor, Kabupaten Banyumas.

---

## Teknologi

| Layer | Stack |
|---|---|
| Backend | Laravel 13 |
| Admin Panel | Filament 5.x |
| Authorization | Filament Shield + Spatie Permission |
| Database | MySQL |
| Frontend Publik | Blade |
| Realtime | Livewire |

---

## Struktur Direktori

```
app/
├── Filament/
│   ├── Resources/          # Admin panel resources
│   │   ├── Activities/     # Manajemen kegiatan
│   │   ├── Approvals/      # Multi-approval
│   │   ├── Audits/         # Audit internal
│   │   ├── CashCategories/ # Kategori kas
│   │   ├── CashRecords/    # Transaksi kas
│   │   ├── ContactMessages/# Pesan dari publik
│   │   ├── Divisions/      # Divisi organisasi
│   │   ├── Posts/          # Konten publik
│   │   ├── Users/          # Manajemen anggota
│   │   └── Votes/          # Sistem voting
│   └── Widgets/
│       ├── StatsOverview.php       # Widget dashboard utama
│       ├── CashStatsWidget.php     # Widget statistik kas (halaman transaksi)
│       └── ActivityLogWidget.php   # Widget log aktivitas
├── Models/
│   ├── User.php            # Anggota / pengguna sistem
│   ├── Division.php        # Divisi organisasi
│   ├── Activity.php        # Kegiatan
│   ├── CashRecord.php      # Transaksi kas
│   ├── CashCategory.php    # Kategori kas (pemasukan/pengeluaran)
│   ├── Vote.php            # Voting
│   ├── VoteItem.php        # Pilihan suara per user
│   ├── Approval.php        # Multi-approval
│   ├── ApprovalItem.php    # Keputusan per approver
│   ├── Audit.php           # Temuan audit
│   ├── AuditResponse.php   # Respons atas temuan audit
│   ├── MemberStatusLog.php # Riwayat perubahan status anggota
│   ├── ActivityLog.php     # Log global semua aksi
│   ├── Post.php            # Artikel/berita publik
│   └── ContactMessage.php  # Pesan kontak dari publik
└── Observers/
    ├── CashRecordObserver.php
    ├── ActivityObserver.php
    └── UserObserver.php
```

---

## Role & Hak Akses

| Role | Deskripsi |
|---|---|
| `super_admin` | Full akses, bisa override semua, semua aksi di-log |
| `ketua` | Approval kegiatan, verifikasi kas, lihat semua data |
| `bendahara` | Input & kelola transaksi kas |
| `pengurus` | Submit kegiatan ke pending |
| `anggota` | Akses terbatas, lihat data sendiri |
| `auditor` | Read-only + bisa buat temuan audit |

---

## Fitur & Use Case

### 1. Manajemen Anggota

**Aktor:** ketua, pengurus, super_admin

| Use Case | Deskripsi |
|---|---|
| Tambah anggota | Input data: nama, telepon, alamat, divisi, status |
| Ubah status anggota | Aktif → Nonaktif wajib isi `inactive_reason` |
| Lihat riwayat status | Semua perubahan status tercatat di `member_status_logs` |
| Filter per divisi | Anggota bisa difilter berdasarkan divisi |

**Business rule:**
- Hanya ketua, pengurus, super_admin yang bisa ubah status
- Setiap perubahan status otomatis dicatat ke `member_status_logs` via Observer

---

### 2. Struktur Organisasi (Divisi)

**Aktor:** ketua, super_admin

| Use Case | Deskripsi |
|---|---|
| Kelola divisi | CRUD divisi organisasi |
| Lihat anggota per divisi | Relasi one-to-many ke User |

---

### 3. Kegiatan

**Aktor:** pengurus (buat), ketua (approve), semua (lihat)

| Use Case | Deskripsi |
|---|---|
| Buat kegiatan | Status awal: `draft` |
| Submit ke review | `draft` → `pending` (oleh pengurus) |
| Approve/Tolak | `pending` → `approved` / `rejected` (oleh ketua) |
| Tandai selesai | Wajib isi `executed_at` + `execution_notes` |
| Kelola peserta | Many-to-many anggota ↔ kegiatan |

**Workflow status:**
```
draft → pending → approved → (executed_at diisi)
                → rejected
```

---

### 4. Keuangan (Kas)

**Aktor:** bendahara (input), ketua & super_admin (verifikasi & lihat)

| Use Case | Deskripsi |
|---|---|
| Input transaksi | Bendahara input pemasukan/pengeluaran |
| Verifikasi transaksi | Ketua/super_admin verifikasi, setelah itu data terkunci |
| Lihat statistik kas | Widget di halaman transaksi: total saldo, pemasukan/pengeluaran bulan ini, saldo bulan lalu |
| Filter transaksi | Filter per kategori, tanggal, status verifikasi |

**Business rule:**
- Setelah `verified_at` terisi, data tidak bisa diubah/dihapus
- Threshold keuangan:
  - < Rp 500.000 → bendahara saja
  - Rp 500.000 – Rp 2.000.000 → butuh persetujuan ketua
  - > Rp 2.000.000 → multi-approval atau voting

---

### 5. Voting

**Aktor:** semua role (sesuai permission)

| Use Case | Deskripsi |
|---|---|
| Buat voting | Tipe: `activity`, `finance`, `general` |
| Beri suara | Pilihan: `approve`, `reject`, `abstain` |
| Tutup voting | Status: `open` → `closed` |
| Lihat hasil | Mayoritas >50% untuk lolos |

---

### 6. Multi-Approval

**Aktor:** role yang ditentukan per approval

| Use Case | Deskripsi |
|---|---|
| Buat approval | Tentukan jumlah approval yang dibutuhkan |
| Beri keputusan | Tiap approver bisa approve/reject + catatan |
| Cek status | Lolos jika jumlah approve terpenuhi |

---

### 7. Audit Internal

**Aktor:** auditor (buat temuan), pengurus/ketua (respons)

| Use Case | Deskripsi |
|---|---|
| Buat temuan | Tipe: `warning` / `critical`, bisa terkait model apapun |
| Respons temuan | Pihak terkait bisa balas temuan audit |
| Pantau status | Auditor bisa track status penyelesaian |

---

### 8. Konten Publik

**Aktor:** pengurus, ketua, super_admin

| Use Case | Deskripsi |
|---|---|
| Buat artikel/berita | Post dengan status `draft` / `published` |
| Website publik | Halaman publik berbasis Blade untuk masyarakat |
| Pesan kontak | Masyarakat bisa kirim pesan, admin bisa lihat & balas |

---

### 9. Dashboard

Widget yang tampil di halaman utama admin:

| Widget | Isi |
|---|---|
| StatsOverview | Anggota aktif, total kas, kegiatan berjalan, kegiatan pending |
| ActivityLogWidget | Log aktivitas terbaru di sistem |

Widget khusus halaman transaksi:

| Widget | Isi |
|---|---|
| CashStatsWidget | Total saldo, pemasukan bulan ini, pengeluaran bulan ini, saldo bulan lalu |

---

## Log & Audit Trail

Semua aksi penting otomatis dicatat via Observer:

| Event | Dicatat di |
|---|---|
| Perubahan status anggota | `member_status_logs` |
| Transaksi kas baru | `activity_logs` |
| Verifikasi kas | `activity_logs` |
| Approval kegiatan | `activity_logs` |
| Eksekusi kegiatan | `activity_logs` |

---

## Keamanan

- Setiap resource dilindungi Laravel Policy
- Permission granular dikelola via Filament Shield
- Fitur impersonate: super_admin bisa login sebagai user lain (untuk debugging/support)
- Input divalidasi di semua form

---

## Instalasi

```bash
composer install
cp .env.example .env
php artisan key:generate
php artisan migrate --seed
php artisan shield:generate --all
php artisan shield:super-admin --user=1
```

Akses admin panel: `/dashboard`