Retur Asset Karyawan

01Informasi Dokumen

03Quick Overview

Karyawan: pilih asset yang dipegang + alasan per asset (+ pengganti? + keterangan) → Ajukan Retur
      │  asset TIDAK dikunci di asset_data (dijaga lewat pengecekan retur aktif)     pengajuan / proses
      ▼
Admin: Setujui / Tolak tiap asset (+ alasan)
       Tukar unit / Rusak dengan pengganti → wajib pilih Asset Pengganti (asset pengganti → proses)
       Metode serah terima: Dijadwalkan (tanggal + jam) atau Serahkan Langsung       disetujui / proses
      │  (semua ditolak → ditolak / selesai)
      ▼
Admin: Terima Asset (pilih lokasi gudang per asset)
   asset lama  → tersedia (tidak digunakan / tukar unit) atau rusak (rusak) @gudang pilihan admin + asset_trx_log
   pengganti   → terpakai @karyawan + asset_trx_log                                      disetujui / selesai

04Ringkasan Fitur

Retur Asset dipakai karyawan untuk mengembalikan asset yang sedang dipegangnya secara tetap (hasil Onboarding/Penambahan/penggantian sebelumnya) ke gudang. Asset pinjaman tidak bisa diretur — harus lewat Pengembalian Peminjaman.

Setiap asset dalam satu pengajuan memiliki alasan sendiri: - Asset Rusak — wajib keterangan kerusakan dan pilihan Tanpa Pengganti atau Dengan Pengganti. - Asset Tidak Digunakan — keterangan opsional. - Tukar Unit — wajib alasan; selalu membutuhkan unit pengganti.

Admin meninjau per asset. Untuk tukar unit dan rusak dengan pengganti, admin memilih asset pengganti dari gudang pada saat menyetujui. Admin juga menentukan apakah serah terima dijadwalkan (tanggal + jam) atau langsung. Serah terima fisik ditutup dengan Terima Asset oleh admin atau karyawan, yang sekaligus memindahkan asset lama ke gudang dan asset pengganti ke karyawan.

05Tujuan Fitur

5.1 Tujuan Bisnis (diturunkan dari kode)

• Karyawan dapat mengembalikan asset yang rusak, tidak terpakai, atau perlu ditukar secara tercatat.
• Admin mengontrol asset mana yang diterima kembali dan unit pengganti yang diberikan.
• Asset rusak masuk gudang dengan status rusak beserta keterangan kerusakannya.
• Penukaran unit tercatat sebagai satu transaksi (asset lama keluar, pengganti masuk).

5.2 Tujuan Sistem

• Menyimpan pengajuan retur per asset dengan alasan dan keterangan.
• Mencatat keputusan admin per asset dan asset pengganti (item anak).
• Mengunci asset pengganti (proses) sampai diserahkan.
• Memperbarui asset_data dan asset_trx_log saat serah terima.
• Mencegah asset yang sedang diretur diproses di Kerusakan/Upgrade.

06Aktor

07Hak Akses

08Terminologi

09Business Rules

BR-001 — Retur hanya untuk asset yang dipegang karyawan sendiri

asset_data.pemegang_asset = karyawan dan id_pemegang_asset = id_karyawan login → "Satu atau beberapa asset bukan milik karyawan atau sudah tidak dapat diretur."

BR-002 — Asset pinjaman tidak dapat diretur

status_asset = dipinjam → "Asset pinjaman tidak dapat diretur. Gunakan pengembalian peminjaman." (dicek saat ajukan, konfirmasi, dan terima).

BR-003 — Karyawan harus aktif

Saat ajukan → "Karyawan tidak ditemukan atau tidak aktif."

BR-004 — Minimal satu asset, tanpa duplikat

→ "Minimal satu asset wajib dipilih." / "Asset yang sama tidak boleh dipilih lebih dari sekali."

BR-005 — Aturan per alasan

BR-006 — Asset tidak boleh sedang di retur lain, offboarding, pemeliharaan, upgrade, atau kerusakan

hasActiveReturAsset → "Satu atau beberapa asset sedang diproses pada retur lain." hasActiveOffboardingAsset → "Satu atau beberapa asset sedang diproses pada offboarding." AssetPemeliharaanKaryawan_m::hasActivePemeliharaanAsset (PML01, fase ≠ selesai; sejak v1.2) → "Satu atau beberapa asset sedang diproses pada pemeliharaan." AssetUpgradeKaryawan_m::hasActiveUpgradeAsset → "…pada upgrade." dan AssetRusakKaryawan_m::hasActiveRusakAsset → "…pada laporan kerusakan." (terverifikasi di kode 12 Okt 2026). Opsi retur juga menyaring asset yang sedang di Upgrade/Kerusakan.

BR-007 — Admin memutuskan seluruh item asal

→ "Seluruh asset retur wajib dikonfirmasi." Tolak wajib alasan → "Alasan penolakan asset wajib diisi."; item ditolak tidak boleh punya pengganti.

BR-008 — Asset masih dipegang karyawan saat konfirmasi

→ "Satu atau beberapa asset sudah tidak dipegang oleh karyawan."

BR-009 — Asset pengganti

Wajib untuk tukar unit & rusak dengan pengganti; dilarang untuk alasan lain; unik; harus tersedia @gudang → "Asset pengganti wajib dipilih untuk retur ini." / "Alasan retur ini tidak memerlukan asset pengganti." / "Asset pengganti yang sama tidak boleh dipilih lebih dari sekali." / "Satu atau beberapa asset pengganti tidak tersedia." Tidak ada syarat kategori sama.

BR-010 — Metode serah terima wajib bila ada asset disetujui

dijadwalkan wajib tanggal + jam, tanggal ≥ tanggal pengajuan → "Metode serah terima retur tidak valid." / "Tanggal dan jam serah terima wajib diisi." / "Tanggal serah terima tidak boleh sebelum tanggal pengajuan."

BR-011 — Hasil keputusan

≥1 disetujui → status_approval = disetujui, status_transaksi = proses; semua ditolak → ditolak / selesai, ket_tolak = "Seluruh asset retur ditolak." Asset pengganti → proses.

BR-012 — Finalisasi hanya oleh admin (v1.4)

Hanya untuk disetujui + proses; asset asal masih dipegang karyawan; pengganti masih proses @gudang → "Retur asset belum dikonfirmasi atau sudah selesai." / "Asset pengganti sudah tidak siap diserahterimakan."

BR-013 — Dampak finalisasi

Asset asal disetujui: rusak → status_asset = rusak + ket_rusak = ket_retur; lainnya → tersedia; semua ke gudang. Pengganti → terpakai @karyawan. asset_trx_log retur_karyawan untuk keduanya. Header selesai, tgl/jam_serah_terima = now.

BR-013a — Lokasi gudang tujuan per asset (v1.4)

Pada Terima Asset admin wajib memilih lokasi gudang untuk setiap asset asal yang disetujui: items[] memuat tiap item (id_asset_trx_retur_item) tepat satu kali dengan id_asset_lokasi_m bertipe gudang pada company yang sama → "Lokasi gudang tujuan setiap asset wajib dipilih." / "Lokasi gudang tujuan tidak valid." / "Lokasi gudang tujuan asset tidak sesuai." Lokasi ditulis ke asset_data.id_asset_lokasi_m dan asset_trx_retur_karyawan_item.id_asset_lokasi_m_tujuan. Asset pengganti yang keluar ke karyawan di-set NULL lokasinya (kolom FK ke asset_lokasi_m; nilai '' ditolak database) (id_asset_lokasi_m = NULL). Route karyawan POST /asset/karyawan/retur/{id}/terima dihapus.

BR-014 — Retur aktif mengunci asset untuk Kerusakan & Upgrade

AssetRusakKaryawan_m dan AssetUpgradeKaryawan_m memanggil hasActiveReturAsset. Offboarding memeriksanya lewat assertNoCrossFlow (query langsung ke tabel retur dengan kondisi yang sama) → "Satu atau beberapa asset sedang diproses pada flow lain."

BR-015 — Penomoran

ID id_company + YYYYMM + 3 digit; no_trx = KRY04-YYYYMMNNN.

10Business Flow

1. Karyawan: Asset Saya → menu "Pengembalian" (Retur Asset) → (+) Tambah Retur Asset
   → Pilih Asset yang Diretur (hanya asset milik sendiri, bukan pinjaman, tidak sedang diretur)
   → per asset: Alasan Retur Asset → (Rusak: Tanpa/Dengan Pengganti) → Keterangan
   → Catatan Tambahan → Ajukan Retur                 [pengajuan/proses · notif admin]
2. Admin: Asset Karyawan → Retur → tab Pengajuan → Detail
   → per asset: Tolak (+alasan) / Setujui / Ganti Asset (pilih pengganti)
   → Konfirmasi Asset → sheet "Konfirmasi Retur Asset":
        Metode: Dijadwalkan (tanggal + jam) / Serahkan Langsung, Catatan → Submit
                                                     [disetujui/proses atau ditolak/selesai · notif karyawan]
3. Serah terima fisik sesuai jadwal / langsung
4. Admin: Detail → Terima Asset → dialog Lokasi Tujuan Asset (gudang per asset)
                                                     [disetujui/selesai · asset diperbarui · asset_trx_log · notif pihak lain]

11Flow Berdasarkan Role

11.1 Karyawan

1. Asset Saya → menu Pengembalian → halaman Retur Asset (tab Pengajuan, Dikonfirmasi, Diterima).
2. + → Tambah Retur Asset → Ajukan Retur.
3. Setelah disetujui: kartu menampilkan jadwal ("Jadwal Serah Terima Retur Asset") atau info serah terima langsung; banner di Asset Saya.
4. Serahkan asset ke admin dan terima pengganti bila ada; penyelesaian dilakukan oleh admin (v1.4).

11.2 Admin Asset

1. Asset Karyawan → aksi Retur (panel ringkasan "perlu diproses" mencakup pengajuan & yang menunggu serah terima).
2. Tab Pengajuan → detail → keputusan per asset → Konfirmasi Asset → sheet → Submit.
3. Tab Dikonfirmasi → detail → Terima Asset setelah serah terima fisik, lalu pilih lokasi gudang setiap asset.

11.3 Approver

Dijalankan Admin Asset.

11.4 System

Validasi kepemilikan & status, lock, penomoran, reservasi pengganti, finalisasi asset + log, notifikasi setelah commit.

12Flow Diagram

flowchart TD
    A[Karyawan pilih asset + alasan per asset] --> B{Validasi}
    B -->|Gagal| X[Pesan error]
    B -->|OK| C[pengajuan / proses, notif admin]
    C --> D{Admin putuskan per asset}
    D -->|Semua ditolak| E[ditolak / selesai, notif karyawan]
    D -->|Ada disetujui| F{Butuh pengganti?}
    F -->|Tukar unit / rusak dengan pengganti| G[Pilih asset pengganti, pengganti jadi proses]
    F -->|Tidak| H[Tanpa pengganti]
    G --> I{Metode serah terima}
    H --> I
    I -->|Dijadwalkan| J[Simpan tanggal + jam pengambilan]
    I -->|Langsung| K[Tanpa jadwal]
    J --> L[disetujui / proses, notif karyawan]
    K --> L
    L --> M[Admin: Terima Asset dan pilih lokasi gudang per asset]
    M --> N[Asset lama ke gudang: tersedia atau rusak]
    M --> O[Asset pengganti ke karyawan: terpakai]
    N --> P[asset_trx_log retur_karyawan, disetujui / selesai]
    O --> P

13Sequence Diagram

sequenceDiagram
    actor K as Karyawan
    actor A as Admin
    participant M as Mobile
    participant CK as AssetKaryawanRetur_c
    participant CA as AssetAdminRetur_c
    participant R as AssetReturKaryawan_m
    participant DB
    participant N as AssetNotification

    K->>M: Pilih asset, alasan, keterangan, Ajukan Retur
    M->>CK: POST /asset/karyawan/retur
    CK->>R: store()
    R->>DB: lock company, cek karyawan, asset milik sendiri, bukan pinjaman
    R->>DB: cek retur aktif dan offboarding
    R->>DB: INSERT header pengajuan + item
    CK->>N: retur.diajukan (admin)
    A->>M: Keputusan per asset, pengganti, metode serah terima
    M->>CA: POST /asset/retur-karyawan/{id}/konfirmasi
    CA->>R: konfirmasiAdmin()
    R->>DB: UPDATE item keputusan, INSERT item pengganti
    R->>DB: UPDATE asset pengganti proses, UPDATE header disetujui + jadwal
    CA->>N: retur.dikonfirmasi atau retur.ditolak (karyawan)
    A->>M: Terima Asset, pilih lokasi gudang per asset
    M->>CA: POST /asset/retur-karyawan/{id}/terima (items per asset)
    CA->>R: terimaAdmin() lalu finalizeHandover()
    R->>DB: UPDATE asset lama gudang tersedia atau rusak, id_asset_lokasi_m
    R->>DB: UPDATE asset pengganti terpakai karyawan
    R->>DB: INSERT asset_trx_log retur_karyawan, UPDATE header selesai
    CA->>N: retur.diterima_admin (karyawan)

14Status Transaksi

Header memiliki dua kolom status: status_approval (enum status_approval_retur: pengajuan, disetujui, ditolak, proses, serah_terima) dan status_transaksi (enum status: proses, selesai).

Status item (status_approval item, enum approval_item): NULL (belum ditinjau) → disetujui / ditolak. Item pengganti langsung disetujui.

15State Transition

stateDiagram-v2
    [*] --> pengajuan: Ajukan Retur (Karyawan)
    pengajuan --> ditolak: Konfirmasi, semua ditolak (Admin)
    pengajuan --> disetujui_proses: Konfirmasi, ada disetujui (Admin)
    disetujui_proses --> disetujui_selesai: Terima Asset (Admin)
    ditolak --> [*]
    disetujui_selesai --> [*]

Status asset_data: | Asset | Dari | Ke | Trigger | |---|---|---|---| | Asset asal | terpakai @karyawan | (tidak berubah saat pengajuan/konfirmasi) | – | | Asset asal (tidak digunakan / tukar unit) | @karyawan | tersedia @gudang | Terima Asset | | Asset asal (rusak) | @karyawan | rusak @gudang (+ket_rusak) | Terima Asset | | Asset pengganti | tersedia @gudang | proses | Konfirmasi admin | | Asset pengganti | proses @gudang | terpakai @karyawan | Terima Asset |

16Struktur Database

17Relasi Database

erDiagram
    ASSET_TRX_RETUR_KARYAWAN ||--o{ ASSET_TRX_RETUR_KARYAWAN_ITEM : "id_asset_trx_retur"
    ASSET_TRX_RETUR_KARYAWAN_ITEM |o--o| ASSET_TRX_RETUR_KARYAWAN_ITEM : "parent_id (pengganti)"
    ASSET_DATA ||--o{ ASSET_TRX_RETUR_KARYAWAN_ITEM : "id_asset_data"
    DATA_KARYAWAN ||--o{ ASSET_TRX_RETUR_KARYAWAN : "id_karyawan (logis)"
    ASSET_DATA ||--o{ ASSET_TRX_LOG : "id_asset_data"
    ASSET_TRX_RETUR_KARYAWAN ||--o{ ASSET_TRX_LOG : "id_transaksi (logis)"

    ASSET_TRX_RETUR_KARYAWAN {
        varchar id_asset_trx_retur_karyawan PK
        varchar no_trx
        varchar id_karyawan
        date tgl_pengajuan
        date tgl_pengambilan
        enum flag_jadwalkan
        date tgl_serah_terima
        enum status_approval
        enum status_transaksi
    }
    ASSET_TRX_RETUR_KARYAWAN_ITEM {
        varchar id_asset_trx_retur_item PK
        varchar parent_id
        varchar id_asset_trx_retur FK
        varchar id_asset_data FK
        enum status_approval
        enum alasan_retur
        int rusak_dengan_pengganti
        varchar ket_retur
    }
    ASSET_DATA {
        varchar id_asset_data PK
        enum status_asset
        enum pemegang_asset
        varchar id_pemegang_asset
        varchar ket_rusak
    }
    ASSET_TRX_LOG {
        varchar id_asset_trx_log PK
        varchar id_asset_data FK
        enum jenis_log
        varchar id_transaksi
    }

18Data Dictionary

18.1 asset_trx_retur_karyawan

18.2 asset_trx_retur_karyawan_item

18.3 asset_data & asset_trx_log

• asset_data: pemegang_asset, id_pemegang_asset, status_asset (terpakai/dipinjam/tersedia/rusak/proses), ket_rusak, kondisi_awal, tgl_update, user_update.
• asset_trx_log (jenis_log = retur_karyawan, nama_tabel_transaksi = asset_trx_retur_karyawan):

19Database Index

20Backend Architecture

RouteAsset.php (prefix /asset, jwt.api + jwt.ctx)
   ↓
AssetAdminRetur_c / AssetKaryawanRetur_c (validateRequest + accessError)
   ↓
AssetReturKaryawan_m ← Asset_m (lock, sequence, getLockedAssets, findActiveKaryawan, findAssetAdmin)
   ↓                 ← AssetAdmin_m::getOnboardingOptions (opsi pengganti)
   ↓                 ← AssetOffboardingKaryawan_m::hasActiveOffboardingAsset
DB::transaction (retry 3) → ApiResponse + AssetNotification

21Backend Business Logic

21.1 Ajukan — store

Lock → karyawan aktif → normalizeItems (aturan alasan §9 BR-005) → asset milik karyawan (FOR UPDATE) → bukan pinjaman → tidak di retur aktif → tidak di offboarding → ID + KRY04-… → INSERT header (pengajuan/proses, jadwal nol, flag_jadwalkan '0') → INSERT item (parent_id NULL, status_approval NULL, snapshot) → notif retur.diajukan. asset_data tidak diubah.

21.2 Konfirmasi — konfirmasiAdmin

Lock → admin → header pengajuan/proses FOR UPDATE → item asal FOR UPDATE → semua diputuskan → asset asal masih dipegang karyawan & bukan pinjaman → validasi keputusan & pengganti per item → pengganti tersedia @gudang (getLockedAssets) → bila ada disetujui: metode serah terima wajib, jadwal bila dijadwalkan (≥ tgl pengajuan) → UPDATE item (status_approval, ket_tolak) → INSERT item pengganti (parent_id, disetujui) → UPDATE pengganti proses → UPDATE header (status, jadwal, flag_jadwalkan, keterangan_serah_terima, user/tgl_approval) → notif retur.dikonfirmasi/retur.ditolak. Response +jumlah_disetujui, jumlah_ditolak, jumlah_pengganti.

21.3 Terima — terimaAdmin → finalizeHandover

Cek admin. Lalu: lock → header disetujui/proses → item asal disetujui (min 1) → resolveItemLocations (lokasi gudang per item asal, v1.4) → asset asal masih dipegang karyawan, bukan pinjaman → pengganti masih proses @gudang → per item asal: UPDATE asset (rusak/tersedia @gudang, id_asset_lokasi_m pilihan admin, ket_rusak) + UPDATE item id_asset_lokasi_m_tujuan + log; bila ada pengganti: UPDATE pengganti terpakai @karyawan, id_asset_lokasi_m = NULL + log → INSERT log → header selesai, tgl/jam_serah_terima = now → notif retur.diterima_admin (ke karyawan).

21.4 Query baca

• Opsi karyawan: asset @karyawan miliknya, bukan dipinjam, tidak di retur aktif + daftar alasan.
• Opsi admin: AssetAdmin_m::getOnboardingOptions → kategori & asset tersedia @gudang (untuk pengganti).
• List: tab pengajuan (pengajuan + ditolak), dikonfirmasi (disetujui/proses/serah_terima + proses), diterima (… + selesai); jumlah_asset hanya item asal.
• Detail: item asal dengan asset_pengganti bersarang, alasan_label, jadwal (tanggal nol dikosongkan).

22Dampak terhadap asset_data

23API Documentation

Terkait: GET /asset/karyawan/onboarding (retur[] = retur disetujui menunggu diterima) dan GET /asset/summary (retur_perlu_proses, retur_pending). Edit/batal retur: ⚠️ Belum ditemukan.

24Detail Setiap API

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

API-001 — Opsi Pengganti (Admin)

GET /asset/retur-karyawan/options

data: { "kategori_asset": [...], "assets": [{id_asset_data, kode_asset, nama_asset, id_asset_kategori_m, kategori_asset, merek, deskripsi, kondisi_awal}] } — asset tersedia @gudang (sama dengan opsi onboarding).

API-002 / API-007 — List Retur

GET /asset/retur-karyawan?tab=pengajuan&limit=20&offset=0     (admin)
GET /asset/karyawan/retur?tab=dikonfirmasi                    (karyawan)

tab: pengajuan | dikonfirmasi | diterima ("Filter retur asset tidak valid."); limit 1–50.

{
  "code": "SUCCESS",
  "message": "Data retur asset berhasil ditemukan.",
  "data": {
    "filters": [
      {"value": "pengajuan", "label": "Pengajuan"},
      {"value": "dikonfirmasi", "label": "Dikonfirmasi"},
      {"value": "diterima", "label": "Diterima"}
    ],
    "records": [
      {
        "id": "CMP001202609011",
        "no_trx": "KRY04-202609011",
        "tgl_pengajuan": "2026-09-26",
        "tgl_pengambilan": "2026-09-29",
        "jam_pengambilan": "10:00:00",
        "flag_jadwalkan": "1",
        "tgl_serah_terima": "",
        "jam_serah_terima": "",
        "status_approval": "disetujui",
        "status_transaksi": "proses",
        "status_label": "Dikonfirmasi",
        "tab": "dikonfirmasi",
        "ket_tolak": "",
        "jumlah_asset": 2,
        "karyawan": {"id_karyawan": "KRY0004", "nik": "EMP-004", "nama_karyawan": "Rina Contoh"}
      }
    ],
    "pagination": {"limit": 20, "offset": 0, "next_offset": 1, "has_more": false}
  }
}

API-003 / API-009 — Detail Retur

GET /asset/retur-karyawan/{id}
GET /asset/karyawan/retur/{id}

{
  "id": "CMP001202609011",
  "no_trx": "KRY04-202609011",
  "tgl_pengajuan": "2026-09-26",
  "keterangan": "Laptop sering mati mendadak",
  "ket_tolak": "",
  "tgl_pengambilan": "2026-09-29",
  "jam_pengambilan": "10:00:00",
  "flag_jadwalkan": "1",
  "tgl_serah_terima": "",
  "jam_serah_terima": "",
  "keterangan_serah_terima": "Bawa charger",
  "status_approval": "disetujui",
  "status_transaksi": "proses",
  "status_label": "Dikonfirmasi",
  "tab": "dikonfirmasi",
  "jumlah_asset": 1,
  "karyawan": {"id_karyawan": "KRY0004", "nik": "EMP-004", "nama_karyawan": "Rina Contoh", "cabang": "Kantor Pusat", "divisi": "HR", "jabatan": "Staff HR"},
  "items": [
    {
      "id_item": "CMP001202609031",
      "parent_id": "",
      "id_asset_data": "CMP00120260100012",
      "kode_asset": "LPT-0012",
      "nama_asset": "Laptop 14 inch",
      "kategori_asset": "Laptop",
      "merek": "MerekX",
      "deskripsi": "Charger",
      "status_item": "disetujui",
      "ket_tolak": "",
      "alasan_retur": "rusak",
      "alasan_label": "Asset Rusak",
      "rusak_dengan_pengganti": 2,
      "ket_retur": "Mati mendadak saat dipakai",
      "asset_pengganti": {
        "id_item": "CMP001202609032",
        "parent_id": "CMP001202609031",
        "id_asset_data": "CMP00120260100015",
        "kode_asset": "LPT-0015",
        "nama_asset": "Laptop 14 inch",
        "status_item": "disetujui"
      }
    }
  ]
}

404: "Retur asset tidak ditemukan."

API-004 — Konfirmasi Retur (Admin)

POST /asset/retur-karyawan/{id}/konfirmasi

{
  "items": [
    {"id_item": "CMP001202609031", "status_item": "disetujui", "ket_tolak": "", "id_asset_pengganti": "CMP00120260100015"}
  ],
  "metode_serah_terima": "dijadwalkan",
  "tgl_pengambilan": "2026-09-29",
  "jam_pengambilan": "10:00",
  "keterangan_serah_terima": "Bawa charger"
}

Database impact:

UPDATE asset_trx_retur_karyawan_item (status_approval, ket_tolak)
INSERT asset_trx_retur_karyawan_item (pengganti, parent_id)
UPDATE asset_data (pengganti → proses)
UPDATE asset_trx_retur_karyawan (status, jadwal, flag_jadwalkan, approval)
INSERT notif_data

{ "code": "UPDATED", "message": "Retur asset berhasil dikonfirmasi.",
  "data": { "id": "CMP001202609011", "no_trx": "KRY04-202609011", "status_approval": "disetujui",
            "status_transaksi": "proses", "status_label": "Dikonfirmasi", "tab": "dikonfirmasi",
            "jumlah_disetujui": 1, "jumlah_ditolak": 0, "jumlah_pengganti": 1 } }

Semua ditolak: "Retur asset berhasil ditolak.", ditolak/selesai. 422: "Retur asset tidak ditemukan.", "Retur asset sudah tidak menunggu konfirmasi.", "Seluruh asset retur wajib dikonfirmasi.", "Satu atau beberapa asset sudah tidak dipegang oleh karyawan.", "Asset pinjaman tidak dapat diretur…", "Asset yang ditolak tidak boleh memiliki asset pengganti.", "Asset pengganti wajib dipilih untuk retur ini.", "Alasan retur ini tidak memerlukan asset pengganti.", "Satu atau beberapa asset pengganti tidak tersedia.", "Tanggal dan jam serah terima wajib diisi.", "Tanggal serah terima tidak boleh sebelum tanggal pengajuan." 500: "Terjadi kesalahan saat mengonfirmasi retur asset."

API-005 — Terima Asset (finalisasi); API-010 dihapus (v1.4)

POST /asset/retur-karyawan/{id}/terima          (admin)

Body (v1.4): lokasi gudang dipilih per asset asal yang disetujui.

{
  "items": [
    {"id_asset_trx_retur_item": "CMP001202609012", "id_asset_lokasi_m": "CMP001202610001"}
  ]
}

Pesan umum validasi: "Data penerimaan retur belum lengkap." Database impact:

UPDATE asset_data (asal → tersedia/rusak @gudang + id_asset_lokasi_m; pengganti → terpakai @karyawan, id_asset_lokasi_m = NULL)
UPDATE asset_trx_retur_karyawan_item (id_asset_lokasi_m_tujuan)
INSERT asset_trx_log (retur_karyawan)
UPDATE asset_trx_retur_karyawan (status_transaksi selesai, tgl/jam_serah_terima)
INSERT notif_data

{ "code": "UPDATED", "message": "Retur asset berhasil diterima.",
  "data": { "id": "CMP001202609011", "no_trx": "KRY04-202609011", "status_approval": "disetujui",
            "status_transaksi": "selesai", "status_label": "Selesai", "tab": "diterima",
            "jumlah_diterima": 1, "jumlah_pengganti": 1 } }

422: "Retur asset tidak ditemukan.", "Retur asset belum dikonfirmasi atau sudah selesai.", "Tidak ada asset retur yang dapat diterima.", "Satu atau beberapa asset retur tidak ditemukan.", "Satu atau beberapa asset sudah tidak dipegang oleh karyawan.", "Asset pengganti sudah tidak siap diserahterimakan.", "Lokasi gudang tujuan setiap asset wajib dipilih.", "Lokasi gudang tujuan tidak valid.", "Lokasi gudang tujuan asset tidak sesuai.", "Pengguna tidak terdaftar sebagai admin asset." (admin). 500: "Terjadi kesalahan saat menerima retur asset."

Detail admin (API-003) mulai v1.4 memuat lokasi_gudang[] (gudang milik company), karyawan.id_cabang, dan items[].id_asset_lokasi_m_tujuan serta nama_lokasi_tujuan (kosong sampai diterima). Route POST /asset/karyawan/retur/{id}/terima (API-010) sudah tidak ada; memanggilnya menghasilkan 404.

API-006 — Opsi Retur (Karyawan)

GET /asset/karyawan/retur/options

{
  "code": "SUCCESS",
  "message": "Opsi retur asset berhasil ditemukan.",
  "data": {
    "alasan_retur": [
      {"value": "rusak", "label": "Asset Rusak"},
      {"value": "tidak_digunakan", "label": "Asset Tidak Digunakan"},
      {"value": "tukar_unit", "label": "Tukar Unit"}
    ],
    "assets": [
      {"id_asset_data": "CMP00120260100012", "kode_asset": "LPT-0012", "nama_asset": "Laptop 14 inch",
       "kategori_asset": "Laptop", "merek": "MerekX", "deskripsi": "Charger", "status_asset": "terpakai"}
    ]
  }
}

API-008 — Ajukan Retur

POST /asset/karyawan/retur

{
  "keterangan": "Laptop sering mati mendadak",
  "items": [
    {"id_asset_data": "CMP00120260100012", "alasan_retur": "rusak", "rusak_dengan_pengganti": 2, "ket_retur": "Mati mendadak saat dipakai"},
    {"id_asset_data": "CMP00120260100013", "alasan_retur": "tidak_digunakan", "rusak_dengan_pengganti": 0, "ket_retur": ""}
  ]
}

Ditambah aturan model §9 BR-005.

Database impact: INSERT header, INSERT item, INSERT notif_data (tanpa update asset_data).

{ "code": "CREATED", "message": "Pengajuan retur asset berhasil dikirim.",
  "data": { "id": "CMP001202609011", "no_trx": "KRY04-202609011", "status_approval": "pengajuan",
            "status_transaksi": "proses", "status_label": "Menunggu Konfirmasi", "tab": "pengajuan" } }

422: "Karyawan tidak ditemukan atau tidak aktif.", "Satu atau beberapa asset bukan milik karyawan atau sudah tidak dapat diretur.", "Asset pinjaman tidak dapat diretur. Gunakan pengembalian peminjaman.", "Satu atau beberapa asset sedang diproses pada retur lain.", "Satu atau beberapa asset sedang diproses pada offboarding.", "Satu atau beberapa asset sedang diproses pada pemeliharaan.", "Asset rusak wajib memilih tanpa atau dengan pengganti.", "Keterangan kerusakan asset wajib diisi.", "Alasan tukar unit wajib diisi." 500: "Terjadi kesalahan saat menyimpan retur asset."

25Mobile Architecture

Page → Bloc (AssetReturBloc / AssetReturAdminBloc) → Api (AssetReturApi / AssetReturAdminApi) → ApiClient → Backend

26Mobile Screen

26.1 Retur Asset (Karyawan & Admin) — list

Tab Pengajuan (termasuk yang ditolak), Dikonfirmasi, Diterima. Kartu: nomor, Tanggal Pengajuan, status (Menunggu Konfirmasi / Ditolak / Dikonfirmasi / Diterima), karyawan (admin), "{jumlah} Asset", Alasan Penolakan, info "Jadwal Serah Terima Retur Asset — Serah terima asset dijadwalkan pada {tanggal}, jam {jam}." atau "Retur Asset Dikonfirmasi Admin/HR — Segera lakukan serah terima asset dan cek kondisi serta kelengkapan unit."

26.2 Tambah Retur Asset (Karyawan)

26.3 Detail Retur Asset (Karyawan)

Nomor, Tanggal Pengajuan, Status, Catatan Tambahan, Alasan Penolakan, Jadwal Serah Terima; Data Karyawan (Jabatan, Cabang, Departemen); Asset Retur: per item alasan, pengganti (Tanpa/Dengan), keterangan, keputusan Disetujui Admin/Ditolak Admin (+alasan), Asset Pengganti bila ada. Karyawan tidak lagi memiliki tombol Terima Asset (v1.4): hanya banner info jadwal / serah langsung; penyelesaian dilakukan admin.

Alur status: AssetAlurStepper.retur (Pengajuan → Konfirmasi → Serah Terima → Selesai; disembunyikan bila ditolak) dan satu kartu timeline per aset (AssetReturTimelineCards): Pengajuan (tanggal, alasan retur, keterangan) · Konfirmasi (unit pengganti; chip Ditolak per aset) · Serah Terima (jadwal) · Selesai (lokasi gudang tujuan aset itu). Aset yang ditolak berhenti di Konfirmasi sementara aset lain lanjut. File: Shared/Widgets/AssetAlurWidgets.dart, Shared/Widgets/AssetReturTimeline.dart.

26.4 Detail Retur Asset (Admin)

Sama dengan 26.3. Status pengajuan: per item Tolak (+Alasan Penolakan) dan Setujui / Ganti Asset (untuk item yang butuh pengganti → pilih asset dari gudang); tombol Konfirmasi Asset → sheet Konfirmasi Retur Asset: Metode Serah Terima (Dijadwalkan / Serahkan Langsung), Jadwal & Jam (mulai hari ini), Catatan Tambahan → Submit. Status disetujui & proses: tombol Terima Asset → dialog Lokasi Tujuan Asset (v1.4): tiap asset asal yang disetujui punya dropdown gudang sendiri (default gudang di cabang karyawan; tombol aktif setelah semua terpilih). Bila belum ada lokasi gudang muncul "Belum ada lokasi gudang.". Setelah selesai, kartu asset menampilkan "Lokasi Tujuan Asset: {gudang}".

Stepper dan kartu timeline sama seperti §26.3; kartu timeline disembunyikan saat form keputusan admin terbuka (status pengajuan).

26.5 Asset Saya

Banner retur yang sudah disetujui dan menunggu diterima (informasi; penyelesaian oleh admin).

27Mobile → API

28API → Mobile

29Mapping Mobile → API → Database

30Mapping Database → API → Mobile

31Validation

31.1 Mobile

31.2 Backend — lihat §9 & §24.

31.3 Database — ENUM status_approval_retur, status, approval_item, retur_aset; tanggal NOT NULL default 0000-00-00.

31.4 Ringkasan per Field

32Error Handling

33Audit Trail

34Notification

35Security

36Manual Book User/Admin

A. Karyawan — Mengajukan Retur

1. Asset Saya → menu Pengembalian → halaman Retur Asset → tekan +.
2. Pilih Asset yang Diretur → Tambah Retur Asset → pilih asset → Pilih.
3. Untuk setiap asset pilih Alasan Retur Asset: - Asset Rusak → pilih Tanpa Pengganti / Dengan Pengganti dan isi Keterangan Kerusakan. - Asset Tidak Digunakan → keterangan opsional. - Tukar Unit → isi alasan.
4. Isi Catatan Tambahan bila perlu → Ajukan Retur.

B. Admin — Meninjau Retur

1. Asset Karyawan → aksi Retur → tab Pengajuan → pilih transaksi.
2. Per asset: Tolak (isi Alasan Penolakan), Setujui, atau Ganti Asset (pilih asset pengganti dari gudang) untuk tukar unit / rusak dengan pengganti.
3. Konfirmasi Asset → pilih Metode Serah Terima: Dijadwalkan (isi Jadwal & Jam) atau Serahkan Langsung → Catatan Tambahan → Submit.

C. Serah Terima

1. Karyawan menyerahkan asset (dan menerima unit pengganti bila ada) sesuai jadwal atau langsung.
2. Admin membuka detail → Terima Asset.
3. Pada dialog Lokasi Tujuan Asset, pilih gudang untuk setiap asset (default: gudang di cabang karyawan), lalu tekan Terima Asset.
4. Asset lama masuk gudang yang dipilih (rusak atau tersedia), asset pengganti tercatat milik karyawan, status Diterima.

37Kondisi Button

38Testing Scenario

39Temuan Ketidaksesuaian

40Edge Case

41Potential Bug / Technical Risk

RISK-001 — Dicabut (koreksi v1.1)

Versi 1.0 menyebut Offboarding tidak memeriksa retur aktif. Ini keliru. AssetOffboardingKaryawan_m::assertNoCrossFlow mengecek tabel retur langsung (status_transaksi = proses dan status_approval != ditolak, sama dengan hasActiveReturAsset), sehingga asset yang sedang diretur tidak dapat di-offboarding. Catatan kecil: logika duplikat — bila definisi "retur aktif" berubah, kedua tempat harus diperbarui bersama.

RISK-002 — Tidak ada batal/kedaluwarsa setelah disetujui (SEDANG)

Asset pengganti tetap proses bila serah terima tidak pernah terjadi.

RISK-003 — Retur mengecek Kerusakan/Upgrade aktif (SELESAI)

store kini mengecek retur, offboarding, pemeliharaan, upgrade, dan laporan kerusakan aktif, sehingga pengecekan dua arah dengan Kerusakan/Upgrade. Risiko ditutup (terverifikasi 12 Okt 2026).

RISK-004 — Asset asal tidak dikunci selama retur (RENDAH)

asset_data asal tidak diubah; perlindungan hanya dari modul yang mengecek hasActiveReturAsset.

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

⚠️ Asumsi: bermasalah pada MySQL strict mode.

RISK-006 — Kapasitas penomoran (RENDAH)

3 digit/bulan/company untuk header & item (termasuk item pengganti).

RISK-007 — Notifikasi di luar transaksi (RENDAH)

42Dependency

Asset milik karyawan (hasil Onboarding / Penambahan / Retur sebelumnya)
      ↓
Retur (pengajuan → disetujui → selesai) ──► Notifikasi
      ↓ Terima Asset
Asset lama → gudang (tersedia / rusak)  ·  Asset pengganti (dari gudang) → karyawan
      ↓
asset_trx_log retur_karyawan

Terkait:
  - Kerusakan & Upgrade: menolak asset yang sedang diretur (hasActiveReturAsset)
  - Offboarding: saling mengecek (retur → hasActiveOffboardingAsset, offboarding → assertNoCrossFlow)
  - Pemeliharaan PML01: saling mengecek (retur → hasActivePemeliharaanAsset, pemeliharaan → hasActiveReturAsset)
  - Peminjaman: asset dipinjam tidak dapat diretur
  - Request/Penambahan: asset yang kembali ke gudang lewat retur bisa ditambahkan lagi (RISK-002 dokumen Request diperbaiki 2026-09-29)
  - Asset Saya & Summary Admin: getPendingForEmployee / getPendingForAdmin

43Source Code Reference

44Developer Notes

• Dua kolom status: gunakan kombinasi status_approval + status_transaksi; returStatusMetadata memetakan ke label/tab.
• Item pengganti adalah baris item dengan parent_id; jumlah_asset & keputusan hanya menghitung item asal. Detail mengembalikan pengganti di items[].asset_pengganti.
• Asset asal tidak dikunci di asset_data; penguncian logis lewat hasActiveReturAsset (dipakai Kerusakan & Upgrade).
• Finalisasi bersama (finalizeHandover) dipakai admin dan karyawan; notifikasi berbeda menurut pelaku.
• Alasan rusak selalu membuat asset asal rusak saat diterima (tanpa/dengan pengganti).
• Tanggal nol dikembalikan ke API sebagai string kosong (nullableDateValue/nullableTimeValue).
• Dokumen lama ALUR RETUR.md masih menggunakan istilah dikonfirmasi dan referensi ALK-KRY03 untuk pengganti — sudah tidak sesuai kode.

45End-to-End Traceability

Karyawan memilih "Tukar Unit" + alasan untuk laptop
  → AssetReturRequestItem(alasanRetur = tukar_unit, ketRetur)
  → JSON items[].alasan_retur / ket_retur
  → normalizeItems() (ket wajib, rusak_dengan_pengganti = 0)
  → asset_trx_retur_karyawan_item.alasan_retur = tukar_unit
Admin: Ganti Asset → pilih laptop pengganti
  → AssetReturAdminDecision(idAssetPengganti)
  → JSON items[].id_asset_pengganti
  → konfirmasiAdmin(): itemRequiresReplacement = true → INSERT item (parent_id) → asset_data pengganti = proses
Admin: Terima Asset (pilih gudang per asset)
  → finalizeHandover(): asset lama → tersedia @gudang pilihan admin, pengganti → terpakai @karyawan (lokasi dikosongkan)
  → asset_trx_log retur_karyawan (2 baris)
  → Detail: items[].asset_pengganti → UI "Asset Pengganti"

45.4 Walkthrough Lengkap dengan Contoh Data

Bagian ini mengikuti satu retur dari pengajuan sampai asset diterima gudang, 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 (AssetReturKaryawan_m, AssetKaryawanRetur_c, AssetAdminRetur_c, AssetNotification).

Skenario: Rina memegang laptop dan keyboard. Ia meretur laptop karena rusak dengan pengganti, dan keyboard karena tidak digunakan. Admin menyetujui keduanya, memilih laptop pengganti, dan menjadwalkan serah terima. Admin lalu menerima asset dan memilih gudang tujuan per asset.

Data awal

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

data_karyawan

asset_data

Semua kondisi_awal = normal. Lokasi gudang tujuan retur: CMP001202610001 = Gudang Servis (untuk asset rusak) dan CMP001202601001 = Gudang Pusat.

Penomoran: header dan item id_company + YYYYMM + 3 digit, no_trx = KRY04-YYYYMMNNN; log dan notifikasi 5 digit. Pengajuan retur tidak mengubah asset_data; asset hanya dijaga lewat pengecekan retur aktif.

Langkah 0 — Karyawan membuka form

Mobile: Asset Saya → menu Pengembalian → + → /asset_tambah_retur → LoadAssetReturOptions → AssetReturApi.getOptions().

Dikirim

GET /asset/karyawan/retur/options
Authorization: Bearer <access_token_rina>

Diproses API (AssetReturKaryawan_m::getOptions): asset yang dipegang karyawan sendiri (pemegang_asset = karyawan, id_pemegang_asset = KRY0004), bukan dipinjam, tidak sedang di retur aktif, dan tidak sedang di Upgrade atau Kerusakan; ditambah daftar alasan.

Database: hanya SELECT.

Diterima mobile: alasan_retur[] (rusak = Asset Rusak, tidak_digunakan = Asset Tidak Digunakan, tukar_unit = Tukar Unit) dan assets[] (A12, A13) seperti API-006.

Langkah 1 — Rina mengajukan retur

Mobile: Rina memilih kedua asset. Laptop: alasan Asset Rusak, Dengan Pengganti, keterangan "Mati mendadak saat dipakai". Keyboard: Asset Tidak Digunakan. Catatan tambahan diisi, lalu Ajukan Retur → AssetReturApi.store(AssetReturRequest).

Dikirim

POST /asset/karyawan/retur

{
  "keterangan": "Laptop sering mati mendadak",
  "items": [
    { "id_asset_data": "CMP00120260100012", "alasan_retur": "rusak",
      "rusak_dengan_pengganti": 2, "ket_retur": "Mati mendadak saat dipakai" },
    { "id_asset_data": "CMP00120260100013", "alasan_retur": "tidak_digunakan",
      "rusak_dengan_pengganti": 0, "ket_retur": "" }
  ]
}

Diproses API (AssetKaryawanRetur_c::storeReturSaya → AssetReturKaryawan_m::store, satu DB::transaction) 1. Validasi: items minimal 1; id_asset_data unik; alasan_retur ∈ rusak/tidak_digunakan/tukar_unit; rusak_dengan_pengganti ∈ 0/1/2; ket_retur maks 255. 2. lockCompany; findActiveKaryawan("KRY0004") (id_karyawan dari JWT). 3. normalizeItems menerapkan aturan per alasan: rusak wajib memilih 1 atau 2 dan keterangan; tidak_digunakan dipaksa rusak_dengan_pengganti = 0; tukar_unit wajib alasan. 4. Asset diambil FOR UPDATE dengan syarat dipegang karyawan ini; jumlah harus sama. 5. Asset tidak boleh dipinjam (gunakan Pengembalian Peminjaman), tidak boleh di retur aktif lain, offboarding, pemeliharaan, upgrade, atau laporan kerusakan. 6. Generate ID: header urutan 1 → CMP001202610001, no_trx = KRY04-202610001; item mulai urutan 1. 7. INSERT header (pengajuan / proses, jadwal nol, flag_jadwalkan = '0') dan INSERT item (parent_id NULL, status_approval NULL, snapshot nama/deskripsi/kategori). 8. Setelah commit: notifikasi retur.diajukan ke seluruh admin.

Hasil database

asset_trx_retur_karyawan

asset_trx_retur_karyawan_item

asset_data: tidak berubah (A12 dan A13 tetap terpakai @karyawan).

notif_data (2 baris, satu per admin)

Diterima mobile (HTTP 201)

{ "code": "CREATED", "message": "Pengajuan retur asset berhasil dikirim.",
  "data": { "id": "CMP001202610001", "no_trx": "KRY04-202610001", "status_approval": "pengajuan",
            "status_transaksi": "proses", "status_label": "Menunggu Konfirmasi", "tab": "pengajuan" } }

Langkah 2 — Admin membuka detail dan memuat opsi pengganti

Mobile: notifikasi membuka /asset_admin_detail_retur → LoadAssetReturAdminDetail(id) (GET /asset/retur-karyawan/CMP001202610001) dan LoadAssetReturAdminOptions (GET /asset/retur-karyawan/options).

Diproses API: detail hanya SELECT dan memuat item, lokasi_gudang[], serta karyawan.id_cabang. Opsi pengganti memakai AssetAdmin_m::getOnboardingOptions: asset tersedia di gudang (A15) dan pohon kategori. Database: tidak berubah.

Langkah 3 — Admin memutuskan per asset

Mobile: admin menekan Setujui pada keyboard, dan untuk laptop Ganti Asset → memilih LPT-0015. Konfirmasi Asset → sheet Konfirmasi Retur Asset: Metode Dijadwalkan, tanggal 23 Okt 2026, jam 10:00, catatan "Bawa charger" → Submit → AssetReturAdminApi.konfirmasi.

Dikirim

POST /asset/retur-karyawan/CMP001202610001/konfirmasi

{
  "items": [
    { "id_item": "CMP001202610001", "status_item": "disetujui", "ket_tolak": "",
      "id_asset_pengganti": "CMP00120260100015" },
    { "id_item": "CMP001202610002", "status_item": "disetujui", "ket_tolak": "" }
  ],
  "metode_serah_terima": "dijadwalkan",
  "tgl_pengambilan": "2026-10-23",
  "jam_pengambilan": "10:00",
  "keterangan_serah_terima": "Bawa charger"
}

Diproses API (AssetAdminRetur_c::konfirmasiReturKaryawan → konfirmasiAdmin) 1. Validasi items (id unik, status_item ∈ disetujui/ditolak, ket_tolak wajib bila ditolak, id_asset_pengganti unik); metode_serah_terima ∈ dijadwalkan/langsung; tanggal Y-m-d dan jam H:i. Cek admin. 2. lockCompany; header FOR UPDATE, harus pengajuan + proses ("Retur asset sudah tidak menunggu konfirmasi."). Item asal FOR UPDATE. 3. Seluruh item asal harus diputuskan. Asset asal masih dipegang Rina dan bukan pinjaman. 4. Per item disetujui, aturan pengganti (itemRequiresReplacement): laptop (rusak dengan pengganti = 2) wajib punya pengganti; keyboard (tidak digunakan) dilarang punya pengganti. Pengganti harus unik dan tersedia @gudang (getLockedAssets); tidak ada syarat kategori sama. 5. Karena ada yang disetujui: metode wajib valid; bila dijadwalkan, tanggal dan jam wajib dan tanggal tidak boleh sebelum tgl_pengajuan (23 ≥ 22 lolos). 6. UPDATE tiap item asal (status_approval, ket_tolak). 7. INSERT item pengganti: parent_id = item laptop, status_approval = disetujui, alasan_retur disalin dari item asal, rusak_dengan_pengganti = 0. Urutan item lanjut dari yang terakhir (→ 3). 8. UPDATE asset_data pengganti → proses. 9. UPDATE header: status_approval = disetujui, status_transaksi tetap proses, flag_jadwalkan = 1, jadwal, keterangan_serah_terima, user_approval, tgl_approval. 10. Notifikasi retur.dikonfirmasi ke karyawan.

Hasil database

Diterima mobile (HTTP 200)

{ "code": "UPDATED", "message": "Retur asset berhasil dikonfirmasi.",
  "data": { "id": "CMP001202610001", "no_trx": "KRY04-202610001", "status_approval": "disetujui",
            "status_transaksi": "proses", "status_label": "Dikonfirmasi", "tab": "dikonfirmasi",
            "jumlah_disetujui": 2, "jumlah_ditolak": 0, "jumlah_pengganti": 1 } }

Kartu Rina menampilkan "Jadwal Serah Terima Retur Asset: 23 Okt 2026, jam 10:00". Karyawan tidak punya tombol Terima Asset (dihapus v1.4); penyelesaian hanya oleh admin.

Langkah 4 — Admin menerima asset

Mobile: setelah serah terima fisik, admin membuka detail (status Dikonfirmasi) → Terima Asset → dialog Lokasi Tujuan Asset: laptop → Gudang Servis, keyboard → Gudang Pusat (tombol aktif setelah semua asset asal dipilih) → AssetReturAdminApi.terima.

Dikirim

POST /asset/retur-karyawan/CMP001202610001/terima

{
  "items": [
    { "id_asset_trx_retur_item": "CMP001202610001", "id_asset_lokasi_m": "CMP001202610001" },
    { "id_asset_trx_retur_item": "CMP001202610002", "id_asset_lokasi_m": "CMP001202601001" }
  ]
}

items[] hanya memuat item asal yang disetujui, masing-masing tepat satu kali.

Diproses API (terimaAdmin → finalizeHandover) 1. Cek admin ("Pengguna tidak terdaftar sebagai admin asset."); lockCompany. 2. Header harus disetujui + proses ("Retur asset belum dikonfirmasi atau sudah selesai."). 3. Item asal yang disetujui (min 1); resolveItemLocations: tiap item asal punya lokasi bertipe gudang, company yang sama, tepat satu kali. 4. Semua asset dikunci. Asset asal masih dipegang Rina dan bukan dipinjam; asset pengganti harus masih proses @gudang ("Asset pengganti sudah tidak siap diserahterimakan."). 5. Per item asal: UPDATE asset_data (rusak → status_asset = rusak dan ket_rusak = ket_retur; selain itu tersedia; keduanya gudang, id_pemegang_asset = '', id_asset_lokasi_m pilihan admin), UPDATE item id_asset_lokasi_m_tujuan, siapkan log. 6. Bila ada pengganti: UPDATE asset_data pengganti → terpakai, karyawan, id_pemegang_asset = KRY0004, id_asset_lokasi_m = NULL, siapkan log. 7. INSERT asset_trx_log; UPDATE header: status_transaksi = selesai, tgl_serah_terima dan jam_serah_terima = waktu Terima Asset diklik. 8. Notifikasi retur.diterima_admin ke karyawan.

Hasil database

asset_trx_log (3 baris; urutan mengikuti item asal, pengganti dicatat tepat setelah asal-nya)

Semua baris: id_transaksi = CMP001202610001, nama_tabel_transaksi = asset_trx_retur_karyawan, user_input = ADM-001 - Siti Admin.

notif_data: CMP00120261000004 ke KRY0004, id_ref CMP001202610001, rute asset_detail_retur, "Asset retur KRY04-202610001 telah diterima admin."

Diterima mobile (HTTP 200)

{ "code": "UPDATED", "message": "Retur asset berhasil diterima.",
  "data": { "id": "CMP001202610001", "no_trx": "KRY04-202610001", "status_approval": "disetujui",
            "status_transaksi": "selesai", "status_label": "Selesai", "tab": "diterima",
            "jumlah_diterima": 2, "jumlah_pengganti": 1 } }

Laptop pengganti kini muncul di Asset Saya Rina, sedangkan laptop rusak menjadi kandidat Perbaikan, Garansi, atau Disposal.

Kondisi akhir data

asset_trx_retur_karyawan

asset_trx_retur_karyawan_item

asset_data: A12 → rusak @gudang servis; A13 → tersedia @gudang pusat; A15 → terpakai @KRY0004. asset_trx_log: 3 baris. notif_data: 4 baris.

jumlah_asset pada daftar hanya menghitung item asal (2), bukan pengganti.

Variasi

Semua asset ditolak. Pada langkah 3, bila kedua item ditolak (alasan wajib per item): metode serah terima tidak diminta, header status_approval = ditolak, status_transaksi = selesai, ket_tolak = "Seluruh asset retur ditolak.", tidak ada pengganti, asset_data tidak berubah, notifikasi retur.ditolak ke karyawan, message "Retur asset berhasil ditolak.". Item yang ditolak tidak boleh memiliki pengganti.

Tolak sebagian. Bila hanya keyboard ditolak: header tetap disetujui/proses; pada langkah 4, items[] hanya memuat item asal yang disetujui, dan keyboard tidak disentuh (tetap terpakai @karyawan).

Serahkan langsung. metode_serah_terima = "langsung": flag_jadwalkan = 0, tgl_pengambilan dan jam_pengambilan tetap 0000-00-00/00:00:00; mobile menampilkan info serah langsung. Alurnya selanjutnya sama.

Tukar unit. Alasan tukar_unit wajib alasan dan selalu butuh pengganti; hasil asset asal saat diterima menjadi tersedia (bukan rusak), kecuali alasannya rusak.

Rusak tanpa pengganti. rusak_dengan_pengganti = 1: admin tidak boleh memilih pengganti; asset asal menjadi rusak saat diterima, karyawan tidak mendapat asset baru.

Kasus gagal yang umum

Semua pelanggaran aturan dilempar sebagai InvalidArgumentException di dalam DB::transaction, sehingga seluruh perubahan request itu dibatalkan.

Ringkasan siapa mengerjakan apa

46Ringkasan Database Impact

47Checklist Implementasi

Database

• Header & item (+ pengganti via parent_id)
• Kolom keputusan item (status_approval, ket_tolak)
• Index list
• Log retur
• Bersihkan enum proses/serah_terima
• Migration CREATE TABLE baseline

Backend

• Ajukan dengan aturan per alasan
• Konfirmasi per asset + pengganti + metode serah terima
• Finalisasi hanya oleh admin dengan lokasi gudang per asset (v1.4)
• Kunci terhadap Kerusakan/Upgrade
• Cek retur aktif di Offboarding (sudah ada, assertNoCrossFlow)
• Batal/edit retur
• Cek Kerusakan/Upgrade aktif saat ajukan

Mobile

• List, form, detail (karyawan & admin)
• Keputusan per asset, Ganti Asset, sheet konfirmasi
• Terima Asset
• Label menu "Retur" (bukan "Pengembalian")
• Tab Ditolak/Selesai terpisah
• maxLength keterangan

Documentation

• Business Flow, DB, API, Mobile, Mapping, Manual Book, Testing
• Perbarui API/ALUR RETUR.md
• Screenshot

48Changelog