Pemeliharaan Terjadwal Asset Karyawan

01Informasi Dokumen

03Quick Overview

Admin: Jatuh Tempo Pemeliharaan → pilih asset → Usulkan Jadwal               konfirmasi_jadwal
Karyawan: Setujui Jadwal  ⇄  Usulkan Jadwal Lain (admin usulkan ulang, berulang)
                                                                         penjadwalan
Admin: Atur Pelaksanaan (mekanisme, vendor, lokasi)
   ├─ Hadir Langsung + PIC Pendamping ─────────────────────────────────── pelaksanaan
   └─ Diserahkan + jadwal pengambilan ────────────────────────────────── menunggu_pengambilan
        Admin: Checklist Pengambilan → Karyawan: Serahkan Aset (asset dalam_perbaikan) ── pelaksanaan
Checklist Hasil PM (5 tingkat per item)
   ├─ Hadir Langsung: diisi PIC Pendamping (akun karyawan)
   └─ Diserahkan: diisi Admin berdasarkan laporan vendor ─────────────── menunggu_review
Admin: Review & Tindak Lanjut
   ├─ Hasil 1–3: jadwal PM berikutnya = hari review + interval
   │     ├─ Hadir Langsung ─────────────────────────────────────────────── selesai
   │     └─ Diserahkan + jadwal pengembalian ──────────────────────────── menunggu_pengembalian
   │           Karyawan: Checklist Pengembalian → Terima Aset (asset terpakai) ── selesai
   └─ Hasil 4–5: asset ditarik → rusak @gudang (+ unit pengganti opsional) ── selesai

04Ringkasan Fitur

Pemeliharaan Terjadwal memastikan asset yang dipegang karyawan (misalnya laptop, kendaraan dinas) diservis berkala sesuai interval. Asset yang ikut PM adalah asset dengan Perlu Pemeliharaan Terjadwal = Ya (flag_pemeliharaan = 1), berstatus terpakai, dan dipegang karyawan aktif.

Admin memulai PM dari daftar Jatuh Tempo Pemeliharaan (asset yang jadwalnya ≤ 14 hari lagi atau sudah lewat) dan mengusulkan jadwal. Karyawan menyetujui atau mengusulkan jadwal lain; negosiasi berulang sampai disepakati. Admin lalu memilih mekanisme:

• Karyawan Hadir Langsung — karyawan membawa asset ke vendor atau vendor datang. Asset tidak berpindah tangan dan tetap terpakai. Seorang PIC Pendamping (boleh karyawan pemegang sendiri) mendampingi teknisi dan mengisi checklist hasil dari akunnya.
• Diserahkan ke Admin/HR — admin mengambil asset (checklist pengambilan), karyawan mengonfirmasi penyerahan, asset menjadi dalam_perbaikan (DALAM SERVICE). Admin mengisi hasil berdasarkan laporan vendor lalu mengembalikan asset.

Checklist hasil PM dinilai per item asset (unit utama & kelengkapan) dengan lima tingkat. Hasil akhir mengikuti item terberat dan menentukan tindak lanjut: jadwal PM berikutnya otomatis (hasil 1–3, dengan catatan watchlist untuk hasil 2–3) atau penarikan asset ke gudang berstatus rusak untuk diteruskan ke Perbaikan (PML02) / Disposal (PML04), opsional dengan unit pengganti.

05Tujuan Fitur

5.1 Tujuan Bisnis (diturunkan dari dokumen bisnis & kode)

• Asset karyawan dipelihara tepat waktu sesuai interval.
• Jadwal disepakati bersama karyawan agar operasional tidak terganggu.
• Hasil pemeriksaan per komponen terdokumentasi, termasuk siapa yang mengisi.
• Temuan ringan dipantau (watchlist) dan diingatkan pada PM berikutnya.
• Asset yang tidak layak segera ditarik, dengan opsi unit pengganti.

5.2 Tujuan Sistem

• Menampilkan asset jatuh tempo yang belum punya PM aktif.
• Menyimpan riwayat negosiasi jadwal (usulan admin, usulan karyawan, konfirmasi).
• Mengunci asset dari Upgrade, Kerusakan, Retur, dan Offboarding selama PM aktif.
• Memperbarui asset_data (status, pemegang, jadwal_pemeliharaan) dan mencatat asset_trx_log.

06Aktor

07Hak Akses

08Terminologi

09Business Rules

BR-001 — Asset yang boleh dipelihara

asset_data dipegang karyawan (pemegang_asset = karyawan), status_asset = terpakai, flag_pemeliharaan = '1', dan pemegang adalah karyawan aktif → "Asset tidak ditemukan atau tidak dipegang karyawan." / "Hanya asset berstatus terpakai yang dapat dipelihara." / "Asset tidak memiliki jadwal pemeliharaan aktif." / "Karyawan pemegang asset tidak ditemukan atau tidak aktif."

BR-002 — Satu PM aktif per asset, tidak bentrok flow lain

Dicek saat membuat PM: pemeliharaan aktif (fase ≠ selesai), upgrade aktif, laporan kerusakan aktif, retur aktif, offboarding aktif → "Asset sedang diproses pada pemeliharaan lain." / "…pada upgrade." / "…pada laporan kerusakan." / "…pada retur." / "…pada offboarding."

BR-003 — PM aktif mengunci asset di modul lain

hasActivePemeliharaanAsset dipanggil oleh Upgrade & Kerusakan ("Asset sedang diproses pada pemeliharaan."), Retur & Offboarding ("Satu atau beberapa asset sedang diproses pada pemeliharaan."). Asset juga hilang dari daftar jatuh tempo selama PM aktif.

BR-004 — Negosiasi jadwal (Fase 2B)

• Admin membuat PM dengan usulan jadwal (tanggal ≥ hari ini). Usulan admin berikutnya boleh diberikan kapan saja selama fase konfirmasi_jadwal.
• Karyawan hanya bisa menjawab bila baris jadwal PM terakhir adalah usulan admin (menunggu) → "Tidak ada usulan jadwal yang perlu dikonfirmasi."
• Setujui: jadwal usulan disalin ke tgl_pemeliharaan/jam_pemeliharaan, fase → penjadwalan.
• Usulkan jadwal lain: tanggal, jam, dan alasan wajib → "Alasan usulan jadwal alternatif wajib diisi."; fase tetap, admin wajib mengusulkan ulang.

BR-005 — Atur pelaksanaan (Fase 2B.4 + 3)

Hanya fase penjadwalan → "Jadwal pemeliharaan belum disepakati karyawan." Asset harus masih terpakai di karyawan. - Vendor: id_asset_vendor_m dari master atau nama_vendor teks → "Vendor tidak ditemukan." / "Vendor / teknisi wajib diisi." - Lokasi wajib → "Lokasi pemeliharaan wajib diisi." - Hadir langsung: PIC Pendamping ditentukan otomatis = pemegang asset (harus karyawan aktif, "Karyawan pemegang aset tidak aktif."); id_pic_pendamping pada request diabaikan; fase → pelaksanaan; pendamping dicatat ke asset_pendamping_m bila belum ada. - Diserahkan: jadwal pengambilan wajib; fase → menunggu_pengambilan.

BR-006 — Pengambilan (mekanisme diserahkan, Fase 2C)

Admin mengisi checklist kondisi seluruh item asset (normal/rusak, rusak wajib keterangan) → "Checklist pengambilan tidak dapat diisi saat ini." / "Seluruh item aset wajib dicek." Karyawan baru bisa Serahkan Aset setelah checklist ada → "Aset belum siap diserahkan untuk pemeliharaan." Penyerahan: status_asset = dalam_perbaikan (pemegang tetap karyawan), log karyawan → gudang, fase → pelaksanaan.

BR-007 — Checklist hasil PM (Fase 4)

Hanya fase pelaksanaan → "Pemeliharaan belum berada pada tahap pelaksanaan." - Pengisi: PIC Pendamping lewat endpoint karyawan (hanya mekanisme hadir langsung dan id_pic_pendamping = dirinya) → "Hanya PIC Pendamping yang dapat mengisi hasil pemeliharaan."; atau admin (semua mekanisme). - Semua item asset wajib dinilai → "Seluruh item aset wajib diperiksa."; hasil harus salah satu dari 5 → "Hasil pemeriksaan item tidak valid."; selain normal wajib keterangan → "Keterangan temuan wajib diisi untuk hasil selain normal." - Hasil akhir = item terberat → status_item_pendamping. Fase → menunggu_review, tgl_hasil/user_hasil diisi.

BR-008 — Review hasil 1–3 (asset tetap dipakai)

• Jadwal PM berikutnya = tanggal review + interval_pemeliharaan bulan (tanpa overflow akhir bulan) → asset_data.jadwal_pemeliharaan dan item.tgl_pemeliharaan_selanjutnya. Interval 0 → tidak dijadwalkan ulang.
• Hasil 3 wajib tanggal rencana penggantian komponen → "Tanggal rencana penggantian komponen wajib diisi."
• Hadir langsung → selesai. Diserahkan → jadwal pengembalian wajib, fase menunggu_pengembalian.

BR-009 — Review hasil 4–5 (asset ditarik)

Asset → status_asset = rusak, kondisi_awal = rusak, ket_rusak = keterangan hasil + review, status_rusak = "sudah tidak bisa di gunakan", pemegang_asset = gudang. Log dengan kondisi_akhir = rusak. nama_tabel_tindak_lanjut = asset_trx_perbaikan (hasil 4) atau asset_trx_disposal (hasil 5); ⚠️ transaksi PML02/PML04 belum dibuat (INC-05). Fase → selesai.

BR-010 — Unit pengganti (hasil 4–5, opsional)

Bila admin memilih unit pengganti, sistem membuat Penambahan asset (KRY-03-1) untuk karyawan yang sama (urgensi = mendesak, jadwal serah terima dari admin) di dalam transaksi review. flag_unit_pengganti = 1, id_trx_request_pengganti diisi, notifikasi penambahan.dikirim dikirim. Aturan Penambahan berlaku (asset harus tersedia @gudang).

BR-011 — Pengembalian (mekanisme diserahkan, Fase 5)

Hanya fase menunggu_pengembalian → "Aset belum dijadwalkan untuk dikembalikan." Karyawan mengisi checklist kondisi seluruh item; asset → terpakai, log gudang → karyawan, fase selesai.

BR-012 — Ubah jadwal

Admin: fase konfirmasi_jadwal → usulan PM baru; menunggu_pengambilan → jadwal pengambilan; menunggu_pengembalian → jadwal pengembalian. Fase lain → "Jadwal tidak dapat diubah pada tahap ini." Tanggal tidak boleh sebelum tanggal transaksi dibuat.

BR-013 — Penomoran

Header/item/jadwal id_company + YYYYMM + 3 digit; no_trx = PML01-2-YYYYMMNNN; asset_pendamping_m 3 digit; log 5 digit.

BR-014 — Skema harus sudah diterapkan

Dashboard dan pengecekan lintas modul memanggil skemaSiap() (kolom fase_pemeliharaan ada). Sebelum SQL diterapkan, bagian PML01 di dashboard kosong dan modul lain tidak terblokir; endpoint PML01 sendiri akan gagal (RISK-001).

10Business Flow

1. Admin: Asset Karyawan → Pemeliharaan → ikon Jatuh Tempo (atau kartu "Pemeliharaan Jatuh Tempo")
   → pilih asset → Jadwalkan PM → tanggal, jam, catatan                 [Konfirmasi Jadwal · notif karyawan]
2. Karyawan: banner "Konfirmasi Jadwal PM" → Detail
   → Setujui Jadwal                                                      [Penjadwalan · notif admin]
     atau Usulkan Jadwal Lain (tanggal, jam, alasan)                     [notif admin → admin usulkan ulang]
3. Admin: Detail → Atur Pelaksanaan → mekanisme, vendor, keterangan vendor, lokasi
   a. Hadir Langsung + PIC Pendamping                                    [Pelaksanaan PM · notif karyawan & pendamping]
   b. Diserahkan + Jadwal Pengambilan                                    [Menunggu Pengambilan · notif karyawan]
      → Admin: Simpan Checklist (pengambilan)                            [notif karyawan]
      → Karyawan: Serahkan Aset                                          [Pelaksanaan PM · asset dalam_perbaikan · notif admin]
4. Checklist Hasil PM → Kirim Hasil
   a. Hadir Langsung: PIC Pendamping (banner "Isi Hasil PM")
   b. Diserahkan: Admin                                                  [Menunggu Review · notif admin]
5. Admin: Review & Tindak Lanjut → Simpan Review
   - Hasil 1–3 hadir langsung                                            [Selesai · notif karyawan]
   - Hasil 1–3 diserahkan + Jadwal Pengembalian                          [Menunggu Pengembalian · notif karyawan]
       → Karyawan: Checklist Pengembalian → Terima Aset                  [Selesai · notif admin]
   - Hasil 4–5 (+ unit pengganti & jadwal pengiriman)                    [Selesai · asset ditarik · notif karyawan]

11Flow Berdasarkan Role

11.1 Karyawan pemegang

1. Asset Saya → menu Pemeliharaan → Pemeliharaan Terjadwal (tab Jadwal / Proses / Selesai).
2. Banner Asset Saya: Konfirmasi Jadwal PM, Serahkan Aset untuk PM, Terima Aset Hasil PM.
3. Detail → Setujui Jadwal / Usulkan Jadwal Lain, Serahkan Aset, Terima Aset.

11.2 PIC Pendamping

1. Banner Isi Hasil PM ("Anda PIC Pendamping pemeliharaan {asset}. Isi checklist hasil.") atau daftar Pemeliharaan (kartu bertanda "Anda PIC Pendamping").
2. Detail → pilih hasil setiap item + keterangan temuan → Kirim Hasil.

11.3 Admin Asset

1. Asset Karyawan → aksi Pemeliharaan, kartu Pemeliharaan Perlu Diproses, atau kartu Pemeliharaan Jatuh Tempo.
2. Daftar → ikon Jatuh Tempo → Jadwalkan PM.
3. Detail → Usulkan Jadwal, Atur Pelaksanaan, Ubah Jadwal, Simpan Checklist, Kirim Hasil, Simpan Review.

11.4 System

Hitung jatuh tempo & watchlist, validasi, hasil terberat, jadwal berikutnya, update asset & log, buat Penambahan unit pengganti, notifikasi.

12Flow Diagram

flowchart TD
    A[Admin: pilih asset jatuh tempo + usulkan jadwal] --> B[Konfirmasi Jadwal]
    B --> C{Karyawan}
    C -->|Usulkan jadwal lain| D[Admin usulkan ulang]
    D --> B
    C -->|Setujui| E[Penjadwalan]
    E --> F{Admin: mekanisme}
    F -->|Hadir langsung + PIC Pendamping| G[Pelaksanaan PM]
    F -->|Diserahkan + jadwal pengambilan| H[Menunggu Pengambilan]
    H --> I[Admin: checklist pengambilan]
    I --> J[Karyawan: Serahkan Aset, asset dalam_perbaikan]
    J --> G
    G --> K[Checklist hasil 5 tingkat: PIC Pendamping atau Admin]
    K --> L{Admin: review hasil akhir}
    L -->|Hasil 1-3| M[Jadwal PM berikutnya dihitung]
    M --> N{Mekanisme}
    N -->|Hadir langsung| Z[Selesai]
    N -->|Diserahkan| O[Menunggu Pengembalian]
    O --> P[Karyawan: checklist + Terima Aset, asset terpakai]
    P --> Z
    L -->|Hasil 4-5| Q[Asset ditarik: rusak di gudang]
    Q --> R{Unit pengganti?}
    R -->|Ya| S[Buat Penambahan asset untuk karyawan]
    R -->|Tidak| Z
    S --> Z

13Sequence Diagram

sequenceDiagram
    actor A as Admin
    actor K as Karyawan
    actor P as PIC Pendamping
    participant M as Mobile
    participant CA as AssetAdminPemeliharaan_c
    participant CK as AssetKaryawanPemeliharaan_c
    participant PM as AssetPemeliharaanKaryawan_m
    participant DB
    participant N as AssetNotification

    A->>M: Jadwalkan PM (asset jatuh tempo)
    M->>CA: POST /asset/pemeliharaan-karyawan
    CA->>PM: store()
    PM->>DB: cek asset, flag, karyawan aktif, flow lain
    PM->>DB: INSERT header + item + jadwal (menunggu)
    CA->>N: pemeliharaan.usulan_jadwal (karyawan)
    K->>M: Setujui Jadwal
    M->>CK: POST /asset/karyawan/pemeliharaan/{id}/jadwal
    CK->>PM: konfirmasiJadwal()
    PM->>DB: INSERT jadwal konfirmasi, header penjadwalan
    CK->>N: pemeliharaan.jadwal_disetujui (admin)
    A->>M: Atur Pelaksanaan (hadir langsung)
    M->>CA: POST /asset/pemeliharaan-karyawan/{id}/pelaksanaan
    CA->>PM: aturPelaksanaan()
    PM->>DB: vendor, lokasi, pendamping, header pelaksanaan
    CA->>N: pemeliharaan.pendamping + pemeliharaan.dijadwalkan
    P->>M: Checklist hasil, Kirim Hasil
    M->>CK: POST /asset/karyawan/pemeliharaan/{id}/hasil
    CK->>PM: hasil()
    PM->>DB: item checklist_hasil + hasil terberat, header menunggu_review
    CK->>N: pemeliharaan.hasil (admin)
    A->>M: Simpan Review
    M->>CA: POST /asset/pemeliharaan-karyawan/{id}/review
    CA->>PM: review()
    PM->>DB: jadwal_pemeliharaan berikutnya atau asset ditarik + asset_trx_log
    PM->>DB: header selesai (atau menunggu_pengembalian)
    CA->>N: pemeliharaan.selesai / pengembalian / ditarik (karyawan)

14Status Transaksi

Kolom utama fase_pemeliharaan (enum). Kolom status (proses/selesai) mengikuti: selesai hanya saat fase selesai.

Hasil PM (status_item_pendamping, NULL sebelum diisi): normal, perlu_tindak_lanjut, komponen_rusak_tidak_segera, komponen_rusak_perlu_segera, tidak_dapat_diperbaiki.

15State Transition

stateDiagram-v2
    [*] --> konfirmasi_jadwal: Admin usulkan jadwal
    konfirmasi_jadwal --> konfirmasi_jadwal: Karyawan usulkan lain / Admin usulkan ulang
    konfirmasi_jadwal --> penjadwalan: Karyawan setujui
    penjadwalan --> pelaksanaan: Atur pelaksanaan (hadir langsung)
    penjadwalan --> menunggu_pengambilan: Atur pelaksanaan (diserahkan)
    menunggu_pengambilan --> pelaksanaan: Checklist admin + Karyawan serahkan
    pelaksanaan --> menunggu_review: Kirim hasil
    menunggu_review --> selesai: Review (hadir, hasil 1-3) / hasil 4-5
    menunggu_review --> menunggu_pengembalian: Review (diserahkan, hasil 1-3)
    menunggu_pengembalian --> selesai: Karyawan terima
    selesai --> [*]

16Struktur Database

17Relasi Database

erDiagram
    asset_trx_pemeliharaan_karyawan ||--|{ asset_trx_pemeliharaan_karyawan_item : "id_asset_trx_pemeliharaan_karyawan"
    asset_trx_pemeliharaan_karyawan ||--o{ asset_trx_pemeliharaan_karyawan_jadwal : "id_asset_trx_pemeliharaan_karyawan"
    asset_trx_pemeliharaan_karyawan }o--o| asset_vendor_m : "id_asset_vendor_m"
    asset_trx_pemeliharaan_karyawan }o--o| asset_pendamping_m : "id_asset_pendamping_m"
    asset_trx_pemeliharaan_karyawan_item }o--|| asset_data : "id_asset_data"
    asset_data ||--o{ asset_trx_log : "id_asset_data"

Relasi logis (tanpa FK): id_karyawan / id_pic_pendamping → data_karyawan; id_trx_request_pengganti → asset_trx_request_karyawan; id_trx_tindak_lanjut + nama_tabel_tindak_lanjut → PML02/PML04 (⚠️ belum terisi).

18Data Dictionary

18.1 asset_trx_pemeliharaan_karyawan

Format JSON checklist_pengambilan / checklist_pengembalian: [{id_item, nama_item, jenis, kondisi: normal|rusak, ket_rusak}].

18.2 asset_trx_pemeliharaan_karyawan_item

18.3 asset_trx_pemeliharaan_karyawan_jadwal

18.4 asset_trx_log (jenis_log = pemeliharaan_karyawan)

Dicatat saat serahkan (karyawan → gudang), terima (gudang → karyawan), dan asset ditarik (hasil 4/5, kondisi_akhir = rusak). id_pemegang/nama_pemegang diisi hanya bila posisi akhir karyawan.

19Database Index

⚠️ Pencarian karyawan sebagai pendamping (id_pic_pendamping) tidak punya index khusus.

20Backend Architecture

routes/modules/asset/RouteAsset.php
   ↓
AssetAdminPemeliharaan_c (10 endpoint)        AssetKaryawanPemeliharaan_c (6 endpoint, pemegang & pendamping)
   ↓  mutateAssetTrx / mutateTrxSaya → AssetNotification::send
AssetPemeliharaanKaryawan_m extends Asset_m
   ↓   ↔ AssetUpgradeKaryawan_m / AssetRusakKaryawan_m / AssetReturKaryawan_m / AssetOffboardingKaryawan_m (cek flow lain)
   ↓   → AssetRequestKaryawan_m::store (unit pengganti)
DB (header, item, jadwal, asset_pendamping_m, asset_data, asset_trx_log)

21Backend Business Logic

21.1 Buat PM — store

Lock company → admin → jadwal valid (≥ hari ini) → asset dipegang karyawan (FOR UPDATE), terpakai, flag_pemeliharaan = 1 → assetBlockMessage → karyawan aktif + cabang/departemen → ID + PML01-2-… → INSERT header (konfirmasi_jadwal, hadir_langsung) → INSERT item (hasil NULL) → INSERT jadwal (pemeliharaan, menunggu, admin).

21.2 Usul/ubah jadwal — updateJadwal

Fase menentukan jenis jadwal (§BR-012); insert baris jadwal (menunggu untuk PM, konfirmasi untuk pengambilan/pengembalian) dan perbarui kolom tanggal header untuk pengambilan/pengembalian.

21.3 Konfirmasi jadwal — konfirmasiJadwal

Karyawan aktif, header milik karyawan, fase konfirmasi_jadwal, usulan admin terakhir terbuka → revisi (insert baris revisi) atau konfirmasi (insert baris konfirmasi, salin jadwal ke header, fase penjadwalan).

21.4 Atur pelaksanaan — aturPelaksanaan

Fase penjadwalan → mekanisme valid → asset terpakai → vendor (master/teks) → lokasi → hadir: pendamping aktif + pendampingMasterId → fase pelaksanaan; diserahkan: jadwal pengambilan + baris jadwal → fase menunggu_pengambilan.

21.5 Checklist pengambilan — checklistPengambilan

Fase menunggu_pengambilan, checklist kosong, asset terpakai → normalizeKondisiChecklist → simpan JSON.

21.6 Serahkan — pelepasan

Karyawan aktif, milik karyawan, checklist ada → asset dalam_perbaikan → log karyawan → gudang → fase pelaksanaan, tgl/user_pelepasan.

21.7 Hasil — hasil

Pengisi = pendamping (payload id_karyawan) atau admin (user_id) → fase pelaksanaan → cek hak pendamping → asset dipegang (status sesuai mekanisme) → normalizeHasilChecklist → hasil terberat → UPDATE item → fase menunggu_review.

21.8 Review — review

Fase menunggu_review → asset dipegang (dalam_perbaikan untuk diserahkan, terpakai untuk hadir) → hasil 4/5: tarik asset + log + (opsional) AssetRequestKaryawan_m::store → selesai; hasil 1–3: jadwalBerikutnya (+ rencana penggantian hasil 3) → hadir selesai / diserahkan jadwal pengembalian + menunggu_pengembalian. Respons menambah hasil, ditarik, id_request_pengganti.

21.9 Terima — terima

Fase menunggu_pengembalian → asset dalam_perbaikan di karyawan → checklist → asset terpakai → log gudang → karyawan → selesai, tgl/user_diterima.

21.10 Query baca

• Monitoring: asset flag = 1, karyawan, terpakai, jadwal ≤ H+14, tanpa PM aktif; urut jadwal terdekat; sisa_hari negatif = terlambat; watchlist dari PM selesai terakhir bila hasil 2/3.
• List: tab jadwal (konfirmasi_jadwal, penjadwalan), proses (fase lain kecuali selesai), selesai; karyawan melihat PM sebagai pemegang atau pendamping (peran).
• Detail: header, riwayat jadwal, usulan_jadwal terbuka, komponen, checklist, hasil, review, objek aksi sesuai peran.
• Pending admin: usulan karyawan terakhir (revisi), penjadwalan, pengambilan tanpa checklist, pelaksanaan mekanisme diserahkan, menunggu_review.
• Pending karyawan: konfirmasi_jadwal (ada usulan admin), pelepasan, terima, hasil (pendamping).

22Dampak terhadap asset_data

23API Documentation

Prefix /asset, header Authorization: Bearer <JWT>. Admin divalidasi accessError (admin asset aktif).

Terkait: GET /asset/summary (pemeliharaan_perlu_proses, pemeliharaan_pending, pemeliharaan_jatuh_tempo_jumlah, pemeliharaan_jatuh_tempo) dan Asset Saya (pemeliharaan[]).

24Detail Setiap API

API-001 — Monitoring jatuh tempo

{
  "code": "SUCCESS",
  "data": {
    "records": [
      {
        "id_asset_data": "C0012026090001",
        "kode_asset": "LTP-2026-0001",
        "nama_asset": "Laptop Kerja",
        "kategori_asset": "Laptop",
        "interval_pemeliharaan": 6,
        "jadwal_pemeliharaan": "2026-10-03",
        "sisa_hari": 5,
        "karyawan": {"id_karyawan": "EMP-01", "nik": "343242", "nama_karyawan": "Karyawan Contoh"},
        "watchlist": {"no_trx": "PML01-2-202603001", "hasil": "perlu_tindak_lanjut", "hasil_label": "Perlu Tindak Lanjut", "keterangan": "Kipas bising"}
      }
    ]
  }
}

API-004 — Buat PM

POST /asset/pemeliharaan-karyawan
{"id_asset_data": "C0012026090001", "tgl_jadwal": "2026-10-02", "jam_jadwal": "10:00", "keterangan_jadwal": "PM rutin 6 bulan"}

Validasi: id_asset_data wajib, tgl_jadwal Y-m-d wajib, jam_jadwal H:i wajib. Respons 201 {id, no_trx, mekanisme_pelaksanaan, fase_pemeliharaan, status_label, tab}. Notif pemeliharaan.usulan_jadwal.

API-005 — Usul/ubah jadwal

tgl_jadwal, jam_jadwal wajib, keterangan_jadwal opsional. Notif pemeliharaan.usulan_jadwal (fase konfirmasi_jadwal) atau pemeliharaan.jadwal_diubah.

API-012 — Konfirmasi jadwal (karyawan)

{"aksi": "revisi", "tgl_jadwal": "2026-10-05", "jam_jadwal": "13:00", "keterangan_jadwal": "Sedang dinas luar"}

aksi konfirmasi|revisi; untuk revisi tanggal, jam, keterangan wajib. Notif pemeliharaan.jadwal_disetujui / pemeliharaan.jadwal_revisi ke admin.

API-006 — Atur pelaksanaan

{
  "mekanisme_pelaksanaan": "hadir_langsung",
  "id_asset_vendor_m": "",
  "nama_vendor": "Servis Laptop Contoh",
  "keterangan_vendor": "0812-0000-0000",
  "lokasi_pemeliharaan": "Ruang IT lantai 2",
  "id_pic_pendamping": "EMP-01"
}

nama_vendor wajib bila id_asset_vendor_m kosong; lokasi_pemeliharaan wajib; id_pic_pendamping boleh dikirim tetapi diabaikan (PIC Pendamping otomatis: pemegang untuk hadir langsung, admin pengatur untuk diserahkan); tgl_jadwal/jam_jadwal (pengambilan) wajib untuk diserahkan. Notif hadir: pemeliharaan.pendamping (ke pendamping) + pemeliharaan.dijadwalkan (ke karyawan); diserahkan: pemeliharaan.pengambilan.

API-007 — Checklist pengambilan & API-015 — Terima

{"items": [{"id_item": "C001…UNIT", "kondisi": "normal", "ket_rusak": ""}, {"id_item": "C001…CHG", "kondisi": "rusak", "ket_rusak": "Kabel longgar"}]}

Semua item asset (komponen di detail) wajib. Notif pemeliharaan.checklist_pengambilan / pemeliharaan.diterima.

API-013 — Serahkan aset

Tanpa body. Notif pemeliharaan.dilepas ke admin.

API-008 / API-014 — Checklist hasil

{
  "items": [
    {"id_item": "C001…UNIT", "hasil": "normal", "keterangan": ""},
    {"id_item": "C001…CHG", "hasil": "komponen_rusak_tidak_segera", "keterangan": "Adaptor panas"}
  ],
  "keterangan": "Dikerjakan vendor, dibersihkan"
}

Respons menambah hasil (hasil akhir). Notif pemeliharaan.hasil ke admin.

API-009 — Review & tindak lanjut

{
  "keterangan_review": "Pantau adaptor",
  "tgl_rencana_penggantian_komponen": "2026-11-01",
  "id_asset_pengganti": "",
  "tgl_jadwal": "2026-10-10",
  "jam_jadwal": "09:00",
  "keterangan_jadwal": "Ambil di ruang HR"
}

tgl_rencana_penggantian_komponen wajib untuk hasil 3; jadwal wajib untuk diserahkan hasil 1–3 (pengembalian) atau bila unit pengganti dipilih (serah terima Penambahan). Respons {…, hasil, ditarik, id_request_pengganti}. Notif pemeliharaan.selesai / pemeliharaan.pengembalian / pemeliharaan.ditarik (+ penambahan.dikirim).

API-010 / API-016 — Detail (ringkas)

{
  "id": "C001202609001",
  "no_trx": "PML01-2-202609001",
  "fase_pemeliharaan": "menunggu_review",
  "status_label": "Menunggu Review",
  "tab": "proses",
  "peran": "pendamping",
  "mekanisme_pelaksanaan": "hadir_langsung",
  "karyawan": {"id_karyawan": "EMP-01", "nik": "343242", "nama_karyawan": "Karyawan Contoh", "cabang": "Pusat", "divisi": "IT", "jabatan": "Staff IT"},
  "pendamping": {"id_karyawan": "EMP-02", "nik": "343243", "nama_karyawan": "Pendamping Contoh"},
  "vendor": {"id_asset_vendor_m": "", "nama_vendor": "Servis Laptop Contoh", "keterangan_vendor": "0812-0000-0000"},
  "lokasi_pemeliharaan": "Ruang IT lantai 2",
  "tgl_pemeliharaan": "2026-10-02", "jam_pemeliharaan": "10:00",
  "usulan_jadwal": null,
  "riwayat_jadwal": [{"jenis_jadwal": "pemeliharaan", "jenis_alur": "menunggu", "label_alur": "admin", "tanggal": "2026-10-02", "jam": "10:00", "keterangan": ""}],
  "asset": {"id_asset_data": "C0012026090001", "nama_asset": "Laptop Kerja", "status_asset": "terpakai", "interval_pemeliharaan": 6},
  "komponen": [{"id_item": "C001…UNIT", "nama_item": "Unit Utama", "jenis": "aset_utama"}],
  "hasil": {"status": "perlu_tindak_lanjut", "label": "Perlu Tindak Lanjut", "checklist": [], "user_hasil": "343243 - Pendamping Contoh"},
  "review": {"tgl_pemeliharaan_selanjutnya": "", "tindak_lanjut": "", "flag_unit_pengganti": false},
  "aksi": {"konfirmasi_jadwal": false, "pelepasan": false, "hasil": false, "terima": false}
}

Objek aksi admin: usul_jadwal, ubah_jadwal, atur_pelaksanaan, checklist_pengambilan, hasil, review. Karyawan hanya melihat PM miliknya atau yang ia dampingi (lainnya 404).

25Mobile Architecture

26Mobile Screen

26.1 Pemeliharaan Terjadwal — list

Tab Jadwal / Proses / Selesai; kartu menampilkan asset, no_trx, badge fase, karyawan (admin), "Anda PIC Pendamping", hasil akhir berwarna, dan notice jadwal aktif. Admin punya ikon Jatuh Tempo di app bar.

26.2 Jatuh Tempo Pemeliharaan (admin)

Kartu per asset: nama, kategori/kode, badge "5 hari lagi" / "Hari ini" / "Terlambat 2 hari", pemegang, jadwal PM, interval, notice Catatan PM sebelumnya (watchlist), tombol Jadwalkan PM (sheet jadwal).

26.3 Detail Pemeliharaan

Header (no_trx, badge, asset, pemegang, interval) → timeline (Jadwal · Pelaksanaan · Review · [Pengembalian] · Selesai) → notice jadwal aktif (+ tombol Ubah Jadwal admin) → notice info fase sesuai peran → ringkasan pelaksanaan (mekanisme, jadwal, vendor, lokasi, pendamping) → form checklist kondisi / form checklist hasil (chip 5 tingkat + keterangan temuan + catatan umum) → ringkasan hasil → form review (catatan, rencana penggantian untuk hasil 3, unit pengganti untuk hasil 4–5) → ringkasan review → checklist pengambilan/pengembalian → riwayat jadwal. Tombol bawah sesuai aksi.

26.4 Sheet Atur Pelaksanaan

Segmented mekanisme, dropdown vendor master + "Isi nama vendor manual", keterangan vendor, lokasi, pemilih PIC Pendamping (default pemegang). Mekanisme diserahkan lanjut ke sheet Jadwal Pengambilan.

26.5 Entry point

• Asset Saya: menu Pemeliharaan; banner teal sesuai aksi (konfirmasi_jadwal, pelepasan, terima, hasil).
• Admin: tile Pemeliharaan, kartu Pemeliharaan Perlu Diproses (label aksi per fase) dan Pemeliharaan Jatuh Tempo (chip merah bila terlambat).

27Mobile → API

28API → Mobile

29Mapping Mobile → API → Database

30Mapping Database → API → Mobile

31Validation

31.1 Mobile

• Sheet jadwal: tanggal (≥ hari ini) & jam wajib.
• Checklist hasil: semua item wajib dipilih ("Pilih hasil untuk setiap item."); keterangan temuan wajib untuk hasil selain normal.
• Sheet pelaksanaan: vendor (manual) wajib, lokasi wajib; PIC Pendamping tidak dipilih (otomatis pemegang asset untuk hadir langsung).
• Review: tanggal rencana penggantian wajib untuk hasil 3.
• Checklist kondisi: semua item wajib, rusak wajib keterangan.

31.2 Backend — §9 & §24.

31.3 Database — enum mekanisme_pelaksanaan, fase_pemeliharaan, jenis_jadwal, jenis_alur, status_item_pendamping, status; FK vendor, pendamping, asset.

32Error Handling

422 lain: "Asset sedang diproses pada pemeliharaan lain.", "Jadwal tidak dapat diubah pada tahap ini.", "Jadwal pemeliharaan belum disepakati karyawan.", "Mekanisme pelaksanaan tidak valid.", "Vendor tidak ditemukan.", "Checklist pengambilan tidak dapat diisi saat ini.", "Aset belum siap diserahkan untuk pemeliharaan.", "Hasil pemeliharaan belum dikirim.", "Status asset sudah berubah atau tidak lagi dipegang karyawan.", "Tanggal serah terima tidak boleh sebelum tanggal pengajuan." (pesan helper jadwal bersama).

33Audit Trail

34Notification

Semua event punya versi ID & EN, disimpan ke notif_data dan dikirim FCM setelah transaksi commit. Penerima pendamping diambil dari id_pic_pendamping header. ⚠️ Vendor tidak menerima notifikasi (INC-01).

35Security

• Semua endpoint di balik JWT; identitas diambil dari token (ctx), bukan dari body.
• Endpoint admin memanggil accessError + actorAdmin (admin asset & karyawan aktif).
• Endpoint karyawan membatasi header: aksi pemegang memakai lockHeader(..., id_karyawan); pengisian hasil memeriksa id_pic_pendamping + mekanisme; detail hanya untuk pemegang/pendamping.
• Semua mutasi di dalam DB::transaction dengan lockCompany + lockForUpdate pada header, item, dan asset.
• Validasi enum di controller dan model; JSON checklist dibangun ulang server-side dari komponen asset (bukan disimpan mentah dari klien).

36Manual Book User/Admin

A. Admin — Menjadwalkan PM

1. Asset Karyawan → Pemeliharaan → ikon Jatuh Tempo (atau kartu Pemeliharaan Jatuh Tempo).
2. Periksa sisa hari dan Catatan PM sebelumnya bila ada.
3. Tekan Jadwalkan PM, isi tanggal, jam, catatan → simpan.

B. Karyawan — Menyetujui jadwal

1. Buka banner Konfirmasi Jadwal PM atau menu Pemeliharaan.
2. Tekan Setujui Jadwal, atau Usulkan Jadwal Lain dengan tanggal, jam, dan alasan.

C. Admin — Menanggapi usulan karyawan

Buka detail (kartu Pemeliharaan Perlu Diproses menampilkan "Usulkan Jadwal"), lihat Riwayat Jadwal, tekan Usulkan Jadwal.

D. Admin — Mengatur pelaksanaan

Tekan Atur Pelaksanaan → pilih mekanisme → vendor (dari daftar atau isi manual), kontak vendor, lokasi → Karyawan Hadir Langsung: pilih PIC Pendamping → Simpan; Diserahkan ke Admin/HR: isi Jadwal Pengambilan.

E. Mekanisme diserahkan — Pengambilan

1. Admin: saat mengambil asset, isi Checklist Pengambilan → Simpan Checklist.
2. Karyawan: banner Serahkan Aset untuk PM → Serahkan Aset.

F. Mengisi hasil PM

• Hadir langsung: PIC Pendamping membuka banner Isi Hasil PM, memilih hasil setiap item bersama teknisi, mengisi keterangan temuan → Kirim Hasil.
• Diserahkan: admin mengisi berdasarkan laporan vendor.

G. Admin — Review & tindak lanjut

Buka detail → periksa hasil → isi catatan → hasil 3: Rencana penggantian komponen; hasil 4–5: pilih Unit pengganti bila perlu → Simpan Review (diserahkan: isi Jadwal Pengembalian; unit pengganti: isi Jadwal Pengiriman Unit Pengganti).

H. Karyawan — Menerima asset kembali

Banner Terima Aset Hasil PM → isi checklist kondisi → Terima Aset.

37Kondisi Button

38Testing Scenario

Test otomatis API (6): test_monitoring_lists_due_asset_and_store_blocks_duplicates, test_retur_and_offboarding_reject_asset_in_maintenance, test_hadir_langsung_flow_with_negotiation_and_pendamping, test_diserahkan_flow_returns_asset_after_review, test_tidak_dapat_diperbaiki_withdraws_asset_to_warehouse, test_routes_confirm_schedule_and_notify_admin. Mobile (6): teks id/en, parsing detail/list, hasil terberat, summary & Asset Saya, monitoring. ⚠️ TC-19 (unit pengganti) belum diuji otomatis.

39Temuan Ketidaksesuaian

40Edge Case

41Potential Bug / Technical Risk

RISK-001 — Skema dari SQL manual (TINGGI)

Lokasi: kolom PML01 hanya ada di sql-pml01-pemeliharaan-karyawan.sql; tidak ada migration. Masalah: environment yang belum menjalankan SQL akan gagal di semua endpoint PML01 (kolom tidak ada), sementara dashboard diam-diam kosong karena skemaSiap(). Rollback migration Upgrade menulis ulang enum jenis_log tanpa pemeliharaan_karyawan. Recommendation: jalankan SQL di semua environment; buat migration padanan; sertakan pemeliharaan_karyawan di daftar enum migration lain.

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

PM yang tidak berlanjut mengunci asset dari Upgrade, Kerusakan, Retur, dan Offboarding tanpa jalan keluar.

RISK-003 — Karyawan nonaktif menghentikan alur (SEDANG)

Konfirmasi jadwal, serahkan, dan terima mensyaratkan karyawan aktif; admin tidak punya aksi pengganti (kecuali isi hasil).

RISK-004 — Penarikan tanpa serah terima fisik (SEDANG)

Hasil 4–5 mekanisme hadir langsung langsung memindahkan asset ke gudang saat review, walau fisik masih di karyawan.

RISK-005 — Kueri pending karyawan N+1 (RENDAH)

getPendingForEmployee membaca riwayat jadwal per transaksi konfirmasi_jadwal.

RISK-006 — Notifikasi di luar transaksi (RENDAH)

Notifikasi (termasuk pendamping & penambahan pengganti) dikirim setelah commit; kegagalan hanya dicatat log.

RISK-007 — Kapasitas penomoran (RENDAH)

999 transaksi per bulan per company (header, item, jadwal).

42Dependency

asset_data (flag_pemeliharaan, interval, jadwal) + asset_data_item (komponen checklist)
      ↓
Pemeliharaan PML01 (konfirmasi_jadwal → … → selesai) ──► Notifikasi (karyawan / admin / pendamping)
      ↓
asset_data (dalam_perbaikan ↔ terpakai | rusak @gudang, jadwal_pemeliharaan baru), asset_trx_log pemeliharaan_karyawan
      ↓ (hasil 4–5)
Penambahan KRY-03-1 (unit pengganti) · PML02 / PML04 (ada, belum terhubung otomatis)

Aturan silang:
  - PML01 mengecek: pemeliharaan lain, Upgrade, Kerusakan, Retur, Offboarding
  - Dicek oleh: Upgrade, Kerusakan, Retur, Offboarding (hasActivePemeliharaanAsset)
  - Summary admin: pemeliharaan_perlu_proses / _pending / _jatuh_tempo(_jumlah); Asset Saya: pemeliharaan[]

43Source Code Reference

44Developer Notes

• Terapkan SQL dulu. Tanpa kolom baru, endpoint PML01 gagal; skemaSiap() hanya melindungi dashboard dan modul lain.
• Hasil akhir dihitung server. Klien mengirim hasil per item; status_item_pendamping = item terberat (urutan konstanta HASIL).
• Peran dari header. Karyawan yang sama bisa pemegang sekaligus pendamping (peran = pemegang_pendamping); aksi hasil hanya dibuka untuk hadir langsung.
• Unit pengganti memakai Penambahan. AssetRequestKaryawan_m::store dipanggil di dalam transaksi review; kegagalannya membatalkan review.
• Jadwal berikutnya memakai addMonthsNoOverflow (31 Jan + 1 bulan → 28/29 Feb).
• Tab list berbeda dari modul lain (jadwal / proses / selesai); AssetTrxListBody kini menerima parameter filters.
• Format kode Mobile: jalankan dart format hanya pada file yang diubah (repo MOBILE memiliki banyak perubahan lokal).

45End-to-End Traceability

45.4 Walkthrough Lengkap dengan Contoh Data

Bagian ini mengikuti satu pemeliharaan (PM) dengan mekanisme Karyawan Hadir Langsung dari usulan jadwal sampai selesai, langkah demi langkah: apa yang dilakukan pengguna di mobile, apa yang dikirim, apa yang diproses API, dan apa yang tersimpan di database. Data bersifat sintetis, tetapi format ID, nama kolom, urutan proses, label status, dan pesan diambil dari kode (AssetPemeliharaanKaryawan_m, AssetAdminPemeliharaan_c, AssetKaryawanPemeliharaan_c, AssetNotification). Mekanisme Diserahkan ke Admin dijelaskan pada bagian Variasi.

Skenario: Laptop Wulan jatuh tempo pemeliharaan enam bulanan. Admin mengusulkan jadwal, Wulan mengusulkan jadwal lain, admin mengusulkan ulang, lalu Wulan menyetujui. Admin mengatur pelaksanaan (hadir langsung, vendor, lokasi). Wulan sebagai PIC Pendamping mengisi checklist hasil: unit normal tetapi adaptor "komponen rusak tidak segera". Admin mereview dan jadwal PM berikutnya dihitung otomatis.

Data awal

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

data_karyawan

asset_data A30: CMP00120260100030 (LTP-2026-0001), Laptop Kerja, kategori Laptop, status_asset = terpakai, pemegang_asset = karyawan, id_pemegang_asset = KRY0011, flag_pemeliharaan = 1, interval_pemeliharaan = 6 (bulan), jadwal_pemeliharaan = 2026-10-30, kondisi_awal = normal.

Komponen (asset_data_item): CMP001ITEM0401 Unit Utama (aset_utama) dan CMP001ITEM0402 Adaptor (kelengkapan).

Penomoran: header, item, dan baris jadwal id_company + YYYYMM + 3 digit, no_trx = PML01-2-YYYYMMNNN; asset_pendamping_m 3 digit; log dan notifikasi 5 digit.

Langkah 0 — Admin membuka daftar jatuh tempo

Mobile: Asset Karyawan → Jatuh Tempo Pemeliharaan → AssetPemeliharaanAdminApi.getMonitoring().

Dikirim

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

Diproses API (AssetPemeliharaanKaryawan_m::getMonitoring): asset dengan flag_pemeliharaan = 1, dipegang karyawan aktif, terpakai, jadwal_pemeliharaan ≤ hari ini + 14, tanpa PM aktif (fase ≠ selesai); diurutkan jadwal terdekat. sisa_hari negatif berarti terlambat. watchlist memuat hasil PM selesai terakhir bila hasilnya "perlu tindak lanjut" atau "komponen rusak tidak segera".

Database: hanya SELECT.

Diterima mobile (ringkas)

{ "code": "SUCCESS",
  "data": { "records": [ {
    "id_asset_data": "CMP00120260100030", "kode_asset": "LTP-2026-0001", "nama_asset": "Laptop Kerja",
    "kategori_asset": "Laptop", "interval_pemeliharaan": 6, "jadwal_pemeliharaan": "2026-10-30", "sisa_hari": 8,
    "karyawan": { "id_karyawan": "KRY0011", "nik": "EMP-011", "nama_karyawan": "Wulan Contoh" },
    "watchlist": null } ] } }

Langkah 1 — Admin membuat PM dan mengusulkan jadwal

Mobile: admin memilih asset → Usulkan Jadwal, mengisi tanggal 30 Okt 2026 pukul 10:00 → AssetPemeliharaanAdminApi.store.

Dikirim

POST /asset/pemeliharaan-karyawan

{ "id_asset_data": "CMP00120260100030", "tgl_jadwal": "2026-10-30", "jam_jadwal": "10:00",
  "keterangan_jadwal": "PM rutin 6 bulan" }

Diproses API (AssetAdminPemeliharaan_c::storePemeliharaanKaryawan → store, satu DB::transaction) 1. Validasi: id_asset_data, tgl_jadwal (Y-m-d), jam_jadwal (H:i) wajib. Cek admin, lockCompany. 2. Jadwal tanggal ≥ hari ini. Asset diambil FOR UPDATE: dipegang karyawan, terpakai, flag_pemeliharaan = 1. 3. assetBlockMessage: tidak ada PM aktif lain, upgrade, laporan kerusakan, retur, atau offboarding atas asset itu. 4. Pemegang harus karyawan aktif (cabang dan departemen diambil untuk snapshot). 5. Generate ID: header urutan 1 → CMP001202610001, no_trx = PML01-2-202610001. 6. INSERT header (fase_pemeliharaan = konfirmasi_jadwal, mekanisme_pelaksanaan = hadir_langsung sebagai nilai awal, status = proses), INSERT item (hasil NULL), INSERT baris jadwal pertama (jenis_jadwal = pemeliharaan, jenis_alur = menunggu, label_alur = admin). 7. asset_data tidak berubah. Notifikasi pemeliharaan.usulan_jadwal ke karyawan.

Hasil database

asset_trx_pemeliharaan_karyawan

asset_trx_pemeliharaan_karyawan_item: CMP001202610001, A30, Laptop Kerja, status_item_pendamping = NULL.

asset_trx_pemeliharaan_karyawan_jadwal (1 baris)

notif_data: CMP00120261000001 ke KRY0011, id_ref CMP001202610001, rute asset_detail_pemeliharaan, "Admin mengusulkan jadwal pemeliharaan PML01-2-202610001. Silakan konfirmasi."

Diterima mobile (HTTP 201)

{ "code": "CREATED", "data": { "id": "CMP001202610001", "no_trx": "PML01-2-202610001",
  "mekanisme_pelaksanaan": "hadir_langsung", "fase_pemeliharaan": "konfirmasi_jadwal",
  "status_label": "Konfirmasi Jadwal", "tab": "jadwal" } }

Langkah 2 — Wulan mengusulkan jadwal lain

Mobile: banner di Asset Saya → detail → Usulkan Jadwal Lain, tanggal 2 Nov 2026 pukul 13:00, alasan "Sedang dinas luar" → AssetPemeliharaanApi.konfirmasiJadwal.

Dikirim

POST /asset/karyawan/pemeliharaan/CMP001202610001/jadwal

{ "aksi": "revisi", "tgl_jadwal": "2026-11-02", "jam_jadwal": "13:00", "keterangan_jadwal": "Sedang dinas luar" }

Diproses API (konfirmasiJadwalPemeliharaanSaya → konfirmasiJadwal) 1. Karyawan aktif; header milik Wulan. Fase harus konfirmasi_jadwal dan baris jadwal PM terakhir adalah usulan admin berstatus menunggu ("Tidak ada usulan jadwal yang perlu dikonfirmasi."). 2. aksi = revisi: tanggal, jam, dan alasan wajib ("Alasan usulan jadwal alternatif wajib diisi."). 3. INSERT baris jadwal (revisi, label_alur = karyawan). Fase tetap konfirmasi_jadwal; admin wajib mengusulkan ulang. 4. Notifikasi pemeliharaan.jadwal_revisi ke admin.

Hasil database

Diterima mobile (HTTP 200): ringkasan fase yang sama (konfirmasi_jadwal).

Langkah 3 — Admin mengusulkan jadwal ulang

Dikirim

PUT /asset/pemeliharaan-karyawan/CMP001202610001/jadwal

{ "tgl_jadwal": "2026-11-03", "jam_jadwal": "09:00", "keterangan_jadwal": "Disesuaikan kehadiran vendor" }

Diproses API (updateJadwalPemeliharaan → updateJadwal): fase menentukan jenis jadwal. Pada konfirmasi_jadwal, jenisnya pemeliharaan sehingga INSERT baris jadwal menunggu baru; kolom tanggal header tidak diubah. Tanggal tidak boleh sebelum tanggal transaksi dibuat. Pada fase lain: menunggu_pengambilan mengubah jadwal pengambilan, menunggu_pengembalian jadwal pengembalian, selain itu 422 "Jadwal tidak dapat diubah pada tahap ini.". Notifikasi pemeliharaan.usulan_jadwal (fase konfirmasi) atau pemeliharaan.jadwal_diubah (fase lain).

Hasil database: jadwal baru CMP001202610003 (pemeliharaan, 2026-11-03 / 09:00:00, menunggu, admin); notifikasi CMP00120261000004 ke KRY0011 ("Admin mengusulkan jadwal pemeliharaan PML01-2-202610001. Silakan konfirmasi.").

Langkah 4 — Wulan menyetujui jadwal

Dikirim

POST /asset/karyawan/pemeliharaan/CMP001202610001/jadwal

{ "aksi": "konfirmasi" }

Diproses API (konfirmasiJadwal): usulan admin terakhir (CMP001202610003) terbuka. INSERT jadwal konfirmasi (label_alur = karyawan) dan UPDATE header: fase_pemeliharaan = penjadwalan, tgl_pemeliharaan = 2026-11-03, jam_pemeliharaan = 09:00:00. Notifikasi pemeliharaan.jadwal_disetujui ke admin.

Hasil database

Diterima mobile: fase_pemeliharaan = penjadwalan, status_label = "Penjadwalan", tab = "jadwal".

Langkah 5 — Admin mengatur pelaksanaan

Mobile: sheet Atur Pelaksanaan: mekanisme Karyawan Hadir Langsung, vendor "Servis Laptop Contoh" (teks), lokasi → AssetPemeliharaanAdminApi.aturPelaksanaan.

Dikirim

POST /asset/pemeliharaan-karyawan/CMP001202610001/pelaksanaan

{
  "mekanisme_pelaksanaan": "hadir_langsung",
  "id_asset_vendor_m": "",
  "nama_vendor": "Servis Laptop Contoh",
  "keterangan_vendor": "0812-0000-0000",
  "lokasi_pemeliharaan": "Ruang IT lantai 2",
  "id_pic_pendamping": "KRY0011"
}

Untuk mekanisme hadir langsung, mobile mengisi id_pic_pendamping dengan pemegang asset; API tidak memakai nilai ini (lihat catatan di bawah).

Diproses API (aturPelaksanaanPemeliharaan → aturPelaksanaan) 1. Validasi: mekanisme_pelaksanaan ∈ hadir_langsung/diserahkan_admin; nama_vendor wajib bila id_asset_vendor_m kosong; lokasi_pemeliharaan wajib; jadwal pengambilan wajib hanya untuk diserahkan. 2. Fase harus penjadwalan ("Jadwal pemeliharaan belum disepakati karyawan."); asset masih terpakai di karyawan. 3. Vendor dari master (id_asset_vendor_m) atau teks bebas. 4. PIC Pendamping ditentukan otomatis: pemegang asset bila hadir langsung, admin yang mengatur bila diserahkan. Karyawan itu dicatat ke asset_pendamping_m bila belum ada. 5. Hadir langsung → fase pelaksanaan. (Diserahkan → INSERT jadwal pengambilan dan fase menunggu_pengambilan.) 6. Notifikasi pemeliharaan.pendamping (ke PIC Pendamping) lalu pemeliharaan.dijadwalkan (ke karyawan).

Hasil database

Diterima mobile (HTTP 200): fase_pemeliharaan = pelaksanaan, status_label = "Pelaksanaan PM", tab = "proses", message "Pelaksanaan pemeliharaan berhasil diatur.".

Langkah 6 — PIC Pendamping mengisi checklist hasil

Mobile: pada hari pelaksanaan Wulan (sebagai pendamping) membuka detail (peran = pendamping), menilai tiap komponen (5 tingkat) → AssetPemeliharaanApi.hasil.

Dikirim

POST /asset/karyawan/pemeliharaan/CMP001202610001/hasil

{
  "items": [
    { "id_item": "CMP001ITEM0401", "hasil": "normal", "keterangan": "" },
    { "id_item": "CMP001ITEM0402", "hasil": "komponen_rusak_tidak_segera", "keterangan": "Adaptor panas" }
  ],
  "keterangan": "Dikerjakan vendor, dibersihkan"
}

Diproses API (hasilPemeliharaanSaya → hasil dengan id_karyawan) 1. Fase harus pelaksanaan ("Pemeliharaan belum berada pada tahap pelaksanaan."). 2. Via karyawan: mekanisme harus hadir langsung dan id_pic_pendamping = penggunanya ("Hanya PIC Pendamping yang dapat mengisi hasil pemeliharaan."). Admin dapat mengisi lewat API-008 untuk semua mekanisme. 3. Asset masih dipegang (terpakai untuk hadir langsung, dalam_perbaikan untuk diserahkan). 4. normalizeHasilChecklist: semua komponen wajib dinilai ("Seluruh item aset wajib diperiksa."); hasil salah satu dari lima tingkat ("Hasil pemeriksaan item tidak valid."); selain normal wajib keterangan. 5. Hasil akhir = item terberat (urutan: normal < perlu_tindak_lanjut < komponen_rusak_tidak_segera < komponen_rusak_perlu_segera < tidak_dapat_diperbaiki) → komponen_rusak_tidak_segera. 6. UPDATE item (status_item_pendamping, checklist_hasil, keterangan_konfirmasi) dan header (fase = menunggu_review, tgl_hasil, user_hasil). 7. Notifikasi pemeliharaan.hasil ke admin.

Hasil database

Diterima mobile (HTTP 200): fase_pemeliharaan = menunggu_review, hasil = "komponen_rusak_tidak_segera".

Langkah 7 — Admin mereview dan menentukan tindak lanjut

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

Dikirim

POST /asset/pemeliharaan-karyawan/CMP001202610001/review

{ "keterangan_review": "Pantau adaptor", "tgl_rencana_penggantian_komponen": "2026-11-20" }

Diproses API (reviewPemeliharaanKaryawan → review) 1. Fase harus menunggu_review ("Hasil pemeliharaan belum dikirim."); asset masih dipegang. 2. Hasil ini bukan tingkat 4–5, sehingga asset tetap dipakai. jadwalBerikutnya: hasil 3 wajib tanggal rencana penggantian komponen ("Tanggal rencana penggantian komponen wajib diisi."); bila interval_pemeliharaan > 0, jadwal PM berikutnya = tanggal review + interval bulan (tanpa overflow akhir bulan), ditulis ke asset_data.jadwal_pemeliharaan dan item.tgl_pemeliharaan_selanjutnya. 3. Mekanisme hadir langsung → header selesai. (Diserahkan → jadwal pengembalian wajib dan fase menunggu_pengembalian.) 4. UPDATE header: tgl_review, user_review, keterangan_review, fase, status = selesai. 5. Hadir langsung dengan hasil 1–3 tidak menulis asset_trx_log; jejaknya ada di transaksi PM dan jadwal_pemeliharaan. 6. Notifikasi pemeliharaan.selesai ke karyawan.

Hasil database

Diterima mobile (HTTP 200)

{ "code": "UPDATED", "data": { "id": "CMP001202610001", "no_trx": "PML01-2-202610001",
  "fase_pemeliharaan": "selesai", "status_label": "Selesai", "tab": "selesai",
  "hasil": "komponen_rusak_tidak_segera", "ditarik": false, "id_request_pengganti": "" } }

Pada pemantauan berikutnya asset ini muncul di watchlist karena hasil terakhirnya "komponen rusak tidak segera".

Kondisi akhir data

asset_trx_pemeliharaan_karyawan: CMP001202610001 / PML01-2-202610001, fase_pemeliharaan = selesai, status = selesai, mekanisme hadir langsung, vendor Servis Laptop Contoh, PIC Pendamping KRY0011.

asset_trx_pemeliharaan_karyawan_jadwal: 4 baris (menunggu admin → revisi karyawan → menunggu admin → konfirmasi karyawan) sebagai riwayat negosiasi.

asset_data A30: tetap terpakai @KRY0011, jadwal_pemeliharaan = 2027-05-03. asset_pendamping_m: 1 baris. asset_trx_log: 0 baris. notif_data: 11 baris.

Variasi

Mekanisme Diserahkan ke Admin. Pada langkah 5, mekanisme_pelaksanaan = diserahkan_admin dengan jadwal pengambilan wajib: PIC Pendamping = admin pelaksana, fase menunggu_pengambilan, jadwal pengambilan ditambahkan, notifikasi pemeliharaan.pengambilan. Lanjutannya: 1. Checklist Pengambilan (API-007, admin, semua komponen, rusak wajib keterangan; notifikasi pemeliharaan.checklist_pengambilan). 2. Serahkan Aset (API-013, karyawan; hanya setelah checklist ada): asset_data → dalam_perbaikan (pemegang_asset tetap karyawan), INSERT asset_trx_log (karyawan → gudang), fase pelaksanaan, notifikasi pemeliharaan.dilepas. 3. Hasil diisi admin dari laporan vendor (API-008). 4. Review hasil 1–3: jadwal pengembalian wajib, fase menunggu_pengembalian, notifikasi pemeliharaan.pengembalian. 5. Terima Aset (API-015, karyawan, checklist kondisi semua komponen): asset_data → terpakai, INSERT asset_trx_log (gudang → karyawan), fase selesai, tgl_diterima/user_diterima, notifikasi pemeliharaan.diterima.

Hasil 4–5 (asset ditarik). Pada review, hasil komponen_rusak_perlu_segera atau tidak_dapat_diperbaiki: asset_data → status_asset = rusak, kondisi_awal = rusak, ket_rusak (keterangan hasil + review, maks 255), status_rusak = "sudah tidak bisa di gunakan", pemegang_asset = gudang, id_pemegang_asset = ''; INSERT asset_trx_log (kondisi_akhir = rusak; posisi awal karyawan untuk hadir langsung, gudang untuk diserahkan); nama_tabel_tindak_lanjut = asset_trx_perbaikan (hasil 4) atau asset_trx_disposal (hasil 5), fase selesai, notifikasi pemeliharaan.ditarik. Transaksi Perbaikan atau Disposal tidak dibuat otomatis.

Unit pengganti (hasil 4–5, opsional). Bila id_asset_pengganti dikirim, review memanggil AssetRequestKaryawan_m::store untuk membuat Penambahan asset (KRY-03-1) bagi karyawan yang sama dalam transaksi yang sama (urgensi = mendesak, jadwal serah terima dari admin, keterangan = "Unit pengganti pemeliharaan {no_trx}"). Item PM mendapat flag_unit_pengganti = 1 dan id_trx_request_pengganti; aturan Penambahan berlaku (asset harus tersedia @gudang) dan notifikasi penambahan.dikirim ikut terkirim.

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

Interval 0. Bila interval_pemeliharaan = 0, jadwal_pemeliharaan tidak diubah dan item tidak diberi tgl_pemeliharaan_selanjutnya.

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

47Checklist Implementasi

Database

• DBML diperbarui ([FIX PML01])
• SQL manual + rollback
• SQL dijalankan di semua environment
• Migration Lumen padanan

Backend

• Monitoring jatuh tempo + watchlist
• Negosiasi jadwal
• Dua mekanisme + PIC Pendamping
• Checklist hasil 5 tingkat, hasil terberat
• Review: jadwal berikutnya, penarikan, unit pengganti
• Blokir lintas modul dua arah
• Notifikasi 14 event
• Test otomatis (6)
• Notifikasi otomatis Jalur A (scheduler)
• Integrasi otomatis ke PML02 / PML04 (modulnya sudah ada)
• Pembatalan / kedaluwarsa
• Test unit pengganti

Mobile

• List, monitoring, detail, sheet pelaksanaan
• Banner Asset Saya & kartu beranda admin
• Bahasa id/en
• Test model (6)
• Uji end-to-end di perangkat

Documentation

• Business Flow, DB, API, Mobile, Mapping, Manual Book, Testing
• Screenshot

48Changelog