--- 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
atau /registration/staff/submit"] --> B["Node: users EXTERNAL
status PENDING, tanpa role"] B --> C["CMS: Approve
form pilih Role"] C --> D{"Role dipilih?"} D -- "tidak" --> E1["Validasi form: Role wajib diisi"] D -- "ya" --> F{"Role ada, guard web,
user_type EXTERNAL?"} F -- "tidak (dihapus / bukan External)" --> E2["DomainException
Role tidak ditemukan atau bukan role External.
Approve batal (rollback)"] F -- "ya" --> G["syncRoles([role]) → syncUserTypeFromRoles()
users.status = APPROVED"] G --> OK["APPROVED
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`).