# TEMPLATE: `<project>-backend/AGENTS.md`

> Template ini di-deploy oleh AI saat split repo migration.
> Customization: replace `<project>` dengan nama project user.

```markdown
# AGENTS.md - <project>-backend

> Repo ini: Backend API + Business Logic + Database.
> Audience AI: Claude Code untuk Backend Staff (2 orang yang akses semua 3 repo: `<project>-frontend`, `<project>-backend`, `<project>-shared`) + owner.
> PRIVATE - 4 Frontend Staff TIDAK punya akses ke repo ini.
>
> Privileges Backend Staff:
> - FULL DB control: CRUD + DDL (CREATE TABLE / ALTER / DROP / migration)
> - Publish version baru `@<project>/shared`
> - Modify Prisma schema dan generate migration

## Scope Kamu (AI)

Kamu di repo `<project>-backend`. Kamu BOLEH:
- Bikin/edit API endpoint (Hono/Express atau Next.js API routes)
- Direct database access via Prisma
- Implement business logic (validation, calculation, workflow)
- Modify Prisma schema + generate migration
- Update `@<project>/shared` types (lalu publish version baru)
- Akses Supabase logs via MCP saat debug

Kamu TIDAK BOLEH:
- Edit UI components (itu di `<project>-frontend`)
- Hardcode rahasia di code (pakai env vars + `.env` gitignored)
- Bypass authentication / authorization checks
- Skip migration files saat schema change (semua DDL via Prisma migrate)
- Run `prisma db push` ke production (selalu pakai migration)
- Drop / truncate tabel produksi tanpa konfirmasi owner eksplisit

## Stack
- Hono OR Next.js API routes (Node.js runtime, bukan edge)
- Prisma ORM (lihat STACK_VERSIONS.md untuk versi terbaru)
- Supabase PostgreSQL (shared dengan staging via branch)
- JWT atau session-based auth (lihat `src/lib/auth.ts`)
- Zod untuk schema validation (semua input WAJIB di-validate)

## Workflow Backend-First

Saat owner/delegate prompt kamu untuk fitur baru:

1. Baca prompt, identify TASK ID
2. Cek apakah ada perubahan data model:
   - Kalau ya: update `prisma/schema.prisma` dulu
   - Generate migration: `npx prisma migrate dev --name <descriptive>`
   - Review SQL hasil migration sebelum apply
3. Bikin route handler dengan validation Zod
4. Implement business logic di service layer (`src/services/`)
5. Update `@<project>/shared` types kalau ada shape baru
6. Test API dengan curl atau Postman atau Hono `testClient`
7. Tulis unit test minimum 1 per endpoint baru
8. Open PR ke `main`
9. Tag version baru `@<project>/shared` kalau ada types update
10. Notify frontend tim via Discord: "API `<endpoint>` ready, types @ v1.X.Y"

## Critical Safety

- Sebelum `prisma migrate deploy` ke prod, CEK `DATABASE_URL` host
- Script `prisma-guard.mjs` akan block kalau host match prod ref
- Migration ke prod = manual owner dengan `PRISMA_GUARD_BYPASS=1` env var
- Backup snapshot owner SEBELUM apply migration destructive (drop column, rename, dst.)

## API Documentation

- Auto-generated via `next-swagger-doc` atau Hono OpenAPI plugin
- Available di: `http://localhost:3001/docs` (local dev)
- Available di: `https://api-staging.<project>.id/docs` (staging)
- Frontend tim baca di sini, BUKAN baca source code backend
- Saat add/update endpoint, WAJIB update OpenAPI annotation

## Style Guide

- Sama dengan frontend (Prettier, naming, TypeScript strict)
- Tambahan: setiap endpoint WAJIB Zod schema validation di input
- Tambahan: error handling pakai `Result<T, E>` pattern atau exception class custom, bukan throw string
- Tambahan: logging pakai `pino` (structured JSON), bukan `console.log`

## Auto-Publish @<project>/shared (Trigger Rule)

Saat AI Claude Code execute task yang touching:
- Prisma schema (prisma/schema.prisma)
- API endpoint signature
- Response/request shape changes
- New domain types

AI WAJIB:

### Step 1: Update src/shared/ dengan types yang affected

    // src/shared/schemas/tracking.ts
    import { z } from 'zod'

    export const TrackingSchema = z.object({
      order_id: z.number(),
      status: z.enum(['pending', 'shipped', 'delivered']),
      shipped_at: z.string().datetime(),
      estimated_arrival: z.string().datetime().nullable(),
      delivered_at: z.string().datetime().nullable(),
    })

    export type OrderTracking = z.infer<typeof TrackingSchema>

### Step 2: Re-export di src/shared/index.ts

Pastikan semua public types ke-export.

### Step 3: Build + Verify

    npm run generate:types
    # Verify shared-dist/ punya types baru
    ls shared-dist/index.d.ts

### Step 4: Commit dengan conventional message

    git commit -m "feat(shared): add OrderTracking type"
    # Conventional message penting untuk semantic-release auto-bump version

### Step 5: Push → GitHub Actions auto-pipeline

Push trigger workflow .github/workflows/publish-shared.yml yang:
- Bump version (patch untuk fix, minor untuk new type, major untuk breaking)
- Publish ke GitHub Packages
- Discord notify

### Aturan Penting untuk AI

KALAU types berubah TANPA update @<project>/shared:
- AI JANGAN commit changes
- AI JANGAN claim "task done"

SELALU:
- Update shared types DULU
- Verify build OK
- Commit dengan conventional message
- Push (publish workflow akan handle sisanya)

Bahasa Indonesia untuk user-facing output:
"Saya update types di @<project>/shared juga (auto-publish akan jalan setelah push). Frontend tim dapat notif via Discord + Renovate PR."

## Project-Specific Rules

<!-- Owner: tambahkan rules spesifik project di sini -->
<!-- Contoh: rate limit policy, audit log requirement, RBAC matrix -->
```