Bab 9 — FAQ & Pemecahan Masalah

9.1 Login & tampilan

Tampilan login / menu lama setelah update?
Hard refresh Ctrl + Shift + R. Pastikan deploy selesai. Logout lalu login jika permission baru disimpan.

Menu tidak muncul padahal role sudah benar?
Cek matriks RBAC (Bab 8). Piutang butuh modul Tagihan Gabungan, bukan hanya Laporan. Persetujuan SO butuh Setujui pada Sales Order.

9.2 Sales order

SO Butuh approval?
Bisa karena: diskon order di atas limit user, harga baris di bawah modal/COGS, limit kredit customer terlampaui, atau ada piutang SO lewat jatuh tempo. User dengan hak approve buka Persetujuan SO; perbaiki diskon/harga/kredit, atau setujui jika sesuai kebijakan. SO tetap DRAFT sampai disetujui.

Tidak bisa buat invoice?

• Umum: perlu TTB untuk DO yang ditagihkan; invoice diterbitkan per TTB (bukan menunggu seluruh qty SO terkirim).
• Asuransi: perlu pembayaran terlebih dahulu untuk invoice resmi.

Preview invoice error / halaman kosong?
Pastikan deploy terbaru sudah jalan (npx prisma migrate deploy). Preview invoice memakai ID invoice (bukan ID SO) — klik badge invoice di bagian Pengiriman pada detail SO.

Ongkir salah / hanya muncul di invoice pertama?
Ongkir sekarang per DO. Isi ongkir saat buat setiap DO. Jika data lama salah, hubungi developer untuk script perbaikan (repair-partial-invoice-delivery-fees).

Bagaimana ubah alamat pengiriman customer?
Master → Customers → edit customer → bagian Alamat Customer → tombol pensil pada kartu alamat. Tidak perlu hapus dan buat ulang.

DP ditolak (limit kredit)?
Cek Limit Kredit dan piutang; lunasi sebagian atau sesuaikan limit di master customer.

9.3 Tagihan gabungan (TAG)

SO tidak masuk TAG?
SO sudah PAID / sisa 0 tidak ikut TAG baru. Lunasi lewat SO dulu atau gunakan SO yang masih outstanding.

TAG Rp 0 tapi ada riwayat bayar di SO?
Sistem reconcile menyelaraskan TAG dengan pembayaran di luar TAG. Buka TAG dengan reconcile atau refresh dialog; sisa TAG yang ditampilkan yang dipakai untuk pelunasan.

Tombol bayar TAG disabled?
Sisa TAG sudah 0 — tidak perlu catat pelunasan TAG lagi.

Invoice massal dari TAG gagal sebagian?
Buka detail SO di workflow — syarat TTB/pembayaran per SO mungkin belum terpenuhi. Pesan error menampilkan SO yang gagal.

Error Unique constraint failed on invoiceNumber saat terbitkan invoice dari TAG?
Terjadi pada versi lama saat banyak invoice dibuat sekaligus. Setelah deploy terbaru (fix penomoran dalam transaksi), klik ulang Terbitkan Invoice Semua SO. Jika masih gagal, cek apakah sebagian invoice sudah terbuat — buka detail SO dan lanjutkan manual.

SO yang sama muncul dua kali di TAG?
Normal untuk customer umum dengan invoice parsial — setiap baris = satu segmen tagihan (mis. per TTB) dengan status invoice berbeda.

Sudah dibayar TAG lebih besar dari total tagihan?
Kemungkinan data tidak selaras (pembayaran ganda atau alokasi lama). Batalkan TAG draft/aktif jika perlu (Batalkan tagihan ini), perbaiki pembayaran di SO, lalu buat TAG baru. Hubungi developer jika riwayat pembayaran perlu dikoreksi manual.

Di mana TAG yang sudah lunas?
Piutang Customer → tampilan TAG sudah lunas → klik nomor TAG untuk detail.

9.4 Purchase order

Tidak ada form pembayaran PO?
PO harus Dikirim atau Diterima. Role perlu izin payments (biasanya Finance).

Status Diterima sebagian?
Normal jika penerimaan partial — terima sisa qty di kunjungan berikutnya.

9.5 Stok

Stok tidak cukup saat SO?
SO masuk Pending Fulfillment (atau tetap DRAFT jika butuh approval). Buka detail SO → Buat PO Pengadaan (atau lacak di Board Pengadaan). Tombol PO juga tersedia pada SO DRAFT yang kekurangan stok. Setelah PO diterima dan stok cukup, badge Siap Kirim muncul → lanjut buat DO.

Bagaimana lacak SO yang menunggu belanja?
Menu Board Pengadaan (/admin/procurement) — 3 kolom: Menunggu PO, PO In Transit, Siap Kirim. Detail SO menampilkan panel Purchase Order Terkait.

PO tidak muncul di board / panel SO?
PO harus dibuat lewat Buat PO Pengadaan dari detail SO agar terhubung (salesOrderId). PO manual tanpa kaitan tidak tampil di lacak SO tersebut.

Tombol Buat PO Pengadaan masih muncul padahal sudah ada PO?
Setelah deploy terbaru, tombol diganti label PO pengadaan terbit dengan link ke PO. Satu SO hanya satu PO pengadaan aktif (kecuali PO dibatalkan).

Kapan bisa buat DO setelah pengadaan?
Setelah PO diterima dan stok cukup, kartu hijau Pengadaan Selesai — Siap Delivery Order muncul di detail SO.

Bagaimana batalkan SO atau PO?
Superadmin batalkan langsung. Role lain ajukan dari detail dokumen; Superadmin setujui di Persetujuan SO (bagian bawah halaman).

Sudah terima PO tapi belum Siap Kirim?
Qty PO mungkin kurang dari kebutuhan, atau masih ada SKU lain yang short — cek kartu alert pengadaan di detail SO.

Saldo master vs menu Stock beda?
Samakan filter entity (EITO vs ALBATROSS).

9.6 Import vendor

Import gagal parse?
Cek format Excel, lihat baris gagal, perbaiki & upload ulang.

Import besar lambat?
Proses background — refresh halaman untuk status terbaru.

9.7 Laporan

Pembayaran harian kosong?
Belum ada pembayaran SO pada tanggal/entity tersebut.

Pengeluaran harian kosong?
Belum ada pembayaran PO dicatat.

Asuransi tanpa badge Siap ditagih?
Belum semua item terkirim atau masih ada DO tanpa TTB.

Limit kredit aneh?
Laporan memakai terpakai efektif = max(credit used master, piutang SO aktif).

9.8 Error Failed to find Server Action

Health /api/health masih ok tetapi pm2 logs menampilkan error ini setelah deploy.

• Penyebab umum: tab browser masih memuat JS versi lama.
• User: hard refresh Ctrl + Shift + R, tab baru, atau logout/login.
• Server: rm -rf .next, build ulang, pm2 restart eito (otomatis di deploy-vps.sh terbaru).

9.9 Error teknis

findFirst undefined / Prisma error setelah update?
Administrator: hentikan dev server, jalankan npx prisma generate, migrasi, restart.

Halaman 500 setelah deploy?

cd /opt/eito
npx prisma migrate deploy
npm run prisma:generate
npm run build
pm2 restart eito

npm ERR! FETCH_ERROR / mirror tencentyun saat deploy?
Registry npm di VPS mengarah ke mirror yang rusak. Di server:

cd /opt/eito
git pull origin master
npm config delete registry --location=global 2>/dev/null || true
npm cache clean --force
./scripts/deploy-vps.sh

Proyek sudah memakai .npmrc → registry.npmjs.org agar npm ci tidak ikut mirror global.

npm ERR! ECONNRESET / network aborted saat npm ci?
Koneksi ke registry npm terputus (sering di VPS Tencent/China). Coba berurutan:

cd /opt/eito
git pull origin master
npm config delete registry --location=global
npm config delete proxy --location=global
npm config delete https-proxy --location=global
npm cache clean --force
npm ci

Jika masih gagal, pakai mirror alternatif sekali untuk install:

NPM_CONFIG_REGISTRY=https://registry.npmmirror.com npm ci
./scripts/deploy-vps.sh

Setelah sukses, build tetap memakai registry.npmjs.org dari .npmrc proyek.

9.10 Kontak dukungan