Developer Handbook

Panduan Developer MYCUSTOMER

Dokumentasi onboarding untuk memahami arsitektur, alur data, aturan domain, dan cara aman mengembangkan fitur baru.

Mulai dari sini

Setup environment lokal dan Google Sheets dijelaskan di README.md. Setelah project berjalan, gunakan halaman ini sebagai referensi saat membaca atau mengubah codebase.

Struktur

Lokasi source dan tanggung jawabnya

Data flow

Cara data bergerak melalui API

Guardrails

Aturan keamanan yang wajib dipertahankan

1. Gambaran arsitektur

MYCUSTOMER adalah aplikasi Next.js App Router. UI client memanggil API route internal, lalu API route membaca atau menulis Google Sheets menggunakan service account di server. Credential Google tidak boleh masuk ke browser.

Client UI

Halaman React dan komponen interaktif.

API layer

Session, authorization, validasi, dan transformasi.

Google Sheets

Datastore untuk users, customers, orders, dan settings.

Client Component
  -> src/services/*
  -> /api/*
  -> authenticatedUser()
  -> Google Sheets API

2. Peta folder

src/app/(app)Halaman aplikasi yang membutuhkan session.

src/app/apiRoute backend untuk auth, customer, order, dan Google Sheets.

src/servicesService client untuk memanggil API dan memetakan data domain.

src/libSession server, auth helper, provider, rate limit, dan utilitas infra.

src/utilsPure utility seperti normalisasi nomor dan status retensi.

src/typesTypeScript types untuk customer, order, session, dan user.

src/components/uiPrimitive UI berbasis shadcn/Base UI.

supabase/migrationsTidak digunakan sebagai datastore utama project ini.

3. Alur data utama

Input order

Halaman input mencari atau resolve customer, menormalisasi nomor, lalu membuat order melalui /api/orders.

Customer

Data customer dan order dibaca melalui service. Status retensi dihitung di client dari tanggal order terakhir dan settings.

Follow-up

Daftar customer berisiko difilter dari data branch yang diizinkan. Pengiriman WhatsApp tetap manual melalui wa.me.

Settings

Settings aplikasi dibaca dari Google Sheets dan disinkronkan ke provider/settings service.

4. API dan authorization

Route terproteksi wajib memanggil helper auth server-side. Jangan menganggap hidden menu atau role dari localStorage sebagai kontrol keamanan.

Auth/api/auth/login, /api/auth/logout, /api/auth/me

Customer/api/customers/resolve, /api/customers/update, /api/customers/follow-up

Order/api/orders, /api/orders/follow-up, /api/orders/recalculate

Sheets/api/sheets dan route append/update/delete/import

Admin/api/admin/backfill-branch-memberships

const auth = await authenticatedUser(["owner", "admin"])
if (auth.error) return auth.error

// Untuk data branch, selalu gunakan auth.user.branch
// Jangan percaya branch dari request body tanpa verifikasi.

5. Aturan domain yang wajib

Nomor WhatsApp

Selalu panggil normalizePhone() sebelum menyimpan, query, deduplikasi, atau matching.

Status retensi

Rule-based dari recency dan threshold settings. Jangan menambahkan ML/DL tanpa keputusan produk baru.

Google Sheets writes

Gunakan RAW, bukan USER_ENTERED, dan cegah formula injection pada input user.

Follow-up

Hanya buat link wa.me manual. Jangan menambahkan API pengiriman WhatsApp otomatis.

6. Checklist membuat fitur baru

1Cari service, utility, dan komponen yang sudah ada sebelum membuat helper baru.
2Tentukan apakah route membutuhkan session, role, dan branch scope.
3Validasi input di server; validasi client hanya untuk UX.
4Batasi query list dengan pagination atau limit.
5Pastikan response tidak mengembalikan PII atau error backend yang tidak diperlukan.
6Tambahkan state loading, error, dan empty state pada UI.
7Jalankan npm run typecheck dan git diff --check sebelum handoff.

7. Testing dan validasi

Utility murni seperti normalisasi nomor, churn status, vCard, dan wa.me link harus mudah diuji tanpa side effect.

npm run typecheck
git diff --check
npm run build

8. Catatan keamanan

Data customer berisi PII. Jangan mencetak nomor WhatsApp atau credential ke log. Export/import wajib dibatasi server-side untuk role admin, dan setiap perubahan schema harus dicatat dalam decision log project.

9. Git workflow

Buat perubahan kecil dan terfokus, jangan mereset perubahan user lain, dan jangan commit secret. Gunakan commit message yang menjelaskan perubahan perilaku, lalu sertakan hasil typecheck pada handoff.

README adalah panduan setup operator. Halaman ini adalah referensi engineer dan harus diperbarui jika arsitektur atau guardrail berubah.