E-Plantation Service — RESTful API Backend untuk Sistem Manajemen Perkebunan

Overview

E-Plantation Service adalah layer backend dari sistem manajemen perkebunan terintegrasi. Dibangun dengan arsitektur berlapis (Controllers → Services → Repositories → Models), service ini menangani 40+ modul bisnis dengan 80+ entitas database PostgreSQL. Mendukung workflow approval multi-level, generate dokumen PDF/Excel, autentikasi JWT berbasis role, serta dilengkapi tracing, logging terstruktur, dan health check untuk keperluan production observability.

Key Features

• Auth & RBAC — JWT authentication dengan role-based access control per module
• Master Data — Organisasi, divisi, blok, karyawan, sub-aktivitat
• Operasi Panen — CRUD SPB (Surat Pengantar Buah), tonase kebun, tonase PKS
• Perencanaan Kerja — RKT (tahunan), RKB (bulanan), RKH (harian)
• Pemeliharaan — Pemupukan, perawatan item, checkup
• Keuangan — Budgeting, cost tracking, perpajakan
• Approval Matrix — Multi-level approval dengan audit trail dan email notifikasi
• Generate Dokumen — PDF A5 SPB dengan branding organisasi, export Excel
• Dashboard & Laporan — Analytics BJR, budget vs realisasi, performance report
• Strategy Pattern — PerformanceReportService dengan kalkulasi dinamis (BJR, AKP, Yield)
• Observability — Request ID tracking, distributed tracing, health check liveness/readiness
• Monitoring — Prometheus metrics, Grafana dashboards, Loki log aggregation

Challenges

• Kompleksitas domain bisnis — Ratusan aturan kalkulasi perkebunan (BJR, AKP, yield, tonase) yang harus akurat dan konsisten lintas modul
• Approval workflow yang fleksibel — Setiap organisasi punya level approval berbeda; harus bisa dikonfigurasi tanpa hardcode
• Performance pada query kompleks — Join antar 80+ tabel dengan filter dinamis (organisasi, divisi, blok, periode) berpotensi lambat
• PDF generation yang konsisten — Template A5 SPB harus akurat secara layout di berbagai konten, termasuk branding per organisasi
• Observability di production — Butuh korelasi antara log, trace, dan metrics dari request yang sama tanpa overhead signifikan
• Data migration bertahap — Migrasi schema database ke production tanpa downtime dengan SQL migration files manual

Solutions

• Strategy Pattern pada PerformanceReportService — setiap jenis kalkulasi (BJR, Yield, dll) dienkapsulasi sebagai strategi independen yang bisa di-swap
• Approval Matrix engine — konfigurasi level approval disimpan di database, service membaca dinamis berdasarkan role & organisasi
• Database indexing (common-indexes.sql) + Materialized Views untuk query dashboard berat
• Custom PDF mapper (SuratJalanMapper.ts) yang menormalisasi data sebelum render ke template PDFKit
• OpenTelemetry + Request ID middleware — setiap request mendapat UUID yang mengalir ke log Winston dan trace Jaeger
• SQL migration files versioned (sql/) untuk DDL changes yang bisa di-review sebelum dieksekusi

Lessons Learned

• Pisahkan kalkulasi bisnis dari controller — menempatkan logika kalkulasi kompleks di service layer + strategy pattern jauh lebih mudah di-test dan di-maintain
• Structured logging dari awal — log tanpa correlation ID membuat debugging production nightmare; lebih baik setup Winston + requestId middleware di hari pertama
• TypeORM relations perlu hati-hati — lazy loading vs eager loading di entitas yang saling berelasi bisa menyebabkan N+1 query yang tidak disadari
• Migration manual lebih aman untuk data sensitif — auto-migration TypeORM di production terlalu berisiko; SQL files yang di-review manual lebih terkontrol
• Approval workflow butuh state machine yang jelas — tanpa mendefinisikan status transitions secara eksplisit, edge case approval/rejection mudah lolos