# SUBS Data Mapping Review

Tarikh semakan: 2026-06-04

Dokumen ini membandingkan data manual client dengan struktur modul semasa dalam sistem `SUBS`.

## Sumber data disemak

1. `SUSB - CUSTOMERS DETAIL.xlsx`
2. `SUSB - SEASON COLLN MAR'26.xlsx`

## Ringkasan

Secara keseluruhan, flow sistem `SUBS` sudah selari dengan proses kerja client:

- customer / company master
- season pass billing
- invoice generation
- payment update
- e-invoice request
- LHDN submission
- monthly consolidated

Tetapi dari sudut **parameter data**, sistem semasa masih belum cukup lengkap untuk menampung semua maklumat dalam fail manual client.

Status keseluruhan:

- `Flow bisnes`: `Match`
- `Data parameter`: `Partial`
- `Import readiness`: `Not ready yet`

## Fail 1: `SUSB - CUSTOMERS DETAIL.xlsx`

Sheet aktif yang relevan:

- `16-3-19`

Kolum utama:

- `Lot No`
- `Slot`
- `Total`
- `Company Name`
- `Contact No`
- `Fax No`
- `Attention To`
- `Email Address`

### Mapping ke sistem

| Kolum Excel | Modul / Field sistem | Status | Catatan |
|---|---|---|---|
| `Company Name` | `customer_subscriptions.name` | `Match` | Sudah ada |
| `Contact No` | `customer_subscriptions.phone` | `Match` | Sudah ada |
| `Email Address` | `customer_subscriptions.email` | `Match` | Sudah ada |
| `Lot No` | Tiada | `Missing` | Perlu field baru |
| `Slot` | Tiada | `Missing` | Perlu field baru |
| `Total` | Tiada | `Missing` | Perlu field baru untuk quantity / bay count |
| `Fax No` | Tiada | `Missing` | Perlu field baru jika masih digunakan |
| `Attention To` | Tiada | `Missing` | Perlu field baru untuk contact person |

### Pemerhatian data

- Ada syarikat yang muncul lebih dari sekali.
- Maksudnya satu syarikat boleh ada lebih dari satu lot / bay / slot.
- Struktur sekarang belum cukup jelas untuk simpan multi-bay di bawah customer yang sama.

## Fail 2: `SUSB - SEASON COLLN MAR'26.xlsx`

Sheet aktif yang relevan:

- `Sheet1`

Kolum utama:

- `Report Date`
- `Passcard No`
- `Customer Name`
- `Receipt No`
- `Amount`
- `Month`
- `Payment Purpose`
- `Remarks`

### Mapping ke sistem

| Kolum Excel | Modul / Field sistem | Status | Catatan |
|---|---|---|---|
| `Customer Name` | `invoices.name` / `customer_subscriptions.name` | `Match` | Sudah ada |
| `Amount` | `invoices.amount` | `Match` | Sudah ada |
| `Month` | `invoice_cycle_month` / `commencement_month` / `next_invoice_date` | `Partial` | Dari sudut flow ada, tapi bukan disimpan seperti format manual file |
| `Receipt No` | `invoices.invoice_no` | `Partial` | Boleh guna, tetapi lebih baik ada field receipt khusus |
| `Report Date` | `invoices.txn_date` / `payment_date` | `Partial` | Sudah ada date, tapi perlu tentukan mapping muktamad |
| `Passcard No` | Tiada | `Missing` | Perlu field baru |
| `Payment Purpose` | Tiada | `Missing` | Perlu field baru atau default business rule |
| `Remarks` | Tiada | `Missing` | Perlu field baru untuk payment remarks |

### Pemerhatian data

- `Payment Purpose` dalam sample yang disemak ialah `Season Payment`.
- `Remarks` mengandungi maklumat seperti:
  - `CASH`
  - `ONLINE C760020326172450`
- Ini menunjukkan client sebenarnya simpan sekurang-kurangnya:
  - kaedah bayaran
  - reference transaksi
- Ada `Receipt No` yang berulang pada banyak row.
- Ini menunjukkan satu receipt boleh mewakili lebih dari satu passcard / bay / rekod bayaran.

## Mapping dengan modul semasa

### 1. Customer Subscriptions

Modul ini paling hampir dengan fail `CUSTOMERS DETAIL`.

Field semasa:

- `user_id`
- `site_id`
- `season_pass_package_id`
- `customer_type`
- `ic_passport`
- `tin_no`
- `name`
- `email`
- `phone`
- `car_plate`
- `commencement_month`
- `monthly_amount`
- `status`
- `next_invoice_date`
- `notes`

Status:

- `Sesuai untuk`:
  - nama customer / syarikat
  - phone
  - email
  - package
  - commencement month
  - monthly amount
- `Belum cukup untuk`:
  - passcard
  - lot
  - slot
  - bay quantity
  - fax
  - attention/contact person

### 2. Subs Invoices

Modul ini paling hampir dengan fail `SEASON COLLN`.

Field semasa:

- `invoice_no`
- `txn_date`
- `amount`
- `invoice_status`
- `payment_date`
- `due_date`
- `invoice_cycle_month`
- `receipt_path`
- `car_plate`
- `site_id`
- `customer_user_id`
- `subscription_id`
- `tin_no`
- `status`

Status:

- `Sesuai untuk`:
  - amount
  - date
  - invoice status
  - payment date
  - cycle month
- `Belum cukup untuk`:
  - passcard no
  - receipt no as separate field
  - payment purpose
  - payment method
  - payment reference
  - payment remarks

## Data yang sistem perlukan tetapi fail manual belum lengkap

Untuk flow e-invoice / LHDN, sistem semasa perlukan juga:

- `customer_type`
- `IC / Passport / BRN`
- `TIN`
- `season_pass_package`
- `commencement_month`

Ini bermaksud jika client mahu migrate data manual ke sistem:

- data manual sahaja tidak cukup
- perlu ada enrichment / cleanup tambahan sebelum import

## Gap utama yang perlu ditutup

### Priority 1

Tambah field baru pada `customer_subscriptions`:

- `parking_card_no`
- `lot_no`
- `slot`
- `bay_total`
- `attention_to`
- `fax_no`

### Priority 2

Tambah field baru pada `invoices`:

- `receipt_no`
- `parking_card_no`
- `payment_purpose`
- `payment_method`
- `payment_reference`
- `payment_remarks`

### Priority 3

Tentukan struktur data sebenar:

- satu customer = satu subscription?
- atau satu customer boleh ada banyak passcard?
- atau satu syarikat ada banyak lot/slot dan satu billing account?

Berdasarkan fail manual, kemungkinan besar:

- satu syarikat boleh ada banyak bay / lot
- satu receipt boleh cover banyak bay

Ini mungkin perlukan salah satu pendekatan:

1. tambah field terus pada `customer_subscriptions`
2. tambah table baru khas untuk `subscription_items` / `passcards` / `bays`

## Cadangan teknikal

### Pilihan minimum

Tambah sahaja field berikut pada `customer_subscriptions`:

- `parking_card_no`
- `lot_no`
- `slot`
- `bay_total`
- `attention_to`
- `fax_no`

Dan pada `invoices`:

- `receipt_no`
- `payment_purpose`
- `payment_remarks`

Kelebihan:

- cepat
- kurang refactor

Kekurangan:

- kurang sesuai jika satu customer ada banyak passcard / lot / bay

### Pilihan lebih betul

Tambah table baru contoh:

- `passcards`

Cadangan field:

- `subscription_id`
- `parking_card_no`
- `lot_no`
- `slot`
- `bay_count`
- `status`
- `notes`

Kelebihan:

- lebih dekat dengan data sebenar client
- lebih sesuai untuk satu syarikat dengan banyak bay

Kekurangan:

- perlu ubah UI dan flow lagi

## Kesimpulan akhir

Sistem `SUBS` sekarang:

- sudah betul dari sudut flow proses
- belum cukup lengkap dari sudut struktur data sebenar client

Sebelum user mula guna sistem berdasarkan data manual ini, dicadangkan:

1. tambah field penting yang masih hilang
2. putuskan sama ada passcard / lot / slot perlu jadi table berasingan
3. buat data cleanup untuk:
   - nama syarikat
   - phone
   - email
   - missing BRN / TIN
4. sediakan template import yang ikut struktur final sistem

## Cadangan next step

1. Finalize field tambahan yang wajib
2. Putuskan sama ada guna:
   - `quick patch fields`
   - atau `proper passcard table`
3. Lepas itu baru buat migration, UI, dan import template