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

# Codex Handoff - 2026-05-10

Dokumen ini menyimpan konteks kerja terakhir agar pengerjaan bisa langsung dilanjutkan saat project dibuka lagi.

## Status Umum

- App aktif dikembangkan di `Next.js + Prisma`.
- Banyak flow bisnis inti sudah tersambung end-to-end.
- Project belum dianggap production-ready; fokus saat ini masih penyelesaian fitur dan perapihan UX.

## Perubahan Domain dan Terminologi

- `Customer` sudah dirapikan menjadi `Buyer`.
- `Seller` sudah dirapikan menjadi `Sales`.
- `sellerCurrencyCode` sudah dirapikan menjadi `companyCurrencyCode`.
- `item type` dan `item grade` sudah dibersihkan dari kontrak aktif UI/API; flow aktif sekarang pakai `grade`.
- Struktur Prisma dan mapping database sudah disesuaikan ke arah penamaan yang lebih jelas.

## Fitur yang Sudah Aktif

### 1. Penjualan Reguler

- Flow create dan close sudah aktif.
- Create:
  - buyer
  - mata uang buyer
  - mata uang perusahaan
  - rate buyer ke perusahaan bila beda currency
  - kurir
  - biaya kirim
  - resi opsional
  - multiple lot
- Line item:
  - pilih lot
  - berat jual
  - harga jual
  - info grade, kode lot, berat sekarang, harga MAL, bagi hasil agent
- Close:
  - berat jual aktual
  - berat retur
  - harga jual aktual
  - selisih otomatis masuk penyusutan
- Komisi agent:
  - dihitung ulang saat close
  - menambah saldo agent

### 2. Titip Jual / Consignment

- Flow create dan close sudah aktif.
- Close support:
  - berat terjual
  - berat kembali
  - berat susut
  - harga jual
  - komisi sales manual
- Rumus komisi agent:
  - `((berat terjual * (harga jual - harga MAL)) - komisi sales) * persentase share`
- Komisi agent:
  - menambah saldo bagi hasil agent
- Komisi sales:
  - punya histori sendiri di master `Sales`

### 3. Penjualan Just In Time

- Placeholder sudah diganti menjadi flow aktif.
- Header input sama arah umumnya dengan penjualan reguler.
- Barang dijual tanpa masuk gudang dan tanpa retur.
- Line item JIT:
  - grade
  - quantity
  - harga MAL
  - harga jual
  - agent opsional
  - skema bagi hasil opsional
  - catatan
- Status create:
  - `OPEN`
- Close:
  - update `harga jual aktual` saja
- Komisi agent:
  - dihitung saat close
  - menambah saldo bagi hasil agent
- Banyak pass UI sudah dilakukan agar gaya JIT mendekati penjualan reguler.

### 4. Purchases

- Menu `Purchases` sudah dipecah:
  - `Pembelian Reguler`
  - `Pembelian Kantor / Buyout Agent`
- `Purchase Detail` sekarang dibuka sebagai popup/modal agar tidak merusak layout utama.
- Tombol `Cetak receipt` dipindah ke detail purchase, bukan lagi di halaman receipt.

### 5. Pembelian Kantor / Buyout Agent

- Sudah aktif sebagai submenu terpisah.
- Sumber hanya dari lot aktif yang sudah ada.
- Buyout bisa parsial atau full.
- Setiap buyout selalu membuat lot baru milik kantor.
- Lot lama dikurangi; jika habis bisa closed.
- Komisi agent saat buyout:
  - `max(0, qty * (harga buyout - harga MAL)) * persen share`
- Jika harga buyout di bawah harga MAL, komisi agent default `0`.
- Komisi buyout menambah saldo bagi hasil agent dan masuk histori.
- Detail lot sudah menampilkan jejak buyout.

### 6. Fund Request

- Menu baru `/fund-requests` sudah aktif.
- Ada 2 tipe:
  - `Dana modal`
  - `Bagi hasil`
- Input:
  - code generated
  - no reff
  - agent
  - rekening agent
  - rekening kantor
  - nominal
  - waktu transfer
  - bukti transfer opsional
- Dampak saldo:
  - `Dana modal`: kantor transfer ke agent, jadi menambah saldo modal agent
  - `Bagi hasil`: pembayaran bagi hasil ke agent, jadi mengurangi saldo bagi hasil agent
- Histori mutasi agent ikut tercatat.

### 7. Master Agent

- Agent punya dua saldo:
  - `saldo bagi hasil`
  - `saldo modal`
- Histori mutasi saldo sudah aktif.
- Sumber histori mencakup:
  - opening balance
  - manual adjustment
  - consignment commission
  - regular sale commission
  - JIT sale commission
  - office buyout commission
  - fund request profit share
  - fund request capital
- Detail agent sudah bisa melihat histori.

### 8. Master Sales

- `Sales` punya `commission_balance`.
- Histori komisi sales sudah aktif.
- Detail sales sudah bisa menampilkan histori komisi.

### 9. Settings / Profil Perusahaan

- Profil perusahaan sekarang mendukung multiple rekening kantor.
- Bank kantor dipilih dari master bank.
- Fund Request memakai pilihan rekening kantor yang dipilih user.
- Bug sesudah save yang membuat list rekening kantor terlihat kosong tanpa refresh sudah diperbaiki.

## Perapihan UI/UX yang Sudah Dilakukan

- Banyak halaman master 2 kolom sekarang sudah punya:
  - pagination
  - search
- Picker grade besar sudah diganti ke searchable combobox di beberapa flow aktif.
- Sidebar bug auto-expand karena prefix path sudah diperbaiki.
- Icon bell di topbar di-hide.
- Tombol `?` diarahkan ke halaman bantuan `/help`.
- Beberapa halaman transaksi besar sudah dipadatkan dan disamakan skalanya.

## Catatan Teknis Penting

- Untuk banyak perubahan schema terakhir, `npm run prisma:generate`, `npm run db:push`, dan `npm run typecheck` sudah pernah lolos.
- Alur kerja saat ini masih banyak mengandalkan `db push`, belum migrasi Prisma versioned.
- Belum ada test suite otomatis yang matang.
- Project sebelumnya juga sudah dinilai belum production-ready, terutama pada aspek auth/bootstrap dev account, secret fallback, migration discipline, dan testing.

## Isu yang Baru Saja Diperbaiki

- `Settings`:
  - setelah simpan, list rekening kantor sempat terlihat reset
  - akar masalah: response `PUT /api/v1/settings` tidak mengembalikan relasi `companyBankAccounts`
  - sudah diperbaiki dengan fetch ulang record lengkap sebelum serialize
- `Pembelian Reguler`:
  - warning `lengkapi master data` sempat muncul terus saat buka halaman
  - sudah diperbaiki agar hanya muncul setelah loading selesai dan hanya jika master wajib benar-benar kosong
- `Purchase Analysis`:
  - chip jumlah purchase sudah dipaksa satu baris

## Kandidat Lanjutan Paling Masuk Akal

1. Lanjut desain dan implementasi flow `Pembelian Just In Time` jika memang masih ada versi purchase-side yang terpisah dari `Sales JIT`.
2. Sweep UI consistency lagi untuk:
   - `Sales JIT`
   - `Fund Request`
   - `Office Buyout`
3. Tambah dokumentasi user flow untuk transaksi baru:
   - regular sale
   - JIT sale
   - office buyout
   - fund request
4. Hardening project sebelum production:
   - hapus bootstrap user dev dari runtime login
   - wajibkan `AUTH_SECRET`
   - pindah ke Prisma migrations
   - tambah test smoke/integration
   - rate limiting auth endpoint

## File Ini

- Update file ini setiap kali ada keputusan bisnis besar atau modul baru selesai.
- Kalau mau lebih formal, file ini bisa diganti nanti menjadi `docs/project-status.md` permanen.