Addon-Odoo19/grt_product_engineering/docs/TERMINOLOGY_AND_CONVENTIONS.md

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.