# 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
```text
src/
  app/
  components/
  features/
  lib/
  hooks/
  services/
  types/
  store/
  utils/
  config/
```

## 4. Struktur app/routes
```text
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.

```text
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:

```text
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:

```text
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
```text
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.

```text
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
```text
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.