titipin/AGENTS.md

ROLE

Kamu adalah "Senior Fullstack Engineer" yang ahli dalam Next.js (App Router), Prisma ORM, PostgreSQL, dan Tailwind CSS. Kamu fokus pada clean code, validasi form yang ketat, dan UX yang seamless, menarik, dan elegan.

OBJECTIVE

Tugasmu adalah membangun aplikasi "TitipIn" (Sistem Titip Pesanan). Aplikasi ini berjalan dengan arsitektur serverless (Server Actions) dan sistem autentikasi stateless berbasis Device ID/User ID (UUID di localStorage) dengan menggunakan Next.js untuk bisa langsung connect ke database PostgreSQL, gunakan versi Nextjs terbaru atau versi yang sudah stabil untuk development. Tampilan UI menggunakan shadcn ui atau design yang serupa dengan shadcn ui dan menggunakan icon dari lucide-react.

1. DATABASE SCHEMA (PRISMA)

Fondasi utama skema database:

table User:

• id String @id @default(uuid())
• username String @unique
• name String
• password String
• photo String?
• role String @default("user") // "user" or "superadmin"
• is_active Boolean @default(true)
• created_at DateTime @default(now())
• updated_at DateTime @updatedAt
• orders Order[] @relation("CreatedOrders")
• purchases Submission[]

table Order:

• id String @id @default(uuid())
• title String
• date DateTime
• allow_custom Boolean @default(false)
• status String @default("DRAFT")
• creator_id String
• creator User @relation("CreatedOrders", fields: [creator_id], references: [id])
• available_items AvailableItem[]
• submissions Submission[]

table AvailableItem:

• id String @id @default(uuid())
• order_id String
• name String
• order Order @relation(fields: [order_id], references: [id], onDelete: Cascade)

table Submission:

• id String @id @default(uuid())
• order_id String
• user_id String
• bill Int?
• payment_status String @default("BELUM_BAYAR")
• order Order @relation(fields: [order_id], references: [id], onDelete: Cascade)
• user User @relation(fields: [user_id], references: [id], onDelete: Cascade)
• items SubmissionItem[]

table SubmissionItem:

• id String @id @default(uuid())
• submission_id String
• name String
• qty Int @default(1)
• is_custom Boolean @default(false)
• submission Submission @relation(fields: [submission_id], references: [id], onDelete: Cascade)

3. ENVIRONMENT SETUP & DATABASE MIGRATION

• Langkah Pertama: Buatkan file .env dengan format berikut (pastikan URL Prisma di-generate dari variabel-variabel ini jika dibutuhkan):

  DATABASE_HOST="172.10.10.2"
  DATABASE_PORT="5411"
  DATABASE_USER="postgres"
  DATABASE_PASSWORD="eigen3m!"
  DATABASE_NAME="testing"
  

• Konfigurasi Prisma: Pastikan schema prisma diatur dengan provider postgresql dan membaca konfigurasi dari file .env.

• Instruksi Migrasi: Setelah membuat skema, berikan saya list perintah terminal (command) yang harus saya jalankan secara eksplisit untuk men-generate Prisma Client dan melakukan sinkronisasi skema ke database (contoh: npx prisma generate dan npx prisma db push).

2. CORE AUTHENTICATION FLOW

• DILARANG menggunakan NextAuth/library auth eksternal. Buat custom authentication menggunakan JWT (atau hash-based token) yang disimpan di HTTP-only cookies atau localStorage.
• Fitur Token: Tanpa waktu expired (no expiration) dan mendukung multi-device login.
• Terdapat halaman /login dan /register untuk pengguna.
• Default role saat registrasi adalah user.
• Harus ada seeder untuk membuat akun superadmin default: Username: superadmin (atau spesifik), Password: titipin123!, Role: superadmin.
• Middleware/Route Protection: Hanya user yang sudah login yang bisa mengakses halaman utama aplikasi. Halaman manajemen user hanya bisa diakses oleh role superadmin.

3. MENU NAVIGATION ORDER

Urutan navigasi menu utama pada aplikasi adalah sebagai berikut:

1. Open Order
2. Jasa Order Saya
3. Pesanan Saya
4. Laporan
5. User Management (Hanya Superadmin)
6. Profile

4. PAGE SPECIFICATIONS & STEP-BY-STEP FLOW

Step 1: Halaman Open Order/Dashboard/Beranda

• Menampilkan list semua order dari semua pengguna dengan status OPEN dan tanggal PO (date) == hari ini.
• Submit / Titip Pesanan (Modal):
  • Tampilkan available_items sebagai list Checkbox.
  • Aturan Item Checkbox & Qty: Jika user mencentang sebuah item, default qty adalah 1. Jika user melakukan uncheck, reset qty item tersebut menjadi 0 dan hapus dari payload. Saat submit, filter dan transform data agar hanya mengambil item yang benar-benar dicentang dengan qty valid.
  • Jika order allow_custom == true, sediakan form list untuk menambah "Item Lainnya" (custom item) beserta input qty-nya (hanya ambil custom item yang memiliki nama valid dan terisi).
  • Pemesan dapat mengedit pesanannya selama order tersebut masih berstatus OPEN dan tanggal PO == hari ini.

Step 2: Halaman Jasa Order Saya (/my-orders)

• Menampilkan list Order milik current user sendiri. Urutan: Status OPEN diletakkan di paling atas.
• Create Order (Modal):
  • title (text, required).
  • date (date picker, default hari ini, min. date hari ini, required).
  • allow_custom (checkbox).
  • available_items (dynamic form list). Aturan: Jika allow_custom == false, min. 1 item required. Jika true, boleh 0 item.
• Order State Machine & Edit Rule: Status otomatis DRAFT saat dibuat. Creator dapat mentrigger perubahan status dari DRAFT -> OPEN -> CLOSE -> OPEN kembali. Order hanya bisa diedit jika statusnya DRAFT atau OPEN DAN tanggal PO (date) == hari ini. Jika beda tanggal, disable tombol edit.
• Duplicate Rule: Tombol "Duplicate" di list view membuka modal Create Order dengan field yang terisi otomatis dari data lama, KECUALI id (baru) dan date (kembali default hari ini).
• List index harus bisa pagination, ada feaure sorting, dan filter.

Step 3: Halaman Detail Jasa Order (/my-orders/[id])

• Menampilkan detail order, daftar item tersedia, dan list Submission (orang yang nitip beserta nama, foto profile, item yang dipilih, dan custom item + qty).
• Manage Tagihan: HANYA BISA DILAKUKAN JIKA STATUS == CLOSE. Creator bisa mengedit data pesanan per orang untuk memasukkan nominal tagihan dan set payment_status (Lunas / Belum Bayar).
• Generator Summary (2 Section Terpisah - Tidak Disimpan ke DB):
  1. By Person: [Judul Order] - [Nama Pemesan 1] : [Item 1] [Qty], [Item 2] [Qty], ... - [Nama Pemesan 2] : [Item 1] [Qty], ... (Sediakan tombol Copy khusus section ini).
  2. By Item (Akumulasi): [Judul Order] - [Item 1] : [Total Qty] - [Item 2] : [Total Qty] (Sediakan tombol Copy khusus section ini).

Step 4: Halaman Pesanan Saya (/my-purchases)

• Menampilkan list Submission milik current user di berbagai order.
• Menampilkan judul order, item yang dipesan, nominal tagihan, dan status pembayaran (payment_status).
• List index harus bisa pagination, ada feaure sorting, dan filter.

Step 5: Halaman Laporan (/reports)

• Menampilkan ringkasan keuangan dan laporan transaksi dengan 2 mode (Tab):
  1. Berdasarkan PO (Kreator): Menampilkan total Omzet yang dikelola dan Piutang (uang yang belum dibayar oleh penitip).
  2. Berdasarkan Orang (Submittor): Menampilkan total Pengeluaran pribadi dan Hutang (tagihan yang belum dilunasi ke kreator).
• Dilengkapi dengan 4 Kartu Ringkasan (Summary Cards) yang responsif: Total Pengeluaran, Hutang Pribadi, Total Omzet, Total Piutang.
• Visualisasi berupa Bar Chart (Grafik) dan Data Grid (Tabel) yang diurutkan secara proporsional.
• Mendukung filter Bulan dan Tahun berbasis server-side.

Step 6: Halaman User Management (/users) - KHUSUS SUPERADMIN

• Hanya muncul jika current user memiliki role superadmin.
• Menampilkan tabel daftar user dengan pagination (default 10 per halaman).
• Fitur Superadmin:
  • Membuat data user baru.
  • Mengedit password user lain.
  • Activate dan Deactivate user.
  • Menghapus user.
• Proteksi Data Superadmin: Data superadmin tidak bisa dihapus atau di-deactivate (terkunci), hanya bisa ganti password.

Step 7: Halaman Profile (/profile)

• Form untuk mengedit Nama dan Foto Profile milik current user.
• Terdapat form Ganti Password yang mewajibkan input: Password Lama, Password Baru, dan Konfirmasi Password Baru.
• Validasi nama dan verifikasi password lama tetap berlaku saat proses update.

6. WORKFLOW EXECUTION

Patuhi arsitektur Next.js App Router. Pisahkan Server Actions (app/actions.ts) dari Client Components ("use client"). Langsung tuliskan kode yang diminta dengan clean dan tanpa penjelasan bertele-tele.

7. DOKUMENTASI README.md

Buatkan file README.md yang mendokumentasikan panduan lengkap langkah demi langkah dari awal proses clone hingga aplikasi berjalan sempurna. Dokumentasi ini harus memuat instruksi yang rapi dan mudah diikuti untuk:

• Kebutuhan Sistem (Prerequisites): Spesifikasi lingkungan yang dibutuhkan (seperti Node.js versi tertentu, database PostgreSQL).
• Instalasi: Perintah terminal untuk mengunduh dependency (npm install atau sejenisnya).
• Pengaturan Environment: Cara setup konfigurasi environment variables .env berdasarkan struktur yang sudah dijelaskan di atas.
• Eksekusi Migrasi Database: Perintah terminal yang wajib dijalankan secara berurutan untuk sinkronisasi database dan mengaktifkan Prisma Client (contoh: npx prisma generate lalu npx prisma db push).
• Menjalankan Aplikasi: Cara menjalankan server lokal (development mode) dan URL default yang bisa diakses di browser.