Update Documentation

grt_product_engineering/docs/TERMINOLOGY_AND_CONVENTIONS.md

@@ -0,0 +1,144 @@
+# Terminology and Conventions
+
+Dokumen ini menjadi sumber referensi tunggal untuk istilah dan konvensi pada modul Product Engineering IFC.
+
+Dokumen ini bersifat rekomendasi implementasi dan dapat direvisi mengikuti perubahan backend.
+
+## 1) Tujuan
+
+- Menyamakan istilah antara backend, frontend, QA, dan dokumentasi.
+- Mencegah ambiguitas pada alur BoM, MO, inventory, dan approval.
+- Menetapkan endpoint utama vs endpoint kompatibilitas.
+
+## 2) Istilah Inti
+
+### Engineering Document
+
+Objek utama dokumen IFC pada model grt.ifc.project.
+
+### Parsed IFC BOM
+
+Struktur BOM hasil ekstraksi IFC dari grt_ifcopenshell (grt.ifc.bom), belum menjadi BoM MRP resmi.
+
+### Estimated BoM
+
+BoM estimasi pada mrp.bom yang dibentuk dari hasil parse IFC.
+Digunakan untuk validasi kebutuhan material awal.
+
+### Permanent BoM
+
+BoM produksi pada mrp.bom yang dibentuk dari Estimated BoM hanya jika availability terpenuhi.
+Menjadi sumber utama pembuatan MO.
+
+### Manufacturing Order (MO)
+
+Perintah produksi mrp.production yang ditautkan ke dokumen IFC.
+
+### MO Availability Summary
+
+Ringkasan ketersediaan material lintas MO untuk menentukan apakah confirm all dapat dilakukan.
+
+## 3) State Conventions
+
+### Parse State
+
+- draft
+- parsed
+- failed
+
+### Approval State
+
+- draft
+- in_validation
+- waiting_production
+- waiting_provisioning
+- approved
+- rejected
+
+Catatan:
+
+- Frontend boleh menampilkan label status bisnis tambahan sebagai derived status.
+- Derived status tidak boleh mengganti state backend inti.
+
+## 4) Endpoint Conventions
+
+### Session
+
+- Primary login: /api/session/login
+- Fallback standar Odoo: /web/session/authenticate
+
+### Manufacturing Order Endpoint Priority
+
+Endpoint utama (recommended):
+
+- /api/ifc/documents/mo/create-from-permanent-bom
+
+Endpoint kompatibilitas (alias):
+
+- /api/ifc/documents/mo/create-if-available
+
+Kebijakan:
+
+- Integrasi baru harus memakai endpoint utama.
+- Endpoint alias dipertahankan untuk menjaga kompatibilitas integrasi lama.
+
+### Pipeline Endpoint
+
+- Eksekusi: /api/ifc/documents/mo/run-pipeline
+- Simulasi tanpa mutasi data: /api/ifc/documents/mo/pipeline-dry-run
+
+## 5) Workflow Conventions (Recommended)
+
+Urutan rekomendasi:
+
+1. Parse IFC
+2. Generate Estimated BoM
+3. Inventory check
+4. Jika shortage, lakukan draft purchase atau create product
+5. Create Permanent BoM
+6. Create MO from Permanent BoM
+7. Check all MO availability
+8. Confirm all MO hanya jika all_available bernilai true
+
+## 6) Naming Conventions
+
+- Gunakan istilah Estimated BoM dan Permanent BoM secara konsisten.
+- Hindari istilah ambigu seperti Production BoM jika maksudnya Permanent BoM.
+- Gunakan istilah MO availability summary untuk ringkasan lintas MO.
+- Gunakan kata recommended dan compatibility alias saat mendeskripsikan endpoint MO create.
+
+## 7) Error Code Conventions
+
+Gunakan format error JSON-RPC:
+
+{
+  "success": false,
+  "error": {
+    "code": "ERROR_CODE",
+    "message": "human-readable message",
+    "details": "optional"
+  }
+}
+
+Contoh code MO dan inventory:
+
+- BOM_PERMANENT_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) Change Management
+
+Jika ada perubahan backend signifikan, update dokumen ini bersama:
+
+- Product_Engineering_Odoo19_IFC_Blueprint.md
+- BACKEND_TECHNICAL_GUIDE.md
+- FRONTEND_TECHNICAL_GUIDE.md
+- API_QUICK_REFERENCE.md
+
+Dengan pendekatan ini, semua tim menggunakan istilah dan alur yang sama.