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.

Lihat juga indeks dokumentasi utama di README.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. Submit approval sesuai alur bisnis
5. Tambah atau tampilkan activity per dokumen
6. Generate BoM saat dibutuhkan
7. Minta signed temp URL
8. Load IFC file ke viewer menggunakan URL temp

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-if-available
• /api/ifc/documents/mo/create-from-permanent-bom
• /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.
• 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.
• 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.