# Tata Kelola Kontrak API & Permission (Governance)

Dokumen ini menjelaskan mekanisme tata kelola (*governance*), jaminan kontrak (*contract assurance*), dan penjaga desinkronisasi (*drift guard*) antara Backend Go dan Client Frontend di KeluargaMart Monorepo.

---

## 1. Latar Belakang Masalah (Pre-Migration Drift)

Pada arsitektur polyrepo sebelumnya:
- Tim backend memperbarui endpoint di Go router atau menambahkan permission baru di `catalog.go`.
- Frontend menduplikasi file teks secara manual (`backendRoutes.txt`, `backendPermissions.txt`).
- **Dampak Buruk**:
  - Saat audit pra-migrasi ditemukan bahwa `apps/erp` kehilangan permission `hr.leaves.store.any` yang sudah ada di backend.
  - Dokumentasi `openapi.yaml` berpotensi usang jika tidak ada tes otomatis yang memverifikasi sinkronisasi file kontrak.
  - Kesalahan ketik (*typo*) pada URL string di frontend baru terdeteksi saat runtime di production (HTTP 404).

---

## 2. Arsitektur Tata Kelola Kontrak

```mermaid
sequenceDiagram
    autonumber
    actor Dev as Backend Engineer
    participant Go as Go Backend (catalog.go / router)
    participant OpenAPI as apps/backend/docs/openapi.yaml
    participant Script as scripts/check-drift.py
    participant PkgContract as packages/contracts
    participant PkgPerm as packages/permissions
    participant CI as GitHub Actions CI

    Dev->>Go: Tambah endpoint baru & permission baru
    Dev->>OpenAPI: Update spesifikasi OpenAPI
    Dev->>PkgPerm: Tambahkan permission ke catalog & index.js
    Dev->>PkgContract: Tambahkan route ke routes.txt & routes.js
    Dev->>Script: Jalankan pnpm drift:check
    Script-->>Dev: PASS: 368 routes, 198 permissions synced!
    Dev->>CI: Push branch & Pull Request
    CI->>Script: Run pnpm drift:check
    alt Terjadi Drift / Desinkronisasi
        CI-->>Dev: ❌ Build Failure (Jelaskan route/permission yang mismatch)
    else Semua Sinkron
        CI-->>Dev: ✅ CI Passed
    end
```

---

## 3. Komponen Utama Governance

### A. Backend Route & Permissions Source of Truth
1. **Endpoint Rute**: `apps/backend/docs/openapi.yaml` mencatat 368 endpoint resmi.
2. **Permission RBAC**: `apps/backend/internal/modules/rbac/catalog.go` mencatat 198 konstanta permission resmi (misalnya `users.view`, `pos.orders.create`, `inventory.transfer.approve`).

### B. Workspace Packages
1. **`@keluargamart/contracts`**:
   - `src/routes.txt`: Daftar 368 canonical routes terurut abjad.
   - `src/routes.js`: Mengekspor array `BACKEND_ROUTES`, `Set` `BACKEND_ROUTE_SET`, dan validator `isValidRoute(path)`.
   - `src/routes.d.ts`: TypeScript definition untuk auto-complete IDE.
2. **`@keluargamart/permissions`**:
   - `src/permissions.txt`: Daftar 198 canonical permissions terurut abjad.
   - `src/index.js`: Object kamus `PERMISSIONS`, fungsi evaluasi `can(perms, perm, role)`, dan `isSuperAdmin(role)`.
   - `src/index.d.ts`: TypeScript definition lengkap.

### C. Automated Drift Guard (`scripts/check-drift.py`)
Script Python mandiri di `scripts/check-drift.py` memverifikasi tiga aspek:
1. Setiap route pada `openapi.yaml` harus terdapat di `packages/contracts/src/routes.txt` dan `routes.js`.
2. Setiap permission pada `catalog.go` harus terdapat di `packages/permissions/src/permissions.txt` dan `src/index.js`.
3. Menghitung exact count dan melaporkan perbedaan jika ada penambahan rute liar yang belum disepakati.

Eksekusi:
```bash
pnpm drift:check
```

Output sukses:
```text
============================================================
KeluargaMart Monorepo API & Permission Drift Guard
============================================================
[PASS] Routes count matches: 368 routes verified
[PASS] Packages contracts exports verified
[PASS] Permissions count matches: 198 permissions verified
[PASS] Packages permissions exports verified
[OK] ZERO DRIFT DETECTED across backend, contracts, and permissions!
```

---

## 4. Standar Penambahan Endpoint & Permission Baru

Jika seorang developer menambahkan modul atau fitur baru:

1. **Definisikan Route di Go**:
   Tambahkan handler pada `apps/backend/internal/modules/<module>/http.go`.
2. **Definisikan Permission di Go**:
   Tambahkan konstanta di `apps/backend/internal/modules/rbac/catalog.go`.
3. **Dokumentasikan di OpenAPI**:
   Tambahkan path & method di `apps/backend/docs/openapi.yaml`.
4. **Update Shared Packages**:
   - Tambahkan permission ke `packages/permissions/src/permissions.txt` dan `src/index.js`.
   - Tambahkan route ke `packages/contracts/src/routes.txt` dan `src/routes.js`.
5. **Verifikasi Drift**:
   Jalankan `pnpm drift:check`. Jika ada selisih, script akan langsung memberi tahu baris yang kurang.
6. **Konsumsi di Frontend**:
   Di ERP/POS/B2B, import konstanta dari `@keluargamart/contracts/routes` dan `@keluargamart/permissions`.