Addon-Odoo19/grt_product_engineering/docs/FRONTEND_TECHNICAL_GUIDE.md

Frontend Technical Guide

Dokumen ini ditujukan untuk developer frontend (Vue.js + three.js + ThatOpen) yang akan mengintegrasikan aplikasi dengan backend Odoo 19 Product Engineering.

Dokumen ini adalah panduan rekomendasi implementasi. Dokumen dapat direview dan direvisi mengikuti perubahan implementasi backend.

Lihat juga indeks dokumentasi utama di README.md. Untuk istilah dan konvensi endpoint, lihat TERMINOLOGY_AND_CONVENTIONS.md.

1) Prinsip Integrasi

Prinsip utama:

• Gunakan JSON-RPC endpoint Odoo type json untuk operasi bisnis.
• Gunakan session cookie untuk auth setelah login.
• Jangan simpan password user di local storage.
• Untuk file IFC viewer, gunakan signed URL dari endpoint temp-file.

2) Alur Integrasi End-to-End

Urutan umum:

1. Login session
2. List atau create dokumen IFC
3. Parse IFC
4. Tambah atau tampilkan activity per dokumen
5. Submit approval sesuai alur bisnis (production -> provisioning)
6. Generate Estimated BoM
7. Jalankan inventory/check
8. Jika shortage, jalankan create-draft-purchase atau create-product
9. Create Permanent BoM (jika availability terpenuhi)
10. Create MO from Permanent BoM
11. Jalankan check-all-availability
12. Confirm all MOs jika all_available bernilai true
13. Opsional: gunakan run-pipeline untuk eksekusi otomatis
14. Opsional: gunakan pipeline-dry-run untuk preview tanpa mutasi data
15. Minta signed temp URL dan load IFC file ke viewer

Catatan:

• Urutan di atas adalah urutan rekomendasi yang selaras dengan backend saat ini.
• Untuk UI cepat, frontend dapat memanfaatkan endpoint run-pipeline atau pipeline-dry-run.

2.1) State Model Singkat

• Parse state: draft -> parsed | failed
• Approval state: draft -> in_validation -> waiting_production -> waiting_provisioning -> approved (dapat rejected pada tahap validasi/approval)

3) Format Request JSON-RPC

Gunakan body seperti berikut untuk endpoint type json Odoo:

{ "jsonrpc": "2.0", "method": "call", "params": { "document_id": 12 }, "id": 1 }

Catatan:

• Header yang umum: Content-Type: application/json
• Session cookie harus otomatis dikirim browser
• Jika frontend beda domain, pastikan konfigurasi CORS/proxy sesuai

4) Session Authentication

Endpoint login authentication yang digunakan frontend:

• Primary: /api/session/login
• Fallback standar Odoo: /web/session/authenticate

4.1 Login

Endpoint:

• /api/session/login

Params wajib:

• db
• login
• password

Contoh params:

{ "db": "odoo19", "login": "user_at_company", "password": "******" }

4.2 Cek sesi aktif

Endpoint:

• /api/session/me

Gunakan untuk:

• restore session saat reload page
• validasi user sebelum load modul viewer

4.3 Logout

Endpoint:

• /api/session/logout

5) Endpoint Operasional Frontend

5.1 Dokumen

• /api/ifc/documents/list
• /api/ifc/documents/create
• /api/ifc/documents/revise
• /api/ifc/documents/parse

Saran UI:

• Setelah create atau revise, tampilkan status revisi terbaru.
• Setelah parse, refresh detail dokumen agar metrik parse terlihat.

5.2 Approval

• /api/ifc/documents/approval/request-validation
• /api/ifc/documents/approval/submit
• /api/ifc/documents/approval/approve-production
• /api/ifc/documents/approval/approve-provisioning
• /api/ifc/documents/approval/reject
• /api/ifc/documents/approval/back-draft

Saran UI:

• Tombol aksi ditampilkan berdasarkan role user dan approval_state.
• Tampilkan reason reject di form revisi berikutnya.

5.3 Activity

• /api/ifc/documents/activities/add
• /api/ifc/documents/activities/list

Saran UI:

• Tampilkan panel Activity (mail.activity) dan panel History terpisah.
• Sort activity berdasarkan deadline terdekat.

5.4 BoM

• /api/ifc/documents/bom/generate
• /api/ifc/documents/bom/get
• /api/ifc/documents/bom/create-permanent-if-available

Saran UI:

• Gunakan parsed_bom untuk tree part IFC.
• Gunakan estimated_bom untuk ringkasan manufacturing.
• Setelah estimated BoM siap dan available, trigger create-permanent-if-available.

5.5 Inventory and Procurement

• /api/ifc/documents/inventory/check
• /api/ifc/documents/inventory/create-draft-purchase
• /api/ifc/documents/inventory/create-product

Saran UI:

• Jalankan inventory/check sebelum tombol Create MO.
• Jika shortage > 0, tampilkan opsi create draft purchase.
• Jika komponen belum punya product, tampilkan opsi create product.

5.6 Manufacturing Order

• /api/ifc/documents/mo/create-from-permanent-bom (recommended)
• /api/ifc/documents/mo/create-if-available (compatibility alias)
• /api/ifc/documents/mo/check-all-availability
• /api/ifc/documents/mo/confirm-all-if-available
• /api/ifc/documents/mo/run-pipeline
• /api/ifc/documents/mo/pipeline-dry-run

Saran UI:

• Aktifkan tombol Create MO hanya jika permanent BoM sudah ada dan availability terpenuhi.
• Untuk integrasi baru, gunakan endpoint create-from-permanent-bom sebagai jalur utama.
• Setelah ada beberapa MO, tampilkan summary kebutuhan produk dari check-all-availability.
• Aktifkan tombol Confirm All MOs hanya jika all_available = true pada summary all MOs.
• Untuk mode otomatis, gunakan run-pipeline dengan auto_confirm=true.
• Untuk preview tanpa perubahan data, gunakan pipeline-dry-run sebelum eksekusi real.
• Jika endpoint gagal karena shortage, arahkan user ke workflow procurement.

6) Integrasi IFC Viewer (ThatOpen)

Flow render IFC:

1. Panggil /api/ifc/documents/temp-file dengan document_id
2. Backend mengembalikan download_url signed
3. Frontend melakukan HTTP GET ke download_url
4. Berikan URL atau blob ke pipeline loader IFC viewer

Penting:

• download_url memiliki expiry
• jika 403 atau expired, minta ulang endpoint temp-file
• jangan cache signed URL terlalu lama

7) Error Handling Strategy

Kontrak error:

{ "success": false, "error": { "code": "PARSE_FAILED", "message": "...", "details": "optional" } }

Saran mapping UI:

• BAD_REQUEST: validasi input form
• AUTH_FAILED: redirect login
• ACCESS_DENIED: tampilkan notifikasi izin
• NOT_FOUND: refresh list lalu tampilkan warning
• DECODE_FAILED: minta user upload ulang

Retry policy:

• endpoint temp-file: retry 1 kali jika timeout
• endpoint parse: jangan auto-retry, butuh konfirmasi user
• endpoint approval: jangan auto-retry untuk hindari duplikasi aksi

8) State Management Recommendation

Store minimal:

• auth: uid, name, login, isAuthenticated
• documents: list, selectedDocument, paging
• activities: listByDocument
• approval: availableActions
• viewer: currentIfcUrl, loadState, error

Event yang perlu memicu refresh data:

• setelah revise
• setelah parse
• setelah approval action
• setelah activity add
• setelah bom generate

9) Security Recommendation untuk Frontend

Checklist keamanan:

• Hindari menyimpan kredensial user secara permanen.
• Pastikan semua request menggunakan HTTPS.
• Jangan expose signed URL ke log publik.
• Bersihkan state viewer saat logout.
• Handle 401 dan 403 secara terpusat.

10) Checklist Integrasi Frontend

Checklist tahap awal:

• Login dan persist session berhasil.
• List dokumen dan detail dokumen berhasil.
• Upload create dan revise berhasil untuk file IFC nyata.
• Parse IFC sukses dan state berubah.
• Activity add/list tampil di UI per dokumen.
• Approval flow berjalan sesuai role.
• BoM generate/get tampil di panel BOM.
• Inventory check dan draft purchase/create product flow berjalan.
• Alur permanent BoM dan create MO from permanent BoM berjalan.
• check-all-availability dan confirm-all-if-available berjalan sesuai rule all_available.
• run-pipeline dan pipeline-dry-run tervalidasi dari UI.
• Viewer berhasil load file dari signed temp URL.

Checklist UAT:

• Uji dokumen besar.
• Uji expiry signed URL saat viewer masih terbuka.
• Uji pergantian role manager produksi/provisioning.
• Uji sesi kadaluarsa lalu login ulang.