8.1 KiB
Backend Technical Guide
Dokumen ini ditujukan untuk developer backend Odoo 19 yang akan memelihara dan mengembangkan modul Product Engineering IFC.
Dokumen ini adalah panduan rekomendasi implementasi, bukan kontrak teknis yang kaku. Isi dokumen dapat direview dan direvisi agar selalu selaras dengan implementasi aktual.
Lihat juga indeks dokumentasi utama di README.md. Untuk istilah dan konvensi penamaan, lihat TERMINOLOGY_AND_CONVENTIONS.md.
1) Scope Modul
Modul utama:
- grt_ifcopenshell: parsing IFC, ekstraksi struktur, dan BOM parse awal.
- grt_product_engineering: document management, revision tracking, approval workflow, KPI, dan JSON-RPC API untuk integrasi frontend.
Tujuan backend:
- Menyediakan endpoint berbasis JSON-RPC dengan session authentication.
- Menangani upload dan revisi dokumen IFC.
- Menangani activity check/approval dan riwayat aktivitas.
- Menyediakan endpoint decode file IFC dari binary Odoo ke temp file yang aman.
2) Struktur Teknis Penting
Controller API:
- grt_product_engineering/controllers/ifc_jsonrpc.py
Model inti:
- grt.ifc.project
- grt.ifc.document.revision
- grt.ifc.activity.history
- mrp.bom (inherit: ifc_project_id)
- mrp.production (inherit: ifc_project_id)
Keterangan:
- Session login/logout/me via endpoint custom.
- Semua endpoint bisnis memakai auth user.
- Kontrol akses memanfaatkan check_access_rights dan check_access_rule.
2.1) State Model Aktual
State parsing dokumen IFC:
- draft -> parsed
- draft -> failed
State approval dokumen:
- draft -> in_validation -> waiting_production -> waiting_provisioning -> approved
- reject dapat terjadi pada in_validation, waiting_production, waiting_provisioning
Catatan:
- Gunakan state backend ini sebagai sumber kebenaran untuk backend dan frontend.
- Jika frontend butuh label status bisnis tambahan, gunakan derived status tanpa mengubah state backend inti.
3) Kontrak Authentication Session
Endpoint login authentication yang direkomendasikan:
- Primary: /api/session/login
- Fallback standar Odoo: /web/session/authenticate
Endpoint login:
- URL: /api/session/login
- Type: json
- Auth: none
- Method: POST
- Params wajib: db, login, password
Contoh payload JSON-RPC untuk endpoint primary:
{ "jsonrpc": "2.0", "method": "call", "params": { "db": "odoo19", "login": "user_backend", "password": "******" }, "id": 1 }
Contoh payload JSON-RPC untuk fallback /web/session/authenticate:
{ "jsonrpc": "2.0", "method": "call", "params": { "db": "odoo19", "login": "user_backend", "password": "******" }, "id": 1 }
Response sukses:
{ "success": true, "result": { "uid": 7, "name": "User A", "login": "user_backend", "db": "odoo19", "session_id": "..." } }
Endpoint logout:
- URL: /api/session/logout
- Type: json
- Auth: user
Endpoint me:
- URL: /api/session/me
- Type: json
- Auth: user
4) Daftar Endpoint API Dokumen
4.1 Dokumen IFC
- /api/ifc/documents/list
- /api/ifc/documents/create
- /api/ifc/documents/revise
- /api/ifc/documents/parse
Ketentuan create:
- file_data harus base64 string.
- revision_note_input otomatis mengisi catatan revisi awal.
Ketentuan revise:
- membentuk revisi baru otomatis melalui method write model.
4.2 Approval Workflow
- /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
Workflow state:
- draft -> in_validation -> waiting_production -> waiting_provisioning -> approved
- reject dapat terjadi pada in_validation, waiting_production, waiting_provisioning
4.3 Activity
- /api/ifc/documents/activities/add
- /api/ifc/documents/activities/list
Activity list mengembalikan:
- data mail.activity yang aktif
- history internal grt.ifc.activity.history
4.4 BoM
- /api/ifc/documents/bom/generate
- /api/ifc/documents/bom/get
- /api/ifc/documents/bom/create-permanent-if-available
BoM generate:
- memanggil action_create_bom_estimate di model dokumen
- hasil mencakup estimated_bom
4.5 Temp IFC File
- /api/ifc/documents/temp-file
- /api/ifc/temp/<file_key>
Flow:
- frontend minta temp-file via JSON-RPC
- backend decode binary ke folder temp
- backend kirim signed download_url
- frontend GET download_url dengan session cookie
4.6 Inventory and Procurement
- /api/ifc/documents/inventory/check
- /api/ifc/documents/inventory/create-draft-purchase
- /api/ifc/documents/inventory/create-product
4.7 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
Aturan endpoint MO:
- Estimated BoM harus availability terpenuhi dulu untuk membuat Permanent BoM.
- MO dibuat dari Permanent BoM yang terhubung ke dokumen IFC.
- Gunakan create-from-permanent-bom sebagai endpoint utama; create-if-available dipertahankan untuk kompatibilitas integrasi lama.
- Confirm all MO hanya boleh saat summary availability seluruh MO terpenuhi.
- Gunakan pipeline-dry-run untuk simulasi readiness tanpa perubahan data.
- Jika ada shortage, endpoint mengembalikan error yang sesuai (MO_CREATE_FAILED/MO_AVAILABILITY_FAILED/MO_CONFIRM_FAILED).
Urutan pipeline rekomendasi:
- inventory check terhadap Estimated BoM
- create Permanent BoM jika availability terpenuhi
- create MO dari Permanent BoM
- check all MO availability summary
- confirm all MO hanya jika all_available bernilai true
5) Signed URL Security
Implementasi signed URL:
- Signature: HMAC SHA-256
- Payload signature: file_key | doc_id | uid | exp
- Secret source: ir.config_parameter database.secret (fallback database.uuid, fallback db name)
Validasi saat GET file:
- doc_id, uid, exp, sig wajib ada
- exp belum lewat
- uid di URL harus sama dengan user session
- signature harus valid
- user harus punya akses read ke dokumen
Keuntungan:
- mencegah penggunaan URL temp lintas user
- membatasi masa berlaku URL
6) Temp File Management
Lokasi decode:
- system temp dir / odoo_ifc_temp
Masa berlaku:
- TEMP_TTL_MINUTES = 60
Cleanup:
- dilakukan saat endpoint temp-file dipanggil
- file lama dihapus berdasarkan modified time
Catatan operasi:
- jika traffic tinggi, pertimbangkan scheduler cron cleanup periodik
- jika storage temp shared, pastikan izin file aman
7) JSON-RPC Error Contract
Format error backend:
{ "success": false, "error": { "code": "ACCESS_DENIED", "message": "Tidak punya akses ke dokumen.", "details": "optional" } }
Contoh code yang dipakai:
- BAD_REQUEST
- AUTH_FAILED
- NOT_FOUND
- ACCESS_DENIED
- CREATE_FAILED
- REVISION_FAILED
- PARSE_FAILED
- ACTION_FAILED
- ACTIVITY_FAILED
- BOM_FAILED
- BOM_PERMANENT_FAILED
- DECODE_FAILED
- INVENTORY_FAILED
- PURCHASE_DRAFT_FAILED
- PRODUCT_CREATE_FAILED
- MO_CREATE_FAILED
- MO_AVAILABILITY_FAILED
- MO_CONFIRM_FAILED
- MO_PIPELINE_FAILED
- MO_PIPELINE_DRY_RUN_FAILED
8) Checklist Backend Developer
Checklist implementasi:
- Pastikan dependency module: grt_ifcopenshell, mail, mrp, purchase, web.
- Pastikan route controller ter-load dari init.
- Verifikasi ACL dan record rule untuk model terkait.
- Uji semua endpoint dengan user role berbeda.
- Uji approval workflow role produksi dan provisioning.
- Uji signed URL expiry dan mismatch user.
- Uji beban upload file IFC berukuran besar.
- Uji alur permanent BoM dan MO pipeline (termasuk dry-run).
Checklist release:
- Uji modul install dan upgrade.
- Uji parse IFC sample dan IFC produksi.
- Uji generate estimated BoM.
- Uji inventory check dan draft purchase.
- Uji run-pipeline dan confirm-all-if-available.
- Uji rollback saat error parse.
9) Saran Pengembangan Lanjutan
Prioritas teknis:
- Tambah endpoint complete activity dan comment activity.
- Tambah audit log request API untuk tracing.
- Tambah rate limit pada endpoint login dan temp-file.
- Tambah pagination metadata standard untuk endpoint list.
- Tambah endpoint health-check API terpisah.