129 lines
7.7 KiB
Markdown
129 lines
7.7 KiB
Markdown
|
|
---
|
|||
|
|
judul: SFA — Staff Registration
|
|||
|
|
proyek: SFA CMS · SFA API
|
|||
|
|
terkait: Mito · SFA Mobile
|
|||
|
|
stack: Node/Express (sfa-api) · Laravel 11 · Filament 3 · MySQL
|
|||
|
|
kategori: Fitur
|
|||
|
|
status: Di-push ke develop 13-10-2026 (sfa-cms 9271eea · sfa-api 79be952) — belum deploy
|
|||
|
|
tipe: dokumen-internal
|
|||
|
|
repo:
|
|||
|
|
- https://repo.sinerka.id/MITO/sfa-api (branch develop)
|
|||
|
|
- https://repo.sinerka.id/MITO/sfa-cms (branch develop)
|
|||
|
|
tags:
|
|||
|
|
- sfa
|
|||
|
|
- cms
|
|||
|
|
- sfa-api
|
|||
|
|
- staff-registration
|
|||
|
|
- fitur
|
|||
|
|
diperbarui: 2026-10-13
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
> Index: [[SFA — Index]] · Kategori: **Fitur**
|
|||
|
|
>
|
|||
|
|
> Implementasi [[SFA – CMS – Staff Registration]]: dealer mendaftarkan staff-nya dari SFA Mobile,
|
|||
|
|
> CMS Admin me-review di menu **Employee External**, lalu akun staff aktif. Mengisi TBD FDD §3.5,
|
|||
|
|
> §3.6, §4, dan §7 dengan keputusan di bawah.
|
|||
|
|
|
|||
|
|
# Staff Registration
|
|||
|
|
|
|||
|
|
## 1. Prinsip: tambahan, tidak mengubah alur yang sudah dipakai mobile
|
|||
|
|
|
|||
|
|
| Yang **tidak** berubah | Keterangan |
|
|||
|
|
|---|---|
|
|||
|
|
| `POST /auth/login` | Staff login dengan kode yang sama: user EXTERNAL `APPROVED` → token `USER`, `PENDING` → *Registrasi belum di-approve*, `REJECTED` → *Registrasi ditolak* |
|
|||
|
|
| `/registration/*` (Self Registration) | Endpoint, tabel `customer_registration`, dan `serviceRegistration.js` tidak disentuh |
|
|||
|
|
| Endpoint sales | Token staff (EXTERNAL) tetap ditolak `validateJWT` |
|
|||
|
|
| `app.js` | Endpoint staff di bawah prefix `/registration`, jadi otomatis ikut batas body 35MB |
|
|||
|
|
|
|||
|
|
## 2. Keputusan (mengisi TBD FDD)
|
|||
|
|
|
|||
|
|
| Hal | Keputusan |
|
|||
|
|
|---|---|
|
|||
|
|
| Siapa mendaftarkan | **Dealer yang sudah login**: user EXTERNAL `APPROVED` yang bukan staff. Staff tidak bisa mendaftarkan staff lain |
|
|||
|
|
| Akun staff | Dibuat saat submit: `users` EXTERNAL, `status = PENDING`, **tanpa role**. Role (mis. `Dealer Staff`) dipilih admin saat Approve — lihat [[SFA — Self Registration#Alur Pemasangan Role (Approve)]] (20-10-2026) |
|
|||
|
|
| Aktivasi (CMS-STAFF_RE-06) | **Approve = aktivasi**: `users.status = APPROVED` + role yang dipilih admin, staff langsung bisa login. Tidak ada langkah Activate terpisah |
|
|||
|
|
| Revisi (CMS-STAFF_RE-05) | Dikerjakan **dealer** lewat resubmit; akun staff tetap PENDING |
|
|||
|
|
| Kode registrasi | `STF` + `YYMMDD` + id 6 digit (customer: `REG…`) |
|
|||
|
|
| Hak akses CMS | Memakai permission Shield Customer Registration yang sama (`review` / `approve` / `revision` / `reject_customer::registration`) |
|
|||
|
|
| Notifikasi (CMS-STAFF_RE-07) | Admin: lonceng CMS (`POST /api/staff-registrations/{id}/notify`). Dealer: cek status lewat `GET /registration/staff/{id}`. Push / email ke dealer masih TBD |
|
|||
|
|
|
|||
|
|
**Status:** `SUBMITTED` → (`UNDER_REVIEW`) → `APPROVED`, atau `REVISION` (→ resubmit → `SUBMITTED`) / `REJECTED` (final; boleh didaftarkan ulang dengan email yang sama, akun lama dipakai ulang).
|
|||
|
|
|
|||
|
|
## 3. Data (FDD §3.5) & validasi (§3.6)
|
|||
|
|
|
|||
|
|
| Field API | Kolom | Wajib | Aturan |
|
|||
|
|
|---|---|---|---|
|
|||
|
|
| `staff_name` | `staff_name` | ✅ | maks 100 |
|
|||
|
|
| `email` | `email_address` + `users.email` | ✅ | format email, maks 60 |
|
|||
|
|
| `phone` | `phone_number` | ✅ | `^\+?[0-9]+$`, 6–20 |
|
|||
|
|
| `password` | `users.password` (hash `$2y$`) | ✅ submit | 8–72 |
|
|||
|
|
| `nik` | `nik` (BIGINT) | — | **JSON number** (string ditolak), 16 digit, maks `9007199254740991` |
|
|||
|
|
| `position` | `position` | — | maks 100 (jabatan, teks bebas) |
|
|||
|
|
| `staff_address` | `staff_address` | — | maks 500 |
|
|||
|
|
| `additional_information` | `additional_information` | — | maks 1000 |
|
|||
|
|
| `attachment[]` | `staff_registration_attachment` | — | PDF/PNG/JPG, 5MB per file, maks 5 per request & 10 per registrasi |
|
|||
|
|
|
|||
|
|
> [!info] NPWP & NIK sebagai number (13-10-2026)
|
|||
|
|
> `nik` (staff) dan `vat_num` (registrasi customer & `POST /master/customer`) dikirim sebagai **JSON number** dan disimpan `BIGINT UNSIGNED` (migration CMS `2026_10_13_000002`). NPWP 14–16 digit (leading zero NPWP lama hilang), NIK 16 digit. Batas atas `9007199254740991` (`Number.MAX_SAFE_INTEGER`): angka di atasnya dibulatkan diam-diam oleh JSON/JavaScript, jadi ditolak 400 — artinya NIK/NPWP 16 digit berawalan `901…`–`99…` (mis. Papua `94…`) belum bisa diinput.
|
|||
|
|
|
|||
|
|
**Duplikat (409):** email sudah dipakai `users` lain / registrasi staff aktif / registrasi customer aktif; no. HP atau NIK sudah dipakai registrasi staff yang belum `REJECTED`. Approve di CMS mengecek ulang email dan memastikan dealer masih `APPROVED`.
|
|||
|
|
|
|||
|
|
## 4. API (Node `sfa-api`)
|
|||
|
|
|
|||
|
|
Semua pakai header `token` dari `/auth/login` milik **dealer** (middleware baru `validateExternalJWT`).
|
|||
|
|
|
|||
|
|
| Endpoint | Fungsi |
|
|||
|
|
|---|---|
|
|||
|
|
| `POST /registration/staff/submit` | Daftarkan staff. 201 + detail registrasi |
|
|||
|
|
| `GET /registration/staff?page&limit&status` | List staff yang didaftarkan dealer ini |
|
|||
|
|
| `GET /registration/staff/{id}` | Detail, status, alasan, dokumen, riwayat. 404 bila bukan milik dealer ini |
|
|||
|
|
| `POST /registration/staff/{id}/resubmit` | Hanya status `REVISION`. Field opsional + `attachment` baru + `remove_attachment_ids` + `password` (bila diganti) |
|
|||
|
|
|
|||
|
|
| Kondisi | HTTP |
|
|||
|
|
|---|---|
|
|||
|
|
| Tanpa token / token internal / token registrant | 403 |
|
|||
|
|
| Token staff, atau dealer belum `APPROVED` | 403 |
|
|||
|
|
| Validasi field / dokumen | 400 |
|
|||
|
|
| Duplikat, resubmit saat status bukan `REVISION` | 409 |
|
|||
|
|
|
|||
|
|
Swagger: tag **Staff Registration** di `/api-docs`.
|
|||
|
|
|
|||
|
|
## 5. CMS — menu Employee External
|
|||
|
|
|
|||
|
|
- Kolom baru **Type** (Dealer / Staff) dan **Dealer**; filter **Type**. Kolom Registration / Status / Submitted menampilkan data staff untuk baris staff.
|
|||
|
|
- Aksi staff (tabel + header View): Start Review, Approve, Request Revision, Reject.
|
|||
|
|
- Halaman View staff: section **Staff Registration**, **Staff Documents**, **Staff History** (section customer disembunyikan).
|
|||
|
|
- **Edit dinonaktifkan untuk staff**: form edit menulis `customer_registration`, jadi perbaikan data staff lewat Request Revision.
|
|||
|
|
- Badge menu sudah ikut menghitung staff `PENDING`.
|
|||
|
|
|
|||
|
|
## 6. Database
|
|||
|
|
|
|||
|
|
Migration CMS `2026_10_13_000001_create_staff_registration_tables.php` (idempotent): `staff_registration`, `staff_registration_attachment`, `staff_registration_history`, dan role `Dealer Staff` (EXTERNAL). Dokumen tersimpan di `files/staff_registration/…` (opsional `.env` Node `staffRegistrationAttachmentPath`).
|
|||
|
|
|
|||
|
|
## 7. Pengujian (lokal, 13-10-2026)
|
|||
|
|
|
|||
|
|
HTTP → Node API → MySQL → CMS, data uji dihapus setelahnya:
|
|||
|
|
- Submit ok (dengan dokumen), validasi 400, tanpa token 403, duplikat email / HP / email customer 409, list, detail, detail milik lain 404
|
|||
|
|
- Staff login sebelum approve → 403; resubmit saat `SUBMITTED` → 409
|
|||
|
|
- Revision → resubmit (ganti dokumen) → Approve → staff login `USER` dengan role `Dealer Staff`; reject setelah approve ditolak
|
|||
|
|
- Token staff → submit 403 & endpoint sales 403
|
|||
|
|
- Reject → login *Registrasi ditolak* → daftar ulang email sama memakai ulang akun (tidak dobel)
|
|||
|
|
- Notifikasi lonceng terkirim ke admin reviewer
|
|||
|
|
- Filament: filter Type, visibilitas aksi staff/customer/edit, halaman View staff & customer lama, Start Review dari header
|
|||
|
|
|
|||
|
|
## 8. Deploy
|
|||
|
|
|
|||
|
|
1. **CMS dulu**: `php artisan migrate --path=database/migrations/2026_10_13_000001_create_staff_registration_tables.php` (Node tidak lagi butuh role saat submit sejak 20-10-2026)
|
|||
|
|
2. Node API: pull + `pm2 restart`. Pastikan `LARAVEL_API_URL` / `LARAVEL_API_KEY` terisi untuk notifikasi
|
|||
|
|
3. Kabari tim mobile: 4 endpoint baru di §4 (endpoint lama tidak berubah)
|
|||
|
|
|
|||
|
|
## 9. Terbuka
|
|||
|
|
|
|||
|
|
| # | Hal |
|
|||
|
|
|---|---|
|
|||
|
|
| 1 | Notifikasi status ke dealer (push / email) — channel masih TBD di FDD |
|
|||
|
|
| 2 | Menu / akses apa yang boleh dipakai staff di aplikasi setelah login (role `Dealer Staff` belum punya pembatasan route) |
|
|||
|
|
| 3 | Bila dealer di-reject / dinonaktifkan, apakah staff-nya ikut dinonaktifkan? Sekarang hanya Approve yang mengecek status dealer |
|
|||
|
|
| 4 | Admin tidak bisa mengedit data staff di CMS (hanya lewat revisi dealer) |
|
|||
|
|
| 5 | Helper dokumen staff (`routes/helpers/registrationDocuments.js`) menduplikasi logika di `serviceRegistration.js`; bisa disatukan nanti tanpa mengubah perilaku |
|