Laporan Kerusakan Asset Karyawan

01Informasi Dokumen

03Quick Overview

Karyawan: pilih 1 asset terpakai → pilih Unit Utama ATAU Kelengkapan → centang item + keterangan → Kirim Laporan
                                                           proses(1) / pengajuan · asset TIDAK berubah
Admin: per item Setujui/Tolak (+alasan); disetujui → Diganti / Tidak Diganti
       unit utama diganti → Pilih Unit Pengganti (sekategori, tersedia @gudang) → pengganti = proses
       → Jadwal Serah Terima (tanggal, jam, catatan)
       ├─ semua ditolak ─────────────────────────────────────── ditolak(2) / selesai
       └─ ada disetujui ─────────────────────────────────────── disetujui(3) / menunggu_pengambilan
Karyawan: Konfirmasi Serah Terima
   • unit utama disetujui → asset lama = rusak @gudang      • hanya kelengkapan → asset tetap @karyawan (ket_rusak dicatat)
   ├─ tanpa pengganti ──────────────────────────────────────── selesai
   └─ ada pengganti ────────────────────────────────────────── checklist unit pengganti diisi bersamaan
Karyawan: Serah Terima & Kirim Checklist Unit Pengganti (Normal/Rusak per item)
   • semua normal → pengganti = terpakai @karyawan ─────────── selesai (otomatis, admin hanya dinotifikasi)
   • ada yang rusak ────────────────────────────────────────── menunggu_review_checklist
Admin: Pilih Pengganti Lain + jadwal → pengganti lama = rusak @gudang  menunggu_pengambilan (ulang)

04Ringkasan Fitur

Karyawan melaporkan kerusakan pada satu asset yang sedang dipakainya (status_asset = terpakai). Laporan bersifat per komponen: unit utama dan/atau kelengkapan (misalnya charger, adaptor) yang diambil dari asset_data_item. Setiap item wajib diberi keterangan kerusakan.

Admin meninjau setiap item. Untuk item yang disetujui admin menentukan apakah item diganti. Hanya unit utama yang diganti yang memicu penukaran unit: admin memilih unit pengganti dari gudang dengan kategori sama. Kelengkapan yang "diganti" hanya dicatat.

Serah terima dikonfirmasi karyawan. Jika ada unit pengganti, karyawan wajib mengecek kondisi setiap komponen unit pengganti (checklist) pada saat serah terima yang sama. Bila semua normal, laporan selesai otomatis. Bila ada yang rusak, admin memilih unit pengganti lain dan siklus berulang sampai unit pengganti dinyatakan normal — seluruh percobaan tersimpan sebagai histori.

05Tujuan Fitur

5.1 Tujuan Bisnis (diturunkan dari kode)

• Karyawan dapat melaporkan kerusakan asset secara terstruktur per komponen.
• Admin memutuskan penarikan dan penggantian unit secara terkontrol.
• Unit pengganti dipastikan dalam kondisi baik sebelum menjadi milik karyawan.
• Riwayat penggantian berulang dapat ditelusuri.

5.2 Tujuan Sistem

• Menyimpan laporan per komponen dengan snapshot data komponen (JSON).
• Mereservasi unit pengganti (proses) hingga lolos checklist.
• Memperbarui asset_data dan mencatat asset_trx_log pada setiap perpindahan.
• Mencegah asset diproses di laporan kerusakan lain, retur, upgrade, atau offboarding saat laporan dibuat.

06Aktor

07Hak Akses

08Terminologi

09Business Rules

BR-001 — Asset yang boleh dilaporkan

Milik karyawan login (pemegang_asset = karyawan, id_pemegang_asset = id_karyawan) dan status_asset = terpakai → "Asset bukan milik karyawan atau tidak ditemukan." / "Hanya asset berstatus terpakai yang dapat dilaporkan rusak." Asset pinjaman (dipinjam) tidak bisa dilaporkan di sini. Karyawan harus aktif.

BR-002 — Asset tidak sedang di flow lain (assetBlockMessage)

Dicek saat opsi dan simpan: laporan kerusakan aktif, retur aktif, upgrade aktif, offboarding aktif, pemeliharaan terjadwal (PML01) aktif → "Asset sedang diproses pada laporan kerusakan lain." / "…pada retur." / "…pada upgrade." / "…pada offboarding." / "…pada pemeliharaan."

BR-003 — Item laporan

Minimal 1; setiap id_item harus komponen asset tersebut; tanpa duplikat; keterangan wajib → "Minimal satu item rusak wajib dipilih." / "Item rusak harus berupa unit utama atau kelengkapan asset." / "Item yang sama tidak boleh dipilih lebih dari sekali." / "Keterangan kerusakan setiap item wajib diisi." Snapshot komponen disimpan di kelengkapan_item (JSON). Mobile membatasi satu jenis per laporan (INC-01).

BR-004 — Laporan tidak mengubah asset

Saat laporan dikirim, asset_data tetap terpakai @karyawan.

BR-005 — Review seluruh item

Semua item wajib diputuskan → "Seluruh item kerusakan wajib direview."; tolak wajib alasan; disetujui wajib status_diganti 0/1. Asset harus masih dipegang karyawan → "Asset sudah tidak dipegang oleh karyawan."

BR-006 — Unit pengganti

Hanya bila ada unit utama disetujui dan diganti. Pengganti wajib dipilih, belum pernah dipakai di laporan ini, tersedia @gudang, kategori sama dengan asset rusak → "Asset pengganti wajib dipilih." / "Asset pengganti hanya dipilih jika unit utama diganti." / "Asset pengganti sudah pernah dipakai pada laporan ini." / "Aset sudah tidak tersedia. Silakan pilih unit lain." / "Kategori asset pengganti harus sama dengan asset yang rusak." Pengganti → status_asset = proses.

BR-007 — Jadwal serah terima

Wajib bila ada item disetujui (review), dan pada pilih pengganti lain; tanggal ≥ tanggal pengajuan → "Tanggal dan jam serah terima wajib diisi." / "Format jadwal serah terima tidak valid." / "Tanggal serah terima tidak boleh sebelum tanggal pengajuan." Satu jadwal untuk pengambilan item rusak dan kedatangan pengganti (docblock: "SOP: hari yang sama").

BR-008 — Hasil review

Semua ditolak → status_approval = 2, selesai (asset tidak berubah). Ada disetujui → 3, menunggu_pengambilan.

BR-009 — Serah terima pertama (karyawan)

• Unit utama disetujui (diganti atau tidak) → asset lama rusak, pemegang = gudang.
• Hanya kelengkapan disetujui → asset tetap dipegang karyawan (status tetap), hanya ket_rusak diisi.
• ket_rusak asset = ringkasan "nama: keterangan; …" (maks 255).
• Log rusak_karyawan. Ada pengganti → tgl_serah_terima pengganti + checklist unit pengganti (BR-011) pada langkah yang sama; tanpa pengganti → selesai.

BR-010 — Serah terima pengganti berikutnya

Bila tgl_pelepasan sudah terisi, konfirmasi serah terima hanya mencatat penerimaan pengganti terbaru → "Tidak ada unit pengganti yang perlu diserahterimakan." bila tidak ada.

BR-011 — Checklist pengganti (karyawan)

Dikirim bersama serah terima (items opsional pada pelepasan) atau lewat endpoint checklist (alur lama, menunggu_checklist); semua komponen unit pengganti wajib dicek; kondisi normal/rusak; rusak wajib keterangan → "Seluruh item unit pengganti wajib dicek." Hasil disimpan sebagai JSON di kelengkapan_item; status_checklist = rusak bila ada satu saja rusak. Normal → laporan selesai otomatis (pengganti terpakai @karyawan + log; admin hanya dinotifikasi). Rusak → menunggu_review_checklist. Bila checklist tidak lengkap, seluruh serah terima dibatalkan.

BR-012 — Keputusan setelah checklist (admin)

• Checklist normal → selesai otomatis (tanpa langkah admin): pengganti terpakai @karyawan + log → selesai. Selesaikan Laporan hanya tersisa untuk laporan lama yang sudah menunggu review.
• Checklist rusak → Pilih Pengganti Lain: pengganti lama rusak @gudang (+ket_rusak) + log; baris pengganti baru (urutan + 1); jadwal baru → menunggu_pengambilan.
• Tombol salah → "Unit pengganti masih memiliki item rusak. Pilih unit pengganti lain." / "Seluruh item unit pengganti normal. Selesaikan laporan." Pengganti harus masih proses @gudang → "Status asset pengganti sudah berubah."

BR-013 — Penomoran

Header & item id_company + YYYYMM + 3 digit; no_trx = KRY06-YYYYMMNNN; log 5 digit.

10Business Flow

1. Karyawan: Asset Saya → Kerusakan → (+) Lapor Kerusakan Asset
   → Pilih Asset yang Rusak → Unit Utama / Kelengkapan → centang item + Keterangan Kerusakan
   → Atribut Lainnya / Keterangan Umum → Kirim Laporan               [Menunggu Review · notif admin]
2. Admin: Asset Karyawan → Kerusakan → Detail
   → per item Setujui/Tolak; disetujui: Diganti / Tidak Diganti
   → (unit utama diganti) Pilih Unit Pengganti
   → Simpan Review → Jadwal Serah Terima                               [Menunggu Serah Terima / Ditolak · notif karyawan]
3. Karyawan: serahkan item rusak, terima pengganti, isi Checklist Unit Pengganti → Serah Terima & Kirim Checklist
                                                                      [Selesai bila normal / Menunggu Review Checklist bila rusak · notif admin]
4. Admin (hanya bila checklist rusak): Pilih Pengganti Lain + jadwal → kembali ke langkah 3 [notif karyawan]

11Flow Berdasarkan Role

11.1 Karyawan

1. Asset Saya → menu Kerusakan → Laporan Kerusakan Asset → tombol Lapor Kerusakan.
2. Banner di Asset Saya: Serah Terima Asset Rusak ("{asset}: serahkan item rusak sesuai jadwal, lalu konfirmasi.") dan Checklist Unit Pengganti ("Cek kondisi unit pengganti untuk {asset}.").
3. Detail → Serah Terima & Kirim Checklist (bila ada unit pengganti) atau Konfirmasi Serah Terima.

11.2 Admin Asset

1. Asset Karyawan → aksi Kerusakan, atau panel Kerusakan Perlu Diproses (laporan baru + checklist yang perlu direview).
2. Detail → review → Simpan Review; Ubah Jadwal; Selesaikan Laporan / Pilih Pengganti Lain.

11.3 System

Deteksi komponen, cek flow lain, reservasi pengganti, update asset & log, notifikasi.

12Flow Diagram

flowchart TD
    A[Karyawan pilih asset + item rusak + keterangan] --> B{Validasi}
    B -->|Gagal| X[Pesan error]
    B -->|OK| C[Menunggu Review, notif admin]
    C --> D{Admin review per item}
    D -->|Semua ditolak| E[Ditolak, asset tidak berubah]
    D -->|Ada disetujui| F{Unit utama diganti?}
    F -->|Ya| G[Pilih unit pengganti sekategori, pengganti proses]
    F -->|Tidak| H[Tanpa pengganti]
    G --> I[Jadwal serah terima, Menunggu Serah Terima]
    H --> I
    I --> J[Karyawan: Konfirmasi Serah Terima]
    J --> K{Unit utama disetujui?}
    K -->|Ya| L[Asset lama rusak di gudang]
    K -->|Tidak, hanya kelengkapan| M[Asset tetap di karyawan, ket_rusak dicatat]
    L --> N{Ada pengganti?}
    M --> N
    N -->|Tidak| Z[Selesai]
    N -->|Ya| P[Karyawan: serah terima + checklist unit pengganti]
    P --> Q{Hasil checklist}
    Q -->|Normal| R[Otomatis selesai: pengganti terpakai di karyawan]
    R --> Z
    Q -->|Rusak| S[Admin: Pilih Pengganti Lain + jadwal, pengganti lama rusak di gudang]
    S --> I

13Sequence Diagram

sequenceDiagram
    actor K as Karyawan
    actor A as Admin
    participant M as Mobile
    participant CK as AssetKaryawanRusak_c
    participant CA as AssetAdminRusak_c
    participant R as AssetRusakKaryawan_m
    participant DB
    participant N as AssetNotification

    K->>M: Pilih asset, item, keterangan, Kirim Laporan
    M->>CK: POST /asset/karyawan/rusak
    CK->>R: store()
    R->>DB: lock company, karyawan aktif, asset terpakai milik karyawan, cek flow lain
    R->>DB: INSERT header (1, pengajuan) + item laporan
    CK->>N: kerusakan.diajukan (admin)
    A->>M: Keputusan item, diganti, unit pengganti, jadwal
    M->>CA: POST /asset/rusak-karyawan/{id}/review
    CA->>R: review()
    R->>DB: UPDATE item, INSERT baris pengganti, pengganti jadi proses
    R->>DB: UPDATE header (3, menunggu_pengambilan) + jadwal
    CA->>N: kerusakan.disetujui atau kerusakan.ditolak (karyawan)
    K->>M: Serah terima + checklist unit pengganti
    M->>CK: POST /asset/karyawan/rusak/{id}/pelepasan (items)
    CK->>R: pelepasan()
    R->>DB: asset lama rusak di gudang atau tetap, INSERT asset_trx_log
    R->>DB: tgl_serah_terima pengganti + hasil checklist (status_checklist)
    R->>DB: normal: pengganti terpakai di karyawan + asset_trx_log, header selesai
    R->>DB: rusak: header menunggu_review_checklist
    CK->>N: kerusakan.selesai_otomatis atau kerusakan.checklist (admin)
    A->>M: Pilih Pengganti Lain (hanya bila rusak)

14Status Transaksi

Dua kolom: status_approval (tinyint, konstanta Asset_m) dan status_transaksi (enum, dari migration).

Status item: laporan status_approval NULL → disetujui/ditolak; pengganti status_checklist belum_dicek → normal/rusak.

Detail API juga mengembalikan objek aksi (review, ubah_jadwal, pelepasan, checklist, pelepasan_checklist, selesai, ganti_pengganti) sebagai penentu tombol.

15State Transition

stateDiagram-v2
    [*] --> pengajuan: Kirim Laporan (Karyawan)
    pengajuan --> ditolak: Review, semua ditolak (Admin)
    pengajuan --> menunggu_pengambilan: Review, ada disetujui (Admin)
    menunggu_pengambilan --> menunggu_pengambilan: Ubah jadwal (Admin)
    menunggu_pengambilan --> selesai: Serah terima tanpa pengganti (Karyawan)
    menunggu_pengambilan --> selesai: Serah terima + checklist normal (Karyawan)
    menunggu_pengambilan --> menunggu_review_checklist: Serah terima + checklist rusak (Karyawan)
    menunggu_pengambilan --> menunggu_checklist: Serah terima tanpa checklist, alur lama (Karyawan)
    menunggu_checklist --> selesai: Kirim checklist normal (Karyawan)
    menunggu_checklist --> menunggu_review_checklist: Kirim checklist rusak (Karyawan)
    menunggu_review_checklist --> selesai: Selesaikan, laporan lama checklist normal (Admin)
    menunggu_review_checklist --> menunggu_pengambilan: Pilih pengganti lain, checklist rusak (Admin)
    ditolak --> [*]
    selesai --> [*]

Status asset_data: | Asset | Dari | Ke | Trigger | |---|---|---|---| | Asset dilaporkan | terpakai @karyawan | tidak berubah | Lapor, review | | Asset dilaporkan (unit utama disetujui) | terpakai @karyawan | rusak @gudang | Serah terima pertama | | Asset dilaporkan (hanya kelengkapan) | terpakai @karyawan | tetap, ket_rusak diisi | Serah terima pertama | | Unit pengganti | tersedia @gudang | proses @gudang | Review / pilih pengganti lain | | Unit pengganti (checklist normal) | proses @gudang | terpakai @karyawan | Checklist normal (otomatis) | | Unit pengganti (checklist rusak) | proses @gudang | rusak @gudang | Pilih pengganti lain |

16Struktur Database

17Relasi Database

erDiagram
    ASSET_TRX_RUSAK_KARYAWAN ||--o{ ASSET_TRX_RUSAK_KARYAWAN_ITEM : "id_asset_trx_rusak"
    ASSET_TRX_RUSAK_KARYAWAN_ITEM |o--o| ASSET_TRX_RUSAK_KARYAWAN_ITEM : "parent_id (rantai pengganti)"
    ASSET_DATA ||--o{ ASSET_TRX_RUSAK_KARYAWAN_ITEM : "id_asset_data"
    ASSET_DATA ||--o{ ASSET_DATA_ITEM : "id_asset_data"
    DATA_KARYAWAN ||--o{ ASSET_TRX_RUSAK_KARYAWAN : "id_karyawan (logis)"
    ASSET_DATA ||--o{ ASSET_TRX_LOG : "id_asset_data"

    ASSET_TRX_RUSAK_KARYAWAN {
        varchar id_asset_trx_rusak_karyawan PK
        varchar no_trx
        date tgl_pengajuan
        date tgl_serah_terima
        time jam_serah_terima
        timestamp tgl_pelepasan
        tinyint status_approval
        enum status_transaksi
    }
    ASSET_TRX_RUSAK_KARYAWAN_ITEM {
        varchar id_asset_trx_rusak_item PK
        varchar parent_id
        int urutan_penggantian
        varchar id_asset_trx_rusak FK
        varchar id_asset_data FK
        enum status_approval
        enum status_diganti
        enum flag_jenis_komponen
        text kelengkapan_item
        enum status_checklist
    }
    ASSET_DATA {
        varchar id_asset_data PK
        enum status_asset
        enum pemegang_asset
        varchar ket_rusak
    }
    ASSET_DATA_ITEM {
        varchar id_asset_data_item PK
        varchar id_asset_data FK
        text json_value
    }
    ASSET_TRX_LOG {
        varchar id_asset_trx_log PK
        varchar id_asset_data FK
        enum jenis_log
    }

18Data Dictionary

18.1 asset_trx_rusak_karyawan

18.2 asset_trx_rusak_karyawan_item

18.3 asset_trx_log (jenis_log = rusak_karyawan)

19Database Index

20Backend Architecture

RouteAsset.php (prefix /asset, jwt.api + jwt.ctx)
   ↓
AssetAdminRusak_c (validateRequest → mutateAssetTrx: accessError + notifikasi)
AssetKaryawanRusak_c (validateRequest → store / mutateTrxSaya)
   ↓
AssetRusakKaryawan_m ← Asset_m (lockCompany, nextSequence, komponenAssets, parseJadwalValue,
   ↓                             insertAssetLog, getLockedAssets, findActiveKaryawan, findAssetAdmin)
   ↓   ↔ AssetReturKaryawan_m / AssetUpgradeKaryawan_m / AssetOffboardingKaryawan_m (cek flow lain)
DB::transaction (retry 3) → ApiResponse + AssetNotification

21Backend Business Logic

21.1 Lapor — store

Lock → karyawan aktif → asset milik karyawan (FOR UPDATE), terpakai → assetBlockMessage → komponenAssets → normalizeReportItems → ID + KRY06-… → INSERT header (1, pengajuan, jadwal nol) → INSERT item (urutan 0, snapshot JSON, flag_jenis_komponen) → notifikasi kerusakan.diajukan.

21.2 Review — review

Admin → header status_approval = 1 → item laporan (FOR UPDATE) → semua diputuskan → validasi keputusan → asset masih dipegang karyawan → jadwal (bila ada disetujui) → pengganti (bila unit utama diganti; lockReplacementCandidate) → UPDATE item → insertReplacement (urutan 1, pengganti proses) → UPDATE header (2/selesai atau 3/menunggu_pengambilan + jadwal) → notifikasi. Response +jumlah_disetujui, jumlah_ditolak, perlu_pengganti.

21.3 Ubah jadwal — updateJadwal

Status menunggu_pengambilan → "Jadwal hanya dapat diubah sebelum serah terima dilakukan." → update jadwal → kerusakan.dijadwalkan.

21.4 Serah terima — pelepasan (karyawan)

Karyawan aktif, laporan miliknya, menunggu_pengambilan → pengganti terbaru yang belum diterima → bila tgl_pelepasan kosong: releaseOriginalAsset → set tgl_serah_terima pengganti → bila items dikirim: simpan checklist (applyChecklist), normal → selesai otomatis (completeReplacement), rusak → menunggu_review_checklist; tanpa items: menunggu_checklist (alur lama) atau selesai bila tanpa pengganti → tgl/user_pelepasan (hanya pertama kali) → notifikasi kerusakan.selesai_otomatis / kerusakan.checklist / kerusakan.diserahkan. items tanpa unit pengganti ditolak; checklist tidak lengkap membatalkan seluruh transaksi.

21.5 Checklist — submitChecklist (karyawan)

menunggu_checklist → pengganti terbaru sudah diterima & belum_dicek → komponen pengganti (komponenAssets) harus lengkap → simpan hasil JSON, status_checklist, ringkasan ket_rusak, tgl_checklist → normal: selesai otomatis (pengganti terpakai @karyawan + log); rusak: header menunggu_review_checklist → kerusakan.checklist. Response +status_checklist.

21.6 Selesaikan — selesai (admin)

Hanya laporan lama (checklist normal baru selesai otomatis): menunggu_review_checklist + checklist normal → pengganti masih proses @gudang → pengganti terpakai @karyawan + log → header selesai → kerusakan.selesai.

21.7 Pilih pengganti lain — gantiPengganti (admin)

menunggu_review_checklist + checklist rusak → jadwal baru → pengganti baru (sekategori, belum dipakai di laporan) → pengganti lama rusak @gudang + log → INSERT baris pengganti (urutan + 1, parent_id = pengganti lama) → header menunggu_pengambilan → kerusakan.pengganti_ulang. Response +urutan_penggantian.

21.8 Query baca

• Opsi karyawan: asset terpakai miliknya yang tidak diblokir flow lain, beserta komponen (items).
• Opsi pengganti (admin): asset tersedia @gudang, kategori sama dengan asset dilaporkan, belum dipakai di laporan ini.
• List: tab pengajuan (approval 1), proses (approval 3 & belum selesai), selesai (status_transaksi selesai — termasuk ditolak). jumlah_item = item laporan.
• Detail: header, karyawan, asset, items, pengganti (histori; komponen hanya untuk pengganti terbaru yang belum dicek), perlu_pengganti, unit_ditarik, aksi.
• Pending: karyawan (menunggu_pengambilan → aksi pelepasan, menunggu_checklist → checklist) di Asset Saya; admin (approval 1 atau menunggu_review_checklist) di summary.

22Dampak terhadap asset_data

23API Documentation

Terkait: GET /asset/karyawan/onboarding (Asset Saya, key kerusakan) dan GET /asset/summary (kerusakan_perlu_proses, kerusakan_pending).

24Detail Setiap API

Header umum: Authorization: Bearer <token>, Content-Type: application/json, Accept, locale, versi-app. Format { code, message, data }.

API-008 — Opsi Laporan (Karyawan)

GET /asset/karyawan/rusak/options

{
  "code": "SUCCESS",
  "message": "Opsi laporan kerusakan berhasil ditemukan.",
  "data": {
    "assets": [
      {
        "id_asset_data": "CMP00120260100012",
        "kode_asset": "LPT-0012",
        "nama_asset": "Laptop 14 inch",
        "kategori_asset": "Laptop",
        "merek": "MerekX",
        "deskripsi": "",
        "status_asset": "terpakai",
        "items": [
          {"id_item": "CMP001ITEM0101", "nama_item": "Laptop 14 inch", "jenis": "aset_utama", "detail": "RAM: 16 GB, SSD: 512 GB"},
          {"id_item": "CMP001ITEM0102", "nama_item": "Charger", "jenis": "kelengkapan", "detail": "Daya: 65 W"}
        ]
      }
    ]
  }
}

API-010 — Kirim Laporan

POST /asset/karyawan/rusak

{
  "id_asset_data": "CMP00120260100012",
  "keterangan": "Terjadi setelah update sistem",
  "items": [
    {"id_item": "CMP001ITEM0101", "ket_rusak": "Ada garis pada layar"}
  ]
}

Pesan umum: "Data laporan kerusakan belum lengkap." Database impact: INSERT header, INSERT item, INSERT notif (asset tidak berubah).

{ "code": "CREATED", "message": "Laporan kerusakan asset berhasil dikirim.",
  "data": { "id": "CMP001202609005", "no_trx": "KRY06-202609005", "status_approval": 1,
            "status_transaksi": "pengajuan", "status_label": "Menunggu Review", "tab": "pengajuan" } }

422: "Karyawan tidak ditemukan atau tidak aktif.", "Asset bukan milik karyawan atau tidak ditemukan.", "Hanya asset berstatus terpakai yang dapat dilaporkan rusak.", "Asset sedang diproses pada laporan kerusakan lain." / "…retur." / "…upgrade." / "…offboarding." / "…pemeliharaan.", "Item rusak harus berupa unit utama atau kelengkapan asset." 500: "Terjadi kesalahan saat menyimpan laporan kerusakan."

API-001 / API-009 — List

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

tab: pengajuan | proses | selesai ("Filter laporan kerusakan tidak valid.").

{
  "filters": [
    {"value": "pengajuan", "label": "Pengajuan"},
    {"value": "proses", "label": "Proses"},
    {"value": "selesai", "label": "Selesai"}
  ],
  "records": [
    {
      "id": "CMP001202609005",
      "no_trx": "KRY06-202609005",
      "tgl_pengajuan": "2026-09-28",
      "flag_jadwalkan": "1",
      "tgl_serah_terima": "2026-09-30",
      "jam_serah_terima": "10:00:00",
      "status_approval": 3,
      "status_transaksi": "menunggu_pengambilan",
      "status_label": "Menunggu Serah Terima",
      "tab": "proses",
      "jumlah_item": 1,
      "asset": {"id_asset_data": "CMP00120260100012", "nama_asset": "Laptop 14 inch", "kategori_asset": "Laptop"},
      "karyawan": {"id_karyawan": "KRY0009", "nik": "EMP-009", "nama_karyawan": "Sari Contoh"}
    }
  ],
  "pagination": {"limit": 20, "offset": 0, "next_offset": 1, "has_more": false}
}

API-002 / API-011 — Detail

{
  "id": "CMP001202609005",
  "no_trx": "KRY06-202609005",
  "tgl_pengajuan": "2026-09-28",
  "keterangan": "Terjadi setelah update sistem",
  "flag_jadwalkan": "1",
  "tgl_serah_terima": "2026-09-30",
  "jam_serah_terima": "10:00:00",
  "keterangan_serah_terima": "Ambil di ruang IT",
  "tgl_pelepasan": "",
  "status_approval": 3,
  "status_transaksi": "menunggu_pengambilan",
  "status_label": "Menunggu Serah Terima",
  "tab": "proses",
  "perlu_pengganti": true,
  "unit_ditarik": true,
  "karyawan": {"id_karyawan": "KRY0009", "nik": "EMP-009", "nama_karyawan": "Sari Contoh", "cabang": "Kantor Pusat", "divisi": "Marketing"},
  "asset": {"id_asset_data": "CMP00120260100012", "kode_asset": "LPT-0012", "nama_asset": "Laptop 14 inch", "kategori_asset": "Laptop", "merek": "MerekX", "deskripsi": ""},
  "items": [
    {"id_item": "CMP001202609011", "id_asset_data_item": "CMP001ITEM0101", "nama_item": "Laptop 14 inch", "jenis": "aset_utama",
     "detail": "RAM: 16 GB, SSD: 512 GB", "ket_rusak": "Ada garis pada layar", "status_item": "disetujui", "ket_tolak": "", "status_diganti": true}
  ],
  "pengganti": [
    {"id_item": "CMP001202609012", "urutan": 1, "id_asset_data": "CMP00120260100020", "kode_asset": "LPT-0020", "nama_asset": "Laptop 14 inch",
     "kategori_asset": "Laptop", "merek": "MerekX", "deskripsi": "", "status_checklist": "belum_dicek", "tgl_serah_terima": "",
     "tgl_checklist": "", "ket_rusak": "", "checklist": [],
     "komponen": [{"id_item": "CMP001ITEM0201", "nama_item": "Laptop 14 inch", "jenis": "aset_utama", "detail": ""}]}
  ],
  "aksi": {"review": false, "ubah_jadwal": true, "pelepasan": true, "checklist": false, "selesai": false, "ganti_pengganti": false}
}

Karyawan tidak menerima karyawan.id_karyawan. 404: "Laporan kerusakan tidak ditemukan."

API-003 — Opsi Unit Pengganti (Admin)

GET /asset/rusak-karyawan/{id}/options

data.assets[]: id_asset_data, kode_asset, nama_asset, kategori_asset, merek, deskripsi, status_asset, id_asset_kategori_m (tersedia @gudang, kategori sama, belum dipakai di laporan). 404 bila laporan tidak punya item.

API-004 — Review

POST /asset/rusak-karyawan/{id}/review

{
  "items": [
    {"id_item": "CMP001202609011", "status_item": "disetujui", "ket_tolak": "", "status_diganti": "1"}
  ],
  "id_asset_pengganti": "CMP00120260100020",
  "tgl_serah_terima": "2026-09-30",
  "jam_serah_terima": "10:00",
  "keterangan_serah_terima": "Ambil di ruang IT"
}

Database impact: UPDATE item, INSERT item pengganti, UPDATE asset pengganti → proses, UPDATE header, INSERT notif.

{ "code": "UPDATED", "message": "Review laporan kerusakan berhasil disimpan.",
  "data": { "id": "CMP001202609005", "no_trx": "KRY06-202609005", "status_approval": 3,
            "status_transaksi": "menunggu_pengambilan", "status_label": "Menunggu Serah Terima", "tab": "proses",
            "jumlah_disetujui": 1, "jumlah_ditolak": 0, "perlu_pengganti": true } }

422: "Laporan kerusakan sudah direview.", "Seluruh item kerusakan wajib direview.", "Asset sudah tidak dipegang oleh karyawan.", "Asset pengganti hanya dipilih jika unit utama diganti.", "Asset pengganti wajib dipilih.", "Aset sudah tidak tersedia. Silakan pilih unit lain.", "Kategori asset pengganti harus sama dengan asset yang rusak.", "Tanggal dan jam serah terima wajib diisi.", "Tanggal serah terima tidak boleh sebelum tanggal pengajuan.", "Pengguna tidak terdaftar sebagai admin asset." 500: "Terjadi kesalahan saat memproses transaksi asset."

API-005 — Ubah Jadwal

PUT /asset/rusak-karyawan/{id}/jadwal

{ "tgl_serah_terima": "2026-10-01", "jam_serah_terima": "14:00", "keterangan_serah_terima": "" }

"Jadwal serah terima berhasil diperbarui." 422: "Jadwal hanya dapat diubah sebelum serah terima dilakukan."

API-012 — Konfirmasi Serah Terima (Karyawan)

POST /asset/karyawan/rusak/{id}/pelepasan

Body opsional items (format sama dengan API-013; kirim bila aksi.pelepasan_checklist true): checklist unit pengganti dikirim bersama serah terima. Normal → laporan selesai otomatis, rusak → menunggu_review_checklist; response +status_checklist bila items dikirim. Database impact: asset dilaporkan (rusak @gudang atau ket_rusak saja), asset_trx_log, item pengganti tgl_serah_terima, header. "Serah terima asset rusak berhasil dikonfirmasi." 422: "Laporan kerusakan belum siap diserahterimakan.", "Tidak ada unit pengganti yang perlu diserahterimakan.", "Tidak ada unit pengganti yang perlu dicek.", "Seluruh item unit pengganti wajib dicek.", "Asset sudah tidak dipegang oleh karyawan.", "Karyawan tidak ditemukan atau tidak aktif."

API-013 — Checklist Unit Pengganti (Karyawan)

POST /asset/karyawan/rusak/{id}/checklist

{
  "items": [
    {"id_item": "CMP001ITEM0201", "kondisi": "normal", "ket_rusak": ""},
    {"id_item": "CMP001ITEM0202", "kondisi": "rusak", "ket_rusak": "Kabel charger terkelupas"}
  ]
}

Response +status_checklist; checklist normal langsung menyelesaikan laporan (status_transaksi = selesai). "Checklist unit pengganti berhasil dikirim." 422: "Unit pengganti belum siap dicek.", "Unit pengganti belum diserahterimakan.", "Seluruh item unit pengganti wajib dicek."

API-006 — Selesaikan (Admin)

POST /asset/rusak-karyawan/{id}/selesai

Tanpa body. Hanya untuk laporan lama yang menunggu review dengan checklist normal. "Laporan kerusakan berhasil diselesaikan." 422: "Checklist unit pengganti belum dikirim karyawan.", "Unit pengganti masih memiliki item rusak. Pilih unit pengganti lain.", "Status asset pengganti sudah berubah."

API-007 — Pilih Pengganti Lain (Admin)

POST /asset/rusak-karyawan/{id}/ganti-pengganti

{ "id_asset_pengganti": "CMP00120260100021", "tgl_serah_terima": "2026-10-02", "jam_serah_terima": "09:00", "keterangan_serah_terima": "" }

id_asset_pengganti required ("Asset pengganti wajib dipilih."). Response +urutan_penggantian. "Unit pengganti baru berhasil dipilih." 422: "Seluruh item unit pengganti normal. Selesaikan laporan.", "Asset pengganti sudah pernah dipakai pada laporan ini.", "Kategori asset pengganti harus sama dengan asset yang rusak.", "Tanggal dan jam serah terima wajib diisi."

25Mobile Architecture

Page → AssetKerusakanBloc / AssetKerusakanAdminBloc → AssetKerusakanApi / AssetKerusakanAdminApi → ApiClient → Backend

26Mobile Screen

26.1 Laporan Kerusakan Asset — list (karyawan & admin)

Tab Pengajuan / Proses / Selesai; kartu: nomor, asset, "{jumlah} item rusak", status (Menunggu Review, Menunggu Serah Terima, Menunggu Checklist, Menunggu Review Checklist, Selesai, Ditolak), jadwal. Karyawan: tombol Lapor Kerusakan. Kosong: "Belum ada laporan kerusakan asset."

26.2 Lapor Kerusakan Asset (karyawan)

26.3 Detail Laporan Kerusakan (karyawan)

Info laporan, Jadwal Serah Terima ("Serah terima dijadwalkan pada {tanggal}, jam {jam}."), item (Disetujui Admin / Ditolak Admin, Diganti / Tidak Diganti, Alasan Penolakan), info "Unit akan ditarik ke gudang saat serah terima." atau "Unit tetap digunakan karyawan; hanya kelengkapan rusak yang diserahkan.", Histori Unit Pengganti ("Pengganti ke-{urutan}"). - aksi.pelepasan → Konfirmasi Serah Terima (info serah terima + dialog "Pastikan item rusak sudah diserahkan kepada Admin/HR."). - aksi.pelepasan_checklist (bersama aksi.pelepasan) → Checklist Unit Pengganti tampil di bawah histori pengganti dan tombol menjadi Serah Terima & Kirim Checklist (satu langkah; checklist dikirim lewat pelepasan). aksi.checklist (alur lama) → Checklist Unit Pengganti (Normal/Rusak per komponen + keterangan) → Terima & Kirim Checklist.

Alur status: di bawah header tampil AssetAlurStepper.kerusakan (Laporan → Review → Serah Terima → Selesai; disembunyikan bila laporan ditolak) dan kartu aset AssetKerusakanTimelineCard berisi timeline vertikal: Laporan (tanggal, jumlah item, keterangan) · Review (jumlah item disetujui/ditolak, jadwal; chip Ditolak) · Serah Terima (tanggal diserahkan, status unit utama, unit pengganti + hasil checklist; chip Checklist Rusak) · Selesai (unit pengganti). Checklist unit pengganti memakai komponen bersama AssetKondisiChecklist (kartu berikon, pilihan Normal / Rusak berwarna hijau/merah, keterangan muncul saat Rusak). File: Shared/Widgets/AssetAlurWidgets.dart, Shared/Widgets/AssetKerusakanTimeline.dart, Shared/Widgets/AssetFormWidgets.dart.

26.4 Detail admin

• Kartu Data Karyawan menampilkan tiga baris berurutan: Jabatan, Cabang, Departemen (label "Divisi" diganti "Departemen"; nilai kosong tampil -). Mobile (AssetKerusakanKaryawan.jabatan) membaca karyawan.jabatan lalu karyawan.nama_jabatan, sedangkan cabang/divisi dari karyawan. API: AssetRusakKaryawan_m::getDetail (endpoint detail admin Kerusakan) menambah karyawan.jabatan lewat join master_jabatan (data_karyawan.id_jabatan); '' bila jabatan kosong.
• aksi.review: per item Tolak (+Alasan Penolakan) / Setujui → Diganti / Tidak Diganti; bila unit utama diganti → Pilih Unit Pengganti ("Tidak ada unit pengganti yang tersedia untuk kategori ini."); Simpan Review → sheet Jadwal Serah Terima (tanggal mulai hari ini, jam, catatan) bila ada yang disetujui.
• aksi.ubah_jadwal → Ubah Jadwal.
• aksi.selesai (hanya laporan lama) → info "Seluruh item unit pengganti normal." + Selesaikan Laporan (dialog "Unit pengganti akan menjadi asset aktif karyawan.").
• aksi.ganti_pengganti → info "Unit pengganti masih memiliki item rusak. Pilih unit pengganti lain." + Pilih Pengganti Lain → pilih unit + jadwal.

Stepper dan kartu timeline sama seperti §26.3.

26.5 Entry point

Asset Saya: menu Kerusakan + banner Serah Terima Asset Rusak / Checklist Unit Pengganti. Asset Karyawan (admin): aksi Kerusakan + panel Kerusakan Perlu Diproses.

27Mobile → API

28API → Mobile

29Mapping Mobile → API → Database

30Mapping Database → API → Mobile

31Validation

31.1 Mobile

31.2 Backend — §9 & §24.

31.3 Database — enum status_transaksi, status_checklist, approval_item; jenis_log enum ditambah rusak_karyawan.

32Error Handling

33Audit Trail

34Notification

35Security

36Manual Book User/Admin

A. Karyawan — Melapor Kerusakan

1. Asset Saya → Kerusakan → Lapor Kerusakan.
2. Pilih Asset yang Rusak (hanya asset aktif yang tidak sedang diproses).
3. Pilih Unit Utama atau Kelengkapan, centang item yang rusak, isi Keterangan Kerusakan setiap item.
4. Isi Atribut Lainnya / Keterangan Umum bila perlu → Kirim Laporan.

B. Admin — Review

1. Asset Karyawan → Kerusakan → pilih laporan (tab Pengajuan).
2. Setiap item: Tolak (isi alasan) atau Setujui lalu Diganti / Tidak Diganti.
3. Bila unit utama diganti → Pilih Unit Pengganti (kategori sama).
4. Simpan Review → isi Jadwal Serah Terima (tanggal, jam, catatan).

C. Karyawan — Serah Terima

1. Pada jadwal, serahkan item rusak ke Admin/HR (dan terima unit pengganti bila ada).
2. Detail → Konfirmasi Serah Terima.

D. Karyawan — Serah Terima + Checklist Unit Pengganti

Detail → isi kondisi Normal/Rusak tiap komponen unit pengganti → Serah Terima & Kirim Checklist (satu langkah dengan serah terima).

E. Admin — Menyelesaikan

• Checklist normal → laporan selesai otomatis: unit pengganti menjadi asset karyawan (admin hanya mendapat notifikasi).
• Checklist rusak → Pilih Pengganti Lain + jadwal baru; ulangi C–E.
• Sebelum serah terima, jadwal dapat diubah dengan Ubah Jadwal.

37Kondisi Button

38Testing Scenario

Test otomatis yang ada (AssetRusakKaryawanTest): test_options_only_list_used_assets_with_unit_and_kelengkapan_items, test_submit_stores_snapshot_without_changing_asset_status, test_submit_rejects_foreign_asset_invalid_item_and_duplicate_report, test_rejecting_every_item_closes_report_without_touching_asset, test_replacement_must_be_available_and_same_category, test_full_replacement_loop_until_replacement_is_normal, test_kelengkapan_replaced_needs_no_replacement_unit, test_kelengkapan_without_replacement_keeps_unit_with_employee, test_unit_utama_without_replacement_is_withdrawn, test_employee_routes_submit_report_and_notify_admin.

39Temuan Ketidaksesuaian

40Edge Case

41Potential Bug / Technical Risk

RISK-001 — Laporan kerusakan aktif dicek Retur dan Offboarding (SELESAI)

Lokasi: AssetRusakKaryawan_m::hasActiveRusakAsset dipanggil oleh AssetUpgradeKaryawan_m, AssetPemeliharaanKaryawan_m, dan — sejak v1.1 — AssetOffboardingKaryawan_m::assertNoCrossFlow ("Satu atau beberapa asset sedang diproses pada laporan kerusakan."). AssetReturKaryawan_m::store kini juga memanggilnya ("Satu atau beberapa asset sedang diproses pada laporan kerusakan."). Pengajuan pengembalian peminjaman tidak memerlukannya karena asset dipinjam tidak bisa dilaporkan rusak (BR-001). Masalah: Sebelumnya asset yang sedang dalam laporan kerusakan masih bisa diretur; kini ditolak saat ajukan retur. Recommendation: Tidak ada; risiko ditutup (terverifikasi 12 Okt 2026).

RISK-002 — Unit pengganti "mengambang" antara serah terima dan penyelesaian (SEDANG)

Setelah karyawan menerima pengganti dengan checklist rusak (menunggu_review_checklist; alur lama juga menunggu_checklist), asset_data pengganti masih proses @gudang. Offboarding tidak akan menarik unit itu, dan transaksi lain tidak melihatnya sebagai milik karyawan.

RISK-003 — Tidak ada pembatalan / kedaluwarsa (SEDANG)

Laporan tidak bisa dibatalkan karyawan maupun admin setelah dikirim/disetujui; pengganti yang direservasi tetap proses.

RISK-004 — Serah terima hanya oleh karyawan (SEDANG)

Admin tidak punya aksi untuk mencatat serah terima; karyawan nonaktif menghentikan alur.

RISK-005 — Tanggal nol 0000-00-00 (SEDANG)

Header memakai tanggal nol untuk jadwal kosong. ⚠️ Asumsi: bermasalah pada MySQL strict mode.

RISK-006 — Notifikasi di luar transaksi (RENDAH)

Dikirim setelah commit; kegagalan tidak membatalkan transaksi.

RISK-007 — Kapasitas penomoran (RENDAH)

3 digit/bulan untuk header & item; setiap pengganti ulang memakai satu nomor item.

42Dependency

Asset terpakai milik karyawan (Onboarding / Penambahan / Retur pengganti / Upgrade)
      ↓ komponen dari asset_data_item
Laporan Kerusakan (review → serah terima + checklist ↺ pengganti ulang → selesai otomatis) ──► Notifikasi
      ↓
asset_data (rusak @gudang / tetap / pengganti terpakai) + asset_trx_log rusak_karyawan

Aturan silang:
  - Kerusakan mengecek: kerusakan lain, Retur, Upgrade, Offboarding, Pemeliharaan PML01 (assetBlockMessage)
  - Dicek oleh: Upgrade, Offboarding, Pemeliharaan PML01, Retur (hasActiveRusakAsset)
  - Summary admin: kerusakan_perlu_proses / kerusakan_pending; Asset Saya: kerusakan[]

43Source Code Reference

44Developer Notes

• Satu laporan = satu asset; id_asset_data sama untuk semua item laporan (urutan 0).
• Komponen berasal dari asset_data_item.json_value (flag_spesifikasi 1/2); asset tanpa unit utama mendapat baris sintetis id_item = id_asset_data.
• kelengkapan_item berfungsi ganda: snapshot komponen (item laporan) dan hasil checklist (baris pengganti).
• Rantai pengganti: urutan_penggantian naik 1 tiap penggantian, parent_id menunjuk baris sebelumnya.
• Objek aksi di detail adalah sumber kebenaran tombol di mobile.
• Satu jadwal dipakai untuk pengambilan item rusak dan kedatangan pengganti.

45End-to-End Traceability

Karyawan: Laptop → Unit Utama → "Ada garis pada layar" → Kirim Laporan
  → AssetKerusakanRequest(idAssetData, items[{idItem, ketRusak}])
  → POST /asset/karyawan/rusak → store() → header KRY06-… (1, pengajuan) + item urutan 0
Admin: Setujui + Diganti + unit LPT-0020 + jadwal 30 Sep 10:00 → Simpan Review
  → review() → item disetujui/diganti, item pengganti urutan 1 (belum_dicek), LPT-0020 = proses, header 3/menunggu_pengambilan
Karyawan: Serah Terima & Kirim Checklist (semua Normal) → pelepasan(items)
  → LPT-0012 rusak @gudang + log; pengganti tgl_serah_terima; status_checklist normal
  → LPT-0020 terpakai @karyawan + log; header selesai (otomatis)
Admin: hanya menerima notifikasi kerusakan.selesai_otomatis
  → Mobile: badge "Selesai", Histori Unit Pengganti "Pengganti ke-1"

45.4 Walkthrough Lengkap dengan Contoh Data

Bagian ini mengikuti satu laporan kerusakan sampai unit pengganti diterima, langkah demi langkah: apa yang dilakukan pengguna di mobile, apa yang dikirim, apa yang diproses API, dan apa yang tersimpan di database. Data bersifat sintetis, tetapi format ID, nama kolom, urutan proses, label status, dan pesan diambil dari kode (AssetRusakKaryawan_m, AssetKaryawanRusak_c, AssetAdminRusak_c, AssetNotification).

Skenario: Sari melaporkan unit utama laptopnya rusak. Admin menyetujui dan memilih laptop pengganti. Saat serah terima, Sari mengecek unit pengganti pertama dan menemukan charger rusak, sehingga admin memilih pengganti kedua. Unit pengganti kedua dinyatakan normal dan laporan selesai otomatis.

Data awal

Company CMP001. Laporan dibuat 22 Oktober 2026, periode ID 202610. Belum ada laporan, log, atau notifikasi pada periode ini.

data_karyawan

asset_data (semua kategori Laptop, kondisi_awal = normal)

Komponen dibaca dari asset_data_item.json_value (flag_spesifikasi 1 = unit utama, 2 = kelengkapan).

Penomoran: header dan item id_company + YYYYMM + 3 digit, no_trx = KRY06-YYYYMMNNN; log dan notifikasi 5 digit. Satu laporan menyimpan item laporan (urutan_penggantian = 0) dan histori unit pengganti (urutan_penggantian ≥ 1) di tabel item yang sama.

Langkah 0 — Karyawan membuka form

Mobile: Asset Saya → Kerusakan → + → form Lapor Kerusakan Asset → AssetKerusakanApi.getOptions().

Dikirim

GET /asset/karyawan/rusak/options
Authorization: Bearer <access_token_sari>

Diproses API (AssetRusakKaryawan_m::getOptions): asset yang dipegang karyawan, berstatus terpakai (asset pinjaman tidak termasuk), tidak diblokir flow lain (laporan kerusakan lain, retur, upgrade, offboarding, pemeliharaan), beserta komponennya (komponenAssets).

Database: hanya SELECT.

Diterima mobile (ringkas)

{ "code": "SUCCESS", "message": "Opsi laporan kerusakan berhasil ditemukan.",
  "data": { "assets": [ {
    "id_asset_data": "CMP00120260100012", "kode_asset": "LPT-0012", "nama_asset": "Laptop 14 inch",
    "kategori_asset": "Laptop", "status_asset": "terpakai",
    "items": [
      { "id_item": "CMP001ITEM0101", "nama_item": "Laptop 14 inch", "jenis": "aset_utama", "detail": "RAM: 16 GB, SSD: 512 GB" },
      { "id_item": "CMP001ITEM0102", "nama_item": "Charger", "jenis": "kelengkapan", "detail": "Daya: 65 W" }
    ] } ] } }

Langkah 1 — Sari mengirim laporan

Mobile: Sari memilih laptop, memilih Unit Utama, mencentang "Laptop 14 inch", mengisi keterangan "Ada garis pada layar", lalu Kirim Laporan → AssetKerusakanApi.store. (Mobile membatasi satu jenis komponen per laporan; API menerima campuran.)

Dikirim

POST /asset/karyawan/rusak

{
  "id_asset_data": "CMP00120260100012",
  "keterangan": "Terjadi setelah update sistem",
  "items": [ { "id_item": "CMP001ITEM0101", "ket_rusak": "Ada garis pada layar" } ]
}

Diproses API (AssetKaryawanRusak_c::storeRusakSaya → AssetRusakKaryawan_m::store, satu DB::transaction) 1. Validasi: id_asset_data wajib; items minimal 1; id_item unik; ket_rusak wajib (maks 255); keterangan maks 1000. 2. lockCompany; findActiveKaryawan("KRY0009"). 3. Asset diambil FOR UPDATE: dipegang Sari dan berstatus terpakai; assetBlockMessage memastikan tidak ada flow lain yang aktif. 4. komponenAssets + normalizeReportItems: setiap id_item harus komponen asset itu. 5. Generate ID: header urutan 1 → CMP001202610001, no_trx = KRY06-202610001; item mulai urutan 1. 6. INSERT header (status_approval = 1, status_transaksi = pengajuan, jadwal nol) dan INSERT item laporan (urutan_penggantian = 0, snapshot komponen di kelengkapan_item dalam JSON). 7. asset_data tidak berubah. Notifikasi kerusakan.diajukan ke admin.

Hasil database

asset_trx_rusak_karyawan

asset_trx_rusak_karyawan_item

notif_data (2 baris, satu per admin)

Diterima mobile (HTTP 201)

{ "code": "CREATED", "message": "Laporan kerusakan asset berhasil dikirim.",
  "data": { "id": "CMP001202610001", "no_trx": "KRY06-202610001", "status_approval": 1,
            "status_transaksi": "pengajuan", "status_label": "Menunggu Review", "tab": "pengajuan" } }

Langkah 2 — Admin membuka detail dan memuat opsi pengganti

Mobile: notifikasi membuka detail admin (GET /asset/rusak-karyawan/CMP001202610001, aksi.review = true) lalu GET /asset/rusak-karyawan/CMP001202610001/options.

Diproses API (getPenggantiOptions): asset tersedia di gudang dengan kategori sama dengan asset yang dilaporkan dan belum pernah dipakai di laporan ini (A20 dan A21 untuk kategori Laptop). Database: hanya SELECT.

Langkah 3 — Admin mereview dan memilih pengganti

Mobile: admin menekan Setujui pada item, memilih Diganti, memilih LPT-0020 sebagai Unit Pengganti, mengisi jadwal 23 Okt 2026 pukul 10:00, lalu Simpan Review → AssetKerusakanAdminApi.review.

Dikirim

POST /asset/rusak-karyawan/CMP001202610001/review

{
  "items": [ { "id_item": "CMP001202610001", "status_item": "disetujui", "ket_tolak": "", "status_diganti": "1" } ],
  "id_asset_pengganti": "CMP00120260100020",
  "tgl_serah_terima": "2026-10-23",
  "jam_serah_terima": "10:00",
  "keterangan_serah_terima": "Ambil di ruang IT"
}

Diproses API (AssetAdminRusak_c::reviewRusakKaryawan → review) 1. Validasi items (id unik, status_item ∈ disetujui/ditolak, ket_tolak wajib bila ditolak, status_diganti 0/1 wajib bila disetujui); format tanggal Y-m-d dan jam H:i. Cek admin, lockCompany. 2. Header harus status_approval = 1 ("Laporan kerusakan sudah direview."); seluruh item laporan harus diputuskan. 3. Asset yang dilaporkan harus masih dipegang Sari ("Asset sudah tidak dipegang oleh karyawan."). 4. Ada item disetujui → jadwal wajib, tanggal tidak boleh sebelum tgl_pengajuan. 5. Unit utama diganti → lockReplacementCandidate: pengganti wajib dipilih, belum dipakai di laporan ini, tersedia @gudang, kategori sama (kategori pengganti dibandingkan dengan asset_data.id_asset_kategori_m asset rusak). Memilih pengganti padahal unit utama tidak diganti ditolak. 6. UPDATE item (status_approval, status_diganti); insertReplacement (urutan 1, parent_id = item laporan, status_approval = disetujui, status_checklist = belum_dicek) dan UPDATE asset_data A20 → proses. 7. UPDATE header: status_approval = 3, status_transaksi = menunggu_pengambilan, jadwal, flag_jadwalkan, approval. 8. Notifikasi kerusakan.disetujui ke karyawan.

Hasil database

Diterima mobile (HTTP 200)

{ "code": "UPDATED", "message": "Review laporan kerusakan berhasil disimpan.",
  "data": { "id": "CMP001202610001", "no_trx": "KRY06-202610001", "status_approval": 3,
            "status_transaksi": "menunggu_pengambilan", "status_label": "Menunggu Serah Terima", "tab": "proses",
            "jumlah_disetujui": 1, "jumlah_ditolak": 0, "perlu_pengganti": true } }

Admin masih bisa Ubah Jadwal (API-005, PUT …/jadwal) selama status menunggu_pengambilan; notifikasi kerusakan.dijadwalkan ke karyawan.

Langkah 4 — Sari menyerahkan laptop rusak dan mengecek pengganti pertama

Mobile: banner Serah Terima Asset Rusak → detail. Karena aksi.pelepasan_checklist = true, tombol Serah Terima & Kirim Checklist menampilkan checklist komponen unit pengganti. Sari menandai Laptop Normal dan Charger Rusak ("Kabel charger terkelupas") → AssetKerusakanApi.pelepasan(id, items).

Dikirim

POST /asset/karyawan/rusak/CMP001202610001/pelepasan

{
  "items": [
    { "id_item": "CMP001ITEM0201", "kondisi": "normal", "ket_rusak": "" },
    { "id_item": "CMP001ITEM0202", "kondisi": "rusak", "ket_rusak": "Kabel charger terkelupas" }
  ]
}

Diproses API (AssetKaryawanRusak_c::pelepasanRusakSaya → pelepasan) 1. lockCompany; karyawan aktif; header milik Sari, status harus menunggu_pengambilan ("Laporan kerusakan belum siap diserahterimakan."). 2. Pengganti terbaru yang belum diterima = …002. 3. Karena tgl_pelepasan masih kosong → releaseOriginalAsset: asset dilaporkan harus masih dipegang Sari. Unit utama disetujui → A12 menjadi rusak, gudang, id_pemegang_asset = ''; ket_rusak = ringkasan "nama: keterangan" item disetujui (maks 255); INSERT asset_trx_log. (Bila hanya kelengkapan yang disetujui, asset tetap dipegang karyawan dan hanya ket_rusak yang terisi.) 4. UPDATE tgl_serah_terima pengganti …002 = sekarang. 5. applyChecklist: semua komponen pengganti wajib dicek (jumlah dan ID harus sama), kondisi ∈ normal/rusak, rusak wajib keterangan. Hasil disimpan sebagai JSON di kelengkapan_item; status_checklist = rusak karena ada satu komponen rusak; ket_rusak = ringkasan komponen rusak; tgl_checklist. 6. settleChecklist: checklist rusak → header menunggu_review_checklist (pengganti tidak diserahkan ke Sari). Checklist normal akan langsung menyelesaikan laporan (lihat langkah 6). 7. UPDATE header: tgl_pelepasan dan user_pelepasan (hanya sekali), status_transaksi. 8. Notifikasi kerusakan.checklist ke admin. Checklist tidak lengkap membatalkan seluruh transaksi, termasuk pelepasan asset lama.

Hasil database

asset_trx_log (1 baris)

notif_data (2 baris ke admin): CMP00120261000004 (KRY0099) dan CMP00120261000005 (KRY0100), rute asset_admin_detail_kerusakan, "Sari Contoh telah mengirim checklist unit pengganti KRY06-202610001."

Diterima mobile (HTTP 200): status_transaksi = menunggu_review_checklist, status_label = "Menunggu Review Checklist", status_checklist = "rusak", message "Serah terima asset rusak berhasil dikonfirmasi.".

Langkah 5 — Admin memilih pengganti lain

Mobile: detail admin menampilkan aksi.ganti_pengganti = true. Admin memilih Pilih Pengganti Lain → LPT-0021, jadwal 24 Okt 2026 pukul 09:00 → AssetKerusakanAdminApi.gantiPengganti.

Dikirim

POST /asset/rusak-karyawan/CMP001202610001/ganti-pengganti

{ "id_asset_pengganti": "CMP00120260100021", "tgl_serah_terima": "2026-10-24",
  "jam_serah_terima": "09:00", "keterangan_serah_terima": "" }

Diproses API (gantiPengganti) 1. Cek admin; header harus menunggu_review_checklist dan pengganti terbaru harus punya checklist rusak ("Seluruh item unit pengganti normal. Selesaikan laporan." bila normal). 2. Pengganti lama (A20) harus masih proses @gudang ("Status asset pengganti sudah berubah."). 3. Jadwal wajib; pengganti baru dipilih dengan lockReplacementCandidate: belum dipakai di laporan ini (A12 dan A20 dikecualikan), tersedia @gudang, kategori sama. 4. UPDATE A20 → rusak, gudang, ket_rusak = ringkasan checklist; INSERT asset_trx_log (gudang → gudang). 5. INSERT item pengganti baru (urutan_penggantian = 2, parent_id = pengganti sebelumnya) dan UPDATE A21 → proses. 6. UPDATE header → menunggu_pengambilan dengan jadwal baru. 7. Notifikasi kerusakan.pengganti_ulang ke karyawan.

Hasil database

asset_trx_log (1 baris baru): CMP00120261000002, A20, rusak_karyawan, kondisi normal → rusak, posisi gudang → gudang, user_input = ADM-001 - Siti Admin.

notif_data: CMP00120261000006 ke KRY0009, rute asset_detail_kerusakan, "Unit pengganti baru untuk KRY06-202610001 telah dijadwalkan."

Diterima mobile (HTTP 200): status_transaksi = menunggu_pengambilan, urutan_penggantian = 2, message "Unit pengganti baru berhasil dipilih.".

Langkah 6 — Sari menerima pengganti kedua dan laporan selesai

Mobile: banner Serah Terima Asset Rusak muncul lagi. Sari mengecek komponen unit pengganti kedua; semuanya Normal → Serah Terima & Kirim Checklist.

Dikirim

POST /asset/karyawan/rusak/CMP001202610001/pelepasan

{
  "items": [
    { "id_item": "CMP001ITEM0301", "kondisi": "normal", "ket_rusak": "" },
    { "id_item": "CMP001ITEM0302", "kondisi": "normal", "ket_rusak": "" }
  ]
}

Diproses API (pelepasan, panggilan kedua) 1. Status menunggu_pengambilan; tgl_pelepasan sudah terisi, sehingga tidak ada pelepasan asset lama lagi; yang diproses hanya pengganti terbaru (…003). Bila tidak ada pengganti yang menunggu, 422 "Tidak ada unit pengganti yang perlu diserahterimakan.". 2. UPDATE tgl_serah_terima pengganti …003; applyChecklist → status_checklist = normal. 3. settleChecklist → completeReplacement: lockReservedReplacement (A21 harus masih proses @gudang), UPDATE A21 → terpakai, karyawan, id_pemegang_asset = KRY0009, id_asset_lokasi_m = NULL; INSERT asset_trx_log; header → selesai. 4. tgl_pelepasan dan user_pelepasan tidak ditimpa (hanya pertama kali). 5. Notifikasi kerusakan.selesai_otomatis ke admin (admin hanya diberi tahu; tidak ada langkah Selesaikan).

Hasil database

asset_trx_log (1 baris baru): CMP00120261000003, A21, rusak_karyawan, kondisi_awal → normal, posisi gudang → karyawan, id_pemegang KRY0009, nama_pemegang Sari Contoh, user_input = EMP-009 - Sari Contoh.

notif_data: CMP00120261000007 (KRY0099) dan CMP00120261000008 (KRY0100), rute asset_admin_detail_kerusakan, "Unit pengganti KRY06-202610001 normal dan telah diterima Sari Contoh. Laporan selesai."

Diterima mobile (HTTP 200): status_approval = 3, status_transaksi = selesai, status_label = "Selesai", tab = "selesai", status_checklist = "normal". Laptop pengganti kini ada di Asset Saya Sari.

Kondisi akhir data

asset_trx_rusak_karyawan: CMP001202610001 / KRY06-202610001, status_approval = 3, status_transaksi = selesai, tgl_pelepasan = 2026-10-23 10:15:00.

asset_trx_rusak_karyawan_item

asset_data: A12 → rusak @gudang; A20 → rusak @gudang (ket_rusak = Charger: Kabel charger terkelupas); A21 → terpakai @KRY0009. asset_trx_log: 3 baris. notif_data: 8 baris. Histori seluruh percobaan penggantian tetap tersimpan sebagai item urutan ≥ 1.

Variasi

Semua item ditolak. Pada langkah 3, bila semua item ditolak (alasan wajib per item): status_approval = 2, status_transaksi = selesai, tanpa pengganti, jadwal tidak diminta, asset_data tidak berubah, notifikasi kerusakan.ditolak.

Tanpa pengganti. Bila item disetujui dengan status_diganti = 0, atau yang disetujui hanya kelengkapan: tidak ada pengganti. Pada serah terima pertama laporan langsung selesai (items checklist ditolak karena tidak ada unit pengganti: "Tidak ada unit pengganti yang perlu dicek."). Untuk unit utama, asset menjadi rusak @gudang; untuk kelengkapan saja, asset tetap dipegang karyawan dan hanya ket_rusak yang diisi (log: kondisi rusak, posisi karyawan → karyawan).

Checklist normal pada percobaan pertama. Pada langkah 4, bila semua komponen normal: pengganti pertama langsung terpakai @karyawan dan laporan selesai otomatis; langkah 5–6 tidak terjadi.

Alur lama (checklist terpisah). pelepasan tanpa items menghasilkan menunggu_checklist; karyawan lalu memanggil API-013 POST /asset/karyawan/rusak/{id}/checklist dengan format items yang sama. Untuk laporan lama yang menunggu review dengan checklist normal, admin memakai API-006 POST …/selesai.

Kasus gagal yang umum

Semua pelanggaran aturan dilempar sebagai InvalidArgumentException di dalam DB::transaction, sehingga seluruh perubahan request itu dibatalkan. Pesan tersedia dalam bahasa Indonesia dan Inggris mengikuti header locale.

Ringkasan siapa mengerjakan apa

46Ringkasan Database Impact

47Checklist Implementasi

Database

• Kolom workflow & index (migration)
• Enum jenis_log rusak_karyawan
• Selaraskan DBML
• Migration CREATE TABLE baseline

Backend

• Lapor per komponen, review, jadwal, serah terima, checklist, penggantian berulang
• Cek flow lain saat lapor
• Test otomatis (10)
• Cek laporan kerusakan aktif di Offboarding (v1.1)
• Cek laporan kerusakan aktif di Retur, Pengembalian Peminjaman
• Pembatalan / kedaluwarsa laporan
• Aksi admin untuk serah terima
• Pindahkan pemegang pengganti saat serah terima

Mobile

• List, form, detail, review, jadwal, checklist, pengganti ulang
• Banner Asset Saya & panel admin
• Selaraskan aturan satu jenis per laporan dengan backend

Documentation

• Business Flow, DB, API, Mobile, Mapping, Manual Book, Testing
• Screenshot

48Changelog