AbelBirdNest-Stock/docs/codex-handoff-2026-05-21.md

Codex Handoff - 2026-05-21

Dokumen ini menyimpan konteks kerja terbaru setelah rangkaian patch mobile, login publik, global search, locking satuan, dan workflow deploy artifact Linux.

Status Umum

• App aktif dikembangkan di Next.js + Prisma + PostgreSQL.
• Branch aktif: main
• Repo remote utama: https://git.iptek.co/wirabasalamah/AbelBirdNest-Stock.git
• Server target production saat ini: /var/www/abelbirdnest-web/AbelBirdNest-Stock

Ringkasan Perubahan Terbaru

0. Update Pembelian, Penerimaan, Label Lot, dan Navigasi - 2026-05-29

• Branch main sudah sinkron dengan origin/main.
• Commit terakhir saat handoff ini diperbarui: 4c5b62d Prefer specific active navigation links
• Commit terkait patch terbaru:
  • 44146a4 Split purchase submit from receipt finalization
  • 57896d3 Add receipt menu access
  • 1217529 Complete receipt translations
  • d0bdd4b Refine purchase receipt and lot label flow
  • 2df1752 Render receipt lot labels with QR and barcode
  • 3a52d29 Keep receipt action labels on one line
  • 4c5b62d Prefer specific active navigation links

Pembelian Reguler

• Halaman Pembelian Reguler tidak lagi meminta input Gudang dan Lokasi.
• Tombol submit lama yang langsung membuat receipt/lot sudah tidak dipakai dari halaman pembelian.
• Pembelian sekarang disimpan sebagai draft/data purchase, lalu proses penerimaan dilakukan dari menu: Pembelian > Penerimaan.
• Payload purchase tetap kompatibel dengan API lama, tetapi warehouse_id dan warehouse_location_id dikirim kosong/null.
• File utama:
  • src/features/purchases/components/purchases-client.tsx

Penerimaan dan Generate Lot

• Menu Pembelian > Penerimaan menjadi tempat utama untuk:
  • memilih pembelian yang belum punya receipt
  • mengisi qty diterima/valid/ditolak
  • memilih gudang dan lokasi
  • membuat receipt
  • generate lot dari receipt
• API receipt mencegah receipt/lot dobel untuk pembelian yang sama.
• Saat Buat lot, status purchase ikut menjadi SUBMITTED.
• Generate lot dari receipt mempertahankan logic realization/allocation terbaru:
  • membuat inventory_lots
  • membuat lot_purchase_allocations
  • membuat purchase_realization_entries
  • recalculation summary realization
• Kode lot dari satu receipt dibuat berurutan dalam satu transaksi agar tidak bentrok untuk receipt multi-line.
• File utama:
  • src/features/receipts/components/receipts-client.tsx
  • src/app/api/v1/receipts/route.ts
  • src/app/api/v1/receipts/[id]/generate-lots/route.ts
  • src/features/receipts/lib/serialize-receipt.ts
  • src/types/receipt.ts

Cetak Receipt dan Label Lot dari Penerimaan

• Daftar/detail penerimaan sekarang punya tombol:
  • Receipt / Cetak receipt
  • Label lot / Cetak label lot
• Cetak label lot dari penerimaan sudah memakai QR code dan barcode sungguhan, dengan library yang sama seperti halaman detail lot:
  • qrcode
  • jsbarcode
• Tombol aksi daftar penerimaan dipaksa satu baris agar label Label lot tidak wrap.
• Label lot dari receipt mengambil nilai scan dari:
  • qr_code_value
  • barcode_value
  • fallback ke lot_code

Navigasi Aktif

• Sidebar dan mobile nav sebelumnya bisa menandai Pembelian Reguler aktif saat user berada di: /purchases/office-buyout
• Active state sekarang memilih href paling spesifik/paling panjang ketika beberapa route cocok.
• File utama:
  • src/components/layout/sidebar.tsx
  • src/components/layout/mobile-nav.tsx

Script Seed Lokal

• File scripts/seed-local-superadmin.mjs sudah ikut masuk git sesuai kebutuhan dev/test.
• Script ini membuat role dan user SYSTEM_ADMIN lokal.
• Catatan keamanan: script berisi password hardcoded password, jadi pakai hanya untuk environment lokal/dev, bukan production.

Verifikasi Patch Terbaru

• npx tsc --noEmit lolos setelah patch:
  • split pembelian/penerimaan
  • cetak receipt
  • cetak label lot QR/barcode
  • active navigation fix

Update Server Dev

• Untuk server dev boleh compile langsung di server via npm.
• Command umum:

cd /path/ke/AbelBirdNest-Stock
git pull origin main
npm ci
npm run prisma:generate
npm run build
sudo rc-service abelbirdnest-web restart
sudo rc-service abelbirdnest-web status
curl -I http://127.0.0.1:3007/login

• Jika server dev memakai systemd:

sudo systemctl restart abelbirdnest-web
sudo systemctl status abelbirdnest-web --no-pager

• Tidak ada migration Prisma baru dari patch ini.

1. Flow Mobile Purchase

• Menu Receipt di mobile sudah dikeluarkan dari bootstrap mobile.
• Submit purchase sekarang langsung:
  • membuat receipt
  • membuat receipt_lines
  • membuat lot
  • membuat alokasi realization terkait
• Endpoint utama:
  • src/app/api/v1/purchases/[id]/submit/route.ts
  • src/app/api/v1/mobile/bootstrap/route.ts
• Dokumen mobile sudah disesuaikan:
  • docs/mobile-api-blueprint.md

2. Formatting Qty dan Currency

• Formatting kg sekarang locale-aware.
• Angka hasil konversi gram ke kilogram tampil dengan format Indonesia yang benar, misalnya 10,5 kg.
• Currency di beberapa modul tidak lagi hardcoded dan mengikuti currency_code sistem.
• File sentral:
  • src/lib/formatters.ts

3. Dashboard Qty Fix

• Dashboard sebelumnya salah menampilkan angka seperti 94.290 kg untuk data gram yang seharusnya dibaca sebagai 94,29 kg.
• Perbaikan dilakukan dengan konversi qty berbasis unit.code sebelum agregasi.
• File utama:
  • src/lib/dashboard.ts

4. Login Publik, Contact Admin, dan Halaman Legal

• Login sekarang punya link publik yang benar-benar aktif:
  • Hubungi Admin
  • Bantuan
  • Kebijakan Privasi
  • Syarat & Ketentuan
• Hubungi Admin sekarang menuju halaman publik dengan form kirim email.
• Form ini memakai:
  • CAPTCHA aritmatika server-side
  • honeypot anti-spam
• Halaman publik legal/help tersedia tanpa login:
  • /contact-admin
  • /help-public
  • /privacy-policy
  • /terms-and-conditions
• Semua halaman publik ini sudah dua bahasa ID/EN.
• Email admin tidak lagi ditampilkan langsung di halaman publik; user diarahkan memakai form kontak admin.
• File utama:
  • src/features/auth/components/login-client.tsx
  • src/features/auth/components/contact-admin-client.tsx
  • src/app/api/v1/public/contact-admin/route.ts
  • src/lib/public-captcha.ts
  • middleware.ts

5. Global Search Header

• Search di topbar sebelumnya hanya placeholder.
• Sekarang search desktop:
  • full width sampai mendekati switch bahasa
  • real-time
  • menampilkan dropdown hasil
  • bisa klik hasil
  • bisa Enter untuk fallback ke halaman lot
• Search lintas:
  • lot
  • purchase
  • supplier/agent terkait
• Endpoint baru:
  • src/app/api/v1/global-search/route.ts
• Komponen utama:
  • src/components/layout/topbar-search.tsx
  • src/components/layout/topbar.tsx
• Halaman lot sudah membaca query URL ?search= agar fallback search juga benar-benar terpakai.

6. Master Satuan Dikunci

• Master Satuan sekarang dibuat fixed dan tidak lagi editable.
• Hanya dua satuan yang diizinkan:
  • gr
  • kg
• GET /api/v1/units akan memastikan dua unit itu selalu ada.
• POST, PUT, dan DELETE unit sekarang ditolak 403.
• Submenu Satuan disembunyikan dari sidebar.
• Kalau halaman /units dibuka langsung, tampilannya read-only.
• File utama:
  • src/features/units/lib/fixed-units.ts
  • src/app/api/v1/units/route.ts
  • src/app/api/v1/units/[id]/route.ts
  • src/components/master-data/units-client.tsx
  • src/config/navigation.ts

Prisma dan Build Cross-Platform

• Local Mac sempat rusak karena build Linux menimpa hasil prisma generate.
• Generator Prisma sekarang mencakup:
  • native
  • darwin-arm64
  • debian-openssl-3.0.x
  • linux-musl-openssl-3.0.x
• File:
  • prisma/schema.prisma

Workflow Deploy Artifact Linux

• Build di server sempat berat dan tidak stabil.
• Sekarang ada workflow artifact standalone Linux.
• Script:
  • deploy/scripts/build-linux-release.sh
• Karakteristik workflow ini:
  • build di Docker Alpine Linux agar cocok dengan server Alpine
  • install openssl di container
  • pakai NODE_OPTIONS=--max-old-space-size=4096
  • copy source ke /work agar tidak menimpa node_modules lokal Mac
  • artifact final memakai timestamp: abelbirdnest-release-YYYYMMDD-HHMMSS.tar.gz
• Artifact final tidak membawa .env.production lokal.

Catatan Tambahan 2026-05-26

• Server production memakai Alpine Linux dengan RAM sekitar 1 GB.
• Jangan compile/build di server.
• Artifact harus dibuat dari container Alpine, default script sekarang memakai node:20-alpine.
• Runtime server Alpine perlu nodejs dan openssl.
• Ukuran artifact runtime-only yang normal sekitar 43 MB.
• Jika artifact membengkak sekitar 120 MB+, kemungkinan Prisma CLI atau node_modules lengkap ikut terbawa. Jangan pakai varian besar itu untuk server 1 GB kecuali memang sengaja.
• Artifact runtime-only tidak dipakai untuk menjalankan prisma migrate deploy di server. Untuk update UI/app tanpa perubahan schema DB, cukup extract release baru lalu restart service.
• Jika nanti ada migration database, jalankan migration dari mesin build/admin yang punya dependency lengkap dan akses DB production, bukan dari server kecil.

Catatan Deploy Server Saat Ini

• Path app aktif di server production saat ini: /opt/abelbirdnest-web
• Struktur release yang dipakai sekarang diasumsikan:
  • upload artifact ke root app server: /opt/abelbirdnest-web
  • extract ke releases/<timestamp>
  • symlink current diarahkan ke release aktif
• Folder aktif runtime: /opt/abelbirdnest-web/current
• Service server memakai OpenRC, bukan systemd.
• Service OpenRC production yang ditemukan:
  • directory="/opt/abelbirdnest-web/current"
  • command="/usr/bin/node"
  • command_args="/opt/abelbirdnest-web/current/server.js"
  • env yang dicek service: /opt/abelbirdnest-web/current/.env
• Karena service mencari .env di folder current, setiap release baru perlu copy .env dari release/current lama ke folder release baru sebelum current diarahkan ke release baru.
• Jangan gunakan path lama /var/www/abelbirdnest-web/AbelBirdNest-Stock untuk server ini kecuali service production memang sudah diubah.

Command Manual Deploy Yang Dipakai

Di lokal:

scp abelbirdnest-release-YYYYMMDD-HHMMSS.tar.gz abelbirdnest@SERVER_IP:/opt/abelbirdnest-web/

Di server:

cd /opt/abelbirdnest-web
RELEASE_NAME=YYYYMMDD-HHMMSS
mkdir -p /opt/abelbirdnest-web/releases/$RELEASE_NAME
tar -xzf /opt/abelbirdnest-web/abelbirdnest-release-$RELEASE_NAME.tar.gz -C /opt/abelbirdnest-web/releases/$RELEASE_NAME
cp /opt/abelbirdnest-web/current/.env /opt/abelbirdnest-web/releases/$RELEASE_NAME/.env
mv /opt/abelbirdnest-web/current /opt/abelbirdnest-web/current-backup-$(date +%Y%m%d-%H%M%S) 2>/dev/null || true
ln -sfn /opt/abelbirdnest-web/releases/$RELEASE_NAME /opt/abelbirdnest-web/current
sudo chown -R abelbirdnest:abelbirdnest /opt/abelbirdnest-web
sudo rc-service abelbirdnest-web restart
sudo rc-service abelbirdnest-web status
curl -I http://127.0.0.1:3007/login

Jika ln -sfn ... current gagal dengan pesan File exists, berarti current masih folder biasa. Backup/rename folder itu dulu, lalu ulangi ln -sfn.

Verifikasi yang Sudah Dilakukan

• npx tsc --noEmit lolos setelah patch terbaru.
• Global search endpoint mengembalikan hasil yang benar untuk sample data lokal.
• GET /api/v1/units sekarang hanya mengembalikan gr dan kg.
• POST /api/v1/units sekarang ditolak dengan pesan lock master.

Risiko / Catatan yang Masih Relevan

• Build standalone lokal tetap menampilkan warning Prisma saat static generation jika DB lokal tidak aktif; warning ini tidak menggagalkan artifact.
• Production deploy sekarang punya dua mode historis:
  • mode lama repo root + npm run start
  • mode baru artifact standalone + node server.js Jangan campur keduanya pada instruksi deploy.
• Beberapa endpoint mobile/receipts/** masih ada untuk kompatibilitas lama, walaupun flow mobile baru tidak lagi menampilkan menu receipt.

Langkah Lanjutan Paling Masuk Akal

1. Deploy artifact terbaru ke server production.
2. Verifikasi:
   • search header aktif
   • halaman publik login aktif
   • Satuan tidak muncul di menu
   • GET /api/v1/units hanya gr dan kg
3. Jika perlu, lanjut bersihkan endpoint legacy yang sudah tidak dipakai lagi, terutama sekitar receipt mobile lama.

Catatan Penutup

• Handoff sebelumnya:
  • docs/codex-handoff-2026-05-19.md
• Handoff 2026-05-21 ini adalah snapshot terbaru dan seharusnya dipakai sebagai konteks utama lanjutan.