20 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 | Plan — belum ada kode · menunggu jawaban Keputusan P1–P9 | 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 | ⬜ 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?}]}kesfa-api. - Harga boleh diinput dari mobile (revisi 09-11-2026), menggantikan catatan MoM 22-10 "salesman hanya input
Product dan Quantity".
price_unitopsional:- Diisi → Odoo pakai harga itu sebagai
price_unitline SO. - Kosong → Odoo hitung dari pricelist (perilaku standar).
- Mobile tampilkan harga default dari master product / pricelist sebagai nilai awal, salesman boleh ubah.
- Diisi → Odoo pakai harga itu sebagai
- Hati-hati: helper
get_floatdimito_base/controllers/api/core.pymenganggap0= kosong. Kalau salesman isi harga 0, harga akan jatuh ke pricelist tanpa pesan. Endpoint SO harus parsingprice_unitsendiri (pola sama denganamountdi 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_refdisale.order+unique(pola sama dengansnk_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_jobkalau > 2 detik per SO.
flowchart TD
A["SFA Mobile: salesman input<br/>customer + product + qty + harga (opsional)"] --> B["sfa-api: validasi<br/>request_id, customer aktif, product aktif, harga ≥ 0"]
B -- "gagal" --> B1["400 / 422 ke mobile"]
B -- "ok" --> C["CMS: simpan SO lokal<br/>integration QUEUED"]
C --> D["Worker CMS → POST Odoo sale order"]
D --> E{"snk_sfa_order_ref<br/>sudah ada?"}
E -- "ya" --> E1["200 · SO lama dikembalikan"]
E -- "tidak" --> F0{"price_unit<br/>dikirim?"}
F0 -- "ya" --> F1["pakai harga dari mobile"]
F0 -- "tidak" --> F2["harga dari pricelist"]
F1 & F2 --> F["Odoo hitung promo / pajak<br/>create sale.order (draft / quotation)"]
F --> S["CMS: SUCCESS<br/>simpan nomor SO + total"]
E1 --> S
D -- "422 data salah" --> P["PERMANENT_ERROR<br/>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 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
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.
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
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.