41 KiB
| judul | proyek | terkait | kategori | status | tipe | tags | diperbarui | ||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| SFA — Plan Revisi 09-11-2026 (SO, Vendor Bill per Reward, History Scan Staff, Export, IMEI Manual) | SFA API · SFA CMS · mito_odoo · SFA Mobile | Mito · Odoo 18 | Fitur | Poin 3 & 5 selesai di kode (belum commit) · P1 diputuskan 10-11-2026 · menunggu P2–P13 | dokumen-internal |
|
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 · Keputusan yang Dibutuhkan · alur (Mermaid) di tiap poin |
| Developer / Senior | Desain teknis per poin · Urutan Kerja & Deploy |
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 | ✅ P1 diputuskan 10-11-2026: mobile → Odoo langsung, CMS hanya riwayat · ⬜ menunggu P10–P13 |
| 2 | Vendor Bill hasil claim dipisah per Reward (bukan 1 bill per claim) | cms | Sedang | 🛠️ CMS selesai 10-11-2026 tanpa ubah Odoo (belum commit) — lihat Hasil A |
| 3 | API history scan IMEI: dealer bisa filter per staff, rekap IMEI yang di-scan staffnya (mobile) | api · mobile | Kecil–sedang | 🛠️ API + index CMS selesai 10-11-2026 (belum commit), mobile belum — lihat Hasil Poin 3 |
| 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 | 🛠️ API + CMS selesai 10-11-2026 (belum commit), mobile belum — lihat Hasil Poin 5 |
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).
Rencana Aman — Tanpa Ubah Odoo (10-11-2026)
[!important] Prinsip
mito_odootidak diubah kecuali diputuskan sendiri oleh Chelvyn. Semua yang bisa dikerjakan di CMS / sfa-api memakai endpoint Odoo yang sudah ada. Belum ada kode untuk bagian ini — dokumen ini untuk direview dulu.
| Poin | Bisa tanpa ubah Odoo? | Cara |
|---|---|---|
| 2 · Vendor bill per program | ✅ Ya | CMS memanggil POST /api/v1/reward-bills sekali per program dengan Claim ID berakhiran program |
| 1 · Buat SO | ✅ Ya | sfa-api memanggil POST /api/v1/sale-orders yang sudah ada |
| 1 · Edit SO | ⚠️ Pilihan | a) API bawaan Odoo (XML-RPC / JSON-RPC, modul tidak diubah) · b) endpoint baru di mito_base — diputuskan Chelvyn |
A. Vendor Bill per Program (poin 2) — CMS saja
Cara kerja: endpoint Odoo menolak 2 bill dengan Claim ID yang sama, jadi CMS mengirim Claim ID berbeda per
program: RCL261110000001-P3 (P + id program). Satu claim dengan 3 program = 3 panggilan = 3 Draft Vendor Bill.
Pengaman dobel di Odoo tetap jalan per program.
flowchart TD
A["Claim RCL261110000001<br/>Rp 500.000 (saldo lock)"] --> B["CMS: hitung per program dari ledger<br/>EARN sejak CLAIM_DEBIT sebelumnya"]
B --> C{"Σ per program<br/>= nominal claim?"}
C -- "tidak" --> C1["PERMANENT_ERROR<br/>split_mismatch"]
C -- "ya" --> D["Simpan baris reward_claim_bill per program<br/>P1 200rb · P3 150rb · P7 150rb"]
D --> E["Worker: untuk tiap program yang belum SUCCESS<br/>POST /reward-bills claim_id = RCL…-P{id}"]
E --> F{"Respons Odoo"}
F -- "201 / 200" --> G["baris program SUCCESS<br/>simpan odoo_bill_id"]
F -- "422" --> H["claim PERMANENT_ERROR<br/>admin perbaiki → Kirim Ulang"]
F -- "timeout / 5xx" --> I["claim RETRY<br/>program yang sudah SUCCESS dilewati"]
I --> E
G --> J{"Semua program<br/>SUCCESS?"}
J -- "ya" --> K["claim SUCCESS · DRAFT_CREATED"]
J -- "belum" --> E
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 B,C,D,E,F,G,J todo
class K ok
class C1,H err
class I warn
| Hal | Rencana |
|---|---|
| Nominal per program | Jumlah ledger EARN per reward_program_id di jendela claim (sama dengan logika jobsheetNo() yang sudah ada). Ledger tidak pernah diubah, jadi hasilnya selalu sama walau dihitung ulang saat retry. Saat ini hanya ada EARN & CLAIM_DEBIT (REVERSAL / ADJUSTMENT belum pernah dibuat kode) |
| Pengaman | Σ per program harus = nominal claim, kalau tidak → PERMANENT_ERROR split_mismatch, tidak dikirim |
| Claim ID per bill | {claim_code}-P{program_id}. Pakai id (tidak pernah berubah), bukan kode program (bisa diedit). Nama program masuk label line bill lewat description |
| Jobsheet No. | Per bill = Jobsheet program itu saja (tidak lagi dipisah koma). Program tanpa Jobsheet → kosong (P4) |
| Tabel baru CMS | reward_claim_bill: reward_claim_id, reward_program_id, odoo_claim_ref, amount, jobsheet_no, odoo_bill_id, odoo_bill_ref, status. Unique (reward_claim_id, reward_program_id) |
| Gagal di tengah | Program yang sudah SUCCESS dilewati saat retry; Odoo juga mengembalikan bill lama kalau Claim ID-nya sudah ada → tidak mungkin dobel |
| Claim lama (P3) | Claim yang sudah SUCCESS (1 bill gabungan) tidak disentuh. Claim yang belum terkirim saat deploy ikut aturan baru |
| Tampilan | Claim History CMS: daftar bill per program. Mobile GET /reward/claims: tambah bills[] (opsional, kontrak lama tetap) |
| Keterbatasan | 3 bill dibuat lewat 3 panggilan terpisah, jadi sesaat bisa ada 1–2 bill dulu sebelum lengkap. Status claim baru SUCCESS setelah semua lengkap |
Hasil A (10-11-2026) — CMS saja, Odoo tidak diubah, belum commit
| File (sfa-cms) | Perubahan |
|---|---|
migrations/2026_11_10_000003_create_reward_claim_bill_table.php |
Tabel reward_claim_bill (unique odoo_claim_ref & (reward_claim_id, reward_program_id)), idempotent (hasTable) |
app/Models/RewardClaimBill.php (baru) · RewardClaim.php |
Model + relasi bills() |
app/Services/RewardClaimOdooService.php |
prepareBills() + programAmounts() (menggantikan jobsheetNo() yang menggabung Jobsheet dengan koma). send() kirim 1x per program yang belum punya bill. split_mismatch bila Σ ≠ nominal. 1 program → odoo_bill_id / odoo_bill_ref claim terisi seperti dulu; > 1 → odoo_bill_ref = "N Vendor Bill" |
RewardClaimResource.php |
Section Vendor Bill per Reward Program di detail claim (program, Jobsheet, nominal, Claim ID di Odoo, bill). Notifikasi Kirim Ulang pakai odoo_bill_ref |
PushRewardClaimsToOdoo.php |
Output worker menampilkan semua id bill claim |
Uji lokal (Odoo palsu, data dibuat dalam transaksi lalu di-rollback — sisa 0 claim, 0 bill):
| # | Skenario | Hasil |
|---|---|---|
| 1 | Claim Rp 500.000: program A (2 IMEI, 200rb, JS/A/001), B (150rb, JS/B/002), C (150rb, tanpa Jobsheet) | ✅ 3 POST RCL…-P89/-P90/-P91, Jobsheet per bill, C tanpa Jobsheet tetap 1 bill (P4), claim SUCCESS, ref "3 Vendor Bill" |
| 2 | Program B timeout | ✅ A tersimpan, claim RETRY; kirim ulang → hanya B yang dikirim, claim SUCCESS |
| 3 | 422 vendor_not_found |
✅ PERMANENT_ERROR; setelah diperbaiki → SUCCESS, 1 program → odoo_bill_id & ref terisi seperti format lama |
| 4 | Nominal claim ≠ Σ ledger per program | ✅ PERMANENT_ERROR split_mismatch, Odoo tidak dipanggil |
| 5 | Kirim ulang claim yang sudah SUCCESS |
✅ ditolak, 0 POST |
Belum diuji: tampilan section di browser, dan kirim ke Odoo asli (dev).
Catatan deploy: claim yang sebelum deploy sedang RETRY / SENDING karena timeout bisa saja sudah punya bill di
Odoo dengan Claim ID lama (tanpa akhiran) → setelah deploy dikirim ulang dengan akhiran → bill dobel. Sebelum deploy
cek: SELECT claim_code, integration_status, error_code FROM reward_claim WHERE integration_status IN ('RETRY','SENDING');
Kalau ada, cek Bill Reference-nya di Odoo dulu. PERMANENT_ERROR karena 422 aman (Odoo tidak membuat bill).
B. Buat SO dari Mobile (poin 1) — sfa-api + CMS saja
| Hal | Rencana |
|---|---|
| Alur | Mobile → POST /transaction/sales-order (sfa-api) → validasi → catat log (request_id unik) → panggil POST /api/v1/sale-orders Odoo langsung → nomor SO balik ke mobile |
| Mapping | Customer → partner_id = customer.cust_code (sudah id Odoo dari sync). Product → [cek] product_id CMS = id product.product Odoo atau product.template? Endpoint butuh product.product |
| Kirim ulang dari mobile | request_id sama → sfa-api balikin hasil yang sudah tercatat, tidak memanggil Odoo lagi |
| Odoo mati / koneksi ditolak | Pasti belum sampai Odoo → RETRY otomatis lewat worker CMS, mobile dapat 202 |
| Timeout (tidak tahu SO sudah dibuat atau belum) | Tidak di-retry otomatis → status NEEDS_CHECK. Admin cek di Odoo, lalu klik Tandai sudah ada (isi nomor SO) atau Kirim Ulang. Ini satu-satunya celah dobel tanpa ubah Odoo; dengan cara ini SO dobel tidak terjadi otomatis |
| Harga | Harga kosong → pricelist. Harga 0 belum bisa (endpoint Odoo menganggap 0 = kosong). Kalau P9 memutuskan 0 harus boleh, baru perlu perubahan Odoo |
| Salesperson | Default customer (P11), endpoint sudah begitu |
| CMS | Menu Sales Order: riwayat dari log + data lama (read-only), tombol Kirim Ulang / Tandai sudah ada untuk RETRY / NEEDS_CHECK |
Yang masih butuh keputusan sebelum coding
| # | Hal |
|---|---|
| P3, P4 | Pakai usulan (claim lama dibiarkan, program tanpa Jobsheet tetap 1 bill)? |
| P9 | Harga 0 boleh? Kalau tidak → sfa-api menolak, Odoo tidak perlu diubah |
| P17 | Edit SO: pakai a (API bawaan Odoo) atau b (endpoint baru, ubah Odoo)? Plus: SO yang sudah diberi promo oleh admin boleh diedit dari mobile? (nilai promo bisa basi) |
| [cek] | Product id CMS = product.product Odoo? (dicek dari kode sync, tanpa ubah apa pun) |
1. Sales Order: Mobile → Odoo langsung, CMS hanya riwayat
[!success] Keputusan P1 (10-11-2026) SO tidak lagi diedit / diproses di CMS. Order salesman dari mobile langsung jadi SO di Odoo, CMS cukup menampilkan riwayat (read-only). Alasan dari Mito: fitur SO di CMS sekarang terlalu banyak, padahal yang dibutuhkan cuma riwayat.
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). Diskon bertingkat, promo, pajak tetap dihitung Odoo.
Kondisi sekarang (dicek 10-11-2026)
| Sistem | Yang ada |
|---|---|
CMS (SalesTableResource + menu terkait) |
Mini-ERP SO sendiri: Create / Edit / Delete / Confirm SO / Create Packing / Cancel SO, menu Sales Packing Journal, Sales Invoice Journal, Sales Tracking, Invent Trans / On Hand. SO tersimpan di tabel CMS sales_table + line, tidak masuk Odoo [cek: ada jalur ke Odoo?] |
| sfa-api (mobile) | GET/POST /transaction/sales-order, /sales-order/update, /sales-order/delete, /sales-order/delete-lines, /sales-order-topten, /invoice + download PDF → semua ke tabel CMS |
Odoo mito_base |
Sudah ada POST /api/v1/sale-orders (+ GET list & detail): SO draft, OU / area / sub-area / salesperson / warehouse / diskon bertingkat diisi otomatis dari master customer (replay onchange form SO), price_unit opsional (kosong = pricelist), tier validation jalan normal |
Celah endpoint Odoo yang harus ditutup sebelum dipakai mobile:
| # | Celah | Akibat | Perbaikan |
|---|---|---|---|
| 1 | Tidak ada idempotency | Sinyal salesman putus → kirim ulang → SO dobel di Odoo | Field sale.order.snk_sfa_order_ref (Char, copy=False, readonly) + unique, diisi request_id mobile. Retry → SO lama dikembalikan 200. Paralel → 409 (pola sama dengan snk_reward_claim_ref) |
| 2 | get_float menganggap 0 = kosong |
Harga 0 diam-diam diganti harga pricelist | Parse price_unit sendiri: null = pricelist, angka ≥ 0 dipakai (P9) |
| 3 | Salesperson diambil dari master customer | — | Bukan celah — memang begitu yang diinginkan (P11, Oliver 10-11-2026). Perubahan salesperson dilakukan manual oleh admin / kacab di Odoo |
| 4 | get_float qty sama |
qty 0 → pesan "required", bukan "> 0" |
Ikut diperbaiki bersama #2 |
Desain baru
sequenceDiagram
participant M as SFA Mobile
participant A as sfa-api
participant DB as DB CMS (sfa_order_log)
participant O as Odoo POST /api/v1/sale-orders
M->>A: POST /transaction/sales-order<br/>{request_id, customer, lines[product, qty, price_unit?]}
A->>A: validasi (customer & product aktif, qty > 0, harga ≥ 0)
A->>DB: simpan log request_id · SENDING
A->>O: kirim (sinkron, timeout ±20 dtk)<br/>sfa_order_ref = request_id
alt sukses (201 baru / 200 sudah ada)
O-->>A: nomor SO, total, state draft
A->>DB: SUCCESS + odoo_order_id + nomor SO
A-->>M: 201 · nomor SO & total
else 422 data salah (customer/product tidak valid)
O-->>A: error.code
A->>DB: FAILED + pesan
A-->>M: 422 · pesan → salesman perbaiki
else timeout / Odoo down
A->>DB: RETRY
A-->>M: 202 · "order diterima, sedang dikirim ke Odoo"
Note over DB,O: worker CMS kirim ulang tiap menit<br/>request_id sama → tidak dobel
end
Note over M,O: Confirm / delivery / invoice di Odoo. Edit dari mobile diteruskan ke Odoo (lihat di bawah). Hapus / batal SO hanya di Odoo. CMS hanya riwayat
Prinsip:
- Odoo = satu-satunya tempat SO. CMS tidak bisa membuat / mengubah SO. Mobile bisa buat dan edit (tidak bisa hapus), tapi semuanya langsung ke Odoo (tidak ada salinan yang diubah sendiri).
- Tetap lewat sfa-api, bukan mobile → Odoo langsung secara teknis: API key Odoo tidak boleh ada di APK. Bagi user tetap "langsung": tidak ada langkah di CMS, nomor SO Odoo langsung balik ke mobile.
- Sinkron dulu, fallback antre: normalnya salesman langsung dapat nomor SO. Kalau Odoo lambat / down, order tidak
hilang: tersimpan
RETRY, dikirim worker (pola sama dengan claim reward), mobile dapat202. - Riwayat di CMS & mobile: daftar dari log lokal (cepat, bisa filter area / salesman), status terkini
(draft / confirmed / dikirim / ditagih) dibaca realtime dari Odoo
GET /api/v1/sale-orders/<id>saat detail dibuka — tanpa cron sync (sama dengan keputusan Jobsheet). - Volume 500–1.000 SO/hari: 1 request = 1 SO, ringan. Kalau create SO di Odoo > 2 detik, pindah ke
snk_queue_job.
Edit SO dari Mobile (tanpa hapus)
Diputuskan 10-11-2026 (P12): mobile bisa edit SO, perubahan langsung ke Odoo. Mobile tidak bisa menghapus / membatalkan SO — pembatalan hanya oleh admin / kacab di Odoo. Odoo tetap satu-satunya sumber data; mobile tidak pernah mengubah salinan lokal saja.
flowchart TD
A["Mobile: edit SO<br/>(header / tambah / ubah / buang line)"] --> B{"SO sudah punya<br/>nomor Odoo?"}
B -- "belum (masih RETRY)" --> B1["409 SO_NOT_SYNCED<br/>tunggu terkirim dulu"]
B -- "SO lama, hanya di CMS" --> B2["409 SO_READ_ONLY<br/>(P16)"]
B -- "ya" --> C["sfa-api → Odoo<br/>cek state + validation_status + write_date"]
C --> D{"SO masih Draft<br/>& belum diajukan approval?"}
D -- "tidak" --> D1["409 SO_LOCKED<br/>ubah lewat Odoo (admin / kacab)"]
D -- "ya" --> E{"write_date sama dengan<br/>yang dilihat mobile?"}
E -- "tidak, sudah diubah di Odoo" --> E1["409 SO_CHANGED<br/>+ data terbaru → mobile refresh"]
E -- "ya" --> G["PUT /api/v1/sale-orders/:id<br/>ganti header & semua lines (min. 1 line)"]
G --> S["200 · SO terbaru (total dihitung ulang Odoo)"]
C -- "Odoo down / timeout" --> R["503 ODOO_UNAVAILABLE<br/>mobile coba lagi"]
X["Mobile: hapus SO"] --> X1["403 SO_DELETE_NOT_ALLOWED<br/>batal SO hanya di Odoo"]
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,G,X todo
class S ok
class B1,B2,D1,E1,X1 err
class R warn
Aturan:
| Hal | Aturan | Alasan |
|---|---|---|
| Kapan boleh diedit (P14) | state = draft dan validation_status = no |
Setelah diajukan tier validation, Odoo sendiri sudah mengunci edit (termasuk ditolak) |
| Edit = ganti penuh | PUT mengirim header + semua lines (bukan per baris). Odoo hapus lines lama → buat ulang → harga, diskon bertingkat, promo, pajak dihitung ulang. Minimal 1 line |
Satu aturan sederhana, aman di-retry (hasil sama), tidak ada line yatim. Buang semua line = sama dengan hapus SO → ditolak |
| Bentrok dengan edit di Odoo | Mobile kirim write_date yang dia lihat. Beda dengan Odoo → 409 SO_CHANGED + data terbaru |
Admin bisa mengubah SO di Odoo pada saat bersamaan; tanpa cek ini edit mobile menimpa perubahan admin |
| Hapus SO (P12) | Tidak bisa dari mobile → 403 SO_DELETE_NOT_ALLOWED. Batal SO dilakukan admin / kacab di Odoo (Cancel) |
Keputusan 10-11-2026 |
| SO belum terkirim ke Odoo | 409 SO_NOT_SYNCED |
Hindari edit menumpuk di antrean; biasanya hanya beberapa detik / menit |
| SO lama (P16) | Read-only | Tidak punya pasangan di Odoo |
| Odoo down | Edit sinkron, tidak diantre → 503, mobile coba lagi |
Edit yang tertunda lalu menimpa perubahan lain lebih berbahaya daripada gagal jelas |
Tambahan di Odoo mito_base: PUT /api/v1/sale-orders/<id> (dengan cek di atas), tanpa endpoint DELETE / cancel.
Respons GET sudah punya state, validation_status, write_date. Di sfa-api: update & delete-lines diarahkan
ke Odoo (delete-lines = edit dengan lines tersisa, minimal 1); POST /transaction/sales-order/delete →
403 SO_DELETE_NOT_ALLOWED.
Perubahan per repo
| Repo | Perubahan |
|---|---|
mito_odoo mito_base |
snk_sfa_order_ref + unique (naik versi, tanpa migration destruktif); endpoint terima sfa_order_ref; parse price_unit / qty tanpa get_float; respons created true/false; test TransactionCase |
| sfa-api | POST /transaction/sales-order diganti: validasi → log → kirim Odoo → nomor SO. update / delete-lines diteruskan ke Odoo dengan aturan kunci (P12, P14, P16); delete → 403 SO_DELETE_NOT_ALLOWED. GET list dari log, detail + status dari Odoo |
| sfa-cms | Tabel sfa_order_log. Menu Sales Order jadi read-only (list + detail + status Odoo + tombol Kirim Ulang ke Odoo untuk RETRY / FAILED). Action Create / Edit / Delete / Confirm / Create Packing / Cancel dihilangkan. Grup Transaction Sales hanya |
| menyisakan Sales Order; menu Sales Packing Journal disembunyikan (kode & data tidak dihapus). Menu lain tidak | |
diubah (P10). Worker odoo:push-sales-orders |
|
| mobile | Form order: customer, product, qty, harga opsional. Edit SO tetap ada, tombol hapus SO dihilangkan; kirim write_date saat edit, tangani 409 SO_LOCKED / SO_CHANGED / SO_NOT_SYNCED / SO_READ_ONLY dan 503. Create: tangani 201 / 202 / 422. Riwayat dari GET |
2. Vendor Bill dipisah per Reward
[!note] Diganti 10-11-2026 Desain teknis di bawah (ubah constraint + migration
mito_base) tidak dipakai. Yang dipakai: Rencana Aman A — tanpa ubah Odoo.
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 (P2 dikonfirmasi 10-11-2026: per Reward Program)
- "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 punyaprogram_iddi 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 <Claim ID> |
Reward Claim <Claim ID> · <Program> + 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_refNULL) 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). Kolomreward_claim.odoo_bill_iddibiarkan 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 arrayrewards, simpan semuaidbill dari respons.- Filament Claim History: blok Integrasi Odoo tampilkan daftar bill per program.
- Mobile
GET /reward/claims: tambahbills[](opsional, tidak memecah kontrak lama).
flowchart TD
A["Claim full balance Rp 500.000<br/>(mobile / CMS)"] --> B["CMS: hitung saldo bersih per program<br/>dari ledger sejak claim terakhir"]
B --> C{"Σ per program<br/>= nominal claim?"}
C -- "tidak" --> C1["PERMANENT_ERROR<br/>split_mismatch"]
C -- "ya" --> D["Simpan snapshot reward_claim_bill<br/>Program A 200rb · B 150rb · C 150rb"]
D --> E["Worker → POST /api/v1/reward-bills<br/>claim_id + rewards[3]"]
E --> F{"Odoo: claim_id sudah<br/>punya bill?"}
F -- "ya" --> F1["200 · created=false<br/>semua bill lama"]
F -- "tidak" --> G["Validasi vendor & product<br/>(422 sama seperti sekarang)"]
G -- "gagal" --> G1["422 → PERMANENT_ERROR"]
G -- "ok" --> H["1 transaksi: create 3 Draft Vendor Bill<br/>tiap bill: program + Jobsheet No. + amount"]
H -- "salah satu gagal" --> H1["rollback semua → 422 / RETRY"]
H -- "ok" --> S["201 · 3 bill<br/>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_iddiambil dari token, bukan dari parameter. Kalau dari parameter, dealer A bisa intip data dealer B.staff_idyang 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 (
limitmaks 100).
flowchart TD
A["Mobile: buka Riwayat Scan<br/>GET /reward/imei-submissions?staff_id=..."] --> B{"Role di token?"}
B -- "Staff Dealer" --> C["Paksa filter scanned_by = user sendiri<br/>staff_id diabaikan"]
B -- "Dealer" --> D{"staff_id dikirim?"}
D -- "tidak" --> E["Semua line milik dealer"]
D -- "ya" --> F{"staff milik<br/>dealer ini?"}
F -- "tidak" --> F1["403 STAFF_NOT_OWNED"]
F -- "ya" --> G["Line milik dealer<br/>AND scanned_by = staff_id"]
B -- "lainnya" --> B1["403"]
C & E & G --> H["200 · list + pagination<br/>(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
Hasil Poin 3 (10-11-2026)
Beda dari desain awal: /reward/imei-submissions tidak diubah (bentuknya per pengajuan, dipakai mobile
sekarang). Dibuat 2 endpoint baru yang berbentuk per IMEI. Kolom "siapa yang scan" ternyata sudah ada
(reward_imei_submission_line.submitted_by, terisi sejak Staff Dealer), jadi tidak perlu kolom baru.
| Endpoint | Isi |
|---|---|
GET /reward/imei-scans?page&limit&staff_id&status&date_from&date_to |
List per IMEI, terbaru di atas. Item = lines[] lama + submission_code + scanned_by {user_id, name}. Dealer: semua IMEI di pengajuannya (scan dirinya, staff, input admin CMS), staff_id = staff miliknya / dirinya sendiri, staff dealer lain → 403 STAFF_NOT_OWNED. Staff: dipaksa hanya scan sendiri, staff_id diabaikan |
GET /reward/imei-scans/summary?date_from&date_to |
Rekap per orang: role DEALER / STAFF / CMS_ADMIN, total_scan, submitted, approved, rejected, approved_amount + totals. Semua staff dealer ikut walau belum pernah scan (angka 0) → dipakai juga untuk dropdown filter staff_id. Staff: hanya barisnya sendiri |
Tanggal = WIB, inklusif (date_from ≤ date_to, selain itu 400). Kolom TIMESTAMP + session +07:00 di CMS dan API,
jadi batas hari konsisten.
| Repo | File |
|---|---|
| sfa-api | serviceReward.js (getImeiScans, getImeiScanSummary, resolveScanScope, wibDayBounds), handler/reward/reward.js, validatorReward.js, routes/sfa.js, MrewardImeiSubmissionLine.js (relasi submitter → users), swagger/openapi.js |
| sfa-cms | Migration 2026_11_10_000002_add_submitted_by_index_to_reward_imei_submission_line_table — index (submitted_by, created_at), idempotent (Schema::hasIndex) |
Uji lokal (data staff sementara untuk dealer 445, dihapus lagi setelah uji): rekap dealer (dealer 8 IMEI + staff 1),
filter tanggal 19-10 → 3 IMEI, rekap staff hanya dirinya, list dealer semua 9 / filter staff 1 / filter diri sendiri +
APPROVED + 16-10 → 5, staff mengirim staff_id dealer → tetap hanya miliknya, staff_id user lain → 403 STAFF_NOT_OWNED, dealer lain tidak melihat data 445. Validator: tanpa page, staff_id bukan angka, tanggal
terbalik, format tanggal salah → 400. Migration index dijalankan ulang → Nothing to migrate.
Info ke tim mobile: layar Riwayat Scan dealer → GET /reward/imei-scans/summary (kartu rekap + dropdown
staff), pilih staff → GET /reward/imei-scans?staff_id=…. Nominal per IMEI masih tampil juga untuk staff (sama
dengan perilaku /reward/imei-submissions sekarang) sampai K5 diputuskan.
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
idcocok → update.idtidak dikenal → ditolak (bukan dibuat baru).idkosong → 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).
flowchart TD
A{"Cara input"} -- "Scan kamera" --> B["IMEI dari barcode<br/>input_method = SCAN"]
A -- "Ketik manual" --> C["Input teks → trim, buang spasi"]
C --> C1{"Format valid?<br/>(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 /<br/>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:<br/>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.
Hasil Poin 5 (10-11-2026)
Dikerjakan dengan keputusan sementara: P7 = tidak dibatasi, cukup ditandai, P8 = tanpa cek panjang / Luhn,
karena contoh IMEI di master 11 digit (11220018494), bukan 15 digit.
| Repo | File | Perubahan |
|---|---|---|
| sfa-api | routes/validator/validatorReward.js |
Spasi di dalam IMEI dibuang (check & submit) sebelum validasi, jadi 1122 0018 494 = 11220018494; cek dobel jalan setelah spasi dibuang. Field opsional manual_imei_number (harus bagian dari imei_number, kalau tidak → 400) |
| sfa-api | routes/services/serviceReward.js · handler/reward/reward.js |
Line dari IMEI di manual_imei_number → input_method = MANUAL, sisanya SCAN. Respons lines[] ikut input_method |
| sfa-api | routes/helpers/enums/reward.js · models/MrewardImeiSubmissionLine.js |
RewardImeiInputMethodEnum + kolom model |
| sfa-api | swagger/openapi.js |
Dokumentasi manual_imei_number, input_method |
| sfa-cms | migrations/2026_11_10_000001_add_input_method_to_reward_imei_submission_line_table.php |
Kolom input_method VARCHAR(10) default SCAN, line lama source = CMS → MANUAL. Idempotent (hasColumn) |
| sfa-cms | RewardImeiSubmissionService.php |
Input admin CMS → MANUAL |
| sfa-cms | LinesRelationManager.php |
Kolom badge Input (Scan abu-abu / Ketik manual kuning) + filter Input di IMEI Registration |
Uji lokal: migration jalan + dijalankan ulang = Nothing to migrate; validator 6 skenario (kontrak lama tanpa
manual_imei_number tetap lolos, spasi dibuang, manual di luar list 400, dobel setelah buang spasi 400, IMEI isi spasi
saja 400); model menulis MANUAL / default SCAN (transaksi di-rollback). Belum: submit end-to-end, karena DB lokal
tidak punya IMEI yang lolos checkImei (program / mapping lokal sudah tidak aktif).
Deploy: CMS dulu (migration), baru API. Kalau API naik duluan, insert line gagal karena kolom belum ada.
Info ke tim mobile: tambah tombol Ketik Manual di layar scan → panggil GET /reward/imei/check yang sama →
masuk list dengan penanda lokal. Saat submit, kirim IMEI yang diketik juga di manual_imei_number. Tidak wajib:
aplikasi lama tanpa field ini tetap jalan (semua tercatat SCAN).
Keputusan yang Dibutuhkan
| # | Poin | Pertanyaan | Usulan | Status |
|---|---|---|---|---|
| P1 | 1 | SO lewat CMS/API atau Mobile langsung ke Odoo? | SO tidak diedit di CMS, langsung jadi SO Odoo, CMS cukup riwayat (fitur SO CMS terlalu banyak) | ✅ 10-11-2026 |
| P10 | 1 | Menu CMS mana yang disembunyikan? | Grup Transaction Sales hanya menyisakan Sales Order (read-only). Sales Packing Journal disembunyikan. Grup Inventory Transactions (Inventory Journal, Inventory Transaction History, Inventory On Hands) juga disembunyikan karena tidak dipakai. Tombol New Sales Order dihapus (canCreate() = false). Kode & data tidak dihapus |
✅ 10-11-2026 (CMS, belum commit) |
| P11 | 1 | Salesperson di SO Odoo = salesman yang input di mobile, atau salesman default customer (perilaku endpoint sekarang)? | Diputuskan Oliver 10-11-2026: pakai salesperson yang ada di master customer (perilaku endpoint sekarang, tanpa perubahan kode). Kalau perlu diganti, diubah manual oleh admin / kacab yang memproses SO di Odoo. Field tambahan "SFA Salesman" di SO tidak dibuat (tidak diminta); siapa yang input tetap tercatat di log SO CMS. Data pendukung (DB MITO_PRODUCTION_20082026): (1) 1.487 dari 1.561 SO 90 hari terakhir (95%) salesperson-nya memang = default customer; 67 SO (4%) beda orang. (2) Tidak ada kunci yang andal untuk mencocokkan salesman SFA → hr.employee: semua 39 salesperson punya identification_id = 00 (tidak unik), 4 kosong, hanya 10 punya user login; sync customer CMS mencocokkan pakai nama dan cuma 29/42 cocok. Kalau nanti kode employee Odoo dirapikan (unik, sama dengan empl_code CMS), bisa diganti jadi salesman yang input |
✅ 10-11-2026 |
| P12 | 1 | Mobile bisa edit / hapus SO? | Edit: bisa, perubahan ikut ke Odoo. Hapus: tidak boleh dari mobile (10-11-2026) — batal SO hanya oleh admin / kacab di Odoo. Aturan di Edit SO dari Mobile | ✅ 10-11-2026 |
| P14 | 1 | Kapan SO masih boleh diedit dari mobile? | Diputuskan 10-11-2026: selama SO masih Draft (Quotation). Catatan teknis: di Odoo SO yang sudah diajukan approval tetap berstatus Draft, tapi base_tier_validation sudah mengunci edit sejak ada review (menunggu, disetujui, maupun ditolak) — ValidationError "not allowed to write those fields under validation". Jadi aturan efektifnya: Draft dan belum diajukan approval (validation_status = no). Selain itu → 409 SO_LOCKED, ubah lewat Odoo. SO ditolak bisa diedit lagi setelah admin Cancel → Set to Draft di Odoo (review ikut terhapus). Tier validation tidak di-bypass |
✅ 10-11-2026 |
| 1 | Gugur — mobile tidak bisa hapus SO (P12) | ✅ 10-11-2026 | ||
| P16 | 1 | SO lama (sebelum go-live, hanya di tabel CMS, tidak ada di Odoo) boleh diedit? | Read-only (10-11-2026). SFA masih tahap dev, jadi SO lama di CMS = data dev / uji, cukup tampil sebagai riwayat | ✅ 10-11-2026 |
| P13 | 1 | Fitur Invoice di mobile (/invoice + download PDF) ikut ambil dari Odoo? |
Tahap berikutnya, di luar scope ini | ⏳ |
| P2 | 2 | "Reward" = Reward Program? Bill dipisah per program (bukan per Jobsheet)? | Ya, per Reward Program (10-11-2026). 1 claim = 1 Draft Vendor Bill per program asal saldo | ✅ 10-11-2026 |
| P3 | 2 | Claim lama yang sudah 1 bill? | Dibiarkan, aturan baru untuk claim yang dikirim setelah deploy (usulan, dijalankan 10-11-2026) | ✅ 10-11-2026 |
| P4 | 2 | Saldo program tanpa Jobsheet? | Tetap 1 bill sendiri, Jobsheet No. kosong (usulan, dijalankan 10-11-2026) | ✅ 10-11-2026 |
| 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? | Tidak. Data master lokal (10-11-2026): 465 × 11 digit, 114 × 12 digit, 13 × 9 digit, 3 × 10 digit, dan beberapa berhuruf (B311804680, B03000176740, S1180000922). Ini nomor seri produk, bukan IMEI HP → tanpa cek panjang / Luhn, keyboard input manual mobile harus alfanumerik. Ada 1 data aneh berisi spasi MTWM202675849800 JANGAN (tidak akan cocok setelah spasi dibuang — kemungkinan data uji) |
✅ dijawab dari data · cek production |
| 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 mobile → Odoo, CMS read-only | odoo (idempotency dulu) → api → cms → mobile | P10–P12 |
Aturan deploy (sama seperti integrasi sebelumnya):
- Odoo dulu, baru CMS untuk poin 2 dan 1. CMS yang naik duluan hanya akan
RETRYsampai Odoo siap. - Odoo: upgrade di kedua server production (share 1 RDS, lihat insiden multi-server),
-u mito_base --stop-after-init, backuppg_dumpdulu. Ikuti playbook diRilis & Deploy/. - Perubahan kontrak API dikabari ke tim mobile sebelum deploy. Semua field baru bersifat opsional, jadi aplikasi lama tidak rusak.