LabaBersih v2 — Complete Documentation

Problem yang Diselesaikan

1. Laba kelihatan besar, ternyata sisa dikit — fee transparency + per-fee reconciliation
2. Manual import/export antar platform — staging pipeline + API sync
3. Gak tau HPP akurat — FEFO lot tracking, bukan tebak-tebakan
4. Laporan keuangan gak beres — Trial Balance enforced, COA immutable, jurnal balanced

Tech Stack

Status & Phase Map

Yang Sudah Jadi

• Backend Layer 0-9: 133 tests, 10 context modules
• UI Phase 1-5: semua list page + detail + shared components
• Refactor Step 1-14: legal entity, COA auto-generate, per-fee rekon, tax
• Deploy: lababersih.id live di Fly.io

Phase Map

Entity Relationships

Key Relationships

Store N──1 Legal Entity
Store 1──8 Account (FK, auto-generated)
Store N──1 Warehouse (default)
Order N──1 Store
Order Item N──1 Product
Journal Entry Line.order_id → Order (per-order tracking)
Journal Entry.batch_date + batch_type (daily summary)
Legal Entity 1──N Tax Record
Legal Entity 1──N Purchase Order
Legal Entity 1──N Inventory Lot

Domain 1: Master Data

Product — Simple vs Bundle

Designed Phase 1

Prinsip

• Product = master data ONLY (nama, SKU, HPP, harga jual, unit)
• stok = readonly, HANYA berubah lewat dokumen (PO Receive / Adjustment / RTS Baik)
• SKU = milik seller, LabaBersih pakai SKU yang SAMA
• 2 tipe: simple (punya stok) dan bundle (virtual, dari komponen)

Schema

-- ALTER products
ADD COLUMN type           VARCHAR NOT NULL DEFAULT 'simple'  -- simple / bundle
ADD COLUMN harga_jual     DECIMAL                            -- untuk margin report
ADD COLUMN reserved_stock INTEGER NOT NULL DEFAULT 0         -- committed qty

-- NEW table: bundle_items (BOM)
bundle_items:
  id                    BINARY_ID PK
  bundle_product_id     FK → products (type=bundle)
  component_product_id  FK → products (type=simple)
  quantity              INTEGER NOT NULL  -- berapa komponen per 1 bundle
  UNIQUE(bundle_product_id, component_product_id)

Bundle Logic

Stok bundle = floor(MIN(komponen.stok / bundle_item.quantity))
HPP bundle  = SUM(komponen.hpp × bundle_item.quantity)

Saat bundle dijual:
  Order: BNDL02 × 2
  Lookup: BNDL02 = FRB01 × 3
  Consume: FRB01 × 6 (FEFO)
  HPP = sum lot costs dari 6 unit FRB01

Stock: On Hand / Committed / Available

On Hand   = product.stok (physical stock in warehouse)
Committed = product.reserved_stock (claimed by orders, not yet shipped)
Available = stok - reserved_stock (can be sold)

reserve_stock(product_id, qty)    → saat order masuk
release_reservation(product_id, qty)  → saat ship atau cancel

Unit Conversion

Designed Phase 1

Schema

unit_conversions:
  id          BINARY_ID PK
  product_id  FK → products
  unit_name   VARCHAR NOT NULL  -- "kardus", "lusin", "pak"
  factor      DECIMAL NOT NULL  -- 1 unit = factor × base unit
  UNIQUE(product_id, unit_name)

Contoh

Stock Audit Report

SKU    Produk           Stok(pcs)  Stok(kardus)  Sisa
FRB01  Forbest New 1kg  180        10 kardus     0 pcs    ✓ PAS
FRB02  Forbest 1kg       55         3 kardus     1 pcs    ← sisa
RTN01  Ritrina 1L        42         2 kardus     2 botol  ← sisa

Warehouse & Location Hierarchy

Partial Phase 1

Gudang Kediri (warehouse)
├── Zona Frozen (location, parent=null)
│   ├── Rak A (parent=Zona Frozen, entity=PT Bestari)
│   └── Rak B (parent=Zona Frozen, entity=CV Maju)
└── Zona Packing (location, parent=null)

Rules

• Store.default_warehouse_id → order masuk, stok dicek dari gudang ini
• Outbound (ship) → consume lot dari warehouse store
• PO Receive → masuk ke warehouse yang dipilih
• Transfer antar gudang = outbound A + inbound B (Phase 2)

Courier Mapping

Designed Phase 1

courier_mappings:
  org_id    FK → organizations
  raw_name  VARCHAR  -- "Shopee Cargo JNE" (dari marketplace)
  courier   VARCHAR  -- "JNE" (induk kurir)
  UNIQUE(org_id, raw_name)

Customer

Decided

orders.customer_name   -- "Budi"
orders.customer_phone  -- "081234" (nullable)

Store — Relasi Lengkap

Implemented

Store:
├── org_id → Organization
├── legal_entity_id → Legal Entity
├── default_warehouse_id → Warehouse (Phase 1 tambah)
├── platform: "tiktok" / "shopee" / "mengantar" / "pos"
├── fee_mapping: [{label, accountCode, percent, flatAmount}]
└── 8 Account FKs (auto-generated):
    ├── piutang_account_id    → "12-201 Piutang Shopee Bestari"
    ├── revenue_account_id    → "40-101 Pendapatan Shopee Bestari"
    ├── kas_account_id        → "11-311 Saldo Shopee Bestari"
    ├── hpp_account_id        → "50-100"
    ├── persediaan_account_id → "13-100"
    ├── retur_account_id      → "41-101 Retur Shopee Bestari"
    ├── sample_account_id     → nullable
    └── transfer_kas_account_id → nullable (Mengantar only)

Legal Entity

Implemented

Legal Entity:
├── name: "PT Bestari Jaya"
├── entity_type: "pt" / "cv" / "personal"
├── tax_status: "non_pkp" / "pkp"
├── npwp: "01.234.567.8-901.000"
├── is_default: true (1 per org, auto-create saat register)
└── Owns: stores, POs, lots, stock_transactions, tax_records

Domain 2: Accounting

COA — 3 Level Hierarchy

Implemented

Level 1: Type header      → 12 Piutang          (is_header=true, source_type="template")
Level 2: Platform header  → 12-2 Piutang Shopee  (source_type="platform")
Level 3: Store leaf       → 12-201 Piutang Shopee Bestari  (source_type="store")

Auto-Generate Flow

1. Org baru → seed COA template (level 1 headers)
2. Toko baru →
   a. Cek platform header ada? Kalau belum → create (level 2)
   b. Create leaf accounts per toko (level 3)
   c. Link store record ke accounts via FK
3. Rekonsiliasi → validasi order milik toko yang dipilih
4. Laporan → aggregate leaf → platform → type

Fundamental Principles

• Pendapatan selalu di CREDIT (normal_balance = credit)
• Beban selalu di DEBIT (normal_balance = debit)
• Trial Balance HARUS balance (total debit = total credit)
• Kode akun IMMUTABLE — sekali dibuat gak boleh diubah
• Posting HANYA ke leaf account — header untuk grouping saja

Daily Summary Journal (Opsi 4)

Designed Phase 1

Flow

SAAT SHIP (real-time per order):
  → Stok potong (FEFO lot consumption) ✓
  → HPP tercatat per order ✓
  → Jurnal fee BELUM (batch nanti)

DAILY BATCH (Oban job akhir hari, per toko):
  → 1 jurnal: "Penjualan Shopee Bestari — 30 Mar 2026"
  → Lines per order:
      Dr. Piutang (PS2603-00001)  Rp 184.000
      Dr. Admin   (PS2603-00001)  Rp   6.000  ← fee estimasi
      Dr. Komisi  (PS2603-00001)  Rp  10.000
      Cr. Revenue (PS2603-00001)  Rp 200.000
  → 1 jurnal HPP summary per toko per hari

SETTLEMENT (7-14 hari kemudian):
  → Per-fee matching (estimasi vs aktual)
  → Known fee → auto-adjust ke akun yang benar
  → Unknown fee → suspense account (61-999)

Per-Fee Reconciliation + Suspense

Implemented

Alur:
1. Validate order.store_id == attrs.store_id (ENFORCED)
2. Calculate estimated piutang dari fee mapping × gross
3. Per fee: match estimated vs actual
4. Known fee dengan selisih → adjustment ke akun fee
5. Unknown fee → suspense account 61-999

Cocok (selisih=0):   Dr. Kas / Cr. Piutang
Fee underestimated:  Dr. Kas + Dr. Adjustment / Cr. Piutang
Fee overestimated:   Dr. Kas / Cr. Piutang + Cr. Adjustment
Unknown fee:         → Suspense 61-999 (user kategorikan manual)

Tax — PPh Final

Implemented

Per legal entity per bulan:
  gross_revenue = SUM revenue jurnal entity bulan itu
  tax_payable   = gross_revenue × 0.5%

NON-PKP flow:
  1. Akhir bulan → auto-generate tax_record
  2. Status: draft → filed → paid
  3. PKP threshold warning: omzet YTD / Rp 4.8M

PKP flow: Structure ready (nullable ppn_output/ppn_input), implement nanti.

14 Journal Formulas

A1. Penjualan (saat kirim)

Dr. Piutang {platform}          = NET (gross - fees)
Dr. Biaya Admin Platform         = fee (dari fee mapping)
Dr. Biaya Komisi                 = fee
    Cr. Pendapatan {platform}    = GROSS (totalHarga)

Dr. HPP                          = FEFO lot cost × quantity
    Cr. Persediaan               = FEFO lot cost × quantity

A2. Rekonsiliasi

Cocok:  Dr. Kas / Cr. Piutang
Under:  Dr. Kas + Dr. Adjustment / Cr. Piutang
Over:   Dr. Kas / Cr. Piutang + Cr. Adjustment

A3. RTS — Reverse Penjualan

Dr. Retur Penjualan              = GROSS
    Cr. Piutang {platform}       = NET
    Cr. Biaya Admin              = fee (reverse)
Dr. Persediaan                   = hppTotal
    Cr. HPP                      = hppTotal

A4. RTS Inbound Rusak

Dr. Beban Kerugian Barang Rusak (64-700)  = hppTotal
    Cr. Persediaan (13-100)               = hppTotal

A5. RTS Inbound Hilang

Dr. Piutang Klaim Kurir (12-400)          = hppTotal
    Cr. Persediaan (13-100)               = hppTotal

A6. Klaim Diterima

Dr. Kas (11-100)                          = amount
    Cr. Piutang Klaim Kurir (12-400)      = amount

A7. Klaim Ditolak

Dr. Beban Kerugian Piutang (64-600)       = amount
    Cr. Piutang Klaim Kurir (12-400)      = amount

A8. PO Receive — Cash

Dr. Persediaan (13-100)     = total
    Cr. Kas (11-100)        = total

A9. PO Receive — Utang

Dr. Persediaan (13-100)     = total
    Cr. Hutang Usaha (20-100) = total

A10. PO Payment

Dr. Hutang Usaha (20-100)   = amount
    Cr. Kas (11-100)        = amount

A11. PO Return — Cash

Dr. Kas (11-100)            = total
    Cr. Persediaan (13-100) = total

A12. PO Return — Utang

Dr. Hutang Usaha (20-100)   = total
    Cr. Persediaan (13-100) = total

A13. Standalone RTS

Shopee/TikTok: Dr. Retur = GROSS, Cr. Piutang = NET, Cr. Fees
Mengantar:     Dr. Retur = GROSS, Cr. Piutang = GROSS (tanpa fee)

A14. Closing Period (3 jurnal)

1. Dr. Pendapatan / Cr. Ikhtisar Laba Rugi (30-400)
2. Dr. Ikhtisar Laba Rugi / Cr. Beban
3. Dr/Cr Ikhtisar ↔ Laba Tahun Berjalan (30-500)

Bonus Features

Aged Receivables Phase 2

Per toko, grouped by umur piutang:
  0-7 hari:   normal (baru kirim)
  8-14 hari:  perhatian (harusnya mulai cair)
  15-30 hari: WARNING
  > 30 hari:  BAHAYA

Recurring Expenses Phase 2

User setup biaya tetap sekali → auto-jurnal setiap bulan via Oban.
"Sewa Gudang Rp 5jt setiap tanggal 1" → auto Dr. Beban / Cr. Kas

Financial Health Dashboard Phase 2

7 metrics:
1. Piutang Ratio     (piutang/omzet %)
2. Cash Gap          (masuk - keluar)
3. Days to Cash      (avg ship → settlement)
4. Burn Rate         (biaya tetap/bulan)
5. RTS Rate          (rts/total order %)
6. Margin per Toko   ((pendapatan-beban)/pendapatan %)
7. PKP Threshold     (omzet YTD / 4.8M %)

Domain 3: Order Intake

XLSX Import — Auto (Tanpa Staging)

Designed Phase 1

Flow

1. Klik "Upload XLSX" di header Pesanan
2. Modal: pilih file + pilih toko (dropdown)
3. System parse XLSX:
   a. Detect format (Shopee/TikTok/Mengantar) by column headers
   b. Extract orders + items
   c. Per item: match SKU ke products (exact match)
4. Auto-import:
   ├── Order baru → create (status: "dibuat")
   ├── Duplikat (nomor_pesanan exists) → skip
   ├── SKU unknown → order masuk, item flagged
   └── Invalid data → reject, log error
5. Toast: "285 pesanan masuk, 10 duplikat, 5 SKU unknown"

3 Platform Parsers

API Sync — Staging Pipeline

Designed Phase 2

API Sync (TikTok/Shopee/Mengantar)
  → Parser → staging_orders (upsert, dedup by platform_order_id)
  → User preview di /app/staging
  → Approve → production orders
  → Reject → skip

SKU Matching & Importer

Designed Phase 1

SKU Matching

Cascade:
1. Exact SKU match → link product_id
2. Not found → item.product_id = nil, flagged "SKU unknown"

TIDAK ADA fuzzy matching di Phase 1.
90% kasus = exact match (seller SKU konsisten).

SKU Importer (Onboarding Produk Cepat)

1. Upload XLSX pesanan 7 hari terakhir
2. System parse → extract SKU unik + nama produk
3. Tabel: SKU | Nama | HPP (user isi) | Harga Jual (user isi)
4. User bulk-fill
5. Confirm → create semua produk (stok = 0)
6. Stok masuk nanti lewat PO

Domain 4: Fulfillment

Phase 1 — Keep Current + Enhance

Phase 1

Current flow (KEEP):
  Packing Session → scan barcode → ship_order()
  ship_order = atomic: status + stok FEFO + jurnal + audit

Enhancement Phase 1:
  + reserved_stock saat order masuk
  + courier_mapping untuk normalize ekspedisi
  + release_reservation saat ship atau cancel

Phase 2 — Full Fulfillment Flow

Phase 2

Outbound Flow

Order masuk → reserve stock
  ↓
FulfillmentOrder (batch orders → 1 dokumen)
  → generate PickList (group by Area + SKU)
  ↓
Kepala Gudang approve (TTD digital)
  ↓
Picker ambil barang → confirm qty_picked
  ↓
Packer scan → verify items → tempel resi → pack
  → TRACK SIAPA YANG PACK (PIC packer)
  ↓
Sort by ekspedisi (via courier_mapping)
  ↓
Courier Handover (manifest TTD staff + driver)
  ↓
Side effects: stock deduction + journal + audit

Inbound Flow — GRN (replace PO Receive)

PO Created → Supplier deliver ke gudang
  ↓
Goods Receipt Note (GRN):
  → Staff cek + hitung fisik
  → Input: qty_received, qty_rejected per item
  → TTD staff gudang + TTD sopir
  ↓
Stock In:
  → Lot created (FEFO: cost + expiry)
  → Journal: Dr. Persediaan / Cr. Hutang atau Kas

12 New Tables

Domain 5: Returns

Implemented

Customer Return / RTS

Order dikirim → detect RTS → return_record
  ↓
RTS Inbound Session:
  ├── Baik   → stok masuk + lot restore + reverse piutang (A3)
  ├── Rusak  → jurnal kerugian (A4)
  └── Hilang → klaim kurir (A5)
  ↓
Klaim Kurir:
  ├── Diterima → A6: Dr. Kas / Cr. Piutang Klaim
  └── Ditolak  → A7: Dr. Beban Kerugian / Cr. Piutang Klaim

Supplier Return

├── Cash PO  → A11: Dr. Kas / Cr. Persediaan
└── Utang PO → A12: Dr. Hutang Usaha / Cr. Persediaan

Domain 6: Intelligence

Phase 3

Platform Differences (KRITIS)

Revenue Formulas (per platform)

Execution Order

Phase 1 — Migrasi v1→v2

Phase 2 — Setelah v2 Live

Phase 3 — Scale

Rules for Executor

1. BACA domain yang relevan SEBELUM koding — jangan asumsi
2. Ikuti execution order — jangan loncat session
3. Per step: implement → compile → test → commit
4. Semua function return {:ok, result} atau {:error, reason}
5. org_id di setiap query — multi-tenant enforced
6. Repo.transaction untuk multi-step — atomic
7. Pattern matching untuk status — gak ada if-else bertingkat
8. Test WAJIB — setiap function punya test
9. Logic di context, BUKAN LiveView
10. Angka JANGAN diasumsi — tanya Hafish
11. JANGAN rewrite dari ingatan — BACA source file dulu
12. WIB timezone — semua datetime +07:00
13. Advisory lock — untuk ID generation
14. Error message bahasa user, bukan teknis
15. SCHEMA → CONTEXT → TEST → SEED → REVIEW → LIVEVIEW
16. JANGAN lanjut layer tanpa checkpoint review