Upgrade Asset Karyawan

01Informasi Dokumen

03Quick Overview

Jalur A: Karyawan pilih asset + atribut + detail upgrade + alasan + urgensi → Ajukan Upgrade
         Admin: Tolak (+alasan) ─────────────────────────────────── ditolak / selesai
                Setujui & Jadwalkan (jadwal pengambilan) ─┐
Jalur B: Admin pilih karyawan + asset + atribut + catatan + jadwal → Buat Upgrade ─┤
                                                          menunggu_pengambilan ◄────┘
Karyawan: Serahkan Aset (tanpa checklist) ─────── dalam_service · asset = dalam_perbaikan (pemegang tetap karyawan)
Admin: Hasil Upgrade (Selesai / Tidak Dapat Diupgrade, nilai baru, biaya, keterangan) + jadwal pengembalian
                                                          menunggu_pengembalian
Karyawan: Terima Aset (tanpa checklist) ─────────────── selesai
          → atribut diperbarui (bila berhasil), asset = terpakai, log gudang → karyawan

04Ringkasan Fitur

Upgrade Asset dipakai untuk meningkatkan spesifikasi komponen asset yang dipegang karyawan tanpa mengganti unitnya. Yang diupgrade adalah atribut spesifikasi (misalnya "RAM", "Storage") yang tersimpan sebagai field komponen di asset_data_item (unit utama maupun kelengkapan).

Ada dua jalur masuk: karyawan mengajukan (dengan alasan dan urgensi) lalu admin menyetujui atau menolak, atau admin langsung membuat upgrade untuk karyawan tertentu. Setelah disetujui dan dijadwalkan, karyawan menekan Serahkan Aset, teknisi mengerjakan di luar sistem, admin mencatat hasil beserta jadwal pengembalian, lalu karyawan menekan Terima Aset. Sejak v1.4 tidak ada lagi checklist kondisi (pengambilan maupun penerimaan), tidak ada review akhir admin, dan tidak ada kirim ulang ke teknisi: tombol Terima Aset langsung menyelesaikan transaksi.

Selama proses, pemegang asset tetap karyawan; hanya status_asset yang berubah menjadi dalam_perbaikan.

05Tujuan Fitur

5.1 Tujuan Bisnis (diturunkan dari kode)

• Karyawan dapat meminta peningkatan spesifikasi asset kerja.
• Admin dapat menjadwalkan upgrade secara proaktif.
• Biaya dan hasil upgrade terdokumentasi.
• Data spesifikasi asset otomatis terbarui setelah upgrade berhasil dan karyawan menerima asset kembali.
• Sejak v1.4 kondisi fisik komponen sebelum dan sesudah upgrade tidak lagi dicatat di sistem (checklist dihapus).

5.2 Tujuan Sistem

• Menyimpan atribut target beserta nilai lama/baru per item.
• Menandai asset dalam_perbaikan selama service dan mengembalikannya ke terpakai.
• Menulis nilai baru ke asset_data_item.json_value.
• Mencegah asset diproses di upgrade lain, kerusakan, retur, atau offboarding saat upgrade dibuat.

06Aktor

07Hak Akses

Karyawan lain maupun PIC tidak dapat menyerahkan atau menerima upgrade milik orang lain: lockHeader memfilter id_karyawan, sehingga transaksi orang lain dijawab "Upgrade asset tidak ditemukan." (422).

08Terminologi

09Business Rules

BR-001 — Asset yang boleh diupgrade

Dipegang karyawan (pemegang_asset = karyawan, id_pemegang_asset = karyawan transaksi), status_asset = terpakai, dan memiliki minimal satu atribut spesifikasi → "Asset bukan milik karyawan atau tidak ditemukan." / "Hanya asset berstatus terpakai yang dapat diupgrade." Karyawan harus aktif → "Karyawan tidak ditemukan atau tidak aktif."

BR-002 — Asset tidak sedang di flow lain

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

BR-003 — Item atribut

Minimal 1; atribut harus milik asset; tanpa duplikat; detail upgrade wajib (≤255) → "Minimal satu komponen wajib dipilih." / "Komponen upgrade tidak ditemukan pada asset." / "Komponen yang sama tidak boleh dipilih lebih dari sekali." / "Detail upgrade setiap komponen wajib diisi." Snapshot atribut disimpan di kelengkapan_item (JSON) dan nilai_lama.

BR-004 — Jalur A (karyawan)

Alasan wajib (≤1000), urgensi wajib (normal/secepatnya/mendesak). Status awal proses / pengajuan.

BR-005 — Jalur B (admin)

Karyawan dipilih dari opsi (aktif & memegang asset yang dapat diupgrade), catatan opsional (≤1000), jadwal pengambilan wajib dengan tanggal ≥ hari ini. Status awal disetujui / menunggu_pengambilan, approval diisi admin pembuat. Notifikasi upgrade.disetujui ke karyawan.

BR-006 — Review (Jalur A)

Hanya saat status_approval = proses → "Pengajuan upgrade sudah direview."

• Tolak: alasan wajib → ditolak, status_transaksi = selesai, fase = selesai.
• Setujui: asset masih terpakai di karyawan; jadwal pengambilan wajib (≥ tanggal pengajuan) → disetujui, menunggu_pengambilan.

BR-007 — Jadwal

Format Y-m-d + H:i; tanggal ≥ tanggal pengajuan (Jalur B: ≥ hari ini) → "Tanggal dan jam serah terima wajib diisi." / "Format jadwal serah terima tidak valid." / "Tanggal serah terima tidak boleh sebelum tanggal pengajuan." Ubah jadwal hanya pada menunggu_pengambilan (jadwal pengambilan) atau menunggu_pengembalian (jadwal pengembalian) → "Jadwal hanya dapat diubah sebelum serah terima dilakukan." Kolom keterangan_pengembalian dipakai untuk catatan kedua jadwal.

BR-008 — (Dihapus v1.4) Checklist pengambilan oleh admin

Aturan lama (admin wajib mengisi checklist semua komponen sebelum karyawan boleh menyerahkan) sudah dihapus. Endpoint POST /asset/upgrade-karyawan/{id}/checklist-pengambilan (API-007) tidak ada lagi dan karyawan dapat menyerahkan asset begitu fase menunggu_pengambilan. Nomor BR-008 dipertahankan agar rujukan lama tidak bergeser.

BR-009 — Serahkan aset / pelepasan (karyawan)

Hanya pada fase menunggu_pengambilan → "Aset belum siap diserahkan untuk upgrade." Tanpa syarat checklist dan tanpa body request.

• Karyawan harus aktif dan pemilik transaksi (lockHeader memfilter id_karyawan; transaksi orang lain → "Upgrade asset tidak ditemukan.").
• Asset harus masih dipegang karyawan transaksi (terpakai atau dalam_perbaikan) → "Status asset sudah berubah atau tidak lagi dipegang karyawan."
• Asset → status_asset = dalam_perbaikan (pemegang tetap karyawan), log upgrade_karyawan posisi karyawan → gudang. Fase → dalam_service, tgl_pelepasan dan user_pelepasan diisi.

BR-010 — Hasil upgrade (admin)

Hanya dalam_service → "Aset belum berada dalam proses upgrade."

• status_hasil: selesai / tidak_dapat_diupgrade; keterangan hasil wajib (≤1000); biaya ≥ 0.
• selesai: nilai baru setiap atribut wajib → "Nilai baru setiap atribut wajib diisi."
• tidak_dapat_diupgrade: nilai_baru dikosongkan, alasan_tidak_upgrade = keterangan (≤255).
• Jadwal pengembalian wajib. Fase → menunggu_pengembalian; tgl_diterima direset. (Sejak v1.4 tidak ada lagi checklist penerimaan yang direset.)

BR-011 — Terima aset (karyawan) — langsung menyelesaikan

Hanya menunggu_pengembalian → "Aset belum dijadwalkan untuk dikembalikan." Tanpa checklist dan tanpa body. Karyawan harus aktif dan pemilik transaksi; asset harus dalam_perbaikan di karyawan → "Status asset sudah berubah atau tidak lagi dipegang karyawan."

• Bila status_hasil = selesai: nilai baru setiap item ditulis ke asset_data_item.json_value (applyAtribut). Bila tidak_dapat_diupgrade: atribut tidak berubah.
• Asset → terpakai; log upgrade_karyawan gudang → karyawan.
• Header: fase_upgrade = selesai, status_transaksi = selesai, tgl_diterima = now.
• Memanggil Terima sekali lagi (fase sudah selesai) ditolak dengan pesan yang sama: "Aset belum dijadwalkan untuk dikembalikan."

BR-012 — (Dihapus v1.4) Review akhir admin (Selesaikan / Kirim Ulang)

Aksi admin Selesaikan Upgrade dan Kirim Ulang ke Teknisi beserta endpoint POST /asset/upgrade-karyawan/{id}/selesai (API-009) sudah dihapus; penyelesaian terjadi otomatis pada BR-011. Siklus ulang kirim ulang tidak ada lagi. Fase menunggu_review tidak dihasilkan lagi (konstanta dan label dipertahankan hanya untuk data lama, lihat BR-015).

BR-013 — Penomoran

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

BR-014 — Kondisi saat serah terima tidak tercatat (v1.4)

Karena checklist dihapus, asset_trx_log selalu menulis kondisi_akhir = kondisi_awal (nilai asset_data.kondisi_awal). Kerusakan yang ditemukan saat pengambilan atau penerimaan harus dilaporkan lewat alur Kerusakan (KRY06), bukan lewat Upgrade.

BR-015 — Data lama pada fase menunggu_review (v1.4)

Transaksi yang sudah berhenti di menunggu_review sebelum v1.4 tidak memiliki aksi lagi (aksi semuanya false) dan asetnya tetap dalam_perbaikan (terkunci). Penyelesaiannya satu kali lewat skrip Claude outputs/sql-upgrade-hapus-checklist-review-lama.sql (belum dijalankan). Lihat RISK-008.

10Business Flow

Jalur A
1. Karyawan: Asset Saya → Upgrade → (+) Ajukan Upgrade Asset
   → Pilih Asset → pilih atribut + Detail Upgrade → Alasan → Urgensi → Ajukan Upgrade   [Menunggu Persetujuan · notif admin]
2. Admin: Detail → Tolak (+Alasan Penolakan)                                             [Ditolak · notif karyawan]
          atau Setujui & Jadwalkan (Jadwal Pengambilan)                                  [Menunggu Pengambilan · notif karyawan]
Jalur B
1. Admin: Upgrade → (+) Buat Upgrade Asset → Pilih Karyawan → Pilih Asset → atribut + Detail Upgrade
   → Catatan → Jadwal Pengambilan → Buat Upgrade                                         [Menunggu Pengambilan · notif karyawan]
Lanjutan (kedua jalur)
3. Karyawan: Serahkan Aset (tanpa checklist)                                             [Dalam Service · notif admin]
4. Admin: Hasil Upgrade (Upgrade Selesai / Tidak Dapat Diupgrade, Nilai Baru, Keterangan, Biaya)
   → Simpan Hasil & Jadwalkan (Jadwal Pengembalian)                                      [Menunggu Pengembalian · notif karyawan]
5. Karyawan: Terima Aset (tanpa checklist) → langsung selesai,
   atribut diperbarui bila berhasil, asset terpakai                                      [Selesai · notif admin]
Admin dapat Ubah Jadwal selama Menunggu Pengambilan dan Menunggu Pengembalian.

11Flow Berdasarkan Role

11.1 Karyawan

1. Asset Saya → menu Upgrade → Upgrade Asset → Ajukan Upgrade.
2. Banner Asset Saya: Serahkan Aset untuk Upgrade ("{asset} siap diambil untuk diupgrade. Konfirmasi setelah diserahkan.") dan Terima Aset Hasil Upgrade ("{asset} selesai diupgrade. Cek kondisinya lalu terima."). Banner pelepasan muncul begitu fase menunggu_pengambilan (tanpa menunggu checklist).
3. Detail → Serahkan Aset (aksi.pelepasan) atau Terima Aset (aksi.terima). Keduanya hanya dialog konfirmasi, tanpa form checklist.

11.2 Admin Asset

1. Asset Karyawan → aksi Upgrade atau panel Upgrade Perlu Diproses ("{jumlah} upgrade menunggu tindakan Admin/HR."): review pengajuan dan input hasil.
2. Buat Upgrade untuk Jalur B.
3. Detail → Setujui & Jadwalkan / Tolak, Simpan Hasil & Jadwalkan, Ubah Jadwal. Admin tidak lagi mengisi checklist dan tidak ada tombol Selesaikan / Kirim Ulang.

11.3 System

Deteksi atribut, cek flow lain, update status asset, tulis nilai atribut (saat Terima), log, notifikasi.

12Flow Diagram

flowchart TD
    A1[Jalur A: Karyawan ajukan upgrade] --> R{Admin review}
    R -->|Tolak| T[Ditolak]
    R -->|Setujui + jadwal| P[Menunggu Pengambilan]
    B1[Jalur B: Admin buat upgrade + jadwal] --> P
    P --> S[Karyawan: Serahkan Aset, tanpa checklist]
    S --> D[Dalam Service, asset dalam_perbaikan]
    D --> H{Admin: Hasil Upgrade}
    H -->|Upgrade Selesai + nilai baru| K[Menunggu Pengembalian + jadwal]
    H -->|Tidak Dapat Diupgrade| K
    K --> G[Karyawan: Terima Aset, tanpa checklist]
    G --> F[Selesai: atribut diperbarui bila berhasil, asset terpakai]

13Sequence Diagram

sequenceDiagram
    actor K as Karyawan
    actor A as Admin
    participant M as Mobile
    participant CK as AssetKaryawanUpgrade_c
    participant CA as AssetAdminUpgrade_c
    participant U as AssetUpgradeKaryawan_m
    participant DB
    participant N as AssetNotification

    K->>M: Pilih asset, atribut, detail, alasan, urgensi
    M->>CK: POST /asset/karyawan/upgrade
    CK->>U: storeKaryawan()
    U->>DB: cek karyawan, asset terpakai, flow lain, INSERT header + item
    CK->>N: upgrade.diajukan (admin)
    A->>M: Setujui & Jadwalkan
    M->>CA: POST /asset/upgrade-karyawan/{id}/review
    CA->>U: review()
    U->>DB: UPDATE header disetujui, menunggu_pengambilan + jadwal
    CA->>N: upgrade.disetujui (karyawan)
    K->>M: Serahkan Aset (tanpa checklist)
    M->>CK: POST /asset/karyawan/upgrade/{id}/pelepasan
    CK->>U: pelepasan()
    U->>DB: asset dalam_perbaikan, INSERT asset_trx_log, fase dalam_service
    CK->>N: upgrade.dilepas (admin)
    A->>M: Hasil upgrade, nilai baru, biaya, jadwal pengembalian
    M->>CA: POST /asset/upgrade-karyawan/{id}/hasil
    CA->>U: hasil()
    U->>DB: UPDATE item nilai_baru, header menunggu_pengembalian
    CA->>N: upgrade.pengembalian (karyawan)
    K->>M: Terima Aset (tanpa checklist)
    M->>CK: POST /asset/karyawan/upgrade/{id}/terima
    CK->>U: terima()
    U->>DB: tulis nilai baru ke asset_data_item (bila berhasil), asset terpakai, INSERT asset_trx_log, fase selesai
    CK->>N: upgrade.diterima (admin, "Upgrade selesai.")

14Status Transaksi

Tiga kolom: status_approval (enum proses/disetujui/ditolak), fase_upgrade (enum, migration), status_transaksi (enum proses/selesai).

Detail API mengembalikan objek aksi yang kini hanya berisi: review, ubah_jadwal, pelepasan, hasil, terima. Kunci checklist_pengambilan dan selesai dihapus (juga field detail checklist_pengambilan, checklist_pengembalian, checklist_pengembalian_rusak).

15State Transition

stateDiagram-v2
    [*] --> pengajuan: Ajukan (Karyawan, Jalur A)
    [*] --> menunggu_pengambilan: Buat upgrade (Admin, Jalur B)
    pengajuan --> ditolak: Tolak (Admin)
    pengajuan --> menunggu_pengambilan: Setujui + jadwal (Admin)
    menunggu_pengambilan --> menunggu_pengambilan: Ubah jadwal (Admin)
    menunggu_pengambilan --> dalam_service: Serahkan aset (Karyawan)
    dalam_service --> menunggu_pengembalian: Input hasil + jadwal (Admin)
    menunggu_pengembalian --> menunggu_pengembalian: Ubah jadwal (Admin)
    menunggu_pengembalian --> selesai: Terima aset (Karyawan)
    ditolak --> [*]
    selesai --> [*]

Fase menunggu_review tidak ada pada diagram karena tidak dihasilkan lagi sejak v1.4; transaksi lama di fase itu hanya bisa diselesaikan lewat skrip SQL.

Status asset_data:

16Struktur Database

17Relasi Database

erDiagram
    ASSET_TRX_UPGRADE_KARYAWAN ||--o{ ASSET_TRX_UPGRADE_KARYAWAN_ITEM : "id_asset_trx_upgrade"
    ASSET_DATA ||--o{ ASSET_TRX_UPGRADE_KARYAWAN_ITEM : "id_asset_data"
    ASSET_DATA ||--o{ ASSET_DATA_ITEM : "id_asset_data"
    ASSET_DATA_ITEM ||--o{ ASSET_TRX_UPGRADE_KARYAWAN_ITEM : "kelengkapan_item.id_asset_data_item (JSON)"
    DATA_KARYAWAN ||--o{ ASSET_TRX_UPGRADE_KARYAWAN : "id_karyawan (logis)"
    ASSET_DATA ||--o{ ASSET_TRX_LOG : "id_asset_data"

    ASSET_TRX_UPGRADE_KARYAWAN {
        varchar id_asset_trx_upgrade_karyawan PK
        varchar no_trx
        enum sumber_pengajuan
        varchar urgensi
        enum status_approval
        enum fase_upgrade "menunggu_review hanya data lama"
        enum status_transaksi
        text checklist_pengambilan "tidak dipakai sejak v1.4"
        text checklist_pengembalian "tidak dipakai sejak v1.4"
        enum status_hasil
        bigint biaya_upgrade
    }
    ASSET_TRX_UPGRADE_KARYAWAN_ITEM {
        varchar id_asset_trx_upgrade_item PK
        varchar id_asset_trx_upgrade FK
        varchar id_asset_data FK
        text kelengkapan_item
        varchar detail_upgrade
        varchar nilai_lama
        varchar nilai_baru
        varchar alasan_tidak_upgrade
    }
    ASSET_DATA {
        varchar id_asset_data PK
        enum status_asset
        enum pemegang_asset
    }
    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_upgrade_karyawan

18.2 asset_trx_upgrade_karyawan_item

18.3 asset_trx_log (jenis_log = upgrade_karyawan)

Sejak v1.4 kondisi_akhir selalu sama dengan kondisi_awal (nilai asset_data.kondisi_awal): kondisi saat serah terima tidak lagi tercatat karena checklist dihapus.

19Database Index

20Backend Architecture

RouteAsset.php (prefix /asset, jwt.api + jwt.ctx)
   ↓
AssetAdminUpgrade_c (validateRequest → mutateAssetTrx 'id_upgrade' / storeUpgradeKaryawan)
AssetKaryawanUpgrade_c (validateRequest → storeUpgradeSaya / mutateTrxSaya 'id_upgrade')
   ↓
AssetUpgradeKaryawan_m ← Asset_m (lockCompany, nextSequence, komponenAssets, parseJadwalValue,
   ↓                               insertAssetLog, findActiveKaryawan, findAssetAdmin)
   ↓   ↔ AssetRusakKaryawan_m / AssetReturKaryawan_m / AssetOffboardingKaryawan_m (cek flow lain)
DB::transaction (retry 3) → ApiResponse + AssetNotification

21Backend Business Logic

21.1 Ajukan (Jalur A) — storeKaryawan

Lock → karyawan aktif → urgensi & alasan → insertTransaction (asset milik karyawan FOR UPDATE, terpakai, assetBlockMessage, atributAssets, normalizeItems, INSERT header proses/pengajuan + item dengan nilai_lama) → upgrade.diajukan.

21.2 Buat (Jalur B) — storeAdmin

Lock → admin → karyawan aktif → jadwal (≥ hari ini) → insertTransaction dengan disetujui/menunggu_pengambilan, jadwal, approval admin → upgrade.disetujui.

21.3 Review — review

Admin → header proses → tolak (alasan wajib → ditolak/selesai) atau setujui (asset terpakai di karyawan, jadwal wajib → disetujui/menunggu_pengambilan) → upgrade.ditolak / upgrade.disetujui.

21.4 Ubah jadwal — updateJadwal

Fase menunggu_pengambilan → kolom pengambilan; menunggu_pengembalian → kolom pengembalian → upgrade.dijadwalkan.

21.5 (Dihapus v1.4) Checklist pengambilan — checklistPengambilan

Method model, method controller (checklistPengambilanUpgrade), rute, dan notifikasi upgrade.checklist_pengambilan sudah dihapus. Helper bersama Asset_m::normalizeKondisiChecklist tetap ada karena dipakai modul lain (mis. PML01 dan Kerusakan), tetapi tidak lagi dipanggil oleh Upgrade Karyawan.

21.6 Serahkan — pelepasan

Karyawan aktif → lockHeader memfilter id_karyawan (milik orang lain → "Upgrade asset tidak ditemukan.") → fase harus menunggu_pengambilan (tidak ada lagi syarat checklist) → lockHeldAsset (terpakai/dalam_perbaikan, dipegang karyawan) → asset dalam_perbaikan + log (karyawan → gudang) → fase dalam_service, tgl/user_pelepasan → upgrade.dilepas.

21.7 Hasil — hasil

Admin → fase dalam_service → validasi status/keterangan/biaya/jadwal → UPDATE item (nilai_baru atau alasan_tidak_upgrade) → header menunggu_pengembalian + hasil + jadwal pengembalian, tgl_diterima = NULL → upgrade.pengembalian.

21.8 Terima (langsung selesai) — terima

Karyawan aktif → lockHeader memfilter id_karyawan → fase harus menunggu_pengembalian → lockHeldAsset (harus dalam_perbaikan di karyawan) → bila status_hasil = selesai: applyAtribut (update komponen[].value di asset_data_item.json_value untuk setiap id_komponen) → asset terpakai + log (gudang → karyawan) → header fase_upgrade = selesai, status_transaksi = selesai, tgl_diterima = now → upgrade.diterima ("… Upgrade selesai."). Tanpa body, tanpa checklist, satu DB::transaction.

21.9 (Dihapus v1.4) Review akhir — selesai

Method model selesai, method controller selesaiUpgradeKaryawan, rute POST /asset/upgrade-karyawan/{id}/selesai, aksi terima / kirim_ulang, dan notifikasi upgrade.selesai / upgrade.kirim_ulang sudah dihapus. Logika yang dulu ada di sini (applyAtribut, asset kembali terpakai, log gudang → karyawan, fase selesai) kini dijalankan oleh terima (21.8).

21.10 Query baca

• Opsi karyawan: asset terpakai miliknya, tidak diblokir flow lain, punya atribut (atribut[]), + daftar urgensi.
• Opsi admin: karyawan aktif yang memegang asset yang dapat diupgrade beserta assets[].
• List: tab pengajuan (approval proses), proses (disetujui & fase ≠ selesai), selesai (status_transaksi = selesai, termasuk ditolak).
• Detail: header, jadwal, hasil, biaya, karyawan, asset, items (nilai lama/baru), komponen, aksi. Field checklist_pengambilan, checklist_pengembalian, checklist_pengembalian_rusak tidak ada lagi. aksi = review, ubah_jadwal, pelepasan (fase menunggu_pengambilan), hasil (fase dalam_service), terima (fase menunggu_pengembalian).
• Pending: karyawan (pelepasan untuk fase menunggu_pengambilan, terima untuk menunggu_pengembalian; tanpa syarat checklist); admin (approval proses ATAU fase dalam_service).

22Dampak terhadap asset_data

23API Documentation

Penomoran API tidak digeser: API-007 dan API-009 tetap tercantum sebagai baris "dihapus v1.4" agar rujukan lama (walkthrough, changelog, dokumen lain) tetap terbaca. Endpoint yang aktif 13 (admin 7: API-001 sampai 006 dan 008; karyawan 6: API-010 sampai 015), dihitung dari API/routes/modules/asset/RouteAsset.php (grup upgrade-karyawan dan grup karyawan upgrade). Mengirim request ke rute yang sudah dihapus tidak cocok dengan rute mana pun sehingga dijawab 404 oleh router.

Terkait: GET /asset/karyawan/onboarding (Asset Saya, key upgrade) dan GET /asset/summary (upgrade_perlu_proses, upgrade_pending).

24Detail Setiap API

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

API-010 — Opsi (Karyawan)

{
  "code": "SUCCESS",
  "message": "Opsi upgrade asset berhasil ditemukan.",
  "data": {
    "assets": [
      {
        "id_asset_data": "CMP00120260100012",
        "kode_asset": "LPT-0012",
        "nama_asset": "Laptop 14 inch",
        "kategori_asset": "Laptop",
        "merek": "MerekX",
        "id_pemegang_asset": "KRY0010",
        "atribut": [
          {"id_atribut": "CMP001ITEM0101|ram", "id_asset_data_item": "CMP001ITEM0101", "id_komponen": "ram",
           "nama_item": "Laptop 14 inch", "jenis": "aset_utama", "label": "RAM", "satuan": "GB", "nilai": "8"}
        ]
      }
    ],
    "urgensi": [
      {"value": "normal", "label": "Normal"},
      {"value": "secepatnya", "label": "Secepatnya"},
      {"value": "mendesak", "label": "Mendesak"}
    ]
  }
}

API-001 (admin) mengembalikan { "karyawan": [ {id_karyawan, nik, nama_karyawan, assets: [...]} ] }.

API-012 — Ajukan (Jalur A)

POST /asset/karyawan/upgrade

{
  "id_asset_data": "CMP00120260100012",
  "alasan": "Aplikasi desain sering lambat",
  "urgensi": "secepatnya",
  "items": [
    {"id_atribut": "CMP001ITEM0101|ram", "detail_upgrade": "8 GB menjadi 16 GB"}
  ]
}

Pesan umum: "Data pengajuan upgrade belum lengkap."

{ "code": "CREATED", "message": "Pengajuan upgrade asset berhasil dikirim.",
  "data": { "id": "CMP001202609006", "no_trx": "KRY03-2-202609006", "status_approval": "proses",
            "fase_upgrade": "pengajuan", "status_label": "Menunggu Persetujuan", "tab": "pengajuan" } }

422: "Karyawan tidak ditemukan atau tidak aktif.", "Asset bukan milik karyawan atau tidak ditemukan.", "Hanya asset berstatus terpakai yang dapat diupgrade.", "Asset sedang diproses pada upgrade lain." / "…laporan kerusakan." / "…retur." / "…offboarding." / "…pemeliharaan.", "Komponen upgrade tidak ditemukan pada asset.", "Komponen yang sama tidak boleh dipilih lebih dari sekali." 500: "Terjadi kesalahan saat menyimpan pengajuan upgrade."

API-003 — Buat (Jalur B)

POST /asset/upgrade-karyawan

{
  "id_karyawan": "KRY0010",
  "id_asset_data": "CMP00120260100012",
  "catatan": "Program peremajaan laptop tim desain",
  "items": [{"id_atribut": "CMP001ITEM0101|ram", "detail_upgrade": "8 GB menjadi 16 GB"}],
  "tgl_jadwal": "2026-09-30",
  "jam_jadwal": "10:00",
  "keterangan_jadwal": "Bawa ke ruang IT"
}

Rules: id_karyawan required max 150, id_asset_data required, catatan nullable max 1000, items seperti API-012, jadwal tgl_jadwal (Y-m-d) / jam_jadwal (H:i) / keterangan_jadwal (≤255). Pesan umum: "Data upgrade asset belum lengkap." Response CREATED "Upgrade asset berhasil dibuat." (disetujui / menunggu_pengambilan). 500: "Terjadi kesalahan saat membuat upgrade asset."

API-002 / API-011 — List

tab: pengajuan | proses | selesai; limit 1–50. Record: id, no_trx, sumber_pengajuan, tgl_pengajuan, urgensi, status_approval, fase_upgrade, status_label, tab, tgl/jam_pengambilan, tgl/jam_pengembalian, jumlah_item, asset{nama_asset, kategori_asset}, karyawan{id_karyawan, nik, nama_karyawan} + filters, pagination.

API-004 / API-013 — Detail

{
  "id": "CMP001202609006",
  "no_trx": "KRY03-2-202609006",
  "sumber_pengajuan": "karyawan",
  "tgl_pengajuan": "2026-09-28",
  "alasan": "Aplikasi desain sering lambat",
  "urgensi": "secepatnya",
  "catatan": "",
  "ket_tolak": "",
  "status_approval": "disetujui",
  "fase_upgrade": "selesai",
  "status_label": "Selesai",
  "tab": "selesai",
  "tgl_pengambilan": "2026-09-30",
  "jam_pengambilan": "10:00:00",
  "tgl_pengembalian": "2026-10-03",
  "jam_pengembalian": "15:00:00",
  "keterangan_jadwal": "",
  "tgl_pelepasan": "2026-09-30 10:12:00",
  "tgl_diterima": "2026-10-03 15:20:00",
  "status_hasil": "selesai",
  "keterangan_hasil": "RAM ditambah 1 keping 8 GB",
  "biaya_upgrade": 650000,
  "karyawan": {"id_karyawan": "KRY0010", "nik": "EMP-010", "nama_karyawan": "Dimas Contoh", "cabang": "Kantor Pusat", "divisi": "Kreatif"},
  "asset": {"id_asset_data": "CMP00120260100012", "kode_asset": "LPT-0012", "nama_asset": "Laptop 14 inch", "kategori_asset": "Laptop", "merek": "MerekX", "status_asset": "terpakai"},
  "items": [
    {"id_item": "CMP001202609014", "nama_item": "Laptop 14 inch", "label": "RAM", "satuan": "GB",
     "detail_upgrade": "8 GB menjadi 16 GB", "nilai_lama": "8", "nilai_baru": "16", "alasan_tidak_upgrade": ""}
  ],
  "komponen": [{"id_item": "CMP001ITEM0101", "nama_item": "Laptop 14 inch", "jenis": "aset_utama", "detail": "RAM: 8 GB"}],
  "aksi": {"review": false, "ubah_jadwal": false, "pelepasan": false, "hasil": false, "terima": false}
}

404: "Upgrade asset tidak ditemukan."

Contoh di atas adalah transaksi yang sudah selesai (semua aksi bernilai false). Sejak v1.4 detail tidak lagi memuat checklist_pengambilan, checklist_pengembalian, checklist_pengembalian_rusak, dan aksi hanya berisi review, ubah_jadwal, pelepasan (fase menunggu_pengambilan), hasil (fase dalam_service), terima (fase menunggu_pengembalian).

API-005 — Review

{ "keputusan": "disetujui", "ket_tolak": "", "tgl_jadwal": "2026-09-30", "jam_jadwal": "10:00", "keterangan_jadwal": "" }

Rules: keputusan required in:disetujui,ditolak; ket_tolak required_if ditolak (≤255, "Alasan penolakan wajib diisi."). "Review upgrade asset berhasil disimpan." 422: "Pengajuan upgrade sudah direview.", "Status asset sudah berubah atau tidak lagi dipegang karyawan.", "Tanggal dan jam serah terima wajib diisi."

API-006 — Ubah Jadwal

{ "tgl_jadwal": "2026-10-01", "jam_jadwal": "09:00", "keterangan_jadwal": "" }

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

API-007 — Checklist Pengambilan (Admin) — DIHAPUS v1.4

POST /asset/upgrade-karyawan/{id}/checklist-pengambilan tidak ada lagi di RouteAsset.php; request ke rute ini dijawab 404. Nomor API-007 dipertahankan agar penomoran lain tidak bergeser.

API-014 — Serahkan Aset (Karyawan)

Tanpa body dan tanpa syarat checklist (v1.4). Karyawan harus pemilik transaksi dan fase menunggu_pengambilan. "Aset berhasil diserahkan untuk upgrade." 422: "Aset belum siap diserahkan untuk upgrade.", "Karyawan tidak ditemukan atau tidak aktif.", "Status asset sudah berubah atau tidak lagi dipegang karyawan.", "Upgrade asset tidak ditemukan." (transaksi milik karyawan lain / PIC).

API-015 — Terima Aset (Karyawan) — langsung menyelesaikan

POST /asset/karyawan/upgrade/{id}/terima

Tanpa body dan tanpa checklist (v1.4); bila body dikirim, isinya diabaikan. Satu request menyelesaikan transaksi: atribut diperbarui (bila status_hasil = selesai), asset terpakai, log gudang → karyawan, fase_upgrade = selesai, status_transaksi = selesai, tgl_diterima terisi.

{ "code": "UPDATED", "message": "Aset hasil upgrade berhasil diterima.",
  "data": { "id": "CMP001202610001", "no_trx": "KRY03-2-202610001", "status_approval": "disetujui",
            "fase_upgrade": "selesai", "status_label": "Selesai", "tab": "selesai" } }

422: "Aset belum dijadwalkan untuk dikembalikan." (fase bukan menunggu_pengembalian, termasuk pemanggilan kedua), "Status asset sudah berubah atau tidak lagi dipegang karyawan.", "Karyawan tidak ditemukan atau tidak aktif.", "Upgrade asset tidak ditemukan." (milik karyawan lain / PIC). Notifikasi upgrade.diterima ke admin.

API-008 — Hasil Upgrade (Admin)

{
  "status_hasil": "selesai",
  "keterangan_hasil": "RAM ditambah 1 keping 8 GB",
  "biaya_upgrade": 650000,
  "items": [{"id_item": "CMP001202609014", "nilai_baru": "16"}],
  "tgl_jadwal": "2026-10-03",
  "jam_jadwal": "15:00",
  "keterangan_jadwal": ""
}

"Hasil upgrade berhasil disimpan." 422: "Aset belum berada dalam proses upgrade.", "Nilai baru setiap atribut wajib diisi.", "Tanggal dan jam serah terima wajib diisi."

API-009 — Review Akhir (Admin) — DIHAPUS v1.4

POST /asset/upgrade-karyawan/{id}/selesai (aksi terima / kirim_ulang) tidak ada lagi; request ke rute ini dijawab 404. Penyelesaian transaksi kini dilakukan oleh API-015. Nomor API-009 dipertahankan agar penomoran lain tidak bergeser.

25Mobile Architecture

Page (admin: bool) → AssetUpgradeBloc → AssetUpgradeApi(admin) → ApiClient → Backend

Satu set layar dipakai admin dan karyawan; AssetUpgradeApi(admin: true) memakai base asset/upgrade-karyawan, selain itu asset/karyawan/upgrade.

26Mobile Screen

26.1 Upgrade Asset — list

Tab Pengajuan / Proses / Selesai; kartu dengan status (Menunggu Persetujuan, Menunggu Pengambilan, Dalam Service, Menunggu Pengembalian, Selesai, Ditolak), label "Diinisiasi Admin/HR" untuk Jalur B. Label "Menunggu Review" masih ada di kode hanya untuk menampilkan data lama. Kosong: "Belum ada data upgrade asset."

26.2 Ajukan Upgrade Asset (karyawan) / Buat Upgrade Asset (admin)

26.3 Detail Upgrade Asset

Stepper Pengajuan → Pengambilan → Service → Pengembalian → Selesai (tidak berubah; data lama fase menunggu_review ditampilkan pada langkah Pengembalian); info asset, karyawan, Jadwal Pengambilan / Jadwal Pengembalian ("{tanggal}, jam {jam}"), Komponen yang Diupgrade (Sebelum / Sesudah), Hasil Upgrade (Upgrade Selesai / Tidak Dapat Diupgrade, Keterangan Hasil, Biaya Upgrade (Rp)). Tidak ada lagi form atau tampilan checklist (pengambilan maupun penerimaan).

Tombol Simpan Checklist Pengambilan, Selesaikan Upgrade, dan Kirim Ulang ke Teknisi sudah dihapus dari layar. Tombol Serahkan / Terima kini mengikuti aksi.pelepasan / aksi.terima.

26.4 Entry point

Asset Saya: menu Upgrade + banner Serahkan Aset untuk Upgrade / Terima Aset Hasil Upgrade (banner pelepasan muncul sejak fase menunggu_pengambilan). Asset Karyawan: aksi Upgrade + panel Upgrade Perlu Diproses ("Lihat semua ({jumlah})"; isinya approval proses atau fase dalam_service).

27Mobile → API

Sejak v1.4 tidak ada lagi payload checklist (items[].kondisi, ket_rusak) maupun aksi review akhir (terima/kirim_ulang).

28API → Mobile

Field lama checklist_pengambilan, checklist_pengembalian, checklist_pengembalian_rusak, dan aksi.checklist_pengambilan / aksi.selesai diabaikan oleh model (ada test yang memastikan payload lama tetap bisa di-parse).

29Mapping Mobile → API → Database

Kolom checklist_pengambilan dan checklist_pengembalian tidak lagi dipetakan dari UI mana pun (tidak ditulis/dibaca sejak v1.4).

30Mapping Database → API → Mobile

31Validation

31.1 Mobile

31.2 Backend — §9 & §24.

31.3 Database — enum sumber_pengajuan, fase_upgrade, status_hasil, status_approval, status; jenis_log + upgrade_karyawan.

32Error Handling

33Audit Trail

34Notification

Event yang dihapus v1.4: upgrade.checklist_pengambilan, upgrade.selesai, upgrade.kirim_ulang. Karena karyawan menyelesaikan transaksi sendiri lewat Terima, karyawan tidak lagi menerima notifikasi "Upgrade Asset Selesai". Daftar di atas diambil dari AssetNotification.php (kunci upgrade.*; kunci upgrade_ruangan.* milik modul lain).

35Security

36Manual Book User/Admin

A. Karyawan — Mengajukan Upgrade

1. Asset Saya → Upgrade → Ajukan Upgrade.
2. Pilih Asset, centang spesifikasi pada Komponen yang Diupgrade, isi Detail Upgrade (contoh: "8 GB menjadi 16 GB").
3. Isi Alasan, pilih Urgensi → Ajukan Upgrade.

B. Admin — Membuat Upgrade Langsung

Upgrade → Buat Upgrade → Pilih Karyawan → Pilih Asset → komponen + detail → Catatan Tambahan → Jadwal Pengambilan → Buat Upgrade.

C. Admin — Menyetujui

Detail → Setujui & Jadwalkan (isi jadwal pengambilan) atau Tolak (isi alasan).

D. Pengambilan (Karyawan)

Pada jadwal pengambilan, karyawan membuka banner Serahkan Aset untuk Upgrade (atau detail upgrade) → Serahkan Aset → konfirmasi. Tidak ada checklist yang harus diisi admin maupun karyawan (v1.4); tombol langsung aktif begitu status Menunggu Pengambilan.

E. Hasil Upgrade (Admin)

Detail → pilih Upgrade Selesai (isi Nilai Baru tiap atribut) atau Tidak Dapat Diupgrade → Keterangan Hasil → Biaya Upgrade (Rp) → jadwal pengembalian → Simpan Hasil & Jadwalkan.

F. Pengembalian (Karyawan)

Terima aset dari teknisi/admin, periksa sendiri kondisinya, lalu buka banner Terima Aset Hasil Upgrade (atau detail) → Terima Aset → konfirmasi. Tidak ada checklist. Pada saat itu juga upgrade selesai: spesifikasi asset diperbarui (bila hasil berhasil) dan aset kembali aktif (terpakai).

G. Bila ada kerusakan saat serah terima

Kondisi komponen tidak lagi dicatat di Upgrade. Bila karyawan menemukan kerusakan setelah menerima aset, laporkan lewat fitur Kerusakan (KRY06). Tidak ada tombol Kirim Ulang ke Teknisi.

37Kondisi Button

38Testing Scenario

Test otomatis PHPUnit (API/tests/Asset/AssetUpgradeKaryawanTest.php): 5 test, 54 assertion, lulus pada 2026-10-30 (vendor/bin/phpunit tests/Asset/AssetUpgradeKaryawanTest.php, PHP 8.2.31, PHPUnit 10.5.45). Isi: test_options_list_spec_attributes_of_held_assets, test_employee_request_is_stored_and_can_be_rejected, test_full_upgrade_updates_attribute_and_returns_asset, test_failed_upgrade_keeps_attribute, test_employee_route_submits_request_and_notifies_admin.

Test otomatis Flutter (MOBILE/test/asset/asset_upgrade_test.dart): 5 test, lulus pada 2026-10-30 (flutter test --no-pub, Flutter 3.35.6): teks lokalisasi id/en lengkap; detail mem-parse item dan aksi serta mengabaikan field checklist lama; beranda dan summary menampilkan upgrade yang perlu tindakan; form ajukan mewajibkan detail komponen dan alasan; admin pada fase service wajib mengisi nilai baru per komponen.

Cakupan: TC-01, TC-03, TC-04, TC-06, TC-11, TC-12, TC-13, TC-14, TC-15, TC-20 dan perilaku aksi (TC-23 sebagian) diverifikasi oleh test PHPUnit di atas (alur penuh: aksi pelepasan sejak menunggu_pengambilan, pending admin hanya pada dalam_service, terima langsung selesai, log 2 baris). TC-16, TC-17, TC-22, TC-24 diturunkan dari kode dan routing, belum ada test otomatisnya; TC-24 bergantung pada skrip SQL yang belum dijalankan.

39Temuan Ketidaksesuaian

40Edge Case

41Potential Bug / Technical Risk

RISK-001 — Retur dan Offboarding mengecek upgrade aktif (SELESAI)

Lokasi: hasActiveUpgradeAsset dipanggil AssetRusakKaryawan_m, AssetPemeliharaanKaryawan_m, dan — sejak v1.1 — AssetOffboardingKaryawan_m::assertNoCrossFlow ("Satu atau beberapa asset sedang diproses pada upgrade."). AssetReturKaryawan_m::store kini juga memanggilnya ("Satu atau beberapa asset sedang diproses pada upgrade."). Masalah: Sebelumnya asset dalam_perbaikan (di teknisi, pemegang tetap karyawan) masih dapat diretur; kini ditolak saat ajukan retur. Recommendation: Tidak ada; risiko ditutup (terverifikasi 12 Okt 2026).

RISK-002 — Status asset tidak mencerminkan posisi fisik (SEDANG)

Pemegang tetap karyawan selama service. (Kasus status dalam_perbaikan setelah kirim ulang sudah tidak ada sejak v1.4.)

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

Setelah disetujui, upgrade tidak dapat dibatalkan; asset terus terkunci dari flow lain.

RISK-004 — Pembaruan atribut tanpa jejak terpisah (SEDANG)

applyAtribut (kini dipanggil saat karyawan menekan Terima) menimpa json_value; riwayat hanya ada di item transaksi (nilai lama/baru), bukan di log asset.

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

⚠️ 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 (satu item per atribut).

RISK-008 — Data lama di menunggu_review terkunci sampai SQL dijalankan (TINGGI, ketergantungan rilis)

Setelah v1.4 tidak ada aksi untuk transaksi yang sudah berada di fase menunggu_review (review akhir dihapus), sehingga asetnya tetap dalam_perbaikan dan terblokir dari flow lain. Penyelesaiannya satu kali lewat Claude outputs/sql-upgrade-hapus-checklist-review-lama.sql (menerapkan atribut bila hasil selesai, asset terpakai, log gudang → karyawan/ruangan, fase selesai; mencakup Upgrade Karyawan dan Upgrade Ruangan). Skrip BELUM dijalankan dan sintaksnya belum diuji di DB; jalankan dulu di salinan/staging, periksa guard 0.c, lalu COMMIT. Rilis v1.4 sebaiknya menunggu keputusan menjalankan skrip ini.

RISK-009 — Kondisi saat serah terima tidak lagi tercatat (SEDANG)

Tanpa checklist, kerusakan yang muncul sebelum atau sesudah upgrade tidak punya bukti di sistem; log aset selalu kondisi_akhir = kondisi_awal. Sengketa tanggung jawab antara karyawan, admin, dan teknisi tidak dapat dirunut dari data.

RISK-010 — Penyelesaian sepihak oleh karyawan (SEDANG)

Satu klik Terima Aset langsung mengubah spesifikasi asset dan status; tidak ada verifikasi admin. Nilai baru berasal dari input admin pada langkah Hasil, jadi risiko terutama pada waktu penerimaan (karyawan menekan Terima sebelum asset benar-benar kembali).

42Dependency

Asset terpakai milik karyawan + atribut spesifikasi di asset_data_item
      ↓
Upgrade (Jalur A / B → pengambilan → service → pengembalian → selesai) ──► Notifikasi
      ↓
asset_data (dalam_perbaikan ↔ terpakai), asset_data_item (nilai baru), asset_trx_log upgrade_karyawan

Aturan silang:
  - Upgrade mengecek: upgrade lain, Kerusakan, Retur, Offboarding, Pemeliharaan PML01
  - Dicek oleh: Kerusakan, Offboarding, Pemeliharaan PML01, Retur (hasActiveUpgradeAsset)
  - Summary admin: upgrade_perlu_proses / upgrade_pending; Asset Saya: upgrade[]
  - Helper bersama Asset_m::normalizeKondisiChecklist dan widget AssetKondisiChecklist tetap ada (dipakai modul lain), tidak dipakai Upgrade Karyawan

Ketergantungan rilis v1.4:
  - Skrip sql-upgrade-hapus-checklist-review-lama.sql (BELUM dijalankan) untuk transaksi lama di menunggu_review (Upgrade Karyawan dan Ruangan)
  - Aplikasi mobile lama yang masih memanggil .../checklist-pengambilan atau .../selesai menerima 404

43Source Code Reference

44Developer Notes

• Satu upgrade = satu asset; item = atribut (id_atribut = id_asset_data_item|id_komponen).
• Atribut diambil dari json_value.komponen[] dengan flag_spesifikasi 1/2, kecuali field bertipe file.
• applyAtribut mengelompokkan item per id_asset_data_item dan menulis value untuk setiap id_komponen yang punya nilai baru. Sejak v1.4 dipanggil dari terima() (bukan lagi dari selesai()), dengan pelaku karyawan.
• Satu set layar mobile untuk admin & karyawan (admin: bool); tombol ditentukan objek aksi (review, ubah_jadwal, pelepasan, hasil, terima).
• AssetUpgradeApi.terima(id) tidak lagi mengirim body; pelepasan(id) tetap tanpa body.
• Widget AssetKondisiChecklist dipertahankan karena dipakai modul lain; Upgrade Karyawan tidak memakainya.
• Jangan mengubah kolom/enum checklist_* dan menunggu_review tanpa persetujuan migrasi; data lama masih memakainya.
• Nomor transaksi memakai sufiks tipe -2 (tipe Upgrade Komponen); tipe KRY03 lainnya ⚠️ Belum ditemukan di kode.

45End-to-End Traceability

Karyawan: Laptop → atribut RAM (Saat ini: 8) → "8 GB menjadi 16 GB" → Ajukan Upgrade
  → POST /asset/karyawan/upgrade → storeKaryawan() → header KRY03-2-… (proses/pengajuan) + item nilai_lama "8"
Admin: Setujui & Jadwalkan 23 Okt 10:00 → review() → disetujui/menunggu_pengambilan
Karyawan: Serahkan Aset (tanpa checklist) → pelepasan() → asset dalam_perbaikan + log → dalam_service
Admin: Upgrade Selesai, Nilai Baru "16", biaya 650.000, jadwal 26 Okt → hasil() → item nilai_baru "16" → menunggu_pengembalian
Karyawan: Terima Aset (tanpa checklist) → terima() → asset_data_item RAM value "16", asset terpakai + log → selesai
  → Mobile: Sebelum 8 / Sesudah 16, badge "Selesai"

45.4 Walkthrough Lengkap dengan Contoh Data

Bagian ini mengikuti satu upgrade dari pengajuan sampai atribut diperbarui, 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 (AssetUpgradeKaryawan_m, AssetKaryawanUpgrade_c, AssetAdminUpgrade_c, AssetNotification). Sejak v1.4 walkthrough ini 6 langkah (langkah 0 sampai 5) karena checklist dan review akhir sudah tidak ada.

Skenario (Jalur A): Dimas mengajukan upgrade RAM laptopnya dari 8 GB ke 16 GB. Admin menyetujui dan menjadwalkan pengambilan, Dimas menyerahkan laptop (tanpa checklist), admin mencatat hasil upgrade beserta jadwal pengembalian, lalu Dimas menekan Terima Aset (tanpa checklist) dan upgrade langsung selesai: nilai RAM baru ditulis ke data komponen.

Data awal

Company CMP001. Pengajuan 22 Oktober 2026, periode ID 202610. Belum ada upgrade, log, atau notifikasi pada periode ini.

data_karyawan

asset_data: A12 CMP00120260100012 (LPT-0012), Laptop 14 inch, kategori Laptop (CMP001202601002), status_asset = terpakai, pemegang_asset = karyawan, id_pemegang_asset = KRY0010, kondisi_awal = normal.

asset_data_item milik A12 (json_value, hanya yang flag_spesifikasi 1 atau 2 yang bisa dipilih)

Setiap field komponen (kecuali bertipe file) menjadi satu atribut dengan id_atribut = id_asset_data_item|id_komponen, misalnya CMP001ITEM0101|ram.

Penomoran: header dan item id_company + YYYYMM + 3 digit, no_trx = KRY03-2-YYYYMMNNN; log dan notifikasi 5 digit. Selama proses, pemegang_asset tetap karyawan; hanya status_asset yang berubah (dalam_perbaikan).

Langkah 0 — Karyawan membuka form

Mobile: Asset Saya → Upgrade → + → form Ajukan Upgrade Asset → AssetUpgradeApi.getOptions().

Dikirim

GET /asset/karyawan/upgrade/options
Authorization: Bearer <access_token_dimas>

Diproses API (AssetUpgradeKaryawan_m::getOptions): asset milik karyawan yang terpakai, tidak diblokir flow lain, dan punya atribut spesifikasi (atributAssets); ditambah daftar urgensi.

Database: hanya SELECT.

Diterima mobile (ringkas)

{ "code": "SUCCESS", "message": "Opsi upgrade asset berhasil ditemukan.",
  "data": {
    "assets": [ { "id_asset_data": "CMP00120260100012", "kode_asset": "LPT-0012", "nama_asset": "Laptop 14 inch",
      "kategori_asset": "Laptop", "id_pemegang_asset": "KRY0010",
      "atribut": [
        { "id_atribut": "CMP001ITEM0101|ram", "id_asset_data_item": "CMP001ITEM0101", "id_komponen": "ram",
          "nama_item": "Laptop 14 inch", "jenis": "aset_utama", "label": "RAM", "satuan": "GB", "nilai": "8" },
        { "id_atribut": "CMP001ITEM0102|daya", "id_asset_data_item": "CMP001ITEM0102", "id_komponen": "daya",
          "nama_item": "Charger", "jenis": "kelengkapan", "label": "Daya", "satuan": "W", "nilai": "65" } ] } ],
    "urgensi": [ { "value": "normal", "label": "Normal" }, { "value": "secepatnya", "label": "Secepatnya" },
                 { "value": "mendesak", "label": "Mendesak" } ] } }

Unit utama selalu ditampilkan lebih dulu daripada kelengkapan.

Langkah 1 — Dimas mengajukan upgrade

Mobile: Dimas memilih laptop, mencentang atribut RAM, mengisi detail "8 GB menjadi 16 GB", alasan, dan urgensi Secepatnya, lalu Ajukan Upgrade → AssetUpgradeApi.storeKaryawan.

Dikirim

POST /asset/karyawan/upgrade

{
  "id_asset_data": "CMP00120260100012",
  "alasan": "Aplikasi desain sering lambat",
  "urgensi": "secepatnya",
  "items": [ { "id_atribut": "CMP001ITEM0101|ram", "detail_upgrade": "8 GB menjadi 16 GB" } ]
}

Diproses API (AssetKaryawanUpgrade_c::storeUpgradeSaya → storeKaryawan → insertTransaction, satu DB::transaction) 1. Validasi: alasan wajib (maks 1000); urgensi ∈ normal/secepatnya/mendesak; items minimal 1; id_atribut unik; detail_upgrade wajib (maks 255). 2. lockCompany; activeKaryawan("KRY0010"). 3. Asset diambil FOR UPDATE: dipegang Dimas dan terpakai; assetBlockMessage memastikan tidak ada upgrade, kerusakan, retur, offboarding, atau pemeliharaan aktif. 4. atributAssets + normalizeItems: setiap atribut harus milik asset itu dan tidak boleh duplikat. 5. Generate ID: header urutan 1 → CMP001202610001, no_trx = KRY03-2-202610001. 6. INSERT header (sumber_pengajuan = karyawan, status_approval = proses, fase_upgrade = pengajuan, jadwal nol) dan INSERT item per atribut (snapshot JSON dan nilai_lama). 7. asset_data tidak berubah. Notifikasi upgrade.diajukan ke seluruh admin.

Hasil database

asset_trx_upgrade_karyawan

asset_trx_upgrade_karyawan_item

notif_data (2 baris, satu per admin)

Diterima mobile (HTTP 201)

{ "code": "CREATED", "message": "Pengajuan upgrade asset berhasil dikirim.",
  "data": { "id": "CMP001202610001", "no_trx": "KRY03-2-202610001", "status_approval": "proses",
            "fase_upgrade": "pengajuan", "status_label": "Menunggu Persetujuan", "tab": "pengajuan" } }

Langkah 2 — Admin menyetujui dan menjadwalkan pengambilan

Mobile: notifikasi membuka detail admin (aksi.review = true). Admin memilih Setujui, mengisi tanggal 23 Okt 2026 pukul 10:00 dan catatan → AssetUpgradeAdminApi.review.

Dikirim

POST /asset/upgrade-karyawan/CMP001202610001/review

{ "keputusan": "disetujui", "ket_tolak": "", "tgl_jadwal": "2026-10-23", "jam_jadwal": "10:00",
  "keterangan_jadwal": "Bawa ke ruang IT" }

Diproses API (reviewUpgradeKaryawan → review) 1. Validasi: keputusan ∈ disetujui/ditolak; ket_tolak wajib bila ditolak. Cek admin, lockCompany. 2. Header harus status_approval = proses ("Pengajuan upgrade sudah direview."). 3. Setuju: asset masih terpakai dan dipegang Dimas (lockHeldAsset, "Status asset sudah berubah atau tidak lagi dipegang karyawan."); jadwal wajib Y-m-d + H:i, tanggal tidak boleh sebelum tgl_pengajuan. 4. UPDATE header: status_approval = disetujui, fase_upgrade = menunggu_pengambilan, jadwal pengambilan, keterangan_pengembalian (kolom catatan untuk kedua jadwal), user_approval, tgl_approval, tgl_update, user_update. 5. Notifikasi upgrade.disetujui ke karyawan.

Hasil database

Diterima mobile (HTTP 200): status_approval = disetujui, fase_upgrade = menunggu_pengambilan, status_label = "Menunggu Pengambilan", tab = "proses", message "Review upgrade asset berhasil disimpan.". Sejak saat ini aksi.pelepasan = true bagi Dimas (tanpa menunggu checklist). Admin masih bisa Ubah Jadwal (API-006) selama fase ini; yang berubah adalah kolom jadwal pengambilan, dengan notifikasi upgrade.dijadwalkan.

Langkah 3 — Dimas menyerahkan aset (tanpa checklist)

Mobile: banner di Asset Saya atau detail upgrade → Serahkan Aset → dialog konfirmasi → AssetUpgradeApi.pelepasan(id). Tidak ada form checklist.

Dikirim

POST /asset/karyawan/upgrade/CMP001202610001/pelepasan

Tanpa body.

Diproses API (pelepasanUpgradeSaya → pelepasan) 1. Karyawan aktif; lockHeader memfilter id_karyawan sehingga hanya header milik Dimas yang ditemukan; fase harus menunggu_pengambilan ("Aset belum siap diserahkan untuk upgrade."). Tidak ada syarat checklist. 2. Asset dikunci dan harus masih dipegang Dimas (terpakai atau dalam_perbaikan). 3. UPDATE asset_data A12 → dalam_perbaikan (pemegang_asset tidak diubah). INSERT asset_trx_log (jenis_log = upgrade_karyawan, karyawan → gudang). 4. UPDATE header: fase_upgrade = dalam_service, tgl_pelepasan, user_pelepasan. 5. Notifikasi upgrade.dilepas ke admin.

Hasil database

asset_trx_log (1 baris)

notif_data: CMP00120261000004 (KRY0099) dan CMP00120261000005 (KRY0100), rute asset_admin_detail_upgrade, "Dimas Contoh telah menyerahkan asset KRY03-2-202610001 untuk diupgrade."

Diterima mobile (HTTP 200): fase_upgrade = dalam_service, status_label = "Dalam Service", message "Aset berhasil diserahkan untuk upgrade.".

Langkah 4 — Admin mencatat hasil upgrade

Mobile: teknisi menyelesaikan pekerjaan di luar sistem. Admin membuka Hasil Upgrade, memilih Selesai, mengisi keterangan, biaya, nilai baru RAM, dan jadwal pengembalian 26 Okt 2026 pukul 15:00 → AssetUpgradeAdminApi.hasil.

Dikirim

POST /asset/upgrade-karyawan/CMP001202610001/hasil

{
  "status_hasil": "selesai",
  "keterangan_hasil": "RAM ditambah 1 keping 8 GB",
  "biaya_upgrade": 650000,
  "items": [ { "id_item": "CMP001202610001", "nilai_baru": "16" } ],
  "tgl_jadwal": "2026-10-26", "jam_jadwal": "15:00", "keterangan_jadwal": ""
}

Diproses API (hasilUpgradeKaryawan → hasil) 1. Fase harus dalam_service ("Aset belum berada dalam proses upgrade."). 2. status_hasil ∈ selesai/tidak_dapat_diupgrade; keterangan_hasil wajib (maks 1000); biaya_upgrade ≥ 0; jadwal pengembalian wajib. 3. Per item: bila selesai, nilai_baru wajib ("Nilai baru setiap atribut wajib diisi."); bila tidak_dapat_diupgrade, nilai_baru dikosongkan dan alasan_tidak_upgrade diisi dari keterangan (maks 255). 4. UPDATE header: fase_upgrade = menunggu_pengembalian, hasil, biaya, jadwal pengembalian, keterangan_pengembalian, serta reset tgl_diterima = NULL. 5. Notifikasi upgrade.pengembalian ke karyawan.

Hasil database

Diterima mobile (HTTP 200): fase_upgrade = menunggu_pengembalian, status_label = "Menunggu Pengembalian", message "Hasil upgrade berhasil disimpan.". aksi.terima = true bagi Dimas. Ubah Jadwal pada fase ini mengubah jadwal pengembalian.

Langkah 5 — Dimas menerima laptop (langsung selesai)

Mobile: Dimas menerima laptop dan memeriksanya sendiri, lalu Terima Aset → dialog konfirmasi → AssetUpgradeApi.terima(id). Tidak ada form checklist dan tidak ada body.

Dikirim

POST /asset/karyawan/upgrade/CMP001202610001/terima

Tanpa body.

Diproses API (terimaUpgradeSaya → terima, satu DB::transaction) 1. Karyawan aktif; lockHeader memfilter id_karyawan; fase harus menunggu_pengembalian ("Aset belum dijadwalkan untuk dikembalikan."). 2. Asset harus dalam_perbaikan dan masih dipegang Dimas ("Status asset sudah berubah atau tidak lagi dipegang karyawan."). 3. Bila status_hasil = selesai → applyAtribut: untuk tiap item, asset_data_item.json_value.komponen[] dengan id = id_komponen diperbarui value-nya ke nilai_baru, bila tidak kosong. 4. UPDATE asset_data A12 → terpakai; INSERT asset_trx_log (gudang → karyawan). 5. UPDATE header: fase_upgrade = selesai, status_transaksi = selesai, tgl_diterima = now. 6. Notifikasi upgrade.diterima ke admin ("… Upgrade selesai."). Karyawan tidak menerima notifikasi tambahan.

Hasil database

asset_trx_log (1 baris baru): CMP00120261000002, A12, upgrade_karyawan, kondisi normal → normal, posisi gudang → karyawan, id_pemegang KRY0010, nama_pemegang Dimas Contoh, user_input = EMP-010 - Dimas Contoh.

notif_data: CMP00120261000007 (KRY0099) dan CMP00120261000008 (KRY0100), rute asset_admin_detail_upgrade, "Dimas Contoh telah menerima asset upgrade KRY03-2-202610001. Upgrade selesai."

Diterima mobile (HTTP 200): fase_upgrade = selesai, status_label = "Selesai", tab = "selesai", message "Aset hasil upgrade berhasil diterima.". Semua nilai aksi menjadi false.

Kondisi akhir data

asset_trx_upgrade_karyawan: CMP001202610001 / KRY03-2-202610001, status_approval = disetujui, fase_upgrade = selesai, status_transaksi = selesai, status_hasil = selesai, biaya_upgrade = 650000, tgl_pelepasan = 2026-10-23 10:15:00, tgl_diterima = 2026-10-26 15:20:00, checklist_pengambilan dan checklist_pengembalian tetap NULL.

asset_trx_upgrade_karyawan_item: CMP001202610001, nilai_lama = 8, nilai_baru = 16.

asset_data: A12 → terpakai @KRY0010 (tidak pernah berpindah pemegang). asset_data_item: RAM = 16. asset_trx_log: 2 baris. notif_data: 8 baris.

Variasi

Jalur B (admin menginisiasi). POST /asset/upgrade-karyawan dengan id_karyawan, id_asset_data, items[], catatan, dan jadwal pengambilan (wajib, tanggal ≥ hari ini). Header langsung sumber_pengajuan = admin, status_approval = disetujui, fase_upgrade = menunggu_pengambilan, alasan dan urgensi kosong, user_approval = admin pembuat; notifikasi upgrade.disetujui ke karyawan. Langkah 3 sampai 5 sama.

Admin menolak. Pada langkah 2, keputusan = ditolak dengan ket_tolak (wajib): status_approval = ditolak, status_transaksi = selesai, fase_upgrade = selesai, asset tidak berubah, notifikasi upgrade.ditolak.

Hasil tidak_dapat_diupgrade. Pada langkah 4, status_hasil = tidak_dapat_diupgrade (nilai baru tidak diisi): - item: nilai_baru dikosongkan ('') dan alasan_tidak_upgrade diisi dari keterangan_hasil (maks 255 karakter); header status_hasil = tidak_dapat_diupgrade, biaya_upgrade tetap boleh diisi, jadwal pengembalian tetap wajib, fase menunggu_pengembalian. - Pada langkah 5, applyAtribut dilewati sehingga asset_data_item (RAM tetap 8) tidak berubah; namun asset tetap kembali terpakai, log gudang → karyawan tetap dibuat, header menjadi selesai dengan tgl_diterima terisi, dan notifikasi upgrade.diterima tetap berbunyi "… Upgrade selesai.". - Tidak ada lagi siklus kirim ulang: bila upgrade harus diulang, pengajuan baru harus dibuat.

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

Tidak ada lagi event Checklist pengambilan, Selesaikan, dan Kirim ulang (dihapus v1.4). Kolom checklist_pengambilan / checklist_pengembalian tidak disentuh oleh event mana pun.

47Checklist Implementasi

Database

• Kolom workflow, index, enum log (migration)
• Selaraskan DBML (index, kolom item, format no_trx; tandai checklist_* tidak dipakai)
• Jalankan Claude outputs/sql-upgrade-hapus-checklist-review-lama.sql untuk transaksi lama menunggu_review (BELUM dijalankan; uji di staging dulu)
• Hapus kolom checklist_pengambilan / checklist_pengembalian dan nilai enum menunggu_review (opsional, setelah data lama selesai; butuh persetujuan migrasi)

Backend

• Jalur A & B, review, jadwal, hasil, serah terima tanpa checklist
• Update atribut asset_data_item (kini saat Terima)
• Hapus checklist pengambilan/penerimaan, review akhir (Selesaikan), kirim ulang; rute dan notifikasi terkait (v1.4)
• Test otomatis (5 test, 54 assertion)
• Cek upgrade aktif di Offboarding (v1.1)
• Cek upgrade aktif di Retur (v1.2)
• Pembatalan / kedaluwarsa
• Validasi list upgrade dengan pesan yang benar

Mobile

• List, form (karyawan/admin), detail + aksi (review, ubah jadwal, serahkan, hasil, terima)
• Hapus form checklist, tombol Simpan Checklist Pengambilan / Selesaikan / Kirim Ulang; terima(id) tanpa body (v1.4)
• Banner Asset Saya & panel admin
• Test Flutter (5)
• Bersihkan kunci lokalisasi lama dan teks pelepasan_info di asset.json (assets/id dan assets/en)
• Model jadwal sendiri (lepas dari Kerusakan)

Documentation

• Business Flow, DB, API, Mobile, Mapping, Manual Book, Testing
• Pembaruan v1.4 (checklist dan review akhir dihapus)
• Screenshot

48Changelog