AbelBirdNest-Stock/docs/project-spec/walet-frontend-structure.md

Frontend Structure Sistem Inventory Walet

1. Tujuan

Dokumen ini menjelaskan struktur frontend yang disarankan untuk aplikasi inventory sarang burung walet berbasis lot, traceability, sorting, partial allocation, dan QR/barcode workflow.

Target utamanya:

• mudah dibangun bertahap
• mudah dipahami tim frontend
• mobile-friendly untuk flow gudang
• scalable untuk modul traceability dan reporting

2. Rekomendasi Stack

• Next.js / React
• TypeScript
• Tailwind CSS
• shadcn/ui atau komponen serupa
• TanStack Query untuk server state
• Zustand atau Redux Toolkit untuk local workflow state yang kompleks
• React Hook Form + Zod untuk form
• Data table component untuk list/listing besar
• QR scanner berbasis camera API di mobile web

3. Struktur Folder Tingkat Atas

src/
  app/
  components/
  features/
  lib/
  hooks/
  services/
  types/
  store/
  utils/
  config/

4. Struktur app/routes

src/app/
  login/
    page.tsx
  dashboard/
    page.tsx
  suppliers/
    page.tsx
    new/page.tsx
    [id]/page.tsx
    [id]/bank/page.tsx
  customers/
    page.tsx
    new/page.tsx
    [id]/page.tsx
    [id]/bank/page.tsx
  item-types/
    page.tsx
  item-grades/
    page.tsx
  warehouses/
    page.tsx
    [id]/page.tsx
  purchases/
    page.tsx
    new/page.tsx
    [id]/page.tsx
    [id]/edit/page.tsx
  receipts/
    page.tsx
    new/page.tsx
    [id]/page.tsx
  lots/
    page.tsx
    [id]/page.tsx
    [id]/trace/page.tsx
  sorting/
    page.tsx
    new/page.tsx
    [id]/page.tsx
  regrade/
    new/page.tsx
  sales/
    page.tsx
    new/page.tsx
    [id]/page.tsx
    [id]/allocation/page.tsx
    [id]/picking/page.tsx
  adjustments/
    page.tsx
    new/page.tsx
  returns/
    sales/page.tsx
    purchase/page.tsx
  barcode/
    scan/page.tsx
    lookup/page.tsx
  reports/
    stock-summary/page.tsx
    stock-lots/page.tsx
    purchases/page.tsx
    sales/page.tsx
    margins/page.tsx
    shrinkage/page.tsx
    traceability/page.tsx
  settings/
    page.tsx

5. Struktur Features

Setiap domain besar sebaiknya punya feature sendiri.

src/features/
  auth/
  dashboard/
  suppliers/
  customers/
  item-types/
  item-grades/
  warehouses/
  purchases/
  receipts/
  lots/
  sorting/
  regrade/
  sales/
  allocations/
  adjustments/
  returns/
  barcode/
  reports/

6. Contoh Isi Tiap Feature

Catatan domain tambahan:

• feature suppliers dan customers perlu mendukung field bank_name dan bank_account_number
• halaman detail supplier/customer sebaiknya punya section informasi pembayaran

Contoh feature purchases:

src/features/purchases/
  api/
    get-purchases.ts
    get-purchase-detail.ts
    create-purchase.ts
    update-purchase.ts
  components/
    purchase-form.tsx
    purchase-line-table.tsx
    purchase-status-badge.tsx
    purchase-filter.tsx
  hooks/
    use-purchase-form.ts
    use-purchases-query.ts
  schemas/
    purchase.schema.ts
  types/
    purchase.type.ts

Contoh feature sales:

src/features/sales/
  api/
    get-sales.ts
    get-sales-detail.ts
    create-sales.ts
    allocate-sales.ts
    confirm-picking.ts
  components/
    sales-form.tsx
    sales-line-table.tsx
    allocation-panel.tsx
    picking-panel.tsx
    sales-summary-card.tsx
  hooks/
    use-sales-form.ts
    use-allocation.ts
    use-picking.ts
  schemas/
    sales.schema.ts
  types/
    sales.type.ts

7. Shared Components

src/components/
  ui/
  layout/
    app-shell.tsx
    sidebar.tsx
    topbar.tsx
    mobile-nav.tsx
  tables/
    data-table.tsx
    table-toolbar.tsx
  forms/
    form-field.tsx
    number-input.tsx
    date-picker.tsx
    select-async.tsx
  status/
    status-badge.tsx
    stock-badge.tsx
  cards/
    metric-card.tsx
    lot-card.tsx
  dialogs/
    confirm-dialog.tsx
    allocation-dialog.tsx
    trace-dialog.tsx
  scanners/
    qr-scanner.tsx
    barcode-input.tsx

8. Services Layer

Pisahkan akses API dari komponen.

src/services/
  api-client.ts
  auth.service.ts
  supplier.service.ts
  purchase.service.ts
  receipt.service.ts
  lot.service.ts
  sorting.service.ts
  sales.service.ts
  adjustment.service.ts
  report.service.ts

9. Types Layer

src/types/
  api.ts
  auth.ts
  supplier.ts
  customer.ts
  item.ts
  warehouse.ts
  purchase.ts
  receipt.ts
  lot.ts
  sorting.ts
  sales.ts
  report.ts

10. State Management

Server state

Gunakan TanStack Query untuk:

• fetch list
• detail view
• mutation create/update
• invalidate cache

Local workflow state

Gunakan Zustand/Redux untuk flow kompleks seperti:

• sales allocation draft
• picking workflow
• sorting result draft
• scanner temporary state

11. Halaman Paling Kritis

A. Stock Lot List

Kebutuhan:

• filter kuat
• table cepat
• klik ke lot detail
• status warna

B. Lot Detail

Kebutuhan:

• identitas lot jelas
• parent-child relation
• movement timeline
• link ke sales/purchase/receipt
• aksi cepat hold/release/regrade/transfer

C. Allocation Screen

Kebutuhan:

• sales line summary di atas
• list lot tersedia
• qty allocation editor
• auto allocate FIFO
• kalkulasi total costing real-time
• validasi total qty

D. Picking Screen

Kebutuhan:

• scan QR
• tampil lot teralokasi
• input qty picked aktual
• error warning jika beda dari alokasi

E. Barcode Lookup Screen

Kebutuhan:

• buka cepat dari scan
• tampil ringkas tapi informatif
• tombol ke lot detail

12. Layout dan UX

Desktop

Cocok untuk:

• dashboard
• purchasing
• reports
• stock table besar

Mobile

Cocok untuk:

• scanning
• receiving
• picking
• transfer lot
• quick lot lookup

Saran:

• gunakan responsive layout, bukan dua app terpisah dulu
• fokus mobile-first pada layar operasional gudang

13. Form Strategy

Gunakan form section

Untuk form besar seperti purchase, receipt, sales:

• header section
• detail lines section
• summary section
• actions footer sticky

Untuk line items

Gunakan editable table atau repeater row.

14. Component Priorities MVP

Bangun komponen inti dulu:

• app shell
• data table
• form field library
• status badge
• QR scanner
• allocation panel
• movement timeline
• lot summary card

15. Flow Antar Halaman

Purchase to Receipt

Purchase List -> Purchase Detail -> Create Receipt -> Receipt Detail -> Generate Lots -> Lot Detail

Lot to Sorting

Lot List -> Lot Detail -> Create Sorting -> Sorting Result -> Child Lot Detail

Sales Flow

Sales List -> Create Sales -> Allocation Screen -> Picking Screen -> Sales Detail

Scan Flow

Scan Page -> Lookup Result -> Lot Detail / Picking / Transfer

16. Permissions UI

Owner

• read mostly all
• no heavy transactional edit by default

Purchasing

• purchase pages

Warehouse

• receipt, lots, transfer, adjustment, barcode

QC

• sorting, regrade

Sales

• sales, allocation, picking

UI harus hide action sesuai role.

17. Frontend API Integration Pattern

Untuk tiap feature:

• query key per list/detail
• mutation untuk create/update/action
• central error handler
• loading skeleton untuk page utama
• toast notification untuk success/error

18. Frontend Deliverable yang Bisa Lanjut Dibuat

Dari struktur ini, next bisa diturunkan menjadi:

• route map detail
• component tree per halaman
• page-by-page wireframe detail
• UI kit token
• frontend task breakdown per sprint

19. Rekomendasi Eksekusi

Urutan frontend yang paling masuk akal:

1. layout + auth
2. master data basic pages
3. purchase & receipt
4. stock lot & lot detail
5. sales & allocation
6. sorting & regrade
7. scanner flow
8. reports

20. Kesimpulan

Frontend sistem walet ini sebaiknya dibangun modular per feature, dengan lot detail dan allocation flow sebagai pusat desain. Fokus utama harus pada kecepatan operasional gudang dan kejelasan traceability, bukan sekadar tampilan tabel stok biasa.