Doc_chelvyn/Mito/Sfa/Fitur/SFA — Reward.md

286 lines
28 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

---
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 |