Panduan Pengembangan Backend (btb_backend)

Backend dibangun menggunakan .NET 8 (C#) dengan arsitektur Service-Repository Pattern.

Struktur Folder Proyek 

  btb_backend/
├── Controllers/          → 41 controller (routing HTTP)
├── Services/
│   ├── Interfaces/       → Kontrak/Interface service
│   └── Implementations/  → Implementasi logika bisnis
├── Repositories/
│   ├── Interfaces/       → Kontrak/Interface repository
│   └── Implementations/  → Implementasi akses data (Dapper)
├── DTOs/                 → Data Transfer Object (request/response)
├── Models/               → Entity/Model domain
├── Hubs/                 → SignalR Hub (real-time WebSocket)
├── Helpers/              → Utility & middleware pendukung
├── Program.cs            → Entry point, DI, middleware pipeline
├── JwtBlacklistMiddleware.cs → Middleware blacklist token JWT
├── appsettings.json      → Konfigurasi aplikasi
└── wwwroot/uploads/      → File statis (surat jalan, checksheet)

Lapisan Arsitektur

  1. Controllers (/Controllers): Menangani routing HTTP dan memanggil Service. Dilarang menaruh logika bisnis berat atau query database di sini.
  2. Services (/Services): Logika bisnis utama. Menerima data dari Controller, melakukan validasi/kalkulasi, dan memanggil Repository.
  3. Repositories (/Repositories): Lapisan akses data. Berkomunikasi dengan SQL Server menggunakan Dapper dan raw SqlCommand untuk memanggil Stored Procedure. (Catatan: Proyek ini TIDAK menggunakan Entity Framework Core.)
  4. DTOs (/DTOs): Kelas model untuk request dan response payload.
  5. Hubs (/Hubs): Endpoint SignalR (WebSocket) untuk fitur real-time.
  6. Helpers (/Helpers): Berisi utility penting:
    • ApiAuthHandler.cs — Autentikasi via header X-API-KEY untuk akses portal eksternal (Supplier).
    • EncryptionHelper.cs — Dekripsi AES-CBC kredensial login dari frontend.
    • JwtHelper.cs — Utilitas pembuatan dan validasi JWT.
    • SanitizerHelper.cs — Sanitasi input untuk keamanan.
    • HasPermissionRequirement.cs & RequiresPermissionAttribute.cs — Atribut otorisasi berbasis permission.

Skema Autentikasi Ganda (JWT + ApiKey)

Backend mendukung dua skema autentikasi yang didaftarkan di Program.cs:

  1. JWT Bearer (default): Untuk login pengguna biasa (Karyawan/Admin) via browser.
  2. ApiKey (X-API-KEY header): Untuk akses machine-to-machine atau portal Supplier eksternal tanpa perlu login JWT.

Notifikasi

Backend memiliki layanan notifikasi yang belum banyak didokumentasikan:

  • EmailService.cs: Mengirim email via SMTP (konfigurasi di appsettings.json bagian EmailSettings).
  • WhatsAppService.cs: Mengirim pesan WhatsApp untuk notifikasi ke pengguna.

SignalR Hubs (Real-time)

Terdapat 17 Hub yang terdaftar di Program.cs dan 1 hub yang belum di-map:

Hub Endpoint Fungsi
BookingHub /bookingHub Real-time booking kedatangan
OutstandingPOHub /outstandingPOHub Update PO outstanding
BarangImportHub /barangImportHub Notif barang import
BarangUrgentHub /barangUrgentHub Notif barang urgent
_5RSafetyHub /5rsHub Update 5R/Safety
AdjustmentHub /adjustmentHub Update adjustment stok
FileHub /fileHub Progress upload file
JenisNGHub /jenisNGHub Update jenis NG
KaryawanHub /karyawanHub Update data karyawan
KategoriBarangHub /kategoriBarangHub Update kategori barang
MSIsoHub /msIsoHub Update master ISO
NCRHub /ncrHub Update NCR
NgDashboardHub /ngDashboardHub Update NG dashboard
ScheduleTestingHub /scheduleTestingHub Update jadwal testing
SortirHub /sortirHub Update sortir
VehicleChecklistHub /vehicleChecklistHub Update checklist kendaraan
CheckInCheckOutHub /checkInCheckOutlistHub Update check-in/out
DNExportHub (belum di-map) (File ada tapi belum aktif)

Konfigurasi (appsettings.json) 

  {
  "ConnectionStrings": { "DefaultConnection": "..." },
  "Cors": { "AllowedOrigins": ["https://localhost:5173", "..."] },
  "Key": { "jwtIssuer": [...], "jwtAudience": "..." },
  "ApiKey": { "Key": "..." },
  "VendorApi": { "BaseUrlProd": "...", "BaseUrlDev": "..." },
  "EmailSettings": { "Host": "...", "Port": "...", "SenderEmail": "..." },
  "WhatsApp": { "..." }
}

Penting: Environment variable DECRYPT_KEY_JWT WAJIB diset sebelum menjalankan aplikasi. Jika tidak ada, aplikasi akan gagal startup.

Cara Menambahkan Fitur (Endpoint) Baru

  1. Buat Model DTO — Buat kelas request/response di folder DTOs/.
  2. Buat Interface Repository — Deklarasikan fungsi di Repositories/Interfaces/IXxxRepository.cs.
  3. Buat Implementasi Repository — Implementasikan query Dapper di Repositories/Implementations/XxxRepository.cs.
  4. Buat Interface Service — Deklarasikan logika bisnis di Services/Interfaces/IXxxService.cs.
  5. Buat Implementasi Service — Panggil repository di Services/Implementations/XxxService.cs.
  6. Buat Controller — Tambahkan route di Controllers/XxxController.cs.
  7. Daftarkan DI — Buka Program.cs dan tambahkan: 
      builder.Services.AddScoped<IXxxService, XxxService>();
builder.Services.AddScoped<IXxxRepository, XxxRepository>();

Daftar Lengkap 41 Controller (Modul API)

AdjustmentController, ApproveBtbController, AuthController, BarangController, BarangImportController, BarangUrgentController, BookingKedatanganController, CheckinCheckoutController, CompanyProfileController, CustClaimController, DNExportController, DashboardController, DojoInforController, FileController, GudangController, JenisNGController, KapasitasController, KaryawanController, KategoriBarangController, MSIsoController, MachineController, MasterStockController, MenuController, NCRController, NgDashboardController, OutstandingController, OutstandingFeedbackController, OutstandingMonitoringController, OutstandingPOController, PengirimanController, PermintaanPembelianController, QualityController, SafetyController, ScheduleTestingController, SortirController, SupplierController, SupplierOutsController, UploadMemoTarikController, VehicleChecklistController, VendorDevController, WhatsAppController.