---
judul: SFA — Plan Revisi 09-11-2026 (SO, Vendor Bill per Reward, History Scan Staff, Export, IMEI Manual)
proyek: SFA API · SFA CMS · mito_odoo · SFA Mobile
terkait: Mito · Odoo 18
kategori: Fitur
status: Plan — belum ada kode · menunggu jawaban Keputusan P1–P9
tipe: dokumen-internal
tags:
- sfa
- reward
- imei
- vendor-bill
- sales-order
- plan
diperbarui: 2026-11-09
---
> Index: [[SFA — Index]] · Kategori: **Fitur** · Terkait: [[SFA — Reward]] ·
> [[SFA — Revisi Reward MoM 22-10-2026]] · [[SFA — Reward Claim ke Odoo (Draft Vendor Bill)]]
# SFA — Plan Revisi 09-11-2026
Rencana kerja untuk 5 permintaan revisi. **Belum ada kode yang diubah.** Bagian bertanda **[cek]** masih asumsi dan
harus dicocokkan dulu ke kode sebelum ngoding.
**Cara baca dokumen ini**
| Pembaca | Bagian |
|---|---|
| Functional / PM / Mito | [Ringkasan](#Ringkasan) · [Keputusan yang Dibutuhkan](#Keputusan%20yang%20Dibutuhkan) · alur (Mermaid) di tiap poin |
| Developer / Senior | Desain teknis per poin · [Urutan Kerja & Deploy](#Urutan%20Kerja%20&%20Deploy) |
## Ringkasan
| # | Permintaan | Repo | Ukuran | Status |
|---|---|---|---|---|
| 1 | Integrasi Sales Order ke Odoo: revisi lewat CMS, atau dari Mobile langsung ke Odoo | api · cms · odoo · mobile | Besar | ⬜ Menunggu keputusan arsitektur (P1) |
| 2 | Vendor Bill hasil claim **dipisah per Reward** (bukan 1 bill per claim) | cms · odoo | Sedang | ⬜ **Membalik keputusan K1** — perlu konfirmasi (P2, P3) |
| 3 | API history scan IMEI: dealer bisa filter per staff, rekap IMEI yang di-scan staffnya (mobile) | api · mobile | Kecil–sedang | ⬜ Siap dikerjakan setelah [cek] relasi staff |
| 4 | Export untuk edit / update (by ID atau External ID) | cms **atau** odoo | Sedang | ⬜ Objek & sistem belum jelas (P5) |
| 5 | IMEI bisa diketik manual (free text) saat scan | mobile · api | Kecil | ⬜ Siap dikerjakan |
**Usulan urutan:** 5 + 3 dulu (kecil, langsung kerasa di mobile) → 2 (uang/akuntansi, scope jelas setelah P2/P3) →
4 → 1 (paling besar, butuh keputusan dulu).
---
## 1. Sales Order: lewat CMS atau Mobile langsung ke Odoo
**Konteks:** MoM 22-10-2026 ([[Fix sfa aftrer meet with mito]]) menyebut *"Salesman hanya menginput Product dan
Quantity"*. **Direvisi 09-11-2026: field harga boleh disediakan di mobile** (opsional, lihat desain di bawah).
Diskon, promo, dan pajak tetap dihitung Odoo. Alur SO yang jalan sekarang di
`sfa-api` / CMS belum dipetakan **[cek]**. Odoo sudah punya endpoint sale order di `mito_base` (`controllers/api/`,
lihat temuan #3 di [[SFA — Reward Claim ke Odoo (Draft Vendor Bill)#9. Temuan Selama Pengujian]]) **[cek isi & pemakainya]**.
### Perbandingan
| | A. Mobile → CMS/API → Odoo (**rekomendasi**) | B. Mobile → Odoo langsung |
|---|---|---|
| Kredensial | API key Odoo tetap di server | API key Odoo harus ada di aplikasi mobile, bisa dibongkar dari APK |
| Retry / offline | Outbox di CMS (pola sama dengan claim reward: `QUEUED → SENDING → SUCCESS / RETRY / PERMANENT_ERROR`) | Mobile urus retry sendiri, rawan SO dobel |
| Beban Odoo | Bisa di-batch & dibatasi; penting karena Odoo masih **single-process** | Setiap tap mobile = 1 request ke Odoo |
| Visibilitas admin | SO gagal terlihat di CMS + tombol **Kirim Ulang ke Odoo** | Tidak ada tempat memantau |
| Ubah alur | Deploy server saja | Rilis ulang aplikasi ke store |
| Latensi | +1 hop (±1 menit kalau lewat worker, atau sinkron kalau perlu nomor SO langsung) | Langsung |
### Desain usulan (opsi A)
- Mobile kirim `{request_id, customer, lines: [{product_code, qty, price_unit?}]}` ke `sfa-api`.
- **Harga boleh diinput dari mobile (revisi 09-11-2026)**, menggantikan catatan MoM 22-10 "salesman hanya input
Product dan Quantity". `price_unit` **opsional**:
- Diisi → Odoo pakai harga itu sebagai `price_unit` line SO.
- Kosong → Odoo hitung dari pricelist (perilaku standar).
- Mobile tampilkan harga default dari master product / pricelist sebagai nilai awal, salesman boleh ubah.
- Hati-hati: helper `get_float` di `mito_base/controllers/api/core.py` menganggap `0` = kosong. Kalau salesman isi
harga **0**, harga akan jatuh ke pricelist tanpa pesan. Endpoint SO harus parsing `price_unit` sendiri (pola sama
dengan `amount` di endpoint reward-bills): `null` = pakai pricelist, `0` = ditolak atau diterima sesuai keputusan P9.
- Interaksi dengan promo / diskon Odoo: harga manual = harga dasar, promo tetap dihitung di atasnya **[konfirmasi P9]**.
- CMS simpan SO lokal + status integrasi, worker kirim ke Odoo (`POST /api/v1/sale-orders` **[cek: endpoint yang ada / baru]**).
- Odoo: idempotency key `snk_sfa_order_ref` di `sale.order` + `unique` (pola sama dengan `snk_reward_claim_ref`).
Harga & promo dihitung Odoo (pricelist + promotion yang sudah ada).
- Respons balik: nomor SO, total, status. Disimpan di CMS, ditampilkan di mobile.
- Volume 500–1.000 SO/hari: pembuatan SO di Odoo pertimbangkan `snk_queue_job` kalau > 2 detik per SO.
```mermaid
flowchart TD
A["SFA Mobile: salesman input
customer + product + qty + harga (opsional)"] --> B["sfa-api: validasi
request_id, customer aktif, product aktif, harga ≥ 0"]
B -- "gagal" --> B1["400 / 422 ke mobile"]
B -- "ok" --> C["CMS: simpan SO lokal
integration QUEUED"]
C --> D["Worker CMS → POST Odoo sale order"]
D --> E{"snk_sfa_order_ref
sudah ada?"}
E -- "ya" --> E1["200 · SO lama dikembalikan"]
E -- "tidak" --> F0{"price_unit
dikirim?"}
F0 -- "ya" --> F1["pakai harga dari mobile"]
F0 -- "tidak" --> F2["harga dari pricelist"]
F1 & F2 --> F["Odoo hitung promo / pajak
create sale.order (draft / quotation)"]
F --> S["CMS: SUCCESS
simpan nomor SO + total"]
E1 --> S
D -- "422 data salah" --> P["PERMANENT_ERROR
admin perbaiki → Kirim Ulang"]
D -- "timeout / 5xx" --> R["RETRY bertahap"]
R --> D
S -.-> M["Mobile tampilkan nomor SO & total"]
classDef ok fill:#d1fae5,stroke:#059669,color:#064e3b
classDef err fill:#fee2e2,stroke:#dc2626,color:#7f1d1d
classDef warn fill:#fef3c7,stroke:#d97706,color:#78350f
classDef todo fill:#f3f4f6,stroke:#9ca3af,color:#374151,stroke-dasharray:4 3
class A,B,C,D,E,F0,F1,F2,F,S,E1,M,R,P todo
```
Semua node abu-abu putus-putus = belum dikerjakan (desain usulan).
---
## 2. Vendor Bill dipisah per Reward
**Permintaan:** 1 claim Rp 500.000 yang saldonya berasal dari **3 Reward (3 Jobsheet)** → di Odoo terbentuk
**3 Draft Vendor Bill**, masing-masing sebesar nominal reward-nya. Bukan 1 bill Rp 500.000.
> [!warning] Ini membalik keputusan K1 (30-10-2026)
> Di [[SFA — Revisi Reward MoM 22-10-2026]] K1 diputuskan **1 bill per claim**, nomor Jobsheet ditulis semua dipisah
> koma. Permintaan ini = opsi **a/b** K1 yang dulu tidak dipilih. Perlu konfirmasi siapa yang memutuskan dan tanggalnya,
> lalu K1 diperbarui.
### Interpretasi yang dipakai (perlu dikonfirmasi — P2)
- **"Reward" = Reward Program.** Jobsheet nempel di header program (`reward_program.jobsheet_no`), jadi
1 program = 0 atau 1 Jobsheet.
- Pemisah bill = **program**, bukan Jobsheet. Alasannya: Oliver bilang *"1 jobsheet bisa banyak reward"*. Kalau
dipisah per Jobsheet, 2 program dengan Jobsheet yang sama akan tergabung jadi 1 bill.
- Nominal per bill = **saldo bersih program itu** di ledger yang ikut ter-claim (EARN − reversal/adjustment per
program sejak claim sebelumnya). Logikanya sudah ada setengah di `RewardClaimOdooService::jobsheetNo()` (ambil
program-program EARN asal saldo claim) **[cek: ledger punya `program_id` di semua tipe transaksi?]**.
- Validasi: **Σ nominal per program = nominal claim**. Kalau tidak sama, claim ditolak dan tidak dikirim
(`PERMANENT_ERROR [split_mismatch]`), supaya tidak ada uang hilang atau dobel.
- Minimum claim Rp 500.000 tetap berlaku **per claim**, bukan per bill. Bill per program boleh di bawah 500.000.
### Desain teknis
**Odoo (`mito_base`):**
| Hal | Sekarang | Jadi |
|---|---|---|
| Endpoint | `POST /api/v1/reward-bills` 1 claim → 1 bill | Endpoint sama, body baru `rewards: [{program_code, program_name, jobsheet_no, amount}]`. Tanpa `rewards` → perilaku lama (kompatibel) |
| Idempotency | `unique(snk_reward_claim_ref)` | Field baru `snk_reward_program_ref` + `unique(snk_reward_claim_ref, snk_reward_program_ref)`. Constraint lama **di-drop** |
| Transaksi | 1 create | **Semua bill dalam 1 transaksi.** Satu gagal → semua rollback (tidak ada claim setengah jadi) |
| Retry | Claim ID ada → bill lama | Claim ID ada → kembalikan **semua** bill claim itu (`created: false`) |
| Label line | `Reward Claim ` | `Reward Claim · ` + Jobsheet No. per bill (bukan lagi dipisah koma) |
Perubahan constraint = perubahan struktur → **naikkan versi `mito_base` + migration script**:
- `pre-migrate` / `post-migrate`: `ALTER TABLE account_move DROP CONSTRAINT IF EXISTS account_move_snk_reward_claim_ref_uniq`
(idempotent). Constraint baru dibuat otomatis oleh `_sql_constraints`.
- Bill lama (1 per claim, `snk_reward_program_ref` NULL) tetap valid. NULL tidak bentrok di unique.
- **[cek]** apakah endpoint reward-bills sudah ter-deploy di production. Kalau belum, migration cukup ringan.
**CMS (`snk_sfa-cms`):**
- Tabel baru `reward_claim_bill` (`reward_claim_id`, `reward_program_id`, `program_code`, `jobsheet_no`, `amount`,
`odoo_bill_id`, `odoo_bill_ref`). Kolom `reward_claim.odoo_bill_id` dibiarkan untuk data lama.
- Pecahan dihitung **saat claim dibuat** dan disimpan (snapshot), bukan saat dikirim. Jadi kalau program diedit
sesudahnya, nilai bill tidak berubah.
- `RewardClaimOdooService::send()` kirim array `rewards`, simpan semua `id` bill dari respons.
- Filament Claim History: blok Integrasi Odoo tampilkan daftar bill per program.
- Mobile `GET /reward/claims`: tambah `bills[]` (opsional, tidak memecah kontrak lama).
```mermaid
flowchart TD
A["Claim full balance Rp 500.000
(mobile / CMS)"] --> B["CMS: hitung saldo bersih per program
dari ledger sejak claim terakhir"]
B --> C{"Σ per program
= nominal claim?"}
C -- "tidak" --> C1["PERMANENT_ERROR
split_mismatch"]
C -- "ya" --> D["Simpan snapshot reward_claim_bill
Program A 200rb · B 150rb · C 150rb"]
D --> E["Worker → POST /api/v1/reward-bills
claim_id + rewards[3]"]
E --> F{"Odoo: claim_id sudah
punya bill?"}
F -- "ya" --> F1["200 · created=false
semua bill lama"]
F -- "tidak" --> G["Validasi vendor & product
(422 sama seperti sekarang)"]
G -- "gagal" --> G1["422 → PERMANENT_ERROR"]
G -- "ok" --> H["1 transaksi: create 3 Draft Vendor Bill
tiap bill: program + Jobsheet No. + amount"]
H -- "salah satu gagal" --> H1["rollback semua → 422 / RETRY"]
H -- "ok" --> S["201 · 3 bill
CMS simpan odoo_bill_id per program"]
F1 --> S
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 C1,G1,H1 err
class B,C,D,H,S todo
class A,E,F,F1,G ok
```
Hijau = sudah ada di kode sekarang, abu-abu putus-putus = perubahan baru, merah = ditolak.
---
## 3. API History Scan IMEI per Staff Dealer
**Permintaan:** dealer punya rekap IMEI yang di-scan oleh staff-nya, bisa difilter per staff (tampilan mobile).
**Kondisi sekarang:** `GET /reward/imei-submissions` = riwayat pengajuan **milik saya**. Scan Staff Dealer masuk ke
pengajuan & saldo **dealer**-nya ([[SFA — Reward]] §2 poin 4). Belum jelas apakah line pengajuan menyimpan
**siapa yang scan** (staff mana) **[cek: `reward_imei_submission_line` punya `scanned_by` / `created_by`?]**.
Kalau belum ada, tambah kolom `scanned_by_user_id` (migration CMS, idempotent `hasColumn`). Data lama `NULL`, tampil
"tidak diketahui".
### Desain endpoint (`sfa-api`)
| Endpoint | Fungsi |
|---|---|
| `GET /reward/imei-submissions?staff_id&date_from&date_to&status&page&limit` | Endpoint lama + filter. Dealer: semua line milik dealer, bisa filter `staff_id`. Staff: **dipaksa** hanya line yang dia scan sendiri (`staff_id` diabaikan) |
| `GET /reward/imei-scans/summary?date_from&date_to` (baru) | Rekap per staff untuk dealer: `staff_id`, `staff_name`, `total_scan`, `approved`, `pending`, `rejected` |
| `GET /reward/staff` (baru, atau pakai `/registration/staff` yang ada **[cek]**) | Daftar staff milik dealer, untuk dropdown filter di mobile |
Aturan keamanan:
- `dealer_id` diambil dari **token**, bukan dari parameter. Kalau dari parameter, dealer A bisa intip data dealer B.
- `staff_id` yang bukan staff dealer tersebut → `403 STAFF_NOT_OWNED`.
- Nominal reward di respons untuk role staff mengikuti keputusan **K5** (masih terbuka).
- Index MySQL: `(customer_user_id, created_at)` dan `(scanned_by_user_id, created_at)` di tabel line **[cek nama kolom]**.
- Wajib pagination (`limit` maks 100).
```mermaid
flowchart TD
A["Mobile: buka Riwayat Scan
GET /reward/imei-submissions?staff_id=..."] --> B{"Role di token?"}
B -- "Staff Dealer" --> C["Paksa filter scanned_by = user sendiri
staff_id diabaikan"]
B -- "Dealer" --> D{"staff_id dikirim?"}
D -- "tidak" --> E["Semua line milik dealer"]
D -- "ya" --> F{"staff milik
dealer ini?"}
F -- "tidak" --> F1["403 STAFF_NOT_OWNED"]
F -- "ya" --> G["Line milik dealer
AND scanned_by = staff_id"]
B -- "lainnya" --> B1["403"]
C & E & G --> H["200 · list + pagination
(nominal ikut keputusan K5)"]
classDef err fill:#fee2e2,stroke:#dc2626,color:#7f1d1d
classDef todo fill:#f3f4f6,stroke:#9ca3af,color:#374151,stroke-dasharray:4 3
class F1,B1 err
class A,B,C,D,E,F,G,H todo
```
---
## 4. Export untuk Edit / Update (by ID atau External ID)
**Yang sudah ada:** Export/Import Excel **Reward Program** di CMS (upsert by `program_code` + `mapping_id`,
1 error = semua ditolak). Lihat [[SFA — Revisi Reward MoM 22-10-2026#Poin 6 · Export & Import Reward Program (Excel)]].
**Belum jelas (P5): export data apa, di sistem mana?**
| Kalau di… | Rencana |
|---|---|
| **Odoo** | Fitur **bawaan**: Export → centang *I want to update data (import-compatible export)* → kolom `id` (External ID) ikut → edit → Import. **Tanpa ngoding**, cukup template export tersimpan + training user. Record tanpa External ID otomatis dibuatkan `__export__.xxx` |
| **CMS** (objek selain Reward Program, mis. Customer, Employee External, Master IMEI) | Pakai pola `RewardProgramExcelService` yang sudah teruji: kolom kunci `id` di kolom pertama, upsert, **mode preview / dry-run** + laporan error per baris, 1 error = semua ditolak, proses sinkron (pindah ke queue kalau > ±2.000 baris) |
Aturan umum kalau dibuat di CMS:
- Baris dengan `id` cocok → update. `id` tidak dikenal → ditolak (bukan dibuat baru). `id` kosong → create **[konfirmasi]**.
- Kolom yang tidak ada di file → tidak disentuh (pola sama dengan `jobsheet_no`).
- Kolom milik Odoo (hasil sync, mis. data product / customer dari Odoo) **tidak boleh** di-update lewat import CMS,
karena akan tertimpa lagi oleh sync malam.
---
## 5. Input IMEI Manual (Free Text) saat Scan
**Permintaan:** selain scan kamera, user bisa **mengetik** IMEI (barcode rusak, kamera gagal, IMEI di dus pudar).
**Kondisi sekarang:** scan → `GET /reward/imei/check` → masuk list lokal → `POST /reward/imei`. API menerima string
IMEI, jadi **jalur validasinya sudah cocok**. Yang berubah terutama di mobile.
| Bagian | Perubahan |
|---|---|
| Mobile | Tombol **Ketik Manual** di layar scan → input teks → panggil `GET /reward/imei/check` yang **sama** → masuk list. Tidak boleh ada jalur validasi kedua |
| API | Normalisasi: `trim`, buang spasi / strip di tengah. Tambah param opsional `input_method = SCAN \| MANUAL` di check & submit |
| CMS | Kolom `input_method` di `reward_imei_submission_line` (default `SCAN`, migration idempotent). Tampil di IMEI Registration supaya approver tahu IMEI mana yang diketik |
| Validasi format | **[cek]** format IMEI di master (selalu 15 digit angka? ada serial non-IMEI?). Kalau semua 15 digit → cek Luhn di mobile supaya typo ketahuan sebelum hit API |
Kenapa `input_method` penting: input manual lebih rawan **IMEI karangan**. Karena tetap lewat approval CMS, approver
perlu tahu mana yang diketik, dan nanti bisa dibuat rekap / batas per user kalau ada penyalahgunaan (P7).
```mermaid
flowchart TD
A{"Cara input"} -- "Scan kamera" --> B["IMEI dari barcode
input_method = SCAN"]
A -- "Ketik manual" --> C["Input teks → trim, buang spasi"]
C --> C1{"Format valid?
(digit, panjang, Luhn [cek])"}
C1 -- "tidak" --> C2["Pesan di mobile, tidak hit API"]
C1 -- "ya" --> D["input_method = MANUAL"]
B & D --> E["GET /reward/imei/check"]
E -- "scannable: false" --> E1["IMEI_NOT_FOUND / IMEI_ALREADY_REWARDED /
IMEI_PENDING_APPROVAL / IMEI_NOT_SOLD / NO_ACTIVE_REWARD"]
E -- "scannable: true" --> F["Masuk list lokal"]
F --> G["POST /reward/imei + input_method per IMEI"]
G --> H["CMS IMEI Registration:
approver lihat badge MANUAL"]
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 B,E,F,G ok
class C2,E1 err
class A,C,C1,D,H todo
```
Hijau = sudah ada, abu-abu putus-putus = baru, merah = ditolak.
---
## Keputusan yang Dibutuhkan
| # | Poin | Pertanyaan | Usulan | Status |
|---|---|---|---|---|
| **P1** | 1 | SO lewat CMS/API atau Mobile langsung ke Odoo? Masalah apa di alur sekarang yang memicu usulan ini? | Lewat CMS/API (opsi A) | ⏳ |
| **P2** | 2 | "Reward" = **Reward Program**? Bill dipisah per program (bukan per Jobsheet)? | Ya, per program | ⏳ |
| **P3** | 2 | Siapa yang memutuskan K1 dibalik + tanggal? Claim lama yang sudah 1 bill: dibiarkan? | Dibiarkan, berlaku untuk claim baru | ⏳ |
| P4 | 2 | Saldo program tanpa Jobsheet: tetap jadi bill sendiri? | Ya, 1 bill per program, Jobsheet No. kosong | ⏳ |
| **P5** | 4 | Export untuk objek apa, di CMS atau Odoo? `id` kosong boleh create? | — | ⏳ |
| P6 | 3 | Dealer perlu lihat nominal reward per IMEI staff? (terkait K5) | Dealer ya, staff ikut K5 | ⏳ |
| P7 | 5 | Input manual dibatasi? (role tertentu / jumlah per hari) | Tidak dibatasi, cukup ditandai `MANUAL` | ⏳ |
| P8 | 5 | Format IMEI di master selalu 15 digit? | — **[cek data]** | ⏳ |
| P9 | 1 | Harga dari mobile: boleh **0** / di bawah harga pricelist? Promo Odoo tetap dihitung di atas harga manual? Perlu approval kalau harga diubah? | Opsional, ≥ 0, promo tetap jalan, tanpa approval tambahan (SO tetap lewat tier validation yang ada) | ⏳ |
| ✅ | 1 | Field harga di mobile | **Diputuskan 09-11-2026: boleh disediakan** (opsional) | ✅ |
## Urutan Kerja & Deploy
| Tahap | Isi | Repo | Syarat mulai |
|---|---|---|---|
| 1 | Poin 5: `input_method` + normalisasi | api · cms → kabari mobile | P7, P8 |
| 2 | Poin 3: `scanned_by` + filter + summary | api · cms → kabari mobile | [cek] relasi staff |
| 3 | Poin 2: split bill per program | odoo (`mito_base` naik versi + migration) → cms | P2, P3, P4 |
| 4 | Poin 4: export/import | cms / odoo | P5 |
| 5 | Poin 1: SO via outbox CMS | api · cms · odoo | P1 + pemetaan alur SO sekarang |
Aturan deploy (sama seperti integrasi sebelumnya):
- **Odoo dulu, baru CMS** untuk poin 2 dan 1. CMS yang naik duluan hanya akan `RETRY` sampai Odoo siap.
- Odoo: upgrade di **kedua server production** (share 1 RDS, lihat insiden multi-server), `-u mito_base --stop-after-init`,
backup `pg_dump` dulu. Ikuti playbook di `Rilis & Deploy/`.
- Perubahan kontrak API dikabari ke tim mobile **sebelum** deploy. Semua field baru bersifat **opsional**, jadi
aplikasi lama tidak rusak.