# MASTER BLUEPRINT ENTERPRISE SYSTEM ## Volume 5 — API Contract and Next.js Application Structure ### Django + Next.js for Multi-Module Enterprise Platform **Versi:** 1.0 **Posisi dokumen:** lanjutan dari Volume 1, 2, 3, dan 4 **Tujuan utama:** menerjemahkan blueprint domain, workflow, authorization, dan backend design menjadi kontrak API yang konsisten serta struktur aplikasi Next.js yang maintainable, permission-aware, dan siap tumbuh. --- ## Tujuan Volume 5 Setelah: - Volume 1 menetapkan fondasi arsitektur - Volume 2 menetapkan workflow - Volume 3 menetapkan kontrol hak akses - Volume 4 menetapkan desain backend dan ERD maka Volume 5 menjawab: - endpoint apa saja yang perlu ada? - bentuk request dan response seperti apa? - error contract seperti apa? - halaman, route, dan modul Next.js seperti apa? - bagaimana frontend mengelola menu, guard, dan page action? - bagaimana page list/detail/form/workflow sebaiknya disusun? - bagaimana frontend memanfaatkan permission summary? - bagaimana menjaga agar aplikasi tetap konsisten saat modul bertambah? Dokumen ini adalah jembatan antara: - backend design - pengalaman pengguna - kontrak integrasi antar tim backend dan frontend # 1. Prinsip API dan Frontend ## 1.1 API Berbicara Bahasa Domain Endpoint sebaiknya tidak hanya berupa CRUD generik tanpa makna. Gunakan aksi bisnis yang jelas. Contoh yang lebih baik: - `POST /purchase-requests/` - `POST /purchase-requests/{id}/submit/` - `POST /purchase-requests/{id}/approve/` daripada memaksa semua transisi terjadi hanya lewat `PATCH status`. ## 1.2 Frontend Mengikuti Domain Folder dan page frontend sebaiknya mengikuti domain: - purchasing - sales - inventory - finance - governance - master-data bukan sekadar: - forms - tables - page1 - page2 ## 1.3 Backend adalah Final Authority Frontend boleh: - menyembunyikan tombol - memberi petunjuk - memfilter UI - memvalidasi form dasar Tetapi backend tetap memutuskan: - apakah action boleh dilakukan - apakah context valid - apakah transisi status sah - apakah side effect boleh terjadi ## 1.4 Kontrak Harus Konsisten Konsisten pada: - envelope response - format error - pagination - sorting/filtering - field summary vs field detail - date/time format - identifier dan document number # 2. Gaya API yang Direkomendasikan ## 2.1 RESTful dengan Action Endpoints Untuk sistem ini, pola yang paling sehat adalah: - resource endpoint untuk create/read/update/list - action endpoint untuk workflow transition Contoh: - `GET /api/purchase-requests/` - `POST /api/purchase-requests/` - `GET /api/purchase-requests/{id}/` - `PATCH /api/purchase-requests/{id}/` - `POST /api/purchase-requests/{id}/submit/` - `POST /api/purchase-requests/{id}/approve/` - `POST /api/purchase-requests/{id}/reject/` - `POST /api/purchase-requests/{id}/cancel/` ## 2.2 Kenapa Bukan CRUD Murni? Karena aksi seperti: - submit - approve - reject - issue - receive - post - reverse adalah aksi bisnis, bukan sekadar update field. ## 2.3 Versioning Gunakan versioning sejak awal, minimal: - `/api/v1/...` Agar nanti perubahan besar tidak menghancurkan semua client. ## 2.4 Naming Convention Endpoint - gunakan plural noun untuk resource - gunakan lowercase kebab-case bila perlu - action endpoint juga gunakan kata kerja bisnis yang eksplisit Contoh: - `/sales-orders/{id}/confirm/` - `/journal-entries/{id}/post/` - `/goods-receipts/{id}/post/` ## 2.5 Pagination dan Filtering Semua endpoint list utama sebaiknya mendukung: - page / page_size atau limit/offset - sorting - keyword search bila relevan - status filter - date range filter - context filter sesuai permission dan kebutuhan UI # 3. Response Contract yang Direkomendasikan ## 3.1 Response Sukses — Detail Contoh: ```json { "data": { "id": "123", "request_no": "PR-2026-00001", "status": "DRAFT", "company": { "id": "1", "code": "1000", "name": "PT Example" } }, "meta": { "timestamp": "2026-04-10T10:00:00Z" } } ``` ## 3.2 Response Sukses — List ```json { "data": [ { "id": "123", "request_no": "PR-2026-00001", "status": "SUBMITTED", "total_amount": "1000000.00" } ], "meta": { "page": 1, "page_size": 20, "total": 125 } } ``` ## 3.3 Response Error ```json { "error": { "code": "PERMISSION_DENIED", "message": "User is not allowed to approve this purchase request.", "details": { "object": "PURCHASE_REQUEST", "action": "APPROVE" } }, "meta": { "timestamp": "2026-04-10T10:00:00Z" } } ``` ## 3.4 Validation Error ```json { "error": { "code": "VALIDATION_ERROR", "message": "Validation failed.", "details": { "lines[0].quantity": ["Must be greater than zero."] } } } ``` ## 3.5 Catatan - error message harus cukup jelas untuk UI - code error harus stabil agar frontend bisa bereaksi secara konsisten # 4. Error Catalogue yang Direkomendasikan ## 4.1 Error Teknis Umum - `BAD_REQUEST` - `UNAUTHORIZED` - `PERMISSION_DENIED` - `NOT_FOUND` - `CONFLICT` - `INTERNAL_SERVER_ERROR` ## 4.2 Error Bisnis Umum - `INVALID_STATUS_TRANSITION` - `APPROVAL_RULE_NOT_FOUND` - `PERIOD_CLOSED` - `INSUFFICIENT_STOCK` - `SOURCE_DOCUMENT_INVALID` - `DUPLICATE_DOCUMENT` - `DOCUMENT_ALREADY_POSTED` - `DOCUMENT_ALREADY_CANCELLED` - `ROLE_CONFLICT_DETECTED` ## 4.3 Kenapa Katalog Error Penting? Karena frontend butuh membedakan: - apakah harus menampilkan toast sederhana - apakah harus highlight field - apakah harus redirect - apakah harus refresh data - apakah user harus meminta akses lain # 5. API Catalogue — Identity, Session, and Permission Summary ## 5.1 Authentication / Session Contoh endpoint: - `POST /api/v1/auth/login/` - `POST /api/v1/auth/logout/` - `POST /api/v1/auth/refresh/` - `GET /api/v1/me/` ## 5.2 Profile and Permission Summary Endpoint penting: - `GET /api/v1/me/profile/` - `GET /api/v1/me/permissions/` - `GET /api/v1/me/modules/` - `GET /api/v1/me/navigation/` ## 5.3 Contoh `GET /me/permissions` Response ringkas: ```json { "data": { "roles": ["PURCHASE_REQUESTER", "PURCHASING_STAFF"], "modules": { "governance": false, "master_data": true, "purchasing": true, "sales": false, "inventory": false, "expense": false, "finance": false }, "permissions": { "PURCHASE_REQUEST": ["CREATE", "READ", "LIST", "UPDATE", "SUBMIT"], "PURCHASE_ORDER": ["CREATE", "READ", "LIST", "UPDATE", "SUBMIT"] }, "contexts": { "company_code": ["1000"], "business_unit_code": ["BU01"] } } } ``` ## 5.4 Kenapa Endpoint Ini Penting? Karena frontend membutuhkan satu sumber ringkas untuk: - menu visibility - page guard - action visibility - default filter context # 6. API Catalogue — Governance ## 6.1 Role Management - `GET /api/v1/governance/roles/` - `POST /api/v1/governance/roles/` - `GET /api/v1/governance/roles/{id}/` - `PATCH /api/v1/governance/roles/{id}/` - `POST /api/v1/governance/roles/{id}/activate/` - `POST /api/v1/governance/roles/{id}/deactivate/` ## 6.2 Role Permission Management - `GET /api/v1/governance/roles/{id}/permissions/` - `POST /api/v1/governance/roles/{id}/permissions/` - `DELETE /api/v1/governance/roles/{id}/permissions/{permission_id}/` ## 6.3 Role Context Rule Management - `GET /api/v1/governance/roles/{id}/context-rules/` - `POST /api/v1/governance/roles/{id}/context-rules/` - `PATCH /api/v1/governance/context-rules/{id}/` - `POST /api/v1/governance/context-rules/{id}/deactivate/` ## 6.4 User Role Assignment - `GET /api/v1/governance/role-assignments/` - `POST /api/v1/governance/role-assignments/` - `GET /api/v1/governance/role-assignments/{id}/` - `PATCH /api/v1/governance/role-assignments/{id}/` - `POST /api/v1/governance/role-assignments/{id}/deactivate/` ## 6.5 Approval Rule - `GET /api/v1/governance/approval-rules/` - `POST /api/v1/governance/approval-rules/` - `GET /api/v1/governance/approval-rules/{id}/` - `PATCH /api/v1/governance/approval-rules/{id}/` - `POST /api/v1/governance/approval-rules/{id}/activate/` - `POST /api/v1/governance/approval-rules/{id}/deactivate/` ## 6.6 Audit Log - `GET /api/v1/governance/audit-logs/` - `GET /api/v1/governance/audit-logs/{id}/` - `POST /api/v1/governance/audit-logs/export/` # 7. API Catalogue — Master Data ## 7.1 Company / Business Unit / Warehouse / Department Contoh pola: - `GET /api/v1/master-data/companies/` - `GET /api/v1/master-data/business-units/` - `GET /api/v1/master-data/warehouses/` - `GET /api/v1/master-data/departments/` Beberapa object tertentu bisa dibatasi create/update hanya untuk role tertentu: - `POST /api/v1/master-data/business-units/` - `PATCH /api/v1/master-data/business-units/{id}/` ## 7.2 Vendor - `GET /api/v1/master-data/vendors/` - `POST /api/v1/master-data/vendors/` - `GET /api/v1/master-data/vendors/{id}/` - `PATCH /api/v1/master-data/vendors/{id}/` - `POST /api/v1/master-data/vendors/{id}/activate/` - `POST /api/v1/master-data/vendors/{id}/deactivate/` ## 7.3 Customer - `GET /api/v1/master-data/customers/` - `POST /api/v1/master-data/customers/` - `GET /api/v1/master-data/customers/{id}/` - `PATCH /api/v1/master-data/customers/{id}/` - `POST /api/v1/master-data/customers/{id}/activate/` - `POST /api/v1/master-data/customers/{id}/deactivate/` ## 7.4 Item - `GET /api/v1/master-data/items/` - `POST /api/v1/master-data/items/` - `GET /api/v1/master-data/items/{id}/` - `PATCH /api/v1/master-data/items/{id}/` - `POST /api/v1/master-data/items/{id}/activate/` - `POST /api/v1/master-data/items/{id}/deactivate/` ## 7.5 Reference Lookup Frontend biasanya butuh endpoint lookup ringan: - `GET /api/v1/lookups/vendors/?q=...` - `GET /api/v1/lookups/customers/?q=...` - `GET /api/v1/lookups/items/?q=...` - `GET /api/v1/lookups/warehouses/?q=...` # 8. API Catalogue — Purchasing ## 8.1 Purchase Request - `GET /api/v1/purchasing/purchase-requests/` - `POST /api/v1/purchasing/purchase-requests/` - `GET /api/v1/purchasing/purchase-requests/{id}/` - `PATCH /api/v1/purchasing/purchase-requests/{id}/` - `POST /api/v1/purchasing/purchase-requests/{id}/submit/` - `POST /api/v1/purchasing/purchase-requests/{id}/approve/` - `POST /api/v1/purchasing/purchase-requests/{id}/reject/` - `POST /api/v1/purchasing/purchase-requests/{id}/cancel/` - `POST /api/v1/purchasing/purchase-requests/{id}/close/` ## 8.2 Purchase Order - `GET /api/v1/purchasing/purchase-orders/` - `POST /api/v1/purchasing/purchase-orders/` - `POST /api/v1/purchasing/purchase-orders/from-request/` - `GET /api/v1/purchasing/purchase-orders/{id}/` - `PATCH /api/v1/purchasing/purchase-orders/{id}/` - `POST /api/v1/purchasing/purchase-orders/{id}/submit/` - `POST /api/v1/purchasing/purchase-orders/{id}/approve/` - `POST /api/v1/purchasing/purchase-orders/{id}/reject/` - `POST /api/v1/purchasing/purchase-orders/{id}/issue/` - `POST /api/v1/purchasing/purchase-orders/{id}/cancel/` - `POST /api/v1/purchasing/purchase-orders/{id}/close/` ## 8.3 Response Summary vs Detail ### List response Gunakan field ringkas: - id - document no - requester/vendor - status - total_amount - company/business unit - created_at ### Detail response Tambahkan: - lines - attachments - history / timeline ringan - linked documents summary # 9. API Catalogue — Sales ## 9.1 Sales Order - `GET /api/v1/sales/sales-orders/` - `POST /api/v1/sales/sales-orders/` - `GET /api/v1/sales/sales-orders/{id}/` - `PATCH /api/v1/sales/sales-orders/{id}/` - `POST /api/v1/sales/sales-orders/{id}/submit/` - `POST /api/v1/sales/sales-orders/{id}/confirm/` - `POST /api/v1/sales/sales-orders/{id}/approve/` - `POST /api/v1/sales/sales-orders/{id}/reject/` - `POST /api/v1/sales/sales-orders/{id}/cancel/` - `POST /api/v1/sales/sales-orders/{id}/close/` ## 9.2 Pricing Override - `POST /api/v1/sales/sales-orders/{id}/request-pricing-override/` - `POST /api/v1/sales/pricing-overrides/{id}/approve/` - `POST /api/v1/sales/pricing-overrides/{id}/reject/` ## 9.3 Delivery - `GET /api/v1/sales/deliveries/` - `POST /api/v1/sales/deliveries/` - `GET /api/v1/sales/deliveries/{id}/` - `PATCH /api/v1/sales/deliveries/{id}/` - `POST /api/v1/sales/deliveries/{id}/ship/` - `POST /api/v1/sales/deliveries/{id}/cancel/` # 10. API Catalogue — Inventory ## 10.1 Goods Receipt - `GET /api/v1/inventory/goods-receipts/` - `POST /api/v1/inventory/goods-receipts/` - `GET /api/v1/inventory/goods-receipts/{id}/` - `PATCH /api/v1/inventory/goods-receipts/{id}/` - `POST /api/v1/inventory/goods-receipts/{id}/post/` - `POST /api/v1/inventory/goods-receipts/{id}/cancel/` ## 10.2 Goods Issue - `GET /api/v1/inventory/goods-issues/` - `POST /api/v1/inventory/goods-issues/` - `GET /api/v1/inventory/goods-issues/{id}/` - `PATCH /api/v1/inventory/goods-issues/{id}/` - `POST /api/v1/inventory/goods-issues/{id}/post/` - `POST /api/v1/inventory/goods-issues/{id}/cancel/` ## 10.3 Stock Transfer - `GET /api/v1/inventory/stock-transfers/` - `POST /api/v1/inventory/stock-transfers/` - `GET /api/v1/inventory/stock-transfers/{id}/` - `PATCH /api/v1/inventory/stock-transfers/{id}/` - `POST /api/v1/inventory/stock-transfers/{id}/approve/` - `POST /api/v1/inventory/stock-transfers/{id}/ship/` - `POST /api/v1/inventory/stock-transfers/{id}/receive/` - `POST /api/v1/inventory/stock-transfers/{id}/cancel/` ## 10.4 Stock Adjustment - `GET /api/v1/inventory/stock-adjustments/` - `POST /api/v1/inventory/stock-adjustments/` - `GET /api/v1/inventory/stock-adjustments/{id}/` - `PATCH /api/v1/inventory/stock-adjustments/{id}/` - `POST /api/v1/inventory/stock-adjustments/{id}/submit/` - `POST /api/v1/inventory/stock-adjustments/{id}/approve/` - `POST /api/v1/inventory/stock-adjustments/{id}/post/` - `POST /api/v1/inventory/stock-adjustments/{id}/cancel/` ## 10.5 Stock Visibility - `GET /api/v1/inventory/stock-balances/` - `GET /api/v1/inventory/stock-movements/` - `GET /api/v1/inventory/stock-reservations/` # 11. API Catalogue — Expense and Costing ## 11.1 Expense Request - `GET /api/v1/expense/expense-requests/` - `POST /api/v1/expense/expense-requests/` - `GET /api/v1/expense/expense-requests/{id}/` - `PATCH /api/v1/expense/expense-requests/{id}/` - `POST /api/v1/expense/expense-requests/{id}/submit/` - `POST /api/v1/expense/expense-requests/{id}/approve/` - `POST /api/v1/expense/expense-requests/{id}/reject/` - `POST /api/v1/expense/expense-requests/{id}/cancel/` - `POST /api/v1/expense/expense-requests/{id}/post/` ## 11.2 Cost Allocation Rule - `GET /api/v1/expense/cost-allocation-rules/` - `POST /api/v1/expense/cost-allocation-rules/` - `GET /api/v1/expense/cost-allocation-rules/{id}/` - `PATCH /api/v1/expense/cost-allocation-rules/{id}/` - `POST /api/v1/expense/cost-allocation-rules/{id}/activate/` - `POST /api/v1/expense/cost-allocation-rules/{id}/deactivate/` # 12. API Catalogue — Finance ## 12.1 Journal Entry - `GET /api/v1/finance/journal-entries/` - `POST /api/v1/finance/journal-entries/` - `GET /api/v1/finance/journal-entries/{id}/` - `PATCH /api/v1/finance/journal-entries/{id}/` - `POST /api/v1/finance/journal-entries/{id}/post/` - `POST /api/v1/finance/journal-entries/{id}/reverse/` ## 12.2 Accounts Payable - `GET /api/v1/finance/accounts-payable/` - `POST /api/v1/finance/accounts-payable/` - `GET /api/v1/finance/accounts-payable/{id}/` - `PATCH /api/v1/finance/accounts-payable/{id}/` - `POST /api/v1/finance/accounts-payable/{id}/validate/` - `POST /api/v1/finance/accounts-payable/{id}/post/` - `POST /api/v1/finance/accounts-payable/{id}/close/` ## 12.3 Accounts Receivable - `GET /api/v1/finance/accounts-receivable/` - `POST /api/v1/finance/accounts-receivable/` - `GET /api/v1/finance/accounts-receivable/{id}/` - `PATCH /api/v1/finance/accounts-receivable/{id}/` - `POST /api/v1/finance/accounts-receivable/{id}/post/` - `POST /api/v1/finance/accounts-receivable/{id}/close/` ## 12.4 Payment - `GET /api/v1/finance/payments/` - `POST /api/v1/finance/payments/` - `GET /api/v1/finance/payments/{id}/` - `PATCH /api/v1/finance/payments/{id}/` - `POST /api/v1/finance/payments/{id}/approve/` - `POST /api/v1/finance/payments/{id}/post/` - `POST /api/v1/finance/payments/{id}/reverse/` ## 12.5 Receipt - `GET /api/v1/finance/receipts/` - `POST /api/v1/finance/receipts/` - `GET /api/v1/finance/receipts/{id}/` - `PATCH /api/v1/finance/receipts/{id}/` - `POST /api/v1/finance/receipts/{id}/post/` - `POST /api/v1/finance/receipts/{id}/reverse/` ## 12.6 Fiscal Period - `GET /api/v1/finance/fiscal-periods/` - `GET /api/v1/finance/fiscal-periods/{id}/` - `POST /api/v1/finance/fiscal-periods/{id}/open/` - `POST /api/v1/finance/fiscal-periods/{id}/close/` # 13. API Payload Pattern — Representative Examples ## 13.1 Create Purchase Request ### Request ```json { "company_id": "1", "business_unit_id": "10", "request_date": "2026-04-10", "notes": "Kebutuhan pembelian operasional", "lines": [ { "item_id": "100", "description": "Printer laser", "quantity": "2", "estimated_price": "3500000.00" } ] } ``` ### Response ```json { "data": { "id": "123", "request_no": "PR-2026-00001", "status": "DRAFT", "total_amount": "7000000.00" } } ``` ## 13.2 Approve Purchase Request ### Request ```json { "notes": "Approved by purchasing supervisor" } ``` ### Response ```json { "data": { "id": "123", "request_no": "PR-2026-00001", "status": "APPROVED", "approved_at": "2026-04-10T10:00:00Z" } } ``` ## 13.3 Create Sales Order ### Request ```json { "company_id": "1", "business_unit_id": "20", "customer_id": "15", "order_date": "2026-04-10", "currency_id": "IDR", "lines": [ { "item_id": "100", "quantity": "10", "unit_price": "500000.00", "discount_amount": "0.00" } ] } ``` # 14. Next.js Architecture yang Direkomendasikan ## 14.1 App Router Gunakan Next.js App Router agar: - layout per domain lebih rapi - route nesting mudah - page-level composition lebih jelas - server/client boundary lebih fleksibel ## 14.2 Struktur Folder Tingkat Tinggi ```text src/ app/ (auth)/ login/ (protected)/ dashboard/ governance/ master-data/ purchasing/ sales/ inventory/ expense/ finance/ modules/ governance/ master-data/ purchasing/ sales/ inventory/ expense/ finance/ components/ ui/ shared/ lib/ api/ auth/ permissions/ query/ hooks/ types/ ``` ## 14.3 Prinsip Struktur - `app/` untuk routing dan layout - `modules/` untuk domain UI reusable - `components/ui` untuk komponen presentasional umum - `lib/api` untuk client API - `lib/permissions` untuk helper visibility - `types/` untuk kontrak TypeScript # 15. Route and Page Map ## 15.1 Governance - `/governance/roles` - `/governance/roles/[id]` - `/governance/role-assignments` - `/governance/approval-rules` - `/governance/audit-logs` ## 15.2 Master Data - `/master-data/vendors` - `/master-data/vendors/new` - `/master-data/vendors/[id]` - `/master-data/customers` - `/master-data/items` - `/master-data/warehouses` ## 15.3 Purchasing - `/purchasing/purchase-requests` - `/purchasing/purchase-requests/new` - `/purchasing/purchase-requests/[id]` - `/purchasing/purchase-orders` - `/purchasing/purchase-orders/new` - `/purchasing/purchase-orders/[id]` ## 15.4 Sales - `/sales/sales-orders` - `/sales/sales-orders/new` - `/sales/sales-orders/[id]` - `/sales/deliveries` - `/sales/deliveries/[id]` ## 15.5 Inventory - `/inventory/goods-receipts` - `/inventory/goods-receipts/new` - `/inventory/goods-receipts/[id]` - `/inventory/goods-issues` - `/inventory/stock-balances` - `/inventory/stock-adjustments` ## 15.6 Expense - `/expense/requests` - `/expense/requests/new` - `/expense/requests/[id]` - `/expense/cost-allocation-rules` ## 15.7 Finance - `/finance/journal-entries` - `/finance/journal-entries/new` - `/finance/journal-entries/[id]` - `/finance/accounts-payable` - `/finance/accounts-receivable` - `/finance/payments` - `/finance/receipts` - `/finance/fiscal-periods` # 16. Page Pattern yang Direkomendasikan ## 16.1 List Page Komponen standar list page: - page title - filter bar - quick action button - table/grid - pagination - empty state - export action jika diizinkan ## 16.2 Detail Page Komponen standar detail page: - summary header - status badge - action bar - tabs / sections: - general info - lines/items - linked documents - history/timeline - attachments ## 16.3 Form Page Komponen standar form: - header - context selector - general fields - line editor/table - totals section - validation summary - save draft / submit action ## 16.4 Workflow Action Modal Untuk aksi seperti: - approve - reject - cancel - post - reverse gunakan modal/confirmation panel dengan: - summary singkat dokumen - input notes/reason bila perlu - warning bila tindakan irreversible secara bisnis # 17. Permission-aware Navigation and Guard ## 17.1 Navigation Source Navigation sebaiknya dibangun dari: - static config per modul - dipadukan dengan permission summary dari backend Contoh: ```ts { key: "purchasing.purchase_requests", label: "Purchase Requests", path: "/purchasing/purchase-requests", requiredObject: "PURCHASE_REQUEST", requiredAction: "LIST" } ``` ## 17.2 Route Guard Halaman sensitif dapat memakai server-side atau client-side guard berbasis permission summary. Tetapi: - guard UI hanya untuk UX - API tetap menentukan final authority ## 17.3 Action Guard Di halaman detail, tombol seperti: - submit - approve - reject - issue - post - reverse ditampilkan berdasarkan: - permission summary - status dokumen - kadang informasi tambahan dari backend response # 18. Frontend State Strategy ## 18.1 Prinsip Umum Jangan buat state management terlalu berat tanpa alasan. Gunakan kombinasi: - server state via query library - local form state - session/auth state - minimal shared UI state ## 18.2 Rekomendasi Gunakan: - React Query / TanStack Query untuk server data - form library seperti React Hook Form - zod/yup untuk validation schema di UI bila perlu - auth/session layer terpusat ## 18.3 Kenapa Ini Cocok? Karena sistem ini: - sangat data-driven - banyak list/detail/form - banyak mutation workflow - butuh cache invalidation yang terkontrol # 19. Query and Mutation Pattern ## 19.1 Query Keys Buat query key konsisten per domain: Contoh: - `["purchase-requests", filters]` - `["purchase-request", id]` - `["purchase-orders", filters]` - `["vendors", filters]` ## 19.2 Mutation Pattern Setiap action bisnis dibuat sebagai mutation terpisah: - createPurchaseRequest - updatePurchaseRequest - submitPurchaseRequest - approvePurchaseRequest - rejectPurchaseRequest ## 19.3 Setelah Mutation Lakukan: - invalidate list query terkait - refetch detail bila perlu - tampilkan toast - redirect bila pola UX mengharuskan # 20. TypeScript Contract Strategy ## 20.1 Pisahkan Tipe Summary dan Detail Contoh: - `PurchaseRequestSummary` - `PurchaseRequestDetail` - `PurchaseRequestCreatePayload` - `PurchaseRequestUpdatePayload` ## 20.2 Pisahkan Tipe Form dan API Bila Perlu Kadang bentuk form UI tidak sama persis dengan payload API. Jangan dipaksa sama jika itu membuat code jelek. ## 20.3 Error Type Buat type error API yang stabil: ```ts type ApiError = { error: { code: string; message: string; details?: Record; }; }; ``` # 21. Form Design Strategy ## 21.1 Draft-first Forms Untuk banyak dokumen operasional, UX yang sehat adalah: - user bisa save draft - user bisa submit setelah lengkap ## 21.2 Line Editor Untuk dokumen seperti PR, PO, SO: - gunakan line table editor yang stabil - hindari terlalu banyak nested uncontrolled state - hitung subtotal/total secara jelas ## 21.3 Lookup Components Butuh reusable lookup: - vendor lookup - customer lookup - item lookup - warehouse lookup - company/business unit selector ## 21.4 Validation Layer Frontend validasi: - required fields - format - angka > 0 - line minimal 1 Backend validasi: - authorization - status transition - context - business rule final # 22. UX Notes untuk Workflow-heavy Pages ## 22.1 Status Visibility Selalu tampilkan status jelas di: - list row - detail header - timeline/history ## 22.2 Linked Documents User perlu melihat relasi dokumen: - PR → PO - PO → Goods Receipt - SO → Delivery - Expense → Journal/AP - AR/AP → Payment/Receipt ## 22.3 Timeline Timeline/history sangat membantu: - siapa create - siapa submit - siapa approve/reject - kapan post/reverse terjadi ## 22.4 Warning State Untuk action sensitif: - post - reverse - cancel - close UI harus memberi warning, tapi tidak menggantikan validasi backend. # 23. Representative Frontend Module Structure ## 23.1 Purchasing Module Example ```text modules/ purchasing/ api/ purchaseRequests.ts purchaseOrders.ts components/ PurchaseRequestForm.tsx PurchaseRequestListTable.tsx PurchaseRequestDetailHeader.tsx PurchaseRequestActions.tsx PurchaseOrderForm.tsx hooks/ usePurchaseRequestFilters.ts usePurchaseRequestMutations.ts types/ purchaseRequest.ts purchaseOrder.ts ``` ## 23.2 Governance Module Example ```text modules/ governance/ api/ roles.ts approvalRules.ts auditLogs.ts components/ RoleForm.tsx RolePermissionMatrix.tsx ApprovalRuleForm.tsx AuditLogTable.tsx ``` ## 23.3 Finance Module Example ```text modules/ finance/ api/ journalEntries.ts accountsPayable.ts payments.ts components/ JournalEntryForm.tsx JournalEntryActions.tsx AccountsPayableTable.tsx PaymentForm.tsx ``` # 24. API-to-Page Mapping Example ## 24.1 Purchase Request List Page Halaman: `/purchasing/purchase-requests` Memakai: - `GET /api/v1/purchasing/purchase-requests/` - `GET /api/v1/me/permissions/` Aksi UI: - filter - pagination - buka detail - create baru jika punya `CREATE` ## 24.2 Purchase Request Detail Page Halaman: `/purchasing/purchase-requests/[id]` Memakai: - `GET /api/v1/purchasing/purchase-requests/{id}/` Aksi UI berdasarkan permission dan status: - update draft - submit - approve - reject - cancel ## 24.3 Vendor List Page Halaman: `/master-data/vendors` Memakai: - `GET /api/v1/master-data/vendors/` Aksi: - create vendor - edit vendor - activate/deactivate # 25. Backend-Frontend Contract Checklist Gunakan checklist ini sebelum modul dianggap siap diintegrasikan. ## 25.1 Endpoint - Apakah list endpoint sudah mendukung filter utama? - Apakah detail endpoint cukup lengkap? - Apakah action endpoint sudah eksplisit? ## 25.2 Response - Apakah response list dan detail konsisten? - Apakah error format konsisten? - Apakah pagination meta konsisten? ## 25.3 Permission - Apakah `/me/permissions` cukup untuk menu/action guard? - Apakah backend tetap menolak action yang tidak sah? - Apakah hidden action di UI bukan satu-satunya kontrol? ## 25.4 Form - Apakah payload create/update stabil? - Apakah lookup endpoint tersedia? - Apakah validation error mudah ditampilkan di form? ## 25.5 UX - Apakah status selalu jelas? - Apakah linked documents tersedia? - Apakah timeline/history tersedia untuk dokumen penting? # 26. Testing Implications for API and Frontend ## 26.1 API Testing Perlu diuji: - list filter - detail retrieval - create/update payload validation - action endpoint status transition - permission denied response - context restriction ## 26.2 Frontend Testing Perlu diuji: - route guard - menu visibility - button/action visibility - form validation dasar - success/error handling - cache invalidation setelah mutation ## 26.3 End-to-End Flow Contoh e2e yang sangat penting: - create PR → submit → approve - create PO → approve → issue - SO → confirm → delivery - expense → approve → post - journal → post → reverse # 27. Kesimpulan Volume 5 Volume 5 menghubungkan seluruh blueprint backend ke aplikasi web yang benar-benar dipakai user. Dokumen ini menetapkan: - gaya API - kontrak response/error - katalog endpoint utama per modul - payload pattern - struktur aplikasi Next.js - route/page map - permission-aware navigation - state/query/mutation strategy - form/list/detail/workflow pattern - checklist integrasi backend-frontend Dengan Volume 1 sampai Volume 5, tim kini memiliki: - fondasi arsitektur - blueprint domain dan workflow - kontrol akses - desain backend - kontrak aplikasi web dan API Ini sudah cukup kuat untuk masuk ke: - penyusunan OpenAPI/Swagger - implementasi DRF endpoint - implementasi page/layout/component frontend - penyusunan test plan integrasi --- ## Langkah Lanjutan yang Direkomendasikan Dokumen berikut yang paling natural adalah: ### Volume 6 — Testing, Deployment, Operating Model, and Scale Strategy Isi utamanya: - testing strategy lengkap - UAT pack - migration/release checklist - environment strategy - logging/monitoring - performance and scaling notes - backup/restore and operational readiness - roadmap hardening ke production Volume 6 akan melengkapi blueprint menjadi paket referensi yang jauh lebih mendekati “panduan sampai sistem hidup utuh”.