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 / MariaDB |
| Frontend Publik | Blade + Tailwind CSS |
| Realtime | Livewire |
| Queue | Supervisor |

---

## Struktur Direktori

```
app/
├── Filament/
│   ├── 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
│       └── ActivityLogWidget.php   # Widget log aktivitas
├── Models/
│   ├── User.php, Division.php, Activity.php
│   ├── CashRecord.php, CashCategory.php
│   ├── Vote.php, VoteItem.php
│   ├── Approval.php, ApprovalItem.php
│   ├── Audit.php, AuditResponse.php
│   ├── MemberStatusLog.php, ActivityLog.php
│   ├── Post.php, ContactMessage.php
└── Observers/
    ├── CashRecordObserver.php  # Log + threshold approval/voting
    ├── ActivityObserver.php    # Log approval & eksekusi kegiatan
    ├── UserObserver.php        # Log perubahan status anggota
    └── VoteObserver.php        # Notifikasi voting baru ke semua user
```

---

## Role & Hak Akses

| Role | Deskripsi |
|---|---|
| `super_admin` | Full akses, 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, bisa voting |
| `auditor` | Read-only + bisa buat temuan audit |

---

## Fitur

### Keuangan (Kas)

Threshold otomatis saat transaksi dibuat:

| Jumlah | Alur |
|---|---|
| < Rp 500.000 | Langsung bisa diverifikasi |
| Rp 500.000 – Rp 2.000.000 | Notifikasi ke ketua → perlu approval ketua |
| > Rp 2.000.000 | Voting dibuat otomatis → perlu mayoritas >50% |

- Transaksi yang belum diverifikasi tidak masuk ke total kas
- Setelah `verified_at` terisi, data terkunci (tidak bisa diubah/dihapus)
- Widget statistik kas tampil di halaman transaksi: total saldo, pemasukan/pengeluaran bulan ini, saldo bulan lalu

### Kegiatan

```
draft → pending → approved → (executed_at diisi)
                → rejected
```

### Voting

- Semua user bisa melihat dan memberi suara
- Tipe: `activity`, `finance`, `general`
- Notifikasi ke semua user saat voting baru dibuat
- Mayoritas >50% untuk lolos

### Notifikasi

- Database notifications via Filament
- Polling otomatis setiap 30 detik
- Queue diproses via Supervisor

### Konten Publik

- Website publik berbasis Blade (font: Roboto + Playfair Display)
- Artikel/berita, halaman kegiatan, form kontak
- Link ke website publik tersedia di sidebar admin

---

## Log & Audit Trail

| Event | Dicatat di |
|---|---|
| Perubahan status anggota | `member_status_logs` |
| Transaksi kas baru/verifikasi | `activity_logs` |
| Approval/eksekusi kegiatan | `activity_logs` |

---

## Instalasi

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

Akses admin panel: `/dashboard`

### Queue Worker (Supervisor)

```ini
[program:persegi-worker]
command=php /path/to/project/artisan queue:work --sleep=3 --tries=3
autostart=true
autorestart=true
user=$USER
redirect_stderr=true
stdout_logfile=/var/log/persegi-worker.log
```

```bash
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start persegi-worker
```

### Production

```bash
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan permission:cache-reset
```

---

## Kontribusi

Lihat [CONTRIBUTING.md](CONTRIBUTING.md) untuk panduan berkontribusi.