25 KiB
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
- Membatasi visibilitas Reward berdasarkan Area employee pembuat Reward dan Area Customer yang dipilih pada Reward.
- Membatasi visibilitas Master Customer berdasarkan Area employee yang sedang login.
- Membatasi pilihan Customer pada Product Reward Mapping berdasarkan Area employee yang sedang login.
- Mendukung employee dengan lebih dari satu Area.
- Menerapkan validasi akses pada backend/API, bukan hanya menyembunyikan data pada frontend.
- 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:
- Terdapat irisan antara Area employee yang login dan Area employee pembuat Reward.
- 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
- Employee login ke CMS.
- CMS mengidentifikasi user dan employee yang terkait.
- CMS mengambil seluruh Area dari relasi Employee--Area.
- CMS mengidentifikasi role user, termasuk apakah user merupakan Admin CMS.
- Sistem menggunakan role dan Area tersebut untuk menerapkan pembatasan data pada fitur terkait.
8.2 Reward List Filtering
- Employee membuka menu Reward Management.
- CMS mengambil Area employee yang sedang login.
- CMS mengambil data Reward beserta creator dan Customer mapping.
- CMS memeriksa irisan Area employee login dengan Area creator.
- CMS memeriksa irisan Area employee login dengan Area Customer pada mapping.
- Reward ditampilkan jika kedua pemeriksaan terpenuhi.
- Mapping Customer yang tidak sesuai Area tidak ditampilkan pada detail Reward.
8.3 Master Customer Filtering
- Employee membuka menu Master Customer.
- CMS mengambil Area employee yang sedang login.
- CMS mengambil data Customer.
- CMS memfilter Customer berdasarkan irisan Area Customer dengan Area employee.
- CMS menampilkan hanya Customer yang memenuhi kriteria.
8.4 Customer Selection on Reward
- Employee membuka form Create/Edit Reward.
- Employee membuka Product Reward Mapping.
- Employee memilih dropdown Customer.
- CMS mengambil daftar Customer sesuai Area employee.
- Employee memilih Customer dari daftar tersebut.
- Saat penyimpanan, backend memvalidasi ulang Area employee dan Customer.
- Jika validasi berhasil, mapping disimpan.
- 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:
- Backend mengambil user/employee dari session atau token terautentikasi, bukan dari nilai employee yang dikirim bebas oleh frontend.
- Backend mengambil Area employee dari Master Employee.
- Backend mengambil Area Customer yang dipilih.
- Backend memvalidasi adanya irisan Area.
- Jika tidak ada irisan, request ditolak.
- Backend juga memastikan employee berhak mengakses Reward induk berdasarkan aturan Creator AND Customer.
- 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:
- Sistem dapat membaca seluruh Area employee dari relasi Many2Many.
- Employee hanya melihat Reward yang memenuhi kecocokan Area Creator dan Area Customer.
- Employee hanya melihat Customer sesuai Area miliknya.
- Dropdown Customer pada Product Reward Mapping hanya menampilkan Customer sesuai Area employee.
- Backend menolak akses dan penyimpanan data di luar Area.
- Employee dengan beberapa Area dapat melihat data dari seluruh Area yang dimilikinya sesuai aturan Reward.
- Admin CMS dapat melihat seluruh Reward dan Customer.
- Filter tetap berlaku pada pencarian, pagination, detail, dan export yang tersedia.
- Tidak ada field Area baru pada Reward.
- 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
- Relasi Employee--Area Many2Many sudah tersedia dan dapat digunakan oleh CMS.
- Master Customer memiliki relasi Area atau akan ditambahkan sebagai bagian dari development ini.
- Reward memiliki informasi creator yang dapat digunakan untuk mengambil Area pembuat Reward.
- Customer yang digunakan dalam Reward berasal dari Master Customer CMS.
- Role Admin CMS sudah dapat diidentifikasi oleh mekanisme authorization CMS.
- Untuk Reward dengan beberapa Customer mapping, aturan visibility menggunakan minimal satu mapping yang memenuhi Area; mapping yang tidak sesuai tetap dibatasi.
- Perlu dipastikan apakah perubahan Area pada employee atau Customer harus langsung memengaruhi session aktif atau berlaku setelah refresh/login ulang.
- Perlu dipastikan apakah export Reward dan Master Customer sudah tersedia agar dapat dimasukkan dalam cakupan pengujian.
End of Document