Satu Kontrak, Dua Backend: Paritas Offline untuk Web dan Mobile

JID Carwash ERP berjalan di tiga permukaan: API NestJS 10 plus Prisma 5, POS dan panel admin Next.js 15, serta aplikasi lapangan Flutter 3.22 yang dibawa kru ke sekitar area cuci. Sejak awal saya menemui masalah yang membosankan tapi mahal. Pemilik ingin melihat POS di laptopnya saat rapat tanpa Wi-Fi. Rekan frontend saya ingin membangun layar payroll sebelum endpoint payroll ada. Dan saya ingin tes Flutter saya berjalan di CI tanpa menyalakan database Postgres. Ketiganya adalah masalah yang sama dengan topeng berbeda: UI seharusnya tidak peduli apakah backend nyata ada di ujung sana.

Solusinya adalah pola repository adapter yang diterapkan konsisten di kedua frontend. Setiap domain punya satu kontrak, dan dua implementasi yang dapat dipertukarkan berada di baliknya. Ini adalah abstraksi yang sama yang dipakai aplikasi Flutter clean-architecture untuk membuat lapisan domain tidak tahu-menahu soal sumber data, dan yang dipakai klien API TypeScript bertipe agar UI dikompilasi terhadap spesifikasi alih-alih endpoint langsung. Berikut persis cara kerjanya di basis kode yang sudah dikirim, termasuk jebakan yang membuat sebagian besar lapisan mock berbohong.

Satu kontrak, didefinisikan sekali

Semuanya dimulai dari satu berkas tipe. Ia mendeklarasikan bentuk setiap entitas dan metode yang harus disediakan setiap repository. Kontrak adalah hukum yang dipatuhi kedua implementasi, dan yang terpenting, ia menyandikan invarian domain langsung di dalam tipe. Uang adalah bilangan bulat IDR, bukan angka pecahan, sehingga field-nya berupa number biasa yang dinamai agar satuannya jelas. Setiap panggilan daftar dan detail menerima branchId, karena di sisi server setiap query Prisma dibatasi per cabang untuk mencegah satu cabang membaca order cabang lain.

// apps/pos-web/src/api/types.ts — the single contract both clients honor
export interface OrdersRepository {
  list(params: { branchId: string; status?: OrderStatus }): Promise<Order[]>;
  getById(branchId: string, orderId: string): Promise<Order>;
  create(input: CreateOrderInput): Promise<Order>;
  settle(
    orderId: string,
    payment: PaymentInput,
    idempotencyKey: string,
  ): Promise<Order>;
}

export interface Order {
  id: string;
  branchId: string;        // every read is scoped by this
  pelangganId: string | null;
  totalIdr: number;        // integer IDR — never a float
  status: OrderStatus;
}

Sisi Next.js: httpClient versus mockClient

Di web, kedua implementasi adalah objek biasa yang sama-sama memenuhi antarmuka OrdersRepository. Yang live membungkus klien HTTP kami dan memanggil rute NestJS. Yang mock membaca dari modul fixture di memori. Aturan yang saya tegakkan sejak hari pertama: mock harus mereproduksi perilaku yang dijamin API, bukan sekadar mengembalikan data. Jadi mock memfilter fixture berdasarkan branchId persis seperti server membatasi query-nya, dan metode settle-nya melakukan deduplikasi pada idempotency key persis seperti layanan settlement asli. Jika mock melewatkan itu, demo akan berperilaku berbeda dari produksi dan seluruh tujuannya runtuh.

// apps/pos-web/src/api/http/orders.http.ts — live implementation
export const httpOrders: OrdersRepository = {
  list: ({ branchId, status }) =>
    api.get(`/branches/${branchId}/orders`, { params: { status } }),
  settle: (orderId, payment, idempotencyKey) =>
    api.post(`/orders/${orderId}/settle`, payment, {
      headers: { "Idempotency-Key": idempotencyKey },
    }),
  // ...
};

// apps/pos-web/src/api/mock/orders.mock.ts — fixture implementation
export const mockOrders: OrdersRepository = {
  list: async ({ branchId, status }) =>
    fixtures.orders
      .filter((o) => o.branchId === branchId)   // same branch scope as the API
      .filter((o) => !status || o.status === status),
  settle: async (orderId, payment, idempotencyKey) =>
    settleInMemory(orderId, payment, idempotencyKey), // dedupes on the key, like prod
  // ...
};

Sisi Flutter: ApiRepository versus MockRepository

Aplikasi lapangan mencerminkan ide yang persis sama di Dart, hanya dengan alat yang sesuai bahasanya. Setiap fitur mendeklarasikan abstract interface class, lalu mengirim dua kelas konkret. ApiOrdersRepository yang live berbicara ke NestJS dan, ketika perangkat offline, mengantrekan tulisannya ke outbox yang dikuras connectivity_plus begitu sinyal kembali. MockOrdersRepository menyimpan fixture di memori dan menjalankan baik demo maupun widget test. Riverpod merangkai pilihan itu di level provider, sehingga tidak ada widget yang pernah mengimpor repository konkret secara langsung; semuanya memantau provider dan menerima implementasi mana pun yang dipilih konfigurasi.

// apps/field-app/lib/features/orders/data/orders_repository.dart
abstract interface class OrdersRepository {
  Future<List<Order>> list({required String branchId, OrderStatus? status});
  Future<Order> settle(String orderId, PaymentInput payment, String idempotencyKey);
}

// Live: talks to NestJS; queues writes in the outbox when offline
final class ApiOrdersRepository implements OrdersRepository { /* ... */ }

// Fixtures: powers demos and widget tests, no network at all
final class MockOrdersRepository implements OrdersRepository { /* ... */ }

final ordersRepositoryProvider = Provider<OrdersRepository>((ref) {
  return ref.watch(appConfigProvider).useMock
      ? MockOrdersRepository()
      : ApiOrdersRepository(ref.watch(httpClientProvider));
});

Ditukar oleh konfigurasi, bukan oleh kode

Pertukarannya adalah satu boolean, diselesaikan sekali di composition root. Di web ia berupa variabel lingkungan yang dibaca saat build; di Flutter ia berupa field pada provider konfigurasi aplikasi yang diatur dari build flavor. Setiap komponen dan setiap layar mengimpor nama netral, bukan varian http atau mock. Satu lapisan tak langsung itulah yang membuat semuanya tanpa rasa sakit: untuk menjalankan demo tanpa Wi-Fi saya mengatur flag ke mock dan UI yang persis sama berjalan terhadap fixture; untuk mengirim produksi saya biarkan live. Tidak ada yang berubah di kode fitur.

// apps/pos-web/src/api/index.ts — the composition root
const useMock = process.env.NEXT_PUBLIC_API_MODE === "mock";

export const orders: OrdersRepository = useMock ? mockOrders : httpOrders;
export const payments: PaymentsRepository = useMock ? mockPayments : httpPayments;

// Components import `orders` — never `httpOrders` or `mockOrders` directly.

Apa yang sebenarnya pola ini berikan

• Demo tanpa backend. Pemilik menjalankan POS lengkap di laptopnya saat rapat tanpa jaringan, mencatat order dan menyelesaikan pembayaran terhadap fixture yang tampak persis seperti hari kerja cabang sungguhan.
• Frontend yang tidak pernah menunggu. Layar payroll dan kasbon dibangun dan ditinjau berminggu-minggu sebelum endpoint itu ada, dikodekan langsung terhadap mock dan beralih ke live begitu API dikirim.
• Tes cepat dan deterministik. Widget test Flutter dan component test Next.js berjalan terhadap fixture di CI tanpa Postgres, tanpa kerapuhan jaringan, dan hasil identik pada setiap eksekusi.
• Sandbox onboarding yang aman. Kontributor baru mengklona repo, mengatur flag ke mock, dan mendapat ERP yang berfungsi dalam satu perintah tanpa rahasia atau akses database apa pun.

Api versus Mock sekilas

Pola ini tidak gratis. Anda memelihara implementasi kedua dari setiap repository, dan disiplin invarian di atas adalah pekerjaan nyata. Namun untuk produk dengan tiga permukaan yang berbagi satu domain, alternatifnya lebih buruk: UI yang terkopel ke backend langsung tidak bisa didemokan offline, tidak bisa dibangun mendahului API-nya, dan tidak bisa dites tanpa infrastruktur. Satu kontrak dan dua adapter membeli ketiganya, dan flag konfigurasi yang menukarnya adalah baris kode termurah di seluruh basis kode.