Blueprint Pengembangan Software Industri - Mx-Core-rbm

Blueprint Pengembangan Software Industri: Mx-Core-rbm

• ✅ 🧩 1. Business Requirement Specification (BRS)
  • 📖 Latar Belakang Masalah
• 🧩 2. Software Requirement Specification (SRS)
• 🧩 3. System Design – Bagian 1: High-Level Design (HLD)
  • 🔷 3.1.1 Diagram Arsitektur Sistem
  • 🔷 3.1.2 Modul / Subsystem Overview
  • 🔷 3.1.3 Komunikasi Antar Modul
  • 🔷 3.1.4 External Interfaces
  • 🔷 3.1.5 Security & Auth Flow
  • 🔷 3.1.6 Integrasi Internal & Eksternal
  • 🧩 3.2 Low-Level Design (LLD) – mx-core-rbm
• 🧩 4. Implementation (Coding)
• 🧩 5. Testing
  • 🧩 Dokumen Pengujian
• 🧩 6. Deployment – mx-core-rbm
• 🧩 7. Maintenance & Support – mx-core-rbm

✅ 🧩 1. Business Requirement Specification (BRS)

• 📘 Judul Proyek

Modul Plugin mx-core-rbm untuk Strategi Risk-Based Maintenance Industri

📖 Latar Belakang Masalah

Sebelum menerapkan pendekatan Risk-Based Maintenance (RBM), strategi pemeliharaan aset di PT PON menggunakan metode yang seragam untuk semua aset, termasuk pemeliharaan berbasis waktu (TBM – Time-Based Maintenance) tanpa mempertimbangkan tingkat kritikalitas dan risiko kegagalan dari masing-masing aset.

Pendekatan tersebut menyebabkan:

• Penggunaan resources yang tinggi (tenaga kerja, waktu, biaya)
• Masih sering terjadi gangguan unplanned dan emergency
• Efektivitas perawatan rendah karena pemeliharaan dilakukan sama rata, bukan berdasarkan dampak potensial kegagalan

Setelah diterapkan RBM:

• Strategi pemeliharaan disusun berdasarkan tingkat risiko aktual dari tiap aset
• Penggunaan resources menurun signifikan, lebih terfokus pada aset kritis
• Tingkat unplanned shutdown menurun
• Performa aset membaik, mendekati kondisi optimal awalnya (mendekati nameplate)

Dengan pendekatan ini, RBM berperan sebagai kerangka pengambilan keputusan strategis untuk pemeliharaan, yang tidak hanya memperhitungkan frekuensi, tetapi dampak dan konsekuensi kegagalan terhadap:

• Keselamatan (Safety)
• Lingkungan (Environment)
• Kontinuitas produksi (Continuity)

Inilah yang mendorong kebutuhan sistem digital RBM seperti mx-core-rbm, agar strategi tersebut dapat diotomatisasi, distandardisasi, dan diintegrasikan ke sistem pemeliharaan yang lebih luas (CMMS, dashboard, dsb).

• 🎯 Visi dan Tujuan Bisnis

• Menyediakan sistem pengambilan keputusan strategis dalam perencanaan pemeliharaan berbasis data.
• Meningkatkan keandalan dan efisiensi biaya dengan mengidentifikasi aset yang kritis dan menentukan jenis perawatan yang tepat.
• Menstandarkan pendekatan RBM yang digunakan PT PON ke dalam bentuk sistem digital modular.
• Memungkinkan integrasi lintas sistem seperti CMMS, IoT monitoring, dan dashboard manajerial.

• 👥 Stakeholders dan Peran

• 📌 Kebutuhan Bisnis Tingkat Tinggi

1. Sistem dapat melakukan penilaian risiko berdasarkan aspek ESC.
2. Sistem dapat menghasilkan klasifikasi kritikalitas aset.
3. Sistem dapat menyusun strategi pemeliharaan berdasarkan hasil evaluasi risiko.
4. Sistem dapat menghasilkan jadwal TBM hybrid jika diperlukan.
5. Sistem menyediakan dashboard dan visualisasi kondisi aset.
6. Sistem dapat mengekspor data ke CMMS atau sistem lain.
7. Sistem dapat mengimport data dari file xlsx sebagai data awal aset.

• ✅ Kriteria Keberhasilan Proyek

• Sistem mampu menangani seluruh aset yang didefinisikan dalam struktur mx-core.
• Minimal 90% data aset tergradasi dengan model ESC dan memiliki criticality.
• Tersedianya dashboard yang menampilkan klasifikasi risiko dan strategi perawatan.
• Tersedia export CMMS yang dapat digunakan untuk integrasi operasional harian.
• Feedback positif dari stakeholders dalam UAT.

• ⚠️ Batasan dan Asumsi

• Data aset tersedia dalam sistem mx-core melalui struktur Asset, AssetType, AssetDetail.
• Engineer memiliki kompetensi dalam melakukan penilaian ESC.
• Penentuan strategi pemeliharaan tetap membutuhkan validasi manusia.
• Sistem tidak bertanggung jawab atas eksekusi fisik pemeliharaan (hanya perencanaan dan monitoring).
• Plugin mx-core-rbm hanya mengelola domain RBM — bukan manajemen aset secara umum.

🧩 2. Software Requirement Specification (SRS)

📌 Tujuan Dokumen

Dokumen ini bertujuan untuk menjabarkan kebutuhan teknis dari modul mx-core-rbm, sebuah plugin pada sistem mx-core, yang digunakan untuk mendukung implementasi Risk-Based Maintenance (RBM) di lingkungan industri, khususnya sesuai praktik PT PON.

Dokumen ini akan menjadi acuan utama bagi tim pengembang, QA, dan integrator sistem selama proses pengembangan, pengujian, dan validasi modul.

📌 Ruang Lingkup

Modul mx-core-rbm merupakan plugin mandiri dalam arsitektur monorepo mx-core yang bertugas menangani:

• Pengelolaan data evaluasi risiko berbasis ESC (Environment, Safety, Continuity)
• Klasifikasi kritikalitas aset
• Perencanaan strategi pemeliharaan (Preventive, Predictive, Corrective)
• Penyusunan jadwal TBM hybrid
• Monitoring histori evaluasi aset
• Export data ke CMMS
• Dashboard visualisasi kondisi aset

📌 Definisi & Akronim

🧭 Gambaran Umum Sistem

Modul mx-core-rbm dibangun di atas dua sub-domain utama:

1. Asset Sub-Domain

   • Menyediakan data statis dan struktural dari aset
   • Berperan sebagai data source untuk RBM
   • Tidak memuat logika evaluasi

2. RBM Sub-Domain

   • Berisi logika evaluasi risiko dan perencanaan strategi
   • Mencakup fitur grading ESC, criticality, perencanaan, evaluasi, dan export

Sistem ini terintegrasi secara internal dalam mx-core dan dapat melakukan export eksternal ke CMMS.

🧪 Functional Requirements (FR-n)

⚙️ Non-Functional Requirements

🧩 Use-Case List & Detail

📋 Daftar Use-Case

⚠️ Use-case diagram dapat disiapkan secara visual menggunakan tools seperti draw.io, Lucidchart, atau PlantUML (jika dibutuhkan nanti).

🔹 UC-01: Melakukan ESC Grading

• Nama: ESC Grading Form Input

• Aktor: Reliability Engineer

• Deskripsi: Engineer melakukan evaluasi risiko terhadap aset berdasarkan tiga aspek: Environment, Safety, dan Continuity.

• Trigger: Engineer membuka form grading untuk suatu aset yang sudah terdaftar.

• Alur Utama:

  1. Engineer memilih aset dari daftar (berdasarkan tagNumber)
  2. Sistem menampilkan form grading ESC
  3. Engineer mengisi nilai untuk setiap aspek (Low / Medium / High)
  4. Engineer menyimpan grading

• Alur Alternatif:

  • Data tidak lengkap → sistem menolak penyimpanan
  • Aset belum tersedia → redirect ke halaman DIA

• Kondisi Sukses: Grading ESC tersimpan dalam model ESCGrading, dan dapat dipakai untuk proses criticality

• Catatan Khusus: Timestamp dan nama grader disimpan sebagai audit trail

🔹 UC-02: Menentukan Criticality Aset

• Nama: Asset Criticality Determination

• Aktor: Sistem (otomatis) atau Reliability Engineer (manual override)

• Deskripsi: Menentukan apakah aset bersifat Kritis atau Normal berdasarkan ESC Grading

• Trigger: ESC Grading disubmit atau diubah

• Alur Utama:

  1. Sistem membaca nilai ESC
  2. Menjalankan rule-set penilaian (misalnya ≥ 2 aspek "High" = Kritis)
  3. Menyimpan hasil ke AssetCriticality

• Alur Alternatif:

  • Engineer bisa override hasil melalui halaman review

• Kondisi Sukses: Aset memiliki entry AssetCriticality yang valid

• Catatan Khusus: Overriding harus dicatat oleh user dan alasan

🔹 UC-03: Menyusun Strategi Pemeliharaan

• Nama: Maintenance Plan Builder

• Aktor: Maintenance Planner

• Deskripsi: Menentukan strategi pemeliharaan yang sesuai (Preventive, Predictive, Corrective) berdasarkan criticality dan kondisi teknis

• Trigger: Criticality aset telah ditentukan

• Alur Utama:

  1. Planner membuka halaman Maintenance Plan
  2. Sistem menyarankan strategi default (berdasarkan Tier)
  3. Planner dapat memilih/menyesuaikan strategi (P / P+C / P+P+C)
  4. Strategi disimpan ke MaintenancePlan

• Alur Alternatif:

  • Planner override → harus memberikan alasan

• Kondisi Sukses: Strategi tercatat dan siap diproses ke TBM scheduler

• Catatan Khusus: Sistem harus mencatat perubahan strategi di histori audit

🔹 UC-04: Menghasilkan Jadwal TBM

• Nama: TBM Schedule Generator

• Aktor: Maintenance Scheduler / Sistem

• Deskripsi: Menghasilkan jadwal pemeliharaan berbasis strategi yang ditentukan

• Trigger: Maintenance plan disimpan

• Alur Utama:

  1. Sistem membaca strategi dari MaintenancePlan
  2. Sistem menghasilkan TBMSchedule berdasarkan interval (misalnya: Predictive = 6 Bulanan)
  3. Jadwal ditampilkan di halaman scheduler

• Alur Alternatif:

  • Aset Tier-3 → tidak dijadwalkan otomatis

• Kondisi Sukses: Jadwal TBM tercatat dan bisa diubah/eksekusi oleh scheduler

• Catatan Khusus: Jadwal harus memperhitungkan last_executed dan next_due

🔹 UC-05: Mencatat Evaluation Record

• Nama: Asset Evaluation Recording

• Aktor: Inspector / Reliability Engineer

• Deskripsi: Mencatat hasil inspeksi atau evaluasi aktual kondisi aset sebagai histori evaluasi periodik atau insidental.

• Trigger: Inspector melakukan inspeksi fisik atau evaluasi kondisi aset.

• Alur Utama:

  1. Inspector memilih aset berdasarkan tagNumber

  2. Sistem menampilkan form Evaluation Record

  3. Inspector mengisi:

     • Tanggal evaluasi
     • Hasil evaluasi (OK / Warning / Failure)
     • Catatan tambahan (opsional)

  4. Inspector menyimpan data

  5. Sistem mencatat data ke tabel EvaluationRecord

• Alur Alternatif:

  • Aset belum memiliki ESC Grading → sistem memberi peringatan
  • Inspector membatalkan input → tidak ada data tersimpan

• Kondisi Sukses: Evaluation Record tersimpan dan dapat dilihat pada histori evaluasi aset

• Catatan Khusus:

  • Data Evaluation Record tidak mengubah criticality secara otomatis
  • Digunakan sebagai referensi untuk re-evaluasi RBM

🔹 UC-06: Melihat Dashboard Risiko & Tier

• Nama: RBM Dashboard Visualization

• Aktor: Supervisor, Manager, Reliability Engineer

• Deskripsi: Menyajikan visualisasi kondisi risiko aset secara agregat dan individual untuk mendukung pengambilan keputusan.

• Trigger: User membuka halaman dashboard RBM.

• Alur Utama:

  1. User mengakses menu Dashboard

  2. Sistem memuat data:

     • ESC grading
     • Criticality
     • Tier aset
     • Strategi pemeliharaan
     • Ringkasan Evaluation Record

  3. Sistem menampilkan grafik dan tabel (pie, bar, trend)

• Alur Alternatif:

  • Data belum tersedia → sistem menampilkan notifikasi "data belum lengkap"

• Kondisi Sukses: User dapat memahami distribusi risiko dan prioritas aset

• Catatan Khusus: Dashboard bersifat read-only, tidak untuk input atau editing data

🔹 UC-07: Menjalankan Export CMMS

• Nama: CMMS Data Export

• Aktor: IT / CMMS Admin

• Deskripsi: Mengekspor data RBM untuk digunakan pada sistem CMMS eksternal.

• Trigger: Admin memilih menu Export CMMS.

• Alur Utama:

  1. Admin memilih jenis data yang akan diekspor:

     • Asset
     • Criticality
     • Maintenance Plan
     • TBM Schedule

  2. Admin memilih format (JSON / CSV)

  3. Sistem memproses dan menghasilkan file export

  4. Admin mengunduh file hasil export

• Alur Alternatif:

  • Data kosong → sistem menampilkan peringatan
  • Format tidak didukung → sistem menolak permintaan

• Kondisi Sukses: File export berhasil diunduh dan siap digunakan CMMS

• Catatan Khusus:

  • Mapping field mengikuti standar mx-core
  • Tidak ada koneksi langsung (push) ke CMMS pada fase ini

🔹 UC-08: Mengelola DIA (Daftar Induk Aset)

• Nama: Asset Master Data Management

• Aktor: Maintenance Planner

• Deskripsi: Mengelola daftar aset sebagai fondasi RBM.

• Trigger: Planner membuka menu DIA / Assets.

• Alur Utama:

  1. Planner melihat daftar aset

  2. Planner dapat:

     • Menambah aset baru
     • Mengedit metadata aset
     • Mengaitkan Asset Type & Category

  3. Sistem menyimpan perubahan ke domain Asset

• Alur Alternatif:

  • Data tidak valid → sistem menolak penyimpanan
  • Aset sudah digunakan RBM → beberapa field terkunci

• Kondisi Sukses: Data aset tersedia dan siap dievaluasi oleh RBM

• Catatan Khusus: Modul RBM tidak mengubah struktur asset inti, hanya mengonsumsinya

🔹 UC-09: Akses Berbasis Peran (RBAC)

• Nama: Role-Based Access Control

• Aktor: Semua pengguna

• Deskripsi: Mengatur hak akses fitur berdasarkan peran pengguna.

• Trigger: User login dan mengakses modul RBM.

• Alur Utama:

  1. Sistem membaca role user

  2. Sistem menentukan akses ke:

     • Menu
     • Form input
     • Aksi (create/update/export)

  3. Sistem menampilkan UI sesuai peran

• Alur Alternatif:

  • User mencoba akses fitur terlarang → sistem menolak

• Kondisi Sukses: User hanya dapat mengakses fitur sesuai perannya

• Catatan Khusus: RBAC mengikuti kebijakan otorisasi mx-core

🔹 UC-10: Import dan Export Data CSV/XLS (Multi-Sheet, Dynamic Schema)

• Nama: Import dan Export Data CSV/XLS

• Aktor:

  • Planner
  • CMMS Admin
  • Inspector

• 🧾 Deskripsi:

Sistem menyediakan fitur untuk mengimpor dan mengekspor data RBM dalam format CSV dan XLS/XLSX, mencakup data konfigurasi aset, hasil grading, evaluasi kondisi, dan rencana pemeliharaan. File dapat terdiri dari banyak worksheet, dan setiap worksheet mewakili kategori aset berbeda dengan struktur kolom yang bervariasi.

Sistem akan melakukan pembacaan, validasi, preview, dan penyimpanan data dari worksheet ke dalam database relasional (SQL-type), menggunakan struktur flat table dan tagNumber sebagai ID unik.

• ⚡ Trigger:

User memilih menu Import atau Export pada halaman terkait (misalnya: Grading, Evaluation, Plan), atau dari halaman khusus Import-Export.

• 🔄 Alur Utama:

Untuk Export:

1. User membuka halaman Import/Export

2. User memilih jenis data yang akan diekspor (e.g. Grading, Evaluation, Maintenance Plan)

3. User memilih format file (CSV atau XLS)

4. Sistem memproses dan mengemas data ke dalam:

   • Beberapa worksheet (jika XLSX)
   • Beberapa file (jika CSV per kategori)

5. Sistem menghasilkan file download dan memberi notifikasi

Untuk Import:

1. User membuka halaman Import/Export

2. User mengunggah file (CSV atau XLSX)

3. Sistem membaca seluruh worksheet dan:

   • Mencocokkan struktur header berdasarkan asset_type
   • Memetakan kolom menjadi General dan Detail
   • Menampilkan preview data terstruktur per worksheet

4. Sistem melakukan validasi:

   • Format kolom sesuai template
   • tagNumber valid dan unik
   • Kolom general wajib ada

5. User memilih opsi simpan:

   • Per worksheet, atau
   • Semua sekaligus

6. Sistem menyimpan data ke DB dalam struktur flat berdasarkan asset type

• 🔁 Alur Alternatif:

• File tidak sesuai format → sistem tampilkan error validasi
• Terdapat worksheet kosong → sistem skip dan beri notifikasi
• Worksheet tidak dikenali → sistem minta mapping manual ke AssetType
• Terdapat tagNumber duplikat → sistem beri opsi: override, skip, atau merge
• File terlalu besar → sistem proses secara async, dengan progress bar

• ✅ Kondisi Sukses:

• File berhasil diimpor atau diekspor tanpa error
• Data tersimpan ke database per kategori aset (struktur flat)
• Notifikasi sukses diberikan per worksheet atau global
• Error log tersedia jika sebagian gagal

• 📝 Catatan Khusus:

• Sistem menyediakan template file per kategori aset untuk memudahkan user

• XLSX didukung multi-sheet, CSV didukung batch per kategori

• Setiap worksheet minimal harus punya kolom:

  • tagNumber (wajib, unik)
  • Kolom General (unit, lokasi, status, dll)

• Kolom Detail dapat bervariasi berdasarkan asset_type_schema

• Penyimpanan dilakukan ke tabel:

  • asset untuk kolom general
  • asset_detail_<kategori> untuk kolom detail

❓ Apa Itu MoSCoW?

MoSCoW adalah metode untuk mengelompokkan prioritas kebutuhan dalam pengembangan sistem, agar tim tahu mana fitur yang wajib ada sejak awal, mana yang bisa ditunda, dan mana yang bersifat opsional.

MoSCoW adalah akronim dari:

📋 Prioritas Pengembangan (MoSCoW) – mx-core-rbm

✅ Catatan:

• Fitur-fitur Must Have adalah scope minimum untuk versi MVP / rilis awal
• Fitur Should Have akan dikejar setelah Must selesai
• Fitur Could Have akan dikerjakan jika resource mencukupi
• Saat ini tidak ada fitur yang dikategorikan sebagai Won’t Have

📊 Traceability Matrix (Opsional)

Traceability Matrix digunakan untuk memetakan keterkaitan antar artefak SDLC — misalnya dari kebutuhan bisnis (BRS), ke fitur (FR), lalu ke use-case (UC), dan seterusnya ke test-case.

🔁 Traceability Matrix ini akan lebih kaya saat test-case sudah tersedia di tahap Testing (misalnya TC-01 menguji UC-01 yang berasal dari FR-01 dan BRS-01)

🧩 3. System Design – Bagian 1: High-Level Design (HLD)

📌 Tujuan: Menjabarkan struktur sistem secara modular, menggambarkan bagaimana komponen utama saling terhubung dan berinteraksi.

🔷 3.1.1 Diagram Arsitektur Sistem

Berikut adalah arsitektur konseptual tingkat tinggi dari plugin mx-core-rbm:

             +------------------------+
             |     User Interface     |
             | (Next.js + Tailwind UI)|
             +-----------+------------+
                         |
                         ▼
     +-------------------------+--------------------------+
     |                   RBM Application Layer           |
     |  (Routing, Pages, Controllers, Role Guarding)     |
     +-------------------------+--------------------------+
                         |
                         ▼
     +-------------------------+--------------------------+
     |     Business Logic / Services Layer                |
     |  - ESC Grading Engine                              |
     |  - Criticality Calculator                          |
     |  - Maintenance Strategy Mapper                     |
     |  - TBM Scheduler                                   |
     |  - Evaluation Recorder                             |
     +-------------------------+--------------------------+
                         |
                         ▼
     +------------------------+---------------------------+
     |     Data Access Layer (Models / Prisma)            |
     |  - Asset Domain Models                             |
     |  - RBM Domain Models                               |
     +------------------------+---------------------------+
                         |
                         ▼
             +----------------------------+
             |        PostgreSQL DB       |
             | (Schema: asset + rbm)      |
             +----------------------------+

                         ⇅
             +----------------------------+
             |     External Interfaces    |
             |     (Export CMMS, IoT*)    |
             +----------------------------+

🔷 3.1.2 Modul / Subsystem Overview

Plugin mx-core-rbm dibagi menjadi dua sub-domain logis, namun tetap dalam satu modul:

1. Asset Sub-Domain

Modul ini menyediakan data dasar aset, bersifat statis, struktural, dan tidak mengandung logika bisnis RBM.

• Asset
• AssetType
• AssetCategory
• AssetTypeSchema
• AssetDetail

2. RBM Sub-Domain

Modul yang menyimpan logika bisnis evaluasi, strategi, dan histori. Dinamis dan bergantung pada data dari Asset Sub-Domain.

• ESCGrading
• AssetCriticality
• MaintenancePlan
• TBMSchedule
• EvaluationRecord
• AssetTier (derived)

🔷 3.1.3 Komunikasi Antar Modul

Catatan: Komunikasi antar sub-domain tetap dilakukan melalui API internal atau shared services, tanpa memecah menjadi microservices.

🔷 3.1.4 External Interfaces

Integrasi dilakukan secara modular & terisolasi agar plugin tetap mandiri dalam mx-core.

🔷 3.1.5 Security & Auth Flow

🔷 3.1.6 Integrasi Internal & Eksternal

🔄 Internal Integration

• Plugin membaca data dari Asset Sub-Domain via shared Prisma models
• Tersedia API internal untuk halaman dashboard dan CMMS export
• Tidak terjadi duplikasi data antar plugin mx-core

🔗 External Integration

• Modul Export menghasilkan file JSON / CSV yang bisa diimpor oleh CMMS eksternal
• Data terstruktur berdasarkan tagNumber, criticality, dan schedule
• Terbuka untuk penambahan adapter REST / MQTT (jika dibutuhkan IoT link ke RBM)

🧩 3.2 Low-Level Design (LLD) – mx-core-rbm

🎯 LLD menyusun spesifikasi teknis yang lebih detail untuk setiap komponen sistem. Semua ini langsung berkaitan dengan FR dan Use Case yang sebelumnya sudah kita tetapkan.

🔹 1. Data Model

📌 a. Entity-Relationship Diagram (ERD)

ERD ini sudah dituliskan secara lengkap di dokumen konsep sebelumnya, dan kini diposisikan sebagai dasar database design untuk LLD:

      Asset (tag_number PK)
           │
           ├───► ESCGrading (FK)
           ├───► AssetCriticality (FK)
           ├───► AssetTier (FK)
           ├───► TBMSchedule (FK)
           ├───► MaintenancePlan (FK)
           └───► EvaluationRecord (FK)

Catatan: Semua entitas di domain RBM memiliki tag_number sebagai foreign key untuk referensi ke data aset.

📘 b. Data Dictionary

Contoh data dictionary untuk entitas utama:

Table: esc_grading

Table: maintenance_plan

(Data Dictionary lengkap bisa diturunkan lebih lanjut ke semua entitas model mx-core-rbm jika dibutuhkan.)

🔹 2. Algoritma / Flowchart

⚙️ a. ESC Grading to Criticality Rule (Inference Logic)

Deskripsi:

• Criticality otomatis ditentukan berdasarkan skor ESC.

Logika Sederhana (Ruleset):

function determineCriticality(esc: {
  environment: string;
  safety: string;
  continuous_running: string;
}) {
  const weights = {
    Low: 1,
    Medium: 2,
    High: 3,
  };

  const totalScore =
    weights[esc.environment] +
    weights[esc.safety] +
    weights[esc.continuous_running];

  return totalScore >= 7 ? 'Kritis' : 'Normal';
}

🎯 Bisa di-refactor sebagai service calculateCriticality() di folder services/criticality.ts

⚙️ b. Maintenance Plan Decision Logic

function mapToStrategy(criticality: string): 'P' | 'P+C' | 'P+P+C' {
  switch (criticality) {
    case 'Kritis':
      return 'P+P+C';
    case 'Normal':
    default:
      return 'P+C';
  }
}

🔹 3. Schema API (REST)

Plugin ini berbasis monorepo dan modular internal, tetapi tetap memungkinkan exposure API internal (Next.js App Router).

📌 a. Endpoint: POST /api/grading

• Deskripsi: Menyimpan grading ESC untuk sebuah aset

✅ Payload (JSON)

{
  "tagNumber": "PU-101",
  "environment": "High",
  "safety": "Medium",
  "continuous_running": "High",
  "gradedBy": "eng.rizki"
}

✅ Response

{
  "success": true,
  "message": "Grading berhasil disimpan",
  "criticality": "Kritis"
}

📌 b. Endpoint: GET /api/plan/:tagNumber

• Deskripsi: Mendapatkan strategi pemeliharaan untuk aset

✅ Response

{
  "tagNumber": "PU-101",
  "strategy": "P+P+C",
  "tier": "Tier1",
  "lastUpdated": "2025-12-12T09:30:00Z"
}

Catatan:

• Semua endpoint ditangani dengan middleware auth (JWT / session dari mx-core)
• Format JSON mengikuti konvensi snake_case atau camelCase konsisten (direkomendasikan camelCase)

🔹 4. Database Design

📌 a. Normalisasi

• Sudah diterapkan hingga 3NF:

  • Tidak ada data redundan
  • Kategori dan tipe aset dipisah dari data grading
  • Setiap evaluasi punya histori sendiri

📌 b. Indexing

📌 c. Partitioning (Opsional)

• EvaluationRecord dapat dipartisi berdasarkan evaluated_at bulanan atau tahunan jika jumlah data tinggi.
• Tidak diterapkan di awal, namun disiapkan desain skemanya.

🔹 5. Config & Parameter List

Konfigurasi ini bisa diletakkan di file .env atau config/rbm-config.ts agar mudah dimodifikasi dan di-maintain.

🧩 4. Implementation (Coding)

Mengubah dokumen teknis (LLD) menjadi implementasi kode sumber dalam bentuk plugin modular mx-core-rbm yang bisa dibuild, dijalankan, dan diuji.

🔹 I. Setup Repositori (Git)

📁 Struktur Repositori (mx-core)

Berikut adalah struktur direktori dari monorepo mx-core, dengan mx-core-rbm sebagai salah satu plugin-nya:

mx-core/
├── apps/
│   ├── web/               # frontend utama
│   └── api/               # backend utama
├── plugins/
│   └── mx-core-rbm/       # 🔍 plugin RBM (fokus kita)
│       ├── src/
│       │   ├── app/
│       │   ├── models/
│       │   ├── services/
│       │   ├── hooks/
│       │   ├── utils/
│       │   └── ...
│       ├── public/
│       ├── plugin.json
│       ├── next.config.js
│       ├── tsconfig.json
│       └── ...
├── package.json
└── turbo.json

🔧 Setup Git Branching

Contoh perintah:

git checkout -b feature/rbm-esc-grading

📦 Setup Tools & Dependency

Plugin mx-core-rbm menggunakan stack:

• Next.js (App Router)
• Tailwind CSS
• TypeScript
• Prisma (ORM)
• Zod (validasi input)
• React Hook Form untuk form grading/input

Perintah setup awal:

cd plugins/mx-core-rbm
npm install
npx prisma generate
npm run dev

🔹 Coding by Module / Sprint

📅 Sprint Planning (modular breakdown)

🎯 Setiap sprint diturunkan ke PR (Pull Request) dengan deskripsi:

• UC/FR yang diimplementasikan
• Screenshot UI (jika ada)
• Rujukan LLD (algoritma/API yang dipakai)

Memastikan setiap kode:

• Mengacu pada struktur model, field, dan relasi di ERD
• Mengimplementasikan algoritma sesuai logika RBM
• Memenuhi kontrak API endpoint yang didefinisikan
• Mengikuti struktur file/folder modular
• Konsisten dengan standar mx-core (Next.js App Router + TypeScript)

🔹 1. Implementasi Model Mengacu ERD

Model ditulis menggunakan Prisma ORM, mengacu langsung pada struktur LLD.

Contoh:

prisma/schema.prisma (sebagian RBM domain)

model ESCGrading {
  tagNumber          String   @id @map("tag_number")
  environment        ESCLevel
  safety             ESCLevel
  continuousRunning  ESCLevel @map("continuous_running")
  gradedBy           String   @map("graded_by")
  gradedAt           DateTime @map("graded_at")

  Asset              Asset    @relation(fields: [tagNumber], references: [tagNumber])
}

enum ESCLevel {
  Low
  Medium
  High
}

Implementasi TypeScript Model (untuk service layer):

// models/rbm/ESCGrading.ts
export interface ESCGrading {
  tagNumber: string;
  environment: 'Low' | 'Medium' | 'High';
  safety: 'Low' | 'Medium' | 'High';
  continuousRunning: 'Low' | 'Medium' | 'High';
  gradedBy: string;
  gradedAt: Date;
}

🔹 2. Implementasi Algoritma / Logic dari LLD

Sesuai dengan algoritma calculateCriticality() di LLD:

// services/criticality.ts
export function calculateCriticality(grading: {
  environment: string;
  safety: string;
  continuousRunning: string;
}): 'Kritis' | 'Normal' {
  const weights = {
    Low: 1,
    Medium: 2,
    High: 3,
  };
  const score =
    weights[grading.environment] +
    weights[grading.safety] +
    weights[grading.continuousRunning];

  return score >= 7 ? 'Kritis' : 'Normal';
}

🔁 Dipakai dalam controller saat user submit ESC grading untuk langsung menentukan criticality.

🔹 3. API Handler Sesuai Kontrak LLD

Contoh implementasi endpoint sesuai skema:

Endpoint: POST /api/grading

// app/api/grading/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { prisma } from '@/lib/prisma';
import { calculateCriticality } from '@/services/criticality';

export async function POST(req: NextRequest) {
  const data = await req.json();

  const criticality = calculateCriticality(data);

  await prisma.eSCGrading.upsert({
    where: { tagNumber: data.tagNumber },
    update: {
      ...data,
      criticality,
      gradedAt: new Date(),
    },
    create: {
      ...data,
      criticality,
      gradedAt: new Date(),
    },
  });

  return NextResponse.json({
    success: true,
    criticality,
  });
}

✅ Payload dan response sesuai dengan LLD API schema.

🔹 4. Struktur Folder & Modularisasi

Folder mengikuti pembagian sub-domain sesuai dengan desain sebelumnya:

mx-core-rbm/
├── src/
│   ├── app/
│   │   ├── grading/          # UC-01
│   │   ├── plan/             # UC-03
│   │   ├── schedule/         # UC-04
│   ├── models/
│   │   ├── asset/            # asset base models
│   │   └── rbm/              # RBM-specific models
│   ├── services/
│   │   ├── grading.ts
│   │   ├── criticality.ts
│   │   ├── plan.ts
│   ├── utils/
│   │   ├── score-utils.ts
│   └── ...

🔁 Service dan model dipisah berdasarkan fungsi agar mudah di-maintain dan di-test.

🔹 5. Validasi Input: Schema + Type Safety

Plugin mx-core-rbm menggunakan Zod untuk validasi input:

// schemas/gradingSchema.ts
import { z } from 'zod';

export const gradingSchema = z.object({
  tagNumber: z.string().min(1),
  environment: z.enum(['Low', 'Medium', 'High']),
  safety: z.enum(['Low', 'Medium', 'High']),
  continuousRunning: z.enum(['Low', 'Medium', 'High']),
  gradedBy: z.string().min(1),
});

Digunakan di API handler:

const parsed = gradingSchema.safeParse(data);
if (!parsed.success) {
  return NextResponse.json(
    { success: false, errors: parsed.error.format() },
    { status: 400 }
  );
}

🔹 1. Versioning & Dokumentasi

📦 a. Versioning (Penomoran Rilis)

Plugin mx-core-rbm mengikuti semver (Semantic Versioning) standar:

vX.Y.Z
└┬┘ └┬┘ └┬┘
 │   │   └── Patch → Fix kecil
 │   └───── Minor → Penambahan fitur backward-compatible
 └───────── Major → Breaking change besar

Contoh penomoran versi:

• v1.0.0-rbm → Rilis awal MVP RBM
• v1.1.0-rbm → Penambahan fitur dashboard dan export
• v1.1.1-rbm → Fix minor pada jadwal TBM
• v2.0.0-rbm → Perubahan struktur model grading (breaking)

🔧 b. Tagging Git + Release Notes

git tag -a v1.0.0-rbm -m "Initial release of mx-core-rbm plugin"
git push origin v1.0.0-rbm

📝 Release Notes dikelola di file: plugins/mx-core-rbm/docs/RELEASE-NOTES.md

Contoh isi:

> v1.0.0-rbm – 2025-12-20
> 🎯 Fitur:

- ESC Grading Form (UC-01)
- Criticality Logic (UC-02)
- Maintenance Plan Generator (UC-03)
- Basic TBM Scheduler (UC-04)
- Evaluation Record Form (UC-05)

🔐 Security:

- Role-based access control untuk semua halaman

📁 Struktur:

- Modular plugin dalam `plugins/mx-core-rbm`

🔹 2. Code Review & Integration Checklist

📋 a. Code Review Checklist

🧪 Catatan: Unit test akan lebih dikembangkan pada tahap Testing (SDLC 5)

🔗 b. Integration Checklist

🧩 5. Testing

📌 Tujuan: Validasi bahwa sistem mx-core-rbm bekerja sesuai dengan spesifikasi teknis (SRS) dan skenario nyata (use-case UC-01 s.d. UC-09).

✅ 1. Unit Test

Menguji logika kecil atau fungsi tunggal yang tidak bergantung pada modul lain.

✅ Ditulis di folder: __tests__/services/ dan __tests__/utils/

🔁 2. Integration Test

Menguji interaksi antar modul, seperti controller → service → database.

Test dilakukan dengan supertest / Next.js test utils atau Postman collection.

🔧 3. System Test (E2E)

Menguji alur lengkap dari perspektif pengguna. Tools: Playwright, Cypress, atau manual UAT.

Contoh Skenario:

🟩 UC-01 sampai UC-05 (grading → strategi):

1. User login sebagai Engineer
2. Pilih aset → isi ESC grading
3. Submit → sistem menilai criticality
4. Login sebagai Planner → buka halaman Maintenance Plan
5. Pilih strategi → sistem generate TBM schedule
6. Evaluasi tercatat → histori muncul

🟩 UC-06 (Dashboard):

• User membuka dashboard dan melihat jumlah Tier1 / Tier2 / Tier3
• Klik satu aset → tampil histori evaluasi

🟩 UC-07 (Export):

• IT mengakses /export → memilih tipe data → download file

👤 4. User Acceptance Test (UAT)

Melibatkan user dari PT PON (misalnya Reliability Engineer, Planner) untuk mencoba langsung sistem sesuai peran mereka.

✅ Hasil UAT akan menjadi dasar keputusan Go-Live / Release Approval

🧩 Dokumen Pengujian

📘 1. Test Plan

Test Plan adalah dokumen strategis untuk mengatur pendekatan, cakupan, peran, dan jadwal pengujian modul mx-core-rbm.

📄 Struktur Test Plan

🧪 2. Test Case (berbasis Use Case)

Masing-masing UC-01 sampai UC-09 dijabarkan ke dalam 1 atau lebih test case terstruktur.

📄 Format Test Case

Format ini bisa ditransfer ke Excel / Test Management System seperti TestRail.

🐞 3. Bug Log

Bug Log mencatat temuan selama pengujian dan status penyelesaiannya.

🔗 4. Traceability Matrix (Final)

Menghubungkan seluruh artefak dari BRS → FR → UC → TC.

🧩 6. Deployment – mx-core-rbm

📌 Tujuan: Meluncurkan plugin mx-core-rbm ke lingkungan produksi dengan proses terkontrol dan terdokumentasi.

🔹 Checklist Deployment

⚙️ 1. Build & CI/CD Pipeline

• Menggunakan Turborepo untuk membangun monorepo mx-core

• CI/CD via GitHub Actions atau GitLab CI

• Pipeline mencakup:

  • Lint & typecheck
  • Unit & integration test
  • Build plugin
  • Deploy ke environment staging/production

# .github/workflows/deploy.yml (contoh sederhana)
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npm install
      - run: npm run build
      - run: npm run test
      - run: bash ./scripts/deploy.sh

🌐 2. Environment Setup

• .env.local → untuk dev
• .env.staging → untuk staging
• .env.production → untuk prod

🛡️ 3. Backup & Rollback Plan

• Backup DB otomatis (PostgreSQL via cron/pg_dump)

• Snapshot konfigurasi .env, schema, dan plugin.json

• Rollback:

  • Revert ke tag Git: git checkout v1.0.0-rbm
  • Restore database backup
  • Trigger deploy ulang dari CI/CD

📄 4. Release Notes

• Disimpan di: plugins/mx-core-rbm/docs/RELEASE-NOTES.md

Contoh:

_v1.0.0-rbm – Production Release (2025-12-24)_

✅ Fitur:

- ESC Grading
- Asset Criticality
- Maintenance Strategy
- TBM Schedule
- Dashboard
- Export CMMS

🔒 RBAC aktif
🧪 Telah melalui UAT

📜 5. Deployment Log

Contoh entry log:

_Deployment Log - v1.0.0-rbm_

Date: 2025-12-24
By: DevOps Team

- Deploy sukses ke https://rbm.mx-core.io
- DB migrated via prisma migrate
- Release Notes attached
- No error in first 24h monitoring

✅ Output Deployment

🧩 7. Maintenance & Support – mx-core-rbm

📌 Menjaga keberlangsungan layanan plugin RBM dan menyiapkan peningkatan jangka panjang.

🔧 Aktivitas Maintenance

🖥️ 1. Monitoring Performance

• Tools: Logtail / Grafana / Vercel Analytics

• Parameter:

  • Load halaman grading & dashboard
  • Waktu respon API
  • Error rate (500, 403, dll)

🐞 2. Patch & Bug Fix

• Bug tracking via GitHub Issues / internal dashboard
• Patch dirilis via versi v1.x.x-rbm (patch semver)
• Hotfix langsung di-merge ke main dengan testing cepat

📣 3. User Feedback Loop

• Tim Planner dan Engineer memberikan masukan rutin

• Feedback dikumpulkan via:

  • Form internal
  • Group WA/Telegram
  • Review pasca shutdown/turnaround

🔄 4. Model Retraining (Jika AI Diterapkan)

• [Opsional untuk versi mendatang] jika RBM ditingkatkan dengan scoring berbasis AI
• Data histori dari EvaluationRecord dapat digunakan

🚀 5. Roadmap Feature Improvement

Contoh rencana jangka pendek:

📏 SLA & KPI Maintenance

✅ Output Maintenance & Support

🎯 Kesimpulan

✅ Proyek mx-core-rbm telah selesai dirancang dan diimplementasikan mengikuti struktur SDLC end-to-end, meliputi:

1. Business Needs (BRS)
2. Technical Specs (SRS)
3. Design (HLD & LLD)
4. Coding (modular, tested, documented)
5. Testing (Unit → UAT)
6. Deployment (CI/CD, backup, live)
7. Maintenance (Support & roadmap)

📌 Cocok digunakan untuk proyek dengan pendekatan structured (Waterfall) maupun iterative (Agile Hybrid)