Doc_chelvyn/Mito/Sfa/Fitur/SFA CMS — Area-Based Visibi...

147 lines
10 KiB
Markdown
Raw Permalink Normal View History

---
judul: SFA CMS — Area-Based Visibility (Reward, Employee External & Master Customer)
proyek: SFA CMS
terkait: Mito · SFA Reward
stack: Laravel 11 · Filament 3 · MySQL
kategori: Fitur
status: Ter-deploy dev 03-11-2026 (cms 377b146, d644d3f, 185eb1e — Jenkins)
tipe: dokumen-internal
tags:
- sfa
- cms
- reward
- hak-akses
diperbarui: 2026-11-03
---
> Index: [[SFA — Index]] · Kategori: **Fitur** · FDD: [[FDD_Area_Based_Visibility_CMS]]
>
> Implementasi FDD Area-Based Visibility v1.0 (permintaan Oliver 02-11-2026: "filter transaksi dan master customer
> untuk internal based on area"). Employee internal hanya melihat Reward Program, baris Product Reward Mapping, dan
> Master Customer yang sesuai Area-nya; Admin CMS melihat semua.
> **Berbeda dari FDD:** lihat [[#Keputusan di luar FDD]].
# SFA CMS — Area-Based Visibility
## Alur Visibilitas Reward Program
```mermaid
flowchart TD
A["User internal buka Reward Program<br/>(list / detail / edit / export / URL id manual)"] --> B{"Role super_admin?"}
B -- "ya" --> OK1["Semua Reward + semua baris mapping"]
B -- "tidak" --> C{"Punya Area?<br/>employee.user_id → employee_area"}
C -- "tidak" --> E1["Tidak ada data<br/>'Area employee belum ditentukan.<br/>Silakan hubungi Administrator.'<br/>Tombol Create disembunyikan"]
C -- "ya" --> D{"Area creator (created_by → employee_area)<br/>beririsan dengan Area user?"}
D -- "tidak" --> E2["Reward tidak tampil<br/>(edit via URL → 404)"]
D -- "ya" --> F{"Reward punya baris dengan<br/>customer spesifik?"}
F -- "tidak (belum ada baris /<br/>hanya 'Semua dealer')" --> OK2["Reward tampil<br/>(keputusan di luar FDD)"]
F -- "ya" --> G{"Minimal 1 customer se-Area?<br/>Area di Employee External<br/>(registrasi terakhir dealer)"}
G -- "tidak" --> E2
G -- "ya" --> OK3["Reward tampil<br/>Baris customer luar Area disembunyikan<br/>(tabel, jumlah Products, export)"]
classDef ok fill:#d1fae5,stroke:#059669,color:#064e3b
classDef err fill:#fee2e2,stroke:#dc2626,color:#7f1d1d
class OK1,OK2,OK3 ok
class E1,E2 err
```
Hijau = data tampil · Merah = ditolak / tidak tampil.
## Alur Simpan Baris Product Reward Mapping
```mermaid
flowchart TD
A["Create / Edit baris mapping<br/>(pilih Customer)"] --> B{"Customer diisi?"}
B -- "tidak" --> OK["Tersimpan<br/>(baris 'Semua dealer')"]
B -- "ya" --> C{"Akun dealer?<br/>EXTERNAL, APPROVED, bukan staff"}
C -- "tidak" --> E1["Ditolak: 'Hanya akun dealer ...'"]
C -- "ya" --> D{"super_admin, atau customer dealer<br/>se-Area user login?"}
D -- "tidak" --> E2["Ditolak: 'Customer yang dipilih tidak termasuk<br/>dalam Area yang menjadi tanggung jawab Anda.'"]
D -- "ya" --> F{"Bentrok dengan baris ACTIVE lain?<br/>(RewardMappingOverlap)"}
F -- "ya" --> E3["Ditolak: pesan bentrok"]
F -- "tidak" --> OK
classDef ok fill:#d1fae5,stroke:#059669,color:#064e3b
classDef err fill:#fee2e2,stroke:#dc2626,color:#7f1d1d
class OK ok
class E1,E2,E3 err
```
Dropdown Customer sudah disaring dengan aturan yang sama. Validasi server di atas menahan ID yang dikirim manual (TC-08).
## Sumber Area
| Data | Area diambil dari | Catatan |
|---|---|---|
| User login | `employee.user_id` → **`employee_area`** (tabel baru, many2many) | Tanpa employee / tanpa Area → tidak dapat data |
| Creator Reward | `reward_program.created_by` (= `users.id`) → employee → `employee_area` | Terisi otomatis saat save (sudah ada sebelumnya) |
| Customer di baris mapping | `reward_product_mapping.user_id` = user **Employee External** → Area di menu Employee External (`customer_registration.area_id` registrasi terakhir) | **Bukan** Master Customer (koreksi `d644d3f`). Dealer tanpa Area di Employee External hanya terlihat oleh Admin |
| Staff dealer (menu Employee External) | Area dealer induknya (`staff_registration.dealer_user_id`) | |
| Master Customer | `customer.area_id` | Tunggal, tidak diubah |
| Admin CMS | role `super_admin` Shield (`config('filament-shield.super_admin.name')`) | Role lain tidak otomatis lintas Area |
## Keputusan di luar FDD
| # | Kondisi | FDD | Implementasi | Alasan |
|---|---|---|---|---|
| K1 | Employee–Area | "Sudah many2many" | DB ternyata hanya `employee.area_id` tunggal → dibuat tabel **`employee_area`**, diisi dari `area_id` lama. Field **Area** di form Employee jadi multi-select. `area_id` tetap disinkron ke salah satu Area (dipertahankan kalau masih dipilih, selain itu Area pertama) | `employee.area_id` dibaca login SFA Mobile (`serviceLogin.js`) — mobile tidak berubah |
| K2 | Reward tanpa customer spesifik (belum ada baris / hanya baris "Semua dealer") | Rumus FDD → tidak tampil untuk non-admin | Cukup cocok Area creator | Kalau ikut FDD, pembuat Reward langsung 404 setelah klik Create. Belum dikonfirmasi user — dipakai opsi rekomendasi |
| K3 | Baris "Semua dealer" di detail Reward | Tidak diatur | Tetap terlihat & bisa diedit oleh employee yang bisa membuka Reward-nya | Baris itu tidak punya customer, jadi tidak ada Area customer yang dibocorkan |
| K4 | Import Excel Reward Program | Tidak diatur | **Khusus Admin CMS** (dikonfirmasi user 03-11-2026). Export (semua & terpilih) ikut filter Area | Import bisa mengubah program & baris lintas Area |
| K5 | Employee tanpa Area membuat Reward | Tidak diatur | Tombol Create disembunyikan (`canCreate`) | Reward-nya tidak akan terlihat siapa pun selain Admin (FR-07) |
## File yang Diubah (sfa-cms)
| File | Perubahan |
|---|---|
| `database/migrations/2026_11_03_000001_create_employee_area_table.php` | Tabel `employee_area` (unique `employee_id, area_id`, index `area_id`) + salin `employee.area_id`; idempotent |
| `app/Services/AreaAccess.php` | **Baru.** Semua aturan: `bypasses`, `areaIds`, `scopeCustomers`, `scopeDealers`, `scopeMappings`, `scopePrograms`, `canUseDealer`. Berupa klausa query → ikut pagination, search, export antrean, resolve record by id |
| `app/Models/Employee.php` | Relasi `areas()` + `syncPrimaryArea()` |
| `app/Filament/Resources/EmployeeResource.php` + `Pages/CreateEmployee.php`, `Pages/EditEmployee.php` | Area multi-select; `area_id`/`area_code` diisi lewat `syncPrimaryArea()` setelah save |
| `app/Filament/Imports/EmployeeImporter.php` | `area_id` hasil import ikut masuk `employee_area` |
| `app/Filament/Resources/RewardProgramResource.php` | `getEloquentQuery` (FR-02/03), `canCreate`, jumlah Products tanpa baris luar Area, export terpilih ikut filter, pesan empty state |
| `.../RewardProgramResource/Pages/ListRewardPrograms.php` | Import khusus Admin |
| `.../RelationManagers/ProductMappingsRelationManager.php` | Tabel & resolve Edit/Delete disaring, dropdown Customer se-Area, validasi server (FR-05) |
| `app/Services/RewardProgramExcelService.php` | Export tidak memuat baris customer luar Area |
| `app/Filament/Resources/CustomerResource.php` | `getEloquentQuery` (FR-04): list, view, edit, search, export |
## Hasil Uji Lokal (03-11-2026)
Dijalankan lewat tinker di dalam transaksi yang di-rollback (data uji tidak tersimpan). Area: J = 974, B = 977.
| Test | User | Hasil |
|---|---|---|
| TC-01 / TC-02 / TC-03 | Andi (J) | Creator J + cust J tampil; creator B + cust J dan creator J + cust B tidak tampil ✅ |
| TC-04 | Saputra (B) | Creator B + cust B tampil ✅ |
| TC-05 | Budi (J+B) | Creator J + cust B tampil, semua Reward uji tampil ✅ |
| TC-06 / TC-07 / TC-08 | Andi (J) | Customer hanya Area J, dropdown hanya dealer J, `canUseDealer(dealer B)` = false ✅ |
| TC-09 | Tanpa Area | 0 Reward, 0 Customer, dropdown kosong, Create tersembunyi ✅ |
| TC-10 | super_admin | Semua Reward, semua baris, semua Customer ✅ |
| TC-11 | Andi (J) | Reward cust J+B tampil, baris yang terlihat hanya cust J ✅ |
| K2 | Andi (J) | Reward creator J tanpa baris / hanya "Semua dealer" tampil ✅ |
Belum diuji: klik-klik UI Filament (form Employee multi-select, edit via URL → 404, export antrean Customer).
## Deploy
| Repo | Commit | Branch | Status |
|---|---|---|---|
| sfa-cms | `377b146` | `develop` | Ter-deploy dev 03-11-2026 lewat Jenkins (push → deploy). Migration `2026_11_03_000001` Ran, `employee_area` terisi 17 baris dari `employee.area_id`, halaman login 200, tidak ada error baru di `laravel.log` |
| sfa-cms | `d644d3f` | `develop` | **Koreksi:** Area customer Reward diambil dari Employee External (bukan Master Customer); menu Employee External + badge PENDING ikut filter Area. Tanpa migration |
| sfa-cms | `185eb1e` | `develop` | Filter Area di **Saldo Reward**, **Claim History**, **IMEI Registration** (transaksi milik dealer se-Area, `AreaAccess::scopeDealerOwned`), badge pengajuan per Area, dropdown Customer input IMEI hanya dealer se-Area + cek server. Permintaan Oliver 03-11-2026. Tanpa migration |
**Kondisi data dev setelah deploy (cek read-only 03-11-2026):**
- 136 dari 139 user internal ber-role `super_admin` → hampir semua user melewati filter. User internal non-admin hanya 3: OLIVER (35), Awanda Rhadifa (47), EUNIKE FERI (440).
- Ke-12 Reward Program dibuat oleh `super_admin` tanpa employee/Area (OLIVERRAKAPUR 449: 10, Admin SFA 435: 2) → **tidak terlihat oleh employee non-admin mana pun** sampai creator-nya diberi Area di Master Employee.
- 6 dealer di baris mapping, baru 3 yang terhubung ke customer ber-Area (Self Registration APPROVED: 14, yang punya `customer_id` baru 6).
## Temuan & Yang Masih Menggantung
1. **Dealer tanpa Area di Employee External (dev 03-11-2026):** TOKO UJI SWAGGER (441), ole (478), kleden (479), PT MICHELLE CALVIN PLASTICS (481) Area-nya kosong → baris Reward mereka hanya terlihat Admin sampai Area diisi di form Employee External. CV MAJU JAYA (438) & TOKO SINAR ABADI (439) = AKULAKU.
2. **Ratusan user ber-role `super_admin`** di data lokal (±130 user). Semua user itu melewati filter Area. Perlu dirapikan role-nya sebelum fitur ini berarti di production.
3. **Reward buatan Admin** (creator tanpa employee/Area) tidak terlihat oleh employee mana pun — konsekuensi aturan creator FDD. Reward lama dengan `created_by` kosong juga begitu.
4. Pesan bentrok mapping (RewardMappingOverlap) bisa menyebut kode program dari Area lain — dibiarkan karena dibutuhkan untuk validasi.
5. Tidak disentuh: Customer Approval, Sales, Visit, pilihan Area di form Customer / Employee External. Dropdown **Reward** di input IMEI tidak difilter Area creator (semua Reward dev dibuat super_admin tanpa Area — kalau difilter, input IMEI non-admin tidak bisa dipakai).
6. Open point FDD 7–8: perubahan Area langsung berlaku di request berikutnya (tidak di-cache di session).