Onboarding Asset Karyawan

01Informasi Dokumen

03Quick Overview

Gambaran implementasi sebenarnya:

Admin Asset
   ↓  (Asset Karyawan → "On Board" → tombol +)
Form On Boarding (Pilih Karyawan, Tambah Asset, Catatan Tambahan)
   ↓  Simpan Draft / Submit ke Karyawan
Flutter (AssetOnboardingBloc → AssetOnboardingApi → ApiClient/Dio + Bearer JWT)
   ↓
Lumen API  (middleware jwt.api + jwt.ctx → AssetAdminOnboarding_c → validasi → AssetAdmin_m)
   ↓  DB::transaction + lock master_company
INSERT asset_trx_onboarding_karyawan (draft/proses)
INSERT asset_trx_onboarding_karyawan_item (status_item = belum_dicek)
UPDATE asset_data.status_asset = 'proses'   (asset ter-reservasi)
   ↓  notifikasi "Onboarding Asset Baru" (jika bukan draft)
Karyawan → Asset Saya → Konfirmasi Asset Baru (Normal / Rusak per asset)
   ↓
Asset Normal → asset_data: terpakai, pemegang = karyawan  + INSERT asset_trx_log
Asset Rusak  → asset_data: rusak, tetap di gudang → status "Isu Rusak"
   ↓  (jika ada rusak) Admin → Ganti Asset Yang Rusak → item pengganti → karyawan cek lagi
Semua item aktif Normal → status_approval = dikonfirmasi ("Selesai")

04Ringkasan Fitur

Asset Onboarding Karyawan adalah fitur modul Asset Management untuk mencatat dan menyerahkan asset perusahaan dari gudang kepada seorang karyawan, disertai verifikasi kondisi fisik oleh karyawan penerima.

Cara kerja berdasarkan kode:

• Onboarding dibuat oleh Admin Asset: memilih satu karyawan aktif, satu/lebih asset yang tersedia di gudang, dan catatan tambahan. Dapat disimpan sebagai Draft (bisa diedit/dihapus) atau langsung dikirim ke karyawan.
• Asset ditentukan saat pembuatan (bukan tahap terpisah). Asset langsung dikunci (status_asset = proses), termasuk untuk draft.
• Tidak ada approval atasan/approver. Tahap "konfirmasi" adalah pengecekan fisik oleh karyawan penerima.
• Serah terima terjadi ketika karyawan mengonfirmasi: setiap asset dinilai Normal atau Rusak. Asset Normal langsung berpindah ke karyawan (per item, parsial). Asset Rusak tetap di gudang berstatus rusak.
• Penggantian: bila ada asset rusak, Admin memilih asset pengganti; karyawan mengecek ulang hanya asset pengganti. Siklus ini dapat berulang.
• Transaksi selesai (dikonfirmasi) ketika seluruh item aktif (item yang tidak digantikan) berstatus normal.
• Pemegang asset berubah pada asset_data.pemegang_asset = 'karyawan' dan id_pemegang_asset = id_karyawan; histori dicatat ke asset_trx_log.

05Tujuan Fitur

5.1 Tujuan Bisnis (diturunkan dari kode)

• Setiap asset yang diserahkan ke karyawan tercatat dalam transaksi bernomor (KRY01-...).
• Karyawan wajib memeriksa kondisi fisik dan menyatakan tanggung jawab atas asset ("Dengan menerima asset ini, saya menyatakan telah memeriksa kondisi dan bertanggung jawab atas asset tersebut.").
• Asset rusak saat serah terima tidak dibebankan ke karyawan, tetap di gudang dengan status rusak, dan dapat diganti.
• Asset yang sedang diproses tidak dapat dipakai oleh transaksi lain (peminjaman, penambahan, onboarding lain).
• Setiap perpindahan asset ke karyawan dapat ditelusuri (asset_trx_log).

5.2 Tujuan Sistem

• Membuat, mengubah, dan menghapus draft transaksi onboarding.
• Menyimpan daftar asset beserta snapshot nama/deskripsi/kategori.
• Mereservasi asset (status_asset = proses) selama transaksi berjalan.
• Mencatat hasil pengecekan per item (normal/rusak + alasan).
• Memindahkan pemegang asset ke karyawan dan mencatat asset_trx_log.
• Menyediakan mekanisme asset pengganti berbentuk pohon (parent_id).
• Mengirim notifikasi inbox + push FCM ke pihak terkait.

06Aktor

07Hak Akses

08Terminologi

09Business Rules

BR-001 — Hanya Admin Asset yang dapat mengelola onboarding

• Kondisi: endpoint /asset/onboarding-karyawan*.
• Validation: Asset_m::isAdmin → ada di asset_admin untuk company yang sama dan data_karyawan.status ∈ '1','2','3','4'. Model juga memanggil findAssetAdmin untuk mengambil nik - nama aktor.
• Error: 403 FORBIDDEN "Pengguna tidak memiliki akses admin asset." / 422 "Pengguna tidak terdaftar sebagai admin asset."

BR-002 — Karyawan penerima wajib dipilih dan aktif

• Validation: id_karyawan required; findActiveKaryawan (company sama, status aktif).
• Error: 422 "Karyawan wajib dipilih." / 422 BUSINESS_RULE_VIOLATION "Karyawan tidak ditemukan atau tidak aktif."

BR-003 — Minimal satu asset, tanpa duplikat

• Validation: asset_ids array min 1, asset_ids.* distinct. Mobile mencegah memilih asset yang sama (exclude di picker).
• Error: "Minimal satu asset wajib dipilih." / "Asset yang sama tidak boleh dipilih lebih dari sekali."

BR-004 — Catatan tambahan wajib saat dikirim, opsional saat draft

• Validation: keterangan required jika is_draft=false.
• Error: "Catatan tambahan wajib diisi."

BR-005 — Asset harus tersedia di gudang

• Validation: asset_data.status_asset = 'tersedia' AND pemegang_asset = 'gudang' (dengan FOR UPDATE). Jumlah hasil harus sama dengan jumlah asset dikirim.
• Error: "Satu atau beberapa asset tidak tersedia untuk onboarding."
• Catatan: kondisi_awal asset tidak divalidasi (asset dengan kondisi awal apa pun boleh dipilih selama status tersedia).

BR-006 — Asset tidak boleh aktif di onboarding lain

• Validation: hasActiveOnboardingAsset — ada item belum_dicek, belum diganti, pada header draft/proses.
• Error: "Satu atau beberapa asset sedang diproses pada onboarding lain."

BR-007 — Asset langsung direservasi, termasuk draft

• Action: asset_data.status_asset = 'proses' saat create/update (draft maupun kirim) dan saat penggantian. Dilepas (proses → tersedia) saat draft diubah (asset lama) atau dihapus.

BR-008 — Draft hanya dapat diubah/dihapus selama berstatus draft

• Error: "Hanya onboarding berstatus draft yang dapat diubah." / "...dapat dihapus." / "Draft onboarding asset tidak ditemukan."

BR-009 — Karyawan hanya mengakses onboarding miliknya dan bukan draft

• Validation: WHERE id_karyawan = ctx.id_karyawan AND status_approval != 'draft'.
• Error: 404 "Onboarding asset tidak ditemukan." (detail) / 422 (konfirmasi).

BR-010 — Konfirmasi hanya untuk status proses dan jika ada item perlu dicek

• Error: "Onboarding asset sudah tidak menunggu konfirmasi." / "Tidak ada asset yang perlu dicek. Asset rusak sedang menunggu penggantian dari admin."

BR-011 — Semua item yang perlu dicek wajib dinilai sekaligus

• Validation: jumlah & ID item dikirim harus sama persis dengan item pending. Mobile: tombol aktif hanya bila semua dinilai.
• Error: "Seluruh asset pada onboarding wajib dicek."

BR-012 — Asset rusak wajib disertai keterangan

• Validation: ket_rusak required_if status_item = rusak, max 255.
• Error: "Alasan kerusakan wajib diisi."

BR-013 — Serah terima bersifat parsial per item

• Action: Item normal pada ronde konfirmasi langsung diserahkan (asset terpakai, pemegang karyawan) walaupun item lain rusak.

BR-014 — Asset rusak kembali ke gudang berstatus rusak

• Action: asset_data.status_asset = 'rusak', id_pemegang_asset = '', ket_rusak = alasan (hanya jika asset masih proses & gudang). Pesan UI: "Asset yang rusak akan dikembalikan ke gudang dengan status "Rusak"."

BR-015 — Transaksi selesai otomatis

• Kondisi: seluruh item aktif berstatus normal → status_approval = dikonfirmasi. Jika tidak, tetap proses (Isu Rusak).

BR-016 — Penggantian hanya setelah karyawan selesai mengecek

• Validation: status proses, tgl_approval tidak NULL, tidak ada item pending.
• Error: "Asset rusak hanya dapat diganti setelah karyawan selesai mengecek asset."

BR-017 — Item yang diganti harus rusak dan belum pernah diganti

• Error: "Satu atau beberapa asset rusak tidak valid atau sudah diganti."
• Penggantian boleh untuk sebagian item rusak saja.

BR-018 — Asset pengganti harus valid

• Tersedia & di gudang (BR-005), unik, tidak aktif di onboarding lain, kelengkapan wajib (max 255).
• Error: "Satu atau beberapa asset pengganti tidak tersedia." / "Asset pengganti yang sama tidak boleh dipilih lebih dari sekali." / "Satu atau beberapa asset pengganti sedang diproses pada onboarding lain." / "Kelengkapan asset pengganti wajib diisi."

BR-019 — Batas penomoran

• ID header dan ID item: 3 digit urut per company per bulan (maks. 999); ID log: 5 digit.
• Error: "Nomor transaksi untuk periode ini sudah mencapai batas."

BR-020 — Satu karyawan hanya boleh punya satu onboarding seumur hidup

• Endpoint options mengecualikan karyawan yang sudah punya baris onboarding berstatus apa pun (draft, proses, ditolak, dikonfirmasi); baris draft milik transaksi yang sedang diedit dikecualikan lewat exclude_onboarding_id.
• Aturan ini juga divalidasi saat simpan dan ubah draft lewat AssetAdmin_m::assertKaryawanBelumPernahOnboarding.
• Error: "Karyawan ini sudah pernah menerima onboarding asset." (422). Menghapus draft membebaskan karyawan kembali.

BR-021 — Asset dalam onboarding aktif terkunci untuk modul lain

• Peminjaman dan Penambahan/Request asset memanggil hasActiveOnboardingAsset → "Satu atau beberapa asset sedang diproses pada onboarding."

10Business Flow

Admin membuka Asset Karyawan → On Board
        ↓
Tambah (+) → Pilih Karyawan → Tambah Asset (kategori → asset) → Catatan Tambahan
        ↓
 ┌──────────── Simpan Draft ─────────────┐        Submit ke Karyawan
 │ status draft, asset direservasi       │               │
 │ (bisa Lanjutkan Draft / Hapus)        │               │
 └── Publish ke Karyawan ────────────────┴──────────────►│
                                                         ↓
                                     status proses ("Menunggu Diterima")
                                     notifikasi ke karyawan
                                                         ↓
                              Karyawan: Asset Saya → Konfirmasi Asset Baru
                              nilai tiap asset Normal / Rusak (+alasan)
                                                         ↓
                    ┌────────── semua item aktif Normal? ──────────┐
                    │ Ya                                            │ Tidak
                    ↓                                               ↓
   status dikonfirmasi ("Selesai")                 status tetap proses ("Isu Rusak")
   asset normal → terpakai, pemegang karyawan      asset normal → terpakai (tetap diserahkan)
   notifikasi admin "Dikonfirmasi"                 asset rusak → status rusak di gudang
                                                   notifikasi admin "Laporan Asset Rusak"
                                                                    ↓
                                                   Admin: Ganti Asset Yang Rusak
                                                   pilih asset pengganti → Submit ke Karyawan
                                                                    ↓
                                                   status "Menunggu Diterima" (hanya pengganti dicek)
                                                                    ↓
                                                   kembali ke konfirmasi karyawan (berulang)

11Flow Berdasarkan Role

11.1 Admin Asset

1. Buka halaman admin Asset Karyawan, pilih aksi On Board → halaman On Boarding Asset (tab Proses/Dikonfirmasi/Selesai).
2. Tekan + → form On Boarding Asset.
3. Pilih Karyawan (bottom sheet, cari nama/NIK). Hanya karyawan aktif yang belum pernah punya onboarding yang muncul.
4. Tambah Asset: pilih kategori (pohon kategori), lalu asset (cari nama/kode/merek). Ulangi untuk asset lain; asset bisa dihapus dari daftar.
5. Isi Catatan Tambahan.
6. Tekan Simpan Draft (status draft) atau Submit ke Karyawan (status proses + notifikasi).
7. Draft: pada list tekan Lanjutkan Draft untuk edit → Simpan Draft / Publish ke Karyawan; atau Hapus.
8. Pantau detail. Jika status Isu Rusak (tab Dikonfirmasi), buka detail → Ganti Asset Yang Rusak → tiap item rusak Ganti Asset → pilih asset pengganti → Submit ke Karyawan.
9. Transaksi berpindah ke tab Selesai setelah karyawan mengonfirmasi semua asset aktif normal.

11.2 Karyawan

1. Menerima notifikasi "Onboarding Asset Baru" / "Asset Pengganti", atau melihat banner On Boarding Asset di Asset Saya.
2. Buka Konfirmasi Asset Baru: lihat data onboarding, data karyawan, catatan tambahan, daftar asset.
3. Untuk setiap asset yang perlu dicek pilih Normal atau Rusak; jika Rusak isi Report Kerusakan.
4. Tekan Konfirmasi Asset. Asset normal masuk daftar asset miliknya.

11.3 Approver

⚠️ Belum ditemukan: tidak ada role/proses approver pada source.

11.4 System

• Validasi request & aturan bisnis; lock master_company per transaksi.
• Generate ID & nomor transaksi.
• Reservasi/pelepasan asset (tersedia ⇄ proses).
• Pada konfirmasi: update item, update asset_data, insert asset_trx_log, tentukan status header.
• Hitung label/tab turunan (status_label, tab, isu_rusak, perlu_dicek, diganti).
• Kirim notifikasi inbox (notif_data) + push FCM setelah transaksi DB selesai.

12Flow Diagram

flowchart TD
    A[Admin buka On Boarding Asset] --> B[Tambah +]
    B --> C[Pilih Karyawan]
    C --> D[Tambah Asset]
    D --> E[Isi Catatan Tambahan]
    E --> F{Aksi}
    F -->|Simpan Draft| G{Validasi mobile: karyawan & min 1 asset}
    F -->|Submit ke Karyawan| H{Validasi mobile: karyawan, asset, catatan}
    G -->|Tidak valid| X[Snackbar / pesan field]
    H -->|Tidak valid| X
    G -->|Valid| I[POST/PUT is_draft=true]
    H -->|Valid| J[POST/PUT is_draft=false]
    I --> K{Validasi backend}
    J --> K
    K -->|Gagal| X2[422 / 403 / 500 → snackbar]
    K -->|OK| L[INSERT header + item, asset_data = proses]
    L -->|draft| M[Status Draft - Lanjutkan / Hapus]
    M -->|Publish| J
    M -->|Hapus| N[DELETE item+header, asset_data = tersedia]
    L -->|proses| O[Notif ke Karyawan]
    O --> P[Karyawan: Konfirmasi Asset Baru]
    P --> Q[Nilai Normal / Rusak]
    Q --> R[POST konfirmasi]
    R --> S[Item normal: asset terpakai, pemegang karyawan, asset_trx_log]
    R --> T[Item rusak: asset status rusak di gudang]
    S --> U{Semua item aktif normal?}
    T --> U
    U -->|Ya| V[Status dikonfirmasi - Selesai, notif admin]
    U -->|Tidak| W[Tetap proses - Isu Rusak, notif admin]
    W --> Y[Admin: Ganti Asset Yang Rusak]
    Y --> Z[POST ganti-asset: item pengganti, asset = proses, notif karyawan]
    Z --> P

13Sequence Diagram

13.1 Buat onboarding (Submit ke Karyawan)

sequenceDiagram
    actor Admin
    participant UI as Form On Boarding
    participant Bloc as AssetOnboardingBloc
    participant Api as AssetOnboardingApi/ApiClient
    participant MW as JwtAuth + ResolveContext
    participant C as AssetAdminOnboarding_c
    participant M as AssetAdmin_m / Asset_m
    participant DB
    participant N as AssetNotification

    Admin->>UI: Pilih karyawan, asset, catatan, Submit
    UI->>Bloc: SubmitAssetOnboarding(request)
    Bloc->>Api: store()
    Api->>MW: POST /asset/onboarding-karyawan (Bearer)
    MW->>C: ctx {id_company, id_karyawan}
    C->>C: validateRequest + accessError
    C->>M: storeOnboardingKaryawan()
    M->>DB: BEGIN, lock master_company
    M->>DB: SELECT asset_data FOR UPDATE (tersedia, gudang)
    M->>DB: cek onboarding aktif, karyawan aktif, admin
    M->>DB: nextSequence header & item (FOR UPDATE)
    M->>DB: INSERT header, INSERT item[], UPDATE asset_data=proses
    M->>DB: COMMIT
    M-->>C: {id, no_trx, status_approval}
    C->>N: send('onboarding.dikirim')
    N->>DB: INSERT notif_data + FCM push
    C-->>Api: 201 CREATED
    Api-->>Bloc: ApiResult
    Bloc-->>UI: success → pop(message)
    UI-->>Admin: kembali ke list + snackbar

13.2 Konfirmasi karyawan

sequenceDiagram
    actor K as Karyawan
    participant UI as Konfirmasi Asset Baru
    participant Bloc as AssetKonfirmasiOnboardingBloc
    participant C as AssetKaryawanOnboarding_c
    participant M as AssetKaryawan_m
    participant DB
    participant N as AssetNotification

    K->>UI: pilih Normal/Rusak tiap asset, Konfirmasi Asset
    UI->>Bloc: SubmitAssetKonfirmasiOnboarding
    Bloc->>C: POST /asset/karyawan/onboarding/{id}/konfirmasi
    C->>C: validateRequest
    C->>M: konfirmasiOnboardingKaryawan()
    M->>DB: BEGIN, lock company, header FOR UPDATE (milik karyawan, proses)
    M->>DB: UPDATE item status_item/ket_rusak
    M->>DB: UPDATE asset_data rusak (item rusak)
    M->>DB: UPDATE header status/user_approval/tgl_approval
    M->>DB: UPDATE asset_data terpakai + pemegang (item normal)
    M->>DB: INSERT asset_trx_log (item normal)
    M->>DB: COMMIT
    C->>N: onboarding.dikonfirmasi / onboarding.rusak (ke semua admin)
    C-->>Bloc: 200 UPDATED {status_approval, status_label, tab}
    Bloc-->>UI: pop(message) → reload Asset Saya

13.3 Ganti asset rusak

sequenceDiagram
    actor Admin
    participant UI as Ganti Asset Rusak
    participant Bloc as AssetGantiRusakBloc
    participant C as AssetAdminOnboarding_c
    participant M as AssetAdmin_m
    participant DB
    participant N as AssetNotification

    UI->>Bloc: LoadAssetPenggantiOptions
    Bloc->>C: GET /asset/onboarding-karyawan/options
    Admin->>UI: Ganti Asset per item rusak → pilih asset
    Admin->>UI: Submit ke Karyawan
    Bloc->>C: POST /asset/onboarding-karyawan/{id}/ganti-asset
    C->>M: gantiAssetRusakOnboarding()
    M->>DB: lock, validasi header, item rusak, asset pengganti
    M->>DB: INSERT item pengganti (parent_id = item rusak)
    M->>DB: UPDATE asset_data pengganti = proses
    M->>DB: UPDATE header tgl_update
    C->>N: onboarding.pengganti (ke karyawan)
    C-->>Bloc: 200 UPDATED
    Bloc-->>UI: pop(message) → reload detail

14Status Transaksi

Field: asset_trx_onboarding_karyawan.status_approval (enum status_onboarding, default proses). Enum PHP: App\Models\Asset\OnboardingStatus. Enum Flutter: AssetOnboardingApproval.

Status turunan per item (status_item, enum kondisi_awal): belum_dicek → normal / rusak. Label UI item: Menunggu Diterima / Normal / Rusak.

Migrasi nilai lama (2026_09_17_000007): 0=draft, 1=proses, 2=ditolak, 3=dikonfirmasi.

15State Transition

stateDiagram-v2
    [*] --> draft: Simpan Draft (Admin)
    [*] --> proses: Submit ke Karyawan (Admin)
    draft --> draft: Simpan Draft lagi (Admin)
    draft --> proses: Publish ke Karyawan (Admin)
    draft --> [*]: Hapus draft (Admin)
    state proses {
        MenungguDiterima --> IsuRusak: Konfirmasi, ada item rusak (Karyawan)
        IsuRusak --> MenungguDiterima: Ganti asset rusak (Admin)
    }
    proses --> dikonfirmasi: Konfirmasi, semua item aktif normal (Karyawan)
    dikonfirmasi --> [*]

Status asset_data.status_asset akibat onboarding:

16Struktur Database

17Relasi Database

Relasi berasal dari ref DBML dan kondisi JOIN pada query (semua JOIN juga mencocokkan id_company).

erDiagram
    ASSET_TRX_ONBOARDING_KARYAWAN ||--o{ ASSET_TRX_ONBOARDING_KARYAWAN_ITEM : "id_asset_trx_onboarding"
    ASSET_TRX_ONBOARDING_KARYAWAN_ITEM |o--o{ ASSET_TRX_ONBOARDING_KARYAWAN_ITEM : "parent_id (pengganti)"
    ASSET_DATA ||--o{ ASSET_TRX_ONBOARDING_KARYAWAN_ITEM : "id_asset_data"
    ASSET_KATEGORI_M ||--o{ ASSET_DATA : "id_asset_kategori_m"
    ASSET_DATA ||--o{ ASSET_TRX_LOG : "id_asset_data"
    ASSET_TRX_ONBOARDING_KARYAWAN ||--o{ ASSET_TRX_LOG : "id_transaksi (logis)"
    DATA_KARYAWAN ||--o{ ASSET_TRX_ONBOARDING_KARYAWAN : "id_karyawan (logis)"
    DATA_KARYAWAN ||--o| ASSET_ADMIN : "id_karyawan"
    DATA_KARYAWAN ||--o{ ASSET_DATA : "id_pemegang_asset (logis)"

    ASSET_TRX_ONBOARDING_KARYAWAN {
        varchar id_asset_trx_onboarding_karyawan PK
        varchar no_trx
        date tgl_onboarding
        text keterangan
        varchar id_karyawan
        enum status_approval
        timestamp tgl_approval
        varchar id_company
    }
    ASSET_TRX_ONBOARDING_KARYAWAN_ITEM {
        varchar id_asset_trx_onboarding_item PK
        varchar parent_id
        varchar id_asset_trx_onboarding FK
        varchar id_asset_data FK
        enum status_item
        varchar ket_rusak
        varchar id_company
    }
    ASSET_DATA {
        varchar id_asset_data PK
        varchar kode_asset
        enum status_asset
        enum pemegang_asset
        varchar id_pemegang_asset
        varchar id_company
    }
    ASSET_TRX_LOG {
        varchar id_asset_trx_log PK
        varchar id_asset_data FK
        enum jenis_log
        varchar id_transaksi
        varchar nama_tabel_transaksi
    }

Relasi logis (tanpa ref di DBML, hanya lewat query): id_karyawan → data_karyawan, id_pemegang_asset → data_karyawan, asset_trx_log.id_transaksi → header, parent_id → item. ⚠️ Belum ditemukan: apakah FK fisik dibuat di database (tidak ada migration create table).

18Data Dictionary

18.1 asset_trx_onboarding_karyawan

18.2 asset_trx_onboarding_karyawan_item

18.3 asset_data (field yang dipakai fitur)

18.4 asset_trx_log (yang diisi fitur)

19Database Index

Dibuat oleh migration 2026_09_17_000005 dan dibuat ulang di 2026_09_17_000007.

Catatan: pencarian berdasarkan atoki.id_asset_data (cek asset aktif) dan pengganti.parent_id (NOT EXISTS) tidak diawali kolom index di atas — lihat RISK-010.

20Backend Architecture

routes/web.php → RouteLoader (routes/modules/asset, prefix "asset")
   ↓  middleware: jwt.api (JwtAuth) → jwt.ctx (ResolveContext)
Controller (AssetAdminOnboarding_c / AssetKaryawanOnboarding_c)  ← extends Asset_c ← BaseController
   ↓  validateRequest() (Validator inline) + accessError()
Model statis (AssetAdmin_m / AssetKaryawan_m ← Asset_m)  — berisi business logic + query
   ↓  DB::table (Query Builder), DB::transaction
Database
   ↓
ApiResponse (format JSON seragam)   +   AssetNotification (setelah commit)

Tidak ada layer Service, Repository, FormRequest, atau Eloquent relation untuk fitur ini.

21Backend Business Logic

Semua aksi tulis memakai DB::transaction(fn, 3) (retry deadlock 3×) dan diawali lockCompany() (SELECT id_company FROM master_company ... FOR UPDATE) sehingga transaksi asset dalam satu company diserialkan.

21.1 Create — storeOnboardingKaryawan

1. Auth: middleware JWT → ctx.
2. Validasi request (controller) lalu cek admin (accessError).
3. lockCompany.
4. asset_ids di-unique; getLockedAssets (tersedia + gudang, FOR UPDATE) — jumlah harus sama.
5. hasActiveOnboardingAsset → tolak jika asset aktif di onboarding lain.
6. findActiveKaryawan (penerima) dan findAssetAdmin (aktor).
7. Generate ID: nextSequence(header) → id_company + YYYYMM + %03d; no_trx = 'KRY01-' + YYYYMM + %03d.
8. INSERT header (status_approval draft/proses, tgl_approval NULL, user_input = nik - nama admin).
9. Generate ID item (sequence lanjutan) dan INSERT item per asset (parent_id='', status_item='belum_dicek', snapshot).
10. UPDATE asset_data status_asset='proses'.
11. COMMIT; controller mengirim notifikasi onboarding.dikirim bila bukan draft.
12. Response 201 CREATED.

21.2 Update Draft — updateOnboardingDraft

1. Validasi, akses, lock, cek admin.
2. Header FOR UPDATE; harus draft.
3. Lepas reservasi asset lama (proses → tersedia).
4. Validasi asset baru (tersedia+gudang, tidak aktif di onboarding lain kecuali ini) & karyawan.
5. DELETE semua item lama → INSERT item baru (ID baru).
6. UPDATE header: tgl_onboarding hari ini, keterangan, karyawan, status draft/proses, reset ket_tolak, user_approval, tgl_approval.
7. UPDATE asset_data baru → proses.
8. Notifikasi onboarding.dikirim bila is_draft=false. Response 200 UPDATED.

21.3 Delete Draft — deleteOnboardingDraft

Lock → cek admin → header draft → asset proses → tersedia → DELETE item → DELETE header → 200 DELETED.

21.4 Konfirmasi — konfirmasiOnboardingKaryawan

1. Validasi request; ctx wajib ada (tidak perlu admin).
2. Lock; header milik karyawan login, FOR UPDATE, harus proses.
3. Karyawan harus aktif.
4. Tentukan item pending (pendingItemIds): - tgl_approval NULL → semua item aktif. - Sudah pernah → item aktif dengan status_item = belum_dicek (asset pengganti).
5. Validasi kelengkapan penilaian & alasan rusak.
6. UPDATE item status_item, ket_rusak.
7. Item rusak → UPDATE asset_data status_asset='rusak', id_pemegang_asset='', ket_rusak (hanya jika masih proses & gudang).
8. Hitung semuaNormal atas seluruh item aktif → status dikonfirmasi atau tetap proses.
9. UPDATE header status_approval, user_approval, tgl_approval = now, tgl_update, user_update.
10. Item normal ronde ini: lock asset_data; lewati jika sudah dipegang karyawan ini; selain itu wajib proses+gudang → UPDATE terpakai/karyawan/id_pemegang_asset; INSERT asset_trx_log per asset.
11. COMMIT; notifikasi onboarding.dikonfirmasi atau onboarding.rusak ke semua admin; response 200 UPDATED.

21.5 Ganti Asset Rusak — gantiAssetRusakOnboarding

1. Validasi, akses, lock, admin, header FOR UPDATE.
2. Syarat: proses, tgl_approval terisi, tidak ada item pending.
3. Asset pengganti unik; item rusak valid & belum diganti (FOR UPDATE).
4. Asset pengganti tersedia+gudang & tidak aktif di onboarding lain.
5. INSERT item pengganti (parent_id = item rusak, deskripsi_asset = kelengkapan, belum_dicek).
6. UPDATE asset_data pengganti → proses; UPDATE header (status_approval tetap proses, tgl_update, user_update).
7. Notifikasi onboarding.pengganti ke karyawan; response 200 UPDATED.

21.6 Query baca

• Options: karyawan aktif yang belum punya onboarding berstatus apa pun (kecuali transaksi exclude_onboarding_id); asset gudang yang tersedia (plus asset proses milik draft yang sedang diedit) dan tidak punya item belum_dicek di onboarding proses; kategori yang dipakai asset beserta seluruh parent-nya.
• List: JOIN item, COUNT item (termasuk pengganti) → jumlah_asset; urut tgl_input DESC; filter tab (§14).
• Detail: header + karyawan (cabang/divisi dari master) + item + flag turunan.

22Dampak terhadap asset_data

asset tersedia @gudang
      ↓ create onboarding
status_asset = proses (terkunci)
      ↓ karyawan konfirmasi
 ├─ Normal → status_asset = terpakai, pemegang_asset = karyawan, id_pemegang_asset = id_karyawan, + asset_trx_log
 └─ Rusak  → status_asset = rusak, tetap gudang, ket_rusak = alasan (tanpa asset_trx_log)

23API Documentation

Base path: ServerInfo.jwtBaseUrl + prefix modul asset/. Semua endpoint wajib Bearer JWT.

Endpoint approve/reject/selesai manual: ⚠️ Belum ditemukan.

Format response umum (ApiResponse):

{ "code": "SUCCESS", "message": "…", "data": { } }

24Detail Setiap API

Headers umum (dikirim mobile):

Authorization: Bearer <access_token>
Content-Type: application/json
Accept: application/json
locale: id
versi-app: <versi aplikasi>

Error umum untuk semua endpoint:

{ "code": "UNAUTHORIZED", "message": "Token telah expired." }
{ "code": "UNAUTHORIZED", "message": "Token tidak valid." }
{ "code": "FORBIDDEN", "message": "Pengguna tidak memiliki akses admin asset." }
{ "code": "SYSTEM_ERROR", "message": "Terjadi kesalahan saat …" }

API-001 — Opsi Onboarding

GET /asset/onboarding-karyawan/options?exclude_onboarding_id={id_draft}

Backend validation: exclude_onboarding_id nullable|string|max:50 → "Parameter opsi onboarding tidak valid." Database impact: SELECT saja.

Success (200):

{
  "code": "SUCCESS",
  "message": "Data opsi onboarding berhasil ditemukan.",
  "data": {
    "karyawan": [
      { "id_karyawan": "KRY0001", "nik": "EMP-001", "nama_karyawan": "Budi Contoh" }
    ],
    "kategori_asset": [
      { "id_asset_kategori_m": "CMP001202601001", "parent_id": "", "flag_parent": 1, "nama_kategori": "Elektronik" },
      { "id_asset_kategori_m": "CMP001202601002", "parent_id": "CMP001202601001", "flag_parent": 0, "nama_kategori": "Laptop" }
    ],
    "assets": [
      {
        "id_asset_data": "CMP00120260100001",
        "kode_asset": "LPT-0001",
        "nama_asset": "Laptop 14 inch",
        "id_asset_kategori_m": "CMP001202601002",
        "kategori_asset": "Laptop",
        "merek": "MerekX",
        "deskripsi": "Charger, tas",
        "kondisi_awal": "normal"
      }
    ]
  }
}

API-002 — Daftar Onboarding

GET /asset/onboarding-karyawan?tab=proses&limit=20&offset=0

Jika tidak ada satu pun parameter → response data berupa array seluruh onboarding (tanpa pagination). Mobile selalu mengirim tab.

Validation: tab.in "Filter onboarding asset tidak valid.", limit.max "Limit maksimal adalah 50 data." (message: "Parameter daftar onboarding asset tidak valid.")

Success (200, paginated):

{
  "code": "SUCCESS",
  "message": "Data onboarding asset karyawan berhasil ditemukan.",
  "data": {
    "filters": [
      { "value": "proses", "label": "Proses" },
      { "value": "dikonfirmasi", "label": "Dikonfirmasi" },
      { "value": "selesai", "label": "Selesai" }
    ],
    "onboardings": [
      {
        "id": "CMP001202609001",
        "no_trx": "KRY01-202609001",
        "tgl_onboarding": "2026-09-26",
        "keterangan": "Onboarding karyawan baru divisi IT",
        "ket_tolak": "",
        "id_karyawan": "KRY0001",
        "nik_karyawan": "EMP-001",
        "nama_karyawan": "Budi Contoh",
        "jumlah_asset": 2,
        "status_approval": "proses",
        "status_label": "Menunggu Diterima",
        "tab": "proses"
      }
    ],
    "pagination": { "limit": 20, "offset": 0, "next_offset": 1, "has_more": false }
  }
}

API-003 — Buat Onboarding

POST /asset/onboarding-karyawan

{
  "id_karyawan": "KRY0001",
  "asset_ids": ["CMP00120260100001", "CMP00120260100002"],
  "keterangan": "Onboarding karyawan baru divisi IT",
  "is_draft": false
}

Backend validation:

Process: §21.1. Database impact:

INSERT asset_trx_onboarding_karyawan
INSERT asset_trx_onboarding_karyawan_item (n baris)
UPDATE asset_data (status_asset = proses)
INSERT notif_data (jika bukan draft)

Success (201):

{
  "code": "CREATED",
  "message": "Onboarding asset berhasil dikirim ke karyawan.",
  "data": { "id": "CMP001202609001", "no_trx": "KRY01-202609001", "status_approval": "proses" }
}

Draft → message "Draft onboarding asset berhasil disimpan.", status_approval: "draft".

Error:

{ "code": "VALIDATION_ERROR", "message": "Data onboarding belum lengkap.",
  "errors": { "id_karyawan": ["Karyawan wajib dipilih."] } }

{ "code": "BUSINESS_RULE_VIOLATION", "message": "Satu atau beberapa asset tidak tersedia untuk onboarding." }

Pesan 422 lain: "Satu atau beberapa asset sedang diproses pada onboarding lain.", "Karyawan tidak ditemukan atau tidak aktif.", "Pengguna tidak terdaftar sebagai admin asset.", "Perusahaan tidak ditemukan.", "Nomor transaksi untuk periode ini sudah mencapai batas." 500: "Terjadi kesalahan saat menyimpan onboarding asset."

API-004 — Ubah / Publish Draft

PUT /asset/onboarding-karyawan/{id}

Body & validasi sama dengan API-003. Process: §21.2.

Database impact:

UPDATE asset_data (asset lama: proses → tersedia)
DELETE asset_trx_onboarding_karyawan_item (semua item draft)
INSERT asset_trx_onboarding_karyawan_item (item baru)
UPDATE asset_trx_onboarding_karyawan
UPDATE asset_data (asset baru → proses)
INSERT notif_data (jika publish)

Success (200):

{ "code": "UPDATED", "message": "Onboarding asset berhasil dipublish ke karyawan.",
  "data": { "id": "CMP001202609001", "no_trx": "KRY01-202609001", "status_approval": "proses" } }

Draft → "Draft onboarding asset berhasil diperbarui." Error 422: "Draft onboarding asset tidak ditemukan.", "Hanya onboarding berstatus draft yang dapat diubah.", + pesan API-003. 500: "Terjadi kesalahan saat memperbarui draft onboarding asset."

API-005 — Hapus Draft

DELETE /asset/onboarding-karyawan/{id}

Tanpa body. Database impact:

UPDATE asset_data (proses → tersedia)
DELETE asset_trx_onboarding_karyawan_item
DELETE asset_trx_onboarding_karyawan

Success (200):

{ "code": "DELETED", "message": "Draft onboarding asset berhasil dihapus.",
  "data": { "id": "CMP001202609001", "no_trx": "KRY01-202609001" } }

Error 422: "Draft onboarding asset tidak ditemukan.", "Hanya onboarding berstatus draft yang dapat dihapus." 500: "Terjadi kesalahan saat menghapus draft onboarding asset."

API-006 — Detail Onboarding (Admin)

GET /asset/onboarding-karyawan/{id}

Database impact: SELECT (header + data_karyawan + master_cabang + master_departemen + item + asset_data).

Success (200):

{
  "code": "SUCCESS",
  "message": "Detail onboarding asset berhasil ditemukan.",
  "data": {
    "id": "CMP001202609001",
    "no_trx": "KRY01-202609001",
    "tgl_onboarding": "2026-09-26",
    "keterangan": "Onboarding karyawan baru divisi IT",
    "status_approval": "proses",
    "status_label": "Isu Rusak",
    "tab": "dikonfirmasi",
    "isu_rusak": true,
    "karyawan": {
      "id_karyawan": "KRY0001",
      "nik": "EMP-001",
      "nama_karyawan": "Budi Contoh",
      "cabang": "Kantor Pusat",
      "divisi": "IT"
    },
    "items": [
      {
        "id_item": "CMP001202609001",
        "parent_id": "",
        "id_asset_data": "CMP00120260100001",
        "kode_asset": "LPT-0001",
        "nama_asset": "Laptop 14 inch",
        "kategori_asset": "Laptop",
        "kelengkapan": "Charger, tas",
        "status_item": "rusak",
        "ket_rusak": "Ada garis pada layar",
        "perlu_dicek": false,
        "diganti": false
      },
      {
        "id_item": "CMP001202609002",
        "parent_id": "",
        "id_asset_data": "CMP00120260100002",
        "kode_asset": "MSE-0001",
        "nama_asset": "Mouse Wireless",
        "kategori_asset": "Aksesoris",
        "kelengkapan": "",
        "status_item": "normal",
        "ket_rusak": "",
        "perlu_dicek": false,
        "diganti": false
      }
    ]
  }
}

API-007 — Ganti Asset Rusak

POST /asset/onboarding-karyawan/{id}/ganti-asset

{
  "items": [
    { "id_item": "CMP001202609001", "id_asset_data": "CMP00120260100003", "kelengkapan": "Charger, tas" }
  ]
}

Backend validation messages: "Minimal satu asset pengganti wajib dipilih.", "Asset rusak yang sama tidak boleh dikirim lebih dari sekali.", "Asset pengganti wajib dipilih.", "Asset pengganti yang sama tidak boleh dipilih lebih dari sekali.", "Kelengkapan asset pengganti wajib diisi." (message: "Data penggantian asset belum lengkap.")

Database impact:

INSERT asset_trx_onboarding_karyawan_item (parent_id = item rusak)
UPDATE asset_data (pengganti → proses)
UPDATE asset_trx_onboarding_karyawan (tgl_update, user_update)
INSERT notif_data

Success (200):

{ "code": "UPDATED", "message": "Asset pengganti berhasil dikirim ke karyawan.",
  "data": { "id": "CMP001202609001", "id_karyawan": "KRY0001", "no_trx": "KRY01-202609001",
            "status_approval": "proses", "jumlah_pengganti": 1 } }

Error 422: "Onboarding asset tidak ditemukan.", "Asset rusak hanya dapat diganti setelah karyawan selesai mengecek asset.", "Satu atau beberapa asset rusak tidak valid atau sudah diganti.", "Satu atau beberapa asset pengganti tidak tersedia.", "Satu atau beberapa asset pengganti sedang diproses pada onboarding lain." 500: "Terjadi kesalahan saat mengganti asset rusak."

API-008 — Asset Saya (Karyawan)

GET /asset/karyawan/onboarding

Response berisi data home Asset Saya; bagian onboarding:

{
  "code": "SUCCESS",
  "message": "Data asset karyawan berhasil ditemukan.",
  "data": {
    "jumlah_asset": 3,
    "onboarding": [
      { "id": "CMP001202609001", "no_trx": "KRY01-202609001", "tgl_onboarding": "2026-09-26",
        "jumlah_asset": 2, "status_approval": "proses", "status_label": "Menunggu Diterima" }
    ],
    "assets": [
      { "id": "CMP00120260100002", "nama_asset": "Mouse Wireless", "kode_asset": "MSE-0001", "merek": "MerekX", "kategori": "Aksesoris" }
    ],
    "penambahan": [], "kerusakan": [], "upgrade": [], "peminjaman": [], "retur": [],
    "jatuh_tempo": [], "peminjaman_aktif": []
  }
}

onboarding hanya berisi transaksi proses yang masih perlu dicek. assets = asset dengan pemegang karyawan ini (bukan dipinjam).

API-009 — Detail Onboarding (Karyawan)

GET /asset/karyawan/onboarding/{id}

Sama dengan API-006, kecuali karyawan tanpa id_karyawan, dan hanya transaksi milik user login yang bukan draft. 404 "Onboarding asset tidak ditemukan."

API-010 — Konfirmasi Onboarding (Karyawan)

POST /asset/karyawan/onboarding/{id}/konfirmasi

{
  "items": [
    { "id_item": "CMP001202609001", "status_item": "rusak", "ket_rusak": "Ada garis pada layar" },
    { "id_item": "CMP001202609002", "status_item": "normal" }
  ]
}

(message: "Data konfirmasi asset belum lengkap.")

Database impact:

UPDATE asset_trx_onboarding_karyawan_item (status_item, ket_rusak)
UPDATE asset_data (rusak → status rusak)
UPDATE asset_trx_onboarding_karyawan (status_approval, user_approval, tgl_approval)
UPDATE asset_data (normal → terpakai, pemegang karyawan)
INSERT asset_trx_log (per asset normal)
INSERT notif_data (semua admin asset)

Success (200):

{ "code": "UPDATED", "message": "Laporan kerusakan asset berhasil dikirim ke admin.",
  "data": { "id": "CMP001202609001", "no_trx": "KRY01-202609001",
            "status_approval": "proses", "status_label": "Isu Rusak", "tab": "dikonfirmasi" } }

Semua normal → message "Asset berhasil dikonfirmasi.", status_approval: "dikonfirmasi", status_label: "Selesai", tab: "selesai". Error 422: "Onboarding asset tidak ditemukan.", "Onboarding asset sudah tidak menunggu konfirmasi.", "Karyawan tidak ditemukan atau tidak aktif.", "Tidak ada asset yang perlu dicek. Asset rusak sedang menunggu penggantian dari admin.", "Seluruh asset pada onboarding wajib dicek.", "Alasan kerusakan wajib diisi.", "Satu atau beberapa asset pada onboarding tidak ditemukan.", "Satu atau beberapa asset pada onboarding tidak dapat diserahkan." 500: "Terjadi kesalahan saat mengonfirmasi asset."

API-011 — Detail Asset Milik Karyawan

GET /asset/karyawan/data/{id}

Dipanggil dari daftar Asset Saya untuk melihat satu asset. {id} adalah id_asset_data. Model: AssetAdmin_m::getAssetDetailPemegang (memakai kueri daftar asset admin dengan filter pemegang_asset = karyawan dan id_pemegang_asset = ctx.id_karyawan; asset berstatus disposed tidak ikut).

Respons memuat identitas asset (kode_asset, nama_asset, kategori, merek, deskripsi, kondisi awal, status_asset, lokasi), data garansi (flag_garansi, tanggal garansi, vendor_garansi, no_dokumen_garansi), dan atribut[] komponen. Data keuangan dan siapa yang mendaftarkan dikosongkan di sisi API: didaftarkan_oleh, vendor_pembelian, tgl_perolehan, sumber_perolehan (string kosong) serta harga_perolehan, masa_penyusutan, nilai_residu, penyusutan_tahunan (0). Pengosongan memakai daftar kolom tetap, sehingga kolom baru pada daftar admin perlu ditinjau agar tidak ikut terkirim ke karyawan.

404 "Asset tidak ditemukan." bila asset bukan (atau tidak lagi) milik pemanggil.

25Mobile Architecture

Page (StatefulWidget + BlocConsumer/BlocBuilder)
  ↓ event
Bloc (flutter_bloc)
  ↓
Api Service (AssetOnboardingApi / AssetSayaApi)   ← berperan sebagai repository
  ↓
ApiClient (Dio + _JwtAuthInterceptor)  → ApiResult
  ↓
Backend

Routes:

/asset_admin_detail_onboarding dan /asset_konfirmasi_onboarding termasuk assetNotifRoutes (dibuka dari notifikasi dengan id_ref).

26Mobile Screen

26.1 List On Boarding (Admin) — title "On Boarding Asset"

• Data tampil per kartu: No transaksi (no_trx), "Tanggal On Boarding", badge status, nik - nama karyawan, "{jumlah} Asset".
• Filter/tab: Proses, Dikonfirmasi, Selesai (label dari API filters, fallback i18n).
• Search: ⚠️ Belum ditemukan (tidak ada pencarian di list).
• Status badge: Menunggu Diterima (oranye), Draft (biru), Ditolak (merah), Isu Rusak (merah), Selesai (hijau).
• Action: + (Tambah onboarding); kartu draft: Hapus (dialog konfirmasi) & Lanjutkan Draft; tap kartu non-draft → Detail. Infinite scroll & pull-to-refresh.

26.2 Form On Boarding (Tambah / Edit Draft) — title "On Boarding Asset"

26.3 Detail On Boarding (Admin) — title "Detail On Boarding"

• Kartu info: Tanggal On Boarding, badge status, Kode On Boarding.
• Data Karyawan: nama, NIK, Cabang, Divisi.
• Asset On Boarding: tiap item utama: nama, kategori • kode, Kelengkapan, Kondisi (Menunggu Diterima / Normal / Rusak), Report Kerusakan (jika rusak), dan box Asset Pengganti bersarang.
• Tombol bawah: Draft → "Simpan Draft" (membuka form edit); Isu Rusak → "Ganti Asset Yang Rusak".
• Catatan tambahan tidak ditampilkan di detail admin.

Alur status: AssetAlurStepper.onboarding (Draft → Diserahkan → Konfirmasi → Selesai; disembunyikan bila ditolak). Layar Konfirmasi Asset Baru karyawan (§26.5) adalah form pemeriksaan, bukan halaman detail, sehingga tidak memakai stepper. File: Shared/Widgets/AssetAlurWidgets.dart.

26.4 Ganti Asset Rusak (Admin) — title "Ganti Asset Rusak"

• Data Karyawan; section "Penggantian Asset yang Rusak".
• Per item rusak yang belum diganti: info asset, Kondisi Rusak, Report Kerusakan, tombol Ganti Asset → picker asset (asset yang sudah dipilih untuk item lain disembunyikan). Pilihan tampil sebagai box pengganti (bisa dihapus).
• Kelengkapan pengganti otomatis = deskripsi asset (tidak dapat diedit).
• Info: "Asset yang rusak akan dikembalikan ke gudang dengan status "Rusak"."
• Tombol Submit ke Karyawan (nonaktif, berlabel "Submit", bila belum ada pilihan).

26.5 Konfirmasi Asset Baru (Karyawan) — title "Konfirmasi Asset Baru"

• Info onboarding (tanggal, status, kode), Data Karyawan, Catatan Tambahan.
• Peringatan: "Penting! Periksa kondisi asset dengan teliti sebelum menerima."
• Per asset: nama, kategori • kode, Kelengkapan, pilihan Normal / Rusak (hanya item perlu_dicek; item lain read-only), field Report Kerusakan * jika Rusak (hint "Contoh: Ada garis pada layar", maks 255).
• Pernyataan: "Dengan menerima asset ini, saya menyatakan telah memeriksa kondisi dan bertanggung jawab atas asset tersebut."
• Tombol Konfirmasi Asset.

26.6 Asset Saya (Karyawan)

Banner "On Boarding Asset" – "Cek dan konfirmasi asset yang Anda terima." per onboarding pending → membuka Konfirmasi Asset Baru.

26.7 Approval

⚠️ Belum ditemukan.

27Mobile → API

Bottom sheet Pilih Karyawan → _selectedEmployee.idKaryawan → AssetOnboardingRequest.idKaryawan → "id_karyawan" → $request->input('id_karyawan') → asset_trx_onboarding_karyawan.id_karyawan

28API → Mobile

29Mapping Mobile → API → Database

30Mapping Database → API → Mobile

31Validation

31.1 Mobile Validation

31.2 Backend Validation

Lihat tabel per API di §24 dan Business Rules §9.

31.3 Database Constraint

31.4 Ringkasan per Field

32Error Handling

Backend: InvalidArgumentException → 422 BUSINESS_RULE_VIOLATION (pesan exception). Throwable → Log::error + 500 SYSTEM_ERROR (pesan generik). Transaksi DB otomatis rollback.

Mobile: ApiClient membaca body error server bila ada; timeout/koneksi → "Tidak dapat terhubung ke server. Periksa koneksi Anda."; selain itu "Terjadi kesalahan tidak terduga." 401 → refresh token sekali lalu retry.

33Audit Trail

34Notification

Kelas: App\Support\Asset\AssetNotification::send(event, id_company, id_trx) — dipanggil controller setelah transaksi DB sukses. Kegagalan hanya di-log.

Mekanisme: INSERT notif_data (jenis='asset', id_ref = id onboarding, rute, ket_notif_id/en, flag_baca='0') di dalam transaksi terpisah (lock master_company), lalu push FCM ke users.token_fcm sesuai users.lang. Di mobile, tap notifikasi → tandai dibaca → pushNamed('/'+rute, arguments: id_ref).

35Security

36Manual Book User/Admin

A. Admin Asset

1. Membuka Menu

1. Login aplikasi.
2. Buka Asset Management → halaman admin Asset Karyawan.
3. Pada panel aksi, pilih On Board. Halaman On Boarding Asset tampil dengan tab Proses, Dikonfirmasi, Selesai.

2. Membuat Onboarding

1. Tekan tombol + di kanan atas.
2. Ketuk Pilih Karyawan, cari lalu pilih karyawan penerima. Karyawan yang masih memiliki onboarding berjalan/draft tidak muncul.
3. Ketuk Tambah Asset → pilih kategori → pilih asset. Ulangi untuk asset lainnya. Hapus asset dengan ikon hapus pada kartunya.
4. Isi Catatan Tambahan.
5. Tekan: - Simpan Draft — menyimpan tanpa mengirim ke karyawan (catatan boleh kosong), atau - Submit ke Karyawan — mengirim onboarding dan notifikasi ke karyawan.
6. Muncul pesan berhasil, kembali ke daftar.

3. Melanjutkan / Menghapus Draft

1. Tab Proses → kartu berstatus Draft.
2. Lanjutkan Draft untuk mengubah karyawan/asset/catatan, lalu Simpan Draft atau Publish ke Karyawan.
3. Hapus → konfirmasi Hapus. Draft terhapus permanen dan asset kembali tersedia.

4. Melihat Detail

1. Ketuk kartu onboarding (selain draft).
2. Halaman Detail On Boarding menampilkan tanggal, status, kode, data karyawan, dan daftar asset beserta kondisinya (Menunggu Diterima, Normal, Rusak + Report Kerusakan), termasuk asset pengganti.

5. Approval

Tidak ada proses approval. Onboarding langsung dikirim ke karyawan.

6. Mengganti Asset Rusak

1. Onboarding berstatus Isu Rusak muncul di tab Dikonfirmasi (juga mendapat notifikasi "Laporan Asset Rusak").
2. Buka detail → tekan Ganti Asset Yang Rusak.
3. Pada tiap asset rusak tekan Ganti Asset → pilih asset pengganti.
4. Tekan Submit ke Karyawan. Karyawan akan mendapat notifikasi "Asset Pengganti".
5. Asset rusak tetap di gudang dengan status Rusak.

7. Menyelesaikan Onboarding

Tidak ada tombol selesai. Onboarding otomatis pindah ke tab Selesai ketika karyawan menyatakan seluruh asset (termasuk pengganti) Normal.

B. Karyawan

1. Membuka Onboarding

1. Buka notifikasi Onboarding Asset Baru / Asset Pengganti, atau
2. Buka Asset Saya → banner On Boarding Asset ("Cek dan konfirmasi asset yang Anda terima.").

2. Serah Terima / Konfirmasi

1. Halaman Konfirmasi Asset Baru menampilkan data onboarding, data Anda, catatan tambahan, dan daftar asset.
2. Periksa fisik setiap asset dan kelengkapannya.
3. Pilih Normal atau Rusak. Jika Rusak, isi Report Kerusakan (contoh: "Ada garis pada layar").
4. Baca pernyataan tanggung jawab, lalu tekan Konfirmasi Asset.
5. Asset Normal langsung tercatat sebagai asset Anda. Asset Rusak dilaporkan ke admin untuk diganti; Anda akan diminta mengecek asset penggantinya nanti.

37Kondisi Button

38Testing Scenario

Happy Path

Validation

Status

Asset

API / Security

Network / Concurrency

39Temuan Ketidaksesuaian

40Edge Case

41Potential Bug / Technical Risk

RISK-001 — Penggantian gagal bila deskripsi asset kosong

Lokasi: HalamanAssetAdminGantiRusak._pilihPengganti (kelengkapan: asset.deskripsi) ↔ AssetAdminOnboarding_c::gantiAssetRusakOnboarding (items.*.kelengkapan required). Masalah: Kelengkapan otomatis dari deskripsi; tidak ada input manual. Kondisi: asset_data.deskripsi kosong. Impact: 422, admin tidak bisa mengganti asset tersebut. Current Handling: Snackbar error. Recommendation: Tambah field kelengkapan editable atau jadikan nullable.

RISK-002 — Tidak ada pembatalan onboarding berjalan

Lokasi: Route & model (hanya delete draft). Masalah: Onboarding proses tidak bisa dibatalkan/ditarik. Kondisi: Karyawan batal masuk/nonaktif, asset berubah. Impact: Asset tertahan status_asset = proses tanpa jalan keluar di aplikasi. Current Handling: Tidak ada (perlu intervensi DB). Recommendation: Endpoint batal yang melepas reservasi.

RISK-003 — Duplikasi onboarding per karyawan (SUDAH DIPERBAIKI)

Lokasi: storeOnboardingKaryawan, updateOnboardingDraft. Status: assertKaryawanBelumPernahOnboarding kini memvalidasi di model dalam transaksi (lihat BR-020). Catatan: aturannya lebih ketat daripada "satu aktif", yaitu satu onboarding per karyawan seumur hidup, sehingga karyawan yang pernah dikonfirmasi tidak bisa diberi onboarding kedua.

RISK-004 — Kapasitas penomoran 3 digit

Lokasi: nextSequence/ensureSequenceCapacity (header & item). Masalah: Maks 999 per company per bulan; item dipakai bersama semua onboarding + pengganti, dan edit draft menghabiskan sequence (delete+insert ID baru). Impact: Transaksi ditolak di akhir bulan bagi company besar. Recommendation: Perbesar digit / sequence table.

RISK-005 — Lock tingkat company

Lokasi: lockCompany. Masalah: Semua transaksi asset satu company diserialkan (juga notifikasi). Impact: Antrian/latensi saat beban tinggi. Recommendation: Pantau; pertimbangkan lock lebih granular.

RISK-006 — Notifikasi di luar transaksi utama

Lokasi: Controller → AssetNotification::send. Masalah: Gagal notif hanya di-log. Impact: Penerima tidak tahu ada onboarding. Recommendation: Queue/retry; banner Asset Saya sebagai fallback sudah ada.

RISK-007 — Status ditolak tanpa implementasi

Lihat INC-01. Query list/options tetap memperhitungkannya.

RISK-008 — Audit item & asset rusak tidak lengkap

Lokasi: Tabel item (tanpa kolom update), konfirmasi item rusak (tanpa asset_trx_log). Impact: Sulit menelusuri siapa/kapan item dinilai rusak (hanya user_approval terakhir). Recommendation: Tambah log/histori.

RISK-009 — Kode HTTP & urutan cek akses tidak konsisten

Lihat INC-12, INC-13.

RISK-010 — Potensi query lambat

Lokasi: hasActiveOnboardingAsset, subquery NOT EXISTS ... parent_id, options asset. Masalah: Filter atoki.id_asset_data dan pengganti.parent_id tidak diawali kolom index yang ada. Impact: Lambat jika data item besar. ⚠️ Asumsi: belum diukur dengan EXPLAIN. Recommendation: Index (id_company, id_asset_data) dan (id_company, parent_id) setelah verifikasi EXPLAIN.

RISK-011 — Hard delete draft

Tidak ada jejak draft yang dihapus.

42Dependency

Master Company (lock, isolasi)
      ↓
Data Karyawan (aktif) ── Asset Admin (hak akses)
      ↓
Master Kategori → Asset Data (tersedia @gudang)
      ↓
Asset Onboarding (header + item)  ──► Notifikasi (notif_data + FCM, users.token_fcm)
      ↓ konfirmasi karyawan
Asset Data (terpakai, pemegang karyawan) ──► Asset Log (onboarding_karyawan)
      ↓
Modul lain yang bergantung:
  - Peminjaman & Penambahan/Request: menolak asset yang aktif di onboarding
  - Offboarding: menelusuri sumber asset karyawan (asset_trx_log / onboarding dikonfirmasi) → jenis "onboarding"
  - Asset Saya: daftar asset & banner onboarding

43Source Code Reference

API (Lumen)
├── routes/web.php, routes/modules/asset/{RouteAsset.php,_config.php}
├── config/route_middleware.php
├── app/Http/Middleware/{JwtAuth.php,ResolveContext.php}
├── app/Http/Controllers/{BaseController.php, Asset/Asset_c.php, Asset/Admin/AssetAdminOnboarding_c.php, Asset/Karyawan/AssetKaryawanOnboarding_c.php}
├── app/Models/Asset/{Asset_m.php, AssetAdmin_m.php, AssetKaryawan_m.php, OnboardingStatus.php}
├── app/Libraries/ApiResponse.php
├── app/Support/Asset/AssetNotification.php
├── diagram-asset.dbml
└── database/migrations/2026_09_14_000002, 2026_09_17_000005, 2026_09_17_000007, 2026_09_18_000011

MOBILE (Flutter)
├── lib/UI/Modul/Asset/AssetAdmin/AssetAdminKaryawan/{HalamanAssetAdminKaryawan.dart, onboarding/*.dart}
├── lib/UI/Modul/Asset/{Shared/Widgets/AssetCommonWidgets.dart, AssetSaya/HalamanAssetSaya.dart, MOBILE/lib/UI/Modul/Asset/AssetSaya/Onboarding/HalamanKonfirmasiAssetBaru.dart}
├── lib/UI/Modul/Notif/KomponenNotif.dart
├── lib/Bloc/Asset/{AssetOnboardingBloc, AssetOnboardingDetailBloc, AssetGantiRusakBloc, AssetKonfirmasiOnboardingBloc}.dart
├── lib/Bloc/NavigatorBloc.dart, lib/Setting/router.dart
├── lib/Repository/Service/{assetOnboardingApi.dart, assetSayaApi.dart, apiClient.dart, apiResult.dart}
├── lib/Repository/Model/{mAssetOnboarding.dart, mAssetSaya.dart, PageModel/mAssetPage.dart}
└── assets/{id,en}/asset.json

44Developer Notes

• Generate ID: nextSequence(table, column, id_company, YYYYMM, digits) mengambil ID terbesar LIKE id_company+YYYYMM% dengan FOR UPDATE, +1. Harus dipanggil di dalam transaksi setelah lockCompany. Header/item 3 digit, log & notif 5 digit.
• Nomor transaksi: KRY01- + YYYYMM + 3 digit (urutan sama dengan ID header). Unik hanya per company.
• Enum: gunakan OnboardingStatus::X->value (PHP) dan AssetOnboardingApproval (Dart). Jangan pakai konstanta int Asset_m::STATUS_*.
• Status turunan dihitung, bukan disimpan: status_label, tab, isu_rusak, perlu_dicek, diganti → Asset_m::statusMetadata, pendingItemIds, wherePerluDicek, applyOnboardingTabFilter. Logika SQL (wherePerluDicek) dan PHP (pendingItemIds) harus tetap sinkron.
• tgl_approval sebagai penanda ronde: NULL = ronde pertama (semua item aktif dicek); terisi = hanya item belum_dicek aktif (pengganti).
• Pohon item: item aktif = tidak dirujuk parent_id. Pengganti dapat bersarang. Mobile merender rekursif.
• Snapshot: nama/NIK karyawan di header; nama/deskripsi/kategori asset di item — perubahan master tidak mengubah transaksi.
• Reservasi draft: asset draft berstatus proses (migration data 2026_09_18_000011). Saat mengedit draft, options harus dipanggil dengan exclude_onboarding_id.
• Relasi tanpa FK pasti: semua JOIN menyertakan id_company; pertahankan pola ini.
• Side effect lintas modul: hasActiveOnboardingAsset dipakai Peminjaman & Request; Offboarding membaca onboarding dikonfirmasi.
• Notifikasi: tambah event baru di AssetNotification::EVENTS; rute tujuan harus terdaftar di assetNotifRoutes mobile dan menerima argumen String id.
• Response: gunakan ApiResponse; InvalidArgumentException untuk pelanggaran aturan bisnis.
• Legacy/technical debt: status ditolak/ket_tolak, HalamanAssetAdminPilihPengganti, teks hardcode form, konstanta int status.

45End-to-End Traceability

45.1 Tracing karyawan

Admin memilih karyawan di bottom sheet "Pilih Karyawan"
       ↓
_HalamanAssetAdminAddOnboardingKaryawanState._selectedEmployee (AssetOnboardingEmployee)
       ↓
AssetOnboardingRequest.idKaryawan
       ↓
JSON: "id_karyawan": "KRY0001"   (POST /asset/onboarding-karyawan)
       ↓
AssetAdminOnboarding_c::storeOnboardingKaryawan → validasi required|max:150
       ↓
AssetAdmin_m::storeOnboardingKaryawan → Asset_m::findActiveKaryawan (data_karyawan aktif)
       ↓
asset_trx_onboarding_karyawan.id_karyawan / nik_karyawan / nama_karyawan

45.2 Tracing asset

Admin memilih asset (Tambah Asset → kategori → asset)
       ↓
_selectedAssets[].idAssetData → AssetOnboardingRequest.assetIds
       ↓
JSON: "asset_ids": ["CMP00120260100001"]
       ↓
Asset_m::getLockedAssets (tersedia @gudang, FOR UPDATE) + hasActiveOnboardingAsset
       ↓
INSERT asset_trx_onboarding_karyawan_item (id_asset_data, status_item = belum_dicek)
UPDATE asset_data.status_asset = 'proses'
       ↓
Karyawan memilih "Normal" → _statusByItem[id_item] = 'normal'
       ↓
JSON: {"items":[{"id_item":"CMP001202609001","status_item":"normal"}]}
       ↓
AssetKaryawan_m::konfirmasiOnboardingKaryawan
       ↓
UPDATE asset_trx_onboarding_karyawan_item.status_item = 'normal'
UPDATE asset_data: status_asset = 'terpakai', pemegang_asset = 'karyawan', id_pemegang_asset = 'KRY0001'
INSERT asset_trx_log (jenis_log = onboarding_karyawan, posisi gudang → karyawan)
       ↓
Asset menjadi milik (dipegang) karyawan → tampil di Asset Saya (API-008 assets[])

45.3 Tracing balik (DB → UI)

asset_trx_onboarding_karyawan_item.deskripsi_asset
   ↓ Asset_m::onboardingDetail
API: items[].kelengkapan
   ↓ AssetOnboardingKaryawanItem.kelengkapan
UI: "Kelengkapan" pada Detail / Konfirmasi Asset Baru

45.4 Walkthrough Lengkap dengan Contoh Data

Bagian ini mengikuti satu transaksi dari awal sampai selesai, langkah demi langkah: apa yang dilakukan pengguna di mobile, apa yang dikirim, apa yang diproses API, dan apa yang tersimpan di database. Semua data di bawah ini sintetis, tetapi format ID, nama kolom, urutan proses, dan pesan diambil dari kode (AssetAdmin_m, AssetKaryawan_m, Asset_m, AssetNotification).

Skenario: Admin Asset menyerahkan laptop dan mouse kepada karyawan baru. Karyawan menemukan laptop rusak, admin menggantinya, lalu karyawan menerima pengganti sehingga onboarding selesai.

Data awal (sebelum langkah 0)

Company CMP001. Tanggal kejadian 22 Oktober 2026, sehingga periode ID adalah 202610. Belum ada onboarding, log, atau notifikasi pada periode ini.

data_karyawan

KRY0099 dan KRY0100 terdaftar di asset_admin untuk CMP001.

asset_data

Singkatan pada tabel berikutnya: A1 = …00001 (laptop pertama), A2 = …00002 (mouse), A3 = …00003 (laptop pengganti).

Langkah 0 — Admin membuka form, mobile memuat opsi

Mobile - Route /asset_admin_add_onboarding_karyawan → AssetOnboardingBloc menerima LoadAssetOnboardingOptions. - AssetOnboardingApi.getOptions() memanggil API tanpa exclude_onboarding_id (form baru, bukan edit draft).

Dikirim

GET /asset/onboarding-karyawan/options
Authorization: Bearer <access_token_admin>

Diproses API 1. JwtAuth memvalidasi token, ResolveContext membentuk ctx (id_karyawan = KRY0099, id_company = CMP001). 2. accessError() memastikan KRY0099 ada di asset_admin. 3. AssetAdmin_m::getOnboardingOptions: - karyawan aktif yang belum pernah punya baris onboarding apa pun (semua status, lihat BR-020) → KRY0001 lolos; - asset tersedia di gudang dan tidak punya item belum_dicek pada onboarding proses → A1, A2, A3; - kategori yang dipakai asset beserta parent-nya.

Database: hanya SELECT, tidak ada perubahan data.

Diterima mobile (ringkas, lengkap di API-001)

{
  "code": "SUCCESS",
  "message": "Data opsi onboarding berhasil ditemukan.",
  "data": {
    "karyawan": [ { "id_karyawan": "KRY0001", "nik": "EMP-001", "nama_karyawan": "Budi Contoh" } ],
    "kategori_asset": [
      { "id_asset_kategori_m": "CMP001202601001", "parent_id": "", "flag_parent": 1, "nama_kategori": "Elektronik" },
      { "id_asset_kategori_m": "CMP001202601002", "parent_id": "CMP001202601001", "flag_parent": 0, "nama_kategori": "Laptop" }
    ],
    "assets": [
      { "id_asset_data": "CMP00120260100001", "kode_asset": "LPT-0001", "nama_asset": "Laptop 14 inch",
        "id_asset_kategori_m": "CMP001202601002", "kategori_asset": "Laptop", "merek": "MerekX",
        "deskripsi": "Charger, tas", "kondisi_awal": "normal" }
    ]
  }
}

Mobile memetakan ke AssetOnboardingEmployee, AssetOnboardingCategory, AssetOnboardingAsset; hasilnya muncul di bottom sheet Pilih Karyawan dan pohon kategori Tambah Asset.

Langkah 1 — Admin menyimpan draft (1 asset)

Mobile - Admin memilih Budi Contoh, menambah Laptop 14 inch (LPT-0001), mengisi Catatan Tambahan, menekan Simpan Draft. - Bloc: SubmitAssetOnboarding(isDraft: true) → AssetOnboardingApi.store(AssetOnboardingRequest) → request.toJson().

Dikirim

POST /asset/onboarding-karyawan
Authorization: Bearer <access_token_admin>
Content-Type: application/json

{
  "id_karyawan": "KRY0001",
  "asset_ids": ["CMP00120260100001"],
  "keterangan": "Onboarding karyawan baru divisi IT",
  "is_draft": true
}

Diproses API (AssetAdminOnboarding_c::storeOnboardingKaryawan → AssetAdmin_m::storeOnboardingKaryawan, satu DB::transaction) 1. Validasi request: id_karyawan wajib, asset_ids minimal 1 dan unik, is_draft boolean. keterangan boleh kosong karena draft. 2. accessError(): pengguna harus admin asset. 3. lockCompany("CMP001") → SELECT … FOR UPDATE pada master_company, transaksi asset company ini diserialkan. 4. getLockedAssets: A1 harus tersedia + gudang; jumlah hasil harus sama dengan jumlah asset_ids. 5. hasActiveOnboardingAsset: A1 tidak boleh ada di onboarding lain yang masih aktif. 6. findActiveKaryawan("KRY0001") → ditemukan dan aktif. 7. assertKaryawanBelumPernahOnboarding: belum ada baris onboarding untuk KRY0001 → lolos. 8. findAssetAdmin("KRY0099") → user_input = "ADM-001 - Siti Admin". 9. nextSequence header: belum ada ID berawalan CMP001202610 → urutan 1 → id = CMP001202610001, no_trx = KRY01-202610001. 10. INSERT header (status draft), nextSequence item → 1, INSERT item per asset, UPDATE asset_data → proses. 11. Karena is_draft = true, controller tidak mengirim notifikasi.

Hasil database

asset_trx_onboarding_karyawan

asset_trx_onboarding_karyawan_item

asset_data: A1 status_asset tersedia → proses, tgl_update = 09:00:00, user_update = ADM-001 - Siti Admin. A2 dan A3 tidak berubah.

Diterima mobile (HTTP 201)

{
  "code": "CREATED",
  "message": "Draft onboarding asset berhasil disimpan.",
  "data": { "id": "CMP001202610001", "no_trx": "KRY01-202610001", "status_approval": "draft" }
}

Mobile menampilkan message sebagai snackbar dan kembali ke list; kartu draft muncul di tab Proses dengan badge Draft.

Langkah 2 — Admin melanjutkan draft, menambah mouse, lalu publish

Mobile - Admin menekan Lanjutkan Draft → route /asset_admin_add_onboarding_karyawan dengan draftId = CMP001202610001. - Bloc: LoadAssetOnboardingDraft(id) memanggil dua endpoint: options dengan ?exclude_onboarding_id=CMP001202610001 (supaya A1 yang sedang proses milik draft ini tetap muncul), dan detail GET /asset/onboarding-karyawan/CMP001202610001 untuk mengisi form. - Admin menambah Mouse Wireless, menekan Publish ke Karyawan → UpdateAssetOnboardingDraft → AssetOnboardingApi.updateDraft(id, request).

Dikirim

PUT /asset/onboarding-karyawan/CMP001202610001

{
  "id_karyawan": "KRY0001",
  "asset_ids": ["CMP00120260100001", "CMP00120260100002"],
  "keterangan": "Onboarding karyawan baru divisi IT",
  "is_draft": false
}

keterangan kini wajib karena is_draft = false.

Diproses API (AssetAdmin_m::updateOnboardingDraft) 1. Validasi dan cek admin seperti langkah 1; lockCompany. 2. Header dikunci FOR UPDATE, harus berstatus draft. 3. Asset lama (A1) yang masih proses dikembalikan ke tersedia (melepas reservasi). 4. Validasi asset baru: A1 dan A2 tersedia + gudang, tidak aktif di onboarding lain (draft ini dikecualikan). 5. Karyawan dicek aktif; assertKaryawanBelumPernahOnboarding dijalankan dengan pengecualian ID transaksi ini sendiri, sehingga draft tidak menolak dirinya. 6. nextSequence item dihitung sebelum item lama dihapus: ID terakhir …001 → mulai dari 2. Karena itu item tidak memakai ulang …001. 7. DELETE semua item lama, INSERT item baru. 8. UPDATE header: tgl_onboarding hari ini, keterangan, data karyawan, status_approval = proses, user_approval = '', tgl_approval = NULL, tgl_update, user_update. 9. UPDATE asset_data A1 dan A2 → proses. 10. Commit. Controller memanggil AssetNotification::send('onboarding.dikirim', 'CMP001', 'CMP001202610001').

Notifikasi (AssetNotification::send, dijalankan setelah commit) - Penerima: karyawan pemilik transaksi (KRY0001). - INSERT notif_data, lalu push FCM bila users.token_fcm terisi.

Hasil database

Header asset_trx_onboarding_karyawan (kolom yang berubah)

Item: baris CMP001202610001 dihapus, diganti dua baris baru:

(Urutan penomoran mengikuti urutan hasil query asset, yang tidak memakai ORDER BY; penomoran bisa tertukar.)

asset_data: A1 tersedia → proses lalu tetap proses; A2 tersedia → proses.

notif_data (1 baris)

Diterima mobile (HTTP 200)

{
  "code": "UPDATED",
  "message": "Onboarding asset berhasil dipublish ke karyawan.",
  "data": { "id": "CMP001202610001", "no_trx": "KRY01-202610001", "status_approval": "proses" }
}

Kartu pindah dari Draft ke Menunggu Diterima di list admin.

Langkah 3 — Karyawan membuka notifikasi dan melihat detail

Mobile - Push FCM dengan route /asset_konfirmasi_onboarding dan id_ref = CMP001202610001 (atau banner On Boarding Asset di Asset Saya, API-008). - AssetKonfirmasiOnboardingBloc menerima LoadAssetKonfirmasiOnboarding(id) → AssetSayaApi.getOnboardingDetail(id).

Dikirim

GET /asset/karyawan/onboarding/CMP001202610001
Authorization: Bearer <access_token_budi>

Diproses API (AssetKaryawan_m::getDetailOnboardingSaya) 1. ctx.id_karyawan = KRY0001. 2. Header dicari dengan id_karyawan = KRY0001 dan bukan draft; transaksi milik orang lain atau draft menghasilkan 404. 3. Item dibaca. perlu_dicek dihitung oleh pendingItemIds: karena tgl_approval masih NULL, semua item aktif perlu dicek.

Database: hanya SELECT.

Diterima mobile (data, ringkas)

{
  "id": "CMP001202610001",
  "no_trx": "KRY01-202610001",
  "tgl_onboarding": "2026-10-22",
  "keterangan": "Onboarding karyawan baru divisi IT",
  "status_approval": "proses",
  "status_label": "Menunggu Diterima",
  "tab": "proses",
  "isu_rusak": false,
  "karyawan": { "nik": "EMP-001", "nama_karyawan": "Budi Contoh", "cabang": "Kantor Pusat", "divisi": "IT" },
  "items": [
    { "id_item": "CMP001202610002", "parent_id": "", "id_asset_data": "CMP00120260100001", "kode_asset": "LPT-0001",
      "nama_asset": "Laptop 14 inch", "kategori_asset": "Laptop", "kelengkapan": "Charger, tas",
      "status_item": "belum_dicek", "ket_rusak": "", "perlu_dicek": true, "diganti": false },
    { "id_item": "CMP001202610003", "parent_id": "", "id_asset_data": "CMP00120260100002", "kode_asset": "MSE-0001",
      "nama_asset": "Mouse Wireless", "kategori_asset": "Aksesoris", "kelengkapan": "",
      "status_item": "belum_dicek", "ket_rusak": "", "perlu_dicek": true, "diganti": false }
  ]
}

Layar Konfirmasi Asset Baru menampilkan kedua item dengan pilihan Normal / Rusak karena perlu_dicek = true.

Langkah 4 — Karyawan mengonfirmasi: laptop rusak, mouse normal

Mobile - Karyawan memilih Rusak pada laptop dan mengetik "Ada garis pada layar" (maks 255 karakter), memilih Normal pada mouse. - Validasi mobile: semua item perlu_dicek harus dinilai, alasan wajib bila Rusak. - SubmitAssetKonfirmasiOnboarding → AssetSayaApi.konfirmasiOnboarding(id, AssetKonfirmasiOnboardingRequest). ket_rusak hanya dikirim untuk item rusak.

Dikirim

POST /asset/karyawan/onboarding/CMP001202610001/konfirmasi

{
  "items": [
    { "id_item": "CMP001202610002", "status_item": "rusak", "ket_rusak": "Ada garis pada layar" },
    { "id_item": "CMP001202610003", "status_item": "normal" }
  ]
}

Diproses API (AssetKaryawanOnboarding_c::konfirmasiOnboardingSaya → AssetKaryawan_m::konfirmasiOnboardingKaryawan, satu transaksi) 1. Validasi: items wajib; id_item unik; status_item hanya normal atau rusak; ket_rusak wajib bila rusak. 2. lockCompany; header diambil dengan id_karyawan = KRY0001 + FOR UPDATE, harus berstatus proses. 3. Karyawan harus aktif. 4. Item yang perlu dinilai (pendingItemIds, tgl_approval NULL → semua item aktif): …002 dan …003. Jumlah dan ID item yang dikirim harus sama persis ("Seluruh asset pada onboarding wajib dicek."). 5. Item rusak tanpa alasan ditolak ("Alasan kerusakan wajib diisi."). 6. UPDATE tiap item: status_item, ket_rusak (kosong untuk normal). 7. Item rusak: UPDATE asset_data (hanya bila masih proses dan gudang) → status_asset = rusak, id_pemegang_asset = '', ket_rusak = alasan. Asset tetap di gudang. 8. Status header dihitung dari semua item aktif (item yang sudah diganti tidak dihitung). Laptop rusak → semuaNormal = false → status tetap proses. 9. UPDATE header: user_approval, tgl_approval = now (mulai sekarang dianggap "sudah pernah dicek"), tgl_update, user_update. 10. Item normal (mouse): asset_data dikunci, harus proses + gudang → terpakai, pemegang karyawan, id_pemegang_asset = KRY0001, id_asset_lokasi_m = NULL. INSERT asset_trx_log per asset normal. 11. Commit, lalu AssetNotification::send('onboarding.rusak', …) ke seluruh admin asset di company (semua baris asset_admin).

Hasil database

Item (kolom yang berubah)

Tabel item tidak punya tgl_update/user_update, jadi pelaku perubahan hanya terbaca dari header.

Header

asset_data

asset_trx_log (1 baris, hanya untuk mouse; laptop rusak tidak masuk log)

notif_data (2 baris, satu per admin; urutan id_notif lanjutan dari notifikasi sebelumnya)

jenis = asset, flag_baca = 0, id_company = CMP001. Bahasa Inggris tersimpan di ket_notif_en.

Diterima mobile (HTTP 200)

{
  "code": "UPDATED",
  "message": "Laporan kerusakan asset berhasil dikirim ke admin.",
  "data": {
    "id": "CMP001202610001",
    "no_trx": "KRY01-202610001",
    "status_approval": "proses",
    "status_label": "Isu Rusak",
    "tab": "dikonfirmasi"
  }
}

Mobile menampilkan snackbar dan kembali. Banner onboarding hilang dari Asset Saya (tidak ada lagi item perlu_dicek), dan mouse sudah muncul di daftar asset karyawan.

Langkah 5 — Admin melihat detail dengan status Isu Rusak

Mobile: notifikasi membuka /asset_admin_detail_onboarding; AssetOnboardingDetailBloc menerima LoadAssetOnboardingDetail(id) → GET /asset/onboarding-karyawan/CMP001202610001.

Diproses API: AssetAdmin_m::getDetailOnboardingKaryawan → SELECT header, karyawan (cabang/divisi dari master), item. isu_rusak bernilai true bila ada item aktif rusak yang belum diganti.

Diterima mobile (ringkas; field header seperti API-006)

{
  "status_approval": "proses", "status_label": "Isu Rusak", "tab": "dikonfirmasi", "isu_rusak": true,
  "items": [
    { "id_item": "CMP001202610002", "status_item": "rusak", "ket_rusak": "Ada garis pada layar", "perlu_dicek": false, "diganti": false },
    { "id_item": "CMP001202610003", "status_item": "normal", "ket_rusak": "", "perlu_dicek": false, "diganti": false }
  ]
}

Karena isu_rusak = true, tombol bawah berubah menjadi Ganti Asset Yang Rusak.

Langkah 6 — Admin mengganti asset yang rusak

Mobile - Tombol membuka /asset_admin_ganti_rusak dengan argumen AssetOnboardingKaryawanDetail; AssetGantiRusakBloc menerima LoadAssetPenggantiOptions (memanggil options API-001 lagi). - Admin menekan Ganti Asset pada laptop rusak dan memilih LPT-0002. Event PilihAssetPengganti. kelengkapan otomatis diisi dari deskripsi asset ("Charger, tas") dan tidak dapat diedit. - Submit ke Karyawan → SubmitAssetGantiRusak → AssetOnboardingApi.gantiAsset(id, AssetGantiAssetRequest).

Dikirim

POST /asset/onboarding-karyawan/CMP001202610001/ganti-asset

{
  "items": [
    { "id_item": "CMP001202610002", "id_asset_data": "CMP00120260100003", "kelengkapan": "Charger, tas" }
  ]
}

Diproses API (AssetAdmin_m::gantiAssetRusakOnboarding) 1. Validasi: items minimal 1; id_item dan id_asset_data unik; kelengkapan wajib (maks 255). Cek admin dan lockCompany. 2. Header dikunci. Syarat penggantian: status proses, tgl_approval terisi, dan tidak ada item yang masih menunggu dicek. Bila tidak: "Asset rusak hanya dapat diganti setelah karyawan selesai mengecek asset." 3. Item rusak yang dikirim (…002) harus berstatus rusak dan belum punya pengganti (NOT EXISTS item dengan parent_id = item itu). 4. A3 harus tersedia + gudang dan tidak aktif di onboarding lain. 5. nextSequence item → ID terakhir …003 → …004. INSERT item pengganti dengan parent_id = CMP001202610002 dan deskripsi_asset = kelengkapan yang dikirim. 6. UPDATE asset_data A3 → proses. UPDATE header status_approval = proses, tgl_update, user_update (tgl_approval tidak di-reset). 7. Commit, notifikasi onboarding.pengganti ke karyawan.

Hasil database

Item baru

Item …002 (laptop rusak) tidak diubah: tetap rusak, dan kini dianggap sudah diganti karena ada anak dengan parent_id miliknya.

asset_data: A3 tersedia → proses. A1 tetap rusak di gudang.

Header: status_approval tetap proses, tgl_update = 2026-10-22 11:00:00, user_update = ADM-001 - Siti Admin.

notif_data (1 baris): id_notif = CMP00120261000004, id_karyawan = KRY0001, rute = asset_konfirmasi_onboarding, ket_notif_id = "Asset pengganti onboarding KRY01-202610001 siap dicek."

Diterima mobile (HTTP 200)

{
  "code": "UPDATED",
  "message": "Asset pengganti berhasil dikirim ke karyawan.",
  "data": { "id": "CMP001202610001", "id_karyawan": "KRY0001", "no_trx": "KRY01-202610001",
            "status_approval": "proses", "jumlah_pengganti": 1 }
}

Langkah 7 — Karyawan mengonfirmasi asset pengganti

Mobile: push "Asset Pengganti" membuka /asset_konfirmasi_onboarding. Detail (API-009) kini berisi:

Karyawan memilih Normal pada pengganti lalu Konfirmasi Asset.

Dikirim

POST /asset/karyawan/onboarding/CMP001202610001/konfirmasi

{ "items": [ { "id_item": "CMP001202610004", "status_item": "normal" } ] }

Hanya item yang perlu_dicek yang dikirim; item lain tidak boleh disertakan karena jumlah dan ID harus sama persis.

Diproses API (konfirmasiOnboardingKaryawan, ronde kedua) 1. Header proses, tgl_approval sudah terisi → pendingItemIds hanya mengembalikan item aktif berstatus belum_dicek = …004. 2. UPDATE item …004 → normal. 3. Item aktif = semua item yang belum diganti: …003 (normal) dan …004 (normal). Laptop lama …002 dikeluarkan karena sudah punya pengganti. semuaNormal = true → status header dikonfirmasi. 4. UPDATE header: status_approval = dikonfirmasi, user_approval, tgl_approval = now, tgl_update, user_update. 5. Hanya item yang dicek pada ronde ini yang diserahkan: A3 → terpakai, karyawan, KRY0001, id_asset_lokasi_m = NULL. Mouse tidak disentuh lagi. 6. INSERT asset_trx_log untuk A3. 7. Commit, notifikasi onboarding.dikonfirmasi ke seluruh admin asset.

Hasil database

Diterima mobile (HTTP 200)

{
  "code": "UPDATED",
  "message": "Asset berhasil dikonfirmasi.",
  "data": { "id": "CMP001202610001", "no_trx": "KRY01-202610001",
            "status_approval": "dikonfirmasi", "status_label": "Selesai", "tab": "selesai" }
}

Transaksi pindah ke tab Selesai di list admin, dan stepper alur mencapai langkah terakhir.

Kondisi akhir seluruh data

asset_trx_onboarding_karyawan

asset_trx_onboarding_karyawan_item

(CMP001202610001 pernah ada pada langkah 1, dihapus pada langkah 2, dan tidak dipakai ulang.)

asset_data

asset_trx_log: 2 baris (A2 dan A3). notif_data: 6 baris (1 pengiriman, 2 laporan rusak, 1 pengganti, 2 dikonfirmasi). Aset A1 yang rusak tidak punya baris log dan kini menjadi kandidat modul Perbaikan/Garansi/Disposal.

Pada Asset Saya karyawan (API-008), assets[] berisi A2 dan A3 dan jumlah_asset = 2.

Skenario variasi

Semua normal sekali jalan. Pada langkah 4, bila kedua item dinilai normal: semuaNormal = true, header langsung dikonfirmasi, kedua asset terpakai/karyawan, 2 baris asset_trx_log, notif onboarding.dikonfirmasi ke admin, status_label = "Selesai", tab = "selesai". Langkah 5–7 tidak terjadi.

Menghapus draft (API-005). DELETE /asset/onboarding-karyawan/CMP001202610001 saat masih draft: asset proses dikembalikan ke tersedia, item dan header di-DELETE, tanpa notifikasi. Response DELETED dengan id dan no_trx. Karena barisnya terhapus, Budi kembali muncul di options dan boleh dibuatkan onboarding baru.

Kasus gagal yang umum

Semua error bisnis dilempar sebagai InvalidArgumentException di dalam DB::transaction, sehingga seluruh perubahan pada request itu dibatalkan. Mobile menampilkan message (atau errors pertama) di snackbar.

Ringkasan siapa mengerjakan apa

46Ringkasan Database Impact

47Checklist Implementasi

Database

• Table header
• Table item (dengan pohon pengganti)
• Index list header & item
• Master relation (DBML ref; ⚠️ FK fisik belum terverifikasi)
• Status enum
• Log (asset_trx_log untuk serah terima normal)
• Migration CREATE TABLE baseline
• Log untuk item rusak / histori status

Backend

• Route
• Controller
• Validation (inline)
• Service / Repository (tidak dipakai; logic di model)
• Transaction + locking
• Logging error
• Error handling
• Notifikasi
• Approve/Reject
• Pembatalan onboarding berjalan
• Validasi satu onboarding per karyawan (assertKaryawanBelumPernahOnboarding)

Mobile

• List (tab, pagination, refresh)
• Create
• Detail
• Edit (draft)
• Delete (draft)
• Approval
• Asset selection (pohon kategori + pencarian)
• Serah terima (konfirmasi karyawan)
• Ganti asset rusak
• Validation
• Error handling
• i18n penuh pada form
• Input kelengkapan manual saat penggantian

Documentation

• Business Flow
• DB Relationship
• API
• Mobile
• Mapping
• Manual Book (tanpa screenshot)
• Testing
• Screenshot aplikasi

48Changelog