Bila Dua Sistem Mula Bercantum, Bukan Integration Yang Susah

Aku sekarang tengah buat satu integration yang agak kompleks.

Ada dua system.

System A ialah system untuk treatment package. Dalam system ni ada package, treatment, staff, agent, leads, booking, online shop dan customer.

System B pula ialah system membership untuk health club.

Pada asalnya, dua-dua system ni tak ada kaitan langsung.

System A ada business dia sendiri.

System B ada business dia sendiri.

Dua-dua berjalan independently.

Tapi sekarang business nak buat satu model baru:

Member daripada System B boleh claim treatment package daripada System A.

Bila dengar macam tu, nampak macam benda biasa.

"Okay, buat API integration."

"System B send member ID."

"System A check member."

"Kalau eligible, create package."

Done.

Sebenarnya tak.

Semakin aku masuk dalam business logic dia, semakin aku nampak bahawa integration tu sendiri bukan benda yang paling susah.

Yang susah ialah nak pastikan dua business model yang sebelum ni hidup sendiri-sendiri boleh bercantum tanpa merosakkan apa yang dah berjalan.

---

Dua system yang asalnya tak perlu kenal antara satu sama lain

Ini penting untuk faham.

System A memang dibina untuk urus business treatment.

System B pula dibina untuk urus membership.

Jadi setiap system ada assumption masing-masing.

Contohnya dalam System A:

• ada customer
• customer boleh beli package
• package ada treatment
• treatment ada berapa session
• package ada value
• customer ada card
• card digunakan dalam operational flow
• customer boleh buat booking
• treatment history disimpan
• staff dan agent terlibat

System B pula ada:

• member
• membership
• wallet / credit
• eligibility
• dan sekarang credit tersebut boleh digunakan untuk mendapatkan sesuatu dalam System A

Jadi bila business cakap:

"Member System B boleh claim package System A."

Sebenarnya kita sedang introduce satu relationship baru antara dua business domain.

Dan relationship tu ada banyak rules.

---

Contoh mudah yang sebenarnya tak mudah

Katakan System A ada tiga package.

Package A

Price: RM500 Value: RM1,000

Package B

Price: RM1,500 Value: RM3,000

Package C

Price: RM5,000 Value: RM10,000

System A memang menggunakan konsep package value.

Member tak semestinya bayar berdasarkan value tersebut.

Ada harga package dan ada value yang package tu represent.

Sekarang System B pula mempunyai wallet atau credit.

Member boleh gunakan credit tersebut untuk claim package tertentu.

Contohnya member ada RM500.

Dia boleh claim Package A.

Lepas claim, credit dia berubah mengikut business rule.

Kemudian dia accumulate lagi.

Bila cukup untuk Package B, dia boleh claim Package B pula.

Kemudian bila cukup untuk Package C, dia boleh claim Package C.

Nampak macam simple.

Tapi sebenarnya kita dah kena jawab banyak soalan.

Apa sebenarnya yang ditolak daripada wallet?

Price?

Value?

Credit?

Apa yang menentukan eligibility?

Berapa kali package boleh di-claim?

Bila claim berlaku, treatment apa yang diberikan?

Macam mana treatment session diperuntukkan?

Apa jadi kalau package berubah selepas member dah claim?

Apa jadi kalau claim berjaya tapi proses create package gagal?

Apa jadi kalau member dah ada customer record dalam System A?

Dan ini baru bahagian claim.

---

Rupanya "claim package" bukan sekadar create package

Ini antara perkara yang aku rasa paling menarik dalam project ni.

Kalau ikut cara paling simple, kita mungkin buat:

Member
   ↓
Claim Package
   ↓
Create Package

Tapi business sebenar lebih dekat kepada:

System B Member
       ↓
Wallet / Credit
       ↓
Eligibility
       ↓
Redemption
       ↓
System A Package
       ↓
Package Value
       ↓
Treatment Allocation
       ↓
Treatment Sessions
       ↓
Card
       ↓
Booking
       ↓
Treatment History

Jadi sebenarnya kita bukan sekadar transfer data antara dua system.

Kita sedang transfer business entitlement daripada satu domain kepada domain yang lain.

Itu jauh lebih besar.

---

Lagi satu masalah: card

System A mempunyai concept yang dipanggil card.

Setiap customer yang mempunyai package akan ada card ID / card number.

Dan card number ni bukan random.

Ia running number.

Contohnya:

10001
10002
10003
10004
10005
...

Masalahnya, business sebelum ni ada reserved number.

Ada nombor tertentu yang memang mereka simpan untuk premium membership atau tujuan lain.

Jadi sebelum ni, cara solve agak straightforward.

Hardcode sahaja:

Kalau nombor ni reserved,
skip.

Masa system masih simple, benda macam ni mungkin boleh hidup.

Tapi bila business process semakin besar, aku dah tak boleh treat card number sebagai sekadar incrementing integer.

Sebab sekarang card number dah menjadi business resource.

---

Jadi aku perlukan Card Inventory

Aku ubah cara fikir.

Daripada:

"System generate card number."

kepada:

"System allocate card daripada inventory."

Ini nampak macam perubahan kecil.

Tapi sebenarnya besar.

Sekarang card boleh ada lifecycle sendiri.

Contohnya:

Available
Reserved
Assigned
Disabled
Released

Jadi management boleh nampak card number mana available, mana reserved dan mana dah digunakan.

Dan system tak perlu lagi tahu:

if ($number === 12345) {
    skip();
}

Sebaliknya system tahu:

"Card ni status Reserved. Jangan allocate."

Itu jauh lebih masuk akal.

Sebab sekarang business rule tersebut duduk sebagai data, bukan hardcoded dalam code.

---

Tapi kemudian jumpa pula repeat customer

Ini satu lagi benda yang nampak kecil pada awalnya.

Ada customer dalam System A yang pernah repeat.

Maksudnya seorang customer boleh ada beberapa card.

Contohnya:

Customer Ali

Card 10001
Card 10057
Card 10231
Card 10455

Kalau aku terus integrate System B tanpa selesaikan benda ni, aku akan ada masalah baru.

Sebab nanti:

System B Member
       ↓
System A Customer
       ↓
New Package
       ↓
New Card

Tapi customer tu mungkin sebenarnya dah wujud dalam System A.

Dan dia mungkin dah ada beberapa card.

Jadi aku tak nak integration baru ni menghasilkan satu lagi identity untuk orang yang sama.

---

Aku decide untuk merge kepada latest card

Untuk repeat customer, aku ubah approach.

Daripada membenarkan customer terus mempunyai banyak active card, aku merge operation dia kepada latest card.

Jadi treatment history dan benda-benda yang berkaitan dengan customer tu boleh berada di satu tempat.

Contohnya:

Customer Ali

Old Card 10001
    ↓
Disabled / Released / Retained

Old Card 10057
    ↓
Disabled / Released / Retained

Latest Card 10231
    ↓
Current
    ├── Package
    ├── Treatment history
    ├── Sessions
    ├── Booking
    └── Entitlement

Old card pula aku tak paksa business untuk decide sekarang.

Management boleh decide kemudian sama ada:

• release card tu balik ke inventory
• kekalkan sebagai disabled
• atau retain untuk historical purpose

Ini bagi aku lebih betul.

Sebab technical system tak patut buat business decision yang management sendiri belum tetapkan.

System patut menyediakan state dan mekanisme.

Management yang tentukan policy.

---

Dan ini secara tak langsung solve masalah masa depan

Ini yang aku suka tentang approach ni.

Aku bukan sekadar solve:

"Macam mana nak integrate System B sekarang?"

Aku sebenarnya sedang solve:

"Apa yang berlaku kalau member System B jadi repeat customer pada masa depan?"

Dan jawapannya dah ada.

Flow dia sekarang boleh jadi:

System B Member
       ↓
Cari existing customer
       ↓
Customer wujud?
   ├── No
   │    ↓
   │  Create customer
   │    ↓
   │  Allocate card
   │
   └── Yes
        ↓
      Gunakan latest/current card
        ↓
      Continue lifecycle

Jadi integration tak perlu mempunyai special logic untuk repeat customer.

Repeat customer behaviour dah menjadi sebahagian daripada core domain System A.

Itu beza antara patch dengan proper implementation.

---

Sebab tu aku rasa integration ni bukan sekadar API integration

Kalau orang tengok dari luar, mungkin nampak:

"Oh, dua system connect."

Tapi dari dalam, sebenarnya kita sedang buat beberapa benda serentak:

1. Identity resolution

Siapa sebenarnya customer ni?

Member System B ni adakah customer yang sama dalam System A?

---

2. Entitlement management

Member berhak dapat apa?

Berapa kali?

Berdasarkan credit apa?

---

3. Wallet / credit accounting

Berapa credit digunakan?

Berapa balance tinggal?

Apa transaction yang berlaku?

---

4. Package lifecycle

Package tu dah claim?

Active?

Consumed?

Expired?

---

5. Treatment allocation

Package tu mempunyai treatment apa?

Berapa session?

Macam mana value package diagihkan?

---

6. Card lifecycle

Card mana yang digunakan?

Card mana reserved?

Card mana active?

Card mana disabled?

Card mana boleh dilepaskan balik?

---

7. Historical data

Apa jadi kepada card lama?

Apa jadi kepada treatment history?

Macam mana kita pastikan history tak pecah kepada beberapa identity?

---

8. Backward compatibility

System A dah digunakan sebelum integration.

Kita tak boleh simply redesign semuanya dan anggap database kosong.

Ada existing customer.

Ada existing package.

Ada existing card.

Ada existing booking.

Ada existing treatment history.

Semua tu kena terus hidup.

---

Ini sebenarnya masalah yang selalu tak nampak masa mula develop

Bila kita develop system baru, kita selalu nampak requirement macam:

"Customer boleh beli package."

Jadi kita buat customer.

Package.

Order.

Booking.

Done.

Kemudian business berkembang.

Customer boleh repeat.

Member dari system lain boleh claim.

Package boleh mempunyai value yang berbeza daripada selling price.

Ada premium card number.

Ada reserved card.

Ada existing customer yang mempunyai multiple card.

Ada business rule baru.

Dan tiba-tiba system yang dulu nampak simple mula mempunyai banyak state.

Bukan sebab developer tak pandai.

Tapi sebab business memang dah berubah.

Software cuma perlu catch up.

---

Mujur kedua-dua system ni aku yang develop

Ini honestly salah satu advantage terbesar dalam project ni.

Kalau System A aku develop dan System B dibangunkan oleh vendor lain, complexity dia boleh naik berkali ganda.

Aku mungkin kena deal dengan:

API documentation
API limitations
Unknown database structure
Unknown business rules
Unknown data assumptions
Unknown edge cases
Version compatibility
Vendor dependency

Dan paling bahaya:

aku tak tahu apa yang aku tak tahu.

Kadang-kadang API boleh bagi data.

Tapi kita tak tahu kenapa data tu macam tu.

Atau kita tahu endpoint dia.

Tapi kita tak tahu business rule yang vendor letak di belakang endpoint tersebut.

Dalam kes aku, aku boleh buka kedua-dua system.

Aku tahu database.

Aku tahu code.

Aku tahu flow.

Aku tahu kenapa sesuatu dibuat macam tu.

Dan lebih penting, aku boleh ubah kedua-dua system kalau architecture asal memang tak lagi sesuai dengan business baru.

Itu bagi aku jauh lebih valuable daripada sekadar "boleh buat API integration".

---

Aku sekarang lebih banyak fikir tentang business invariant

Bila system dah sampai tahap macam ni, aku rasa cara fikir developer kena berubah.

Jangan hanya fikir:

"Function ni nak buat apa?"

Tapi mula fikir:

"Apa benda yang mesti sentiasa benar dalam business ni?"

Contohnya:

Seorang customer tak sepatutnya mempunyai dua active operational card.

Card yang reserved tak boleh diberikan kepada customer.

Member tak boleh claim package kalau credit tak mencukupi.

Satu package claim tak boleh berlaku dua kali kalau business rule kata hanya sekali.

Treatment history mesti kekal berkait dengan customer yang betul.

Card lama tak boleh hilang begitu sahaja kerana ia mungkin mempunyai historical significance.

Bila kita mula tulis benda macam ni, architecture jadi lebih jelas.

Kita bukan lagi sekadar build CRUD.

Kita sedang membina system yang enforce business rules.

---

Integration yang baik bukan semestinya integration yang paling banyak API

Aku rasa ini misconception yang selalu berlaku.

Bila orang dengar integration, mereka terus fikir:

System A → API → System B

Tapi dalam project sebenar, API mungkin bahagian paling mudah.

Yang susah ialah menentukan:

System A
   ↕
Business rules
   ↕
System B

Apa yang boleh masuk?

Apa yang boleh keluar?

Siapa source of truth?

Bila data dianggap valid?

Siapa yang menentukan ownership?

Siapa yang menentukan balance?

Siapa yang menentukan entitlement?

Dan bila berlaku conflict, siapa yang menang?

Kalau benda ni tak jelas, integration boleh technically "berjaya" tetapi business operation rosak.

---

Dua system tak semestinya perlu jadi satu system

Ini pun satu benda yang aku cuba jaga.

Aku tak nak sebab System A dan System B dah integrate, terus semua benda dicampurkan.

System B masih bertanggungjawab untuk membership.

System A masih bertanggungjawab untuk treatment.

Jadi conceptually:

System B
Membership
Wallet
Credit
     │
     │ entitlement / redemption
     ▼
System A
Package
Treatment
Card
Booking
History

Setiap system masih ada domain masing-masing.

Integration hanya menjadi bridge antara kedua-duanya.

Bagi aku ini lebih sustainable.

Sebab kalau satu hari nanti business tambah system C, kita tak perlu runtuhkan semua benda.

Kita cuma define relationship baru.

---

Yang paling menarik sebenarnya ialah business sedang berkembang

Aku rasa ini part yang paling best daripada project ni.

Kalau business tak berkembang, aku tak perlu buat semua ni.

System A boleh kekal macam dulu.

System B boleh kekal macam dulu.

Tapi bila sales naik dan business mula buat model baru, software kena ikut.

Dan bila sales semakin naik, perkara yang sebelum ni boleh dibuat secara manual mula menjadi masalah.

Reserved card number mungkin dulu boleh maintain secara manual.

Repeat customer mungkin dulu boleh settle seorang demi seorang.

Package claim mungkin dulu tak wujud.

Tapi bila volume meningkat, semua benda tu perlu menjadi system behaviour.

Ini bagi aku antara tanda paling jelas bahawa sebuah system sedang outgrow design asalnya.

Bukan semestinya sebab system tu buruk.

Tetapi sebab business dah lebih besar daripada assumption yang digunakan masa system tu dibina.

---

Jadi, adakah integration ni complex?

Ya.

Tapi bukan kerana:

"API dia susah."

Bukan juga sebab:

"Code dia banyak."

Complexity datang daripada business rules yang saling bergantung.

Satu perubahan kecil boleh memberi kesan kepada beberapa domain.

Contohnya bila kita decide:

"Repeat customer tak boleh ada multiple active card."

Terus affected:

• customer
• card
• card inventory
• package
• treatment history
• booking
• future System B redemption

Itulah complexity sebenar.

---

Dan mungkin ini lesson paling besar untuk aku

Bila aku mula buat system dulu, aku banyak fikir tentang:

"Macam mana nak build feature ni?"

Sekarang aku semakin banyak fikir:

"Apa business model yang sebenarnya sedang cuba kita represent?"

Sebab bila business model dah jelas, implementation biasanya lebih mudah.

Tapi kalau business model masih kabur, developer boleh tulis code sampai beribu-ribu line pun system tetap rasa fragile.

Dalam project macam ni, tugas developer bukan hanya:

ambil requirement → tulis code.

Kadang-kadang tugas kita ialah:

ambil business yang semakin kompleks → faham relationship dia → pecahkan kepada domain yang jelas → kemudian baru translate kepada software.

Dan bila kita buat benda tu dengan betul, integration bukan lagi sekadar "connect two systems".

Kita sebenarnya sedang membina operating model baru untuk business tersebut.

Dan bagi aku, itu jauh lebih menarik.