asset-management-system/documentation/guide.md

Dokumentasi Lengkap Asset Management System

Dokumen ini menjadi referensi utama untuk developer/ops yang ingin memahami alur, konfigurasi, dan fitur lengkap sistem.

Isi Singkat

• Arsitektur Ringkas
• Alur Penggunaan
• Setup & Wizard
• Authentication, 2FA, Session Timeout
• RBAC
• System Settings (Referensi)
• Identifikasi Aset (QR/RFID/NFC)
• Transaksi & Approval Workflow
• Maintenance & Read-only Mode
• Logging & Audit Trail
• Import/Export & Bulk Data
• Laporan (Excel/PDF)
• Integrasi API & Webhook
• Notifikasi
• Public Asset View (QR Scan)
• Queues & Kinerja
• Testing
• Deployment Checklist

Arsitektur Ringkas

• Laravel + template Vyzor (Bootstrap).
• Service-first: logic domain di app/Services/*, controller tipis.
• UUID sebagai primary key (role/permission juga sudah di-custom untuk UUID).
• Settings berbasis DB di tabel settings, dibaca via App\Services\System\SystemSettingService.
• Log ke file khusus channel asset_activity (bukan DB).

Alur Penggunaan

1. Buka aplikasi; jika DB belum siap, otomatis redirect ke /setup.
2. Jalankan wizard:
   • Step DB: migrate + seed minimal/full.
   • Step 1: buat admin.
   • Step 2: isi nilai setting (form dari data di DB).
   • Step 3: generate master data dasar.
   • Step 4: buat aset sample (opsional).
3. Login ke dashboard (/dashboard/index), cek ringkasan di dashboard.
4. Kelola master data (status, kelas, kategori, lokasi, PIC, dsb.).
5. Input aset + foto, QR otomatis di-generate jika diaktifkan.
6. Jalankan transaksi (movement, disposal, maintenance, audit) sesuai izin.
7. Approval (jika workflow pending) dikerjakan di menu Approvals.
8. Export laporan (Excel/PDF) atau lakukan import massal jika perlu.

Setup & Wizard

• Route: GET /setup, POST /setup, POST /setup/migrate.
• Bila koneksi DB gagal → tampilkan panduan isi .env + tombol migrate (minimal/full seed).
• Wizard langkah 1–4 (admin, setting, master, aset sample).
• Middleware EnsureDatabaseReady mencegah akses normal sebelum DB siap.

Authentication, 2FA, Session Timeout

• Login: /login, Register: /register, Logout: POST /logout.
• 2FA: setelah password benar, user yang aktifkan 2FA akan diminta kode 6 digit di /two-factor-challenge.
• Session timeout: middleware session.timeout memakai setting security.session_idle_minutes.

RBAC

• Paket spatie/laravel-permission dengan UUID (lihat config/permission.php).
• Permissions utama: settings.manage, users.manage, roles.manage, permissions.manage, assets.view, assets.manage, movements.manage, disposals.manage, audits.manage, maintenance.manage, reports.view, approvals.manage.
• Role seed: super-admin, asset-manager, auditor, maintenance, viewer.
• Scoping data aset: Asset::forUser($user) membatasi berdasar departemen/lokasi kecuali user punya assets.view_all.

System Settings (Referensi)

Semua ada di tabel settings (seeded oleh SettingSeeder). Contoh kunci penting:

• Aplikasi/UI: application.name, application.timezone, ui.date_format, ui.time_format, ui.table_page_size.
• Aset & Identifikasi: asset.code_prefix, asset.qr_enabled, asset.qr_format, asset.qr_size, asset.rfid_enabled, asset.nfc_enabled, asset.rfid_auto_generate, asset.nfc_auto_generate, asset.warranty_reminder_days.
• Workflow: asset.workflow.auto_approve_movement|disposal|maintenance.
• Import: asset.import_max_rows, asset.import_allow_remote_images, asset.import_dedupe_priority, asset.import_default_status/category/location.
• Retensi/Arsip: asset.archive_retention_days, asset.soft_delete_retention_days.
• Security: security.audit_log, security.session_idle_minutes, security.two_factor_enforced.
• Notification: notification.email_enabled, notification.slack_webhook_url, notification.import_result_email.
• Maintenance mode: maintenance.readonly_mode.
• Integrasi: integration.api_key, integration.webhook_enabled, integration.webhook_url, integration.webhook_secret, integration.api_rate_limit.

Identifikasi Aset (QR/RFID/NFC)

• QR otomatis saat create/update aset (jika asset.qr_enabled = true), disimpan di storage/app/public/qr/, isi QR: route('assets.public.show').
• RFID/NFC: field rfid_tag, nfc_tag. Bisa diwajibkan (asset.rfid_required, asset.nfc_required) dan auto-generate (asset.rfid_auto_generate, asset.nfc_auto_generate) oleh AssetService.

Transaksi & Approval Workflow

• Movement: ubah lokasi/departemen/user; jika auto-approve OFF → status pending dan butuh approval.
• Disposal: status approved akan mengubah status aset ke DISPOSED (jika ada); bisa di-reverse.
• Maintenance: status awal pending/planned, lanjut in_progress, completed.
• Audit/Stocktake: status matched/missing/damaged.
• Approval: tersimpan di asset_approval_requests, dikelola via ApprovalService, notifikasi email ke approver & requester.
• Menu approvals: /dashboard/approvals.

Maintenance & Read-only Mode

• Jika maintenance.readonly_mode = true, middleware maintenance.readonly memblok aksi tulis dan dashboard menampilkan badge peringatan.

Logging & Audit Trail

• Request audit: middleware audit.request mencatat semua non-GET beserta durasi dan status.
• Helper: asset_activity_log(), asset_request_log() → channel asset_activity (storage/logs/asset-activity.log, daily).
• ActivityLogger: masking field sensitif (password, token) dan memotong body terlalu panjang.

Import/Export & Bulk Data

• Import: modal di /dashboard/assets, mendukung:
  • Preview (tanpa commit) + ringkasan create/update/invalid.
  • Import langsung.
  • Gambar dari URL (jika asset.import_allow_remote_images) atau ZIP (images_zip + kolom image_file).
• Sample CSV: public/samples/assets_import_sample.csv.
• Export: CSV via GET /dashboard/assets-export (limit 2000 rows).
• Dedupe berdasarkan setting asset.import_dedupe_priority (code/serial).

Laporan (Excel/PDF)

• Menu laporan: /dashboard/reports/assets|movements|disposals|audits.
• Export:
  • Excel multi-sheet (aset + relasi utama, dll.)
  • PDF via DomPDF.
• Filter mengikuti halaman laporan (date range, lokasi, dsb.).

Integrasi API & Webhook

• Public API key di integration.api_key; middleware VerifyApiKey (header X-Api-Key).
• Webhook event aset di App\Services\Integration\WebhookDispatcher (respect integration.webhook_enabled/url/secret/timeout).
• Dokumentasi API disediakan di GET /api-docs.

Notifikasi

• Email notifikasi approval: ApprovalRequestedNotification, ApprovalDecisionNotification.
• SMTP wajib dikonfigurasi di .env (MAIL_*). Jika notification.email_enabled=false, notifikasi email tidak dikirim.
• Contoh cron reminder sederhana: php artisan asset:notify-due (garansi akan habis, maintenance due, audit overdue) → tambahkan ke cron jika perlu.

Public Asset View (QR Scan)

• Route: GET /asset-view/{asset} (tanpa login).
• Di halaman ini tersedia tombol transaksi (movement/disposal/maintenance) dalam bentuk modal jika user login & punya permission; jika tidak, hanya view data + foto aset.

Queues & Kinerja

• Import besar dianjurkan dijalankan di queue (kini masih sinkron); arsitektur kode disiapkan agar mudah dialihkan ke job queue jika volume tinggi.
• Gunakan php artisan queue:work untuk job lain (notifikasi/email) jika diubah ke asynchronous.
• Pagination server-side diterapkan pada tabel besar (misal approvals, master, transaksi).
• Index DB sudah disiapkan di migrasi utama (cek migrasi masing-masing tabel).

Testing

• Jalankan semua test:

php artisan test

• Test penting:
  • tests/Feature/DashboardPageTest.php
  • tests/Feature/AssetTransactionFlowTest.php
  • tests/Feature/SystemSettingsPageTest.php

Deployment Checklist

• APP_ENV=production, APP_DEBUG=false, APP_KEY terisi.
• Konfigurasi DB + jalankan php artisan migrate --force.
• php artisan storage:link.
• Build frontend: npm run build (atau gunakan artifact public/build yang sudah ada).
• Permission folder: storage/ dan bootstrap/cache/ writable.
• Set SMTP (MAIL_*), dan cron untuk queue (jika dipakai) / asset:notify-due (opsional).