Update Documentation

2026-05-31 10:29:44 +07:00
parent 17a9c69379
commit eebb9c9fe9
6 changed files with 208 additions and 12 deletions
@@ -4,6 +4,7 @@ Dokumen ini adalah cheat sheet endpoint Product Engineering IFC untuk kebutuhan
 Dokumen ini bersifat rekomendasi implementasi dan dapat direvisi mengikuti perubahan backend.

 Lihat detail lengkap di [BACKEND_TECHNICAL_GUIDE.md](BACKEND_TECHNICAL_GUIDE.md) dan [FRONTEND_TECHNICAL_GUIDE.md](FRONTEND_TECHNICAL_GUIDE.md).
+Untuk istilah standar, lihat [TERMINOLOGY_AND_CONVENTIONS.md](TERMINOLOGY_AND_CONVENTIONS.md).

 ## State Model Singkat

@@ -209,12 +210,14 @@ Contoh params:
 - Route: /api/ifc/documents/mo/create-if-available
 - Params wajib: document_id
 - Rule: auto memastikan Permanent BoM tersedia, lalu create MO dari Permanent BoM
+- Status: compatibility alias (disarankan gunakan endpoint create-from-permanent-bom untuk integrasi baru)
 - Response: data manufacturing order yang baru dibuat

 ### Create MO from Permanent BoM

 - Route: /api/ifc/documents/mo/create-from-permanent-bom
 - Params wajib: document_id
+- Status: endpoint utama yang direkomendasikan

 ### Check All MOs Availability Summary

@@ -252,6 +255,10 @@ Contoh params:
 4. /api/ifc/documents/mo/check-all-availability
 5. /api/ifc/documents/mo/confirm-all-if-available (hanya bila all_available = true)

+Catatan:
+
+- /api/ifc/documents/mo/create-if-available tersedia untuk kompatibilitas, namun endpoint utama yang direkomendasikan adalah /api/ifc/documents/mo/create-from-permanent-bom.
+
 ## 10) Standard Success and Error

 ### Success
@@ -6,6 +6,7 @@ Dokumen ini adalah panduan rekomendasi implementasi, bukan kontrak teknis yang k
 Isi dokumen dapat direview dan direvisi agar selalu selaras dengan implementasi aktual.

 Lihat juga indeks dokumentasi utama di [README.md](README.md).
+Untuk istilah dan konvensi penamaan, lihat [TERMINOLOGY_AND_CONVENTIONS.md](TERMINOLOGY_AND_CONVENTIONS.md).

 ## 1) Scope Modul

@@ -197,8 +198,8 @@ Flow:

 ### 4.7 Manufacturing Order

- /api/ifc/documents/mo/create-if-available
- /api/ifc/documents/mo/create-from-permanent-bom
+- /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
@@ -208,6 +209,7 @@ 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).
@@ -2,7 +2,11 @@

 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](README.md).
+Untuk istilah dan konvensi endpoint, lihat [TERMINOLOGY_AND_CONVENTIONS.md](TERMINOLOGY_AND_CONVENTIONS.md).

 ## 1) Prinsip Integrasi

@@ -20,11 +24,28 @@ 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
+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

@@ -153,8 +174,8 @@ Saran UI:

 ### 5.6 Manufacturing Order

- /api/ifc/documents/mo/create-if-available
- /api/ifc/documents/mo/create-from-permanent-bom
+- /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
@@ -163,6 +184,7 @@ Saran UI:
 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.
@@ -250,6 +272,10 @@ Checklist tahap awal:
 - 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:
@@ -11,6 +11,8 @@ Dokumen ini boleh direview, ditingkatkan, dan direvisi agar selalu selaras denga
 - grt_ifcopenshell
 - grt_product_engineering

+Untuk konsistensi istilah lintas dokumen, lihat juga [TERMINOLOGY_AND_CONVENTIONS.md](TERMINOLOGY_AND_CONVENTIONS.md).
+
 ## Objective

 Menyediakan panduan praktis pengembangan Product Engineering berbasis IFC yang:
@@ -2,6 +2,9 @@

 Dokumentasi ini menjadi pintu masuk utama untuk tim backend dan frontend yang mengintegrasikan Odoo 19 Product Engineering dengan IFC Viewer.

+Seluruh dokumen pada folder ini bersifat rekomendasi implementasi.
+Dokumen dapat direview dan direvisi untuk menyesuaikan implementasi terbaru.
+
 ## Dokumen Utama

 1. Backend technical developer guide:
@@ -13,6 +16,14 @@ Dokumentasi ini menjadi pintu masuk utama untuk tim backend dan frontend yang me
 3. API quick reference (cheat sheet):
 [API_QUICK_REFERENCE.md](API_QUICK_REFERENCE.md)

+4. Terminology and conventions (single source of truth):
+[TERMINOLOGY_AND_CONVENTIONS.md](TERMINOLOGY_AND_CONVENTIONS.md)
+
+## Catatan Scope
+
+- Implemented: alur dokumen IFC, approval, BoM, inventory, procurement, MO pipeline, dan temp signed URL.
+- Roadmap: fitur lanjutan seperti quality domain khusus, ECO, visual revision comparison, dan AI recommendation.
+
 ## Peta Endpoint

 ### Session
@@ -58,8 +69,8 @@ Dokumentasi ini menjadi pintu masuk utama untuk tim backend dan frontend yang me

 ### Manufacturing Order

- /api/ifc/documents/mo/create-if-available
- /api/ifc/documents/mo/create-from-permanent-bom
+- /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
@@ -80,11 +91,15 @@ Dokumentasi ini menjadi pintu masuk utama untuk tim backend dan frontend yang me
 6. Buat activity dan monitor activity list.
 7. Generate estimated BoM.
 8. Create Permanent BoM jika availability Estimated BoM terpenuhi.
-9. Create MO dari Permanent BoM.
+9. Create MO dari Permanent BoM (recommended: create-from-permanent-bom).
 10. Cek availability all MOs dan summary material.
 11. Confirm all MOs jika availability summary terpenuhi.
 12. Minta signed URL temp-file dan load IFC ke viewer.

+Catatan:
+
+- Gunakan pipeline-dry-run untuk preview readiness tanpa perubahan data sebelum eksekusi real.
+
 ## Catatan Keamanan Penting

 - Semua endpoint bisnis membutuhkan session user aktif.
@@ -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.