Doc_chelvyn/Mito/Sfa/Fitur/SFA — Staff Registration.md

129 lines
7.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

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