From 0bd79b79dde25d2f52f49410a99abdfcb4ca991d Mon Sep 17 00:00:00 2001 From: Arya Dwi Putra Date: Fri, 19 Dec 2025 09:18:52 +0700 Subject: [PATCH] docs: add detailed documentation guide and link from README --- README.md | 6 ++ documentation/guide.md | 149 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 155 insertions(+) create mode 100644 documentation/guide.md diff --git a/README.md b/README.md index d699447..dc3af8e 100644 --- a/README.md +++ b/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` diff --git a/documentation/guide.md b/documentation/guide.md new file mode 100644 index 0000000..7f2e633 --- /dev/null +++ b/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). +