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

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
https://repo.sinerka.id/MITO/sfa-api (branch feature/self-registration)
https://repo.sinerka.id/MITO/sfa-cms (branch develop)
sfa
cms
sfa-api
self-registration
fitur
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), 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:

{
  "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).