First Commit

2026-05-31 10:17:09 +07:00
commit 17a9c69379
4547 changed files with 1170384 additions and 0 deletions
@@ -0,0 +1,318 @@
+# API Quick Reference
+
+Dokumen ini adalah cheat sheet endpoint Product Engineering IFC untuk kebutuhan implementasi cepat.
+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).
+
+## State Model Singkat
+
+- Parse state: draft -> parsed | failed
+- Approval state: draft -> in_validation -> waiting_production -> waiting_provisioning -> approved (dapat rejected pada tahap validasi atau approval)
+
+## 1) JSON-RPC Envelope
+
+Gunakan payload berikut untuk semua endpoint type json:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "call",
+  "params": {},
+  "id": 1
+}
+```
+
+## 2) Session Endpoints
+
+Authentication login endpoint:
+
+- Primary: /api/session/login
+- Fallback standar Odoo: /web/session/authenticate
+
+### Login
+
+- Route: /api/session/login
+- Auth: none
+- Params: db, login, password
+
+Contoh params:
+
+```json
+{
+  "db": "odoo19",
+  "login": "user_backend",
+  "password": "******"
+}
+```
+
+### Logout
+
+- Route: /api/session/logout
+- Auth: user
+- Params: none
+
+### Me
+
+- Route: /api/session/me
+- Auth: user
+- Params: none
+
+## 3) Document Endpoints
+
+### List
+
+- Route: /api/ifc/documents/list
+- Auth: user
+- Params opsional: limit, offset, search
+
+### Create
+
+- Route: /api/ifc/documents/create
+- Auth: user
+- Params wajib: name, file_data
+- Params opsional: file_name, revision_note, company_id
+
+Contoh params:
+
+```json
+{
+  "name": "IFC Docking Station",
+  "file_name": "docking_station.ifc",
+  "file_data": "<BASE64_IFC>",
+  "revision_note": "Initial upload"
+}
+```
+
+### Revise
+
+- Route: /api/ifc/documents/revise
+- Auth: user
+- Params wajib: document_id, file_data
+- Params opsional: file_name, revision_note
+
+### Parse
+
+- Route: /api/ifc/documents/parse
+- Auth: user
+- Params wajib: document_id
+
+## 4) Approval Endpoints
+
+### Request Validation
+
+- Route: /api/ifc/documents/approval/request-validation
+- Params wajib: document_id
+
+### Submit Approval
+
+- Route: /api/ifc/documents/approval/submit
+- Params wajib: document_id
+
+### Approve Production
+
+- Route: /api/ifc/documents/approval/approve-production
+- Params wajib: document_id
+- Role: manager produksi
+
+### Approve Provisioning
+
+- Route: /api/ifc/documents/approval/approve-provisioning
+- Params wajib: document_id
+- Role: manager provisioning
+
+### Reject
+
+- Route: /api/ifc/documents/approval/reject
+- Params wajib: document_id
+- Params opsional: note
+
+### Back to Draft
+
+- Route: /api/ifc/documents/approval/back-draft
+- Params wajib: document_id
+
+## 5) Activity Endpoints
+
+### Add Activity
+
+- Route: /api/ifc/documents/activities/add
+- Params wajib: document_id, summary
+- Params opsional: note, user_id, deadline
+
+### List Activity
+
+- Route: /api/ifc/documents/activities/list
+- Params wajib: document_id
+- Response: activities aktif dan history internal
+
+## 6) BoM Endpoints
+
+### Generate Estimated BoM
+
+- Route: /api/ifc/documents/bom/generate
+- Params wajib: document_id
+
+### Get BoM Data
+
+- Route: /api/ifc/documents/bom/get
+- Params wajib: document_id
+- Response: parsed_bom dan estimated_bom
+
+### Create Permanent BoM If Availability Fulfilled
+
+- Route: /api/ifc/documents/bom/create-permanent-if-available
+- Params wajib: document_id
+- Rule: hanya berhasil jika availability Estimated BoM terpenuhi
+- Response: data permanent_bom yang terhubung ke IFC document
+
+## 7) Temp IFC File Endpoints
+
+### Generate Signed Temp URL
+
+- Route: /api/ifc/documents/temp-file
+- Params wajib: document_id
+- Response penting: download_url, expires_in_minutes, expires_at_unix
+
+### Download Temp File
+
+- Route: /api/ifc/temp/<file_key>?doc_id=...&uid=...&exp=...&sig=...
+- Method: GET
+- Auth: user (session)
+- Catatan: URL signed, ada expiry, terikat user dan dokumen
+
+## 8) Inventory and Procurement Endpoints
+
+### Check Availability vs Estimated BoM
+
+- Route: /api/ifc/documents/inventory/check
+- Params wajib: document_id
+- Response: ringkasan all_available, total_shortage_qty, dan detail item per komponen
+
+### Create Draft Purchase for Shortage
+
+- Route: /api/ifc/documents/inventory/create-draft-purchase
+- Params wajib: document_id
+- Params opsional: vendor_id, only_shortage (default true)
+- Response: daftar draft purchase.order yang dibuat
+
+### Create Product from IFC BOM Line
+
+- Route: /api/ifc/documents/inventory/create-product
+- Params wajib: document_id, ifc_bom_line_id
+- Response: data product existing/new + flag created
+
+## 9) Manufacturing Order Endpoints
+
+### Create MO If Availability Fulfilled
+
+- Route: /api/ifc/documents/mo/create-if-available
+- Params wajib: document_id
+- Rule: auto memastikan Permanent BoM tersedia, lalu create MO dari Permanent BoM
+- 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
+
+### Check All MOs Availability Summary
+
+- Route: /api/ifc/documents/mo/check-all-availability
+- Params wajib: document_id
+- Response: summary all MOs + summary product requirement vs on hand
+
+### Confirm All MOs If Available
+
+- Route: /api/ifc/documents/mo/confirm-all-if-available
+- Params wajib: document_id
+- Rule: hanya confirm jika summary all MOs menunjukkan all_available = true
+- Response: daftar MO yang dikonfirmasi
+
+### Run End-to-End MO Pipeline
+
+- Route: /api/ifc/documents/mo/run-pipeline
+- Params wajib: document_id
+- Params opsional: auto_confirm (default false)
+- Alur: check estimated availability -> create permanent bom -> create mo from permanent bom -> check all mo summary -> optional confirm all mo
+- Response: ringkasan lengkap tiap tahap pipeline
+
+### Dry Run MO Pipeline (No Data Mutation)
+
+- Route: /api/ifc/documents/mo/pipeline-dry-run
+- Params wajib: document_id
+- Alur: simulasi readiness tiap tahap pipeline tanpa create/update data
+- Response: preview readiness step, estimated availability, existing MO summary
+
+### Urutan Rekomendasi Eksekusi MO
+
+1. /api/ifc/documents/inventory/check
+2. /api/ifc/documents/bom/create-permanent-if-available
+3. /api/ifc/documents/mo/create-from-permanent-bom
+4. /api/ifc/documents/mo/check-all-availability
+5. /api/ifc/documents/mo/confirm-all-if-available (hanya bila all_available = true)
+
+## 10) Standard Success and Error
+
+### Success
+
+```json
+{
+  "success": true,
+  "result": {}
+}
+```
+
+### Error
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "BAD_REQUEST",
+    "message": "...",
+    "details": "optional"
+  }
+}
+```
+
+## 11) Error Code Quick List
+
+- BAD_REQUEST
+- AUTH_FAILED
+- NOT_FOUND
+- ACCESS_DENIED
+- CREATE_FAILED
+- REVISION_FAILED
+- PARSE_FAILED
+- ACTION_FAILED
+- ACTIVITY_FAILED
+- BOM_FAILED
+- DECODE_FAILED
+- INVENTORY_FAILED
+- PURCHASE_DRAFT_FAILED
+- PRODUCT_CREATE_FAILED
+- MO_CREATE_FAILED
+- BOM_PERMANENT_FAILED
+- MO_AVAILABILITY_FAILED
+- MO_CONFIRM_FAILED
+- MO_PIPELINE_FAILED
+- MO_PIPELINE_DRY_RUN_FAILED
+
+## 12) Integration Checklist
+
+- Login session berhasil dan cookie terkirim otomatis.
+- Upload create atau revise dokumen IFC sukses.
+- Parse IFC sukses dan state berubah.
+- Approval flow berjalan sesuai role.
+- Activity add atau list berjalan per dokumen.
+- Generate atau get BoM sukses.
+- Create permanent BoM dari estimated BoM sukses.
+- Cek inventory availability dan trigger draft purchase sukses.
+- Endpoint create product dari IFC BOM line berjalan.
+- Endpoint create MO dari permanent BoM berjalan.
+- Endpoint check-all-MOs availability summary dan confirm-all-MOs berjalan.
+- Endpoint run-pipeline berjalan untuk eksekusi flow end-to-end.
+- Endpoint pipeline-dry-run berjalan untuk preview sebelum eksekusi real.
+- Temp file URL bisa dipakai viewer.
+- Jika URL expired, frontend meminta URL baru.
@@ -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.
@@ -0,0 +1,260 @@
+# Frontend Technical Guide
+
+Dokumen ini ditujukan untuk developer frontend (Vue.js + three.js + ThatOpen) yang akan mengintegrasikan aplikasi dengan backend Odoo 19 Product Engineering.
+
+Lihat juga indeks dokumentasi utama di [README.md](README.md).
+
+## 1) Prinsip Integrasi
+
+Prinsip utama:
+
+- Gunakan JSON-RPC endpoint Odoo type json untuk operasi bisnis.
+- Gunakan session cookie untuk auth setelah login.
+- Jangan simpan password user di local storage.
+- Untuk file IFC viewer, gunakan signed URL dari endpoint temp-file.
+
+## 2) Alur Integrasi End-to-End
+
+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
+
+## 3) Format Request JSON-RPC
+
+Gunakan body seperti berikut untuk endpoint type json Odoo:
+
+{
+  "jsonrpc": "2.0",
+  "method": "call",
+  "params": {
+    "document_id": 12
+  },
+  "id": 1
+}
+
+Catatan:
+
+- Header yang umum: Content-Type: application/json
+- Session cookie harus otomatis dikirim browser
+- Jika frontend beda domain, pastikan konfigurasi CORS/proxy sesuai
+
+## 4) Session Authentication
+
+Endpoint login authentication yang digunakan frontend:
+
+- Primary: /api/session/login
+- Fallback standar Odoo: /web/session/authenticate
+
+### 4.1 Login
+
+Endpoint:
+
+- /api/session/login
+
+Params wajib:
+
+- db
+- login
+- password
+
+Contoh params:
+
+{
+  "db": "odoo19",
+  "login": "user_at_company",
+  "password": "******"
+}
+
+### 4.2 Cek sesi aktif
+
+Endpoint:
+
+- /api/session/me
+
+Gunakan untuk:
+
+- restore session saat reload page
+- validasi user sebelum load modul viewer
+
+### 4.3 Logout
+
+Endpoint:
+
+- /api/session/logout
+
+## 5) Endpoint Operasional Frontend
+
+### 5.1 Dokumen
+
+- /api/ifc/documents/list
+- /api/ifc/documents/create
+- /api/ifc/documents/revise
+- /api/ifc/documents/parse
+
+Saran UI:
+
+- Setelah create atau revise, tampilkan status revisi terbaru.
+- Setelah parse, refresh detail dokumen agar metrik parse terlihat.
+
+### 5.2 Approval
+
+- /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
+
+Saran UI:
+
+- Tombol aksi ditampilkan berdasarkan role user dan approval_state.
+- Tampilkan reason reject di form revisi berikutnya.
+
+### 5.3 Activity
+
+- /api/ifc/documents/activities/add
+- /api/ifc/documents/activities/list
+
+Saran UI:
+
+- Tampilkan panel Activity (mail.activity) dan panel History terpisah.
+- Sort activity berdasarkan deadline terdekat.
+
+### 5.4 BoM
+
+- /api/ifc/documents/bom/generate
+- /api/ifc/documents/bom/get
+- /api/ifc/documents/bom/create-permanent-if-available
+
+Saran UI:
+
+- Gunakan parsed_bom untuk tree part IFC.
+- Gunakan estimated_bom untuk ringkasan manufacturing.
+- Setelah estimated BoM siap dan available, trigger create-permanent-if-available.
+
+### 5.5 Inventory and Procurement
+
+- /api/ifc/documents/inventory/check
+- /api/ifc/documents/inventory/create-draft-purchase
+- /api/ifc/documents/inventory/create-product
+
+Saran UI:
+
+- Jalankan inventory/check sebelum tombol Create MO.
+- Jika shortage > 0, tampilkan opsi create draft purchase.
+- Jika komponen belum punya product, tampilkan opsi create product.
+
+### 5.6 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
+
+Saran UI:
+
+- Aktifkan tombol Create MO hanya jika permanent BoM sudah ada dan availability terpenuhi.
+- 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.
+- Untuk preview tanpa perubahan data, gunakan pipeline-dry-run sebelum eksekusi real.
+- Jika endpoint gagal karena shortage, arahkan user ke workflow procurement.
+
+## 6) Integrasi IFC Viewer (ThatOpen)
+
+Flow render IFC:
+
+1. Panggil /api/ifc/documents/temp-file dengan document_id
+2. Backend mengembalikan download_url signed
+3. Frontend melakukan HTTP GET ke download_url
+4. Berikan URL atau blob ke pipeline loader IFC viewer
+
+Penting:
+
+- download_url memiliki expiry
+- jika 403 atau expired, minta ulang endpoint temp-file
+- jangan cache signed URL terlalu lama
+
+## 7) Error Handling Strategy
+
+Kontrak error:
+
+{
+  "success": false,
+  "error": {
+    "code": "PARSE_FAILED",
+    "message": "...",
+    "details": "optional"
+  }
+}
+
+Saran mapping UI:
+
+- BAD_REQUEST: validasi input form
+- AUTH_FAILED: redirect login
+- ACCESS_DENIED: tampilkan notifikasi izin
+- NOT_FOUND: refresh list lalu tampilkan warning
+- DECODE_FAILED: minta user upload ulang
+
+Retry policy:
+
+- endpoint temp-file: retry 1 kali jika timeout
+- endpoint parse: jangan auto-retry, butuh konfirmasi user
+- endpoint approval: jangan auto-retry untuk hindari duplikasi aksi
+
+## 8) State Management Recommendation
+
+Store minimal:
+
+- auth: uid, name, login, isAuthenticated
+- documents: list, selectedDocument, paging
+- activities: listByDocument
+- approval: availableActions
+- viewer: currentIfcUrl, loadState, error
+
+Event yang perlu memicu refresh data:
+
+- setelah revise
+- setelah parse
+- setelah approval action
+- setelah activity add
+- setelah bom generate
+
+## 9) Security Recommendation untuk Frontend
+
+Checklist keamanan:
+
+- Hindari menyimpan kredensial user secara permanen.
+- Pastikan semua request menggunakan HTTPS.
+- Jangan expose signed URL ke log publik.
+- Bersihkan state viewer saat logout.
+- Handle 401 dan 403 secara terpusat.
+
+## 10) Checklist Integrasi Frontend
+
+Checklist tahap awal:
+
+- Login dan persist session berhasil.
+- List dokumen dan detail dokumen berhasil.
+- Upload create dan revise berhasil untuk file IFC nyata.
+- Parse IFC sukses dan state berubah.
+- Activity add/list tampil di UI per dokumen.
+- Approval flow berjalan sesuai role.
+- BoM generate/get tampil di panel BOM.
+- Viewer berhasil load file dari signed temp URL.
+
+Checklist UAT:
+
+- Uji dokumen besar.
+- Uji expiry signed URL saat viewer masih terbuka.
+- Uji pergantian role manager produksi/provisioning.
+- Uji sesi kadaluarsa lalu login ulang.
@@ -0,0 +1,173 @@
+# Product Engineering IFC Blueprint
+## Odoo 19 + IfcOpenShell + Vue.js 3D Viewer
+
+## Document Positioning
+
+Dokumen ini adalah dokumen rekomendasi arsitektur dan implementasi.
+Dokumen ini bukan kontrak teknis kaku.
+
+Dokumen ini boleh direview, ditingkatkan, dan direvisi agar selalu selaras dengan implementasi aktual di:
+
+- grt_ifcopenshell
+- grt_product_engineering
+
+## Objective
+
+Menyediakan panduan praktis pengembangan Product Engineering berbasis IFC yang:
+
+- realistis terhadap implementasi backend saat ini
+- tetap memberi arah pengembangan lanjutan
+- memisahkan dengan jelas fitur yang sudah berjalan dan fitur roadmap
+
+## Current Implementation Scope
+
+### Modul dan Peran
+
+- grt_ifcopenshell
+  - upload/parse IFC
+  - ekstraksi entitas IFC
+  - pembentukan struktur IFC BOM awal
+- grt_product_engineering
+  - document management dan revision tracking
+  - approval workflow 2 layer
+  - activity history
+  - estimated BoM, permanent BoM, MO pipeline
+  - inventory check, draft purchase, create missing product
+  - JSON-RPC API untuk integrasi frontend
+
+### Status Model Aktual
+
+State parsing dokumen IFC:
+
+```text
+draft -> parsed | failed
+```
+
+State approval dokumen:
+
+```text
+draft -> in_validation -> waiting_production -> waiting_provisioning -> approved
+                                     \-> rejected
+```
+
+Catatan:
+
+- Status di atas adalah status backend aktual yang harus dijadikan acuan implementasi UI/workflow.
+- Status bisnis tambahan dapat ditampilkan di frontend sebagai derived status, bukan mengganti state backend.
+
+## Aligned End-to-End Workflow (Recommended)
+
+Urutan berikut diselaraskan dengan implementasi backend terbaru:
+
+```text
+Create Engineering Document
+-> Upload IFC
+-> Parse IFC (IfcOpenShell in-process di Odoo)
+-> Review hasil parse dan IFC BOM
+-> Create/Map Product bila diperlukan
+-> Generate Estimated BoM
+-> Inventory Availability Check (Estimated BoM)
+-> Create Draft Purchase untuk shortage bila perlu
+-> Approval Workflow (Production lalu Provisioning)
+-> Create Permanent BoM (hanya jika availability memenuhi)
+-> Create MO from Permanent BoM
+-> Check All MO Availability Summary
+-> Confirm All MO jika seluruh requirement tersedia
+-> Start Production (proses MRP standar)
+```
+
+Catatan penting:
+
+- Permanent BoM tidak dibuat sebelum Estimated BoM dinyatakan available.
+- MO dibuat dari Permanent BoM.
+- Tersedia dry-run pipeline untuk simulasi tanpa perubahan data.
+
+## Recommended Architecture (Aligned)
+
+Arsitektur saat ini:
+
+```text
+Vue.js 3D Viewer
+        |
+        v
+     Odoo 19 (JSON-RPC API)
+        |
+        v
+grt_ifcopenshell (in-process Python library)
+        |
+        v
+ PostgreSQL
+```
+
+Catatan roadmap:
+
+- IfcOpenShell Service terpisah dapat dipertimbangkan di masa depan untuk kebutuhan scaling khusus.
+- Saat ini implementasi berjalan in-process di Odoo, bukan service terpisah.
+
+## Key Principles
+
+1. IFC tidak langsung menjadi BoM resmi.
+2. Semua revisi dokumen harus tersimpan dan dapat diaudit.
+3. Approval wajib sebelum pembentukan Permanent BoM dan proses MO.
+4. Permanent BoM dan MO harus tertelusur ke dokumen IFC sumber.
+5. Alur inventory/procurement harus mencegah konfirmasi MO saat requirement belum terpenuhi.
+6. Fitur roadmap tidak boleh diasumsikan sebagai fitur produksi sebelum tersedia di modul.
+
+## Feature Alignment Matrix
+
+### Implemented
+
+- Upload IFC
+- Revision control dan revision history
+- IFC parsing dan IFC BOM extraction
+- Approval workflow 2 tahap
+- Estimated BoM generation
+- Inventory availability check
+- Draft purchase creation untuk shortage
+- Missing product creation dari IFC BOM line
+- Permanent BoM creation (gated by availability)
+- MO creation from permanent BoM
+- MO availability summary + confirm all if available
+- MO pipeline run + pipeline dry-run
+- Session login/logout/me API
+- Temp IFC file decode + signed URL download
+
+### Partially Implemented / Integration-Dependent
+
+- IFC 3D Viewer end-to-end UX (bergantung implementasi frontend)
+- Product mapping UX yang lebih kaya (saat ini dominan backend/API)
+
+### Roadmap
+
+- ECO Integration
+- Visual Revision Comparison
+- Clash Detection
+- Cost Simulation
+- AI Mapping Recommendation
+- AI Quantity Validation
+- AI Procurement Recommendation
+- Quality domain model khusus dan QC workflow khusus Product Engineering
+
+## API Capability Snapshot (High Level)
+
+- Session: login, logout, me
+- Document: list, create, revise, parse
+- Approval: request-validation, submit, approve-production, approve-provisioning, reject, back-draft
+- Activity: add, list
+- BoM: generate, get, create-permanent-if-available
+- Inventory: check, create-draft-purchase, create-product
+- MO: create-from-permanent-bom, check-all-availability, confirm-all-if-available, run-pipeline, pipeline-dry-run
+- Temp IFC: temp-file request dan signed download
+
+Lihat detail endpoint teknis pada dokumen backend API guide.
+
+## Revision Policy for This Blueprint
+
+Setiap perubahan signifikan pada backend harus diikuti pembaruan blueprint ini, minimal pada:
+
+- status model dan alur state
+- urutan workflow inti
+- matriks fitur implemented vs roadmap
+- catatan arsitektur aktual
+
+Dengan pendekatan ini, dokumen tetap menjadi panduan rekomendasi yang berguna, namun tetap konsisten dengan implementasi terbaik yang sedang berjalan.
@@ -0,0 +1,100 @@
+# Product Engineering API Docs Index
+
+Dokumentasi ini menjadi pintu masuk utama untuk tim backend dan frontend yang mengintegrasikan Odoo 19 Product Engineering dengan IFC Viewer.
+
+## Dokumen Utama
+
+1. Backend technical developer guide:
+[BACKEND_TECHNICAL_GUIDE.md](BACKEND_TECHNICAL_GUIDE.md)
+
+2. Frontend technical developer guide:
+[FRONTEND_TECHNICAL_GUIDE.md](FRONTEND_TECHNICAL_GUIDE.md)
+
+3. API quick reference (cheat sheet):
+[API_QUICK_REFERENCE.md](API_QUICK_REFERENCE.md)
+
+## Peta Endpoint
+
+### Session
+
+- Primary login authentication: /api/session/login
+- Standard Odoo login fallback: /web/session/authenticate
+- /api/session/login
+- /api/session/logout
+- /api/session/me
+
+### Document IFC
+
+- /api/ifc/documents/list
+- /api/ifc/documents/create
+- /api/ifc/documents/revise
+- /api/ifc/documents/parse
+
+### 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
+
+### Activity
+
+- /api/ifc/documents/activities/add
+- /api/ifc/documents/activities/list
+
+### BoM
+
+- /api/ifc/documents/bom/generate
+- /api/ifc/documents/bom/get
+- /api/ifc/documents/bom/create-permanent-if-available
+
+### Inventory and Procurement
+
+- /api/ifc/documents/inventory/check
+- /api/ifc/documents/inventory/create-draft-purchase
+- /api/ifc/documents/inventory/create-product
+
+### 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
+
+### Temp IFC File
+
+- /api/ifc/documents/temp-file
+- /api/ifc/temp/<file_key>
+
+## Alur Integrasi Cepat
+
+1. Login sesi dengan endpoint session login.
+2. Buat dokumen IFC dengan documents create.
+3. Parse file IFC dengan documents parse.
+4. Jika perlu, lakukan revisi dengan documents revise.
+5. Jalankan approval bertahap sesuai role.
+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.
+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 Keamanan Penting
+
+- Semua endpoint bisnis membutuhkan session user aktif.
+- Temp file IFC hanya diakses melalui signed URL ber-expiry.
+- Signed URL terikat ke document id dan user id.
+- Frontend harus re-request temp-file jika URL expired.
+
+## Rekomendasi Operasional
+
+- Gunakan HTTPS di semua environment.
+- Tambahkan monitoring error per endpoint.
+- Audit role akses manager produksi dan provisioning secara periodik.
+- Uji dokumen IFC ukuran besar saat UAT.