286 lines
28 KiB
Markdown
286 lines
28 KiB
Markdown
---
|
||
judul: SFA — Reward (scan IMEI, saldo, claim)
|
||
proyek: SFA API · SFA CMS
|
||
terkait: Mito · Odoo 18 · SFA Mobile
|
||
stack: Node/Express (sfa-api) · Laravel 11 · Filament 3 · MySQL
|
||
kategori: Fitur
|
||
status: Ter-deploy ke CMS dev 13-10-2026 (cms 137aca2 + db25341, api 63c9153) — integrasi Odoo selesai di kode (cms 46fc3c7, odoo a5cc341e), belum deploy
|
||
tipe: dokumen-internal
|
||
tags:
|
||
- sfa
|
||
- reward
|
||
- imei
|
||
- odoo
|
||
diperbarui: 2026-10-27
|
||
---
|
||
|
||
> Index: [[SFA — Index]] · Kategori: **Fitur** · FDD: [[Functional Design — SFA Reward, CMS, dan Integrasi Odoo]]
|
||
>
|
||
> Implementasi tahap 1 FDD SFA Reward v0.2: config reward, ledger, saldo, scan IMEI, claim full balance,
|
||
> dan menu CMS. **Berbeda dari FDD:** scan IMEI tidak langsung menambah saldo — masuk **Pengajuan IMEI** dulu dan reward
|
||
> baru masuk saldo setelah di-approve user internal di CMS. Admin juga bisa input pengajuan dari CMS untuk IMEI yang
|
||
> tidak bisa di-scan (§5).
|
||
> **Draft Vendor Bill di Odoo** dikerjakan terpisah: [[SFA — Reward Claim ke Odoo (Draft Vendor Bill)]] (FDD v0.4, belum deploy).
|
||
|
||
# SFA — Reward
|
||
|
||
## 1. Keputusan
|
||
|
||
| # | Hal | Keputusan |
|
||
|---|---|---|
|
||
| 1 | IMEI uniqueness scope (FDD §12) | ✅ **Per IMEI** (MoM 22-10-2026, sebelumnya per produk sejak 13-10-2026). Cek di Node & CMS: IMEI yang sudah ada di ledger — termasuk yang saldonya sudah di-claim — ditolak `IMEI_ALREADY_REWARDED`, walaupun produk IMEI di Odoo berubah. `UNIQUE(imei_number, product_id)` di ledger tetap sebagai pengaman terakhir |
|
||
| 2 | Sumber relasi IMEI–produk (FDD §12) | ✅ Tabel **`imei`** hasil `odoo:sync-imeis`. Product ID dari mobile tidak dipakai |
|
||
| 3 | Siapa "konsumen" | `users.id` dari token `/auth/login`, **INTERNAL maupun EXTERNAL** (middleware baru `validateUserJWT`). Token registrant ditolak |
|
||
| 4 | Saldo per apa | Per user, **lintas program**. Ledger tetap menyimpan program & produk untuk laporan. Satu claim = seluruh saldo user |
|
||
| 5 | Mapping tumpang tindih | CMS menolak 2 mapping ACTIVE untuk **produk yang sama** dengan periode bertabrakan, **lintas program** (program ENDED dikecualikan). Kalau tidak begitu, program pemberi reward jadi ambigu karena IMEI hanya dapat sekali per produk |
|
||
| 6 | Ubah nominal | Mapping yang sudah dipakai ledger: produk, nominal, effective_from **dikunci**. Ubah nominal = isi `effective_to` mapping lama lalu buat mapping baru |
|
||
| 7 | Minimum claim | Tidak ada. Claim ditolak hanya kalau saldo 0 |
|
||
| 8 | Expiry | Tidak ada (FDD: kalau tidak didefinisikan, saldo tidak kedaluwarsa) |
|
||
| 9 | Approval IMEI (di luar FDD, 13-10-2026) | **Semua IMEI lewat Pengajuan IMEI dulu**, saldo belum bertambah. **Satu customer = satu pengajuan `SUBMITTED`**: scan mobile dan input admin CMS untuk customer itu masuk sebagai line di header yang sama (lintas reward program; program, sumber, catatan, attachment disimpan per line). **Approval per pengajuan** → satu EARN per IMEI + saldo bertambah total, header ditutup; IMEI berikutnya membuka header baru. IMEI bermasalah bisa **ditolak per line** tanpa menolak header. Approver tidak boleh yang meng-input / scan IMEI di header itu. Produk dan nominal **dikunci saat IMEI masuk**. Detail di §5 |
|
||
| 10 | Submit IMEI dari mobile (di luar FDD, 19-10-2026) | Hasil scan **dikumpulkan dulu di list mobile** (belum hit API), user menambahkan **satu nota**, lalu dikirim sekali: `POST /reward/imei` `{imei_number: [..], request_id, attachment?}`. Nota dipakai bersama semua IMEI di list — **opsional sejak MoM 22-10-2026** (submit tanpa nota → `attachment` line `null`, bisa ditambah lewat `PUT`). **Semua atau tidak sama sekali** — satu IMEI ditolak → tidak ada yang disimpan, `422 IMEI_REJECTED` + alasan per IMEI. `POST /reward/imei/attachment` (upload nota sesudah scan) dihapus; `PUT` tetap untuk ganti nota. `reward_imei_submission_line.request_id` jadi index biasa (bukan UNIQUE), migration CMS `2026_10_19_000001` |
|
||
| 11 | IMEI hanya sekali di-scan & harus sudah terjual (MoM 22-10-2026, di luar FDD) | **Terjual = `stock.lot.product_qty` Odoo = 0** (stok internal habis, diputuskan 27-10-2026). API Odoo `/imeis` mengirim `product_qty`; `updated_since` juga menangkap IMEI yang **quant**-nya berubah (DO / retur tidak mengubah `write_date` IMEI). CMS menyimpan `imei.product_qty` (migration `2026_10_27_000001`, `NULL` = belum ter-sync → dianggap belum terjual). Cek **saat scan** lewat endpoint baru `GET /reward/imei/check` (sebelumnya list mobile tidak hit API) + dicek ulang saat submit / input CMS → `IMEI_NOT_SOLD`. IMEI yang pernah `REJECTED` boleh di-scan lagi |
|
||
|
||
## Alur Scan IMEI → Pengajuan → Approval
|
||
|
||
Berlaku untuk cek saat scan (`GET /reward/imei/check`), submit SFA Mobile (`POST /reward/imei`), dan input admin CMS
|
||
(menu **IMEI Registration**). Kode error mobile sama persis dengan respon API. Cek C–D dijalankan **per IMEI**, urut
|
||
seperti di chart: saat scan hasilnya `200 scannable: false` + `error.code` (IMEI tidak masuk list), saat submit semua
|
||
alasan dikumpulkan ke `422 IMEI_REJECTED` (`data.errors[]`), di CMS tampil sebagai error di line itu.
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A0["SFA Mobile: scan IMEI<br/>GET /reward/imei/check?imei_number"] --> CK["Cek C–D (tanpa lock, tidak menyimpan)"]
|
||
CK -- "ada yang gagal" --> CK1["200 scannable: false + error.code<br/>IMEI tidak masuk list"]
|
||
CK -- lolos --> CK2["200 scannable: true<br/>product, program, reward_amount<br/>→ IMEI masuk list"]
|
||
CK2 --> A["List IMEI + nota opsional → kirim<br/>POST /reward/imei {imei_number: [..], request_id baru, attachment?}<br/>atau Admin CMS: Buat Pengajuan<br/>(Reward + customer + attachment opsional + IMEI per line)"]
|
||
A --> V{"Body valid?<br/>array 1–100 tanpa dobel,<br/>nota (kalau ada) PDF / PNG / JPG ≤ 5MB"}
|
||
V -- tidak --> V1["400"]
|
||
V -- ya --> B{"request_id<br/>sudah pernah dipakai?<br/>(mobile saja)"}
|
||
B -- "ya, user & daftar IMEI sama" --> B1["200 replay<br/>hasil submit sebelumnya"]
|
||
B -- "ya, user / daftar IMEI lain" --> B2["409 REQUEST_ID_CONFLICT"]
|
||
B -- tidak --> C{"Per IMEI: ada di<br/>master IMEI?"}
|
||
C -- tidak --> C1["IMEI_NOT_FOUND"]
|
||
C -- ya --> E{"IMEI sudah pernah dapat reward?<br/>(ada di ledger, termasuk<br/>yang sudah di-claim)"}
|
||
E -- ya --> E1["IMEI_ALREADY_REWARDED"]
|
||
E -- tidak --> P{"IMEI ini masih menunggu<br/>approval (line SUBMITTED)?<br/>REJECTED tidak dihitung"}
|
||
P -- ya --> P1["IMEI_PENDING_APPROVAL"]
|
||
P -- tidak --> S{"Sudah terjual?<br/>imei.product_qty = 0<br/>(NULL = belum sync)"}
|
||
S -- tidak --> S1["IMEI_NOT_SOLD"]
|
||
S -- ya --> D{"Program ACTIVE + mapping produk<br/>berlaku hari ini?<br/>(CMS: di Reward yang dipilih)"}
|
||
D -- tidak --> D1["NO_ACTIVE_REWARD"]
|
||
D -- ya --> Q["IMEI lolos"]
|
||
C1 & E1 & P1 & S1 & D1 & Q --> R{"Ada IMEI yang ditolak?"}
|
||
R -- ya --> R1["422 IMEI_REJECTED<br/>errors[] per IMEI<br/>tidak ada IMEI / nota yang disimpan"]
|
||
R -- tidak --> O{"Customer punya pengajuan<br/>SUBMITTED?"}
|
||
O -- ya --> F["Semua IMEI ditambah sebagai line<br/>di pengajuan itu, nota sama (atau null)"]
|
||
O -- tidak --> F0["Buat pengajuan baru<br/>kode RIS + YYMMDD + id"]
|
||
F0 --> F
|
||
F --> F2["201 WAITING APPROVAL<br/>submitted_lines[], produk & nominal dikunci<br/>saldo BELUM bertambah"]
|
||
|
||
classDef ok fill:#d1fae5,stroke:#059669,color:#064e3b
|
||
classDef err fill:#fee2e2,stroke:#dc2626,color:#7f1d1d
|
||
class CK2,B1,Q,F0,F,F2 ok
|
||
class CK1,V1,B2,C1,D1,E1,P1,S1,R1 err
|
||
```
|
||
|
||
Hijau = lolos / tersimpan · merah = ditolak (kode per IMEI tanpa angka HTTP = isi `data.errors[].code`).
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
S["Pengajuan customer SUBMITTED<br/>(berisi line IMEI dari mobile + CMS)"] --> T{"Ada IMEI bermasalah?"}
|
||
T -- ya --> T1["Tolak IMEI (per line) + alasan<br/>line REJECTED, total dikurangi"]
|
||
T1 --> T2{"Masih ada line<br/>menunggu?"}
|
||
T2 -- tidak --> R0["Pengajuan REJECTED<br/>(semua IMEI ditolak)"]
|
||
T2 -- ya --> S
|
||
T -- tidak --> G{"Approve / Reject pengajuan<br/>(satu-satu / bulk)"}
|
||
G -- "Reject + alasan" --> R["REJECTED: semua line menunggu ditolak<br/>IMEI boleh di-scan / diajukan lagi"]
|
||
G -- Approve --> H{"Approver pernah input / scan<br/>IMEI di pengajuan ini?"}
|
||
H -- ya --> H1["Ditolak: harus user lain<br/>(bulk: dilewati)"]
|
||
H -- tidak --> N{"Ada IMEI baru masuk sejak<br/>dialog approve dibuka?"}
|
||
N -- ya --> N1["Gagal: muat ulang lalu approve lagi"]
|
||
N -- tidak --> I{"Ada IMEI yang sudah dapat<br/>reward dari jalur lain?"}
|
||
I -- ya --> I1["Gagal: tolak IMEI itu dulu"]
|
||
I -- tidak --> J["Satu transaksi DB: EARN per IMEI<br/>(request_id = RIS…-line_id) + saldo bertambah<br/>→ APPROVED, header ditutup"]
|
||
J -.-> K["Scan berikutnya membuka<br/>pengajuan baru"]
|
||
|
||
classDef ok fill:#d1fae5,stroke:#059669,color:#064e3b
|
||
classDef err fill:#fee2e2,stroke:#dc2626,color:#7f1d1d
|
||
class J,K,L ok
|
||
class T1,R0,R,H1,N1,I1 err
|
||
```
|
||
|
||
Hijau = sukses, merah = ditolak / gagal (saldo tidak berubah).
|
||
|
||
## Alur Claim
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
H["SFA Mobile: Claim Full Balance<br/>amount = saldo di layar<br/>(hanya reward yang sudah APPROVED)"] --> I{"amount = saldo<br/>saat diproses?"}
|
||
H2["Admin CMS: Saldo Reward → tab Reward Ledger<br/>tombol Claim (permission claim_reward::balance)<br/>amount = saldo saat dialog dibuka"] --> I
|
||
I -- "saldo 0" --> I1["422 BALANCE_EMPTY<br/>(CMS: tombol tidak tampil)"]
|
||
I -- "beda" --> I2["409 BALANCE_CHANGED + saldo terbaru<br/>(CMS: Claim gagal, muat ulang)"]
|
||
I -- sama --> J["Satu transaksi DB:<br/>reward_claim + CLAIM_DEBIT<br/>saldo jadi 0"]
|
||
J --> K["reward_claim<br/>integration_status = QUEUED"]
|
||
K --> L["CMS → Odoo tiap menit<br/>Draft Vendor Bill (lihat dokumen integrasi)"]
|
||
|
||
classDef ok fill:#d1fae5,stroke:#059669,color:#064e3b
|
||
classDef err fill:#fee2e2,stroke:#dc2626,color:#7f1d1d
|
||
classDef todo fill:#f3f4f6,stroke:#9ca3af,color:#374151,stroke-dasharray:4 3
|
||
class J,K ok
|
||
class I1,I2 err
|
||
```
|
||
|
||
Hijau = sukses, merah = ditolak (saldo tidak berubah), abu-abu putus-putus = belum dikerjakan. Claim dari CMS (di luar FDD)
|
||
memakai `RewardClaimService` dengan aturan yang sama: `request_id` = `CMS-<uuid>`, CLAIM_DEBIT `reason` "Claim dari CMS",
|
||
`created_by` = admin; claim-nya tampil juga di `GET /reward/claims` customer.
|
||
|
||
## 2. Tabel (migration CMS `2026_10_13_000003_create_reward_tables`)
|
||
|
||
| Tabel | Isi | Ditulis oleh |
|
||
|---|---|---|
|
||
| `reward_program` | Program: kode, nama, periode, status `DRAFT/ACTIVE/PAUSED/ENDED`, `claim_mode = FULL_BALANCE` | CMS |
|
||
| `reward_product_mapping` | Nominal per IMEI per produk, `effective_from/to`, `ACTIVE/INACTIVE` | CMS |
|
||
| `reward_transaction` | **Ledger**: `EARN` (+), `CLAIM_DEBIT` (−), `REVERSAL`/`ADJUSTMENT` (±). Tidak pernah di-update/dihapus. `request_id` unik (EARN = kode RIS pengajuan, CLAIM_DEBIT = kosong) | EARN: CMS (approve) · CLAIM_DEBIT: Node |
|
||
| `reward_balance` | Saldo per user (`balance`, `total_earned`, `total_claimed`, `total_adjusted`). Di-update di transaksi DB yang sama dengan ledger; baris ini yang di-lock (`FOR UPDATE`) | CMS (approve) · Node (claim) |
|
||
| `reward_claim` | Claim: `claim_code` `RCL`+YYMMDD+id, `status`, `integration_status` (`QUEUED` = outbox untuk Odoo), kolom Odoo bill / error / retry | Node (CMS untuk integrasi nanti) |
|
||
| `reward_imei_submission` | Header pengajuan IMEI (migration `2026_10_13_000004`), **satu `SUBMITTED` per customer** (kolom generated `open_user_id` unik): `submission_code` `RIS`+YYMMDD+id, `user_id`, `total_amount` (line yang tidak ditolak), `status` `SUBMITTED/APPROVED/REJECTED`, `submitted_at` (IMEI pertama), `updated_at` (IMEI terakhir), `reviewed_by/at`, `review_note` | Node (scan) · CMS (input + approve/reject) |
|
||
| `reward_imei_submission_line` | Satu baris per IMEI: `source` `MOBILE/CMS`, `request_id` (mobile, sama untuk semua line satu submit — index biasa sejak `2026_10_19_000001`), `imei_number`, snapshot `product_id/code`, `reward_program_id`, `reward_product_mapping_id`, `reward_amount`, catatan (CMS) + attachment (nota mobile / bukti CMS), `submitted_by`, `status` `SUBMITTED/APPROVED/REJECTED` + `reviewed_by/at`, `review_note` (alasan tolak per IMEI), `reward_transaction_id` | Node (scan) · CMS |
|
||
|
||
Scan mobile hanya menulis pengajuan. EARN + saldo ditulis CMS saat approve (`RewardImeiSubmissionService`).
|
||
Urutan lock di Node dan CMS sama supaya tidak deadlock: `reward_balance` customer → master `imei` → header. Lock saldo
|
||
menyerialkan semua tambah-IMEI / approve / claim satu customer (jadi tidak pernah ada dua header terbuka); lock master
|
||
IMEI menyerialkan scan IMEI yang sama dari customer berbeda.
|
||
|
||
## 3. Endpoint Node API (`sfa-api`)
|
||
|
||
Semua pakai header `token` dari `/auth/login`. Error membawa `data.code`.
|
||
|
||
| Endpoint | Fungsi | Respon penting |
|
||
|---|---|---|
|
||
| `GET /reward/imei/check?imei_number&program_id?` | Cek satu IMEI **saat scan**, sebelum masuk list (aturan sama dengan submit, tanpa menyimpan) | Selalu 200: `scannable: true` + `product`, `program`, `reward_amount`, atau `scannable: false` + `error` (`IMEI_NOT_FOUND` / `IMEI_ALREADY_REWARDED` / `IMEI_PENDING_APPROVAL` / `IMEI_NOT_SOLD` / `NO_ACTIVE_REWARD`) · 400 validasi |
|
||
| `POST /reward/imei` `{imei_number: [..], request_id, attachment?, program_id?}` | Submit list IMEI hasil scan + satu nota (opsional) → line di **pengajuan customer** (belum masuk saldo). Semua atau tidak sama sekali | 201 + `submission_code`, `status: SUBMITTED`, `total_amount`, `lines[]` (`line_id`, `imei_number`, `product`, `program`, `reward_amount`, `status`, `source`, `attachment`, `reject_reason`), `submitted_lines[]` (IMEI request ini), `balance` (saat ini) · 200 `replay` · 400 IMEI dobel / nota tidak valid · 422 `IMEI_REJECTED` + `errors[]` (`IMEI_NOT_FOUND` / `IMEI_ALREADY_REWARDED` / `IMEI_PENDING_APPROVAL` / `IMEI_NOT_SOLD` / `NO_ACTIVE_REWARD` per IMEI) · 409 `REQUEST_ID_CONFLICT` |
|
||
| `PUT /reward/imei/attachment` `{line_ids, attachment}` | Ganti nota IMEI di list pengajuan (masih `SUBMITTED`, sumber `MOBILE`) | 200 + URL nota baru, `submissions[]` · 404 `LINE_NOT_FOUND` · 409 `LINE_ALREADY_REVIEWED` / `LINE_NOT_FROM_MOBILE`. Nota lama dihapus kalau tidak dipakai IMEI lain |
|
||
| `GET /reward/imei-submissions?page&limit&status` | Riwayat pengajuan saya (mobile + CMS) | Format sama dengan respon scan. Maksimal satu `SUBMITTED`. `status` pengajuan `SUBMITTED` / `APPROVED` / `REJECTED` + `reject_reason`; status per IMEI di `lines[].status` |
|
||
| `GET /reward/balance` | Saldo | `balance`, totals, `pending_approval` (reward menunggu approval, belum bisa di-claim), `pending_integration`, `claimable` |
|
||
| `GET /reward/transactions?page&limit&trans_type` | Ledger saya | — |
|
||
| `POST /reward/claim` `{request_id, amount}` | Claim full balance | 201 + `claim_code`, `balance` 0 · 409 `BALANCE_CHANGED` + saldo terbaru · 422 `BALANCE_EMPTY` |
|
||
| `GET /reward/claims?page&limit&status` | Riwayat claim | `display_status`: `PROCESSING` / `DRAFT_BILL_CREATED` / `NEEDS_ASSISTANCE` / `REVERSED` |
|
||
|
||
**`amount` di claim** = saldo yang tampil di layar. Kalau saldo berubah sebelum diproses (reward baru masuk / claim lain),
|
||
claim ditolak 409 dengan saldo terbaru → mobile menampilkan ulang, user konfirmasi, kirim dengan `request_id` baru.
|
||
Ini memenuhi UAT "CMS menghitung ulang saldo dan mengonfirmasi nominal full-balance yang benar sebelum debit".
|
||
|
||
**`request_id`**: dibuat mobile (UUID) per aksi, dikirim ulang apa adanya saat retry → hasil sama, tanpa reward/debit ganda.
|
||
Unik **global** (semua user), 8–64 karakter `[A-Za-z0-9_-]`. Submit IMEI disimpan di `reward_imei_submission_line.request_id`
|
||
(sama untuk semua line dari satu submit; replay dicocokkan dengan **daftar IMEI**, urutan bebas), claim di
|
||
`reward_claim.request_id`. `request_id` lama yang dipakai untuk daftar IMEI lain / user lain /
|
||
nominal claim lain → `409 REQUEST_ID_CONFLICT` (submit: ada `used_for_imei[]`). Untuk tes manual di Swagger cukup `MITO0001`,
|
||
`MITO0002`, …; di aplikasi tetap UUID supaya dua HP tidak bertabrakan.
|
||
|
||
File: `routes/services/serviceReward.js`, `routes/handler/reward/reward.js`, `routes/validator/validatorReward.js`,
|
||
`routes/helpers/enums/reward.js`, `models/Mreward*.js` (termasuk `MrewardImeiSubmission`), `validateUserJWT` di `validatorJWT.js`, route di `routes/sfa.js`, Swagger tag **Reward**.
|
||
|
||
## 4. Menu CMS (grup **Reward**)
|
||
|
||
| Menu | Isi |
|
||
|---|---|
|
||
| **Reward Program** | CRUD program (tidak bisa dihapus, akhiri dengan ENDED) + relation manager **Product Reward Mapping** (validasi overlap, kunci nominal setelah dipakai, hapus hanya kalau belum dipakai) |
|
||
| **Saldo Reward** | List saldo per customer (saldo, earned, claimed, pending integration, last activity; filter tipe user, rentang saldo, tanggal). Detail: **Reward Ledger** (filter type/program, tombol **Claim** = claim seluruh saldo atas nama customer, tampil bila saldo > 0 dan punya `claim_reward::balance`) + **Claim History** |
|
||
| **Claim History** | Semua claim (filter status, status integrasi, tanggal). Detail: data claim + blok Integrasi Odoo |
|
||
| **IMEI Registration** | Satu baris per pengajuan customer (tombol **New IMEI Registration**). List (badge = jumlah WAITING APPROVAL, kolom Sumber / Reward / IMEI / Jumlah IMEI / Total / IMEI terakhir masuk, filter Sumber, Reward, status, tanggal, cari per IMEI) dengan **bulk Approve / Reject**, form Buat Pengajuan (header + line IMEI), detail (header + tabel IMEI dengan **Tolak IMEI** per baris) dengan tombol **Approve** / **Reject**. Lihat §5 |
|
||
|
||
Ledger di detail **Saldo Reward** punya kolom **Sumber**: `Scan Mobile` / `Input CMS` (EARN, dari pengajuannya), `Mobile` (claim).
|
||
|
||
Permission Shield: `*_reward::program`, `*_reward::balance` (+ `claim_reward::balance`), `*_reward::claim` (policy sudah di-generate), dan
|
||
`view / view_any / create / approve / reject _reward::imei::submission`. Di server:
|
||
`php artisan shield:generate --resource=RewardProgramResource,RewardBalanceResource,RewardClaimResource --panel=admin`
|
||
lalu `php artisan shield:generate --resource=RewardImeiSubmissionResource,RewardBalanceResource --panel=admin --ignore-existing-policies`
|
||
(**wajib** `--ignore-existing-policies`, kalau tidak policy custom tertimpa dan pengajuan jadi bisa di-edit / dihapus).
|
||
Setelah itu centang permission di role yang sesuai: pembuat pengajuan cukup `create`, approver `approve` + `reject`.
|
||
|
||
## 5. Pengajuan IMEI & Approval (di luar FDD)
|
||
|
||
Semua IMEI masuk Pengajuan IMEI dulu; reward baru masuk saldo setelah di-approve. Alur lengkap di chart
|
||
**Alur Scan IMEI → Pengajuan → Approval** di atas.
|
||
|
||
| Hal | Aturan |
|
||
|---|---|
|
||
| Satu pengajuan per customer | Customer hanya punya **satu pengajuan `SUBMITTED`**. Scan mobile dan input CMS untuk customer itu masuk sebagai line di pengajuan yang sama, lintas reward program. Setelah pengajuan di-approve / ditolak, IMEI berikutnya membuka pengajuan baru |
|
||
| Sumber line | `MOBILE`: scan SFA Mobile, `submitted_by` = user yang scan. `CMS`: admin dengan `create_reward::imei::submission` atas nama customer (user `status = APPROVED`, internal maupun external), bila scan mobile tidak bisa |
|
||
| Form CMS — header | **Reward** (Reward Program ACTIVE hari ini, untuk IMEI yang diinput sekarang), **Customer**, **Attachment** jpg / png / pdf (opsional, maks 5 MB, `files/reward_imei_submission`), **Reason** (opsional, mis. alasan scan mobile tidak bisa). Program, reason, dan attachment disimpan di tiap line yang diinput (kolom Reason di tabel IMEI) |
|
||
| Form CMS — line IMEI | Isi IMEI → **Product dan Reward terisi otomatis** dari master IMEI + mapping program terpilih (read-only). Tombol **Add IMEI** menambah line baru. Total reward + jumlah IMEI tampil di bawah. Ganti Reward → semua line dihitung ulang. IMEI yang sama tidak boleh diisi dua kali. Setelah submit → diarahkan ke detail pengajuan customer itu |
|
||
| Validasi saat scan / submit (per IMEI) | IMEI di master, mapping ACTIVE **hari ini** (CMS: di program yang dipilih), IMEI + produk belum dapat reward, IMEI tidak sedang menunggu approval (`409 IMEI_PENDING_APPROVAL`, `by_you`). Di CMS error tampil di line IMEI yang salah |
|
||
| Status | Pengajuan: `SUBMITTED` (tampil **WAITING APPROVAL**) → `APPROVED` / `REJECTED`. Line: `SUBMITTED` → `APPROVED` (ikut approve pengajuan) / `REJECTED` (ditolak sendiri atau ikut reject pengajuan). Tidak bisa diedit / dihapus |
|
||
| Nominal | **Dikunci per IMEI saat masuk**. Kalau program berakhir atau nominal mapping diubah sebelum approve, yang dibayar tetap nominal saat itu |
|
||
| Tolak IMEI (per line) | Di tabel IMEI pada detail pengajuan, user dengan `reject_reward::imei::submission`, alasan wajib (tampil di mobile sebagai `lines[].reject_reason`). Total pengajuan dikurangi; pengajuan tetap menunggu. Kalau semua IMEI ditolak, pengajuan ikut `REJECTED` |
|
||
| Approve | User dengan `approve_reward::imei::submission` yang **tidak meng-input / scan IMEI mana pun yang menunggu di pengajuan itu**. Dialog approve tanpa isian catatan. Satu transaksi DB: satu EARN per line `SUBMITTED` (`request_id` = `RIS…-<line_id>`, `reason` = "Scan IMEI RIS…" / "Pengajuan IMEI CMS RIS…", `created_by` = approver), saldo bertambah, pengajuan `APPROVED`. Gagal kalau ada IMEI baru masuk sejak dialog approve dibuka (muat ulang) atau ada IMEI yang sudah dapat reward dari jalur lain (tolak IMEI itu dulu) |
|
||
| Reject pengajuan | Alasan wajib; semua line yang menunggu ikut ditolak. Semua IMEI-nya boleh di-scan / diajukan lagi |
|
||
| Bulk | Approve / Reject banyak pengajuan sekaligus dari list (hanya WAITING APPROVAL yang bisa dicentang). Tiap pengajuan transaksi sendiri; yang gagal dilewati dan dilaporkan di notifikasi. Bulk approve tidak memakai cek "IMEI baru masuk" — semua line yang menunggu saat diproses ikut di-approve |
|
||
| Di SFA Mobile | Scan masuk list lokal dulu; setelah nota ditambah dan dikirim, tampilkan "menunggu approval" + `submitted_lines[].reward_amount`. Kalau `422 IMEI_REJECTED`, tandai IMEI di `errors[]` di list (hapus / perbaiki) lalu kirim ulang dengan `request_id` baru. Pengajuan + status per IMEI dari `GET /reward/imei-submissions`; total menunggu dari `pending_approval` di `GET /reward/balance`. Reward yang di-approve muncul di `GET /reward/transactions` sebagai `EARN` dan bisa di-claim |
|
||
|
||
File CMS: `RewardImeiSubmissionService`, `RewardImeiSubmissionResource` (+ Pages, `RelationManagers\LinesRelationManager`), `RewardImeiSubmission`, `RewardImeiSubmissionLine`,
|
||
`RewardImeiSubmissionStatusEnum`, `RewardImeiSubmissionPolicy`, migration `2026_10_13_000004_create_reward_imei_submission_table`.
|
||
File Node: `submitImei` / `replaceImeiAttachment` / `getSubmissions` di `serviceReward.js`, `models/MrewardImeiSubmission.js` + `MrewardImeiSubmissionLine.js`, route `GET /reward/imei-submissions`.
|
||
|
||
## 6. Pengujian (lokal, 13-10-2026)
|
||
|
||
- **Node, 24/24 lolos** (versi awal, scan langsung EARN — digantikan uji approval di bawah): token registrant/tanpa token 403, EARN + replay, request_id milik user lain,
|
||
IMEI duplikat, IMEI tidak ada, produk tanpa mapping, program_id salah, **5 scan paralel IMEI sama → tepat 1 reward**,
|
||
claim nominal salah → `BALANCE_CHANGED`, claim + replay, saldo kosong, **5 claim paralel → tepat 1 debit, saldo 0**,
|
||
SUM ledger = saldo, filter & isolasi antar user. Tidak ada respon 500.
|
||
- **CMS, 12/12 lolos** (Livewire): semua halaman list/create/edit/view + relation manager ter-render; overlap mapping
|
||
produk sama ditolak, produk lain diterima.
|
||
- **Pengajuan IMEI, 2 test / 96 assertion lolos** (PHPUnit + Livewire, rollback otomatis): IMEI tidak ada / produk
|
||
tanpa mapping / alasan kosong ditolak form, preview produk & nominal tampil, submit → kode RIS, pengajuan ganda
|
||
ditolak, pembuat tidak bisa approve (tombol disabled), user tanpa permission tidak melihat tombol, approve →
|
||
EARN + saldo bertambah (SUM ledger = saldo), approve/reject ulang ditolak, reject dari tabel wajib alasan,
|
||
IMEI yang sudah di-scan mobile saat pengajuan menunggu → approve gagal tanpa reward dobel, kolom Sumber `CMS`.
|
||
- **Approval scan mobile, E2E 27/27 lolos** (HTTP Node + approve/reject lewat service CMS): scan → 201 `SUBMITTED` saldo
|
||
tetap 0, replay 200, `REQUEST_ID_CONFLICT`, `IMEI_PENDING_APPROVAL` (user sama & lain), **5 scan paralel IMEI sama →
|
||
tepat 1 pengajuan**, `pending_approval` di balance, ledger kosong & claim `BALANCE_EMPTY` selama pending, list + filter +
|
||
isolasi user, pemilik scan tidak bisa approve, approve → EARN + saldo, reject → `reject_reason`, IMEI ter-reward →
|
||
`IMEI_ALREADY_REWARDED`, IMEI ditolak boleh di-scan ulang, claim full balance, SUM ledger = saldo.
|
||
- **Claim dari CMS, 29 assertion lolos** (Livewire): tombol tersembunyi tanpa permission, saldo berubah setelah dialog
|
||
dibuka → gagal tanpa claim, claim → `RCL…` PROCESSING / QUEUED + CLAIM_DEBIT (`created_by` admin) + saldo 0,
|
||
SUM ledger = saldo, tombol hilang saat saldo 0.
|
||
- **Satu pengajuan per customer — Node E2E 26/26 lolos**: scan pertama buka header, scan berikutnya masuk header
|
||
yang sama, **2 scan paralel IMEI berbeda → tetap 1 header**, 4 scan paralel IMEI sama → tepat 1 masuk, replay,
|
||
`REQUEST_ID_CONFLICT`, `IMEI_PENDING_APPROVAL` (user sama & lain), `pending_approval`, user yang scan tidak bisa
|
||
approve, tolak 1 IMEI (header tetap menunggu, total berkurang), approve dengan daftar IMEI basi ditolak, approve →
|
||
4 EARN + saldo, IMEI ditolak bisa di-scan lagi → header baru, reject pengajuan, claim, SUM ledger = saldo.
|
||
- **CMS, 89 assertion lolos** (Livewire): input CMS masuk header customer yang sudah berisi scan mobile (redirect ke
|
||
detail, notifikasi "N IMEI masuk ke pengajuan …"), 2 program dalam 1 header, customer lain header sendiri, list 1
|
||
baris per customer + cari IMEI + filter Sumber, maker tidak bisa approve, Tolak IMEI wajib alasan, IMEI baru masuk
|
||
setelah dialog approve dibuka → gagal, approve → EARN per line + saldo, header baru setelah ditutup, bulk approve,
|
||
kolom Sumber ledger. Halaman list / detail / create dirender dengan data lokal.
|
||
- **Form header + line IMEI, 68 assertion lolos** (versi satu pengajuan per input) (Livewire, setelah pengajuan dipecah header/line): halaman create
|
||
menampilkan Add IMEI & Attachment, product & reward terisi otomatis per line, total `Rp 55.000 (2 IMEI)`, ganti Reward
|
||
→ line dihitung ulang, error per line (produk di program lain / tanpa mapping / IMEI tidak ada / IMEI dobel), submit
|
||
2 IMEI → header CMS + 2 line, IMEI di pengajuan menunggu ditolak, pembuat tidak bisa approve, approve → 2 EARN
|
||
(`RIS…-line_id`) + saldo +55.000, pengajuan multi-IMEI dengan 1 IMEI sudah ter-reward → bulk approve gagal tanpa
|
||
mengubah saldo, cari per IMEI di list, kolom Sumber ledger. E2E Node 27/27 diulang dengan format `lines[]`.
|
||
- **CMS bulk & sumber, 60 assertion lolos** (Livewire, versi sebelum header/line): form CMS → `source = CMS`, form menolak IMEI yang pending dari
|
||
mobile, filter Sumber, bulk approve (pengajuan sendiri dilewati: "2 di-approve, 1 gagal"), bulk reject wajib alasan,
|
||
detail menampilkan Sumber / alasan, reason ledger per sumber, kolom Sumber di ledger saldo.
|
||
- Data uji sudah dibersihkan dari DB lokal.
|
||
|
||
**Submit list IMEI + nota (lokal, 19-10-2026)** — HTTP ke Node, DB lokal: 3 IMEI + nota → 201, 3 line nota sama, total
|
||
30.000 · kirim ulang (urutan IMEI dibalik) → 200 `replay`, file nota kedua terhapus · `request_id` sama untuk IMEI lain →
|
||
409 `REQUEST_ID_CONFLICT` + `used_for_imei[]` · 3 IMEI (1 pending, 1 tidak ada) → 422 `IMEI_REJECTED` 2 alasan, IMEI yang
|
||
valid ikut tidak disimpan, file terhapus · IMEI dobel (`" 1122"` & `"1122"`) → 400 · tanpa nota → 400 · `PUT` ganti nota 2
|
||
dari 3 line → nota lama tetap dipakai line ke-3 · `POST /reward/imei/attachment` → 404. Migration `2026_10_19_000001`
|
||
up → rollback → up lolos. Data uji dibersihkan.
|
||
|
||
## 7. Belum Dikerjakan
|
||
|
||
| Hal | Kenapa / butuh apa |
|
||
|---|---|
|
||
| ~~Integrasi Odoo — Draft Vendor Bill~~ | ✅ Dikerjakan 14-10-2026: [[SFA — Reward Claim ke Odoo (Draft Vendor Bill)]]. Sisa: deploy Odoo → CMS, keputusan Finance (akun expense, jurnal, pajak, OU) |
|
||
| Audit trail status claim | Tabel history status claim ditambahkan bersama integrasi Odoo (saat ini status hanya berubah sekali saat dibuat) |
|
||
| Adjustment / Reversal dari CMS | Action terkontrol + alasan + approver. FDD §12: siapa yang berwenang masih terbuka |
|
||
| Monthly settlement / rekonsiliasi | Laporan snapshot saldo per periode + exception claim tanpa bill |
|
||
| Eligibility (kanal / wilayah) | Belum ada aturannya di FDD |
|
||
| Maker-checker config | FDD §12 masih terbuka |
|
||
| Kabari tim mobile | **Kontrak submit IMEI berubah 19-10-2026** (`imei_number` array + `attachment` wajib, `IMEI_REJECTED.errors[]`, `submitted_lines[]` menggantikan `line`, POST attachment dihapus). Kontrak endpoint lain di atas, terutama: scan **tidak langsung menambah saldo** (status `SUBMITTED`, `IMEI_PENDING_APPROVAL`, `GET /reward/imei-submissions`, `pending_approval`), `request_id`, dan alur `BALANCE_CHANGED` |
|
||
| Notifikasi hasil approval ke mobile | Saat ini mobile harus polling `GET /reward/imei-submissions`; push notification belum ada |
|