Pemeliharaan Terjadwal Asset Gudang

01Informasi Dokumen

03Quick Overview

Asset yang tersedia di gudang dan punya jadwal PM (flag_pemeliharaan = 1) muncul di Monitoring Jatuh Tempo sejak H-14. Admin memilih satu atau banyak asset; untuk setiap asset dibuat satu transaksi PM sendiri dengan jadwal, vendor/teknisi, lokasi, dan PIC Pendamping (wajib, dari master pendamping aktif) masing-masing. Sejak dibuat, asset dikunci (dalam_perbaikan). PIC (atau admin sebagai cadangan) langsung mengisi checklist hasil per komponen setelah PM dilaksanakan, tanpa langkah Mulai; hasil asset = komponen terberat. Admin mereview: hasil 1–3 mengembalikan asset ke tersedia dengan jadwal PM berikutnya, hasil 4–5 menandai asset rusak di gudang untuk Perbaikan/Disposal.

04Ringkasan Fitur

05Tujuan Fitur

5.1 Tujuan Bisnis (diturunkan dari kode)

• Asset cadangan di gudang tetap terawat sesuai interval PM.
• Tanggung jawab pelaksanaan jelas: satu PIC Pendamping per transaksi.
• Asset yang sedang dipelihara tidak bisa dipakai modul lain.
• Hasil PM menentukan nasib asset: kembali tersedia, atau ditarik untuk perbaikan/disposal.

5.2 Tujuan Sistem

• Mengunci asset sepanjang PM dan membuka kembali saat selesai/batal.
• Menurunkan hasil asset dari checklist komponen (hasil terberat).
• Menghitung jadwal PM berikutnya dari interval asset.
• Mencatat asset_trx_log (pemeliharaan_gudang) dan notifikasi.

06Aktor

07Hak Akses

Admin ditentukan lewat Asset_m::isAdmin (tabel asset_admin). PIC divalidasi dari id_pic_pendamping header dan status karyawan aktif.

08Terminologi

09Business Rules

BR-001 — Asset yang boleh dipelihara

Hanya asset pemegang_asset = gudang, status_asset = tersedia, flag_pemeliharaan = 1, dan jadwal_pemeliharaan terisi. Pelanggaran: "Hanya asset tersedia di gudang yang dapat dipelihara." atau "…tidak memiliki jadwal pemeliharaan aktif."

BR-002 — Tidak bentrok onboarding

Asset yang masih berstatus belum dicek pada onboarding aktif tidak boleh dipilih.

BR-003 — Asset dikunci

Saat PM dibuat, setiap asset menjadi dalam_perbaikan dan masuk asset_trx_log. Karena statusnya bukan tersedia, asset otomatis hilang dari monitoring dan tidak bisa dipilih modul lain.

BR-004 — PIC wajib

PIC dipilih dari pendamping aktif (flag_aktif = 1). Dapat diganti selama fase penjadwalan atau pelaksanaan; memilih pendamping yang sama ditolak.

BR-005 — Perubahan dan pembatalan

Ubah hanya saat penjadwalan. Batal hanya saat penjadwalan dan alasan wajib; asset kembali tersedia.

BR-006 — Hasil (tanpa langkah Mulai)

Hasil dikirim langsung dari penjadwalan (atau pelaksanaan pada transaksi lama) dan seluruh asset wajib diperiksa, masing-masing dengan checklist komponen lengkap. tgl_mulai/user_mulai terisi otomatis saat hasil dikirim.

BR-007 — Hasil terberat

Hasil asset = hasil komponen tertinggi pada urutan 1–5.

BR-008 — Review hasil 1–3

Asset kembali tersedia; jadwal PM berikutnya dihitung dari tanggal review + interval; hasil 3 dapat membawa tgl_rencana_penggantian_komponen.

BR-009 — Review hasil 4–5

Asset menjadi rusak, kondisi_awal = rusak, ket_rusak dari temuan + catatan review, status_rusak = sudah tidak bisa di gunakan. nama_tabel_tindak_lanjut diisi asset_trx_perbaikan (hasil 4) atau asset_trx_disposal (hasil 5).

BR-010 — Penomoran

id = id_company + YYYYMM + 3 digit; no_trx = PML01-3-YYYYMMNNN. Batas 999 per bulan per perusahaan, dihitung per transaksi (N asset memakai N nomor).

BR-011 — Skema harus sudah diterapkan

Dashboard memanggil skemaSiap(); sebelum SQL diterapkan, bagian gudang kosong tanpa memblokir modul lain.

BR-012 — Satu transaksi satu asset

Setiap transaksi baru memuat tepat satu asset (satu header, satu item), sehingga jadwal, vendor, lokasi, dan PIC ditentukan per asset. Satu request pembuatan boleh memuat 1–50 asset dan menghasilkan satu transaksi per asset secara atomik: bila satu asset gagal validasi, tidak ada transaksi yang tersimpan. Transaksi lama yang berisi banyak asset tetap dapat dibuka, diubah, diisi hasilnya, dan direview seperti sebelumnya.

10Business Flow

1. Admin membuka Monitoring Jatuh Tempo (tab Gudang) dan memilih satu atau banyak asset.
2. Admin mengisi jadwal, vendor/teknisi, lokasi, PIC, keterangan untuk setiap asset (halaman form per asset) → satu transaksi penjadwalan per asset, asset dalam_perbaikan. PIC dinotifikasi per transaksi.
3. Admin dapat mengubah jadwal, mengganti PIC, atau membatalkan.
4. PIC mengisi checklist hasil seluruh asset → menunggu_review. Admin dinotifikasi.
5. Admin mereview → selesai; asset kembali tersedia (hasil 1–3) atau rusak (hasil 4–5).

11Flow Berdasarkan Role

11.1 Admin Asset

Pantau jatuh tempo → buat PM → ubah/ganti PIC/batal bila perlu → (opsional) isi hasil sebagai cadangan → review.

11.2 PIC Pendamping

Terima notifikasi tugas → isi checklist hasil seluruh asset → pantau sampai review selesai.

11.3 System

Mengunci asset, memvalidasi, menurunkan hasil terberat, menghitung jadwal berikutnya, menulis log dan notifikasi.

12Flow Diagram

flowchart TD
    A[Monitoring jatuh tempo H-14] --> B[Admin buat PM]
    B --> C{Validasi asset gudang tersedia}
    C -- gagal --> B
    C -- ok --> D[penjadwalan<br/>asset dalam_perbaikan]
    D --> E{Admin}
    E -- batal + alasan --> X[dibatalkan<br/>asset tersedia]
    E -- ubah / ganti PIC --> D
    E -- isi hasil --> G[Checklist hasil seluruh asset]
    D -- PIC isi hasil --> G
    G --> H[menunggu_review]
    H --> I{Hasil terberat}
    I -- 1 sampai 3 --> J[asset tersedia<br/>jadwal PM berikutnya]
    I -- 4 atau 5 --> K[asset rusak di gudang<br/>tindak lanjut PML02/PML04]
    J --> S[selesai]
    K --> S

13Sequence Diagram

sequenceDiagram
    actor Admin
    actor PIC
    participant App as Mobile
    participant API
    participant DB
    Admin->>App: Buat PM
    App->>API: POST pemeliharaan-gudang (1 request, N transaksi)
    API->>DB: Kunci asset, insert N header + N item, asset_trx_log
    API-->>PIC: Notifikasi ditugaskan
    PIC->>API: POST karyawan/pemeliharaan-gudang/{id}/hasil (checklist)
    API->>DB: hasil per item, tgl_mulai, fase menunggu_review
    API-->>Admin: Notifikasi hasil masuk
    Admin->>API: POST pemeliharaan-gudang/{id}/review
    API->>DB: asset tersedia/rusak, jadwal berikutnya, fase selesai
    API-->>PIC: Notifikasi selesai

14Status Transaksi

15State Transition

stateDiagram-v2
    [*] --> penjadwalan: Admin buat
    penjadwalan --> penjadwalan: ubah / ganti PIC
    penjadwalan --> dibatalkan: batal (alasan wajib)
    penjadwalan --> menunggu_review: hasil (tanpa langkah Mulai)
    pelaksanaan --> pelaksanaan: ganti PIC (transaksi lama)
    pelaksanaan --> menunggu_review: hasil (transaksi lama)
    menunggu_review --> selesai: review
    selesai --> [*]
    dibatalkan --> [*]

16Struktur Database

17Relasi Database

erDiagram
    asset_trx_pemeliharaan_gudang ||--o{ asset_trx_pemeliharaan_gudang_item : memiliki
    asset_trx_pemeliharaan_gudang }o--|| asset_pendamping_m : "PIC"
    asset_trx_pemeliharaan_gudang }o--o| asset_vendor_m : "vendor"
    asset_trx_pemeliharaan_gudang_item }o--|| asset_data : "asset"
    asset_data ||--o{ asset_trx_log : "jejak"

18Data Dictionary

18.1 asset_trx_pemeliharaan_gudang

18.2 asset_trx_pemeliharaan_gudang_item

18.3 asset_trx_log (jenis_log = pemeliharaan_gudang)

Ditulis saat PM dibuat (posisi gudang → gudang), saat dibatalkan, dan saat review. kondisi_akhir = rusak untuk hasil 4–5.

19Database Index

20Backend Architecture

21Backend Business Logic

21.1 Buat PM — store

Transaksi DB dengan kunci perusahaan. Input pemeliharaan[] (1–50 elemen, satu elemen per asset). Seluruh elemen divalidasi lebih dulu (asset BR-001/002, jadwal tidak sebelum hari ini, vendor, lokasi, PIC) sebelum ada yang ditulis. Nomor urut header dan item dihitung sekali untuk N transaksi (batas 999 dicek untuk N sekaligus); setiap asset → satu header + satu item, dalam_perbaikan + asset_trx_log. Pesan error bisnis diawali Asset <nama>:. Notifikasi ditugaskan dikirim per transaksi setelah commit.

21.2 Ubah — ubah

Hanya penjadwalan; validasi ulang jadwal dan PIC. Mengembalikan pic_berubah untuk memilih event notifikasi (ditugaskan bila PIC berganti, selain itu diubah).

21.3 Ganti PIC — gantiPic

penjadwalan atau pelaksanaan; PIC baru harus berbeda.

21.4 Batal — batal

Hanya penjadwalan, alasan wajib; asset kembali tersedia; fase dibatalkan.

21.5 Hasil — hasil

Aktor PIC (id_karyawan, harus PIC header dan karyawan aktif) atau admin (user_id). Fase penjadwalan (atau pelaksanaan pada transaksi lama); tgl_mulai/user_mulai diisi otomatis; input harus mencakup semua asset; checklist dinormalisasi per komponen asset; hasil asset = terberat; fase menunggu_review.

21.6 Review — review

Fase menunggu_review; per asset sesuai BR-008/009; fase selesai; mengembalikan daftar ditarik.

21.7 Query baca

getPage (tab jadwal/proses/selesai, paginasi limit+1), getDetail, getMonitoring, countJatuhTempo, getPendingForPic, getPendingForAdmin, countByTabForPic, countPendingForAdmin, hasActivePic.

22Dampak terhadap asset_data

23API Documentation

24Detail Setiap API

API-001 — Monitoring

Daftar asset gudang jatuh tempo (H-14) beserta watchlist dari PM sebelumnya.

API-002 — Opsi

{vendor[], pendamping[] (aktif), asset[] (eligible), hasil[]}.

API-003/011 — Daftar

Query: tab (jadwal|proses|selesai), limit (1–50, default 20), offset. Respons {filters, records[], pagination{limit, offset, next_offset, has_more}}. Record memuat peran (admin/pendamping), jumlah_asset, ringkasan asset, PIC.

API-004 — Buat

Satu request membuat satu transaksi per asset. Body:

{
  "pemeliharaan": [
    {
      "id_asset_data": "AC-1",
      "tgl_jadwal": "2026-10-20",
      "jam_jadwal": "09:00",
      "id_asset_vendor_m": "VND-1",
      "nama_vendor": "",
      "keterangan_vendor": "0812-0000",
      "lokasi_pemeliharaan": "Gudang Utama",
      "id_asset_pendamping_m": "PDM-1",
      "keterangan": "Servis berkala"
    },
    {
      "id_asset_data": "AC-2",
      "tgl_jadwal": "2026-10-22",
      "jam_jadwal": "13:00",
      "id_asset_vendor_m": "",
      "nama_vendor": "Teknisi Lepas",
      "keterangan_vendor": "",
      "lokasi_pemeliharaan": "Gudang Cabang",
      "id_asset_pendamping_m": "PDM-2",
      "keterangan": ""
    }
  ]
}

Aturan: pemeliharaan wajib, 1–50 elemen, id_asset_data harus berbeda antar elemen. Setiap elemen divalidasi dengan aturan form yang sama; nama_vendor wajib bila id_asset_vendor_m kosong. Kunci error validasi berbentuk pemeliharaan.N.field (N = indeks elemen). Pembuatan atomik: bila satu asset gagal (mis. bukan asset gudang tersedia), tidak ada transaksi yang tersimpan dan pesan BUSINESS_RULE_VIOLATION diawali Asset <nama>:. Respons CREATED: {records: [{id, no_trx, fase_pemeliharaan, status_label, tab, id_asset_data}], jumlah}. Payload lama asset_ids tidak lagi diterima.

API-005 — Ubah

Body sama dengan satu elemen pemeliharaan[] pada API-004, tanpa id_asset_data.

API-006 — Ganti PIC

Body {id_asset_pendamping_m}.

API-007 — Batal

Body {alasan_batal} (wajib).

API-008/012 — Hasil

{
  "assets": [
    {
      "id_asset_data": "AC-1",
      "keterangan": "Filter kotor",
      "items": [
        {"id_item": "KMP-1", "hasil": "normal", "keterangan": ""},
        {"id_item": "KMP-2", "hasil": "komponen_rusak_tidak_segera", "keterangan": "Kipas berisik"}
      ]
    }
  ]
}

hasil ∈ lima tingkat. Respons memuat peta hasil per asset.

API-009 — Review

{
  "keterangan_review": "Lanjut pantau kipas",
  "items": [{"id_asset_data": "AC-1", "tgl_rencana_penggantian_komponen": "2026-12-01"}]
}

Respons memuat ditarik[] (id asset hasil 4–5).

API-010/013 — Detail

Berisi header, PIC, vendor, jadwal, hasil/review, assets[] dengan checklist, dan objek aksi per peran (ubah, ganti PIC, batal, hasil, review).

25Mobile Architecture

26Mobile Screen

26.1 Daftar (tab Gudang / Tugas PIC)

HalamanAssetPemeliharaanGudang dan AssetPemeliharaanGudangListView: tab Jadwal/Proses/Selesai, kartu transaksi, paginasi.

26.2 Monitoring dan Buat PM (admin)

HalamanBuatPemeliharaanGudang: daftar asset jatuh tempo, pilih banyak (maksimal 50), lalu Lanjut membuka halaman HalamanFormPemeliharaanGudang (route /asset_admin_form_pemeliharaan_gudang, bukan bottom sheet). Halaman form berisi satu kartu per asset yang bisa dilipat (satu terbuka sekaligus; header: nama, kode, chip Lengkap/Belum lengkap, menu Samakan untuk semua; ringkasan satu baris saat terlipat) dengan field tanggal, jam, vendor terdaftar/manual, kontak vendor, lokasi, PIC, dan catatan. Bar bawah menampilkan progres "N dari M lengkap" dan tombol Buat Pemeliharaan, yang baru mengirim setelah semua kartu lengkap; kartu pertama yang bermasalah terbuka otomatis. Tombol back sistem dan AppBar nonaktif saat submit. Picker vendor dan PIC tetap bottom sheet. Sheet ubah di halaman detail (showAssetPemeliharaanGudangFormSheet) tidak berubah.

26.3 Detail

HalamanDetailAssetPemeliharaanGudang: tahapan, asset beserta checklist, tombol sesuai aksi.

26.4 Master Pendamping

HalamanPendampingAsset (lihat dokumen Master Pendamping & Tugas PIC).

26.5 Entry point

Admin: Pemeliharaan → tab Gudang, kartu "perlu diproses" dan "jatuh tempo" di beranda. PIC: kartu Tugas PIC.

27Mobile → API

28API → Mobile

Respons dipetakan ke AssetPemeliharaanGudangRecord/Page/Options; kegagalan validasi (422) ditampilkan CustomSnackBar tipe warning, kegagalan lain tipe error. Sukses menutup halaman dengan pesan dan memuat ulang daftar/ringkasan.

29Mapping Mobile → API → Database

Setiap field form dikirim per asset sebagai satu elemen pemeliharaan[]; kartu form = satu elemen = satu transaksi.

30Mapping Database → API → Mobile

31Validation

31.1 Mobile

Tanggal, jam, lokasi, vendor (mode terdaftar/manual), dan PIC wajib per asset (kartu yang belum lengkap ditandai dan submit tertahan sampai semua lengkap); maksimal 50 asset dipilih; alasan batal wajib; checklist harus lengkap untuk semua asset.

31.2 Backend

Lihat BR dan §24. Aturan Laravel: pemeliharaan wajib 1–50 elemen dengan id_asset_data distinct, dan aturan berikut berlaku per elemen: tgl_jadwal Y-m-d, jam_jadwal H:i, lokasi_pemeliharaan wajib, id_asset_pendamping_m wajib, hasil dalam lima nilai.

31.3 Database

Enum fase_pemeliharaan, status, status_item_pendamping; FK PIC, vendor, asset; unik (trx, asset).

32Error Handling

33Audit Trail

Kolom user_*/tgl_* per langkah (hasil, review, batal; *_mulai terisi bersama hasil) berisi nik - nama. asset_trx_log mencatat pembuatan, pembatalan, dan review.

34Notification

Notifikasi dikirim setelah transaksi commit; kegagalan kirim hanya dicatat log.

35Security

JWT; admin diperiksa per request; PIC dibatasi ke id_pic_pendamping miliknya; filter id_company di semua query; transaksi + lockForUpdate mencegah balapan; input dinormalisasi dan dipotong sesuai panjang kolom.

36Manual Book User/Admin

A. Admin — Menjadwalkan PM

1. Buka Pemeliharaan → tab Gudang.
2. Pilih satu atau banyak asset jatuh tempo (maksimal 50), ketuk Lanjut.
3. Pada halaman Jadwal per Aset, isi jadwal, vendor, lokasi, PIC, dan catatan untuk tiap asset. Gunakan menu ⋮ → Samakan untuk semua untuk menyalin isian satu asset ke asset lain.
4. Pastikan bar bawah menunjukkan semua asset lengkap, lalu ketuk Buat Pemeliharaan (satu transaksi per asset).

B. Admin — Mengubah / mengganti PIC / membatalkan

Buka detail transaksi penjadwalan; pilih Ubah, Ganti PIC, atau Batalkan (isi alasan).

C. PIC — Menjalankan PM

Buka Tugas PIC → transaksi → isi checklist setiap komponen untuk semua asset → Kirim hasil.

D. Admin — Review

Buka transaksi menunggu_review, periksa hasil, isi catatan dan rencana penggantian (hasil 3), simpan.

37Kondisi Button

Semua dikendalikan objek aksi dari API.

38Testing Scenario

Cakupan otomatis: lihat §1.

39Temuan Ketidaksesuaian

40Edge Case

• PIC dinonaktifkan di master saat transaksi berjalan: transaksi tetap, tetapi hasActivePic mencegah penonaktifan pendamping yang masih bertugas.
• Asset diubah statusnya di luar alur saat pelaksanaan: lockAssets menolak dengan "Status asset sudah berubah…".
• Dua admin membuat PM untuk asset yang sama: yang kedua gagal karena asset sudah dalam_perbaikan.
• Asset tanpa interval: review tidak mengubah jadwal.
• Transaksi lama yang berisi banyak asset tetap berfungsi (hasil dan review diproses untuk semua asset sekaligus); transaksi baru selalu 1 asset.
• Back saat submit ditahan (PopScope). Bila form tetap tertutup setelah pembuatan sukses, halaman pilih ikut tertutup dan daftar dimuat ulang.

41Potential Bug / Technical Risk

RISK-001 — Skema dari SQL manual (TINGGI)

Endpoint gagal bila SQL belum dijalankan; dashboard aman lewat skemaSiap().

RISK-002 — Tidak ada pembatalan setelah hasil dikirim (SEDANG)

PM yang tertahan di menunggu_review mengunci asset.

RISK-003 — Tindak lanjut hasil 4–5 manual (SEDANG)

Lihat INC-01.

RISK-004 — Notifikasi di luar transaksi (RENDAH)

Kegagalan push tidak membatalkan transaksi.

RISK-005 — Kapasitas penomoran (RENDAH)

Maksimum 999 transaksi per bulan per perusahaan.

RISK-006 — Submit ulang setelah request terputus (RENDAH)

Klien memakai timeout 30 detik tanpa sendTimeout. Bila koneksi putus setelah server menyimpan, form aktif lagi; submit ulang kemungkinan besar ditolak karena asset sudah dalam_perbaikan, tetapi belum diuji.

RISK-007 — Notifikasi berurutan untuk banyak transaksi (RENDAH)

Sampai 50 notifikasi dikirim berurutan setelah commit. Kegagalan di tengah dapat menghasilkan respons error padahal transaksi sudah tersimpan. Penguncian lockForUpdate baru diuji pada SQLite, belum pada MySQL.

42Dependency

43Source Code Reference

44Developer Notes

• Pola konsisten dengan PML02/PML03: header fase_*, lockHeader/lockAssets, updateHeader, headerResult.
• Admin dan PIC memakai model yang sama; perbedaan hanya parameter $idPic dan lockForActor.
• Daftar memakai paginasi limit + 1 untuk has_more.
• Jangan mengubah urutan nilai enum jenis_log tanpa menyesuaikan SQL berikutnya (PML02/03/04 menulis ulang daftar penuh).

45End-to-End Traceability

45.4 Walkthrough Lengkap dengan Contoh Data

Bagian ini mengikuti satu permintaan pemeliharaan gudang yang membuat dua transaksi: satu diisi hasilnya dan direview, satu dibatalkan. 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 (AssetPemeliharaanGudang_m, AssetAdminPemeliharaanGudang_c, AssetKaryawanPemeliharaanGudang_c, AssetNotification).

Skenario: Dua asset gudang jatuh tempo PM: AC Portable dan Mesin Fotokopi. Admin membuat PM untuk keduanya dalam satu request (satu transaksi per asset, masing-masing dengan jadwal, vendor, lokasi, dan PIC sendiri). Jadwal mesin fotokopi diubah. PIC AC mengisi checklist hasil dan admin mereview. PM mesin fotokopi dibatalkan.

Data awal

Company CMP001. PM dibuat 22 Oktober 2026, periode ID 202610. Belum ada transaksi PM gudang, log, atau notifikasi pada periode ini.

asset_data (semua pemegang_asset = gudang, status_asset = tersedia, flag_pemeliharaan = 1, kondisi_awal = normal)

asset_pendamping_m (PIC aktif, flag_aktif = 1)

Vendor: asset_vendor_m CMP001VND001 = PT Servis Dingin. Admin: KRY0099 (ADM-001, Siti Admin) dan KRY0100 (ADM-002, Rudi Admin).

Penomoran: header dan item id_company + YYYYMM + 3 digit, no_trx = PML01-3-YYYYMMNNN (-3- = gudang); log dan notifikasi 5 digit. Satu transaksi = satu asset; N asset memakai N nomor header dan N nomor item.

Langkah 0 — Admin membuka monitoring dan memuat opsi

Mobile: Pemeliharaan (admin) → tab Gudang → Jatuh Tempo Pemeliharaan → AssetPemeliharaanGudangApi.getMonitoring() dan getOptions() (admin: true).

Dikirim

GET /asset/pemeliharaan-gudang/monitoring
GET /asset/pemeliharaan-gudang/options
Authorization: Bearer <access_token_admin>

Diproses API: getMonitoring mengembalikan asset tersedia di gudang dengan flag_pemeliharaan = 1 dan jadwal_pemeliharaan ≤ hari ini + 14, urut jadwal terdekat, beserta watchlist dari PM sebelumnya. getAdminOptions memuat vendor[], pendamping[] (hanya yang aktif), asset[] (eligible), dan hasil[].

Database: hanya SELECT. Karena asset yang sudah dipilih akan menjadi dalam_perbaikan, ia otomatis hilang dari monitoring dan opsi.

Langkah 1 — Admin membuat PM untuk dua asset

Mobile: admin memilih AC dan mesin fotokopi, lalu untuk setiap asset mengisi jadwal, vendor, lokasi, PIC, dan keterangan → Simpan → AssetPemeliharaanGudangApi.store.

Dikirim

POST /asset/pemeliharaan-gudang

{
  "pemeliharaan": [
    { "id_asset_data": "CMP00120260100040", "tgl_jadwal": "2026-10-24", "jam_jadwal": "09:00",
      "id_asset_vendor_m": "CMP001VND001", "nama_vendor": "", "keterangan_vendor": "0812-0000-0000",
      "lokasi_pemeliharaan": "Gudang Utama", "id_asset_pendamping_m": "CMP001202601001",
      "keterangan": "Servis berkala" },
    { "id_asset_data": "CMP00120260100041", "tgl_jadwal": "2026-10-26", "jam_jadwal": "13:00",
      "id_asset_vendor_m": "", "nama_vendor": "Teknisi Lepas", "keterangan_vendor": "",
      "lokasi_pemeliharaan": "Gudang Cabang", "id_asset_pendamping_m": "CMP001202601002", "keterangan": "" }
  ]
}

Diproses API (AssetAdminPemeliharaanGudang_c::storePemeliharaanGudang → AssetPemeliharaanGudang_m::store, satu DB::transaction untuk semua elemen) 1. Validasi: pemeliharaan wajib, 1–50 elemen; id_asset_data unik antar elemen; nama_vendor wajib bila id_asset_vendor_m kosong. Kunci error berbentuk pemeliharaan.N.field. 2. lockCompany; cek admin. Asset dikunci FOR UPDATE (urut id_asset_data). 3. Seluruh elemen divalidasi lebih dulu sebelum ada yang ditulis: asset dipegang gudang dan tersedia ("Hanya asset tersedia di gudang yang dapat dipelihara."), flag_pemeliharaan = 1, tidak ada di onboarding aktif, jadwal valid dan tidak sebelum hari ini, vendor, lokasi wajib, dan PIC harus ada di pendamping aktif ("PIC Pendamping wajib dipilih dari daftar pendamping aktif."). Pesan error diawali Asset <nama>:. 4. Nomor urut header dan item dihitung sekali untuk N transaksi (batas 999 dicek untuk N sekaligus): header …001 dan …002. 5. Per asset: INSERT header (fase_pemeliharaan = penjadwalan, status = proses, snapshot PIC, vendor, jadwal), INSERT item (hasil NULL), UPDATE asset_data → dalam_perbaikan, INSERT asset_trx_log (gudang → gudang). 6. Setelah commit: notifikasi pemeliharaan_gudang.ditugaskan per transaksi ke PIC masing-masing. Bila satu asset gagal, tidak ada transaksi yang tersimpan.

Hasil database

asset_trx_pemeliharaan_gudang (2 baris)

asset_trx_pemeliharaan_gudang_item

asset_data: A40 dan A41 status_asset tersedia → dalam_perbaikan, pemegang_asset tetap gudang, user_update = ADM-001 - Siti Admin.

asset_trx_log (2 baris, jenis_log = pemeliharaan_gudang)

notif_data (2 baris, masing-masing ke PIC transaksinya)

Diterima mobile (HTTP 201)

{ "code": "CREATED", "message": "…",
  "data": { "records": [
      { "id": "CMP001202610001", "no_trx": "PML01-3-202610001", "fase_pemeliharaan": "penjadwalan",
        "status_label": "Penjadwalan", "tab": "jadwal", "id_asset_data": "CMP00120260100040" },
      { "id": "CMP001202610002", "no_trx": "PML01-3-202610002", "fase_pemeliharaan": "penjadwalan",
        "status_label": "Penjadwalan", "tab": "jadwal", "id_asset_data": "CMP00120260100041" } ],
    "jumlah": 2 } }

Langkah 2 — Admin mengubah jadwal transaksi kedua

Mobile: detail transaksi kedua (aksi.ubah = true) → Ubah → AssetPemeliharaanGudangApi.ubah.

Dikirim

PUT /asset/pemeliharaan-gudang/CMP001202610002

{ "tgl_jadwal": "2026-10-27", "jam_jadwal": "10:00", "id_asset_vendor_m": "", "nama_vendor": "Teknisi Lepas",
  "keterangan_vendor": "", "lokasi_pemeliharaan": "Gudang Cabang", "id_asset_pendamping_m": "CMP001202601002",
  "keterangan": "Jadwal digeser" }

Body sama dengan satu elemen pemeliharaan[], tanpa id_asset_data.

Diproses API (ubah): hanya fase penjadwalan; jadwal, vendor, lokasi, dan PIC divalidasi ulang. Respons menandai apakah PIC berganti (pic_berubah): bila berganti, event pemeliharaan_gudang.ditugaskan; selain itu pemeliharaan_gudang.diubah.

Hasil database

Admin juga bisa Ganti PIC (API-006, POST …/{id}/pic dengan {id_asset_pendamping_m}) selama penjadwalan atau pelaksanaan; PIC baru harus berbeda dari PIC saat ini.

Langkah 3 — PIC mengisi checklist hasil transaksi pertama

Mobile: menu Tugas PIC → detail transaksi AC (peran = pendamping) → checklist tiap komponen (lima tingkat) → AssetPemeliharaanGudangApi.hasil (admin: false). Tidak ada langkah "Mulai PM": hasil dapat dikirim langsung dari penjadwalan.

Dikirim

POST /asset/karyawan/pemeliharaan-gudang/CMP001202610001/hasil

{
  "assets": [ {
    "id_asset_data": "CMP00120260100040",
    "keterangan": "Filter kotor",
    "items": [
      { "id_item": "CMP001ITEM0501", "hasil": "normal", "keterangan": "" },
      { "id_item": "CMP001ITEM0502", "hasil": "komponen_rusak_tidak_segera", "keterangan": "Filter kotor dan sobek" }
    ] } ]
}

Diproses API (AssetKaryawanPemeliharaanGudang_c → hasil) 1. lockForActor: aktor PIC lewat id_karyawan; header harus milik PIC itu (id_pic_pendamping = KRY0020) dan karyawan aktif. Admin dapat mengisi lewat API-008. 2. Fase harus penjadwalan (atau pelaksanaan pada transaksi lama) ("Pemeliharaan sudah tidak berada pada tahap pelaksanaan."). 3. lockAssets: seluruh asset transaksi harus masih di gudang dan dalam_perbaikan ("Status asset sudah berubah atau tidak lagi berada di gudang."). 4. Seluruh asset transaksi wajib ada pada assets[] ("Seluruh asset wajib diperiksa."). 5. normalizeHasilChecklist: semua komponen wajib dinilai, hasil salah satu dari lima tingkat, selain normal wajib keterangan. 6. Hasil asset = komponen terberat (komponen_rusak_tidak_segera). 7. UPDATE item (status_item_pendamping, checklist_hasil, keterangan_konfirmasi); UPDATE header: fase_pemeliharaan = menunggu_review, tgl_mulai dan user_mulai diisi otomatis bila kosong, tgl_hasil, user_hasil. 8. Notifikasi pemeliharaan_gudang.hasil ke admin.

Hasil database

Diterima mobile (HTTP 200): header fase_pemeliharaan = menunggu_review, status_label = "Menunggu Review", tab = "proses", dan peta hasil: {"CMP00120260100040": "komponen_rusak_tidak_segera"}.

Langkah 4 — Admin mereview transaksi pertama

Mobile: detail admin (aksi.review = true) → Review, mengisi catatan dan tanggal rencana penggantian komponen → AssetPemeliharaanGudangApi.review.

Dikirim

POST /asset/pemeliharaan-gudang/CMP001202610001/review

{ "keterangan_review": "Lanjut pantau filter",
  "items": [ { "id_asset_data": "CMP00120260100040", "tgl_rencana_penggantian_komponen": "2026-12-01" } ] }

Diproses API (review) 1. Fase harus menunggu_review ("Hasil pemeliharaan belum dikirim."). Asset pada items[] harus termasuk transaksi ini. 2. Hasil asset ini bukan 4–5, sehingga jadwalBerikutnya: hasil 3 (komponen_rusak_tidak_segera) wajib tanggal rencana penggantian komponen; bila interval_pemeliharaan > 0, jadwal berikutnya = tanggal review + interval bulan (tanpa overflow akhir bulan). 3. UPDATE asset_data → tersedia (kembali bisa dipakai modul lain) dan INSERT asset_trx_log (gudang → gudang). 4. UPDATE header → selesai: status = selesai, tgl_review, user_review, keterangan_review. 5. Notifikasi pemeliharaan_gudang.selesai ke PIC. Respons memuat ditarik[] (kosong di sini).

Hasil database

asset_trx_log (1 baris baru): CMP00120261000003, A40, pemeliharaan_gudang, id_transaksi CMP001202610001, kondisi normal → normal, posisi gudang → gudang, user_input = ADM-001 - Siti Admin.

Diterima mobile (HTTP 200): fase_pemeliharaan = selesai, status_label = "Selesai", tab = "selesai", ditarik = [].

Langkah 5 — Admin membatalkan transaksi kedua

Mobile: detail transaksi kedua → Batalkan dengan alasan → AssetPemeliharaanGudangApi.batal.

Dikirim

POST /asset/pemeliharaan-gudang/CMP001202610002/batal

{ "alasan_batal": "Vendor berhalangan" }

Diproses API (batal): hanya fase penjadwalan ("Hanya pemeliharaan yang belum dimulai yang dapat dibatalkan."); alasan wajib ("Alasan pembatalan wajib diisi."). Asset dikunci dan dikembalikan tersedia, INSERT asset_trx_log, header dibatalkan. Notifikasi pemeliharaan_gudang.dibatalkan ke PIC.

Hasil database

Diterima mobile (HTTP 200): fase_pemeliharaan = dibatalkan, status_label = "Dibatalkan", tab = "selesai".

Kondisi akhir data

asset_trx_pemeliharaan_gudang

asset_data: A40 → tersedia, jadwal_pemeliharaan = 2027-01-24; A41 → tersedia, jadwal tetap 2026-11-02. asset_trx_log: 4 baris. notif_data: 7 baris.

Variasi

Hasil 4–5 (asset ditarik). Pada review, asset dengan hasil komponen_rusak_perlu_segera atau tidak_dapat_diperbaiki: status_asset = rusak, kondisi_awal = rusak, ket_rusak (temuan + catatan review, maks 255), status_rusak = "sudah tidak bisa di gunakan"; INSERT asset_trx_log dengan kondisi_akhir = rusak; item nama_tabel_tindak_lanjut = asset_trx_perbaikan (hasil 4) atau asset_trx_disposal (hasil 5); id asset masuk ditarik[]. Transaksi Perbaikan atau Disposal tidak dibuat otomatis. Pada gudang, pemegang_asset memang sudah gudang.

Hasil 1–2. Hasil normal atau perlu_tindak_lanjut: tanpa tanggal rencana penggantian; jadwal PM berikutnya tetap dihitung bila interval > 0. Interval 0 tidak mengubah jadwal_pemeliharaan.

Admin mengisi hasil sebagai cadangan. POST /asset/pemeliharaan-gudang/{id}/hasil (API-008) dengan body sama; aktor admin (user_id), tanpa pemeriksaan kepemilikan PIC.

Request pembuatan gagal sebagian. Bila salah satu asset tidak lolos validasi (mis. sudah dalam_perbaikan), seluruh request ditolak, tidak ada transaksi atau perubahan asset yang tersimpan, dan pesan berbentuk Asset <nama>: <alasan>.

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_pemeliharaan_gudang, …_item. Perubahan: asset_pendamping_m (+flag_aktif, audit update, unik per karyawan), asset_trx_log.jenis_log (+pemeliharaan_gudang). asset_data tidak diubah strukturnya.

47Checklist Implementasi

Database

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

Backend

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

Mobile

• Daftar, buat, detail, form
• Teks id/en
• Test otomatis

Documentation

• Dokumen ini

48Changelog