12 KiB
| judul | proyek | terkait | stack | kategori | status | tipe | repo | tags | diperbarui | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| SFA — Self Registration | SFA CMS · SFA API | Mito · SFA Mobile | Node/Express (sfa-api) · Laravel 11 · Filament 3 · MySQL | Fitur | Ter-deploy di CMS (develop) — Node API menunggu merge ke main | dokumen-internal |
|
|
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).
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), laluusers.user_typedihitung ulang dari flagroles.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:
{
"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=permissionsphp artisan shield:generate --resource=CustomerRegistrationResource --option=permissions --panel=admin. Tanpa opsi itu Shield menimpaCustomerRegistrationPolicydengan 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).