persegi/DOKUMENTASI.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

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