Doc_chelvyn/Mito/Sfa/FDD/FDD_Area_Based_Visibility_C...

605 lines
25 KiB
Markdown
Raw Normal View History

# Functional Design Document (FDD)
## Area-Based Visibility -- CMS
Item Detail
---------- --------------------------------------------
Module CMS -- Reward Management & Master Customer
Feature Area-Based Data Visibility
Version 1.0
Status Draft
Platform CMS
------------------------------------------------------------------------
## 1. Background
CMS memiliki fitur Reward Management yang digunakan oleh karyawan
internal untuk membuat program reward bagi Dealer (Customer/External).
Reward diberikan kepada Dealer berdasarkan penjualan produk dengan IMEI
sebagai referensi klaim.
Setiap karyawan internal memiliki tanggung jawab terhadap satu atau
lebih Area. Relasi Employee dan Area pada Master Employee sudah tersedia
dan menggunakan Many2Many.
Diperlukan pembatasan visibilitas agar employee hanya dapat melihat data
yang relevan dengan Area tanggung jawabnya. Pembatasan berlaku pada
daftar Reward, Master Customer, serta pilihan Customer ketika employee
membuat atau mengubah Product Reward Mapping.
Admin CMS tetap dapat mengakses seluruh Area.
## 2. Objective
1. Membatasi visibilitas Reward berdasarkan Area employee pembuat
Reward **dan** Area Customer yang dipilih pada Reward.
2. Membatasi visibilitas Master Customer berdasarkan Area employee yang
sedang login.
3. Membatasi pilihan Customer pada Product Reward Mapping berdasarkan
Area employee yang sedang login.
4. Mendukung employee dengan lebih dari satu Area.
5. Menerapkan validasi akses pada backend/API, bukan hanya
menyembunyikan data pada frontend.
6. Memberikan Admin CMS akses lintas seluruh Area.
## 3. Scope
### 3.1 In Scope
-----------------------------------------------------------------------
No. Modul Kebutuhan
----------------------- ----------------------- -----------------------
1 Master Employee Menggunakan relasi
Employee--Area
Many2Many yang sudah
tersedia.
2 Reward Management Filter daftar/detail
Reward berdasarkan Area
pembuat Reward dan Area
Customer pada mapping.
3 Master Customer Filter daftar/detail
Customer berdasarkan
Area employee yang
login.
4 Product Reward Mapping Filter dropdown
Customer berdasarkan
Area employee yang
login.
5 Backend/API Validasi hak akses saat
membaca, membuat, dan
mengubah data terkait.
6 CMS Authorization Admin CMS dapat melihat
seluruh Reward dan
Customer.
-----------------------------------------------------------------------
### 3.2 Out of Scope
- Perubahan perhitungan atau nominal Reward.
- Perubahan mekanisme klaim Reward berdasarkan IMEI.
- Perubahan Claim Mode, Jobsheet, atau periode program Reward.
- Perubahan integrasi Reward dengan Odoo 18.
- Perubahan proses approval Reward, kecuali diperlukan untuk mendukung
kontrol akses yang dijelaskan dalam dokumen ini.
## 4. Existing Data Reference
### 4.1 Master Employee
Master Employee sudah memiliki relasi ke Area dengan tipe Many2Many.
Contoh:
Employee Area
---------- ---------------
Andi Jakarta
Saputra Bali
Budi Jakarta, Bali
Sistem menggunakan seluruh Area yang terhubung ke employee aktif sebagai
dasar filtering.
### 4.2 Master Customer
Master Customer perlu memiliki relasi Area yang dapat digunakan untuk
menentukan Area dealer/customer. Jika relasi Area belum tersedia pada
implementasi CMS saat ini, relasi tersebut perlu ditambahkan.
Satu Customer diasumsikan dapat memiliki satu atau lebih Area apabila
kebutuhan bisnis mengizinkan. Jika implementasi bisnis menetapkan satu
Customer hanya untuk satu Area, struktur relasinya dapat tetap mengikuti
desain Master Customer yang berlaku.
### 4.3 Reward dan Product Reward Mapping
Reward memiliki informasi employee pembuat/creator dan Product Reward
Mapping yang menghubungkan produk dengan Customer serta nilai
Reward/IMEI.
Tidak diperlukan penambahan field Area pada header Reward maupun Product
Reward Mapping. Area diperoleh dari relasi Employee pembuat Reward dan
Customer yang dipilih pada mapping.
**Catatan implementasi:** sistem harus dapat mengidentifikasi creator
Reward secara konsisten, misalnya melalui field `created_by` atau relasi
employee yang setara. Jika field tersebut belum tersedia, perlu
dipastikan mekanisme penyimpanan creator sebelum development.
## 5. Functional Requirements
### FR-01 -- Employee Area Reference
- Saat employee login, CMS mengambil identitas employee dan seluruh
Area yang terhubung pada Master Employee.
- Area employee menjadi referensi filtering untuk fitur yang tercakup
dalam dokumen ini.
- Sistem harus mendukung employee dengan beberapa Area.
- Perubahan Area pada Master Employee berlaku pada akses berikutnya
atau setelah mekanisme refresh session/permission yang digunakan
CMS.
### FR-02 -- Reward List Visibility
Reward hanya dapat ditampilkan kepada employee apabila **kedua kondisi**
berikut terpenuhi:
1. Terdapat irisan antara Area employee yang login dan Area employee
pembuat Reward.
2. Terdapat irisan antara Area employee yang login dan Area Customer
yang dipilih pada Product Reward Mapping di dalam Reward tersebut.
Dengan demikian, kecocokan Area creator saja tidak cukup. Kecocokan Area
Customer juga wajib terpenuhi.
**Formula konseptual:**
`Visible Reward = Creator Areas ∩ Logged-in Employee Areas is not empty AND Customer Areas ∩ Logged-in Employee Areas is not empty`
Untuk Reward dengan lebih dari satu Customer mapping, Reward dapat
ditampilkan apabila terdapat minimal satu mapping Customer yang memenuhi
kecocokan Area. Namun, data mapping Customer yang tidak sesuai Area
tetap tidak boleh dibuka atau diakses oleh employee tersebut.
### FR-03 -- Reward Detail and Mapping Visibility
- Employee hanya dapat membuka detail Reward yang lolos FR-02.
- Saat membuka detail Reward, sistem hanya menampilkan Product Reward
Mapping dengan Customer yang Area-nya sesuai dengan Area employee.
- Mapping Customer di luar Area employee tidak boleh terekspos melalui
response API, meskipun Reward induknya terlihat karena memiliki
mapping lain yang sesuai.
- Employee tidak boleh mengakses Reward di luar Area dengan menebak
atau mengubah ID pada URL/request.
### FR-04 -- Master Customer Visibility
- Daftar Master Customer hanya menampilkan Customer yang Area-nya
memiliki irisan dengan Area employee yang login.
- Detail Customer hanya dapat dibuka jika Customer memenuhi aturan
Area tersebut.
- Pencarian, filter, pagination, export, dan endpoint lain yang
mengambil data Customer harus mengikuti pembatasan yang sama.
- Customer di luar Area tidak boleh dapat diakses melalui direct URL
atau request API.
### FR-05 -- Customer Dropdown on Product Reward Mapping
- Pada form Create/Edit Reward, dropdown Customer hanya menampilkan
Customer yang Area-nya sesuai dengan Area employee yang login.
- Opsi pencarian Customer pada dropdown juga harus menerapkan filter
Area.
- Employee tidak dapat menyimpan mapping dengan Customer di luar Area,
termasuk jika ID Customer dikirim secara manual melalui request.
- Validasi dilakukan kembali pada backend saat data disimpan.
### FR-06 -- Admin CMS Access
- Admin CMS dapat melihat seluruh Reward dari semua Area.
- Admin CMS dapat melihat seluruh Customer dari semua Area.
- Dropdown Customer pada Product Reward Mapping untuk Admin CMS
menampilkan seluruh Customer.
- Pengecualian Admin hanya berlaku untuk role Admin CMS yang secara
eksplisit ditetapkan pada konfigurasi otorisasi CMS. Role lain tidak
otomatis memperoleh akses lintas Area.
### FR-07 -- Employee Without Area
- Employee tanpa Area yang terhubung tidak mendapatkan data Reward
atau Customer melalui akses berbasis Area.
- Dropdown Customer untuk employee tersebut tidak menampilkan pilihan
Customer.
- Backend menolak request untuk membaca atau menyimpan data yang
membutuhkan hak akses Area.
- Admin CMS tetap dapat mengakses seluruh data sesuai FR-06.
## 6. Business Rules
-----------------------------------------------------------------------
ID Business Rule
----------------------------------- -----------------------------------
BR-01 Area employee diambil dari relasi
Many2Many pada Master Employee.
BR-02 Reward visibility wajib memenuhi
kecocokan Area Creator dan Area
Customer.
BR-03 Tidak diperlukan field Area
tambahan pada Reward.
BR-04 Area Customer diambil dari relasi
Area pada Master Customer.
BR-05 Customer pada Master Customer hanya
terlihat jika Area Customer
beririsan dengan Area employee yang
login.
BR-06 Dropdown Customer pada Reward
menggunakan aturan filtering yang
sama dengan Master Customer.
BR-07 Employee multi-Area dapat mengakses
data dari seluruh Area yang
dimilikinya.
BR-08 Jika salah satu syarat Reward tidak
terpenuhi, Reward tidak ditampilkan
kepada employee.
BR-09 Untuk Reward dengan beberapa
mapping, minimal satu mapping yang
sesuai dapat membuat Reward tampil;
mapping yang tidak sesuai tetap
disembunyikan dari employee.
BR-10 Admin CMS memiliki akses seluruh
Area.
BR-11 Validasi Area wajib dilakukan pada
backend untuk setiap operasi yang
relevan.
BR-12 Employee tanpa Area tidak
mendapatkan akses data berbasis
Area.
-----------------------------------------------------------------------
## 7. Access Matrix
-----------------------------------------------------------------------
Fitur Employee Single Employee Admin CMS
Area Multi-Area
----------------- ----------------- ----------------- -----------------
Reward List Sesuai aturan Sesuai aturan Semua Area
Creator AND Creator AND
Customer Customer
Reward Detail Hanya Reward yang Hanya Reward yang Semua Area
berhak diakses berhak diakses
Reward Customer Hanya mapping Hanya mapping Semua mapping
Mapping sesuai Area sesuai Area
Master Customer Customer sesuai Customer dari Semua Customer
List Area seluruh Area
miliknya
Customer Detail Sesuai Area Sesuai Area Semua Customer
Customer Dropdown Customer sesuai Customer dari Semua Customer
Area seluruh Area
miliknya
Create/Edit Hanya Customer Hanya Customer Semua Customer
Mapping sesuai Area sesuai Area
-----------------------------------------------------------------------
## 8. Process Flow
### 8.1 Employee Login and Area Retrieval
1. Employee login ke CMS.
2. CMS mengidentifikasi user dan employee yang terkait.
3. CMS mengambil seluruh Area dari relasi Employee--Area.
4. CMS mengidentifikasi role user, termasuk apakah user merupakan Admin
CMS.
5. Sistem menggunakan role dan Area tersebut untuk menerapkan
pembatasan data pada fitur terkait.
### 8.2 Reward List Filtering
1. Employee membuka menu Reward Management.
2. CMS mengambil Area employee yang sedang login.
3. CMS mengambil data Reward beserta creator dan Customer mapping.
4. CMS memeriksa irisan Area employee login dengan Area creator.
5. CMS memeriksa irisan Area employee login dengan Area Customer pada
mapping.
6. Reward ditampilkan jika kedua pemeriksaan terpenuhi.
7. Mapping Customer yang tidak sesuai Area tidak ditampilkan pada
detail Reward.
### 8.3 Master Customer Filtering
1. Employee membuka menu Master Customer.
2. CMS mengambil Area employee yang sedang login.
3. CMS mengambil data Customer.
4. CMS memfilter Customer berdasarkan irisan Area Customer dengan Area
employee.
5. CMS menampilkan hanya Customer yang memenuhi kriteria.
### 8.4 Customer Selection on Reward
1. Employee membuka form Create/Edit Reward.
2. Employee membuka Product Reward Mapping.
3. Employee memilih dropdown Customer.
4. CMS mengambil daftar Customer sesuai Area employee.
5. Employee memilih Customer dari daftar tersebut.
6. Saat penyimpanan, backend memvalidasi ulang Area employee dan
Customer.
7. Jika validasi berhasil, mapping disimpan.
8. Jika tidak valid, penyimpanan ditolak dan sistem menampilkan pesan
kesalahan.
## 9. Technical Design Guidance
Bagian ini merupakan arahan implementasi untuk tim developer. Nama
tabel, field, endpoint, dan struktur query final mengikuti standar serta
struktur database CMS yang sudah berjalan.
### 9.1 Data Relationship
Relasi data konseptual:
- Employee ↔ Area: Many2Many (existing).
- Customer ↔ Area: relasi Area pada Master Customer (existing atau
perlu ditambahkan).
- Reward → Creator Employee: relasi creator yang tersimpan pada
Reward.
- Reward → Product Reward Mapping: One2Many/relasi mapping yang sudah
berjalan.
- Product Reward Mapping → Customer: relasi Customer yang sudah
berjalan.
### 9.2 Filtering Logic
Untuk employee non-admin:
- `employee_area_ids`: seluruh Area employee yang login.
- `creator_area_ids`: seluruh Area employee pembuat Reward.
- `customer_area_ids`: seluruh Area Customer pada mapping.
Reward dapat ditampilkan jika:
- `intersection(employee_area_ids, creator_area_ids)` tidak kosong;
dan
- minimal satu Customer mapping memiliki
`intersection(employee_area_ids, customer_area_ids)` yang tidak
kosong.
Customer dapat ditampilkan jika:
- `intersection(employee_area_ids, customer_area_ids)` tidak kosong.
Untuk Admin CMS, filter Area dilewati sesuai hak akses Admin.
### 9.3 Backend Enforcement
Developer wajib menerapkan pembatasan pada backend/service/API layer
untuk:
- Reward list dan Reward detail.
- Product Reward Mapping list/detail.
- Master Customer list dan detail.
- Customer search/autocomplete/dropdown.
- Create dan update Product Reward Mapping.
- Export atau endpoint lain yang mengembalikan data dari modul
terkait.
Frontend filtering hanya berfungsi untuk pengalaman pengguna dan tidak
boleh menjadi satu-satunya lapisan keamanan.
### 9.4 Create/Edit Validation
Pada saat create atau update Product Reward Mapping:
1. Backend mengambil user/employee dari session atau token
terautentikasi, bukan dari nilai employee yang dikirim bebas oleh
frontend.
2. Backend mengambil Area employee dari Master Employee.
3. Backend mengambil Area Customer yang dipilih.
4. Backend memvalidasi adanya irisan Area.
5. Jika tidak ada irisan, request ditolak.
6. Backend juga memastikan employee berhak mengakses Reward induk
berdasarkan aturan Creator AND Customer.
7. Admin CMS mengikuti pengecualian akses Admin.
### 9.5 Query and Performance Considerations
- Filtering dilakukan di sisi server/database sebelum pagination.
- Search, sorting, dan pagination harus tetap mempertahankan filter
Area.
- Hindari mengambil seluruh data kemudian hanya menyembunyikannya di
frontend.
- Gunakan relasi dan index yang sesuai untuk kolom penghubung
Employee--Area, Customer--Area, Creator Reward, dan Reward Mapping.
- Pastikan perubahan Area employee atau Customer tidak meninggalkan
akses lama yang tidak valid.
## 10. Validation and Error Handling
-----------------------------------------------------------------------
No. Kondisi Expected Result
----------------------- ----------------------- -----------------------
1 Employee memiliki Area Reward tampil.
Jakarta dan Creator
Reward memiliki Area
Jakarta; Customer
memiliki Area Jakarta
2 Employee Area Jakarta; Reward tidak tampil.
Creator Reward Area
Bali; Customer Area
Jakarta
3 Employee Area Jakarta; Reward tidak tampil.
Creator Reward Area
Jakarta; Customer Area
Bali
4 Employee Area Jakarta Reward tampil karena
dan Bali; Creator Area kedua relasi memiliki
Bali; Customer Area irisan dengan Area
Jakarta employee.
5 Employee Area Jakarta; Customer tidak tampil
Customer Area Bali pada Master Customer
dan dropdown.
6 Employee mencoba Request ditolak.
mengirim Customer ID di
luar Area melalui API
7 Employee tidak memiliki Tidak ada data berbasis
Area Area yang ditampilkan.
8 Admin CMS membuka Seluruh data dapat
Reward atau Customer diakses.
lintas Area
9 Reward memiliki dua Reward tampil, tetapi
mapping Customer, satu hanya mapping Customer
Jakarta dan satu Bali; Jakarta yang terlihat.
employee hanya memiliki
Area Jakarta
10 Employee mengubah Backend menolak akses.
URL/ID untuk membuka
Reward di luar Area
-----------------------------------------------------------------------
Pesan kesalahan yang disarankan:
- **Akses data:** "Anda tidak memiliki akses untuk melihat data ini."
- **Validasi Customer:** "Customer yang dipilih tidak termasuk dalam
Area yang menjadi tanggung jawab Anda."
- **Employee tanpa Area:** "Area employee belum ditentukan. Silakan
hubungi Administrator."
## 11. Acceptance Criteria
Development dinyatakan memenuhi kebutuhan apabila:
1. Sistem dapat membaca seluruh Area employee dari relasi Many2Many.
2. Employee hanya melihat Reward yang memenuhi kecocokan Area Creator
dan Area Customer.
3. Employee hanya melihat Customer sesuai Area miliknya.
4. Dropdown Customer pada Product Reward Mapping hanya menampilkan
Customer sesuai Area employee.
5. Backend menolak akses dan penyimpanan data di luar Area.
6. Employee dengan beberapa Area dapat melihat data dari seluruh Area
yang dimilikinya sesuai aturan Reward.
7. Admin CMS dapat melihat seluruh Reward dan Customer.
8. Filter tetap berlaku pada pencarian, pagination, detail, dan export
yang tersedia.
9. Tidak ada field Area baru pada Reward.
10. Sistem tidak membocorkan Customer mapping yang berada di luar Area
employee.
## 12. Test Scenario
-----------------------------------------------------------------------
Test ID Scenario Expected Result
----------------------- ----------------------- -----------------------
TC-01 Login sebagai Andi Reward tampil.
(Jakarta), buka Reward
dari creator Jakarta
dengan Customer Jakarta
TC-02 Login sebagai Andi Reward tidak tampil.
(Jakarta), buka Reward
dari creator Bali
dengan Customer Jakarta
TC-03 Login sebagai Andi Reward tidak tampil.
(Jakarta), buka Reward
dari creator Jakarta
dengan Customer Bali
TC-04 Login sebagai Saputra Reward tampil.
(Bali), buka Reward
dari creator Bali
dengan Customer Bali
TC-05 Login sebagai Budi Reward tampil.
(Jakarta dan Bali),
buka Reward dari
creator Jakarta dengan
Customer Bali
TC-06 Login sebagai Andi, Hanya Customer Jakarta
buka Master Customer yang tampil.
TC-07 Login sebagai Andi, Hanya Customer Jakarta
buka dropdown Customer yang menjadi pilihan.
pada Reward
TC-08 Login sebagai Andi, Request ditolak.
submit Customer Bali
melalui manipulasi API
TC-09 Login sebagai employee Tidak ada data berbasis
tanpa Area Area yang dapat
diakses.
TC-10 Login sebagai Admin CMS Seluruh Reward dan
Customer dapat diakses.
TC-11 Reward memiliki mapping Reward tampil, mapping
Customer Jakarta dan Jakarta saja yang
Bali; login sebagai terlihat.
Andi
TC-12 Employee mencoba Akses ditolak.
membuka Reward di luar
Area melalui direct URL
TC-13 Employee melakukan Customer tidak muncul
pencarian Customer di dalam hasil pencarian.
luar Area
TC-14 Employee menggunakan Hanya data sesuai Area
pagination atau export yang diproses.
-----------------------------------------------------------------------
## 13. Assumptions & Open Points
1. Relasi Employee--Area Many2Many sudah tersedia dan dapat digunakan
oleh CMS.
2. Master Customer memiliki relasi Area atau akan ditambahkan sebagai
bagian dari development ini.
3. Reward memiliki informasi creator yang dapat digunakan untuk
mengambil Area pembuat Reward.
4. Customer yang digunakan dalam Reward berasal dari Master Customer
CMS.
5. Role Admin CMS sudah dapat diidentifikasi oleh mekanisme
authorization CMS.
6. Untuk Reward dengan beberapa Customer mapping, aturan visibility
menggunakan minimal satu mapping yang memenuhi Area; mapping yang
tidak sesuai tetap dibatasi.
7. Perlu dipastikan apakah perubahan Area pada employee atau Customer
harus langsung memengaruhi session aktif atau berlaku setelah
refresh/login ulang.
8. Perlu dipastikan apakah export Reward dan Master Customer sudah
tersedia agar dapat dimasukkan dalam cakupan pengujian.
------------------------------------------------------------------------
**End of Document**