Odoo14Kanjabung/README.md

GRT Sales Business Category

Dokumentasi ini menjelaskan modul grt_sales_business_category pada Odoo 14, termasuk alur customer-wilayah-ongkir, approval Sales Order, dan endpoint frontend sales.

Ringkasan

Modul ini menambahkan kemampuan berikut:

• Integrasi Business Category pada Sales Order, Invoice, dan Payment.
• Approval 2 tahap untuk konfirmasi Sales Order.
• Customer QR Reference unik pada partner utama (commercial partner).
• Wilayah Ongkir customer berbasis wilayah.kecamatan.
• Rule ongkir frontend per wilayah dengan tarif per kg.
• Auto tambah line ongkir pada Sales Order frontend.
• Auto recalculated ongkir saat draft quotation diedit di backend UI.

Dependency

Modul ini bergantung pada:

• sale_management
• sale_crm
• account
• contacts
• asa_wilayah
• grt_business_category_base
• grt_crm_business_category

Fitur Utama

1. Business Category pada Dokumen Sales

• Field business_category_id pada Sales Order.
• Analytic account mengikuti business category.
• Team Sales dibatasi agar sesuai company dan business category.
• Propagasi business category ke invoice.
• Rule access berdasarkan effective business category user.

2. Approval Berlapis Sales Order

Status approval:

• draft
• waiting_sales_leader
• waiting_accounting
• approved
• rejected

Alur:

1. User submit quotation.
2. Sales Team Leader approve.
3. Accounting Manager approve.
4. Sistem menjalankan action confirm.

3. Customer QR Reference

• Setiap commercial partner memiliki customer_qr_ref unik.
• Sequence di-generate otomatis saat create.
• Backfill customer lama dijalankan saat init modul.
• Digunakan oleh endpoint frontend untuk lookup customer.

4. Wilayah Ongkir Customer

Pada res.partner tersedia field:

• shipping_wilayah_kecamatan_id (Wilayah Ongkir)

Field ini menjadi kunci pemilihan rule ongkir saat create order frontend.

5. Frontend Shipping Rule

Model sale.frontend.shipping.rule berisi:

• company_id
• wilayah_kecamatan_id
• shipping_product_id
• shipping_price_per_kg
• active

Ketentuan:

• Unik per company + wilayah.
• Tarif per kg wajib lebih dari 0.
• Produk ongkir harus sale_ok.
• Company produk harus konsisten dengan company rule.

Alur Otomatis Ongkir

Saat create draft order dari endpoint frontend

1. Order dibuat dengan penanda is_frontend_order = True.

2. Sistem membaca customer shipping_wilayah_kecamatan_id.

3. Sistem mencari rule aktif sesuai company + wilayah.

4. Sistem menghitung total berat produk non-shipping line.

5. Harga ongkir dihitung dengan rumus:

   Ongkir = Total_Berat_Kg x Tarif_Per_Kg

6. Sistem menambah atau mengupdate 1 line ongkir otomatis.

Saat user edit draft quotation di backend UI

Untuk order frontend pada state draft atau sent, ongkir akan dihitung ulang otomatis saat:

• Partner diganti.
• Order line berubah.
• Flag is_frontend_order berubah.
• Ada perubahan baris melalui create, write, atau unlink sale.order.line.

Mekanisme guard context dipakai agar update line ongkir internal tidak memicu loop rekursif.

Konfigurasi

A. Konfigurasi Master

1. Pastikan Team Sales, Business Category, dan user membership sudah benar.
2. Isi Wilayah Ongkir pada customer.
3. Buat Frontend Shipping Rule:
   • Menu: Sales > Frontend Shipping Rules
   • Isi company, wilayah, produk ongkir, tarif per kg.

B. Konfigurasi Produk

• Produk yang dijual harus memiliki berat jika ingin ikut perhitungan ongkir.
• Produk ongkir harus aktif dan sale_ok.

Endpoint API Frontend Sales

Endpoint utama:

• POST /api/sales/authenticate
• POST /api/sales/products
• POST /api/sales/payment-terms
• POST /api/sales/customer-qr-by-id
• POST /api/sales/customer-qr-payload-by-id
• POST /api/sales/customer-qr-payload-by-ref
• POST /api/sales/customer-detail-by-qr
• POST /api/sales/customer-accounting-summary-by-qr
• POST /api/sales/orders-by-qr
• POST /api/sales/draft-order
• POST /api/sales/draft-order/bon-kering
• POST /api/sales/draft-order/bon-partus
• POST /api/sales/draft-order/bon-reguler

Catatan autentikasi:

• Login memakai auth public untuk membentuk session.
• Endpoint data sales memakai auth user.
• Frontend lintas domain harus mengirim cookie session dengan credentials include.

Validasi dan Error yang Umum

Kasus yang akan ditolak sistem:

• Customer belum memiliki Wilayah Ongkir.
• Rule ongkir untuk wilayah customer belum tersedia.
• Tarif per kg kurang dari atau sama dengan 0.
• Produk ongkir tidak valid atau tidak bisa dijual.
• Total berat produk kurang dari atau sama dengan 0.
• Konfirmasi Sales Order tanpa approval complete.

Hak Akses

• Sales user dan manager dibatasi oleh effective business category.
• System admin memiliki bypass penuh.
• Rule model yang terkait sales/accounting menerapkan domain per company dan business category.

Pengujian

Script smoke test tersedia:

• test_frontend_shipping_rule_api.py

Contoh:

python test_frontend_shipping_rule_api.py --base-url http://localhost:8070 --db your_db --login admin --password admin --endpoint /api/sales/draft-order/bon-kering --partner-id 45 --payment-term-id 4 --team-id 3 --business-category-id 2 --product-id 1001

Struktur Modul Relevan

• grt_sales_business_category/models/sale_order.py
• grt_sales_business_category/models/res_partner.py
• grt_sales_business_category/models/frontend_shipping_rule.py
• grt_sales_business_category/controllers/main.py
• grt_sales_business_category/views/sale_order_views.xml
• grt_sales_business_category/views/res_partner_views.xml
• grt_sales_business_category/views/frontend_shipping_rule_views.xml
• grt_sales_business_category/security/ir.rule.csv
• grt_sales_business_category/security/ir.model.access.csv

Dokumen Tambahan

• grt_sales_business_category/frontend_sales.md
• grt_sales_business_category/frontend_shipping_rule_test.md

Catatan Implementasi Terbaru

Pembaruan terakhir menambahkan recalculated ongkir otomatis saat draft Sales Order frontend diedit dari backend UI, sehingga nilai ongkir tetap sinkron terhadap perubahan item dan berat transaksi.