AbelBirdNest-Stock/docs/purchase-realization-design.md

Purchase Realization Design

Tujuan

Menyediakan model data dan alur kalkulasi untuk melacak satu purchase dari:

• pembelian awal
• receipt menjadi lot
• washing
• regrade / mix / split
• regular sale
• consignment
• office buyout

sampai status akhir purchase dapat dinyatakan CLOSED dan laba/rugi agent dapat dihitung final.

Prinsip

• Purchase Analysis tetap dipakai sebagai snapshot awal pembelian.
• Purchase Realization dipakai sebagai hasil aktual setelah barang bergerak dan terjual.
• Setiap lot harus bisa dilacak asal purchase-nya, termasuk jika hasil mix atau regrade.
• Setiap event yang memengaruhi qty atau nilai harus menulis jurnal realization.

Model Baru

lot_purchase_allocations

Menyimpan komposisi asal purchase untuk setiap lot.

Contoh:

• Lot LOT-A berasal 100% dari purchase P-1
• Lot LOT-B hasil mix dari P-1 40% dan P-2 60%

Maka LOT-B memiliki 2 allocation rows.

Kolom penting:

• lot_id
• purchase_id
• purchase_line_id
• source_type
• source_ref_id
• qty_allocated
• cost_total_allocated
• unit_cost_snapshot
• agent_id_snapshot
• profit_share_scheme_id_snapshot

purchase_realization_entries

Ledger event yang memengaruhi hasil akhir purchase.

Kolom penting:

• purchase_id
• lot_id
• allocation_id
• event_type
• reference_type
• reference_id
• occurred_at
• qty_in
• qty_out
• qty_shrinkage
• amount_cost
• amount_revenue
• amount_expense
• amount_profit
• agent_share_percent_snapshot
• agent_amount

Event type awal yang direkomendasikan:

• OPENING_COST
• WASHING_COST
• WASHING_SHRINKAGE
• TRANSFORMATION_SHRINKAGE
• SALE_REVENUE
• SALE_RETURN
• SALE_SHRINKAGE
• CONSIGNMENT_REVENUE
• CONSIGNMENT_RETURN
• CONSIGNMENT_SHRINKAGE
• OFFICE_BUYOUT_REVENUE
• OFFICE_BUYOUT_TRANSFER_OUT
• STOCK_ADJUSTMENT_LOSS
• STOCK_ADJUSTMENT_GAIN
• MANUAL_ADJUSTMENT

purchase_realization_summaries

Cache summary per purchase untuk kebutuhan UI dan closing.

Kolom penting:

• status
• qty_opening
• qty_remaining
• qty_sold
• qty_returned
• qty_shrinkage
• cost_opening_total
• cost_additional_total
• revenue_total
• profit_loss_total
• agent_share_percent
• agent_profit_total
• closed_at

Status yang direkomendasikan:

• OPEN
• PARTIAL
• READY_TO_CLOSE
• CLOSED

Aturan Alokasi

Purchase submit

• Buat lot seperti implementasi saat ini.
• Buat 1 allocation row per lot:
  • source_type = PURCHASE
  • qty_allocated = lot.original_qty
  • cost_total_allocated = qty * unit_cost
• Buat 1 realization entry:
  • event_type = OPENING_COST

Washing selesai

• Allocation lot tidak berubah.
• Jika ada biaya cuci, tulis WASHING_COST.
• Jika ada susut, tulis WASHING_SHRINKAGE.
• Semua entry dibagi ke purchase asal berdasarkan allocation aktif lot tersebut.

Transformation / regrade / mix

• Baca allocation dari semua source lots.
• Bentuk allocation baru pada output lots dengan distribusi proporsional terhadap qty / cost input.
• Jika ada processing loss, buat TRANSFORMATION_SHRINKAGE.
• Output lot mewarisi allocation campuran dari input.

Regular sale close

• Baca allocation lot pada line yang dijual.
• Revenue aktual dibagi ke purchase asal sesuai allocation.
• Tulis:
  • SALE_REVENUE
  • SALE_RETURN
  • SALE_SHRINKAGE

Consignment close

• Perlakuan sama seperti regular sale, tetapi sumber event adalah consignment line.

Office buyout

Untuk purchase lama:

• Tulis OFFICE_BUYOUT_REVENUE
• qty_out sebesar qty yang dibeli kantor
• amount_revenue = qty * buyout_unit_price

Untuk lot baru hasil buyout:

• Buat allocation baru yang menunjuk purchase buyout / jalur kantor
• Setelah itu hasil jual berikutnya tidak lagi menjadi hak agent lama

Rumus Summary

• cost_opening_total = total opening cost
• cost_additional_total = washing cost + biaya tambahan + adjustment
• revenue_total = sale + consignment + office buyout
• profit_loss_total = revenue_total - cost_opening_total - cost_additional_total
• agent_profit_total = akumulasi agent_amount atau fallback profit_loss_total * share_agent / 100

Rule Closing Purchase

Purchase dapat CLOSED jika seluruh qty asal purchase sudah terselesaikan menjadi salah satu:

• terjual
• susut
• dibuyout kantor
• habis masuk transformasi dan seluruh descendant lots-nya selesai

Artinya closing harus melihat seluruh lineage lot, bukan hanya lot awal purchase.

Scope Implementasi Bertahap

Tahap 1

• Tambah schema baru
• Isi allocation + opening realization saat purchase submit
• Tambah summary recalculation dasar

Tahap 2

• Integrasi office buyout
• Integrasi washing cost dan shrinkage

Tahap 3

• Integrasi transformation / mix / regrade allocation propagation

Tahap 4

• Integrasi regular sale dan consignment revenue realization

Tahap 5

• UI Purchase Realization
• closing otomatis

Tahap 6

• JIT sale, jika nanti ingin ditautkan ke lineage purchase