Doc_chelvyn/Mito/Sfa/Fitur/SFA — Plan Revisi 09-11-202...

43 KiB
Raw Blame History

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
sfa
reward
imei
vendor-bill
sales-order
plan
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 Kecil 🛠️ P5 terjawab 11-11-2026: Export/Import Reward Program CMS. Import sudah upsert; bug export diperbaiki (belum commit)
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_odoo tidak 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 dapat 202.
  • 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 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 <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_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).
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_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 ✅ 11-11-2026: staff melihat nominal IMEI miliknya saja, dealer dirinya + staff.
  • 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).
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/>(staff: nominal milik sendiri · 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) — sesuai K5 (11-11-2026): staff boleh lihat nominal miliknya saja.


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

[!success] P5 terjawab 11-11-2026 — Export/Import Reward Program di CMS Import sudah bisa update (upsert): program by program_code, baris produk by mapping_id (kosong = baris baru). Yang membuat user mengira "import hanya bisa tambah data": Export error untuk semua user sejak Area-Based Visibility (377b146, ter-deploy dev 03-11-2026): AreaAccess::scopeMappings(): Argument #1 ($query) must be of type Builder, HasMany given — closure eager-load with(['productMappings' => fn ($q) => ...]) di RewardProgramExcelService::export() menerima Relation, bukan Builder. Tanpa file Export, user tidak pernah dapat mapping_id untuk update. Fix: scopeMappings(Builder|Relation $query). Uji lokal: tanpa fix → error yang sama persis; dengan fix → export 13 baris, ubah reward_amount mapping #47 10.000 → 11.111, import balik → programs_updated 1, mappings_updated 13, mappings_created 0, jumlah baris tetap 13 (transaksi di-rollback).

Tambahan 11-11-2026 — centang "Untuk update data" di Export (gaya Odoo import-compatible export), di tombol Export header & "Export terpilih". Dicentang → ikut kolom mapping_id (bisa diedit lalu Import balik). Tidak dicentang (default) → export biasa tanpa mapping_id, untuk dibaca / laporan; kalau di-Import ditolak dengan pesan "Pakai file Export dengan centang Untuk update data". Uji lokal: biasa 14 kolom, update 15 kolom, import file biasa ditolak (0 tersimpan), import file update → 13 updated, 0 created.

Pilihan awal sebelum P5 terjawab (arsip):

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

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
P15 1 "Hapus" dari mobile = Cancel atau hapus permanen? 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? Reward Program CMS; mapping_id kosong = baris baru ✅ 11-11-2026
P6 3 Dealer perlu lihat nominal reward per IMEI staff? (terkait K5) Dealer ya, staff ikut K5 ✅ 11-11-2026: dealer lihat nominal dirinya + semua staff; staff hanya miliknya
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 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.