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.

**URL Production:** https://persegi.nyawiji.net

---

## 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 (database driver) |

---

## 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
│   │   ├── MemberDues/      # Iuran anggota
│   │   ├── MemberPoints/    # Poin anggota
│   │   ├── 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, MemberStatusLog.php, ActivityLog.php
│   ├── MemberDue.php, MemberPoint.php
│   ├── CashRecord.php, CashCategory.php
│   ├── Vote.php, VoteItem.php
│   ├── Approval.php, ApprovalItem.php
│   ├── Audit.php, AuditResponse.php
│   └── Post.php, ContactMessage.php
└── Observers/
    ├── UserObserver.php        # Log perubahan status anggota
    ├── ActivityObserver.php    # Log approval & eksekusi kegiatan
    ├── CashRecordObserver.php  # Log + threshold approval/voting otomatis
    ├── VoteObserver.php        # Notifikasi voting baru ke semua user
    └── PostObserver.php        # Poin +5 saat artikel dipublish
```

---

## Role & Hak Akses

| Role | Deskripsi |
|---|---|
| `super_admin` | Full akses via gate, semua aksi di-log |
| `ketua` | Approval kegiatan, verifikasi kas, lihat semua data |
| `bendahara` | Input & kelola transaksi kas dan iuran |
| `pengurus` | Submit kegiatan ke pending |
| `anggota` | Akses terbatas, bisa voting dan buat artikel |
| `auditor` | Read-only semua + 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)

### Iuran Anggota

- Satu iuran per anggota per periode (format `YYYY-MM`)
- Unique constraint `(user_id, period)` mencegah duplikasi

### Kegiatan

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

- Draft hanya terlihat oleh kreator dan `super_admin`

### Voting

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

### Sistem Poin

| Event | Poin |
|---|---|
| Hadir kegiatan | +10 |
| Artikel dipublish | +5 |

- Duplikasi dicegah via `firstOrCreate` dengan key `(user_id, source_type, source_id)`

### Notifikasi

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

### Konten Publik

- Website publik berbasis Blade
- 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 --all -n
php artisan db:seed --class=PermissionSeeder --force
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 migrate
php artisan shield:generate --panel=admin --all -n
php artisan db:seed --class=PermissionSeeder --force
php artisan permission:cache-reset
php artisan filament:optimize-clear
php artisan filament:optimize
php artisan config:cache
php artisan route:cache
```