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