# Alur Kerja Penambahan & Perubahan API (API Workflow)

Dokumen ini memandu pengembang langkah demi langkah ketika menambahkan endpoint baru, memperbarui parameter API, atau menambahkan hak akses (permission) baru di KeluargaMart Monorepo.

---

## 1. Diagram Alur Kerja

```text
[1. Buat Handler Go] ──> [2. Tambah Permission di catalog.go] ──> [3. Update openapi.yaml]
                                                                          │
[6. Konsumsi di Frontend] <── [5. Validasi pnpm drift:check] <── [4. Update Shared Packages]
          │
[7. Jalankan Test Suite & Buat Pull Request]
```

---

## 2. Langkah-Langkah Detail

### Langkah 1: Implementasikan Handler & Router di Go Backend
Buat HTTP handler di modul terkait pada `apps/backend/internal/modules/<nama_modul>/`:
```go
// apps/backend/internal/modules/inventory/http.go
r.Route("/stock-audits", func(r chi.Router) {
    r.Use(rbac.RequirePermission(rbac.PermInventoryStockAuditCreate))
    r.Post("/", h.CreateStockAudit)
})
```

### Langkah 2: Tambahkan Konstanta Permission di RBAC Catalog
Jika endpoint membutuhkan hak akses baru, daftarkan permission tersebut di `apps/backend/internal/modules/rbac/catalog.go`:
```go
const (
    PermInventoryStockAuditCreate = "inventory.stock_audit.create"
)

// Daftarkan ke dalam slice AllPermissions
var AllPermissions = []string{
    // ...
    PermInventoryStockAuditCreate,
}
```

### Langkah 3: Dokumentasikan Endpoint pada OpenAPI Spec
Perbarui dokumen OpenAPI di `apps/backend/docs/openapi.yaml`:
```yaml
paths:
  /api/v1/inventory/stock-audits:
    post:
      summary: Create new stock audit
      security:
        - BearerAuth: []
      tags:
        - Inventory
      responses:
        '201':
          description: Stock audit created successfully
```

### Langkah 4: Perbarui Shared Packages
Untuk memastikan frontend memiliki type dan konstanta sinkron:

1. **Tambahkan Permission ke `@keluargamart/permissions`**:
   - Tambahkan baris baru di `packages/permissions/src/permissions.txt`:
     ```text
     inventory.stock_audit.create
     ```
   - Tambahkan konstanta pada object `PERMISSIONS` di `packages/permissions/src/index.js` dan file deklarasi `index.d.ts`.

2. **Tambahkan Rute ke `@keluargamart/contracts`**:
   - Tambahkan baris baru di `packages/contracts/src/routes.txt`:
     ```text
     POST /api/v1/inventory/stock-audits
     ```
   - Tambahkan string tersebut ke array `BACKEND_ROUTES` di `packages/contracts/src/routes.js` dan file deklarasi `routes.d.ts`.

### Langkah 5: Jalankan Drift Guard
Verifikasi bahwa seluruh kontrak telah sinkron 100%:
```bash
pnpm drift:check
```
Jika Anda melewatkan salah satu rute atau permission, script akan menampilkan selisih dan menghentikan proses sebelum mencapai CI.

### Langkah 6: Gunakan di Aplikasi Frontend
Konsumsi rute dan permission yang baru ditambahkan di dalam modul ERP atau POS:
```javascript
import { BACKEND_ROUTES } from '@keluargamart/contracts/routes';
import { PERMISSIONS, can } from '@keluargamart/permissions';

// Cek permission
if (can(currentUser.permissions, PERMISSIONS.INVENTORY_STOCK_AUDIT_CREATE)) {
  // Panggil API
  await apiClient.post('/api/v1/inventory/stock-audits', payload);
}
```

### Langkah 7: Pengujian & Verifikasi
Pastikan semua tes lulus:
```bash
pnpm test:backend
pnpm test
pnpm build
```
Commit perubahan dan ajukan Pull Request.