Retur Asset Ruangan (ALK-RGN06)

01Informasi Dokumen

02Daftar Isi

Lihat panel navigasi di samping.

03Quick Overview

PIC Ruangan mengajukan retur satu atau beberapa asset yang dipegang ruangannya, masing-masing dengan alasan (rusak, tidak digunakan, atau tukar unit). Admin/HR memutuskan per asset (setujui atau tolak), memilih asset pengganti dari gudang bila alasannya tukar unit atau rusak dengan pengganti, lalu menentukan metode serah terima (dijadwalkan atau langsung). Setelah serah terima fisik, Admin/HR menekan Terima Asset dan memilih gudang tujuan untuk setiap asset. Asset lama masuk gudang (tersedia, atau rusak bila alasannya rusak) dan asset pengganti menjadi terpakai di ruangan. PIC tidak memiliki aksi terima dan tidak ada aksi edit/batal pengajuan.

PIC Ruangan: pilih ruangan + asset + alasan per asset → Ajukan Retur   [pengajuan / proses · notif Admin/HR]
   asset TIDAK dikunci di asset_data (dijaga lewat pengecekan retur aktif)
Admin/HR: Setujui / Tolak tiap asset (+ pengganti) + metode serah terima
   [disetujui / proses · notif PIC]      semua ditolak → [ditolak / selesai · notif PIC]
Admin/HR: Terima Asset (pilih gudang per asset)
   [disetujui / selesai · asset diperbarui · asset_trx_log · notif PIC]

04Ringkasan Fitur

05Tujuan Fitur

• Mengembalikan asset milik ruangan ke gudang secara terdokumentasi, dengan alasan per asset dan keputusan Admin/HR per asset.
• Menjamin asset pengganti (tukar unit atau rusak dengan pengganti) berpindah ke ruangan dalam satu transaksi serah terima.
• Mencatat gudang tujuan setiap asset yang kembali, kondisi akhir (tersedia atau rusak), pelaku, dan waktu.
• Memakai ulang alur dan layar KRY04 supaya perilaku dan tampilannya seragam.

06Aktor

07Hak Akses

08Terminologi

09Business Rules

Aturan per alasan (BR-05):

10Business Flow

1. PIC Ruangan: PIC Ruangan → Retur Asset → (+) Ajukan Retur Asset Ruangan
   → pilih Ruangan → Tambah Retur Asset (hanya asset ruangan itu yang bebas dari flow lain)
   → per asset: Alasan Retur Asset → (Rusak: Tanpa/Dengan Pengganti) → Keterangan
   → Catatan Tambahan → Ajukan Retur            [pengajuan/proses · notif Admin/HR]
2. Admin/HR: Ruangan → Retur → tab Pengajuan → Detail
   → per asset: Tolak (+alasan) / Setujui / Ganti Asset (pilih pengganti)
   → Konfirmasi Asset → sheet: Dijadwalkan (tanggal + jam) / Serahkan Langsung, Catatan → Submit
                                                [disetujui/proses atau ditolak/selesai · notif PIC]
3. Serah terima fisik sesuai jadwal atau langsung
4. Admin/HR: Detail → Terima Asset → dialog Lokasi Tujuan Asset (gudang per asset)
                                                [disetujui/selesai · asset diperbarui · log · notif PIC]

11Flow Berdasarkan Role

12Flow Diagram

flowchart TD
    A([Mulai]) --> B[PIC pilih ruangan, asset, alasan per asset]
    B --> C{Validasi}
    C -->|Gagal| X([Pesan error])
    C -->|OK| D[Header pengajuan/proses, notif Admin/HR]
    D --> E{Admin putuskan per asset}
    E -->|Semua ditolak| F([ditolak/selesai, notif PIC])
    E -->|Ada disetujui| G{Butuh pengganti?}
    G -->|Tukar unit atau rusak dengan pengganti| H[Pilih asset pengganti, pengganti jadi proses]
    G -->|Tidak| I[Tanpa pengganti]
    H --> J{Metode serah terima}
    I --> J
    J -->|Dijadwalkan| K[Simpan tanggal dan jam]
    J -->|Langsung| L[Jadwal tetap NULL]
    K --> M[disetujui/proses, notif PIC]
    L --> M
    M --> N[Admin Terima Asset, pilih gudang per asset]
    N --> O[Asset asal ke gudang: tersedia atau rusak]
    N --> P[Pengganti ke ruangan: terpakai]
    O --> Q([disetujui/selesai, log retur_ruangan])
    P --> Q

13Sequence Diagram

sequenceDiagram
    actor PIC as PIC Ruangan
    actor ADM as Admin/HR
    participant M as Mobile
    participant CP as AssetKaryawanReturRuangan_c
    participant CA as AssetAdminReturRuangan_c
    participant R as AssetReturRuangan_m
    participant DB as Database
    participant N as AssetNotification

    PIC->>M: Pilih ruangan, asset, alasan, Ajukan Retur
    M->>CP: POST /asset/karyawan/pic-ruangan/retur
    CP->>R: store()
    R->>DB: lock company, cek PIC ruangan, kepemilikan, kunci flow lain
    R->>DB: INSERT header pengajuan + item asal
    CP->>N: retur_ruangan.diajukan (Admin/HR)
    ADM->>M: Keputusan per asset, pengganti, metode serah terima
    M->>CA: POST /asset/retur-ruangan/{id}/konfirmasi
    CA->>R: konfirmasiAdmin()
    R->>DB: UPDATE item keputusan, INSERT item pengganti, pengganti jadi proses
    R->>DB: UPDATE header disetujui/proses atau ditolak/selesai
    CA->>N: retur_ruangan.dikonfirmasi atau .ditolak (PIC)
    ADM->>M: Terima Asset, pilih gudang per asset
    M->>CA: POST /asset/retur-ruangan/{id}/terima
    CA->>R: terimaAdmin()
    R->>DB: UPDATE asset asal ke gudang, pengganti ke ruangan, INSERT asset_trx_log
    R->>DB: UPDATE header selesai
    CA->>N: retur_ruangan.diterima_admin (PIC)

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 (PIC)
    pengajuan --> ditolak: Konfirmasi, semua ditolak (Admin/HR)
    pengajuan --> disetujui_proses: Konfirmasi, ada disetujui (Admin/HR)
    disetujui_proses --> disetujui_selesai: Terima Asset (Admin/HR)
    ditolak --> [*]
    disetujui_selesai --> [*]

16Struktur Database

SQL manual: sql-alk-rgn06-retur-ruangan.sql (guard, 2 tabel, ALTER enum jenis_log, verifikasi, rollback) dan sql-alk-rgn06-no-trx-unik-per-company.sql (mengganti unique global uq_retur_rgn_no_trx menjadi per company). Skrip pertama sudah dijalankan pengguna; skrip kedua perlu dijalankan/dikonfirmasi (status eksekusi belum dikonfirmasi pengguna).

17Relasi Database

erDiagram
    asset_lokasi_m ||--o{ asset_trx_retur_ruangan : "id_asset_lokasi_m"
    asset_trx_retur_ruangan ||--o{ asset_trx_retur_ruangan_item : "id_asset_trx_retur_ruangan"
    asset_trx_retur_ruangan_item |o--o{ asset_trx_retur_ruangan_item : "parent_id (pengganti)"
    asset_data ||--o{ asset_trx_retur_ruangan_item : "id_asset_data"
    asset_lokasi_m ||--o{ asset_trx_retur_ruangan_item : "id_asset_lokasi_m_tujuan (gudang)"
    asset_lokasi_m ||--o{ asset_lokasi_pic_m : "PIC ruangan"

PIC pada header disimpan sebagai id_karyawan_pic (snapshot nama_pic, nik_pic). Hak akses lihat/daftar dihitung dari master asset_lokasi_pic_m saat ini, bukan dari snapshot. parent_id pada item tidak memakai foreign key (hanya kolom referensi).

18Data Dictionary

asset_trx_retur_ruangan

asset_trx_retur_ruangan_item

19Database Index

Nama index di SQL manual (DBML mendefinisikan kolom yang sama dengan nama otomatis, kecuali unique yang diberi nama).

Foreign key: fk_atrr_retur_id_asset_lokasi_m, fk_atrri_retur_header, fk_atrri_retur_asset_data, fk_atrri_retur_lokasi_tujuan.

20Backend Architecture

Controller memvalidasi input, memanggil model dalam DB::transaction (model), lalu mengirim notifikasi setelah transaksi sukses. Pengecualian InvalidArgumentException menjadi BUSINESS_RULE_VIOLATION; Throwable lain menjadi SYSTEM_ERROR dan dicatat di log.

21Backend Business Logic

• getOptionsPic: memastikan karyawan PIC ruangan aktif tersebut (null → 403). Mengembalikan ruangan, daftar assets (milik ruangan, terpakai, belum terkunci retur/onboarding/penambahan ruangan, urut nama lalu kode), dan alasan.
• store: kunci company; validasi karyawan aktif, PIC ruangan, normalizeItems (BR-04, BR-05); asset dikunci FOR UPDATE; cek milik ruangan, kunci flow lain, status terpakai; buat header pengajuan/proses (jadwal NULL, flag_jadwalkan='0') dan item asal. asset_data tidak diubah.
• konfirmasiAdmin: kunci company; cek admin; header harus pengajuan/proses; seluruh item asal wajib diputuskan; asset asal masih dipegang ruangan; validasi pengganti dan jadwal; update status item; sisipkan item pengganti (parent_id, status_approval='disetujui') dan set aset pengganti proses; update header (disetujui/proses atau ditolak/selesai).
• terimaAdmin: kunci company; cek admin; header harus disetujui/proses; resolveItemLocations memetakan gudang per item asal yang disetujui; cek asal masih dipegang ruangan dan pengganti masih proses @gudang; update asset, id_asset_lokasi_m_tujuan, sisipkan asset_trx_log, header selesai dengan tgl/jam_serah_terima = sekarang.
• Daftar dan detail: getPageAdmin, getPagePic (filter PIC lewat wherePicRuangan), getDetail, getDetailAdmin (menambah lokasi_gudang).
• Ringkasan: countPendingForAdmin, getPendingForAdmin (maks. 3, terlama di atas), getPerluTindakanPic (maks. 50, proses dan bukan ditolak).

22Dampak terhadap asset_data

23API Documentation

Base asset/. Semua memakai JWT dan envelope ApiResponse.

Tambahan pada endpoint lain: GET karyawan/pic-ruangan (beranda PIC) memuat key retur_ruangan dan ruangan[] (dipakai form untuk memilih ruangan); GET summary (admin) memuat ruangan_retur_perlu_proses dan ruangan_retur_pending.

24Detail Setiap API

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

API-08 · POST asset/karyawan/pic-ruangan/retur (PIC)

{
  "id_asset_lokasi_m": "RGN-1",
  "keterangan": "Renovasi ruangan",
  "items": [
    { "id_asset_data": "AST-1", "alasan_retur": "rusak", "rusak_dengan_pengganti": 2, "ket_retur": "Layar pecah" },
    { "id_asset_data": "AST-2", "alasan_retur": "tidak_digunakan", "rusak_dengan_pengganti": 0, "ket_retur": "" },
    { "id_asset_data": "AST-3", "alasan_retur": "tukar_unit", "rusak_dengan_pengganti": 0, "ket_retur": "Perlu spek lebih tinggi" }
  ]
}

Respons CREATED ("Pengajuan retur asset ruangan berhasil dikirim."):

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

Pesan umum validasi: "Data retur asset ruangan belum lengkap." Aturan model tambahan: §9 (BR-01 sampai BR-06). Database impact: INSERT header, INSERT item, INSERT notif_data; tanpa UPDATE asset_data.

API-06 · GET asset/karyawan/pic-ruangan/retur/options?id_asset_lokasi_m=RGN-1 (PIC)

{ "code": "SUCCESS", "message": "Opsi retur asset ruangan berhasil ditemukan.",
  "data": {
    "ruangan": { "id_asset_lokasi_m": "RGN-1", "nama_ruangan": "Ruang Finance Lt.2", "cabang": "Pusat", "divisi": "Finance" },
    "assets": [
      { "id_asset_data": "AST-1", "kode_asset": "KOM-0001", "nama_asset": "Komputer R1",
        "kategori_asset": "Komputer", "merek": "MerekX", "deskripsi": "" } ],
    "alasan": [
      { "value": "rusak", "label": "Asset Rusak" },
      { "value": "tidak_digunakan", "label": "Asset Tidak Digunakan" },
      { "value": "tukar_unit", "label": "Tukar Unit" } ] } }

id_asset_lokasi_m kosong → 422 ("Ruangan wajib dipilih."). Bukan PIC ruangan, ruangan nonaktif, atau lokasi bertipe gudang → 403 FORBIDDEN ("Ruangan tidak ditemukan, tidak aktif, atau Anda bukan PIC ruangan ini."). Key alasan di respons adalah alasan (bukan alasan_retur seperti retur karyawan).

API-02 / API-07 · Daftar

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

tab: pengajuan | dikonfirmasi | diterima ("Filter retur asset ruangan tidak valid."); limit 1–50 ("Limit maksimal adalah 50 data."). Pesan umum: "Parameter daftar retur asset ruangan tidak valid."

{ "code": "SUCCESS", "message": "Data retur asset ruangan berhasil ditemukan.",
  "data": {
    "filters": [ {"value":"pengajuan","label":"Pengajuan"}, {"value":"dikonfirmasi","label":"Dikonfirmasi"}, {"value":"diterima","label":"Diterima"} ],
    "records": [ {
      "id": "COMP202610001", "no_trx": "RGN06-202610001", "tgl_pengajuan": "2026-10-15",
      "tgl_pengambilan": "2026-10-20", "jam_pengambilan": "09: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": 3,
      "ruangan": { "id_asset_lokasi_m": "RGN-1", "nama_ruangan": "Ruang Finance Lt.2", "cabang": "Pusat", "divisi": "Finance" },
      "pic": { "id_karyawan": "PIC-1", "nik": "111", "nama": "Pic Satu" } } ],
    "pagination": { "limit": 20, "offset": 0, "next_offset": 1, "has_more": false } } }

Tanggal/jam yang NULL ditampilkan sebagai string kosong "".

API-03 / API-09 · Detail

{
  "id": "COMP202610001", "no_trx": "RGN06-202610001", "tgl_pengajuan": "2026-10-15",
  "keterangan": "Renovasi ruangan", "ket_tolak": "",
  "tgl_pengambilan": "", "jam_pengambilan": "", "flag_jadwalkan": "0",
  "tgl_serah_terima": "", "jam_serah_terima": "", "keterangan_serah_terima": "",
  "status_approval": "disetujui", "status_transaksi": "proses", "status_label": "Dikonfirmasi",
  "tab": "dikonfirmasi", "jumlah_asset": 1,
  "ruangan": { "id_asset_lokasi_m": "RGN-1", "nama_ruangan": "Ruang Finance Lt.2", "cabang": "Pusat", "divisi": "Finance" },
  "pic": { "id_karyawan": "PIC-1", "nik": "111", "nama": "Pic Satu" },
  "items": [ {
    "id_item": "COMP202610011", "parent_id": "", "id_asset_data": "AST-1", "kode_asset": "KOM-0001",
    "nama_asset": "Komputer R1", "kategori_asset": "Komputer", "merek": "MerekX", "deskripsi": "",
    "status_item": "disetujui", "ket_tolak": "",
    "alasan_retur": "rusak", "alasan_label": "Asset Rusak", "rusak_dengan_pengganti": 2, "ket_retur": "Layar pecah",
    "id_asset_lokasi_m_tujuan": "", "nama_lokasi_tujuan": "",
    "asset_pengganti": { "id_item": "COMP202610012", "parent_id": "COMP202610011", "id_asset_data": "AST-9",
                         "kode_asset": "KOM-0009", "nama_asset": "Komputer Gudang", "status_item": "disetujui" } } ]
}

Item pengganti tidak muncul di items[] utama, melainkan di asset_pengganti (objek item dengan field yang sama; null bila tidak ada). Khusus admin (API-03) ditambah lokasi_gudang[] (id_asset_lokasi_m, nama_lokasi, id_cabang). 404 NOT_FOUND: "Retur asset ruangan tidak ditemukan."

API-04 · POST asset/retur-ruangan/{id}/konfirmasi (Admin)

{
  "items": [
    { "id_item": "COMP202610011", "status_item": "disetujui", "ket_tolak": "", "id_asset_pengganti": "AST-9" },
    { "id_item": "COMP202610013", "status_item": "ditolak", "ket_tolak": "Masih dipakai" }
  ],
  "metode_serah_terima": "dijadwalkan",
  "tgl_pengambilan": "2026-10-20",
  "jam_pengambilan": "09:00",
  "keterangan_serah_terima": "Bawa kabel daya"
}

Pesan umum: "Data konfirmasi retur asset ruangan belum lengkap." Database impact: UPDATE item (status_approval, ket_tolak), INSERT item pengganti (parent_id), UPDATE asset_data pengganti → proses, UPDATE header, INSERT notif_data.

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

Semua ditolak: pesan "Retur asset ruangan berhasil ditolak.", status_approval ditolak, status_transaksi selesai, event notifikasi retur_ruangan.ditolak.

API-05 · POST asset/retur-ruangan/{id}/terima (Admin)

{ "items": [
    { "id_asset_trx_retur_item": "COMP202610011", "id_asset_lokasi_m": "GDG-1" },
    { "id_asset_trx_retur_item": "COMP202610014", "id_asset_lokasi_m": "GDG-2" } ] }

Pesan umum: "Data penerimaan retur belum lengkap." Item yang dikirim harus tepat sama dengan item asal yang disetujui. Database impact: UPDATE asset_data (asal dan pengganti), UPDATE item (id_asset_lokasi_m_tujuan), INSERT asset_trx_log, UPDATE header, INSERT notif_data.

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

API-01 · GET asset/retur-ruangan/options (Admin): mengembalikan data yang sama dengan opsi admin retur karyawan (kategori_asset[] dan assets[] asset tersedia @gudang) karena memanggil AssetReturKaryawan_m::getAdminOptions. Pesan: "Opsi retur asset ruangan berhasil ditemukan."

Ringkasan admin dan beranda PIC (bukan endpoint baru): GET summary → ruangan_retur_perlu_proses (jumlah) dan ruangan_retur_pending[] (id, no_trx, nama_asset, nama_ruangan, nama_karyawan, status_approval); GET karyawan/pic-ruangan → retur_ruangan[] (bentuk sama dengan records[]).

25Mobile Architecture

Halaman retur karyawan dipakai ulang lewat parameter untukRuangan, supaya kode tidak digandakan.

File: model Repository/Model/Asset/mAssetRetur.dart (AssetReturRuangan, AssetReturRecord.ruangan/pic/untukRuangan), mAssetSummary.dart (ruanganReturPerluProses, ruanganReturPending), mAssetPicRuangan.dart (returRuangan); API Repository/Service/assetReturApi.dart, assetReturAdminApi.dart; bloc Bloc/Asset/AssetReturBloc.dart; UI UI/Modul/Asset/AssetSaya/Retur/*, UI/Modul/Asset/AssetAdmin/AssetAdminKaryawan/Retur/*, UI/Modul/Asset/Shared/Widgets/AssetReturRuanganCard.dart, UI/Modul/Asset/PicRuangan/HalamanAssetPicRuangan.dart, UI/Modul/Asset/AssetAdmin/AssetAdminRuangan/HalamanAssetAdminRuangan.dart.

26Mobile Screen

Form PIC. Dropdown Ruangan (dari ruangan[] beranda PIC; satu ruangan dipilih otomatis; bila kosong tampil pemberitahuan "Tidak ada ruangan yang dapat diretur."), lalu Pilih Asset yang Diretur → picker. Mengganti ruangan membuang asset terpilih dan memuat asset ruangan baru. Per asset: Alasan Retur Asset, pilihan Tanpa/Dengan Pengganti (bila rusak), Keterangan. Lalu Catatan Tambahan dan tombol Ajukan Retur.

Detail. Kartu info (nomor, tanggal, status, catatan, alasan penolakan, jadwal), AssetAlurStepper.retur, kartu timeline per aset, kartu Data Ruangan, daftar asset retur (alasan, keputusan, pengganti, gudang tujuan). Admin pada status pengajuan melihat tombol keputusan per asset; pada disetujui/proses melihat Terima Asset. PIC hanya melihat pemberitahuan serah terima (jadwal atau langsung).

Beranda PIC. Tombol Retur Asset dan banner untuk retur berjalan ("Menunggu konfirmasi Admin/HR" atau jumlah asset menunggu serah terima + jadwal). Dashboard Admin Ruangan. Panel ringkasan memakai ruangan_retur_*.

27Mobile → API

28API → Mobile

Model: mAssetRetur.dart (AssetReturRuangan dengan id_asset_lokasi_m/nama_ruangan/id_cabang/cabang/divisi; AssetReturRecord.ruangan, .pic, .untukRuangan = ruangan tidak kosong; AssetReturOptions.ruangan; AssetReturRequest.idAssetLokasi hanya dikirim bila retur ruangan), mAssetPicRuangan.dart (returRuangan, toleran bila key retur_ruangan tidak ada), mAssetSummary.dart (ruanganReturPerluProses, ruanganReturPending, toleran bila key tidak ada). Daftar ruangan PIC (AssetReturRuangan.listFrom) membuang entri tanpa id. Opsi alasan dibaca dari key alasan_retur, reasons, atau alasan.

29Mapping Mobile → API → Database

30Mapping Database → API → Mobile

31Validation

Mobile

Backend: lihat §9 dan §24. Database: enum status_approval_retur, status, approval_item, retur_aset, kondisi_on_off; tgl_pengambilan, jam_pengambilan, tgl_serah_terima, jam_serah_terima, id_asset_lokasi_m_tujuan, parent_id boleh NULL.

32Error Handling

33Audit Trail

34Notification

Judul/isi dua bahasa: mis. "Pengajuan Retur Asset Ruangan — {pic} mengajukan retur asset untuk {ruangan} ({no_trx})." Penerima PIC diambil dari snapshot id_karyawan_pic pada header (lihat RISK-005). Notifikasi dibuat setelah transaksi database sukses; kegagalan kirim tidak membatalkan transaksi. Rute /asset_pic_ruangan_retur dari notifikasi membawa id sehingga langsung membuka detail; ketiga rute terdaftar di assetNotifRoutes.

35Security

• JWT wajib; ctx memuat id_company dan id_karyawan. Seluruh query dibatasi id_company.
• Aksi admin memeriksa keanggotaan asset_admin di controller (accessError) dan di model (findAssetAdmin). ⚠️ Pada konfirmasi dan terima, validasi input dijalankan sebelum pemeriksaan admin, sehingga non-admin dengan payload tidak valid menerima 422 alih-alih 403 (pola yang sama dengan KRY04).
• PIC hanya melihat dan mengajukan untuk ruangan yang dipegangnya; detail milik ruangan lain menghasilkan 404, bukan 403.
• Company dikunci per transaksi dan asset dikunci FOR UPDATE untuk mencegah nomor ganda dan keputusan ganda; kepemilikan asset dicek ulang saat konfirmasi dan terima.
• Gudang tujuan divalidasi bertipe gudang dan satu company; tidak ada query mentah dari input pengguna.
• Foto/berkas: tidak dipakai di alur ini.

36Manual Book User/Admin

Label dari assets/id/asset.json (grup menu_asset.pic_ruangan) dan teks retur karyawan yang dipakai bersama. ⚠️ Screenshot menyusul.

A. PIC Ruangan: mengajukan retur

1. Buka Asset → PIC Ruangan, ketuk Retur Asset (daftar retur), lalu + (Ajukan Retur Asset Ruangan).
2. Pilih Ruangan (bila hanya satu, sudah terpilih otomatis).
3. Ketuk Tambah Retur Asset, pilih asset ruangan, ketuk Pilih. Asset yang sedang diproses di retur lain, onboarding, atau penambahan ruangan tidak tampil.
4. Untuk setiap asset pilih Alasan Retur Asset:
   • Asset Rusak: pilih Tanpa Pengganti atau Dengan Pengganti, isi Keterangan Kerusakan.
   • Asset Tidak Digunakan: keterangan opsional.
   • Tukar Unit: isi alasan.
5. Isi Catatan Tambahan bila perlu, ketuk Ajukan Retur.

B. PIC Ruangan: memantau

1. Status tampil sebagai banner di halaman PIC Ruangan ("Menunggu konfirmasi Admin/HR", lalu jumlah asset dan jadwal serah terima) dan di daftar retur (tab Pengajuan, Dikonfirmasi, Diterima).
2. Setelah dikonfirmasi, serahkan asset kepada Admin/HR sesuai jadwal atau langsung, dan terima unit pengganti bila ada. PIC tidak menekan tombol terima; Admin/HR yang menyelesaikan.
3. Bila ditolak, alasan penolakan terlihat di detail.

C. Admin/HR: meninjau retur

1. Buka Asset → Ruangan → Retur, tab Pengajuan, pilih transaksi.
2. Per asset: Tolak (isi Alasan Penolakan), Setujui, atau Ganti Asset (pilih pengganti dari gudang) untuk tukar unit dan rusak dengan pengganti.
3. Ketuk Konfirmasi Asset, pilih Metode Serah Terima: Dijadwalkan (tanggal + jam) atau Serahkan Langsung, isi catatan, Submit.

D. Admin/HR: menerima asset

1. Setelah serah terima fisik, buka transaksi di tab Dikonfirmasi, ketuk Terima Asset.
2. Pada dialog Lokasi Tujuan Asset, pilih gudang untuk setiap asset, lalu ketuk Terima Asset.
3. Asset lama masuk gudang yang dipilih (tersedia atau rusak), asset pengganti tercatat milik ruangan, status menjadi Diterima.

37Kondisi Button

38Testing Scenario

Hasil terakhir (dijalankan 15 Oktober 2026): API AssetReturRuanganTest 16 test (269 assertion) lolos; seluruh tests/Asset 224 test (2697 assertion) lolos; tests/Routing 4 test gagal (assertion jumlah route 506, sedangkan hasil nyata 537). Mobile asset_retur_ruangan_test.dart 25 test lolos; flutter test test/asset +338 -5 (5 kegagalan, semuanya di asset_onboarding_widget_test dan asset_peminjaman_test, bukan berkas retur ruangan). Belum diuji di server, emulator, atau MariaDB nyata.

39Temuan Ketidaksesuaian

⚠️ Tidak ada dokumen bisnis sumber untuk RGN06; persyaratan = "alur sama dengan KRY04". Tabel berikut membandingkan implementasi RGN06 dengan KRY04.

40Edge Case

41Potential Bug / Technical Risk

42Dependency

• Data master: asset_lokasi_m (tipe ruangan dan gudang, status_aktif), asset_lokasi_pic_m, master_cabang, master_departemen, data_karyawan, asset_admin, asset_kategori_m.
• Modul lain: asset_data, asset_trx_log, notifikasi (notif_data, FCM); pengecekan kunci terhadap Onboarding Ruangan (RGN01) dan Penambahan Asset Ruangan (RGN04); opsi pengganti dari AssetReturKaryawan_m::getAdminOptions (KRY04).
• Berbagi komponen mobile: halaman retur karyawan (untukRuangan), AssetReturAdminConfirmationSheet, dialog Lokasi Tujuan Asset, AssetAlurStepper.retur, AssetReturTimelineCards.
• SQL manual: urutan setelah sql-pml04-disposal.sql (enum jenis_log mengasumsikan sampai disposal_gudang).

43Source Code Reference

44Developer Notes

• Alur dan kontrak sengaja dibuat sama dengan KRY04 supaya halaman mobile dapat dipakai ulang; perbedaan utama ada di §39.
• Tanggal/jam NULL (bukan 0000-00-00); nullableDateValue/nullableTimeValue mengubah NULL dan nilai nol menjadi "" untuk mobile.
• id_asset_lokasi_m_tujuan dan parent_id NULL pada item asal; kode memeriksa parent_id NULL atau '' untuk keamanan.
• asset_data tidak dikunci saat pengajuan; konsistensi dijaga lewat hasActiveReturRuanganAsset dan penyaringan opsi. Flow lain yang ingin menghormati retur ruangan harus memanggil helper tersebut.
• Log memakai asset_trx_log (jenis_log='retur_ruangan'). Dokumen KRY04 sudah dikoreksi (v1.8) dan selaras dengan kode.
• Mengubah enum jenis_log harus mempertahankan seluruh nilai lama (lihat blok 3 SQL).
• tests/Routing memuat angka jumlah route yang ditulis keras (506); hasil nyata 537 sehingga 4 test gagal. Penyebab selisih tidak diselidiki di sini.
• Pemformatan: hanya dart format pada file Dart yang diubah.

45End-to-End Traceability

45.4 Walkthrough Lengkap dengan Contoh Data

Walkthrough berikut mengikuti satu retur dari awal sampai selesai: PIC Ruangan mengajukan tiga asset dengan alasan berbeda, Admin/HR memutuskan per asset (dua disetujui, satu ditolak, satu mendapat pengganti), lalu Admin/HR menerima asset dengan memilih gudang tujuan per asset. Setiap langkah menjelaskan apa yang dilakukan di mobile, apa yang dikirim, apa yang diproses API, apa yang tersimpan di database, dan apa yang diterima mobile. Data bersifat sintetis, tetapi nama kolom, urutan proses, dan pesan diambil dari kode (AssetReturRuangan_m, AssetKaryawanReturRuangan_c, AssetAdminReturRuangan_c, AssetNotification).

Data awal

Company CMP001. Tanggal 22 Oktober 2026, periode ID 202610.

data_karyawan (semua aktif)

asset_lokasi_m: LOK0007 "Ruang Meeting Lt.2" (tipe = ruangan, status_aktif = 1, cabang "Jakarta", departemen "Operasional"), asset_lokasi_pic_m menunjuk KRY0030. Gudang: LOK0001 "Gudang Pusat" dan LOK0002 "Gudang Cadangan" (tipe = gudang).

asset_data

Penomoran: header dan item memakai id_company + YYYYMM + 3 digit (urut per tabel); no_trx = RGN06-YYYYMMNNN (unik per company); asset_trx_log dan notifikasi memakai 5 digit. Pengajuan tidak mengunci asset_data: asset tetap terpakai sampai Terima Asset; penjagaannya lewat pengecekan retur aktif.

Langkah 0 — PIC memilih ruangan dan asset

Mobile: halaman PIC Ruangan → Retur Asset → Ajukan Retur Asset Ruangan. Setelah ruangan dipilih, layar memanggil API-06.

Dikirim

GET /asset/karyawan/pic-ruangan/retur/options?id_asset_lokasi_m=LOK0007
Authorization: Bearer <access_token_dewi>

Diproses API: getOptionsPic memastikan ruangan aktif dan milik PIC login (selain itu 403 FORBIDDEN: "Ruangan tidak ditemukan, tidak aktif, atau Anda bukan PIC ruangan ini."), lalu menampilkan asset terpakai di ruangan itu kecuali yang sedang terkunci di retur aktif, onboarding proses, penambahan proses, atau upgrade aktif. Database: hanya SELECT.

Diterima mobile: AST0401, AST0402, AST0403 dengan nama dan kategori, ditambah pilihan alasan (rusak, tidak_digunakan, tukar_unit).

Langkah 1 — PIC mengajukan retur tiga asset

Mobile: Dewi menambahkan tiga asset, memilih alasan per asset (untuk Laptop: Asset Rusak → Dengan Pengganti + keterangan), mengisi catatan tambahan, lalu Ajukan Retur.

Dikirim

POST /asset/karyawan/pic-ruangan/retur
Authorization: Bearer <access_token_dewi>

{ "id_asset_lokasi_m": "LOK0007",
  "keterangan": "Penataan ulang ruang meeting",
  "items": [
    { "id_asset_data": "AST0401", "alasan_retur": "rusak", "rusak_dengan_pengganti": 2, "ket_retur": "Layar mati total" },
    { "id_asset_data": "AST0402", "alasan_retur": "tidak_digunakan", "ket_retur": "Tidak dipakai lagi" },
    { "id_asset_data": "AST0403", "alasan_retur": "tidak_digunakan" } ] }

Diproses API (AssetKaryawanReturRuangan_c::storeReturRuangan → AssetReturRuangan_m::store, satu DB::transaction(…, 3)) 1. Validasi controller: id_asset_lokasi_m ("Ruangan wajib dipilih."), items minimal satu ("Minimal satu asset wajib dipilih."), id_asset_data wajib dan tidak kembar ("Asset retur wajib dipilih." / "Asset yang sama tidak boleh dipilih lebih dari sekali."), alasan_retur ("Alasan retur setiap asset wajib dipilih." / "Alasan retur asset tidak valid."), rusak_dengan_pengganti ∈ 0/1/2 ("Pilihan pengganti asset rusak tidak valid."), ket_retur maksimal 255. 2. lockCompany; karyawan aktif ("Karyawan tidak ditemukan atau tidak aktif."). 3. findRuanganPic: ruangan aktif dan PIC-nya pengaju ("Ruangan tidak ditemukan, tidak aktif, atau Anda bukan PIC ruangan ini."). 4. normalizeItems menerapkan aturan per alasan: rusak wajib memilih tanpa/dengan pengganti ("Asset rusak wajib memilih tanpa atau dengan pengganti.") dan keterangan ("Keterangan kerusakan asset wajib diisi."); tukar unit wajib keterangan ("Alasan tukar unit wajib diisi."); selain rusak, rusak_dengan_pengganti dipaksa 0. 5. Asset dibaca FOR UPDATE dengan syarat pemegang_asset = ruangan dan lokasi = ruangan ini ("Satu atau beberapa asset bukan milik ruangan atau sudah tidak dapat diretur."). 6. Cek lintas flow: retur aktif lain ("Satu atau beberapa asset sedang diproses pada retur lain."), onboarding ruangan ("…pada onboarding ruangan."), penambahan ruangan ("…pada penambahan asset ruangan."), upgrade ruangan ("…pada upgrade ruangan."); status harus terpakai ("Satu atau beberapa asset tidak berstatus terpakai dan tidak dapat diretur."). 7. Nomor: CMP001202610001, RGN06-202610001. INSERT header dan tiga item. Tidak ada UPDATE asset_data. 8. Controller mengirim retur_ruangan.diajukan ke semua admin asset.

Hasil database

asset_trx_retur_ruangan (1 baris)

asset_trx_retur_ruangan_item (3 item asal; parent_id NULL)

asset_data: tidak berubah (ketiganya tetap terpakai di LOK0007).

notif_data: satu baris per admin asset, rute asset_admin_detail_retur_ruangan, judul "Pengajuan Retur Asset Ruangan", isi "Dewi PIC mengajukan retur asset untuk Ruang Meeting Lt.2 (RGN06-202610001).". Push FCM ikut dikirim; kegagalan push hanya dicatat di log.

Diterima mobile (HTTP 201)

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

Retur muncul di tab Pengajuan milik PIC.

Langkah 2 — Admin membuka detail dan opsi pengganti

Mobile: Ruangan → Retur → tab Pengajuan → detail. Detail menampilkan tiap asset dengan alasannya; AssetAdminReturRuangan memuat opsi pengganti.

Dikirim

GET /asset/retur-ruangan/options
GET /asset/retur-ruangan/CMP001202610001
Authorization: Bearer <access_token_admin>

Diproses API: hanya admin asset (selain itu 403 FORBIDDEN). getAdminOptions mengembalikan asset tersedia di gudang dan kategori; getDetailAdmin menggabungkan header, item, pasangan asal–pengganti lewat parent_id, dan lokasi_gudang[]. Database: hanya SELECT.

Diterima mobile: AST0501 muncul sebagai kandidat pengganti. Tombol aksi: Tolak, Setujui, Ganti Asset per asset.

Langkah 3 — Admin memutuskan per asset

Mobile: Siti menyetujui AST0401 dan memilih AST0501 sebagai pengganti, menyetujui AST0402, menolak AST0403 dengan alasan, memilih metode Dijadwalkan (24 Okt 2026 pukul 10:00), lalu mengonfirmasi.

Dikirim

POST /asset/retur-ruangan/CMP001202610001/konfirmasi

{ "items": [
    { "id_item": "CMP001202610001", "status_item": "disetujui", "id_asset_pengganti": "AST0501" },
    { "id_item": "CMP001202610002", "status_item": "disetujui" },
    { "id_item": "CMP001202610003", "status_item": "ditolak", "ket_tolak": "Masih dipakai rapat mingguan" } ],
  "metode_serah_terima": "dijadwalkan",
  "tgl_pengambilan": "2026-10-24", "jam_pengambilan": "10:00",
  "keterangan_serah_terima": "Bawa troli" }

Diproses API (konfirmasiReturRuangan → konfirmasiAdmin) 1. Validasi controller: items ("Keputusan asset retur wajib diisi."), status_item hanya disetujui/ditolak, ket_tolak wajib bila ditolak ("Alasan penolakan asset wajib diisi."), metode_serah_terima ∈ dijadwalkan|langsung ("Metode serah terima retur tidak valid."), tanggal Y-m-d dan jam H:i wajib bila dijadwalkan. 2. lockCompany; aktor harus admin asset ("Pengguna tidak terdaftar sebagai admin asset."); header FOR UPDATE ("Retur asset tidak ditemukan."); harus pengajuan/proses ("Retur asset sudah tidak menunggu konfirmasi."). 3. Keputusan harus mencakup seluruh item asal, tidak kurang dan tidak lebih ("Seluruh asset retur wajib dikonfirmasi."). Asset asal harus masih dipegang ruangan ini ("Satu atau beberapa asset sudah tidak dipegang oleh ruangan."). 4. Per item: keputusan bukan disetujui/ditolak → "Keputusan asset harus disetujui atau ditolak."; ditolak tanpa alasan ditolak; ditolak dengan pengganti → "Asset yang ditolak tidak boleh memiliki asset pengganti."; disetujui yang membutuhkan pengganti (tukar unit, atau rusak dengan pengganti = 2) tanpa pengganti → "Asset pengganti wajib dipilih untuk retur ini."; disetujui yang tidak membutuhkan pengganti tetapi diberi → "Alasan retur ini tidak memerlukan asset pengganti."; pengganti kembar → "Asset pengganti yang sama tidak boleh dipilih lebih dari sekali.". 5. Pengganti dikunci lewat getLockedAssets (harus tersedia di gudang; "Satu atau beberapa asset pengganti tidak tersedia."). 6. Bila ada yang disetujui, metode wajib valid; dijadwalkan butuh tanggal dan jam ("Tanggal dan jam serah terima wajib diisi."), format benar ("Format jadwal serah terima tidak valid."), tanggal tidak sebelum tgl_pengajuan ("Tanggal serah terima tidak boleh sebelum tanggal pengajuan."). 7. UPDATE keputusan tiap item asal; INSERT item pengganti (parent_id = item asal); UPDATE pengganti → proses; UPDATE header. 8. Controller mengirim retur_ruangan.dikonfirmasi (atau ditolak bila semua ditolak) ke PIC.

Hasil database

asset_trx_retur_ruangan_item

Baris pengganti menyalin alasan_retur item asal (rusak), rusak_dengan_pengganti = 0, ket_retur = '', user_input = admin.

asset_data: hanya AST0501 berubah, status_asset tersedia → proses (user_update = ADM-001 - Siti Admin). AST0401–AST0403 tetap terpakai di ruangan.

asset_trx_retur_ruangan (header)

notif_data: baris untuk KRY0030, rute asset_pic_ruangan_retur, judul "Retur Asset Ruangan Dikonfirmasi", isi "Retur asset RGN06-202610001 untuk Ruang Meeting Lt.2 telah dikonfirmasi admin.".

Diterima mobile (HTTP 200; pesan "Retur asset ruangan berhasil dikonfirmasi.")

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

Transaksi pindah ke tab Dikonfirmasi; tombol Terima Asset muncul untuk Admin/HR.

Langkah 4 — Admin menerima asset dan memilih gudang

Pada 24 Okt, laptop rusak dan proyektor tiba. Siti memilih gudang tujuan per asset asal yang disetujui: Laptop rusak ke LOK0001, proyektor ke LOK0002.

Dikirim

POST /asset/retur-ruangan/CMP001202610001/terima

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

Diproses API (terimaReturRuangan → terimaAdmin) 1. Validasi: items wajib, id tidak kembar, gudang wajib ("Lokasi gudang tujuan setiap asset wajib dipilih." / "Lokasi gudang tujuan wajib dipilih."). 2. lockCompany, admin asset, header FOR UPDATE; harus disetujui/proses ("Retur asset belum dikonfirmasi atau sudah selesai."). 3. Item asal yang disetujui dipetakan ke gudang lewat resolveItemLocations: setiap item tepat satu kali ("Lokasi gudang tujuan asset tidak sesuai."), semua item terisi, dan lokasi harus bertipe gudang pada company yang sama ("Lokasi gudang tujuan tidak valid."). Item yang ditolak tidak dimasukkan. Tidak ada item disetujui → "Tidak ada asset retur yang dapat diterima.". 4. Semua asset terkait dikunci FOR UPDATE; asset asal harus masih dipegang ruangan ("Satu atau beberapa asset sudah tidak dipegang oleh ruangan.") dan pengganti harus masih proses di gudang ("Asset pengganti sudah tidak siap diserahterimakan."). 5. Per asset asal: UPDATE asset_data ke gudang (rusak → rusak + ket_rusak, selain itu tersedia), simpan id_asset_lokasi_m_tujuan di item, siapkan log. Bila ada pengganti: UPDATE asset_data → terpakai di ruangan, siapkan log. 6. INSERT semua baris asset_trx_log sekaligus, lalu UPDATE header → status_transaksi = selesai. 7. Controller mengirim retur_ruangan.diterima_admin ke PIC.

Hasil database

asset_data

asset_trx_retur_ruangan_item: kolom id_asset_lokasi_m_tujuan terisi LOK0001 pada CMP001202610001 dan LOK0002 pada CMP001202610002.

asset_trx_log (3 baris; nomor contoh dengan asumsi log pertama periode 202610)

Semua baris memakai jenis_log = retur_ruangan, id_transaksi = CMP001202610001, nama_tabel_transaksi = asset_trx_retur_ruangan. Urutan log mengikuti urutan item: asset asal, pengganti miliknya, lalu item berikutnya.

asset_trx_retur_ruangan (header): status_transaksi proses → selesai; tgl_serah_terima = 2026-10-24, jam_serah_terima = waktu penerimaan (misalnya 10:05:00); tgl_update/user_update diperbarui. status_approval tetap disetujui.

notif_data: baris untuk KRY0030, judul "Retur Asset Ruangan Diterima", isi "Asset retur RGN06-202610001 untuk Ruang Meeting Lt.2 telah diterima admin.".

Diterima mobile (HTTP 200)

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

Langkah 5 — PIC memantau

PIC tidak memiliki aksi terima, ubah, atau batal. Dewi hanya membuka daftar GET /asset/karyawan/pic-ruangan/retur?tab=diterima dan detail GET …/retur/CMP001202610001. Akses dibatasi ke ruangan yang saat ini dipegang PIC (join asset_lokasi_pic_m); PIC lain mendapat 404 NOT_FOUND ("Retur asset ruangan tidak ditemukan."). Detail PIC tidak menyertakan lokasi_gudang[]. Banner pada halaman PIC Ruangan hilang setelah transaksi selesai.

Kondisi akhir

Variasi

• Semua asset ditolak: tidak ada metode serah terima yang diperlukan; header menjadi status_approval = ditolak, status_transaksi = selesai, ket_tolak = "Seluruh asset retur ditolak."; tidak ada pengganti, asset_data tidak berubah, PIC dinotifikasi retur_ruangan.ditolak (judul "Retur Asset Ruangan Ditolak"). Respons: "Retur asset ruangan berhasil ditolak.", tab pengajuan, label "Ditolak". Terima Asset tidak dapat dijalankan karena status bukan disetujui.
• Metode Langsung: metode_serah_terima = "langsung", tanpa tanggal dan jam; flag_jadwalkan = 0, tgl_pengambilan/jam_pengambilan tetap NULL. Terima Asset dapat dilakukan kapan saja setelah konfirmasi.
• Tukar unit: alasan_retur = tukar_unit (keterangan wajib) selalu membutuhkan pengganti saat disetujui. Asal kembali ke gudang sebagai tersedia (bukan rusak) dan pengganti masuk ke ruangan. Tidak ada syarat kategori yang sama.
• Rusak tanpa pengganti: rusak_dengan_pengganti = 1; Admin tidak boleh memberi pengganti ("Alasan retur ini tidak memerlukan asset pengganti."). Asal kembali ke gudang sebagai rusak.
• Tidak digunakan: asal kembali sebagai tersedia; keterangan opsional; pengganti dilarang.

Kasus gagal

Semua kesalahan aturan bisnis dilempar sebagai InvalidArgumentException di dalam transaksi, sehingga seluruh perubahan di-rollback dan controller membalas BUSINESS_RULE_VIOLATION dengan pesan di bawah.

Ringkasan siapa mengerjakan apa

46Ringkasan Database Impact

47Checklist Implementasi

• DBML diperbarui ([NEW ALK-RGN06])
• SQL manual dibuat (sql-alk-rgn06-retur-ruangan.sql) dan sudah dijalankan pengguna
• SQL sql-alk-rgn06-no-trx-unik-per-company.sql dijalankan dan diverifikasi (perlu dikonfirmasi)
• Model, controller, route, notifikasi API
• Ringkasan admin dan beranda PIC (ruangan_retur_*, retur_ruangan)
• Test API (16) lolos dan seluruh tests/Asset (224) lolos
• Model, API client, bloc, halaman, route, teks mobile
• Test mobile retur ruangan (25) lolos
• Uji di server/emulator dan MariaDB nyata, termasuk push notifikasi
• Jalur batal/edit pengajuan (belum ada)
• Pengenalan retur_ruangan pada riwayat log asset (belum ada)

48Changelog