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

232 lines
12 KiB
Markdown

---
judul: SFA — Self Registration
proyek: SFA CMS · SFA API
terkait: Mito · SFA Mobile
stack: Node/Express (sfa-api) · Laravel 11 · Filament 3 · MySQL
kategori: Fitur
status: Ter-deploy di CMS (develop) — Node API menunggu merge ke main
tipe: dokumen-internal
repo:
- https://repo.sinerka.id/MITO/sfa-api (branch feature/self-registration)
- https://repo.sinerka.id/MITO/sfa-cms (branch develop)
tags:
- sfa
- cms
- sfa-api
- self-registration
- fitur
diperbarui: 2026-10-06
---
> Index: [[SFA — Index]] · Kategori: **Fitur**
>
> Implementasi [[SFA_MD_CMS_Self_Registration_v1.0]]: pendaftaran user/customer dari SFA
> Mobile, review oleh CMS Admin, lalu aktivasi akun. Mengisi TBD FDD §4 (API) dan §7 (Open
> Issues) dengan keputusan teknis di bawah.
# Self Registration
## Alur Pemasangan Role (Approve)
Keputusan teknis 20-10-2026 (tidak ada di FDD): Node API **tidak memasang role** apa pun, karena role bisa
ditambah, di-rename, dan dihapus di Shield → Roles. Role dipilih admin saat **Approve**, dicari berdasarkan
**id**, bukan nama. Latar belakang: [[2026-10-20_registrasi-role-customer-direname-dealer]].
Berlaku sama untuk [[SFA — Staff Registration]] (menu Employee External).
```mermaid
flowchart TD
A["POST /registration/submit<br/>atau /registration/staff/submit"] --> B["Node: users EXTERNAL<br/>status PENDING, tanpa role"]
B --> C["CMS: Approve<br/>form pilih Role"]
C --> D{"Role dipilih?"}
D -- "tidak" --> E1["Validasi form: Role wajib diisi"]
D -- "ya" --> F{"Role ada, guard web,<br/>user_type EXTERNAL?"}
F -- "tidak (dihapus / bukan External)" --> E2["DomainException<br/>Role tidak ditemukan atau bukan role External.<br/>Approve batal (rollback)"]
F -- "ya" --> G["syncRoles([role]) → syncUserTypeFromRoles()<br/>users.status = APPROVED"]
G --> OK["APPROVED<br/>login /auth/login, roles di token"]
classDef ok fill:#d1fae5,stroke:#059669,color:#064e3b
classDef err fill:#fee2e2,stroke:#dc2626,color:#7f1d1d
class OK ok
class E1,E2 err
```
Hijau = sukses · Merah = ditolak / gagal
- Default pilihan di form = role External yang sudah dipegang user (registrasi lama yang role-nya dulu dipasang Node).
- Role lama user diganti (`syncRoles`), lalu `users.user_type` dihitung ulang dari flag `roles.user_type`.
- Kode: `App\Filament\Forms\ExternalRoleField`, `CustomerRegistrationService::assignExternalRole`.
## 1. Ringkasan
| | |
|---|---|
| **Alur** | SFA Mobile → Node API `sfa-api` (simpan ke DB CMS) → CMS Admin review di Filament → Approve → Activate → akun `users` + master `customer` |
| **Siapa bisa daftar** | Publik (tombol "create account" di mobile), **atau** user yang sudah login mendaftarkan orang lain (hasil diskusi dengan Oliver, 01-10-2026) |
| **Hasil aktivasi** | Baris `users` (`user_type = CUSTOMER`, **tidak bisa** masuk panel CMS) + baris `customer` (`ACTIVE` / `REGULAR`) + dokumen disalin ke `customer_attachment` |
| **Commit** | sfa-api `1ac3427` (feature/self-registration) · sfa-cms `af6a6e3` (develop) |
| **Deploy** | CMS: ✅ 06-10-2026 (lihat [[SFA CMS — Deploy 2026-10-06]]). Node API: ⬜ menunggu merge ke `main` |
```
SFA Mobile ──POST /registration/submit──► sfa-api ──► MySQL CMS (customer_registration*)
▲ │
└──GET /registration/status (token registrant) ▼
Filament: Customer Registrations
Start Review → Approve / Revision / Reject
→ Activate (users + customer)
```
---
## 2. Status & Transisi
| Status | Arti | Siapa yang mengubah | Berikutnya |
|---|---|---|---|
| — (Draft) | Belum dikirim, **hanya di mobile** | — | Submit |
| `SUBMITTED` | Sudah dikirim | API (submit / resubmit) | Start Review, Approve, Revision, Reject |
| `UNDER_REVIEW` | Sedang direview | Admin (Start Review) | Approve, Revision, Reject |
| `REVISION` | Perlu perbaikan, **alasan wajib** | Admin | Resubmit dari mobile → `SUBMITTED` |
| `APPROVED` | Disetujui | Admin | Activate |
| `REJECTED` | Ditolak, **alasan wajib**. Final | Admin | — (boleh daftar ulang dengan data sama) |
| `ACTIVE` | Akun sudah dibuat | Admin (Activate) | Login |
Approve/Revision/Reject boleh langsung dari `SUBMITTED` (Start Review opsional, berguna
supaya mobile tahu sedang diproses). Setiap transisi: transaksi DB + `lockForUpdate`
(dua admin tidak bisa memproses registrasi yang sama bersamaan) + baris audit.
---
## 3. Database
Migration CMS `2026_10_01_000001_create_customer_registration_tables.php` (idempotent,
semua pakai `hasTable` / `hasColumn`):
| Tabel | Isi |
|---|---|
| `customer_registration` | Data customer (nama, tipe, NPWP, alamat, HP, email, PIC, area, channel, GPS), referral sales, **hash password**, `registered_by_user_id` (null = daftar sendiri), status, alasan, reviewer, `user_id` + `customer_id` hasil aktivasi |
| `customer_registration_attachment` | Dokumen pendukung: `doc_type`, `filepath` (`files/customer_registration/...`) |
| `customer_registration_history` | Audit trail FDD §3.10: action, status sebelum/sesudah, alasan, actor (`REGISTRANT`/`USER`) |
| `users.user_type` (kolom baru) | `null` = user internal, `CUSTOMER` = hasil self registration |
Relasi customer ↔ akun login disimpan di `customer_registration` (`user_id`, `customer_id`)
karena tabel `customer` tidak punya kolom `user_id`.
---
## 4. API (Node `sfa-api`)
Semua di `routes/sfa.js`, logika di `routes/services/serviceRegistration.js`.
| Endpoint | Auth | Fungsi |
|---|---|---|
| `GET /registration/master-data` | publik | Dropdown: `cust_types`, `areas`, `channels` |
| `POST /registration/submit` | publik **atau** header `token` user | Daftar baru. Tanpa token → `referral_empl_code` wajib, response berisi `token` registrant. Dengan token user → referral otomatis = employee login |
| `POST /registration/login` | publik | `{ email, password }` → token registrant |
| `GET /registration/status` | token registrant | Detail, status, alasan, dokumen, riwayat |
| `POST /registration/resubmit` | token registrant | Hanya status `REVISION`. Field opsional + `attachment` baru + `remove_attachment_ids` |
| `GET /registration/created` | token user | `?page&limit&status` — registrasi yang didaftarkan user ini |
**Contoh submit:**
```json
{
"cust_name": "Toko Abadi", "cust_type": "COMPANY", "vat_num": "01.234.567.8-901.000",
"cust_address": "Jl. ...", "phone": "08123456789", "email": "abadi@mail.com",
"password": "minimal8karakter", "pic": "Budi",
"area_id": 3, "channel_id": 2, "latitude": -6.2, "longitude": 106.8,
"referral_empl_code": "S001",
"attachment": [{ "doc_type": "KTP", "file": "data:image/png;base64,..." }]
}
```
Response `201`: data registrasi + `registration_code` (`REG` + `YYMMDD` + id 6 digit) +
`token` (null kalau didaftarkan user login).
**Validasi & error:**
| Kondisi | HTTP |
|---|---|
| Field wajib kosong / format salah (email, HP `^\+?[0-9]+$`, tipe `INDIVIDUAL`/`COMPANY`) | 400 |
| Dokumen bukan PDF/PNG/JPG, > 5MB, atau MIME tidak cocok dengan isi file | 400 |
| Email / HP / NPWP sudah terdaftar (`users`, `customer`, atau registrasi yang belum `REJECTED`) | 409 |
| Login salah | 401 |
| Resubmit saat status bukan `REVISION` | 409 |
`area_id` dan `channel_id` **opsional** (boleh tidak dikirim atau `null`; sempat diwajibkan di `0d334db`, di-revert `7f4dc2b`). `attachment` wajib minimal 1 di server (perubahan opsional masih lokal, belum di-commit). Batas: 5 dokumen per request (body JSON maks 35 MB), 10 dokumen per registrasi.
---
## 5. CMS (Filament)
Menu **Master Sales → Customer Registrations** (badge = jumlah yang menunggu keputusan).
List + filter status/area, halaman View dengan data, dokumen (bisa dibuka), dan riwayat.
Tidak ada Create/Edit/Delete — data hanya dari mobile.
| Action | Permission Shield | Muncul saat |
|---|---|---|
| Start Review | `review_customer::registration` | `SUBMITTED` |
| Approve (pilih **Role** External, wajib) | `approve_customer::registration` | `SUBMITTED` / `UNDER_REVIEW` |
| Request Revision | `revision_customer::registration` | `SUBMITTED` / `UNDER_REVIEW` |
| Reject | `reject_customer::registration` | `SUBMITTED` / `UNDER_REVIEW` |
| Activate Account | `activate_customer::registration` | `APPROVED` |
Approve dan Activate **mengecek ulang duplikat** email/HP/NPWP (bisa saja sudah dipakai
customer hasil sync Odoo sejak registrasi disubmit).
> [!warning] Generate permission wajib pakai `--option=permissions`
> `php artisan shield:generate --resource=CustomerRegistrationResource --option=permissions --panel=admin`.
> Tanpa opsi itu Shield menimpa `CustomerRegistrationPolicy` dengan template standar
> (admin jadi bisa create/delete registrasi).
---
## 6. Keamanan
| Hal | Penanganan |
|---|---|
| Pendaftar belum di-approve tidak boleh punya akun | Password disimpan sebagai hash di `customer_registration`, baris `users` baru dibuat saat Activate |
| Customer tidak boleh masuk panel CMS | `User::canAccessPanel()` menolak `user_type = CUSTOMER` (sebelumnya selalu `true` → semua baris `users` bisa login panel) |
| Token registrant dipakai ke endpoint lain | `validateJWT` menolak token `account_type = REGISTRANT`; endpoint registrasi pakai `validateRegistrantJWT` |
| Hash password Node ↔ Laravel | bcryptjs menghasilkan `$2b$` yang **tidak dikenali PHP** → cast `hashed` Laravel meng-hash ulang dan user tidak bisa login. Node menyimpan dengan prefix `$2y$`, CMS juga menormalkan saat Activate |
| Spoof `jwtdata` lewat body di endpoint publik | `validateOptionalJWT` menghapus `req.body.jwtdata` bila tidak ada token |
---
## 7. Pengujian
- CMS: 17 cek workflow (transisi valid/tidak valid, duplikat, aktivasi, `canAccessPanel`,
login dengan hash `$2b$`) + 24 assertion halaman Filament — semua lolos, dijalankan di
DB lokal dalam transaksi yang di-rollback.
- Node API: route, validator, middleware JWT, deteksi file palsu — dicek tanpa DB.
**Belum ada uji end-to-end HTTP → DB.**
---
## 8. Belum Dikerjakan / Keputusan Terbuka
| # | Hal | Catatan |
|---|---|---|
| 1 | **Notifikasi ke user** (FDD §3.9, CMS-REG-08) | Channel masih TBD (Open Issue #11). Sementara mobile cek `GET /registration/status` |
| 2 | **Login customer ke aplikasi setelah ACTIVE** | `/auth/login` hanya untuk employee (wajib ada baris `employee`). Perlu alur login customer + definisi menu yang boleh diakses. Rancangan: [[SFA API — Login Terpadu auth-login]] |
| 3 | Customer hasil registrasi **tidak masuk Odoo** | `cust_code` dari number sequence (`CUSTOMER-xxxx`), bukan id partner Odoo. Sync Odoo sudah mengecualikannya dari soft delete. Kalau SO-nya harus diproses Odoo → perlu push ke Odoo |
| 4 | Status customer hasil aktivasi | Sekarang `ACTIVE` / `REGULAR`. Ganti di `CustomerRegistrationService::activate()` bila harus `PROSPECT` |
| 5 | Rate limiting endpoint publik | Belum ada (submit, login) |
| 6 | Cek duplikat bisa lolos untuk dua submit bersamaan | Tidak ada unique constraint (registrasi `REJECTED` boleh duplikat). Approve/Activate mengecek ulang |
| 7 | Uji end-to-end Node API | Lihat §7 |
---
## 9. File
**sfa-api** — `models/McustomerRegistration*.js` (3), `routes/services/serviceRegistration.js`,
`routes/handler/registration/registration.js`, `routes/validator/validatorRegistration.js`,
`routes/validator/validatorJWT.js` (diubah), `routes/helpers/enums/registrationStatus.js`,
`routes/sfa.js` (route), `docs.md` §9.
**sfa-cms** — migration `2026_10_01_000001_…`, `app/Models/CustomerRegistration*.php` (3),
`app/Enums/RegistrationStatusEnum.php`, `app/Services/CustomerRegistrationService.php`,
`app/Filament/Resources/CustomerRegistrationResource.php` + `Pages/` (List, View),
`app/Policies/CustomerRegistrationPolicy.php`, `app/Models/User.php` (`canAccessPanel`).
`.env` Node API: `filePath` harus mengarah ke `storage/app/public/files` milik CMS
(dokumen tersimpan di `files/customer_registration/…` dan dibuka lewat symlink
`public/storage/files` yang sudah ada). Opsional `registrationAttachmentPath`
(default `customer_registration`).