Membangun POS + ERP Mobile untuk UKM Cuci Mobil Indonesia

Klien menjalankan jaringan kecil cabang cuci mobil di seputar kota. Sebelum proyek ini mereka bergantung pada struk kertas, grup WhatsApp yang ramai, dan satu spreadsheet bersama yang tidak dipercaya siapa pun di akhir bulan. Kas hilang, hitungan stok tidak pernah cocok, dan pemilik tidak bisa tahu cabang mana yang benar-benar untung. Ringkasannya mudah diucapkan tapi sulit dibangun: satu sistem, tiga tempat pemakaian yang sangat berbeda.

Saya membangunnya sebagai monorepo dengan tiga permukaan yang dapat dideploy dan berbagi satu pemahaman tentang domain. Kasir mendapat POS desktop yang cepat. Pemilik mendapat konsol admin dengan laporan. Kru cuci mendapat aplikasi ponsel atau tablet yang tetap berjalan saat wifi di area cuci putus, yang sering terjadi. Tulisan ini adalah gambaran produk dan rekayasa: permukaannya, kendala yang membentuknya, dan sejumlah kecil invarian yang saya tolak untuk dilanggar.

Satu bisnis, tiga permukaan, satu kontrak

Ketiga aplikasi terlihat sangat berbeda, tetapi semuanya berbicara ke model domain yang sama. Di sisi API, setiap area bisnis mendapat modulnya sendiri — order, pembayaran, sesi kas, inventori, penggajian, pelanggan, kendaraan, cabang, dan lainnya. Di sisi klien, baik POS web maupun aplikasi Flutter menyembunyikan jaringan di balik klien live dan klien mock yang berbagi satu kontrak bertipe, sehingga saya bisa mengembangkan dan mendemokan permukaan mana pun tanpa server berjalan.

• apps/api — NestJS 10 dengan Prisma 5 di atas PostgreSQL. Satu modul per domain, satu skema Prisma sebagai sumber kebenaran tunggal untuk bentuk dan migrasi.
• apps/pos-web — Next.js 15 App Router. POS kasir plus konsol admin pemilik, dengan akses API di balik httpClient asli dan mockClient tiruan yang berbagi satu kontrak types.ts.
• apps/field-app — Flutter 3.22 di Dart 3.4, memakai Riverpod dan go_router. Setiap fitur menyertakan repository Api untuk penggunaan live dan repository Mock untuk mode offline dan demo.

Kendala yang benar-benar membentuk pembangunan

Hampir setiap keputusan yang tidak jelas berakar pada kendala dunia nyata, bukan preferensi teknis. Ini UKM Indonesia, bukan startup SaaS, dan toko fisiknya jauh lebih menentukan perangkat lunak daripada framework mana pun.

• Area cuci offline. Area cuci basah, penuh logam, dan jauh dari router. Wifi putus selama beberapa menit, jadi aplikasi lapangan harus menganggap tanpa koneksi sebagai kondisi bawaan, bukan pengecualian.
• Padat kas. Sebagian besar pelanggan membayar tunai. Setiap sif membuka dan menutup sesi kas, dan rekonsiliasi harian adalah laporan yang paling dipedulikan pemilik.
• Kasbon. Staf rutin meminta uang muka atas gaji mereka. Itu adalah hutang nyata, dilacak dalam modulnya sendiri dan dipotong saat penggajian.
• Multi-cabang. Beberapa cabang berbagi satu basis data dan satu pemilik, tetapi kasir di satu cabang tidak boleh melihat atau menyentuh order, kas, atau stok cabang lain.

Uang adalah bilangan bulat, dan buku kas adalah ilusi

Dua aturan data bekerja lebih keras daripada apa pun di sistem ini. Pertama, uang selalu bilangan bulat rupiah — tidak pernah float. Rupiah tidak punya sub-unit dalam pemakaian sehari-hari, jadi harga hanyalah bilangan bulat, dan aritmetika floating point tidak punya tempat di dekatnya. Kedua, buku kas yang dibaca pemilik tiap malam sama sekali bukan tabel tersimpan. Itu adalah tampilan gabungan turunan yang dihitung sesuai permintaan dari peristiwa yang benar-benar menggerakkan kas: pembayaran masuk, kasbon keluar, pembelian keluar. Tidak ada yang menulis baris ke buku besar, karena buku besar adalah proyeksi, bukan sumber.

// CashLedgerEntry is NEVER a table. It is a DERIVED union view.
// The source of truth is the domain events that actually moved cash.
const ledger = [
  ...payments.map(p  => ({ ts: p.paidAt,   type: 'IN',  amountIdr: p.amountIdr })),
  ...kasbons.map(k   => ({ ts: k.issuedAt, type: 'OUT', amountIdr: k.amountIdr })),
  ...purchases.map(x => ({ ts: x.paidAt,   type: 'OUT', amountIdr: x.totalIdr })),
].sort((a, b) => a.ts.getTime() - b.ts.getTime());

// Product.stockQty is only a cache. The truth is the movement sum:
//   SELECT SUM(qty_delta) FROM stock_movement WHERE product_id = $1;

Setiap kueri dibatasi per cabang (perbaikan IDOR)

Di awal, sebuah endpoint detail order menerima id dan mengembalikan order tanpa filter cabang. Saat pengujian saya membuka order cabang lain hanya dengan menebak id berurutan — kasus klasik insecure direct object reference. Perbaikannya menjadi aturan keras untuk seluruh basis kode: setiap kueri daftar dan detail dibatasi oleh branchId yang diambil dari sesi terautentikasi, tidak pernah dari apa pun yang bisa dikirim klien. Jika baris itu bukan milik cabang Anda, baris itu sama saja tidak ada bagi sesi Anda.

// Every list/detail query is scoped by branchId from the SESSION,
// never from the request body or params.
async findOrder(orderId: string, session: Session) {
  return this.prisma.order.findFirst({
    where: { id: orderId, branchId: session.branchId },
  });
}

// The IDOR that forced the rule: GET /orders/:id with no branch filter
// let a cashier at branch A open branch B's order by guessing the id.

Area cuci offline dan outbox

Aplikasi lapangan tidak pernah menghambat kru karena jaringan. Setiap penulisan — memulai cuci, menandai selesai, menerima pembayaran tunai — masuk ke outbox lokal terlebih dahulu dan langsung kembali. Sebuah listener konektivitas memantau tautan, dan saat kembali, outbox dikuras berurutan ke API live. Karena setiap fitur punya repository Api dan repository Mock di balik antarmuka yang sama, mode offline dan mode demo adalah jalur kode yang sama, yang membuat semuanya dapat diuji tanpa pernah menyentuh router.

// field-app: every write hits a local outbox first, then drains when online.
final repo = online ? ApiOrderRepository(dio) : MockOrderRepository();
await outbox.enqueue(CreateOrderOp(payload));

Connectivity().onConnectivityChanged.listen((status) {
  if (status != ConnectivityResult.none) {
    outbox.drain(); // replay queued ops in order against the live API
  }
});

Penyelesaian idempoten dan log audit hanya-tambah

Pembayaran adalah tempat percobaan ulang offline menjadi berbahaya. Kasir di wifi tidak stabil menekan selesaikan, permintaan timeout, mereka menekan lagi — dan tanpa proteksi itu adalah pembebanan ganda. Karena itu penyelesaian membutuhkan kunci idempotensi: klien menghasilkan satu per percobaan penyelesaian, dan server mengembalikan hasil sebelumnya jika sudah pernah melihat kunci itu. Percobaan ulang aman secara desain. Di sampingnya, log audit bersifat hanya-tambah dan menyunting data pribadi saat penulisan, sehingga selalu ada catatan jujur tentang siapa melakukan apa, tanpa membocorkan nomor telepon pelanggan ke log.

// settlement.service.ts — client sends an Idempotency-Key on settle.
const existing = await this.prisma.settlement.findUnique({
  where: { idempotencyKey: key },
});
if (existing) return existing; // safe retry: return the prior result

return this.prisma.settlement.create({
  data: { paymentId, idempotencyKey: key, amountIdr, settledAt: new Date() },
});

Pilihan tumpukan dan alasannya

Tidak satu pun pilihan ini eksotis, dan itulah intinya. Untuk bisnis kecil, risikonya bukan framework — melainkan pemodelan domain. Benarkan uang bilangan bulat, buku besar turunan, pembatasan cabang, dan penulisan idempoten, dan sisanya adalah CRUD biasa yang bisa dirilis cepat. Salah menanganinya dan sebanyak apa pun poles framework tidak akan membuat pemilik mempercayai angkanya.