--- 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 |