Arsitektur & pengujian
Temukan pemilik setiap perubahan, pertahankan kontrak keamanan serta pembukuan, dan jalankan pemeriksaan yang sesuai sebelum mengirim perubahan.
Unduh OpenAPI 3.1Di halaman ini
Ikuti aliran yang sudah ada
Client component + SWR
→ api() / usePing() / useOrder()
→ app/api/** + apiHandler + requireUser
→ domain lib/orders, lib/wallet, lib/payments
→ database / provider adapter
→ DTO + { ok, data }
→ revalidasi cache penggunaRoute handler tipis memvalidasi input dan sesi. Aturan bisnis berada di domain, akses provider di adapter. Tidak boleh ada jalur pembelian provider langsung dari komponen, saldo paralel, atau mock auth untuk mempermudah pengembangan.
Ubah di modul yang benar
| Perubahan | Sumber kebenaran | Pengujian terkait |
|---|---|---|
| Kontrak HTTP / error | app/api/** dan lib/api/handler.ts | tests/phase3-api.test.ts |
| DTO / fetch / polling | lib/ping/types.ts, mappers.ts, client.ts, payments.ts | tests/phase3-client.test.ts |
| Order / lifecycle | lib/orders/state-machine.ts, service.ts, lifecycle.ts | tests/order-state-machine.test.ts, order-service.test.ts |
| Pergerakan uang order | lib/orders/settlement.ts → lib/wallet/ledger.ts | tests/order-service.test.ts, wallet-ledger.test.ts |
| Pembayaran | lib/payments/service.ts dan provider KlikQRIS | tests/payments.test.ts, klikqris-client.test.ts |
| Database | lib/db/schema.ts → migrasi di drizzle/ | Tes domain yang menyentuh tabel terkait |
| Dokumentasi API | lib/docs/developer-api.ts, api-schemas.ts, api-examples.ts | tests/developer-docs.test.ts, documentation.test.ts |
Invariant yang tidak boleh dipotong
- Saldo hanya berubah lewat ledger append-only. Order memindahkan dana lewat settlement; jangan mengubah wallets langsung dari route atau UI.
- Status order berubah melalui state machine. Status terminal tidak dibangkitkan kembali. Transisi dan settlement harus tetap terkoordinasi.
- Setiap pembacaan resource pengguna dibatasi userId di query. Jangan mengambil semua data lalu memfilter setelahnya.
- Jangan menahan transaksi database selama HTTP ke provider. Pertahankan lease, revisi, idempotency, dan penanganan hasil ambigu.
- Client state lintas komponen memakai SWR dan cache per pengguna. Akun keluar/berganti tidak boleh melihat cache akun sebelumnya.
- Provider secret, password, cookie, dan OTP bukan bahan log. Error publik harus tetap disanitasi.
Jalankan kontrak, bukan transaksi produksi
pnpm exec next typegen
pnpm typecheck
pnpm test
pnpm buildVitest memakai PGlite in-memory dan HTTP provider yang di-mock, sehingga tidak membeli nomor nyata. CI juga melakukan production build dengan database yang sengaja tidak tersedia agar prerender tidak menyentuh database.
Untuk perubahan schema, buat dan tinjau migrasi dengan pnpm db:generate, lalu uji pada database terpisah sebelum menerapkannya. PGlite file hanya boleh dimiliki satu proses; jangan menjalankan script migrasi pada direktori yang sedang dibuka server.
Saat menambah endpoint atau field, perbarui route, DTO/client, contoh docs, schema OpenAPI, dan tes yang terkait dalam perubahan yang sama. Halaman docs memeriksa bentuk kontrak, tetapi bukan pengganti tes domain atau audit keamanan.
Review tampilan secara terpisah
/preview memakai komponen produksi dengan transport demo terisolasi. Cocok untuk layout, state kosong, dan navigasi; tidak membuktikan autentikasi, saldo, provider, atau pembayaran nyata. /developers dapat dibaca tanpa login dan tidak menjalankan request contoh.