Doc_chelvyn/Mito/Sfa/FDD/SFA–CMS Reward Claim Integr...

252 lines
14 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

**Version:** 0.4
**Date:** 14 October 2026
**Status:** Draft untuk alignment flow dan requirement; metode integrasi API masih dalam pembahasan.
---
## 1. Tujuan
Dokumen ini menjelaskan flow integrasi ketika user melakukan Claim Reward melalui SFA/CMS, kemudian sistem membuat **Draft Vendor Bill** di Odoo 18.
Dokumen ini menggabungkan dua konfigurasi utama:
1. **CMS User ID pada master Vendor Odoo** untuk menentukan vendor yang menerima bill.
2. **Default Reward Product pada Accounting Settings** untuk menentukan produk default pada baris Vendor Bill.
Keputusan apakah integrasi menggunakan custom API/module atau External API Odoo masih terbuka. Keputusan tersebut tidak mengubah business flow yang dijelaskan di dokumen ini.
## 2. Scope
Termasuk:
- Lookup vendor Odoo berdasarkan CMS User ID.
- Default product untuk Vendor Bill Reward yang dikonfigurasi melalui Accounting Settings.
- Pembuatan Draft Vendor Bill setelah claim diterima CMS.
- Penyimpanan Claim ID, referensi bill Odoo, dan log request teknis.
- Validasi mapping dan pencegahan bill duplikat.
Belum ditetapkan dalam dokumen ini:
- Mekanisme teknis final untuk koneksi CMS–Odoo (custom API/module atau External API).
- Detail endpoint, authentication, payload final, dan mapping teknis seluruh field Odoo.
- Akun expense, pajak, jurnal, serta kebijakan accounting final; perlu dikonfirmasi Finance/Odoo team.
## 3. Master Data dan Konfigurasi Odoo
### 3.1 Field CMS User ID pada Vendor
Tambahkan satu field pada form master Vendor Odoo untuk menampung ID user dari CMS.
| Property | Requirement |
|---|---|
| Label | CMS User ID |
| Suggested technical name | `x_cms_user_id` |
| Model | `res.partner` |
| Field type | Char direkomendasikan; Integer dapat digunakan jika ID dipastikan selalu numerik tanpa leading zero |
| Pengisian | Manual oleh user/admin yang berwenang |
| Kegunaan | Key untuk mencari vendor penerima reward berdasarkan user yang melakukan claim di CMS |
| Validasi | CMS User ID tidak boleh terhubung ke lebih dari satu vendor penerima reward |
**Catatan desain:**
- Field harus tersedia pada master Vendor yang relevan.
- Integrasi menggunakan CMS User ID sebagai kunci lookup, bukan nama vendor, nama user, atau email.
- Gunakan hanya vendor yang sesuai dan aktif menurut aturan master data yang disepakati.
- Jika satu CMS User ID tidak ditemukan atau ditemukan pada lebih dari satu vendor, proses pembuatan bill dihentikan dan dicatat sebagai exception.
- Tidak boleh membuat vendor baru secara otomatis hanya karena mapping tidak ditemukan.
- Simpan snapshot vendor/partner yang terpilih pada data claim CMS agar perubahan mapping di kemudian hari tidak mengubah tujuan claim yang sudah tercatat.
### 3.2 Accounting Settings — Default Reward Product
Tambahkan satu parameter pada **Accounting → Configuration/Settings**, di bagian **Vendor Bills**, untuk menentukan produk default yang digunakan ketika Draft Vendor Bill dibuat dari Claim Reward.
| Property | Requirement |
|---|---|
| Section | Accounting Settings → Vendor Bills |
| Label yang disarankan | Default Reward Product |
| Suggested technical name | `reward_claim_product_id` (nama final mengikuti konvensi implementasi) |
| Field type | Many2one / dropdown relation |
| Related model | `product.product` |
| Pengisian | Dipilih dan disimpan oleh administrator Accounting |
| Fungsi | Menjadi produk default pada baris Vendor Bill yang dibuat dari Claim Reward |
| Nilai wajib | Harus dikonfigurasi sebelum integrasi digunakan di production |
**Behavior yang diharapkan:**
- Saat CMS mengirim claim yang valid, integrasi membaca konfigurasi Default Reward Product dari Odoo.
- Produk yang terpilih digunakan sebagai produk pada invoice line Vendor Bill.
- Nominal baris harus sama dengan nominal Claim Reward yang disetujui/tercatat di CMS.
- Deskripsi baris sebaiknya menyertakan Claim ID untuk memudahkan tracing dan rekonsiliasi.
- Jika parameter belum diisi atau produk tidak valid/tidak dapat digunakan, jangan membuat bill; catat exception agar administrator memperbaiki konfigurasi.
- Produk ini adalah konfigurasi default untuk transaksi reward, bukan produk yang dikirim/dipilih bebas oleh user SFA.
- Perubahan parameter berlaku untuk claim baru. Claim yang sudah diproses harus tetap dapat ditelusuri melalui snapshot data claim dan referensi bill yang sudah dibuat.
**Catatan implementasi:** `product.product` adalah model varian produk yang dapat dipakai langsung pada invoice line Vendor Bill. Field setting menggunakan Many2one ke `product.product`, sehingga integrasi menggunakan produk/varian yang dipilih tersebut secara langsung.
### 3.3 Pengelolaan akses dan audit
- Hanya role yang berwenang yang boleh mengubah CMS User ID pada Vendor dan Default Reward Product.
- Perubahan mapping atau konfigurasi harus mengikuti kontrol akses dan audit log yang berlaku di Odoo.
- Perubahan mapping tidak boleh mengubah vendor pada claim lama yang sudah tercatat.
- Perubahan default product hanya berlaku untuk claim baru yang diproses setelah perubahan konfigurasi.
## 4. Business Flow
### 4.1 Flow end-to-end
1. User melakukan login ke SFA.
2. User mengajukan Claim Reward.
3. CMS memvalidasi claim, termasuk saldo tersedia dan aturan **full-balance claim**.
4. Ketika claim diterima, CMS mencatat Claim ID unik dan mendebit seluruh saldo yang di-claim sesuai desain reward yang telah disepakati.
5. Integrasi menggunakan CMS User ID dari claim untuk mencari Vendor Odoo berdasarkan field `x_cms_user_id`.
6. Integrasi membaca parameter Default Reward Product dari Accounting Settings Odoo.
7. Jika tepat satu vendor ditemukan dan Default Reward Product valid, integrasi membuat **Draft Vendor Bill** dengan:
- Vendor: hasil lookup CMS User ID.
- Product: Default Reward Product dari Accounting Settings.
- Amount: nominal claim yang tersimpan di CMS.
- Reference: Claim ID unik.
- Description: keterangan Claim Reward yang memuat Claim ID.
8. Integrasi selesai setelah request pembuatan Draft Vendor Bill berhasil diproses oleh Odoo. Odoo tidak mengirim pembaruan status atau data bill kembali ke CMS.
9. Finance memeriksa Draft Vendor Bill dan melanjutkan proses accounting di Odoo sesuai prosedur internal.
### 4.2 Diagram flow
```text
User Claim Reward di SFA
|
v
CMS validasi claim dan saldo
|
v
CMS membuat Claim ID + debit full balance
|
v
Lookup Vendor Odoo menggunakan CMS User ID
|
+---- tidak ada / duplikat ----> Exception; jangan buat bill
|
v
Baca Default Reward Product dari Accounting Settings
|
+---- belum diset / tidak valid -> Exception; jangan buat bill
|
v
Create Draft Vendor Bill
(Vendor + Default Product + Claim Amount + Claim ID)
|
v
Selesai di sisi integrasi satu arah
(Odoo tidak mengirim update ke CMS)
|
v
Finance review dan proses bill di Odoo
```
## 5. Data yang Diperlukan
### 5.1 Data dari CMS
| Field konseptual | Keterangan |
|---|---|
| `claim_id` | ID unik claim, digunakan sebagai external reference/idempotency key |
| `cms_user_id` | ID user CMS yang mengajukan claim |
| `claim_amount` | Nominal full balance yang di-claim, dalam IDR |
| `claim_timestamp` | Waktu claim dicatat |
| `description` | Keterangan claim untuk bill |
| `claim_status` | Status claim di CMS |
| `integration_request_log` | Log request dan hasil respons yang tersedia pada saat request; bukan status bill yang disinkronkan dari Odoo |
### 5.2 Data/configuration dari Odoo
| Data | Sumber | Penggunaan |
|---|---|---|
| Vendor/partner ID | Hasil lookup `res.partner` berdasarkan `x_cms_user_id` | Mengisi Vendor pada bill |
| Default Reward Product | Accounting Settings | Mengisi product pada invoice line |
| Company | Konfigurasi integrasi atau aturan company yang disepakati | Menentukan company bill |
| Journal | Konfigurasi Odoo/Accounting | Menentukan jurnal Vendor Bill |
| Expense account | Konfigurasi produk atau aturan Accounting | Akun beban pada invoice line |
| Tax | Konfigurasi produk/aturan Accounting jika berlaku | Perhitungan pajak sesuai kebijakan |
| referensi bill Odoo | Respons Odoo, jika dikembalikan saat create | Tidak disinkronkan kembali ke CMS sebagai update/status; dapat dicatat pada log teknis request bila diperlukan |
Nama field teknis dan sumber konfigurasi final perlu dikonfirmasi saat desain API/module dilakukan.
## 6. Aturan Pembuatan Vendor Bill
- Jenis dokumen adalah Vendor Bill dan status awal harus **Draft**; integrasi tidak boleh otomatis mem-post/validate bill.
- Vendor ditentukan berdasarkan exact match CMS User ID.
- Hasil lookup harus tepat satu vendor yang valid.
- Product ditentukan oleh Default Reward Product di Accounting Settings, bukan oleh input user SFA.
- Nilai claim amount harus berasal dari data claim CMS yang tervalidasi dan tersimpan, bukan dihitung ulang dari request yang tidak dipercaya.
- Baris bill menggunakan nominal sesuai claim. Perlakuan pajak, apakah harga termasuk atau di luar pajak, serta akun expense harus dikonfirmasi Finance.
- Gunakan Claim ID sebagai referensi eksternal yang unik untuk tracing dan pencegahan duplikasi.
- Satu Claim ID hanya boleh menghasilkan maksimal satu Vendor Bill.
- Bill harus dibuat di company Odoo yang benar; untuk database multi-company, company dan akses pengguna integrasi harus dikonfigurasi dengan jelas.
## 7. Error Handling dan Idempotency
| Kondisi | Expected behavior |
|---|---|
| CMS User ID tidak ditemukan di Odoo | Jangan buat bill; tandai exception dan tampilkan alasan |
| CMS User ID cocok dengan lebih dari satu vendor | Jangan buat bill; minta perbaikan data mapping |
| Default Reward Product belum dikonfigurasi | Jangan buat bill; minta administrator melengkapi setting |
| Produk tidak memiliki variant yang dapat digunakan | Jangan buat bill sampai aturan variant/produk diperjelas |
| Odoo timeout setelah request create | Periksa berdasarkan Claim ID/external reference sebelum retry create |
| Bill sudah terbuat untuk Claim ID yang sama | Kembalikan/reconcile bill yang sudah ada; jangan buat duplikat |
| Pembuatan bill gagal secara definitif | Catat error dan lakukan retry sesuai kebijakan integrasi |
| Status hasil create tidak pasti | Jangan membuat ulang secara membabi buta; lakukan reconciliation terlebih dahulu |
**Penting:** sesuai desain sebelumnya, debit reward di CMS tidak otomatis dibatalkan hanya karena integrasi Odoo gagal atau timeout. Log request teknis dipisahkan dari saldo reward. Koreksi atau reversal harus melalui proses yang terotorisasi dan memiliki audit trail.
## 8. Logging dan Status Vendor Bill
Integrasi bersifat **one-way: CMS mengirim request pembuatan Draft Vendor Bill ke Odoo**. Odoo tidak mengirim callback, polling result, atau pembaruan status Vendor Bill kembali ke CMS.
CMS dapat menyimpan log teknis request dan respons yang tersedia saat pengiriman, termasuk:
- Claim ID
- CMS User ID
- Vendor/partner ID hasil mapping pada saat claim diproses
- Nominal claim
- Identitas Default Reward Product yang dikirim
- External reference / Claim ID
- Waktu request dan respons teknis
- Pesan error jika request gagal
Log request bukan status accounting yang disinkronkan dari Odoo. Status Draft, Posted, Paid, atau Cancelled dikelola dan diperiksa di Odoo. CMS tidak perlu menyimpan referensi bill Odoo atau status bill sebagai data yang harus diperbarui setelah pembuatan bill. Jika respons create mengandung ID bill, pemanfaatannya hanya mengikuti kebutuhan log teknis dan tidak menjadi mekanisme sinkronisasi status.
Untuk request yang timeout atau hasilnya tidak pasti, cegah duplikasi menggunakan Claim ID/external reference dan mekanisme pengecekan/retry yang disepakati di sisi integrasi/Odoo. Karena tidak ada update balik ke CMS, status akhir Vendor Bill harus diperiksa di Odoo.
## 9. Security dan Kontrol
- API credential/integration user harus dikelola secara aman dan memiliki hak minimum yang diperlukan.
- User integrasi hanya diberi akses ke company dan operasi Odoo yang dibutuhkan.
- Validasi claim dilakukan di CMS; Odoo tidak boleh menerima nominal dari input bebas user tanpa validasi.
- CMS User ID tidak boleh dapat diubah oleh user SFA biasa.
- Hindari duplikasi melalui unique Claim ID/external reference dan proses retry yang idempotent.
- Semua error, retry, perubahan mapping, dan koreksi penting harus dapat diaudit.
- Jangan membuat Vendor Bill jika vendor mapping atau konfigurasi produk belum valid.
## 10. Open Decisions
Hal-hal berikut masih harus dikonfirmasi sebelum implementasi:
1. Metode integrasi: custom API/module Odoo atau External API Odoo.
2. Technical name final field CMS User ID.
3. Apakah CMS User ID dijamin unik secara global di seluruh company Odoo.
4. Aturan company Odoo yang digunakan saat membuat bill.
5. Technical name final dan perilaku dropdown Default Reward Product yang berelasi ke `product.product`.
6. Jurnal, akun expense, pajak, tanggal accounting, dan deskripsi baris sesuai kebijakan Finance.
7. Apakah perlu field/parameter tambahan untuk mengendalikan company atau jurnal bila terdapat lebih dari satu company.
8. Penanganan operasional exception dan siapa yang bertanggung jawab memperbaiki mapping/configuration.
## 11. Acceptance Criteria
1. Admin dapat mengisi CMS User ID pada master Vendor Odoo.
2. CMS User ID yang sama tidak dapat dipakai oleh lebih dari satu vendor penerima reward.
3. Admin Accounting dapat memilih Default Reward Product pada Accounting Settings → Vendor Bills.
4. Ketika claim valid, sistem mencari vendor berdasarkan CMS User ID dari claim.
5. Draft Vendor Bill dibuat dengan vendor yang tepat, Default Reward Product yang dikonfigurasi, dan amount sesuai claim CMS.
6. Claim ID tercatat sebagai reference yang bisa ditelusuri dari CMS ke Odoo.
7. referensi bill Odoo dan log request teknis tersimpan kembali di CMS.
8. Jika vendor tidak ditemukan/duplikat atau product belum dikonfigurasi, bill tidak dibuat dan exception tercatat.
9. Retry setelah timeout tidak membuat bill duplikat.
10. Integrasi hanya mengirim request untuk membuat Draft Vendor Bill; posting dan pembayaran tetap diproses oleh Finance di Odoo. Tidak ada update status dari Odoo ke CMS.
---
**Catatan:** Dokumen ini mendefinisikan business flow dan kebutuhan fungsional. Detail implementasi teknis final mengikuti keputusan tim CMS/Odoo dan validasi tim Finance.