Platform Layanan Publik Warga PRISMA RT 04 (Laravel 13)

Urus surat, cek kas, lapor masalah — semua dari HP.

PRISMA RT 04 Kemayoran: Platform Realisasi Informasi, Sistem Manajemen & Administrasi Warga Berbasis Web & Progressive Web App (PWA).
Visual Reference: https://prisma-rose.vercel.app/
Framework: PHP 8.4+ & Laravel 13.x | Database: MySQL 8.x | UI: CSS & JavaScript native (PWA) | Runtime: FrankenPHP / Docker (Railway)

---

Mulai Cepat (3 Langkah)

Butuh PHP 8.4+, Composer, dan MySQL (Laragon/XAMPP). Node.js tidak diperlukan.

# 1. Pasang dependensi & siapkan konfigurasi
composer install
copy .env.example .env          # Linux/Mac: cp .env.example .env
php artisan key:generate

# 2. Buat database di phpMyAdmin / HeidiSQL: layanan_publik_warga (utf8mb4_unicode_ci), lalu isi tabel + data demo
php artisan migrate --seed

# 3. Jalankan
php artisan serve               # buka http://localhost:8000

Akun Default (khusus lokal / testing)

Dibuat otomatis oleh php artisan migrate --seed (tidak dibuat di APP_ENV=production). Masuk di /login dengan username dan password berikut:

Peran	Tingkat	Username	Password
Superadmin	superadmin	superadmin	password
Admin	admin	admin	password
Ketua RT (Raden Erry Adu Sundaru)	admin	ketua_rt	password
Sekretaris (Melly)	admin	sekretaris	password
Bendahara (Retno Fellyanti)	admin	bendahara	password
Petugas Keamanan	admin	keamanan	password
Warga (Budi Santoso)	user	warga	password

⚠️ Ganti atau hapus akun-akun ini sebelum dipakai sungguhan. Untuk production buat Superadmin dengan php artisan app:create-superadmin (lihat bagian Deploy). Pengaturan MySQL ada di .env (DB_DATABASE, DB_USERNAME, DB_PASSWORD); zona waktu default Asia/Jakarta.

Peta Singkat: apa ada di mana?

Ingin mengubah...	Buka
Tampilan / warna / navbar	public/css/prisma.css, resources/views/layouts/*.blade.php
Kolom tabel & form tiap halaman CRUD	public/js/pages.js
Aturan validasi, hak akses, notifikasi tiap modul	app/Support/ManagedRegistry.php
Menu & halaman per peran	app/Support/Navigation.php, app/Models/User.php (hasPermission)
Registrasi, login, lupa password	app/Http/Controllers/Api/V1/AuthController.php, public/js/auth.js
Notifikasi	app/Services/NotifyService.php, public/js/prisma.js
Kop surat, wilayah, kontak sekretariat, nama Ketua/Sekretaris/Bendahara	config/rt.php (atau variabel RT_* di .env)
Diagram 5 unsur	resources/views/app/system.blade.php (menu Pemodelan Sistem)

Pemecahan Masalah

Gejala	Solusi
could not find driver / Connection refused	Nyalakan MySQL di Laragon/XAMPP; pastikan ekstensi pdo_mysql aktif dan .env benar
Unknown database 'layanan_publik_warga'	Buat database dulu (langkah 2), lalu php artisan migrate --seed
Halaman putih / No application encryption key	Jalankan php artisan key:generate
Data lama / error setelah git pull	php artisan migrate lalu php artisan optimize:clear
Ingin mengulang data demo dari nol	php artisan migrate:fresh --seed (menghapus semua data di database itu)
Install PWA tidak muncul	PWA butuh HTTPS atau localhost; di iPhone: Share → Add to Home Screen
Tes gagal	php artisan test memakai SQLite memori, tidak menyentuh database MySQL Anda

---

Alur Aplikasi

1. Alur pengguna secara keseluruhan

flowchart TD
    A([Warga membuka aplikasi / PWA]) --> B[Layar pembuka PRISMA RT 04]
    B --> C[Beranda publik: kas, pengumuman, agenda, kontak]
    C --> D{Sudah punya akun?}
    D -- Belum --> E[Daftar: NIK, No. KK, Nama, Username, Password]
    E --> F{NIK, nama+KK, username belum terdaftar?}
    F -- Tidak --> E
    F -- Ya --> G[Akun dibuat: warga lama langsung aktif, warga baru menunggu verifikasi Sekretaris]
    D -- Sudah --> H[Masuk dengan username + password]
    H --> I{Lupa password?}
    I -- Ya --> J[Isi username + NIK + No. KK] --> K[Tautan reset dikirim ke email, berlaku 20 menit] --> H
    G --> L
    H --> L[Dashboard sesuai peran]
    L --> M{Peran}
    M -- Warga --> N[Ajukan surat, pengaduan, laporan keamanan, lihat iuran]
    M -- Sekretaris --> O[Verifikasi surat dan pendaftar, kelola konten]
    M -- Ketua RT --> P[Sahkan surat, pantau pengaduan dan kas]
    M -- Bendahara --> Q[Catat kas dan iuran]
    M -- Keamanan --> R[Tindak laporan keamanan, jadwal ronda]
    M -- Admin / Superadmin --> S[Kelola pengguna, audit, pemodelan sistem]
    N --> T[(MySQL)]
    O --> T
    P --> T
    Q --> T
    R --> T
    S --> T
    T --> U[Notifikasi real-time ke pihak terkait]
    U --> L

2. Alur surat pengantar (2 tingkat)

flowchart LR
    W[Warga isi permohonan + lampiran] --> A[Draft]
    A -->|Ajukan| B[Diajukan]
    B -->|Notifikasi ke Sekretaris| C{Sekretaris periksa berkas}
    C -->|Lengkap| D[Terverifikasi]
    C -->|Kurang| X[Ditolak + alasan]
    D -->|Notifikasi ke Ketua RT| E{Ketua RT}
    E -->|Setuju| F[Disahkan: nomor surat + QR keaslian]
    E -->|Tidak| X
    F --> G[Surat PDF/Word siap diunduh dengan kop RT 04 / RW 09]
    X -->|Notifikasi alasan ke warga| W

3. Alur data real-time

sequenceDiagram
    participant U as Browser / PWA
    participant A as API /api/v1
    participant D as MySQL
    U->>A: POST/PATCH/DELETE (cookie sesi + CSRF)
    A->>D: Simpan (transaksi, versi data, audit log)
    A->>D: Buat notifikasi untuk pihak terkait
    A-->>U: 200 OK
    loop tiap 8-10 detik (berhenti saat tab tidak aktif)
        U->>A: GET daftar / notifikasi (ETag)
        A-->>U: Data terbaru atau 304
    end

---

Daftar Isi

0. Mulai Cepat · Alur Aplikasi
1. Tentang Proyek
2. Identitas Komunitas & Referensi Desain
3. Arsitektur Sistem & Tech Stack
4. Hak Akses: 3 Tingkat & 7 Peran
5. Pemodelan Rekayasa Perangkat Lunak (5 Unsur Utama)
   • 1. Entity Relationship Diagram (ERD)
   • 2. Logical Record Structure (LRS)
   • 3. Use Case Diagram & Spesifikasi Aktor
   • 4. Activity Diagram (Alur Verifikasi NIK & Persuratan)
   • 5. Unified Modeling Language (UML) Diagrams

---

Tentang Proyek

PRISMA RT 04 (Platform Realisasi Informasi, Sistem Manajemen & Administrasi) adalah platform digital layanan publik warga RT 04 / RW 09 Kemayoran, Jakarta Pusat. Sistem ini mengintegrasikan seluruh administrasi lingkungan warga ke dalam satu ekosistem terpadu:

• Pendaftaran Mandiri & Verifikasi NIK Real-Time: Pencocokan 16 digit NIK secara instan dengan deteksi warga sensus terdaftar (pre-registered), pengajuan warga baru (pending verification), dan pencegahan duplikasi akun.
• Birokrasi Surat Digital 2-Tier: Verifikasi berkas administratif oleh Sekretaris, persetujuan/tanda tangan digital oleh Ketua RT, penomoran surat otomatis anti-bentrok, dan verifikasi keaslian via token QR Code.
• Buku Kas Anti-Fraud (Immutable Financial Ledger): Setiap penerimaan dan pengeluaran dicatat dengan presisi DECIMAL(15,2). Transaksi terbit bersifat append-only dengan mekanisme reversal audit jika terdapat koreksi.
• Pengaduan Warga & Laporan Keamanan: Penyampaian keluhan fasilitas lingkungan dan laporan darurat dengan bukti foto, pelacakan status tiket, dan koordinasi petugas keamanan pos ronda.
• Transparansi Komunitas: Publikasi warta pengumuman, agenda kegiatan kerja bakti, struktur pengurus RT, jadwal ronda kamling, dan kontak darurat 24 jam.
• Progressive Web App (PWA): Akses cepat seperti aplikasi mobile asli dengan Web App Manifest, Service Worker caching cerdas, dan halaman offline fallback.

---

Identitas Komunitas & Referensi Desain

• Entitas Lingkungan: Sekretariat PRISMA RT 04 / RW 09 Kemayoran
• Alamat Sekretariat: Rumah - Gg. Bugis No. 95, RT 04 / RW 09, Kebon Kosong, Kec. Kemayoran, Kota Jakarta Pusat, DKI Jakarta 10620
• Koordinat Wilayah (GEO): Latitude -6.1618, Longitude 106.8456
• Saluran Bantuan WhatsApp: +62 878-7200-4448
• Kontak IT & Pengurus: Swandaru Tirta ([email protected])
• Visual & Functional Reference: https://prisma-rose.vercel.app/

---

Arsitektur Sistem & Tech Stack

Platform dibangun secara murni menggunakan arsitektur monolitik modern MVC + Service Layer + ViewModel dengan backend PHP Laravel 13 dan frontend Blade Components:

Lapisan Sistem	Teknologi	Keterangan & Rincian Implementasi
Backend Framework	Laravel 13.x (PHP 8.4.1+)	Native Laravel 13 dengan Eloquent ORM, Form Requests, Policies, dan Gates
Frontend Templating	Laravel Blade + Components	Komponen UI modular, semantic HTML5, WCAG accessible
CSS / Design System	CSS native (public/css/prisma.css)	Tema gelap/terang, token warna, navbar desktop + bottom-nav mobile; tanpa langkah build
Interaktivitas UI	JavaScript native (public/js/*.js)	fetch + polling real-time, validasi registrasi langsung ke MySQL, modal CRUD, toast notifikasi
Database Transaksional	MySQL 8.x	Sumber kebenaran utama (Single Source of Truth), nilai moneter DECIMAL(15,2), foreign keys
Cache & Queue Engine	Redis 7.x	Penanganan cache aplikasi, session driver, queue worker, dan API rate limiting
Autentikasi & API	Session + Laravel Sanctum	Stateful web session untuk browser dan Bearer Token untuk REST API /api/v1
Dokumentasi API	OpenAPI 3.1 & Swagger UI	Tersedia interaktif di rute /docs/api bersumber dari docs/api_spec/openapi.yaml
Containerization	FrankenPHP & Docker	Image dunglas/frankenphp:1-php8.4-bookworm dengan Caddy web server
Hosting & Deploy	Railway-Compatible	Konfigurasi deklaratif via Dockerfile dan railway.json
Code Style & QA	Laravel Pint & PHPUnit	PSR-12 standard formatting dan 150 Automated Feature Tests (100% Passed)

---

Hak Akses: 3 Tingkat & 7 Peran

Tingkat akses	Peran (role)	Username demo	Wewenang utama
Superadmin	SUPERADMIN	superadmin	Kontrol penuh: semua modul, manajemen semua peran, audit log, halaman Pemodelan Sistem
Admin	ADMIN	admin	Kelola pengguna (selain Superadmin/Admin), data warga, pengumuman, agenda, pengurus, ronda, kontak, audit
Admin	KETUA_RT	ketua_rt	Pengesahan surat (tahap akhir), supervisi pengaduan, keamanan, dan kas
Admin	SEKRETARIS	sekretaris	Verifikasi surat & pendaftar baru, data warga, pengumuman, agenda, struktur pengurus
Admin	BENDAHARA	bendahara	Catat/terbitkan/koreksi transaksi kas
Admin	PETUGAS_KEAMANAN	keamanan	Tindak lanjut laporan keamanan, jadwal ronda, kontak darurat
User	WARGA	warga	Hanya data sendiri: ajukan surat, pengaduan, laporan keamanan

Semua akun demo berpassword password (hanya environment local/testing). Matriks hak akses lengkap yang dihitung langsung dari kode tersedia di menu Pemodelan Sistem → Matriks Hak Akses.

Registrasi warga memakai NIK (16 digit), No. KK (16 digit), Nama, dan Username. Aturan yang ditegakkan di API dan di database MySQL:

• satu NIK hanya satu akun;
• kombinasi nama + No. KK hanya boleh terdaftar sekali (indeks unik citizens_kk_name_unique);
• username unik (tidak peka huruf besar/kecil);
• password sengaja tidak dibuat unik antar-pengguna (itu akan membocorkan password pengguna lain); yang ditegakkan adalah password minimal 8 karakter yang di-hash bcrypt.

Lupa password: /forgot-password memverifikasi username + NIK + No. KK terhadap database, lalu mengirim tautan reset sekali pakai (20 menit) ke email akun. Akun tanpa email, atau bila SMTP belum diatur, memakai cadangan: tautan ditampilkan di layar. Token disimpan ter-hash di password_reset_requests. Login dikunci sementara 5 menit setelah 5 kali gagal per username. Akun pengurus tidak memakai jalur ini; Superadmin mengatur ulang lewat Manajemen Pengguna.

---

Pemodelan Rekayasa Perangkat Lunak (5 Unsur Utama)

Sistem ini dikembangkan dengan metode Waterfall terkendali (lihat SPRINT_PLAN.md) dan didokumentasikan melalui 5 unsur pemodelan. Setiap unsur dihasilkan pada fase Waterfall tertentu dan ditelusuri sampai ke kode Laravel dan pengujiannya.

Fase Waterfall	Sprint	Unsur pemodelan	Berujung di
Analisis kebutuhan	0 dan 1	3. Use Case Diagram	rute dan izin peran
Perancangan	2	4. Activity Diagram, 1. ERD, 2. LRS, 5. UML (Class dan Sequence)	migrasi, model, service
Implementasi	3 dan 4	penerjemahan seluruh unsur ke kode	database/, app/, routes/
Pengujian	5	penelusuran use case, activity, dan sequence ke tes	tests/
Penyebaran dan pemeliharaan	6 dan seterusnya	diagram dibangkitkan ulang setiap perubahan	runbook

Penjelasan lengkap, tabel penelusuran ke kode dan tes, serta aturan pemeliharaan diagram ada di SYSTEM_MODELING_5_ELEMENTS.md. Seluruh diagram bergaris siku-siku diaudit otomatis agar garis tidak menembus kotak dan tidak berimpit.

1. Entity Relationship Diagram (ERD)

Dibangkitkan dari skema hasil migrasi (php artisan migrate), 27 tabel domain dipecah menjadi enam modul agar terbaca. Kolom created_at dan updated_at ada di semua tabel dan tidak digambar. Tabel framework (cache, jobs, sessions) tidak ditampilkan.

Cara membaca: kotak berheader warna adalah tabel modul tersebut; kotak abu-abu hanya penanda tabel dari modul lain (hanya PK). +id tebal adalah primary key, nama miring adalah foreign key, {UK} adalah kolom unik. Garis putus-putus berarti FK boleh kosong (nullable), garis utuh berarti FK wajib terisi. Ujung garis memakai notasi crow's foot: ‖ tepat satu, ○| nol atau satu, ○< nol atau banyak.

1.1. Akun dan Akses

1.2. Kependudukan

1.3. Surat Pengantar

1.4. Keuangan dan Iuran

1.5. Pengaduan dan Keamanan

1.6. Informasi RT dan Audit

notifications dan personal_access_tokens terhubung ke users secara polimorfik (notifiable_id, tokenable_id), bukan lewat foreign key database.

---

2. Logical Record Structure (LRS)

LRS dibahas sebagai dokumen tersendiri: docs/design/LRS.md. Isinya diagram LRS per modul (kotak tabel dengan PK bergaris bawah, FK miring, dan panah FK ke PK), aturan transformasi ERD ke LRS, matriks 28 relasi beserta aturan ON DELETE, daftar LRS dalam bentuk teks untuk 27 tabel, dan catatan normalisasi 3NF.

Modul	Diagram LRS
Akun dan akses	lrs-1-akun-akses.svg
Kependudukan	lrs-2-kependudukan.svg
Surat pengantar	lrs-3-surat.svg
Keuangan dan iuran	lrs-4-keuangan.svg
Pengaduan dan keamanan	lrs-5-pengaduan-keamanan.svg
Informasi RT dan audit	lrs-6-informasi-audit.svg

---

3. Use Case Diagram & Spesifikasi Aktor

Use case dipecah per modul agar terbaca. Notasi mengikuti UML: aktor di luar batas sistem, use case berupa elips berawalan kata kerja, «include» untuk langkah yang selalu dijalankan, «extend» untuk perilaku opsional, dan panah segitiga kosong untuk pewarisan aktor (Superadmin mewarisi seluruh wewenang Admin). Pengunjung adalah pengguna publik tanpa login; hak akses tiap peran diambil dari User::hasPermission().

3.1. Akun dan Registrasi Warga

3.2. Layanan Surat Pengantar

3.3. Keuangan dan Iuran RT

3.4. Pengaduan dan Keamanan Lingkungan

Pengurus RT pada diagram ini mewakili peran yang memiliki izin complaint.manage: Ketua RT, Sekretaris RT, dan Admin.

3.5. Informasi RT dan Administrasi Sistem

Spesifikasi aktor

Aktor	Peran sistem	Wewenang utama
Pengunjung	tanpa login	Melihat kas publik, warta, agenda, struktur pengurus, ronda, dan kontak darurat; mendaftar akun; melacak surat dengan nomor tiket; memeriksa keaslian surat lewat QR
Warga	WARGA	Mengajukan dan memantau surat, melihat iuran, mengirim pengaduan dan laporan keamanan, mengelola profil
Sekretaris RT	SEKRETARIS	Memverifikasi surat dan pendaftar baru, menerbitkan dokumen, mengelola data warga, templat surat, pengumuman, agenda, dan struktur pengurus
Ketua RT	KETUA_RT	Mengesahkan atau menolak surat, menanggapi pengaduan, menerbitkan laporan triwulan, meninjau kas dan audit unduhan (kas hanya dibaca)
Bendahara RT	BENDAHARA	Membuat tagihan iuran, mencatat pembayaran, transaksi, dan pembelian, menerbitkan atau mengoreksi transaksi, menyusun laporan triwulan
Petugas Keamanan	PETUGAS_KEAMANAN	Menindaklanjuti laporan keamanan, mengelola jadwal ronda dan kontak darurat
Admin	ADMIN	Mengelola akun pengguna, data warga, pengumuman, agenda, struktur pengurus, pengaduan, dan melihat audit log
Superadmin	SUPERADMIN	Seluruh wewenang Admin, ditambah mengelola semua peran dan izin

---

4. Activity Diagram

Setiap diagram memakai swimlane per pelaku. Notasi: lingkaran hitam adalah awal, lingkaran bertanda target adalah akhir, belah ketupat oranye adalah keputusan atau penggabungan, bar hitam adalah fork/join (aksi paralel), dan kotak hijau adalah objek data. Alur ditulis dari kode (AuthController, LetterService, ResidentDueService, FinanceService, ComplaintController).

4.1. Registrasi Mandiri & Verifikasi Warga

4.2. Login & Penguncian Percobaan

4.3. Lupa & Atur Ulang Kata Sandi

4.4. Birokrasi Surat Pengantar 2-Tier

4.5. Pembayaran Iuran ke Buku Kas

4.6. Transaksi Kas, Koreksi, & Laporan Triwulan

4.7. Pengaduan Lingkungan

---

5. Unified Modeling Language (UML) Diagrams

5.1. UML Class Diagram

Notasi mengikuti template UML: tiga kompartemen (nama, atribut, operasi), - atribut/kolom, + operasi publik, panah segitiga kosong untuk pewarisan atau realisasi, belah ketupat penuh untuk komposisi, belah ketupat kosong untuk agregasi, garis putus-putus untuk dependensi. Atribut dan operasi diambil dari model dan service di app/; atribut yang ditampilkan adalah kolom utama (daftar lengkap ada di ERD), dan created_at/updated_at tidak digambar. Kotak abu-abu hanyalah penanda kelas dari diagram lain.

5.1.1. Akun dan Kependudukan

5.1.2. Surat Pengantar

5.1.3. Model Keuangan

5.1.4. Layanan Keuangan

5.1.5. Pengaduan dan Keamanan

5.1.6. Lapisan Aplikasi (Controller, Service, Event)

5.1.7. Hierarki Kelas Dasar

5.2. UML Sequence Diagram

Notasi mengikuti template UML: kotak peserta berwarna, garis hidup putus-putus, bar aktivasi, panah penuh untuk pemanggilan, panah putus-putus untuk balasan, serta fragmen alt, opt, dan loop dengan kondisi penjaga. Urutan pesan ditulis dari kode (AuthController, LetterService, ResidentDueService, prisma.js), bukan dari rancangan awal.

5.2.1. Registrasi Mandiri Warga

5.2.2. Login dan Penguncian Percobaan

5.2.3. Lupa dan Atur Ulang Kata Sandi

5.2.4. Pengesahan Surat dengan Optimistic Locking

5.2.5. Pencatatan Pembayaran Iuran ke Buku Kas

5.2.6. Pembaruan Dashboard Real-Time (Polling)

Dashboard memakai polling 8 detik (dashboard) dan 10 detik (notifikasi) yang berhenti saat tab tersembunyi. Endpoint GET /api/v1/sync untuk sinkronisasi inkremental disediakan bagi klien lain (mis. aplikasi Android) dan tidak dipanggil oleh PWA web.

---

Fitur Unggulan Antarmuka & Layanan Publik

1. Aestetika Modern PRISMA RT 04:
   • Navigasi responsif dengan logo gradien Blue-Cyan dan drawer mobile ramah layar sentuh.
   • Kartu tindakan cepat ("Apa yang ingin Anda lakukan?"): Urus Surat, Cek Kas RT, Lapor Masalah, Jadwal Kegiatan, Hubungi Pengurus via WhatsApp.
2. Umpan Balik Validasi Interaktif:
   • Animasi shake lembut saat input formulir tidak valid.
   • Notifikasi toast mengambang untuk status sukses dan peringatan sistem.
3. Optimasi Core Web Vitals:
   • Preconnect tipografi Google Fonts via Bunny Fonts untuk menghilangkan FOIT (Flash of Invisible Text).
   • Zero Cumulative Layout Shift (CLS = 0) dengan dimensi gambar eksplisit.
4. Metadata SEO & GEO Wilayah:
   • Tag OpenGraph dan Twitter Cards terpasang rapi.
   • Schema.org Structured Data (GovernmentOrganization dan WebSite) terindeks di wilayah Kemayoran, Jakarta Pusat.

---

API CRUD Real-Time (MySQL)

Seluruh data dibaca/ditulis langsung ke MySQL lewat /api/v1 (autentikasi: sesi browser, atau Bearer token Sanctum dari POST /api/v1/login).

Method	Endpoint	Keterangan
GET	/api/v1/manage/{resource}?q=&page=&per_page=&status=&mine=1	Daftar (cari, filter, paginasi, updated_since)
GET	/api/v1/manage/{resource}/{id}	Detail
POST	/api/v1/manage/{resource}	Tambah
PATCH / PUT	/api/v1/manage/{resource}/{id}	Ubah (kirim version → 409 Conflict bila basi)
DELETE	/api/v1/manage/{resource}/{id}	Hapus
POST	/api/v1/manage/{resource}/{id}/{aksi}	Aksi alur kerja: letters: submit, verify, approve, complete, reject; finance: publish, reverse; citizens: verify, reject

{resource}: users, citizens, announcements, events, officers, schedules, contacts, letters, complaints, security-reports, finance, dues (iuran: POST = buat tagihan bulanan, aksi pay = catat pembayaran), audit-logs. Hak akses tiap resource ditegakkan per peran (lihat matriks di menu Pemodelan Sistem); warga hanya dapat melihat datanya sendiri.

Berkas privat disajikan setelah otorisasi: GET /api/v1/files/letter-attachments/{id}, /files/complaints/{id}, /files/ktp/{id}; surat sah diunduh lewat GET /api/v1/letters/{id}/download?format=pdf|docx (setelah disahkan).

Ekspor CSV (Excel-ready, UTF-8 BOM, aman dari formula injection, maks. 5.000 baris, tercatat di audit log): GET /api/v1/manage/{resource}/export?status=&q= — tombol Ekspor CSV ada di halaman Warga, Kas, Iuran, Surat, Pengaduan, dan Audit. Foto profil: POST|DELETE /api/v1/me/photo.

Endpoint pendukung: GET /api/v1/portal (beranda publik tanpa cache), GET /api/v1/dashboard/summary, GET|POST|DELETE /api/v1/notifications, PATCH /api/v1/me/account, POST /api/v1/me/password, POST /api/v1/auth/check-citizen, POST /api/v1/auth/forgot-password, POST /api/v1/auth/reset-password.

Real-time: UI memakai polling fetch (8 detik untuk tabel/dashboard, 10 detik untuk notifikasi, 20 detik untuk beranda publik) yang berhenti otomatis saat tab tidak aktif; respons API dilengkapi ETag. Setiap perubahan memicu notifikasi database (notifications) + toast/alert, badge lonceng, dan notifikasi browser bila diizinkan.

---

Klasifikasi Dokumentasi Teknis (5 Pilar Subfolder docs/)

Dokumentasi proyek diklasifikasikan ke dalam 5 subfolder tematik yang dapat ditinjau melalui docs/README.md:

1. docs/api_spec/:
   • openapi.yaml: Spesifikasi OpenAPI 3.1 untuk Swagger UI interaktif (/docs/api).
   • API_SPEC.md: Katalog endpoint RESTful JSON v1.
   • API_V1_1_CONTRACT.md: Kontrak penagihan iuran dan audit laporan keuangan.
2. docs/business/:
   • AUTH_REGISTER_AND_LOGIN_SPEC.md: Spesifikasi mendalam alur registrasi, validasi NIK, aktivasi akun, dan login.
   • SRS.md: Software Requirements Specification.
   • LETTER_WORKFLOW.md: Alur kerja surat 2-tier dan QR verification token.
   • FINANCIAL_REPORTS_AND_BACKUP_STORE.md: Regulasi buku kas anti-fraud & backup store.
   • DATA_CLASSIFICATION.md: Standar privasi UU PDP No. 27/2022.
3. :

---

Panduan Instalasi & Menjalankan Proyek (Laragon / XAMPP di Laptop Lain)

Aplikasi ini bersifat self-contained dan siap dijalankan di perangkat/laptop baru mana pun menggunakan stack lokal standar seperti Laragon atau XAMPP.

1. Kebutuhan Sistem & Prasyarat

• PHP versi >= 8.4 (Wajib PHP 8.4+ karena menggunakan Laravel 13)
  • Ekstensi PHP yang aktif: pdo_mysql, mbstring, openssl, curl, fileinfo, gd, zip.
• Composer versi >= 2.5
• (Node.js/NPM tidak diperlukan — UI memakai CSS & JavaScript native tanpa langkah build.)
• MySQL Database Server versi 8.x (atau MariaDB bawaan Laragon/XAMPP)
• Redis Server (Opsional — aplikasi telah dikonfigurasi otomatis menggunakan driver database untuk session, cache, dan queue jika Redis tidak terpasang).

💡 Tips Pengguna Laragon / XAMPP (Cara Memastikan PHP 8.4):

1. Jika Laragon/XAMPP di laptop Anda masih menggunakan PHP 8.1 atau 8.2, unduh paket zip PHP 8.4 VS17 x64 Thread Safe dari windows.php.net/download.
2. Ekstrak ke folder C:\laragon\bin\php\php-8.4.x-Win32-x64.
3. Buka Laragon ➡️ Klik Kanan di mana saja ➡️ PHP ➡️ Version ➡️ Pilih versi 8.4.x.

---

2. Langkah demi Langkah Menjalankan di Laptop Baru (5 Menit)

Langkah 1: Clone Repositori dari GitHub

Buka terminal (Git Bash / PowerShell / Command Prompt):

git clone https://github.com/not162/platform-layanan-publik-warga.git
cd platform-layanan-publik-warga

Langkah 2: Instal Dependensi Backend

composer install

Langkah 3: Konfigurasi File Lingkungan (.env)

Salin file konfigurasi contoh dan buat kunci enkripsi aplikasi:

# Di Windows PowerShell / CMD:
copy .env.example .env

# Generate application encryption key:
php artisan key:generate

Buka file .env di teks editor, lalu sesuaikan koneksi database MySQL Laragon/XAMPP Anda:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=layanan_publik_warga
DB_USERNAME=root
DB_PASSWORD=

(Driver session, queue, dan cache secara default sudah diset ke database, sehingga tidak memerlukan konfigurasi Redis tambahan di laptop lokal).

Langkah 4: Buat Database & Jalankan Migrasi + Seeder

1. Buka phpMyAdmin (http://localhost/phpmyadmin) atau HeidiSQL bawaan Laragon.
2. Buat database baru dengan nama: layanan_publik_warga (Collation: utf8mb4_unicode_ci).
3. Jalankan migrasi dan pengisian data awal melalui terminal:

php artisan migrate --seed

✨ Perintah ini menyusun seluruh tabel relasional dan menginjeksi akun demo (Superadmin, Admin, Ketua RT, Sekretaris, Bendahara, Keamanan, Warga) beserta data contoh beranda, kas, surat, dan pengaduan.

Langkah 5: Jalankan Server Lokal

php artisan serve

Atau gunakan Laragon: arahkan document root ke folder public/.

Buka browser di laptop Anda: 🌐 http://localhost:8000

---

3. Pintasan Kredensial Pengujian Cepat

Daftar akun default (username + password) ada di bagian Mulai Cepat → Akun Default di atas. Halaman login tidak lagi menampilkan pintasan akun apa pun.

Untuk mencoba aktivasi akun dari master RT: buka /register, isi NIK 3171045505920002, No. KK 3171040409950001, nama Siti Aminah, lalu pilih username.

4. Mengirim Email (reset password)

Default MAIL_MAILER=log (email ditulis ke storage/logs/laravel.log). Untuk email sungguhan, isi .env, contoh Gmail (gunakan App Password):

MAIL_MAILER=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
[email protected]
MAIL_PASSWORD=app-password-16-karakter
[email protected]

5. Kop Surat & Pejabat Penandatangan

Semua dokumen resmi (surat HTML/PDF/DOCX, laporan keamanan, laporan kas & rekap iuran) memakai satu sumber identitas di config/rt.php:

Data	Nilai default	Variabel .env
Wilayah	RT 04 / RW 09, Kelurahan Kemayoran, Kecamatan Kemayoran, Jakarta Pusat	RT_NUMBER, RW_NUMBER, RT_KELURAHAN, RT_KECAMATAN, RT_KOTA
Kontak sekretariat	Gg. Bugis No. 95 · +62 878-7200-4448 · [email protected]	RT_ADDRESS, RT_PHONE, RT_EMAIL
Ketua RT (penandatangan surat)	Raden Erry Adu Sundaru	RT_KETUA
Sekretaris (pemeriksa berkas)	Melly	RT_SEKRETARIS
Bendahara (laporan kas)	Retno Fellyanti	RT_BENDAHARA

Nama penandatangan selalu mengikuti konfigurasi ini, bukan akun yang kebetulan menekan tombol Sahkan, sehingga surat tetap sah bila pengurus berganti akun. Jika jabatan berganti, cukup ubah .env lalu php artisan config:clear. Penomoran surat memakai RT04.

6. Deploy ke Production

Seeder demo tidak berjalan di APP_ENV=production (tidak ada akun/password bawaan). Urutan:

# .env production: APP_ENV=production, APP_DEBUG=false, APP_URL=https://domain-anda, DB_*, SESSION_SECURE_COOKIE=true, MAIL_* (SMTP)
composer install --no-dev --optimize-autoloader
php artisan key:generate --force
php artisan migrate --force
php artisan app:create-superadmin admin.rt --name="Nama Anda" [email protected]   # password diminta interaktif
php artisan storage:link   # hanya bila memakai disk public
php artisan config:cache && php artisan route:cache && php artisan view:cache

Catatan: login web memakai cookie sesi + CSRF (host dari APP_URL otomatis terdaftar sebagai domain stateful Sanctum; domain tambahan: SANCTUM_STATEFUL_DOMAINS). Backup rutin database MySQL dan folder storage/app/private (KTP, lampiran). PWA mensyaratkan HTTPS.

7. Membuka Data Langsung di phpMyAdmin

Setiap aksi CRUD di UI/API langsung ditulis ke MySQL. Buka http://localhost/phpmyadmin → database layanan_publik_warga → tabel users, citizens, letters, finance_transactions, announcements, notifications, audit_logs, dst. Halaman akan menampilkan perubahan tanpa perlu cache apa pun.

---

Pengujian Otomatis (Automated Testing)

Pengujian fitur (Feature Tests) dan unit (Unit Tests) dijalankan menggunakan PHPUnit 12:

# Eksekusi ringkas pengujian:
php artisan test --compact

Bukti Hasil Pengujian Terkini:

   Tests:    194 passed (1011 assertions)
   Status:   100% OK

Cakupan baru: iuran, lampiran & foto, unduh PDF, email reset, penguncian login, registrasi (NIK/KK/nama/username unik), lupa & reset password, akses per peran (3 tingkat), CRUD /api/v1/manage/*, alur surat 2-tier + notifikasi, buku kas, manajemen pengguna, dan PWA (manifest, service worker, offline).

---

Keamanan & Perlindungan Data Pribadi (UU PDP)

Sistem mematuhi standar Undang-Undang Perlindungan Data Pribadi (UU PDP No. 27/2022):

1. Blind Indexing SHA-256: NIK mentah di-hash secara satu arah untuk indeks pencarian tanpa mengekspos angka NIK pada query log.
2. Penyamaran Data Publik: NIK yang ditampilkan di antarmuka publik atau pencarian kesamaan nama selalu disamarkan (contoh: 317103********0001).
3. Isolasi Rahasia: Kredensial database dan API keys tidak di-hardcode ke dalam kode sumber, melainkan diatur melalui Environment Variables terenkripsi di server produksi.
4. Audit Trail Komprehensif: Setiap tindakan login, modifikasi berkas, persetujuan surat, dan posting kas tercatat permanen di tabel audit_logs.

---

Lisensi

Proyek ini dikembangkan di bawah lisensi MIT License.
Hak Cipta © 2026 Pengurus PRISMA RT 04 / RW 09 Kemayoran & Pengembang Sistem.