# CI/CD & Deployment Runbook

Dokumen ini menjelaskan pipeline otomatisasi Continuous Integration & Continuous Delivery (CI/CD) serta panduan rollback untuk KeluargaMart Monorepo.

---

## 1. Arsitektur Pipeline CI/CD

Pipeline CI/CD monorepo dikonfigurasi menggunakan **GitHub Actions** dengan dua alur kerja utama:

```mermaid
flowchart TD
    subgraph Trigger["Git Event Trigger"]
        PR["Pull Request / Push"]
        Release["Git Tag v*.*.* / Push to main"]
    end

    subgraph CI["Workflow: .github/workflows/ci.yml"]
        DG["1. Drift Guard<br/>(scripts/check-drift.py)"]
        BE["2. Go Backend CI<br/>(test & build binary)"]
        FE["3. Frontend & Packages CI<br/>(turbo lint, test, build)"]
    end

    subgraph CD["Workflow: .github/workflows/deploy-ghcr.yml"]
        Matrix["Build Matrix:<br/>- backend<br/>- erp<br/>- pos<br/>- b2b<br/>- nextreport"]
        GHCR["Push Images to GHCR<br/>(ghcr.io/keluargamart/*)"]
        Deploy["Trigger Webhook / Deploy to VPS"]
    end

    PR --> CI
    DG --> BE
    DG --> FE

    Release --> CD
    Matrix --> GHCR --> Deploy
```

---

## 2. Alur Kerja Continuous Integration (`ci.yml`)

Dijalankan secara otomatis pada setiap **Push ke branch `main`** dan pada setiap **Pull Request**:

### Job 1: `drift-guard` (Penjaga Desinkronisasi Kontrak)
- Memeriksa keselarasan antara `apps/backend/docs/openapi.yaml`, `catalog.go`, `@keluargamart/contracts`, dan `@keluargamart/permissions`.
- Mencegah PR di-merge jika terdapat rute API atau permission yang tidak sinkron.

### Job 2: `backend-ci` (Pengujian Backend Go)
- Menjalankan `go test -v -race ./...` di dalam `apps/backend`.
- Mengompilasi binary `go build -o bin/server ./cmd/server` untuk memvalidasi buildability.

### Job 3: `frontend-ci` (Pengujian Frontend & Packages)
- Menyiapkan environment Node.js 22 & pnpm v12 dengan dependency cache.
- Menjalankan `pnpm turbo run lint` untuk static analysis.
- Menjalankan `pnpm turbo run test` (80 test files, 625+ unit tests).
- Menjalankan `pnpm turbo run build` untuk memverifikasi tidak ada error kompilasi Vite/Nuxt.

---

## 3. Alur Kerja Continuous Delivery (`deploy-ghcr.yml`)

Dijalankan ketika commit masuk ke `main` atau tag rilis (`v*`):
- Menggunakan **Matrix Strategy** untuk membangun 5 container image secara paralel:
  - `ghcr.io/<org>/km-backend`
  - `ghcr.io/<org>/km-erp`
  - `ghcr.io/<org>/km-pos`
  - `ghcr.io/<org>/km-b2b`
  - `ghcr.io/<org>/km-nextreport`
- Menggunakan cache Docker layer (`type=gha`) untuk mempercepat build time hingga di bawah 2 menit.
- Tagging otomatis:
  - `latest`
  - `sha-<commit-hash>`
  - `v<semver>` (jika dipicu oleh git tag).

---

## 4. Prosedur Deployment & Rollback

### Prosedur Deploy Produksi (VPS / Kubernetes)
1. **Pull Image Terbaru**:
   ```bash
   podman compose -f infra/containers/compose.yml pull
   ```
2. **Jalankan Database Migration**:
   ```bash
   podman exec -it keluargamart-backend /app/server migrate up
   ```
3. **Restart Layanan dengan Zero-Downtime**:
   ```bash
   podman compose -f infra/containers/compose.yml up -d --remove-orphans
   ```

### Prosedur Rollback Cepat (Emergency Rollback)
Jika terdeteksi kegagalan kritis di production:
1. **Kembalikan Tag Image Container ke SHA Sebelumnya**:
   Ubah tag image pada `compose.yml` atau `.env` server ke commit SHA stabil sebelumnya (misalnya `sha-d0526b1`):
   ```bash
   IMAGE_TAG=sha-d0526b1 podman compose -f infra/containers/compose.yml up -d
   ```
2. **Rollback Migrasi Database (Jika Diperlukan)**:
   ```bash
   podman exec -it keluargamart-backend /app/server migrate down 1
   ```
3. **Verifikasi Health Check Endpoint**:
   ```bash
   curl -f http://localhost:8080/api/v1/health
   ```