Mengembangkan

Panduan untuk developer yang menambah modul baru, tabel baru, atau kolom baru ke lapisan database BigStarter.

A. Menambah Modul Baru (atau Memigrasi ke Query Contract)

Checklist lengkap — urutan ini yang dipakai semua modul official:

1. Inventarisasi — petakan semua titik akses data modul (.from(, .rpc() beserta konsumen lintas modul.
2. Tabel Drizzle — buat modules/<m>/server/db/tables.drizzle.ts dari DDL kanonik; daftarkan ke agregator infrastructure/db/schema.drizzle.ts. FK lintas modul = kolom polos (tanpa .references()); PK komposit & unique mengikuti nama constraint DDL.
3. Contract — tulis modules/<m>/server/queries/contract.ts dari semantik call-site (filter, urutan, matematika paginasi, guard soft-delete). Bentuk input/output netral-ORM.
4. Variant — implementasikan drizzle.ts (dan prisma.ts bila modul masuk program paritas) + binder zero-arg; konversi impl lama jadi supabase.ts (legacy) dengan binder.
5. Binding — queries/index.ts berisi tepat satu baris import binding (import { bindXQueries } from "./drizzle").
6. Konsumen — rewrite service/api/actions/jobs memakai singleton; serap straggler; pindahkan query browser ke oRPC.
7. RPC — bungkus fungsi SQL sebagai method contract bertipe di variant.
8. Hapus repository lama setelah nol importer (grep + typecheck).
9. Testing — test variant (import file variant langsung) + test service tetap mock di boundary @modules/<m>/server/queries.
10. Registrasi — modules/<m>/module.ts (manifest: tabel, contract, implementations, contributions) + daftarkan di tooling/modules/catalog.ts, lalu aktifkan rule arch untuk modules/<m>/server/(api|services)/.

B. Menambah Kolom

Tiga file wajib berubah bersama:

1. Migrasi SQL kanonik — tooling/supabase/migrations/<timestamp>_<name>.sql (alter table ... add column ...).
2. Mirror Drizzle — kolom di modules/<pemilik>/server/db/tables.drizzle.ts.
3. Mirror Prisma — field di model terkait (schema kontribusi modul, mis. tooling/templates/database/prisma/postgresql/<m>/prisma/<m>.prisma).

Lalu sesuaikan contract/variant yang mengekspos kolom itu, dan test-nya.

C. Testing per Variant

Drizzle — fake driver pg-proxy (tooling/test/helpers/fake-drizzle.ts):

import { createFakeDrizzle } from "@tooling/test/helpers/fake-drizzle";

const fake = createFakeDrizzle(() => [["row-1", ...]]); // rows = ARRAY posisional!
const queries = createDrizzleTaskQueries(fake.db as unknown as DrizzleDatabase);

Penting: baris hasil adalah array posisional mengikuti urutan kolom select — bukan objek bernama. Objek SQL Drizzle bersifat opak: asersi ditujukan pada pemetaan hasil, bukan teks SQL.

Billing (SQL mentah via execute) — harness { execute }:

const execute = jest.fn().mockResolvedValue({ rows: [...] });
const queries = createDrizzleBillingQueries({ execute } as never);

Prisma — mock delegat struktural ({ task: { findMany: jest.fn() } }), tanpa generated client.

Service — mock module boundary: jest.mock("@modules/<m>/server/queries", ...).

D. Aturan yang Dijaga Architecture Check

• modules/<m>/server/(api|services)/ modul yang sudah termigrasi: bebas dari import supabase & PostgREST chaining.
• modules/<m>/index.ts tidak boleh me-re-export ./server/ — melanggar batas browser.
• app/ dan zona web/ tidak boleh query langsung atau mengimpor repository internal modul lain.