# MASTER BLUEPRINT ENTERPRISE SYSTEM
## Django + Next.js for Multi-Module Enterprise Platform
### Volume 1 — Foundation, Domain Architecture, and Module Blueprint

**Versi:** 1.0  
**Target organisasi:** perusahaan dengan kompleksitas menengah-besar, multi unit, pertumbuhan modul bertahap, kebutuhan kontrol internal kuat, dan skala penjualan tahunan sekitar triliunan rupiah.  
**Stack utama:** Django, Django REST Framework, PostgreSQL, Redis, Celery, Next.js, TypeScript.

---

## Cara Menggunakan Dokumen Ini

Dokumen ini disusun sebagai **blueprint implementasi**, bukan sekadar artikel konsep. Setiap bagian dirancang agar bisa dipakai untuk:

- menyelaraskan pemahaman stakeholder
- menjadi acuan desain sistem
- menuntun pembuatan ERD dan API
- menjadi dasar coding backend dan frontend
- menjadi dasar penyusunan test scenario
- menjadi referensi ekspansi modul di masa depan

Dokumen ini fokus pada dua pondasi terberat:

1. **Foundation Architecture**  
   Menentukan prinsip sistem, batasan, pola otorisasi, pola modul, pola data, dan keputusan teknis kunci.

2. **Domain Blueprint**  
   Menentukan isi dan batas tiap modul, entitas inti, alur utama, transaksi, status, relasi, dan kontrol penting.

> Dokumen ini sengaja mendahulukan fondasi dan domain sebelum detail endpoint atau coding final, karena kesalahan terbesar pada proyek enterprise biasanya terjadi saat tim melompat ke implementasi tanpa desain domain yang disiplin.

---

## Tujuan Utama Sistem

Sistem yang dibangun ditujukan untuk menjadi **platform operasi perusahaan** yang dapat berkembang menjadi tulang punggung proses bisnis lintas fungsi, meliputi:

- pembelian
- master data
- governance
- penjualan
- biaya
- inventory
- finance
- modul pendukung lain sesuai pertumbuhan perusahaan

Sistem ini harus memiliki karakteristik:

- modular
- aman
- auditable
- scalable
- context-aware
- mendukung approval
- mendukung multi-role user
- siap berkembang dari 3 modul awal menjadi sistem enterprise yang utuh

---

## Prinsip Besar Dokumen Ini

1. **Jangan mulai dari layar, mulai dari domain bisnis.**
2. **Jangan mulai dari menu, mulai dari authorization object.**
3. **Jangan tempel permission ke user, tempel ke role.**
4. **Jangan anggap frontend sebagai pengaman utama.**
5. **Jangan membangun modul seolah berdiri sendiri; pikirkan integrasi sejak awal.**
6. **Jangan mengejar “selesai cepat” dengan mengorbankan fondasi data dan kontrol.**
7. **Jangan membuat governance sebagai tempat “admin sakti”.**
8. **Jangan mengunci desain untuk 3 modul saja; rancang agar bisa tumbuh.**

---

## Daftar Isi Ringkas

1. Visi dan cakupan sistem
2. Prinsip arsitektur inti
3. Pola modul dan bounded context
4. Model authorization enterprise
5. Prinsip data, transaksi, audit, dan workflow
6. Blueprint domain per modul
7. Cross-module integration map
8. Roadmap transformasi dari 3 modul ke full platform
9. Checklist keputusan teknis sebelum coding besar

# 1. Visi dan Cakupan Sistem

## 1.1 Visi Sistem

Visi sistem ini adalah menjadi **enterprise operations platform** yang menyatukan proses utama perusahaan dalam satu kerangka kendali yang konsisten. Sistem ini bukan hanya tempat input transaksi, tetapi juga:

- alat kontrol operasional
- alat kontrol approval
- alat kontrol keuangan
- alat kontrol master data
- alat audit
- alat pelaporan berbasis data yang terpercaya

Dengan kata lain, sistem harus mampu menjawab dua pertanyaan sekaligus:

1. **Bagaimana transaksi berjalan?**
2. **Bagaimana transaksi dikendalikan?**

Jika sistem hanya menjawab pertanyaan pertama, ia menjadi aplikasi operasional biasa.  
Jika ia menjawab keduanya, ia mulai mendekati kelas ERP yang sehat.

## 1.2 Cakupan Bertahap

### Tahap awal
- Purchasing
- Master Data
- Governance

### Tahap ekspansi
- Sales
- Inventory
- Costing / Expense
- Finance

### Tahap lanjutan
- Fixed Asset
- Treasury
- CRM
- Service
- HR integration
- Reporting and BI
- Integration hub

## 1.3 Tujuan Bisnis yang Harus Didukung

Sistem harus membantu perusahaan mencapai beberapa tujuan berikut:

- mempercepat proses transaksi tanpa melemahkan kontrol
- menurunkan kesalahan input dan duplikasi data
- memperjelas tanggung jawab per peran
- memastikan approval berjalan sesuai aturan
- memastikan data master terkendali
- memungkinkan laporan lebih cepat dan akurat
- memudahkan audit internal dan eksternal
- memungkinkan pertumbuhan modul tanpa refactor total

## 1.4 Ciri Perusahaan yang Cocok

Blueprint ini cocok untuk perusahaan yang:

- memiliki banyak transaksi antar fungsi
- memiliki lebih dari satu unit / divisi / cabang / entitas
- memiliki kebutuhan approval dan pembatasan akses
- ingin mengurangi ketergantungan pada spreadsheet dan proses manual
- ingin membangun platform internal yang bertahan lama

## 1.5 Cakupan yang Tidak Dibahas Mendalam di Volume Ini

Agar dokumen tetap terfokus, beberapa topik berikut hanya disentuh garis besar:
- desain UI rinci per layar
- contoh setiap endpoint API secara lengkap
- CI/CD detail
- observability stack detail
- data warehouse / BI model
- mobile app strategy

Topik-topik itu sebaiknya menjadi volume lanjutan setelah fondasi domain dan authorization stabil.

# 2. Prinsip Arsitektur Inti

## 2.1 Arsitektur Harus Tahan Tumbuh

Kesalahan umum saat membangun sistem internal:
- dianggap hanya untuk tim kecil
- dianggap hanya untuk 3 modul
- dianggap proses bisnis akan tetap sederhana

Akibatnya:
- logic dicampur di view/controller
- role hardcode
- relasi antar modul tidak disiplin
- data context tidak disimpan dari awal
- approval ditambal belakangan

Blueprint ini menolak pendekatan tersebut.

### Prinsip:
Bangun sistem yang **sederhana untuk mulai**, tetapi **tidak menghukum pertumbuhan**.

## 2.2 Monolith Modular Lebih Tepat daripada Microservices di Awal

Untuk tahap ini, rekomendasi terbaik adalah:
- **modular monolith** di backend
- API tunggal
- database utama tunggal dengan skema dan disiplin domain yang kuat

Kenapa?
- transaksi lintas modul masih rapat
- tim biasanya belum cukup besar
- kompleksitas operasional microservices terlalu tinggi
- kebutuhan utamanya adalah konsistensi bisnis, bukan distribusi sistem

### Kapan mulai mempertimbangkan pemecahan layanan?
- beban transaksi sudah tinggi per domain tertentu
- kebutuhan deploy terpisah sudah nyata
- tim sudah terbagi per domain dengan matang
- bottleneck arsitektur monolith sudah terbukti, bukan sekadar asumsi

## 2.3 Layering yang Direkomendasikan

Backend Django sebaiknya dibagi menjadi layer:

- **Models** → struktur data
- **Selectors / Queries** → pembacaan data
- **Services** → business logic dan transaksi
- **Permissions / Authorization** → hak akses
- **Serializers / DTO logic** → validasi transport layer
- **Views / ViewSets** → orchestration tipis
- **Tasks** → asynchronous processing non-critical path

Frontend Next.js sebaiknya dibagi menjadi:

- **routing**
- **layouts**
- **page containers**
- **domain components**
- **table/form components**
- **hooks**
- **API clients**
- **permission-aware navigation**
- **state layer seperlunya**

## 2.4 Database sebagai Sumber Kebenaran Operasional

Untuk sistem jenis ini, database transaksi operasional adalah sumber kebenaran.  
Laporan dan cache boleh menyederhanakan, tetapi tidak boleh menggantikan kebenaran transaksi.

Karena itu:
- definisi status harus jelas
- field context harus ada
- referensi master harus disiplin
- audit tidak boleh diabaikan
- side effect transaksi harus tercatat

## 2.5 Hindari Arsitektur yang Terlalu “UI-Driven”

Sering terjadi:
- modul dibentuk berdasarkan menu
- security berdasarkan visibility menu
- workflow berdasarkan tombol di halaman
- data model mengikuti layout form

Pendekatan ini salah untuk sistem enterprise.

Yang benar:
- menu mengikuti domain
- UI mengikuti workflow
- endpoint mengikuti action bisnis
- data model mengikuti objek bisnis
- security mengikuti role-object-action-context

# 3. Pola Modul dan Bounded Context

## 3.1 Kenapa Perlu Bounded Context?

Jika semua modul dibiarkan saling bebas memanggil dan menyimpan logic tanpa batas, maka:
- definisi data menjadi kabur
- otoritas kepemilikan data hilang
- perubahan satu modul merusak modul lain
- audit dan integrasi menjadi sulit

Karena itu tiap modul harus punya **bounded context**:
- batas tanggung jawab
- objek utama
- aturan bisnis utama
- event utama
- integrasi yang diizinkan

## 3.2 Bounded Context yang Direkomendasikan

### Governance
Pemilik rule sistem, authorization, approval rule, delegasi tertentu, audit rule.

### Master Data
Pemilik master yang dipakai lintas modul, seperti vendor, customer, item, category, company, business unit.

### Purchasing
Pemilik proses pengadaan barang/jasa dari request sampai pemesanan.

### Sales
Pemilik siklus order penjualan sampai invoice penjualan.

### Inventory
Pemilik pergerakan stok, saldo, reservasi, receiving, issue, transfer, adjustment.

### Expense / Costing
Pemilik biaya operasional, pengalokasian biaya, reimbursement tertentu, posting biaya, analitik biaya.

### Finance
Pemilik pencatatan keuangan final, journal, AR/AP control, cash/bank, reconciliation, close period.

## 3.3 Hubungan Antarmodul

Setiap modul harus tahu:
- data apa yang dimiliki sendiri
- data apa yang hanya direferensikan
- event apa yang dikonsumsi
- status apa yang mengunci tindakan di modul lain

Contoh:
- Purchasing boleh mereferensikan Vendor dari Master Data
- Purchasing tidak boleh menjadi pemilik data Vendor
- Finance boleh mereferensikan Purchase Order dan Vendor, tapi tidak boleh mengedit logika purchasing
- Inventory boleh menerima efek dari PO dan SO, tapi tetap menjadi pemilik stok

## 3.4 Prinsip Kepemilikan Data

Setiap entitas harus punya “rumah” utama.

Contoh:
- Vendor → Master Data
- Purchase Request → Purchasing
- Sales Order → Sales
- Stock Ledger → Inventory
- Journal Entry → Finance
- Approval Rule → Governance

Kalau aturan ini dilanggar, sistem akan cepat kacau.

# 4. Model Authorization Enterprise

## 4.1 Struktur Dasar

Model hak akses yang dipakai:

```text
User → Role → Authorization Object → Action → Context
```

Ini berarti:
- user bisa punya banyak role
- role terdiri dari izin terhadap object tertentu
- izin selalu terkait action tertentu
- izin dapat dibatasi context tertentu

## 4.2 Kenapa Bukan User → Permission Langsung?

Karena jika permission ditempel ke user:
- pemeliharaan meledak
- audit sulit
- role ganda sulit dikelola
- revocation berantakan
- SoD sulit dipantau

## 4.3 Authorization Object Bukan Menu

Authorization object adalah **fungsi bisnis** atau **objek bisnis**, bukan tampilan.

Contoh yang benar:
- PURCHASE_REQUEST
- PURCHASE_ORDER
- SALES_ORDER
- VENDOR
- JOURNAL_ENTRY
- APPROVAL_RULE

Contoh yang keliru:
- MENU_PURCHASE
- PAGE_VENDOR
- BUTTON_APPROVE

## 4.4 Action Standar

Gunakan vocabulary action yang stabil dan dipahami bersama.  
Tidak semua object perlu semua action, tetapi kamus aksi sebaiknya konsisten.

Contoh action standar:
- CREATE
- READ
- UPDATE
- DELETE
- SUBMIT
- APPROVE
- REJECT
- CANCEL
- ISSUE
- RECEIVE
- POST
- REVERSE
- ASSIGN
- CLOSE
- OPEN
- EXPORT
- CONFIRM

## 4.5 Context

Context menjawab:
**“boleh melakukan action ini pada data milik siapa / unit mana / periode apa?”**

Contoh context:
- company_code
- business_unit_code
- warehouse_code
- department_code
- branch_code
- cost_center_code
- fiscal_period
- document_owner
- sales_org
- plant

## 4.6 Row-level Security Mindset

Authorization bukan hanya:
- user boleh masuk modul

Tetapi juga:
- data mana yang boleh terlihat
- transaksi mana yang boleh diproses
- dokumen siapa yang boleh diapprove
- unit mana yang boleh dikelola

## 4.7 Segregation of Duties (SoD)

Dalam perusahaan dengan kebutuhan kontrol internal tinggi, role design harus mempertimbangkan konflik seperti:
- membuat vendor dan mengapprove pembayaran vendor
- membuat PR dan mengapprove PO sendiri tanpa kontrol
- membuat jurnal dan memposting reversal sendiri tanpa pembatasan
- mengelola role sendiri lalu memberi akses ke diri sendiri

SoD tidak harus full engine di awal, tetapi desain role harus memberi ruang untuk pengendalian konflik.

## 4.8 Temporary Assignment dan Delegation

Karena dunia nyata tidak statis, model role harus mendukung:
- role sementara
- delegation approver
- penugasan lintas unit sementara
- assignment berbasis masa berlaku

Ini sangat penting untuk operasional nyata.

# 5. Prinsip Data, Transaksi, Audit, dan Workflow

## 5.1 Status Bukan Ornamen

Di sistem enterprise, status adalah mekanisme kontrol.  
Status harus menjawab:
- apa kondisi dokumen sekarang
- aksi apa yang masih diperbolehkan
- modul mana yang boleh melanjutkan proses
- kapan data menjadi mengikat

Contoh status PR:
- DRAFT
- SUBMITTED
- UNDER_REVIEW
- APPROVED
- REJECTED
- CANCELLED

## 5.2 Dokumen vs Ledger

Banyak modul memiliki dua bentuk data:
1. **dokumen operasional**
2. **catatan efek / ledger / journal / movement**

Contoh:
- Sales Order = dokumen
- Stock Movement = ledger
- Journal Entry = ledger finansial

Jangan campurkan keduanya tanpa disiplin.

## 5.3 Audit Log

Audit minimal harus bisa menjawab:
- siapa melakukan apa
- kapan
- terhadap entitas apa
- sebelum dan sesudah perubahan utama

Untuk beberapa area sensitif, audit juga sebaiknya melacak:
- approval
- penolakan
- perubahan master data kritikal
- perubahan role assignment
- perubahan approval rule

## 5.4 Workflow Harus Eksplisit

Workflow tidak boleh “terbentuk sendiri” dari kombinasi tombol di UI.  
Workflow harus didefinisikan secara eksplisit:
- status asal
- action
- validasi
- role yang boleh
- status tujuan
- side effect

## 5.5 Side Effect Harus Terkendali

Contoh side effect:
- PR approved memungkinkan pembuatan PO
- PO issued menghasilkan kebutuhan receiving
- Sales order confirmed membuat stock reservation
- Expense posted membuat journal entry
- Inventory adjustment posted memengaruhi stock ledger

Side effect harus melalui service layer, bukan terjadi liar di banyak tempat.

# 6. Module Blueprint — Governance


Governance adalah modul kendali sistem. Ia tidak menghasilkan transaksi bisnis utama seperti pembelian atau penjualan, tetapi menentukan **siapa boleh melakukan apa**, **rule approval seperti apa**, dan **bagaimana kontrol sistem dijaga**.

### Tujuan Modul
- mengelola role bisnis
- mengelola assignment role ke user
- mengelola approval rule
- mengelola delegasi tertentu
- menyediakan audit visibility
- menjaga agar kontrol sistem tidak bocor

### Entitas Inti
- Role
- User Role Assignment
- Authorization Object
- Role Permission
- Role Context Rule
- Approval Rule
- Delegation Rule
- Audit Log
- Policy / Setting tertentu

### Catatan Penting
Governance bukan tempat semua setting campur aduk. Modul ini harus disiplin dan dipisahkan antara:
- authorization
- approval governance
- audit visibility
- system policy operasional

### Role Tipikal
- Governance Admin
- Security Admin
- Auditor
- Workflow Admin

### Risiko Besar
- governance dijadikan super admin dumping ground
- role diberikan terlalu luas
- audit hanya bisa dilihat admin tertentu tanpa kontrol
- approval rule diubah sembarangan tanpa histori

### Desain Domain
#### Role
Kumpulan tanggung jawab bisnis. Role harus berbasis fungsi, bukan hanya jabatan formal.

#### Authorization Object
Daftar objek yang diamankan. Harus stabil, mudah dipahami, dan dipakai lintas backend/frontend/testing.

#### Role Permission
Relasi role dengan object dan action.

#### Role Context Rule
Pembatas scope data untuk role tertentu.

#### Approval Rule
Menentukan siapa yang boleh approve transaksi tertentu berdasarkan:
- modul
- object
- nilai
- unit
- company
- kondisi lain seperlunya

#### Delegation Rule
Mendukung approver pengganti sementara.

### Alur Utama
1. Governance admin membuat / mengubah role
2. Governance admin menghubungkan role dengan permission
3. Governance admin menetapkan context rule
4. Governance admin menetapkan approval rule
5. Role di-assign ke user
6. Semua modul lain membaca hasil rule ini saat runtime

### Keputusan Penting
- perubahan role dan rule harus diaudit
- role assignment sebaiknya punya masa berlaku opsional
- approval rule sebaiknya tidak di-hardcode di transaksi
- modul governance tidak boleh memodifikasi transaksi bisnis operasional secara langsung

# 6. Module Blueprint — Master Data


Master Data adalah modul yang memegang data referensi lintas modul. Kualitas modul ini menentukan kualitas seluruh sistem.

### Tujuan Modul
- menjaga konsistensi entitas referensi
- menghindari duplikasi data inti
- menjadi sumber data standar lintas modul

### Entitas Inti
- Company
- Business Unit
- Branch
- Department
- Warehouse
- Vendor
- Customer
- Item
- Item Category
- UOM
- Currency
- Tax Code
- Cost Center
- Chart of Account reference tertentu
- Payment Term
- Price List reference tertentu

### Prinsip Penting
Master Data bukan hanya tempat CRUD. Ia adalah pusat kualitas data. Karena itu perlu:
- rule validasi
- status aktif/nonaktif
- histori tertentu untuk data kritikal
- approval untuk perubahan sensitif bila dibutuhkan

### Domain Bounded Context
Master Data memiliki data, modul lain hanya mereferensikan.

Contoh:
- Purchasing boleh memakai Vendor
- Sales boleh memakai Customer
- Inventory boleh memakai Item dan Warehouse
- Finance boleh memakai Currency, Tax Code, CoA reference
Tetapi kepemilikan utama tetap di Master Data

### Risiko Besar
- vendor dibuat dari modul purchasing tanpa kontrol
- item dikelola dari modul inventory tanpa governance
- customer dibuat bebas dari sales tanpa standardisasi
- kode master tidak konsisten
- data tidak pernah dinonaktifkan, hanya dibiarkan menggantung

### Desain Master yang Direkomendasikan
#### Company
Entitas legal / operasional tingkat atas.
#### Business Unit
Unit bisnis di bawah company.
#### Warehouse
Lokasi stok dan transaksi inventory.
#### Vendor
Penyedia barang/jasa.
#### Customer
Pelanggan / pihak penjualan.
#### Item
Barang / jasa / SKU utama.
#### UOM
Satuan ukur.
#### Payment Term
Aturan termin pembayaran.
#### Tax Code
Referensi perpajakan transaksi.

### Pattern Penting
- master penting punya `code`, `name`, `is_active`
- master tertentu punya approval atau review
- referensi antar modul selalu melalui foreign key atau reference code yang disiplin

### Strategi Evolusi
Mulai dari master yang paling dibutuhkan:
- company
- business unit
- vendor
- customer
- item
- warehouse
- currency
Lalu berkembang ke cost center, project, tax, CoA, dan lain-lain.

# 6. Module Blueprint — Purchasing


Purchasing mengelola proses pengadaan dari kebutuhan sampai pemesanan, dan nantinya terhubung ke receiving, AP, dan inventory.

### Tujuan Modul
- menangkap kebutuhan pembelian
- mengatur approval kebutuhan
- menghasilkan dokumen pembelian resmi
- mengontrol vendor dan nilai pembelian
- menjadi sumber dokumen bagi inventory receiving dan finance AP

### Entitas Inti
- Purchase Request (PR)
- Purchase Request Line
- Purchase Order (PO)
- Purchase Order Line
- Vendor Quotation (opsional)
- Purchase Approval Record
- Purchase Terms reference
- Receiving reference link
- Invoice Matching reference

### Alur Tingkat Tinggi
1. user membuat Purchase Request
2. PR disubmit
3. PR direview/diapprove
4. PR yang valid dapat dijadikan PO
5. PO diissue ke vendor
6. PO dipakai untuk receiving
7. PO dan receiving dipakai untuk invoice matching dan AP

### Status yang Direkomendasikan
#### Purchase Request
- DRAFT
- SUBMITTED
- UNDER_REVIEW
- APPROVED
- REJECTED
- CANCELLED
- CLOSED

#### Purchase Order
- DRAFT
- PENDING_APPROVAL
- APPROVED
- ISSUED
- PARTIALLY_RECEIVED
- FULLY_RECEIVED
- CLOSED
- CANCELLED

### Aturan Penting
- draft masih bisa diubah
- submitted tidak boleh diubah bebas
- approved PR tidak otomatis selesai; ia menjadi sumber PO
- PO yang sudah issued harus punya kontrol perubahan
- receiving tidak boleh melebihi kuantitas/aturan toleransi tertentu
- PO closed tidak boleh dimodifikasi kecuali melalui mekanisme khusus

### Integrasi
- Vendor dari Master Data
- Approval Rule dari Governance
- Receiving ke Inventory
- Invoice/Payable ke Finance

### Risiko Besar
- approval PR dan PO dicampur
- purchasing bisa membuat vendor sembarangan
- dokumen approved masih bisa diedit bebas
- tidak ada jejak siapa approve apa
- hubungan PR-PO-receiving tidak konsisten

### Domain Note
PR menangkap kebutuhan internal.  
PO menangkap komitmen pembelian ke vendor.  
Jangan campur dua konsep ini.

# 6. Module Blueprint — Sales


Sales mengelola proses order penjualan dari penerimaan permintaan pelanggan sampai pengiriman dan penagihan.

### Tujuan Modul
- mengelola customer order
- mengontrol harga, diskon, dan komitmen pengiriman
- menjadi sumber demand untuk inventory
- menjadi sumber invoice penjualan untuk finance

### Entitas Inti
- Sales Quotation (opsional)
- Sales Order (SO)
- Sales Order Line
- Delivery Order / Shipment Request
- Sales Invoice reference
- Return / Credit Note reference
- Price / Discount control reference

### Alur Tingkat Tinggi
1. customer request / quotation
2. sales order dibuat
3. sales order direview/confirmed
4. stok diresevasi / dicek ketersediaannya
5. pengiriman diproses
6. invoice dibuat
7. AR diproses oleh finance

### Status yang Direkomendasikan
#### Sales Order
- DRAFT
- SUBMITTED
- CONFIRMED
- PARTIALLY_DELIVERED
- FULLY_DELIVERED
- INVOICED
- CLOSED
- CANCELLED

### Aturan Penting
- harga dan diskon tertentu perlu approval
- order tidak boleh dikonfirmasi jika data customer atau item invalid
- integrasi stok harus jelas: reserve vs available stock
- pengiriman dan invoice tidak boleh berdiri sendiri tanpa acuan yang sah
- retur harus ditangani sebagai dokumen terpisah dengan jejak jelas

### Integrasi
- Customer, Item, Payment Term dari Master Data
- Stock allocation dari Inventory
- AR dan Invoice dari Finance
- Approval untuk diskon / limit dari Governance

### Risiko Besar
- sales bisa override harga tanpa kontrol
- invoice dibuat tanpa dasar pengiriman / order sah
- stok negatif karena reservasi tidak jelas
- customer master tidak terkontrol

# 6. Module Blueprint — Inventory


Inventory mengelola keberadaan stok secara operasional. Modul ini harus menjadi pemilik pergerakan stok dan saldo yang dipercaya.

### Tujuan Modul
- melacak stok masuk, keluar, transfer, adjustment
- memisahkan stok available, reserved, damaged, in-transit sesuai kebutuhan
- menjadi sumber saldo stok operasional
- mendukung receiving dari purchasing dan fulfillment dari sales

### Entitas Inti
- Warehouse
- Stock Item Balance
- Stock Movement
- Goods Receipt
- Goods Issue
- Transfer Order
- Stock Adjustment
- Reservation
- Batch/Lot/Serial (opsional sesuai kebutuhan)

### Prinsip Penting
Inventory harus berbasis movement ledger, bukan hanya menyimpan “saldo akhir” tanpa histori.  
Saldo akhir bisa dihitung / dipelihara, tetapi ledger movement harus ada.

### Alur Sumber Pergerakan
- receiving dari PO
- issue untuk sales
- transfer antar gudang
- adjustment manual terkontrol
- return
- stock opname adjustment

### Status / Kontrol
- DRAFT
- POSTED
- CANCELLED
- REVERSED
untuk dokumen movement tertentu

### Integrasi
- Purchasing menghasilkan kebutuhan receiving
- Sales menghasilkan kebutuhan reservation dan issue
- Finance / Costing bisa menggunakan valuation / movement summary
- Governance mengontrol siapa boleh adjustment

### Risiko Besar
- stok diubah langsung tanpa movement
- receiving tidak terkait PO
- shipment tidak terkait SO
- adjustment dijadikan jalan pintas
- tidak ada separation antara available dan reserved stock

### Catatan Penting
Jika perusahaan besar dan pertumbuhan transaksi tinggi, inventory accuracy adalah area kritikal.  
Kesalahan di sini akan menyebar ke penjualan, pembelian, dan keuangan.

# 6. Module Blueprint — Expense and Costing


Modul Expense dan Costing menangani biaya operasional dan, bila diperlukan, alokasi biaya ke unit, cost center, proyek, atau produk.

### Tujuan Modul
- mencatat biaya operasional non-pembelian utama
- mengelola reimbursement / petty cash tertentu
- mengalokasikan biaya ke struktur analitik
- menyediakan dasar analisa biaya
- menyiapkan data untuk posting ke finance

### Entitas Inti
- Expense Claim / Expense Request
- Expense Category
- Expense Allocation
- Cost Center
- Cost Allocation Rule
- Petty Cash Transaction (opsional)
- Accrual Request (opsional)
- Costing Snapshot / Allocation Result

### Batas Domain
Modul ini bukan full accounting, tetapi menjadi jembatan antara biaya operasional dan pencatatan finansial.

### Alur Tingkat Tinggi
1. biaya diajukan / dicatat
2. biaya direview / diapprove
3. biaya dialokasikan ke cost center / unit
4. biaya diposting ke finance

### Risiko Besar
- semua biaya dilempar langsung ke finance tanpa struktur operasional
- cost center tidak konsisten
- alokasi dilakukan manual di luar sistem
- tidak ada jejak hubungan biaya dengan approval

### Integrasi
- Master Data: expense category, cost center, company, employee reference bila ada
- Governance: approval rule
- Finance: journal posting dan AP/cash impact

# 6. Module Blueprint — Finance


Finance adalah modul pencatatan finansial dan kontrol akuntansi. Ia menerima efek dari modul operasional dan mengelolanya menjadi catatan keuangan formal.

### Tujuan Modul
- mengelola journal entry
- mengelola AP/AR
- mengelola cash/bank tertentu
- mengelola posting dan reversal
- mengelola period control
- menjaga integritas laporan keuangan

### Entitas Inti
- Journal Entry
- Journal Line
- Account / Chart of Account
- Accounts Payable Document
- Accounts Receivable Document
- Payment / Receipt
- Bank / Cash Account
- Fiscal Period
- Reconciliation Record
- Tax Posting reference

### Prinsip Penting
Finance tidak boleh menjadi tempat input liar semua transaksi.  
Sebisa mungkin finance menerima transaksi yang sudah sah dari modul operasional, lalu memproses efek akuntansinya.

### Alur Tingkat Tinggi
- purchasing / expense menghasilkan payable candidate
- sales menghasilkan receivable candidate
- inventory dan costing dapat menghasilkan valuation / COGS effect
- finance melakukan posting, payment, receipt, reconciliation, close

### Status dan Kontrol
- DRAFT
- READY_TO_POST
- POSTED
- REVERSED
- CLOSED
tergantung entitas

### Risiko Besar
- jurnal bisa diedit sesudah posting tanpa kontrol
- period control tidak ada
- AP dan AR tidak terhubung ke dokumen sumber
- posting dilakukan manual tanpa referensi jelas
- reversal tidak teraudit

### Integrasi
- Purchasing
- Sales
- Expense
- Inventory
- Governance
- Master Data

### Catatan
Untuk organisasi sebesar target kamu, finance sebaiknya dibangun dengan kontrol period dan posting discipline sejak awal, walaupun fiturnya bertahap.

# 7. Cross-Module Integration Map

## 7.1 Prinsip Integrasi

Integrasi antarmodul harus menjawab:
- siapa pemilik data sumber
- siapa pemilik efek turunan
- kapan sebuah dokumen dianggap cukup sah untuk memicu modul lain
- bagaimana mencegah side effect ganda

## 7.2 Peta Integrasi Inti

### Purchasing → Inventory
PO yang approved dan issued menjadi dasar receiving.  
Receiving tidak boleh berdiri sendiri tanpa referensi yang sah, kecuali ada skenario khusus yang dikontrol.

### Purchasing / Expense → Finance
Invoice vendor, biaya, atau payable candidate diposting ke finance melalui jalur terkontrol.

### Sales → Inventory
Sales order confirmed dapat membuat reservation.  
Delivery / shipment mengurangi stok melalui movement inventory.

### Sales → Finance
Invoice penjualan menghasilkan AR.  
Receipt dan settlement dikelola di finance.

### Inventory → Finance / Costing
Movement tertentu dapat menjadi dasar valuation, COGS, atau jurnal tertentu, tergantung tingkat kedalaman implementasi.

### Governance → Semua Modul
Semua modul memakai:
- role assignment
- permission
- approval rule
- audit visibility

### Master Data → Semua Modul
Semua modul mereferensikan data master yang disetujui.

## 7.3 Event Penting yang Sebaiknya Diakui dalam Desain

Walaupun belum memakai event bus penuh, secara konsep sistem harus mengenali event seperti:
- purchase_request_submitted
- purchase_request_approved
- purchase_order_issued
- goods_received
- sales_order_confirmed
- goods_issued
- expense_approved
- journal_posted
- payment_recorded

Mendefinisikan event secara konseptual sejak awal akan membantu jika nanti sistem berkembang.

# 8. Roadmap Transformasi dari 3 Modul ke Full Platform

## 8.1 Tahap 1 — Foundation and Control
Modul:
- Governance
- Master Data
- Purchasing

Target:
- role dan permission stabil
- object/action/context stabil
- purchase flow dasar berjalan
- master data inti stabil
- approval rule dasar stabil

## 8.2 Tahap 2 — Revenue and Stock
Modul:
- Sales
- Inventory

Target:
- order-to-delivery flow
- reservation dan stock movement
- integrasi item/customer/warehouse
- dasar kontrol fulfillment

## 8.3 Tahap 3 — Cost and Finance Core
Modul:
- Expense / Costing
- Finance

Target:
- AP/AR dasar
- journal posting dasar
- cash/bank dasar
- expense approval
- posting dari modul operasional

## 8.4 Tahap 4 — Control Deepening
Tambahan:
- SoD rule formal
- advanced audit
- period close
- reconciliation
- stock opname flow
- return management
- price / discount governance

## 8.5 Tahap 5 — Scale and Optimization
Tambahan:
- performance tuning
- background job optimization
- report snapshot
- notification engine
- integration adapter
- BI / analytics feeds

## 8.6 Prinsip Rollout
Jangan menunggu semua modul sempurna baru dipakai.  
Lebih baik:
- rilis per domain yang sudah terkendali
- pertahankan kontrak integrasi yang disiplin
- lakukan hardening sebelum modul berikutnya

# 9. Keputusan Teknis yang Harus Dibakukan Sebelum Coding Besar

## 9.1 Identitas dan Kode
Setiap entitas penting harus punya:
- id internal
- code / nomor bisnis bila relevan

## 9.2 Standar Timestamp dan Audit
Setiap tabel utama minimal punya:
- created_at
- updated_at
- created_by bila perlu
- updated_by bila relevan

## 9.3 Status Vocabulary
Tim harus menyepakati vocabulary status.  
Hindari tiap modul membuat istilah sendiri untuk makna yang mirip.

## 9.4 Numbering Strategy
Dokumen bisnis seperti PR, PO, SO, GR, JE perlu strategi penomoran:
- unik
- bisa dibaca
- tidak bentrok antar unit jika diperlukan
- jelas apakah sequence global atau per company / per tahun

## 9.5 Soft Delete vs Inactive
Untuk master data, lebih aman pakai:
- `is_active`
daripada hard delete.

Untuk transaksi, hampir selalu hindari hard delete.

## 9.6 Approval Rule Storage
Approval rule jangan di-hardcode di frontend.  
Rule harus ada di backend / data governance.

## 9.7 UoM, Currency, Tax
Walaupun implementasi awal sederhana, entitas ini sebaiknya sudah dipikirkan dari awal agar tidak menyulitkan saat scale.

## 9.8 Posting Discipline
Jika modul finance akan dibangun, tentukan sejak awal:
- apa arti “posted”
- siapa boleh post
- kapan reversal boleh dilakukan
- bagaimana hubungan posting dengan perubahan dokumen sumber

## 9.9 Background Jobs
Tentukan sejak awal mana yang synchronous, mana yang asynchronous.

Contoh asynchronous:
- email / notification
- report generation
- recalculation berat
- integrasi ke sistem lain

Contoh yang sebaiknya synchronous:
- validasi inti transaksi
- authorization
- perubahan status utama

## 9.10 Observability Minimal
Walaupun belum canggih, pastikan:
- error logging ada
- request tracing minimal ada
- audit perubahan penting ada

# 10. Rekomendasi Struktur Django dan Next.js Tingkat Tinggi

## 10.1 Struktur Django yang Direkomendasikan

```text
apps/
  accounts/
  authorization/
  governance/
  master_data/
  purchasing/
  sales/
  inventory/
  expense/
  finance/
shared/
  db/
  exceptions/
  utils/
  types/
```

Setiap app sebaiknya memiliki pola:
- models.py
- services.py
- selectors.py
- permissions.py
- serializers.py
- views.py
- tests/

## 10.2 Struktur Next.js yang Direkomendasikan

```text
src/
  app/
  modules/
    purchasing/
    sales/
    inventory/
    finance/
    governance/
    master-data/
  components/
  lib/
    api/
    auth/
    permissions/
  hooks/
  types/
```

### Prinsip Frontend
- page mengikuti domain
- komponen reusable dipisah dari domain-specific components
- guard menu dan route berbasis permission summary
- validasi UI membantu pengguna, tapi backend tetap final authority

## 10.3 Permission-aware Frontend
Frontend sebaiknya menerima summary akses seperti:
- role user
- module visibility
- action visibility ringkas
- unit context summary seperlunya

Namun frontend **tidak boleh** menjadi satu-satunya enforcement.

## 10.4 API Design Mindset
API harus berbicara dalam bahasa domain:
- create purchase request
- submit purchase request
- approve purchase request
- create purchase order
- confirm sales order
- post journal

Bukan sekadar CRUD generik tanpa makna.

# 11. Role Families yang Direkomendasikan

Agar role tidak meledak liar, gunakan family role.

## 11.1 Operational Roles
Contoh:
- Purchasing Staff
- Sales Admin
- Warehouse Staff
- Expense Submitter

## 11.2 Supervisory Roles
Contoh:
- Purchasing Supervisor
- Sales Supervisor
- Warehouse Supervisor

## 11.3 Managerial / Approver Roles
Contoh:
- Purchasing Manager
- Finance Approver
- Sales Manager

## 11.4 Master Data Roles
Contoh:
- Vendor Master Admin
- Item Master Admin
- Master Data Reviewer

## 11.5 Governance Roles
Contoh:
- Governance Admin
- Security Admin
- Workflow Admin
- Auditor

## 11.6 Finance Roles
Contoh:
- AP Officer
- AR Officer
- GL Officer
- Treasury Staff
- Finance Manager

## 11.7 Prinsip Pembentukan Role
- berbasis tanggung jawab nyata
- hindari role campur aduk tanpa alasan
- hindari terlalu granular di awal
- dukung multi-role user
- siapkan masa berlaku assignment

# 12. Checklist Kelayakan Desain Sebelum Masuk Implementasi Besar

Gunakan checklist ini sebelum tim masuk sprint implementasi besar.

## 12.1 Domain
- Apakah semua modul punya batas tanggung jawab jelas?
- Apakah ownership data tiap entitas jelas?
- Apakah status tiap dokumen sudah didefinisikan?

## 12.2 Authorization
- Apakah daftar authorization object sudah ada?
- Apakah action vocabulary sudah disepakati?
- Apakah minimal context inti sudah disepakati?
- Apakah role family sudah dirancang?

## 12.3 Data
- Apakah entitas master inti sudah ditetapkan?
- Apakah transaksi punya field context yang cukup?
- Apakah dokumen dan ledger dibedakan?

## 12.4 Workflow
- Apakah status transition utama sudah jelas?
- Apakah approval rule akan dibaca dari data, bukan hardcode?
- Apakah side effect transaksi utama sudah diidentifikasi?

## 12.5 Integrasi
- Apakah hubungan Purchasing-Inventory-Finance jelas?
- Apakah hubungan Sales-Inventory-Finance jelas?
- Apakah hubungan Governance dengan semua modul jelas?

## 12.6 Teknologi
- Apakah custom user model sudah diputuskan?
- Apakah strategi modular monolith diterima tim?
- Apakah strategi background job sudah ditentukan garis besarnya?

Jika checklist ini belum stabil, coding besar sebaiknya ditahan.

# 13. Kesimpulan Volume 1

Volume ini membangun hal yang paling menentukan keberhasilan sistem enterprise:

- visi sistem yang benar
- arsitektur inti yang sehat
- bounded context per modul
- pola authorization yang scalable
- pemahaman status, workflow, audit, dan side effect
- peta integrasi lintas modul
- roadmap pertumbuhan dari 3 modul ke platform penuh

Dengan fondasi ini, tim tidak lagi memulai dari “halaman apa yang dibuat”, tetapi dari:
- domain apa yang dimiliki
- rule apa yang dijalankan
- data apa yang dikendalikan
- role apa yang boleh bertindak
- modul mana yang menjadi sumber kebenaran

Ini adalah perbedaan antara aplikasi internal biasa dan platform enterprise yang bisa bertahan.

---

## Langkah Lanjutan yang Direkomendasikan

Sesudah Volume 1, dokumen berikut yang paling natural dibuat adalah:

1. **Volume 2 — Functional Specification and Workflow**
   - fitur rinci per modul
   - state transition table
   - approval path
   - validation rule

2. **Volume 3 — Access Control Matrix and Authorization Pack**
   - daftar role final awal
   - object-action-context matrix
   - SoD rule awal
   - seeding strategy

3. **Volume 4 — ERD Global and Django Implementation**
   - ERD lintas modul
   - Django models rinci
   - service layer pattern
   - DRF permission integration

4. **Volume 5 — API Contract and Next.js Application Structure**
   - endpoint contract
   - frontend module map
   - navigation and page guard
   - forms, tables, detail pages

5. **Volume 6 — Testing, Deployment, and Scale Strategy**
   - UAT
   - permission testing
   - release checklist
   - operational readiness

Dokumen ini bisa menjadi dasar semua volume lanjutan tersebut.