Entities (Entitas)
| Code | SET-ENT |
| Module | Settings |
| Type | Master data (read + sync) |
| Status | Implemented |
| Priority | P1 |
| Process | Setup tenant |
| API | [URL Postman] |
1. Overview
Entitas (party) adalah identitas tunggal untuk orang atau organisasi di dalam tenant. Satu entitas bisa berperan sebagai Pengguna (akun login), Karyawan, dan/atau Pemasok sekaligus. Contohnya, seorang staf yang juga login ke sistem cukup punya satu entitas yang terhubung ke data pengguna dan data karyawannya.
Entitas tidak dibuat atau diubah langsung dari halaman ini; entitas terbentuk saat membuat pengguna, karyawan, atau pemasok. Halaman Entitas dipakai untuk melihat semua entitas beserta perannya, dan untuk menyinkronkan (menghubungkan) entitas dengan data pengguna, karyawan, atau pemasok yang sudah ada.
Hasil yang diharapkan: satu orang atau organisasi tidak tercatat sebagai beberapa identitas terpisah, sehingga data seperti nama dan kontak konsisten di semua peran.
2. Problem
- Orang yang sama bisa terdaftar dua kali, misalnya sebagai pengguna dan sebagai karyawan, dengan nama atau email yang berbeda.
- Tanpa identitas tunggal, sulit mengetahui bahwa karyawan X adalah pengguna yang login dengan email Y.
- Data lama yang terlanjur terpisah perlu cara untuk disatukan.
3. Goals & Non-goals
Goals
- Admin bisa melihat semua entitas dan perannya di satu tempat. Indikator: kolom Sebagai Pengguna / Karyawan / Pemasok per entitas.
- Admin bisa menghubungkan entitas dengan data peran yang sudah ada. Indikator: sinkronisasi dilakukan tanpa membuat ulang data.
Non-goals
- Membuat, mengubah, atau menghapus entitas langsung dari halaman ini
- Memutus hubungan (unsync) entitas dengan peran
- Menggabungkan (merge) dua entitas secara otomatis berdasarkan kemiripan data
4. User Scenarios
| Role | Scenario |
|---|---|
| Admin | Melihat karyawan mana saja yang belum punya akun login |
| Admin | Menghubungkan entitas karyawan “Budi” dengan akun pengguna Budi yang dibuat terpisah |
| Owner | Memeriksa apakah sebuah pemasok juga terdaftar sebagai karyawan |
| Auditor | Melihat log aktivitas untuk satu entitas tertentu |
5. User Flow
- Daftar entitas — Kolom nama lengkap, kategori, jenis kelamin, Sebagai Pengguna (email), Sebagai Karyawan (kode), Sebagai Pemasok (kode). Peran yang belum terhubung tampil sebagai badge Hubungkan (jika berizin sync) atau Belum Terhubung.
- Dialog sinkronisasi — Menampilkan data sumber (entitas) dan tabel data target sesuai peran yang diklik: daftar pengguna, karyawan, atau pemasok.
- Pilih target — Cari dengan kata kunci, 10 data per halaman; klik Pilih pada satu baris (klik lagi untuk batal pilih).
- Hubungkan — Tombol aktif setelah target dipilih; mengirim
party_iddan id target. - Terhubung — Toast sukses, daftar entitas dimuat ulang, dan kolom peran menampilkan data yang terhubung.
Alternative paths
- Tanpa izin sync — badge Hubungkan diganti Belum Terhubung dan tidak bisa diklik.
- Target sudah terhubung ke entitas lain — tidak dicegah FE; BE yang menentukan hasilnya (lihat EC-01).
6. User Stories
Prioritas: P0 wajib untuk rilis, P1 penting, P2 kalau sempat.
US-01 — Melihat daftar entitas (P1)
Sebagai admin, saya ingin melihat semua entitas beserta perannya, agar tahu siapa berperan sebagai apa.
| ID | Kriteria penerimaan |
|---|---|
| AC-01.1 | Kolom: nama lengkap, kategori (individu / organisasi / perusahaan), jenis kelamin, sebagai pengguna, sebagai karyawan, sebagai pemasok. |
| AC-01.2 | Pencarian kata kunci, paginasi, urutan default nama A–Z; hanya kolom nama yang bisa diurutkan. |
| AC-01.3 | Peran yang terhubung tampil sebagai badge: email pengguna, kode karyawan, kode pemasok. |
US-02 — Menyinkronkan entitas (P1)
Sebagai admin, saya ingin menghubungkan entitas dengan pengguna, karyawan, atau pemasok yang sudah ada, agar satu orang tidak tercatat sebagai identitas terpisah.
| ID | Kriteria penerimaan |
|---|---|
| AC-02.1 | Badge Hubungkan hanya tampil pada peran yang belum terhubung dan untuk pengguna dengan izin sync. |
| AC-02.2 | Dialog menampilkan data sumber: nama, kategori, jenis kelamin, email, telepon (diawali ”+”), dan status ketiga peran. |
| AC-02.3 | Tabel target mengikuti peran: pengguna (nama, email, peran, status), karyawan (kode, nama, jenis kelamin, toko, status), pemasok (kode, nama, jenis kelamin, alamat, kontak, status). |
| AC-02.4 | Hanya satu target yang bisa dipilih; tombol Hubungkan nonaktif sampai target dipilih. |
| AC-02.5 | Setelah berhasil, toast sukses tampil, dialog tertutup, dan daftar dimuat ulang. |
US-03 — Riwayat aktivitas entitas (P2)
Sebagai auditor, saya ingin melihat log aktivitas entitas, agar perubahan identitas bisa ditelusuri.
| ID | Kriteria penerimaan |
|---|---|
| AC-03.1 | Log tersedia untuk semua entitas (tombol di header) dan per entitas (aksi baris), dengan filter event, pelaku, dan rentang tanggal. |
7. Document Structure
| Field | Required | Default | Notes |
|---|---|---|---|
| Nama Lengkap | — | — | Dari data entitas |
| Kategori | — | — | individual, organization, company |
| Jenis Kelamin | — | — | male, female, atau kosong |
| — | — | Nullable | |
| Nomor Telepon | — | — | Nullable; ditampilkan dengan awalan ”+” |
| Sebagai Pengguna | — | — | Relasi ke user (id, email) |
| Sebagai Karyawan | — | — | Relasi ke employee (id, code) |
| Sebagai Pemasok | — | — | Relasi ke supplier (id, code) |
Semua field read-only di halaman ini. Body sinkronisasi: party_id ditambah salah satu dari user_id, employee_id, atau supplier_id.
8. Status Lifecycle
Tidak berlaku. Entitas tidak punya status; status aktif ada pada peran masing-masing (pengguna, karyawan, pemasok).
9. Permissions & Actions
Permissions
| Action | Permission | Syarat tambahan |
|---|---|---|
| Lihat daftar entitas dan log aktivitas | settings:party:list:any | — |
| Sinkronkan entitas | settings:party:sync:any | Peran belum terhubung |
FE menyembunyikan aksi yang tidak diizinkan; BE tetap menolaknya.
10. Business Rules
Aturan bisnis adalah ketentuan yang berlaku di semua layar dan semua aksi, siapa pun yang melakukannya. FE memakainya sebagai validasi di form, BE memakainya sebagai sumber kebenaran; jika keduanya berbeda, perilaku BE yang dianggap benar dan FE menyesuaikan.
- BR-01 Satu entitas maksimal terhubung ke satu pengguna, satu karyawan, dan satu pemasok.
- BR-02 Entitas terbentuk otomatis saat membuat pengguna, karyawan, atau pemasok “dari awal”; membuat “dari entitas” memakai entitas yang sudah ada.
- BR-03 Sinkronisasi hanya tersedia untuk peran yang belum terhubung pada entitas tersebut.
- BR-04 Sinkronisasi dan perubahan entitas dicatat di log aktivitas.
11. Edge Cases
Edge case adalah kondisi yang jarang terjadi tetapi pasti muncul di operasional nyata. Perilaku yang diharapkan ditetapkan di sini agar tidak diputuskan sendiri-sendiri saat implementasi.
| ID | Case | Expected behavior |
|---|---|---|
| EC-01 | Target yang dipilih sudah terhubung ke entitas lain | FE tidak menyaring target yang sudah terhubung; BE menentukan apakah ditolak atau dipindahkan ke entitas ini |
| EC-02 | Nama/email entitas berbeda dengan data target | Sinkronisasi tetap bisa dilakukan; aturan data mana yang dipakai ditentukan BE |
| EC-03 | Entitas tanpa email atau telepon | Ditampilkan sebagai ”-” di dialog |
| EC-04 | Salah menghubungkan entitas | Belum ada aksi putus hubungan dari UI |
12. API Contract
| Action | Method | Endpoint | Ref |
|---|---|---|---|
| Daftar entitas (paginasi, cari) | GET | /api/parties/paginate | US-01 |
| Daftar entitas (cursor) | GET | /api/parties/cursor | — |
| Sinkronkan entitas | POST | /api/parties/sync | US-02 |
| Log aktivitas semua entitas | GET | /api/parties/activity-logs/cursor | US-03 |
| Log aktivitas satu entitas | GET | /api/parties/:id/activity-logs/cursor | US-03 |
| Target: daftar pengguna | GET | /api/users/paginate | AC-02.3 |
| Target: daftar karyawan | GET | /api/employees/paginate | AC-02.3 |
| Target: daftar pemasok | GET | /api/suppliers/paginate | AC-02.3 |
13. Dependencies
PRD terkait
- Users, Employees — dibuat dari awal atau dari entitas (filter
doesnt_have). - Suppliers (modul Purchasing) — pemasok juga merupakan entitas.
- Activity Logs — sumber log aktivitas.
Efek ke modul lain
- Kolom “Sebagai Karyawan/Pengguna/Pemasok” di daftar Pengguna dan Karyawan berasal dari relasi entitas.
- Karyawan yang terhubung ke pengguna yang sedang login dipakai untuk menentukan PIC di Pesanan Pembelian.