Stores (Toko)
| Code | SET-STR |
| Module | Settings |
| Type | Master data |
| Status | Implemented |
| Priority | P0 — MVP |
| Process | Setup tenant |
| API | [URL Postman] |
1. Overview
Toko adalah unit operasional tenant: cabang, outlet, atau gudang. Setiap toko punya kode 3 karakter, nama, status aktif/tidak aktif, dan satu atau lebih alamat. Di antara alamat-alamat toko, admin menetapkan satu alamat utama, satu alamat penagihan, dan satu alamat pengiriman.
Toko menjadi konteks kerja di seluruh aplikasi. Pengguna memilih toko aktif lewat pemilih toko, dan transaksi seperti Pesanan Pembelian dibuat untuk toko aktif tersebut. Karyawan ditugaskan ke satu atau lebih toko.
Hasil yang diharapkan: struktur cabang tenant tercatat rapi, alamat yang benar dipakai otomatis di dokumen transaksi, dan toko yang sudah tidak beroperasi bisa dinonaktifkan tanpa menghapus riwayatnya.
2. Problem
- Bisnis dengan banyak cabang perlu memisahkan data dan transaksi per cabang.
- Alamat kantor, alamat tagihan, dan alamat terima barang sering berbeda; salah alamat membuat barang dikirim ke tempat yang salah.
- Cabang yang tutup tidak boleh lagi dipakai untuk transaksi baru, tetapi riwayatnya harus tetap bisa dilihat.
3. Goals & Non-goals
Goals
- Admin bisa mendaftarkan toko beserta alamatnya dalam satu alur. Indikator: toko baru langsung bisa dipakai untuk transaksi.
- Alamat default otomatis dipakai di transaksi. Indikator: alamat pengiriman PO terisi otomatis dari alamat pengiriman toko.
- Toko tidak aktif terkunci untuk transaksi baru. Indikator: aksi ubah di modul transaksi disembunyikan saat toko aktif berstatus tidak aktif.
Non-goals
- Jam operasional, koordinat peta, atau zona waktu per toko
- Hierarki toko (regional / area)
- Pengaturan harga atau pajak per toko (diatur di modul terkait)
4. User Scenarios
| Role | Scenario |
|---|---|
| Owner | Membuka cabang baru; mendaftarkan toko dengan alamat kantor sekaligus alamat terima barang |
| Admin | Menambah alamat gudang baru dan menjadikannya alamat pengiriman |
| Owner | Menonaktifkan cabang yang tutup agar tidak dipakai untuk PO baru |
| Admin | Mencari toko berdasarkan nama untuk memeriksa alamat penagihannya |
5. User Flow
- Data Toko — Pilih status (Aktif / Tidak Aktif, wajib dipilih, bisa dibatalkan pilihannya dengan klik ulang), isi kode (tepat 3 karakter) dan nama toko (maksimal 20 karakter).
- Alamat — Tambah alamat lewat dialog (nama, telepon, alamat lengkap). Alamat pertama otomatis menjadi alamat utama, penagihan, dan pengiriman. Alamat berikutnya tidak punya peran sampai ditetapkan lewat menu “Jadikan sebagai”. Alamat bisa diubah dan dihapus selama tersisa minimal satu.
- Tinjauan — Ringkasan data toko dan alamat, beserta error dari BE bila ada.
- Validasi — Validasi per langkah saat klik Selanjutnya, dan validasi BE saat Simpan.
- Tersimpan — Toast sukses, kembali ke daftar toko.
- Detail / Ubah — Tab Data Toko disimpan sekaligus. Tab Alamat dikelola per alamat: tambah, ubah, hapus, dan tetapkan peran langsung tersimpan ke BE.
Alternative paths
- Menetapkan peran alamat — memilih “Jadikan sebagai Utama/Penagihan/Pengiriman” memindahkan peran itu dari alamat lain ke alamat ini, karena setiap peran hanya dimiliki satu alamat.
- Hapus toko — satuan atau massal dari daftar, setelah konfirmasi. BE yang memutuskan apakah toko yang sudah punya transaksi boleh dihapus.
- Tinggalkan wizard tanpa simpan — muncul konfirmasi perubahan belum disimpan.
6. User Stories
Prioritas: P0 wajib untuk rilis, P1 penting, P2 kalau sempat.
US-01 — Membuat toko (P0)
Sebagai owner, saya ingin mendaftarkan toko beserta alamatnya, agar toko bisa dipakai untuk transaksi.
| ID | Kriteria penerimaan |
|---|---|
| AC-01.1 | Wizard terdiri dari Data Toko → Alamat → Tinjauan; pengguna tidak bisa lanjut bila field wajib di langkah itu belum valid. |
| AC-01.2 | Status wajib dipilih; kode harus tepat 3 karakter; nama wajib, maksimal 20 karakter. |
| AC-01.3 | Minimal satu alamat wajib ditambahkan sebelum lanjut ke Tinjauan. |
| AC-01.4 | Alamat pertama otomatis bertanda Utama, Penagihan, dan Pengiriman. |
| AC-01.5 | Tombol hapus alamat disembunyikan bila hanya tersisa satu alamat. |
| AC-01.6 | Setelah berhasil, toast sukses tampil dan pengguna diarahkan ke daftar toko. |
| AC-01.7 | Error BE tampil di langkah Tinjauan dan pada field terkait. |
US-02 — Mengelola alamat toko (P0)
Sebagai admin, saya ingin menambah, mengubah, menghapus, dan menetapkan peran alamat, agar dokumen memakai alamat yang benar.
| ID | Kriteria penerimaan |
|---|---|
| AC-02.1 | Alamat terdiri dari nama (maks 20), telepon (maks 15), dan alamat lengkap (maks 255); semuanya wajib. |
| AC-02.2 | Menu “Jadikan sebagai” hanya menampilkan peran yang belum dimiliki alamat tersebut. |
| AC-02.3 | Menetapkan peran ke satu alamat mencabut peran yang sama dari alamat lain. |
| AC-02.4 | Di mode ubah, setiap aksi alamat langsung tersimpan ke BE, dengan spinner pada alamat yang sedang diperbarui. |
| AC-02.5 | Tombol tambah, ubah, dan hapus alamat mengikuti izin create, update, dan delete. |
| AC-02.6 | Setiap alamat menampilkan badge perannya (Utama / Penagihan / Pengiriman). |
US-03 — Mengubah data toko (P0)
Sebagai owner, saya ingin mengubah status, kode, atau nama toko, agar data tetap akurat.
| ID | Kriteria penerimaan |
|---|---|
| AC-03.1 | Tombol Ubah Data hanya tampil untuk pengguna dengan izin update. |
| AC-03.2 | Validasi sama dengan pembuatan (AC-01.2); tombol simpan aktif hanya jika ada perubahan. |
| AC-03.3 | Tab yang sedang dibuka dipertahankan di URL (section-tab). |
US-04 — Daftar toko (P0)
Sebagai owner, saya ingin melihat semua toko, agar mudah memeriksa dan mengelolanya.
| ID | Kriteria penerimaan |
|---|---|
| AC-04.1 | Kolom: kode, nama toko, alamat (daftar alamat berperan, dapat diperluas), dan status. |
| AC-04.2 | Pencarian kata kunci, paginasi, urutan default nama A–Z. |
| AC-04.3 | Aksi baris: Lihat, Ubah, Hapus sesuai izin; hapus massal dari baris terpilih. |
US-05 — Menghapus toko (P1)
Sebagai owner, saya ingin menghapus toko yang salah dibuat, agar daftar bersih.
| ID | Kriteria penerimaan |
|---|---|
| AC-05.1 | Hapus satuan dan massal memerlukan konfirmasi dan izin delete. |
| AC-05.2 | Bila BE menolak, pesan error tampil sebagai toast. |
US-06 — Riwayat aktivitas (P2)
Sebagai owner, saya ingin melihat log aktivitas toko, agar perubahan bisa ditelusuri.
| ID | Kriteria penerimaan |
|---|---|
| AC-06.1 | Log tersedia untuk semua toko (di daftar) dan per toko (di detail), dengan filter event, pelaku, dan rentang tanggal. |
7. Document Structure
Header
| Field | Required | Default | Notes |
|---|---|---|---|
Status (is_active) | Ya | Belum dipilih (buat) | Aktif / Tidak Aktif |
| Kode | Ya | — | Tepat 3 karakter |
| Nama Toko | Ya | — | Maks 20 karakter |
Lines (Alamat)
| Field | Required | Default | Notes |
|---|---|---|---|
| Nama | Ya | — | Label alamat, maks 20 karakter |
| Nomor Telepon | Ya | — | Maks 15 karakter |
| Alamat Lengkap | Ya | — | Maks 255 karakter |
| Alamat Utama | Otomatis | Alamat pertama | Satu per toko |
| Alamat Penagihan | Otomatis | Alamat pertama | Satu per toko |
| Alamat Pengiriman | Otomatis | Alamat pertama | Satu per toko; default alamat kirim PO |
8. Status Lifecycle
| Status | Label UI | Meaning | Editable | Next status |
|---|---|---|---|---|
is_active: true | Aktif | Toko beroperasi; bisa dipakai untuk transaksi baru | Ya | Tidak Aktif, dihapus |
is_active: false | Tidak Aktif | Toko tidak beroperasi; data transaksi hanya bisa dilihat | Ya | Aktif, dihapus |
9. Permissions & Actions
Permissions
| Action | Permission | Syarat tambahan |
|---|---|---|
| Lihat daftar dan log semua toko | settings:store:list:any | — |
| Lihat detail toko | settings:store:view:store | Scope toko |
| Buat toko / tambah alamat | settings:store:create:any | — |
| Ubah toko / ubah alamat / tetapkan peran alamat | settings:store:update:any | — |
| Hapus toko / hapus alamat | settings:store:delete:any | — |
FE menyembunyikan aksi yang tidak diizinkan; BE tetap menolaknya.
Actions by status (✓ tersedia)
| Action | Aktif | Tidak Aktif |
|---|---|---|
| Lihat / ubah / hapus di Settings | ✓ | ✓ |
| Dipilih sebagai toko aktif | ✓ | ✓ |
| Buat / ubah transaksi (PO, GR, Bill, dll.) | ✓ | — |
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 Kode toko tepat 3 karakter.
- BR-02 Nama toko wajib, maksimal 20 karakter.
- BR-03 Toko wajib memiliki minimal satu alamat saat dibuat.
- BR-04 Setiap peran alamat (utama, penagihan, pengiriman) dimiliki tepat satu alamat per toko; menetapkan peran ke alamat lain memindahkannya.
- BR-05 Alamat pertama yang dibuat otomatis memiliki ketiga peran.
- BR-06 Toko tidak aktif tidak bisa dipakai untuk membuat atau mengubah transaksi; semua aksi ubah di modul transaksi disembunyikan dan halaman tambah/ubah menampilkan halaman toko tidak aktif.
- BR-07 Alamat pengiriman toko menjadi default alamat pengiriman di Pesanan Pembelian.
- BR-08 Setiap perubahan toko dan alamat 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 | Menghapus alamat terakhir di mode ubah | FE tidak mencegah (berbeda dengan wizard buat); BE harus menolak agar BR-03 terjaga |
| EC-02 | Menghapus alamat yang memegang peran utama/penagihan/pengiriman | Perilaku ditentukan BE (menolak atau memindahkan peran); FE tidak mencegah |
| EC-03 | Toko punya alamat tanpa peran | Alamat tetap tersimpan tetapi tidak tampil di kolom Alamat pada daftar (hanya alamat berperan yang ditampilkan) |
| EC-04 | Menghapus toko yang sudah punya karyawan atau transaksi | Ditentukan BE; bila ditolak, pesan error tampil sebagai toast |
| EC-05 | Kode toko duplikat | Ditolak BE; error tampil pada field kode |
| EC-06 | Toko dinonaktifkan saat pengguna sedang memakainya sebagai toko aktif | Halaman transaksi menjadi read-only setelah data toko dimuat ulang |
| EC-07 | Pengguna tidak ditugaskan ke toko mana pun | Modul transaksi menampilkan halaman toko belum ditetapkan |
12. API Contract
| Action | Method | Endpoint | Ref |
|---|---|---|---|
| Daftar toko (paginasi, cari) | GET | /api/stores/paginate | US-04 |
| Daftar toko (cursor, untuk combobox) | GET | /api/stores/cursor | — |
| Semua toko (tanpa paginasi) | GET | /api/stores | — |
| Detail toko | GET | /api/stores/:id | US-03 |
| Buat toko (+ alamat) | POST | /api/stores | US-01 |
| Ubah toko | PUT | /api/stores/:id | US-03 |
| Hapus toko | DELETE | /api/stores/:id | US-05 |
| Hapus toko massal | DELETE | /api/stores/bulk | US-05 |
| Daftar alamat toko | GET | /api/stores/:id/addresses | US-02 |
| Daftar alamat toko (cursor) | GET | /api/stores/:id/addresses/cursor | — |
| Detail alamat | GET | /api/stores/:id/addresses/:address_id | US-02 |
| Tambah alamat | POST | /api/stores/:id/addresses | US-02 |
| Ubah alamat | PUT | /api/stores/:id/addresses/:address_id | US-02 |
| Hapus alamat | DELETE | /api/stores/:id/addresses/:address_id | US-02 |
Tetapkan peran alamat (field: primary/billing/shipping, value: address id) | PATCH | /api/stores/:id/addresses/set-default | BR-04 |
| Log aktivitas semua toko | GET | /api/stores/activity-logs/cursor | US-06 |
| Log aktivitas satu toko | GET | /api/stores/:id/activity-logs/cursor | US-06 |
Endpoint turunan per toko (dipakai modul lain)
| Action | Method | Endpoint | Ref |
|---|---|---|---|
| Karyawan toko | GET | /api/stores/:id/employees/cursor | — |
| Inventaris produk toko | GET | /api/stores/:id/product-inventories/cursor | — |
| PO toko | GET | /api/stores/:id/purchase-orders/paginate, /cursor | — |
| Penerimaan barang toko | GET | /api/stores/:id/goods-receipts/cursor | — |
13. Dependencies
PRD terkait
- Employees — karyawan ditugaskan ke toko.
- Purchase Order, Goods Receipt, Bill — transaksi dibuat per toko dan memakai alamat toko.
- Activity Logs — sumber log aktivitas.
Efek ke modul lain
- Pemilih toko di layout menentukan toko aktif (disimpan di cookie) untuk seluruh modul transaksi.
- Status tidak aktif mengunci aksi ubah di semua modul transaksi (BR-06).
Last updated on