docs: add detailed documentation guide and link from README

README.md

@@ -30,6 +30,7 @@ Project ini dibuat dengan fokus pada **best practice**, **clean code**, dan siap
 - [Testing](#testing)
 - [Deployment Notes](#deployment-notes)
 - [Contributing](#contributing)
+- [Dokumentasi Lengkap](#dokumentasi-lengkap)
 
 ## Fitur Utama
 
@@ -358,3 +359,8 @@ Kontribusi sangat diterima.
 - Gunakan style & struktur yang sudah ada (controller tipis, logic di service)
 - Tambahkan test untuk fitur baru bila memungkinkan
 - Buat PR kecil dan fokus per fitur
+
+## Dokumentasi Lengkap
+
+Dokumentasi teknis terperinci (alur, setting, workflow, integrasi, notifikasi, dsb.) tersedia di:
+- `documentation/guide.md`

documentation/guide.md

@@ -0,0 +1,149 @@
+# 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](#arsitektur-ringkas)
+- [Alur Penggunaan](#alur-penggunaan)
+- [Setup & Wizard](#setup--wizard)
+- [Authentication, 2FA, Session Timeout](#authentication-2fa-session-timeout)
+- [RBAC](#rbac)
+- [System Settings (Referensi)](#system-settings-referensi)
+- [Identifikasi Aset (QR/RFID/NFC)](#identifikasi-aset-qrrfidnfc)
+- [Transaksi & Approval Workflow](#transaksi--approval-workflow)
+- [Maintenance & Read-only Mode](#maintenance--read-only-mode)
+- [Logging & Audit Trail](#logging--audit-trail)
+- [Import/Export & Bulk Data](#importexport--bulk-data)
+- [Laporan (Excel/PDF)](#laporan-excelpdf)
+- [Integrasi API & Webhook](#integrasi-api--webhook)
+- [Notifikasi](#notifikasi)
+- [Public Asset View (QR Scan)](#public-asset-view-qr-scan)
+- [Queues & Kinerja](#queues--kinerja)
+- [Testing](#testing)
+- [Deployment Checklist](#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:
+```bash
+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).
+