First Commit
This commit is contained in:
@@ -0,0 +1,330 @@
|
||||
# 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](README.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:
|
||||
|
||||
1. frontend minta temp-file via JSON-RPC
|
||||
2. backend decode binary ke folder temp
|
||||
3. backend kirim signed download_url
|
||||
4. 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-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
|
||||
|
||||
Aturan endpoint MO:
|
||||
|
||||
- Estimated BoM harus availability terpenuhi dulu untuk membuat Permanent BoM.
|
||||
- MO dibuat dari Permanent BoM yang terhubung ke dokumen IFC.
|
||||
- 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:
|
||||
|
||||
1. inventory check terhadap Estimated BoM
|
||||
2. create Permanent BoM jika availability terpenuhi
|
||||
3. create MO dari Permanent BoM
|
||||
4. check all MO availability summary
|
||||
5. 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.
|
||||
Reference in New Issue
Block a user