desamoderen

Imported from ranggamaulana111111-bit/desamoderen (AGENTS.md). Install upstream with npx skills add ranggamaulana111111-bit/desamoderen. Copyright stays with the author.

AGENTS.md - Prodesa

Stack

Laravel 11, PHP ^8.2, MySQL (via Laragon), Tailwind CSS (CDN), Alpine.js, Chart.js.

First-time setup

copy .env.example .env
php artisan key:generate
npm install && npm run build

APP_KEY must be generated before the app runs. SQLite extension pdo_sqlite and zip extension must be enabled in php.ini.

PHP and Composer via Laragon:

$env:Path = "C:\laragon\bin\php\php-8.2.31-Win32-vs16-x64\;C:\laragon\bin\composer\;$env:Path"
php -d memory_limit=-1 C:\laragon\bin\composer\composer.phar require <package>

Server prerequisites for the Update Aplikasi feature

The "Update Aplikasi" card (Admin → Pengaturan → Maintenance) uses git via Symfony Process.

• git must be on the PATH of the process serving the app (php artisan serve / Laragon Apache). On Windows, prepend C:\Program Files\Git\cmd to PATH before starting the server.
• The app folder must be a git clone of the project repo (a plain copy/folder is not detected as a repository).
• The server must have internet access to origin for git fetch.
• The card runs git pull --ff-only, composer install, php artisan migrate, npm ci, npm run build, php artisan optimize:clear (requires Node + Composer on PATH).
• Important (Windows): the service uses array-form Process(['git', ...]), NOT Process::fromShellCommandline(). Shell-form commands (cmd.exe /c) fail to resolve executables inside Laravel web requests on Windows even when git is on PATH — array-form is reliable.

## Users & Auth

| Role | Login | Register |
|------|-------|----------|
| Warga | NIK + password via `/login` | Self-register via `/register` |
| Admin (any role != Warga) | NIK + password via `/login` | Only created manually via tinker |

**Roles available:** Super Admin, Operator Pelayanan, Sekretaris Desa, Kepala Desa, RT, RW, Warga, Lembaga.

Admin user created via:
```powershell
php artisan tinker --execute="\App\Models\User::create(['name'=>'Admin','nik'=>'0000000000000000','password'=>bcrypt('admin123'),'email'=>'admin@prodesa.id']);"

Common commands

Routes

Public (no auth)

Guest

Auth (shared)

Admin (/admin/*, middleware: auth + admin + ip.whitelist)

Warga (/warga/*, middleware: auth)

Lembaga (/lembaga/*, middleware: auth + permission:lembaga.content)

Roles & Permissions

Database

• MySQL: database prodesa, user root, no password
• Key tables: users, pengajuan_surats, approval_histories, document_versions, letter_configs, antrean_pengambilan, events, event_pesertas, berita, activity_logs, village_settings, setting_versions, user_settings, dashboard_layouts, lembagas, permissions, roles, model_has_roles, model_has_permissions
• pengajuan_surats.data_tambahan stores per-type form fields as JSON

Architecture

Approval Workflow

• ApprovalService handles all workflow logic (step map, permissions, transitions, timeline)
• Steps: submitted → verified → approved_operator → approved_sekdes → approved_kades → completed
• Reject/revision can happen at any step
• PengajuanSurat status tracks current workflow step
• Permissions: letter.create (warga), letter.review (operator), letter.verify (sekdes), letter.final_approve (kades)

Letter Config System (Feature 6)

• LetterConfig model stores per-type config: fields JSON, body_template, kode_klasifikasi, masa_berlaku_bulan
• DynamicLetterService implements LetterGeneratorInterface using LetterConfig::renderBody()
• LetterServiceFactory resolves: existing strategies (sktm/ktp_sementara/akta) → DynamicLetterService fallback
• 14 letter types seeded: sktm, ktp_sementara, akta, sku, domisili, skkb, belum_menikah, izin_keramaian, ahli_waris, kepemilikan_tanah, pengantar_skck, penghasilan, janda_duda, pindah
• Form validation is dynamic via LetterConfig::getValidationRules()
• Form view renders fields dynamically (text, select, textarea, number, date, time)

Document Versioning

• DocumentVersionService auto-creates version on each workflow transition
• DocumentVersionController provides index, show, diff, restore, download
• DocumentVersionPolicy gates access

Queue Monitoring

• QueueMonitoringService fetches stats + failed jobs from failed_jobs table
• Chart.js weekly bar chart + status donut
• Retry single / retry all / delete failed jobs

Analytics

• AnalyticsService with 8 metric methods (overview, trends, popular types, avg processing time, user growth, operator performance, status distribution, export CSV)
• 4 Chart.js charts (line, bar, donut, line)

Conventions

• 4-space indentation, LF line endings (.editorconfig)
• Models in app\Models\, controllers in app\Http\Controllers\
• Routes: web in routes/web.php, commands in routes/console.php
• bootstrap/app.php is the Laravel 11 app config entrypoint
• No Breeze / Jetstream / auth scaffolding — custom auth via NIK
• Spatie Permission for RBAC (already installed)
• Service Layer pattern (ApprovalService, AnalyticsService, etc.)
• Strategy/Factory pattern (LetterServiceFactory + strategies)
• Transaction safety for multi-step operations
• Activity Log via ActivityLog::catat() model method