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

20 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 Plan — belum ada kode · menunggu jawaban Keputusan P1–P9 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 ⬜ Menunggu keputusan arsitektur (P1)
2 Vendor Bill hasil claim dipisah per Reward (bukan 1 bill per claim) cms · odoo Sedang ⬜ Membalik keputusan K1 — perlu konfirmasi (P2, P3)
3 API history scan IMEI: dealer bisa filter per staff, rekap IMEI yang di-scan staffnya (mobile) api · mobile Kecil–sedang ⬜ Siap dikerjakan setelah [cek] relasi staff
4 Export untuk edit / update (by ID atau External ID) cms atau odoo Sedang ⬜ Objek & sistem belum jelas (P5)
5 IMEI bisa diketik manual (free text) saat scan mobile · api Kecil ⬜ Siap dikerjakan

Usulan urutan: 5 + 3 dulu (kecil, langsung kerasa di mobile) → 2 (uang/akuntansi, scope jelas setelah P2/P3) → 4 → 1 (paling besar, butuh keputusan dulu).


1. Sales Order: lewat CMS atau Mobile langsung ke Odoo

Konteks: MoM 22-10-2026 (Fix sfa aftrer meet with mito) menyebut "Salesman hanya menginput Product dan Quantity". Direvisi 09-11-2026: field harga boleh disediakan di mobile (opsional, lihat desain di bawah). Diskon, promo, dan pajak tetap dihitung Odoo. Alur SO yang jalan sekarang di sfa-api / CMS belum dipetakan [cek]. Odoo sudah punya endpoint sale order di mito_base (controllers/api/, lihat temuan #3 di SFA — Reward Claim ke Odoo (Draft Vendor Bill)#9. Temuan Selama Pengujian) [cek isi & pemakainya].

Perbandingan

A. Mobile → CMS/API → Odoo (rekomendasi) B. Mobile → Odoo langsung
Kredensial API key Odoo tetap di server API key Odoo harus ada di aplikasi mobile, bisa dibongkar dari APK
Retry / offline Outbox di CMS (pola sama dengan claim reward: QUEUED → SENDING → SUCCESS / RETRY / PERMANENT_ERROR) Mobile urus retry sendiri, rawan SO dobel
Beban Odoo Bisa di-batch & dibatasi; penting karena Odoo masih single-process Setiap tap mobile = 1 request ke Odoo
Visibilitas admin SO gagal terlihat di CMS + tombol Kirim Ulang ke Odoo Tidak ada tempat memantau
Ubah alur Deploy server saja Rilis ulang aplikasi ke store
Latensi +1 hop (±1 menit kalau lewat worker, atau sinkron kalau perlu nomor SO langsung) Langsung

Desain usulan (opsi A)

  • Mobile kirim {request_id, customer, lines: [{product_code, qty, price_unit?}]} ke sfa-api.
  • Harga boleh diinput dari mobile (revisi 09-11-2026), menggantikan catatan MoM 22-10 "salesman hanya input Product dan Quantity". price_unit opsional:
    • Diisi → Odoo pakai harga itu sebagai price_unit line SO.
    • Kosong → Odoo hitung dari pricelist (perilaku standar).
    • Mobile tampilkan harga default dari master product / pricelist sebagai nilai awal, salesman boleh ubah.
  • Hati-hati: helper get_float di mito_base/controllers/api/core.py menganggap 0 = kosong. Kalau salesman isi harga 0, harga akan jatuh ke pricelist tanpa pesan. Endpoint SO harus parsing price_unit sendiri (pola sama dengan amount di endpoint reward-bills): null = pakai pricelist, 0 = ditolak atau diterima sesuai keputusan P9.
  • Interaksi dengan promo / diskon Odoo: harga manual = harga dasar, promo tetap dihitung di atasnya [konfirmasi P9].
  • CMS simpan SO lokal + status integrasi, worker kirim ke Odoo (POST /api/v1/sale-orders [cek: endpoint yang ada / baru]).
  • Odoo: idempotency key snk_sfa_order_ref di sale.order + unique (pola sama dengan snk_reward_claim_ref). Harga & promo dihitung Odoo (pricelist + promotion yang sudah ada).
  • Respons balik: nomor SO, total, status. Disimpan di CMS, ditampilkan di mobile.
  • Volume 500–1.000 SO/hari: pembuatan SO di Odoo pertimbangkan snk_queue_job kalau > 2 detik per SO.
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 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 (masih terbuka).
  • Index MySQL: (customer_user_id, created_at) dan (scanned_by_user_id, created_at) di tabel line [cek nama kolom].
  • Wajib pagination (limit maks 100).
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 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.


Keputusan yang Dibutuhkan

# Poin Pertanyaan Usulan Status
P1 1 SO lewat CMS/API atau Mobile langsung ke Odoo? Masalah apa di alur sekarang yang memicu usulan ini? Lewat CMS/API (opsi A) ⏳
P2 2 "Reward" = Reward Program? Bill dipisah per program (bukan per Jobsheet)? Ya, per program ⏳
P3 2 Siapa yang memutuskan K1 dibalik + tanggal? Claim lama yang sudah 1 bill: dibiarkan? Dibiarkan, berlaku untuk claim baru ⏳
P4 2 Saldo program tanpa Jobsheet: tetap jadi bill sendiri? Ya, 1 bill per program, Jobsheet No. kosong ⏳
P5 4 Export untuk objek apa, di CMS atau Odoo? id kosong boleh create? — ⏳
P6 3 Dealer perlu lihat nominal reward per IMEI staff? (terkait K5) Dealer ya, staff ikut K5 ⏳
P7 5 Input manual dibatasi? (role tertentu / jumlah per hari) Tidak dibatasi, cukup ditandai MANUAL ⏳
P8 5 Format IMEI di master selalu 15 digit? — [cek data] ⏳
P9 1 Harga dari mobile: boleh 0 / di bawah harga pricelist? Promo Odoo tetap dihitung di atas harga manual? Perlu approval kalau harga diubah? Opsional, ≥ 0, promo tetap jalan, tanpa approval tambahan (SO tetap lewat tier validation yang ada) ⏳
✅ 1 Field harga di mobile Diputuskan 09-11-2026: boleh disediakan (opsional) ✅

Urutan Kerja & Deploy

Tahap Isi Repo Syarat mulai
1 Poin 5: input_method + normalisasi api · cms → kabari mobile P7, P8
2 Poin 3: scanned_by + filter + summary api · cms → kabari mobile [cek] relasi staff
3 Poin 2: split bill per program odoo (mito_base naik versi + migration) → cms P2, P3, P4
4 Poin 4: export/import cms / odoo P5
5 Poin 1: SO via outbox CMS api · cms · odoo P1 + pemetaan alur SO sekarang

Aturan deploy (sama seperti integrasi sebelumnya):

  • Odoo dulu, baru CMS untuk poin 2 dan 1. CMS yang naik duluan hanya akan RETRY sampai Odoo siap.
  • Odoo: upgrade di kedua server production (share 1 RDS, lihat insiden multi-server), -u mito_base --stop-after-init, backup pg_dump dulu. Ikuti playbook di Rilis & Deploy/.
  • Perubahan kontrak API dikabari ke tim mobile sebelum deploy. Semua field baru bersifat opsional, jadi aplikasi lama tidak rusak.