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
• name String @unique
• photo String?
• 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.
• Setiap kali web diakses, jalankan pengecekan:
  1. Cek localStorage untuk user_id.
  2. Jika belum ada, generate UUID baru, simpan ke localStorage.
  3. Lakukan verifikasi ke database/server action apakah user_id tersebut sudah terdaftar di tabel User.
  4. Jika belum terdaftar, wajib munculkan Modal Profile yang tidak bisa ditutup.
  5. Modal meminta input "Nama" (Wajib) dan "Foto Profile" (Opsional).
  6. Validasi: Nama harus UNIK di tabel User. Setelah valid, simpan ke database menggunakan user_id sebagai id.
  7. Jika user_id sudah terdaftar, lewati modal dan muat data user secara mulus.

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. 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 Profile (/profile)

• Form untuk mengedit Nama dan Foto Profile milik current user.
• Validasi nama unik 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.