Perbaikan Asset (PML02)

01Informasi Dokumen

03Quick Overview

Aset gudang yang rusak diperbaiki oleh vendor atau tim internal. Admin membuat transaksi perbaikan (dipilih satu atau banyak aset sekaligus; sistem membuat satu transaksi per aset dengan jadwal dan PIC masing-masing), menunjuk PIC Service dari master pendamping, dan menetapkan jadwal serah terima. PIC menerima aset dengan checklist, mengirimnya ke tempat service (data vendor, bukti), memantau progres, lalu mengisi hasil service dan mengajukan jadwal serah terima balik. Admin menerima aset kembali dengan checklist kondisi, lalu menentukan tindak lanjut per aset.

04Ringkasan Fitur

05Tujuan Fitur

5.1 Tujuan Bisnis (diturunkan dari kode)

• Aset rusak punya jalur perbaikan yang tercatat dan bisa diaudit.
• Perpindahan fisik aset admin → PIC → tempat service → PIC → admin terdokumentasi dengan checklist.
• Hasil service menentukan nasib aset: kembali tersedia, diganti unit baru, atau disposal.

5.2 Tujuan Sistem

• Mengunci aset sepanjang proses lewat status_asset.
• Memvalidasi data vendor, bukti, dan hasil sesuai jenis pelaksana dan hasil.
• Mencatat asset_trx_log dan memberi notifikasi pada tiap perpindahan tanggung jawab.

06Aktor

07Hak Akses

08Terminologi

09Business Rules

BR-001 — Aset yang boleh diperbaiki

Hanya pemegang_asset = gudang dan status_asset = rusak; tidak boleh masih dalam onboarding aktif. Pelanggaran: "Hanya asset rusak di gudang yang dapat diperbaiki."

BR-002 — PIC Service

Dipilih dari pendamping aktif. Dapat berubah hanya selama menunggu_serah_terima.

BR-003 — Penerimaan aset

Checklist status_kesesuaian_item dan status_kelengkapan_aset (ya/tidak) untuk semua aset. Bila ada tidak, keterangan wajib. Aset menjadi dalam_perbaikan.

BR-004 — Pengiriman ke tempat service

Per aset wajib: pelaksana, tanggal mulai, estimasi selesai (tidak sebelum mulai), lokasi. Bila vendor: nomor referensi dan foto tanda terima wajib. Boleh diperbarui berulang selama dalam_service.

BR-005 — Progres

Hanya setelah data pengiriman seluruh aset terisi. Minimal satu aset; keterangan wajib; estimasi baru (opsional) tidak boleh sebelum tanggal mulai dan memperbarui estimasi item.

BR-006 — Hasil service

Seluruh aset wajib diisi. diperbaiki/diganti_unit_baru: komponen dan kondisi akhir wajib. tidak_bisa_diperbaiki: keterangan wajib. PIC sekaligus mengajukan jadwal serah terima balik (tidak boleh sebelum hari ini). Fase → menunggu_pengembalian.

BR-007 — Terima kembali

Admin mengisi checklist kesesuaian kondisi dengan hasil service; tidak memerlukan keterangan. Fase → menunggu_review.

BR-008 — Review per aset

• diperbaiki: aset tersedia di gudang tujuan (default gudang asal; admin boleh pilih gudang lain), kondisi_awal = normal, ket_rusak/status_rusak dikosongkan. Tindak lanjut simpan_gudang.
• diganti_unit_baru: admin memilih unit baru (gudang, tersedia, belum dipakai perbaikan/klaim lain). Unit lama tetap rusak, tindak lanjut disposal (asset_trx_disposal).
• tidak_bisa_diperbaiki: aset tetap rusak, tindak lanjut disposal.

BR-009 — Penomoran

id = id_company + YYYYMM + 3 digit; no_trx = PML02-YYYYMMNNN. Batas 999 per bulan per perusahaan.

BR-010 — Skema harus sudah diterapkan

skemaSiap() menjaga dashboard tetap berjalan sebelum SQL diterapkan.

10Business Flow

1. Admin memilih aset gudang rusak, mengisi jadwal serah terima dan PIC Service → menunggu_serah_terima, aset menunggu_serah_terima_service.
2. PIC menerima aset dengan checklist → dalam_service, aset dalam_perbaikan.
3. PIC mengisi data pengiriman ke tempat service, lalu mencatat progres sesuai perkembangan.
4. PIC mengisi hasil per aset dan jadwal serah terima balik → menunggu_pengembalian.
5. Admin menerima aset kembali dengan checklist → menunggu_review.
6. Admin mereview dan menentukan tindak lanjut → selesai.

11Flow Berdasarkan Role

11.1 Admin Asset

Buat → (ubah) → (cadangan terima/kirim/hasil) → atur jadwal balik → terima kembali → review.

11.2 PIC Service

Terima notifikasi → terima aset → kirim ke service → progres → hasil.

11.3 System

Kunci status aset per tahap, validasi, tautkan unit pengganti, log, notifikasi.

12Flow Diagram

flowchart TD
    A[Aset gudang rusak] --> B[Admin buat perbaikan + PIC]
    B --> C[menunggu_serah_terima<br/>asset menunggu_serah_terima_service]
    C --> D[PIC terima + checklist]
    D --> E[dalam_service<br/>asset dalam_perbaikan]
    E --> F[Kirim ke tempat service]
    F --> G[Progres berulang]
    G --> H[Hasil per aset + jadwal balik]
    H --> I[menunggu_pengembalian]
    I --> J[Admin terima kembali + checklist]
    J --> K[menunggu_review]
    K --> L{Hasil per aset}
    L -- diperbaiki --> M[tersedia di gudang]
    L -- diganti unit baru --> N[unit lama rusak, tindak lanjut disposal]
    L -- tidak bisa diperbaiki --> N
    M --> S[selesai]
    N --> S

13Sequence Diagram

sequenceDiagram
    actor Admin
    actor PIC
    participant API
    participant DB
    Admin->>API: POST perbaikan
    API->>DB: header+item, asset menunggu_serah_terima_service
    API-->>PIC: perbaikan.ditugaskan
    PIC->>API: POST karyawan/perbaikan/{id}/terima
    API->>DB: asset dalam_perbaikan, fase dalam_service
    API-->>Admin: perbaikan.diterima
    PIC->>API: POST .../kirim
    API-->>Admin: perbaikan.masuk_service
    PIC->>API: POST .../progres (berulang)
    PIC->>API: POST .../hasil
    API-->>Admin: perbaikan.hasil
    Admin->>API: POST perbaikan/{id}/terima-kembali
    API-->>PIC: perbaikan.diterima_kembali
    Admin->>API: POST perbaikan/{id}/review
    API->>DB: tindak lanjut per aset, fase selesai
    API-->>PIC: perbaikan.selesai

14Status Transaksi

Status per item (status_perbaikan): proses → selesai saat review.

15State Transition

stateDiagram-v2
    [*] --> menunggu_serah_terima: Admin buat
    menunggu_serah_terima --> menunggu_serah_terima: ubah jadwal / PIC
    menunggu_serah_terima --> dalam_service: terima aset
    dalam_service --> dalam_service: kirim / progres
    dalam_service --> menunggu_pengembalian: hasil
    menunggu_pengembalian --> menunggu_pengembalian: atur jadwal balik
    menunggu_pengembalian --> menunggu_review: terima kembali
    menunggu_review --> selesai: review
    selesai --> [*]

16Struktur Database

17Relasi Database

erDiagram
    asset_trx_perbaikan ||--o{ asset_trx_perbaikan_item : memiliki
    asset_trx_perbaikan_item ||--o{ asset_trx_perbaikan_progres : mencatat
    asset_trx_perbaikan }o--|| asset_pendamping_m : "PIC Service"
    asset_trx_perbaikan_item }o--|| asset_data : "asset lama"
    asset_trx_perbaikan_item }o--o| asset_data : "unit baru"
    asset_trx_perbaikan_item }o--o| asset_vendor_m : "vendor"
    asset_trx_perbaikan_item }o--o| asset_lokasi_m : "gudang asal/tujuan"

18Data Dictionary

18.1 asset_trx_perbaikan

18.2 asset_trx_perbaikan_item

18.3 asset_trx_perbaikan_progres

id_asset_trx_perbaikan_progres (PK), id_asset_trx_perbaikan_item (FK), keterangan_progres, tgl_estimasi_selesai_baru, id_company, tgl_input, user_input.

19Database Index

20Backend Architecture

21Backend Business Logic

21.1 Buat — store

Menerima daftar perbaikan[] (1–50 elemen). Semua aset dikunci (lockForUpdate) dan seluruh elemen divalidasi lebih dulu (BR-001, PIC, jadwal per aset); lalu per aset dibuat satu header + satu item (snapshot, gudang asal) dengan nomor urut sendiri; aset → menunggu_serah_terima_service + log. Pesan batas nomor urut mengikuti locale.

21.2 Ubah — ubah

Hanya menunggu_serah_terima; mengembalikan pic_berubah.

21.3 Terima — terima

Aktor PIC atau admin (lockForActor); checklist per aset; aset → dalam_perbaikan; fase dalam_service.

21.4 Kirim — kirim

Boleh berulang; baru = true bila ada item yang pertama kali diisi (menentukan event masuk_service vs progres).

21.5 Progres — progres

Memasukkan baris progres dan memperbarui estimasi item bila ada estimasi baru.

21.6 Hasil — hasil

Validasi per hasil (BR-006); mengajukan jadwal balik; fase menunggu_pengembalian.

21.7 Jadwal balik / terima kembali

Admin: jadwalKembali (ubah jadwal), terimaKembali (checklist, fase menunggu_review).

21.8 Review — review

Per item sesuai BR-008; unit baru divalidasi (assertUnitBaru: gudang, tersedia, tidak dipakai perbaikan/klaim lain); gudang tujuan divalidasi (assertGudang); item status_perbaikan = selesai; fase selesai.

21.9 Query baca

getPage, getDetail (dengan objek aksi per peran), getAdminOptions, getVendorOptions, getPendingForPic/Admin, countByTabForPic, countPendingForAdmin, hasActivePic.

22Dampak terhadap asset_data

23API Documentation

24Detail Setiap API

API-001/013 — Opsi

Admin: {vendor, pendamping, asset (gudang rusak), asset_baru (gudang tersedia), gudang, hasil, pelaksana}. PIC: hanya vendor.

API-002/014 — Daftar

Query tab (jadwal|proses|selesai), limit (1–50), offset. Respons {filters, records[], pagination}; record memuat fase_perbaikan, jadwal, peran, jumlah_asset, ringkasan aset, PIC.

API-003 — Buat

{"perbaikan": [
  {"id_asset_data": "AC-1", "tgl_jadwal": "2026-10-12", "jam_jadwal": "09:00",
   "id_asset_pendamping_m": "PDM-1", "keterangan_serah_terima": "Bawa kelengkapan"},
  {"id_asset_data": "AC-2", "tgl_jadwal": "2026-10-13", "jam_jadwal": "10:00",
   "id_asset_pendamping_m": "PDM-2", "keterangan_serah_terima": ""}
]}

Array perbaikan berisi 1–50 elemen dengan id_asset_data unik; jadwal, PIC Service, dan keterangan diisi per aset. Server membuat satu transaksi (header + satu item) per aset dalam satu transaksi database: bila satu elemen gagal validasi, tidak ada yang tersimpan. Field lama asset_ids sudah dihapus (request lama → 422). Respons sukses 201 CREATED: {"records": [{id, no_trx, fase_perbaikan, status_label, tab, id_asset_data}], "jumlah": N}. Pesan error aturan bisnis diawali nama aset, mis. "Asset Laptop A: …". Notifikasi perbaikan.ditugaskan dikirim per transaksi. Transaksi lama yang berisi banyak aset tetap dapat diproses pada fase terima sampai review.

API-004 — Ubah

Body satu objek: tgl_jadwal, jam_jadwal, id_asset_pendamping_m, keterangan_serah_terima (tanpa perbaikan[] dan id_asset_data).

API-005/015 — Terima

{"assets": [{"id_asset_data": "AC-1", "status_kesesuaian_item": "ya", "status_kelengkapan_aset": "tidak", "keterangan": "Kabel daya tidak ada"}]}

API-006/016 — Kirim

{"assets": [{
  "id_asset_data": "AC-1", "jenis_pelaksana": "vendor", "id_asset_vendor_m": "VND-1",
  "keterangan_vendor": "0812-0000", "tgl_mulai_perbaikan": "2026-10-13",
  "tgl_estimasi_selesai_perbaikan": "2026-10-20", "lokasi_perbaikan": "Bengkel Vendor",
  "nomor_referensi": "SRV-001", "foto_tanda_terima": "<base64 atau file multipart>"
}]}

Foto disimpan di object storage dengan key <company>/asset/perbaikan/<id_karyawan>/<hex>.<ext>; kolom menyimpan key; kosong = foto lama dipertahankan.

API-007/017 — Progres

{"assets": [{"id_asset_data": "AC-1", "keterangan_progres": "Menunggu sparepart", "tgl_estimasi_selesai_baru": "2026-10-25"}]}

API-008/018 — Hasil

{
  "tgl_pengembalian": "2026-10-26", "jam_pengembalian": "13:00",
  "assets": [{"id_asset_data": "AC-1", "hasil_perbaikan": "diperbaiki",
    "komponen_diperbaiki": "Roller", "komponen_watchlist": "", "kondisi_akhir": "Normal",
    "keterangan_hasil": ""}]
}

API-009 — Jadwal balik

{tgl_pengembalian, jam_pengembalian}.

API-010 — Terima kembali

{assets: [{id_asset_data, status_kesesuaian_kembali: ya|tidak, ket_kesesuaian_kembali}]}.

API-011 — Review

{"keterangan_review": "Selesai",
 "items": [{"id_asset_data": "AC-2", "id_asset_data_baru": "AC-NEW", "id_asset_lokasi_m_tujuan": ""}]}

Aset diperbaiki memakai id_asset_lokasi_m_tujuan (kosong = gudang asal); aset diganti_unit_baru wajib id_asset_data_baru.

API-012/019 — Detail

Header, PIC, serah_terima, pengembalian, review, assets[] (penerimaan, service, progres, hasil, kembali, tindak lanjut), dan aksi (ubah, terima, kirim, progres, hasil, jadwal_kembali, terima_kembali, review).

25Mobile Architecture

26Mobile Screen

26.1 Daftar

HalamanAssetPerbaikan (admin dan PIC): tab Serah Terima/Proses/Selesai, kartu AssetPerbaikanRecordCard.

26.2 Buat Perbaikan (admin)

HalamanBuatPerbaikan: pilih satu atau banyak aset gudang rusak (checkbox, maks. 50), lalu Lanjut membuka HalamanFormBuatPerbaikan dengan satu kartu per aset (tanggal, jam, PIC Service, keterangan). Submit mengirim satu request perbaikan[]; server membuat satu transaksi per aset.

26.3 Detail

HalamanDetailAssetPerbaikan: hero, stepper proses, timeline per aset (AssetPerbaikanAssetTimeline), tombol sesuai aksi.

26.4 Sheet aksi

AssetPerbaikanActionSheets: terima, kirim (vendor terdaftar/manual, foto kamera/galeri), progres, hasil, terima kembali, review.

26.5 Entry point

Admin: menu Perbaikan dan kartu "perlu diproses" beranda. PIC: kartu Tugas PIC.

27Mobile → API

Prefix asset/perbaikan (admin) atau asset/karyawan/perbaikan (PIC).

28API → Mobile

Dipetakan ke AssetPerbaikanRecord/Page/Options; objek aksi menentukan tombol. 422 tampil sebagai snackbar warning, kegagalan lain sebagai error; sukses menutup halaman dengan pesan.

29Mapping Mobile → API → Database

30Mapping Database → API → Mobile

31Validation

31.1 Mobile

Form sheet memvalidasi wajib-isi (tanggal, jam, PIC, lokasi, vendor, nomor referensi, foto bila vendor, estimasi ≥ mulai, hasil, komponen, kondisi akhir).

31.2 Backend

Aturan Laravel di Asset_c/controller (format Y-m-d, H:i, in: untuk enum) ditambah aturan bisnis di model (§9).

31.3 Database

Enum fase/status/hasil/pelaksana/tindak lanjut; FK PIC, vendor, lokasi, aset; unik (trx, asset).

32Error Handling

33Audit Trail

user_terima, user_ajukan_pengembalian, user_terima_kembali, user_review beserta timestamp; user_input/user_update per baris; asset_trx_log (perbaikan_gudang) saat dibuat dan saat review.

34Notification

35Security

JWT; admin diperiksa per request; PIC dibatasi ke id_pic_pendamping miliknya dan harus karyawan aktif; foto diunggah ke bucket MinIO privat lewat Asset_c::uploadAssetImage (AssetImageStorage): hanya JPEG/PNG/WebP valid, maks 5 MB dan 25 megapiksel; key memuat id_company dan id_karyawan dari JWT; URL foto berupa presigned URL berumur singkat (lihat dokumentasi-minio-object-storage.md); semua query memfilter id_company; transaksi + lockForUpdate.

36Manual Book User/Admin

A. Admin — Membuat perbaikan

Perbaikan → tombol + → centang satu atau banyak aset rusak → Lanjut → isi tanggal, jam, PIC Service, dan keterangan untuk tiap aset → Buat Perbaikan. Setiap aset menjadi satu transaksi perbaikan sendiri.

B. PIC — Menerima aset

Tugas PIC → transaksi → Terima Aset → isi checklist kondisi dan kelengkapan.

C. PIC — Service

Isi Data Pengiriman (pelaksana, tanggal, lokasi; vendor wajib nomor referensi dan foto) → Update Progres bila ada perkembangan → Isi Hasil Service dan jadwal serah terima balik.

D. Admin — Menerima kembali dan review

Terima Aset Kembali (checklist) → Review & Tindak Lanjut: pilih gudang tujuan (aset diperbaiki) atau unit baru (aset diganti).

37Kondisi Button

38Testing Scenario

39Temuan Ketidaksesuaian

40Edge Case

• PIC menghapus/mengganti data pengiriman setelah progres: diperbolehkan selama dalam_service.
• Dua unit lama memakai unit baru yang sama: ditolak (penggantiDipakai).
• Unit baru sudah dipakai perbaikan atau klaim garansi lain: ditolak.
• Aset berubah status di luar alur: ditolak "Status asset sudah berubah…".

41Potential Bug / Technical Risk

RISK-001 — Skema dari SQL manual (TINGGI)

SQL belum dijalankan; jalankan setelah SQL PML01 gudang dan PML03 karena blok enum menulis ulang seluruh daftar.

RISK-002 — Tidak ada pembatalan (SEDANG)

Perbaikan yang tertahan mengunci aset.

RISK-003 — Foto lama di disk lokal (RENDAH)

Foto baru disimpan di object storage. Foto lama di UPLOAD_DIR tetap terbaca lewat fallback URL lokal. Object lama tidak dihapus saat foto diganti; object baru yang yatim dibersihkan otomatis bila transaksi gagal.

RISK-004 — Notifikasi di luar transaksi (RENDAH)

RISK-005 — Kapasitas penomoran 999/bulan (RENDAH)

42Dependency

Asset_m/Asset_c, AssetPendamping_m, AssetPemeliharaanKaryawan_m (vendor, format tanggal), AssetImageStorage, AssetNotification, tabel asset_vendor_m, asset_lokasi_m, asset_data.

43Source Code Reference

44Developer Notes

• Pola dasar sama dengan PML01 gudang dan PML03 (lockHeader, lockAssets($status), updateItem, headerResult).
• lockForActor memungkinkan satu method melayani PIC dan admin cadangan.
• Aksi kirim idempotent-update; progres menambah baris.
• Jangan mengubah urutan enum status_asset; nilai baru ditambah di akhir.

45End-to-End Traceability

45.4 Walkthrough Lengkap dengan Contoh Data

Bagian ini mengikuti satu permintaan perbaikan untuk dua asset gudang rusak: satu asset diperbaiki sampai kembali tersedia (alur lengkap, dengan progres service), sedangkan variasi menunjukkan hasil "diganti unit baru" dan "tidak bisa diperbaiki". Setiap langkah menjelaskan 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 (AssetPerbaikan_m, AssetAdminPerbaikan_c, AssetKaryawanPerbaikan_c, AssetNotification).

Skenario: Admin membuat perbaikan untuk printer dan monitor yang rusak di gudang (satu transaksi per asset, masing-masing dengan jadwal dan PIC Service). PIC printer menerima asset dengan checklist, mengirimkannya ke vendor, mencatat progres, dan mengisi hasil "diperbaiki". Admin mengatur ulang jadwal serah terima balik, menerima asset kembali, lalu mereview sehingga printer kembali tersedia.

Data awal

Company CMP001. Perbaikan dibuat 22 Oktober 2026, periode ID 202610. Belum ada transaksi perbaikan, progres, log, atau notifikasi pada periode ini.

asset_data (semua pemegang_asset = gudang, status_asset = rusak, kondisi_awal = rusak, id_asset_lokasi_m = CMP001202601001 = Gudang Pusat)

asset_pendamping_m (PIC Service): CMP001202601001 = Tono Pendamping (KRY0020, EMP-020) untuk printer, CMP001202601002 = Rina Pendamping (KRY0021, EMP-021) untuk monitor. Vendor: asset_vendor_m CMP001VND001 = PT Servis Printer. Admin: KRY0099 (ADM-001, Siti Admin), KRY0100 (ADM-002, Rudi Admin).

Penomoran: header, item, dan progres id_company + YYYYMM + 3 digit, no_trx = PML02-YYYYMMNNN; log dan notifikasi 5 digit. Satu transaksi = satu asset.

Langkah 0 — Admin memuat opsi

Mobile: Pemeliharaan (admin) → Perbaikan → buat → AssetPerbaikanApi memuat opsi.

Dikirim

GET /asset/perbaikan/options
Authorization: Bearer <access_token_admin>

Diproses API (AssetPerbaikan_m::getAdminOptions): vendor, pendamping (aktif), asset (gudang berstatus rusak), asset_baru (gudang tersedia, untuk unit pengganti), gudang, hasil, dan pelaksana. Untuk PIC, opsi hanya memuat vendor. Database: hanya SELECT.

Langkah 1 — Admin membuat perbaikan untuk dua asset

Mobile: admin memilih printer dan monitor; untuk setiap asset mengisi jadwal serah terima, PIC Service, dan keterangan → Simpan.

Dikirim

POST /asset/perbaikan

{
  "perbaikan": [
    { "id_asset_data": "CMP00120260100050", "tgl_jadwal": "2026-10-23", "jam_jadwal": "09:00",
      "id_asset_pendamping_m": "CMP001202601001", "keterangan_serah_terima": "Bawa kelengkapan" },
    { "id_asset_data": "CMP00120260100051", "tgl_jadwal": "2026-10-23", "jam_jadwal": "10:00",
      "id_asset_pendamping_m": "CMP001202601002", "keterangan_serah_terima": "" }
  ]
}

Diproses API (AssetAdminPerbaikan_c → AssetPerbaikan_m::store, satu DB::transaction untuk semua elemen) 1. Validasi: perbaikan 1–50 elemen, id_asset_data unik ("Asset yang sama tidak boleh dipilih lebih dari sekali."). Field lama asset_ids ditolak (422). 2. lockCompany; cek admin. Semua asset dikunci FOR UPDATE. 3. Seluruh elemen divalidasi lebih dulu sebelum ada yang ditulis: asset dipegang gudang dan berstatus rusak ("Hanya asset rusak di gudang yang dapat diperbaiki."), tidak ada di onboarding aktif, PIC dari pendamping aktif, jadwal tidak sebelum hari ini. Pesan error diawali Asset <nama>:. 4. Nomor urut header dan item dihitung sekali untuk N transaksi: …001 dan …002. 5. Per asset: INSERT header (fase_perbaikan = menunggu_serah_terima, snapshot PIC, jadwal), INSERT item (snapshot asset, keterangan_rusak dari asset_data.ket_rusak, pemegang_asset_asal = gudang, id_asset_lokasi_m_asal), UPDATE asset_data → menunggu_serah_terima_service, INSERT asset_trx_log (gudang → gudang). 6. Notifikasi perbaikan.ditugaskan ke PIC tiap transaksi. Bila satu asset gagal, tidak ada transaksi yang tersimpan.

Hasil database

asset_trx_perbaikan (2 baris)

asset_trx_perbaikan_item (2 baris)

asset_data: A50 dan A51 status_asset rusak → menunggu_serah_terima_service.

asset_trx_log (2 baris, jenis_log = perbaikan_gudang): CMP00120261000001 (A50, id_transaksi = CMP001202610001) dan CMP00120261000002 (A51, CMP001202610002), kondisi awal → akhir rusak → rusak, posisi gudang → gudang, user_input = ADM-001 - Siti Admin.

notif_data (2 baris, ke PIC masing-masing)

Diterima mobile (HTTP 201)

{ "code": "CREATED", "message": "…",
  "data": { "records": [
    { "id": "CMP001202610001", "no_trx": "PML02-202610001", "fase_perbaikan": "menunggu_serah_terima",
      "status_label": "Menunggu Serah Terima", "tab": "jadwal", "id_asset_data": "CMP00120260100050" },
    { "id": "CMP001202610002", "no_trx": "PML02-202610002", "fase_perbaikan": "menunggu_serah_terima",
      "status_label": "Menunggu Serah Terima", "tab": "jadwal", "id_asset_data": "CMP00120260100051" } ],
    "jumlah": 2 } }

Selama fase ini admin dapat Ubah jadwal dan PIC (API-004, PUT /asset/perbaikan/{id}; body satu objek: tgl_jadwal, jam_jadwal, id_asset_pendamping_m, keterangan_serah_terima). Bila PIC berganti dikirim perbaikan.ditugaskan, selain itu perbaikan.diubah.

Langkah 2 — PIC menerima asset

Mobile: menu Tugas PIC Service → detail transaksi printer → checklist penerimaan → Terima.

Dikirim

POST /asset/karyawan/perbaikan/CMP001202610001/terima

{ "assets": [ { "id_asset_data": "CMP00120260100050", "status_kesesuaian_item": "ya",
                "status_kelengkapan_aset": "tidak", "keterangan": "Kabel daya tidak ada" } ] }

Diproses API (terima) 1. lockForActor: aktor PIC (header harus miliknya) atau admin sebagai cadangan. 2. Fase harus menunggu_serah_terima ("Perbaikan tidak menunggu serah terima."); asset harus menunggu_serah_terima_service di gudang. 3. Semua asset wajib diperiksa ("Seluruh asset wajib diperiksa."); status_kesesuaian_item dan status_kelengkapan_aset ∈ ya/tidak; bila ada tidak, keterangan wajib ("Keterangan wajib diisi jika ada checklist yang tidak sesuai."). 4. UPDATE item (checklist, keterangan_perbaikan_pendamping) dan UPDATE asset_data → dalam_perbaikan. 5. UPDATE header: fase_perbaikan = dalam_service, tgl_terima, user_terima. Notifikasi perbaikan.diterima ke admin.

Hasil database

Diterima mobile (HTTP 200): fase_perbaikan = dalam_service, status_label = "Dalam Service", tab = "proses".

Langkah 3 — PIC mengirim asset ke tempat service

Mobile: form pengiriman: pelaksana Vendor, vendor dari master, tanggal mulai dan estimasi, lokasi, nomor referensi, foto tanda terima (kamera atau galeri) → Simpan.

Dikirim (multipart, karena ada foto)

POST /asset/karyawan/perbaikan/CMP001202610001/kirim

{ "assets": [ {
    "id_asset_data": "CMP00120260100050", "jenis_pelaksana": "vendor", "id_asset_vendor_m": "CMP001VND001",
    "keterangan_vendor": "0812-0000-0000", "tgl_mulai_perbaikan": "2026-10-24",
    "tgl_estimasi_selesai_perbaikan": "2026-10-30", "lokasi_perbaikan": "Bengkel Vendor",
    "nomor_referensi": "SRV-001", "foto_tanda_terima": "<file multipart atau base64>" } ] }

Diproses API (perbaikanAssetsPayload lalu kirim) 1. prepareImageUpload memvalidasi dulu bahwa fase dalam_service, asset dalam_perbaikan, dan data pengiriman semua asset lengkap, sebelum foto diunggah. 2. Foto diunggah ke object storage dengan key CMP001/asset/perbaikan/<id_karyawan>/<hex>.<ext>; hanya key yang disimpan. Foto kosong = foto lama dipertahankan. 3. kirim: per asset wajib jenis_pelaksana ∈ vendor/internal, tanggal mulai, estimasi selesai (tidak sebelum mulai), dan lokasi. Bila vendor: nomor referensi dan foto tanda terima wajib. Vendor dari master atau teks bebas. 4. UPDATE item. Endpoint ini boleh dipanggil berulang selama dalam_service untuk memperbarui data; baru = true bila ada item yang pertama kali diisi. 5. Notifikasi perbaikan.masuk_service (pengiriman pertama) atau perbaikan.progres (pembaruan) ke admin. Fase tidak berubah.

Hasil database

Diterima mobile (HTTP 200): header ringkas, fase dalam_service.

Langkah 4 — PIC mencatat progres

Mobile: Catat Progres: "Menunggu sparepart", estimasi baru 3 Nov 2026.

Dikirim

POST /asset/karyawan/perbaikan/CMP001202610001/progres

{ "assets": [ { "id_asset_data": "CMP00120260100050", "keterangan_progres": "Menunggu sparepart",
                "tgl_estimasi_selesai_baru": "2026-11-03" } ] }

Diproses API (progres): fase dalam_service; data pengiriman semua asset harus sudah terisi ("Data pengiriman ke tempat service harus diisi sebelum memperbarui progres."); minimal satu asset (tidak wajib semuanya); keterangan wajib; estimasi baru tidak boleh sebelum tanggal mulai. INSERT baris progres; bila ada estimasi baru, tgl_estimasi_selesai_perbaikan item ikut diperbarui. Notifikasi perbaikan.progres ke admin.

Hasil database

Langkah 5 — PIC mengisi hasil service dan jadwal balik

Mobile: Isi Hasil: hasil Diperbaiki, komponen "Roller", kondisi akhir "Normal", jadwal serah terima balik 4 Nov 2026 pukul 13:00.

Dikirim

POST /asset/karyawan/perbaikan/CMP001202610001/hasil

{ "tgl_pengembalian": "2026-11-04", "jam_pengembalian": "13:00",
  "assets": [ { "id_asset_data": "CMP00120260100050", "hasil_perbaikan": "diperbaiki",
                "komponen_diperbaiki": "Roller", "komponen_watchlist": "", "kondisi_akhir": "Normal",
                "keterangan_hasil": "" } ] }

Diproses API (hasil) 1. Fase dalam_service; data pengiriman semua asset sudah terisi; hasil seluruh asset wajib diisi. 2. hasil_perbaikan ∈ diperbaiki/diganti_unit_baru/tidak_bisa_diperbaiki. Untuk dua hasil pertama, komponen_diperbaiki dan kondisi_akhir wajib; untuk tidak_bisa_diperbaiki, keterangan_hasil wajib. 3. Jadwal serah terima balik wajib dan tidak boleh sebelum hari ini. 4. UPDATE item (hasil) dan header: fase_perbaikan = menunggu_pengembalian, jadwal balik, user_ajukan_pengembalian. Notifikasi perbaikan.hasil ke admin.

Hasil database

Diterima mobile (HTTP 200): fase_perbaikan = menunggu_pengembalian, status_label = "Menunggu Pengembalian".

Langkah 6 — Admin mengatur ulang jadwal balik

Dikirim

POST /asset/perbaikan/CMP001202610001/jadwal-kembali

{ "tgl_pengembalian": "2026-11-05", "jam_pengembalian": "10:00" }

Diproses API (jadwalKembali): hanya fase menunggu_pengembalian ("Jadwal pengembalian hanya dapat diubah sebelum aset diterima kembali."). UPDATE tgl_pengembalian_perbaikan dan jam_pengembalian. Notifikasi perbaikan.jadwal_kembali ke PIC.

Hasil database: header tgl_pengembalian_perbaikan 2026-11-04 → 2026-11-05, jam_pengembalian 13:00:00 → 10:00:00; notifikasi CMP00120261000011 ke KRY0020, "Jadwal serah terima balik perbaikan PML02-202610001 telah ditetapkan admin.".

Langkah 7 — Admin menerima asset kembali

Dikirim

POST /asset/perbaikan/CMP001202610001/terima-kembali

{ "assets": [ { "id_asset_data": "CMP00120260100050", "status_kesesuaian_kembali": "ya", "ket_kesesuaian_kembali": "" } ] }

Diproses API (terimaKembali): fase menunggu_pengembalian ("Perbaikan tidak menunggu serah terima balik."); asset masih dalam_perbaikan; semua asset diperiksa; bila tidak, keterangan wajib ("Keterangan wajib diisi jika kondisi asset tidak sesuai."). Fase → menunggu_review. Notifikasi perbaikan.diterima_kembali ke PIC. asset_data belum berubah.

Hasil database

Langkah 8 — Admin mereview dan menentukan tindak lanjut

Mobile: detail admin (aksi.review = true) → Review; gudang tujuan dibiarkan default (gudang asal).

Dikirim

POST /asset/perbaikan/CMP001202610001/review

{ "keterangan_review": "Selesai", "items": [ { "id_asset_data": "CMP00120260100050", "id_asset_lokasi_m_tujuan": "" } ] }

Diproses API (review) 1. Fase harus menunggu_review ("Aset belum diterima kembali dari PIC Service."); items[] hanya boleh memuat asset transaksi ini. 2. Per asset menurut hasil_perbaikan. diperbaiki: gudang tujuan = pilihan admin, bila kosong = gudang asal (id_asset_lokasi_m_asal); wajib gudang bertipe gudang pada company yang sama (assertGudang). UPDATE asset_data → tersedia, id_asset_lokasi_m = tujuan, kondisi_awal = normal, ket_rusak = '', status_rusak = ''; INSERT asset_trx_log (kondisi akhir normal); item tindak_lanjut_akhir = simpan_gudang. 3. UPDATE item status_perbaikan = selesai dan header fase_perbaikan = selesai, status = selesai, tgl_review, user_review, keterangan_review. 4. Notifikasi perbaikan.selesai ke PIC.

Hasil database

Diterima mobile (HTTP 200): fase_perbaikan = selesai, status_label = "Selesai", tab = "selesai".

Kondisi akhir data

asset_trx_perbaikan: CMP001202610001 / PML02-202610001 selesai; CMP001202610002 / PML02-202610002 masih menunggu_serah_terima (belum dikerjakan dalam contoh ini).

asset_data: A50 → tersedia @Gudang Pusat, kondisi_awal = normal; A51 → menunggu_serah_terima_service. asset_trx_perbaikan_progres: 1 baris. asset_trx_log: 3 baris. notif_data: 13 baris.

Variasi

Diganti unit baru. Pada hasil, hasil_perbaikan = diganti_unit_baru (komponen dan kondisi akhir wajib). Pada review, admin wajib memilih id_asset_data_baru per asset: harus berbeda dari asset lama, belum dipakai di asset lain pada review yang sama, bukan salah satu asset transaksi ini, dan lolos assertUnitBaru (gudang, tersedia, belum dipakai perbaikan atau klaim lain). Efeknya: unit lama tetap rusak (log kondisi akhir rusak), item id_asset_data_baru terisi, tindak_lanjut_akhir = disposal, nama_tabel_tindak_lanjut = asset_trx_disposal. Unit baru hanya ditautkan; statusnya tidak diubah oleh review ini.

Tidak bisa diperbaiki. hasil_perbaikan = tidak_bisa_diperbaiki (keterangan wajib; komponen dan kondisi akhir dikosongkan). Review: asset tetap rusak, log kondisi akhir rusak, tindak_lanjut_akhir = disposal, nama_tabel_tindak_lanjut = asset_trx_disposal. Transaksi Disposal tidak dibuat otomatis.

Pelaksana internal. jenis_pelaksana = internal: nomor referensi dan foto tanda terima tidak wajib.

Admin sebagai cadangan. API-005 sampai API-008 (POST /asset/perbaikan/{id}/terima|kirim|progres|hasil) memakai logika yang sama untuk admin tanpa pemeriksaan kepemilikan PIC.

Ganti PIC. Lewat Ubah (API-004) hanya selama menunggu_serah_terima.

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

Tabel baru: asset_trx_perbaikan, _item, _progres (struktur lama di-drop bila kosong). asset_data.status_asset +menunggu_serah_terima_service; asset_trx_log.jenis_log +perbaikan_gudang, perbaikan_karyawan.

47Checklist Implementasi

Database

• DBML diperbarui
• SQL manual + guard + rollback
• SQL dijalankan di setiap environment

Backend

• Model, controller admin dan PIC, route, notifikasi
• Test otomatis

Mobile

• Daftar, buat, detail, sheet aksi
• Teks id/en, test otomatis

Documentation

• Dokumen ini

48Changelog